<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>Modules Index</title>
</head>

<body bgcolor="#ffffff">
<table border="0" width="100%">
<tr>
<td align="left"><a href="../../../../index.html"><img src="../../../../images/canon.gif" border="0"></a></td>
<td align="right"><img src="../../../../images/canre.gif"></td>
</tr>
</table>
<div align="right">
<small><a href="../../../../index.html">XML Schema Home</a></small>
</div>

<h1>XML::Schema::Type::Simple</h1>

<ul>

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

<h2>Table of Contents</h2>
<ul>
<table border="0" cellpadding="2" cellspacing="0">
<tr valign="top">
<td>
  <li><b><a href="#section_Synopsis">Synopsis</a></b>
</td>

<td>
</td>

<td>
<td>

</tr>
<tr valign="top">
<td>
  <li><b><a href="#section_Description">Description</a></b>
</td>

<td>
</td>

<td>
<td>

</tr>
</table>
</ul>




<hr width="100%" size="1" noshade="1"><a name="section_Synopsis"><h2>Synopsis</h2></a>
<ul><pre><p>package XML::Schema::Type::whatever;
use XML::Schema::Type::Builtin;
use base qw( XML::Schema::Type::Simple );
use vars qw( @FACETS );

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

package main;

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

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

print $item-&gt;{ result };</b></pre></ul>

  
<hr width="100%" size="1" noshade="1"><a name="section_Description"><h2>Description</h2></a>
    <p>
    The XML::Schema::Type::Simple module implements a base class from
    which the builtin simple datatypes like 
    <a href="../../../../modules/XML/Schema/Type/Builtin.html#string">string</a>,
    <a href="../../../../modules/XML/Schema/Type/Builtin.html#integer">integer</a>,
    <a href="../../../../modules/XML/Schema/Type/Builtin.html#float">float</a> and
    <a href="../../../../modules/XML/Schema/Type/Builtin.html#time">time</a>
    (all defined in <a href="../../../../modules/XML/Schema/Type/Builtin.html">XML::Schema::Type::Builtin</a>) 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 
    <a href="../../../../modules/XML/Schema/Type/Builtin.html#integer">integer</a>,
    and <code>price</code> as 
    <a href="../../../../modules/XML/Schema/Type/Builtin.html#money">money</a>,
  
<ul><pre>&lt;product id=&quot;widget99&quot; price=&quot;19.99&quot;/&gt;</pre></ul>
    </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></code> as a simple element within
    <code>&lt;constant></code>, having a content type of 
    <a href="../../../../modules/XML/Schema/Type/Builtin.html#money">money</a>.
<ul><pre>&lt;product id=&quot;widget99&quot;&gt;
  &lt;price&gt;19.99&lt;/price&gt;
&lt;/product&gt;</pre></ul>
    </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. <a href="../../../../modules/XML/Schema/Type/Builtin.html#money">XML::Schema::Type::money</a>) used to
    represent the value(s) for both attributes and simple elements.
    </p>


    <p>
    Simple types use validation <a href="../../../../modules/XML/Schema/Facet.html">facets</a> 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.
<ul><pre><p>my $type = XML::Schema::Type::positiveInteger-&gt;new();
$type-&gt;constrain( maxInclusive =&gt; 32 );</b></pre></ul>

     </p>

     <p>
     Now, when you try to create an instance of this type via the
     <a href="#method_instance"><code><b>instance()</b></code></a> 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>

<ul><pre><p>my $item = $type-&gt;instance(14)
    || die $type-&gt;error();</b></pre></ul>

    <p>
    The value returned from a successful call to
    <a href="#method_instance"><code><b>instance()</b></code></a> 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.
<ul><pre><p>print $item-&gt;{ result };</b></pre></ul>

    </p>


    <p>
    In summary, the hash array returned by the
    <a href="#method_instance"><code><b>instance()</b></code></a> 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>


  



<div align="center">
<small><b>Perl XML::Schema Documentation</b></small>
</div>
</body>
</html>