<module name="XML::Schema::Type::Simple">

  <about>
    The XML::Schema::Type::Simple module is a base class for objects that 
    represent XML Schema simple types.
  </about>

  <synopsis>
<perl>
package XML::Schema::Type::whatever;
use XML::Schema::Type::Builtin;
use base qw( XML::Schema::Type::Simple );
use vars qw( @FACETS );

@FACETS = (
    minLength  => 10,
    maxLength  => 30,
    otherFacet => { 
        value  => $n, 
        fixed  => 1, 
        annotation => "a comment",
    }, 
);

package main;

my $type = XML::Schema::Type::whatever->new()
    || die XML::Schema::Type::whatever->error();

my $item = $type->instance('some instance value')
    || die $type->error();

print $item->{ result };
</perl>
  </synopsis>

  <description>
    <p>
    The XML::Schema::Type::Simple module implements a base class from
    which the builtin simple datatypes like 
    <module class="XML::Schema::Type::Builtin" anchor="string">string</module>,
    <module class="XML::Schema::Type::Builtin" anchor="integer">integer</module>,
    <module class="XML::Schema::Type::Builtin" anchor="float">float</module> and
    <module class="XML::Schema::Type::Builtin" anchor="time">time</module>
    (all defined in <module>XML::Schema::Type::Builtin</module>) are subclassed.
    It can also be used as a base class for creating user defined simple types.
    </p>
    <p>
    Simple data types are used to represent single values in XML
    documents, appearing as attribute values or the content of
    simple elements.
    </p>

    <p>
    Here's an example showing an element with attributes
    <code>id</code> and <code>price</code>, with corresponding
    values <code>widget99</code> and <code>19.99</code>.  The
    XML Schema fragment for this element would typically 
    define <code>id</code> as having simple type 
    <module class="XML::Schema::Type::Builtin" anchor="integer">integer</module>,
    and <code>price</code> as 
    <module class="XML::Schema::Type::Builtin" anchor="money">money</module>,
  
<xblock>
<product id="widget99" price="19.99"/>
</xblock>
    </p>


    <p>
    Simple types are also be used to represent to content 
    of simple elements.  These are elements that have no attributes or
    nested elements.  The previous example could instead have defined
    <code>&lt;price&gt;</code> as a simple element within
    <code>&lt;constant&gt;</code>, having a content type of 
    <module class="XML::Schema::Type::Builtin" anchor="money">money</module>.
<xblock>
<product id="widget99">
  <price>19.99</price>
</product>
</xblock>
    </p>

    <p>
    The schema used to represent these different examples is
    different, as is the resulting data set generated by parsing these
    examples.  However, in both cases, it is a simple type object
    (e.g. <module class="XML::Schema::Type::Builtin"
    anchor="money">XML::Schema::Type::money</module>) used to
    represent the value(s) for both attributes and simple elements.
    </p>

    <p>
    Simple types use validation <module
    class="XML::Schema::Facet">facets</module> which implement
    different aspects of validation for different types.  These are
    used internally to specialise existing types.  For example, the
    <code>positiveInteger</code> simple type is derived from the
    <code>integer</code> type by adding a facet which encodes the
    constraint <code>minInclusive => 1</code>.
    </p>

    <p>
    Facets can subsequently be applied to simple types to create 
    user defined specialised types.  To constrain a number to an
    integer value between 1 and 32, you might do the following.
<perl>
my $type = XML::Schema::Type::positiveInteger->new();
$type->constrain( maxInclusive => 32 );
</perl>
     </p>
     <p>
     Now, when you try to create an instance of this type via the
     <method>instance()</method> method, the value passed will first
     be validated against the internal <code>minInclusive => 1</code>
     facet and then against the user-defined <code>maxInclusive =>
     32</code> facet.
    </p>
<perl>
my $item = $type->instance(14)
    || die $type->error();
</perl>
    <p>
    The value returned from a successful call to
    <method>instance()</method> is a reference to a hash array which
    represents the <i>infoset</i> generated by creating an instance of
    the type for a particular input value.  Although a simple type
    starts off as a simple string, it may get broken down into all
    manner of different components.  For example, the
    <code>time</code> simple type returns an infoset containing values
    for <code>hour</code>, <code>minute</code>, <code>second</code>
    and so on.
    </p>

    <p>
    The infoset hash has a <code>text</code> item to indicate the
    original input text.  This is copied to the <code>value</code>
    item which validation facets then use as a working copy to modify
    and manipulate as necessary.  Facets may also make any number of
    other contributions to the infoset depending on their and the 
    underlying data types.  
    </p>

    <p>
    If all facets validate successfully then the resultant
    <code>value</code> value is copied to the <code>result</code>
    value.  If any callbacks have been scheduled for activation
    then these are called and may modify the <code>result</code>
    further.
<perl>
print $item->{ result };
</perl>
    </p>

    <p>
    In summary, the hash array returned by the
    <method>instance()</method> should contain at least a
    <code>text</code> member containing the original text, a
    <code>value</code> containing the possibly modified
    post-validation value, and <code>result</code> containing the
    post-activation result which may be some alternate representation
    of the validated text (e.g. text converted to an object reference
    by a user-defined scheduled action).
    </p>

    <p>
    This might all seem rather cumbersome, but it's generally not
    something you have to worry about.  The higher level components
    generally take care of the nitty gritty detail for you.
    </p>

  </description>
</module>