<!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 => 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 };</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><product id="widget99" price="19.99"/></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><price></code> as a simple element within
<code><constant></code>, having a content type of
<a href="../../../../modules/XML/Schema/Type/Builtin.html#money">money</a>.
<ul><pre><product id="widget99">
<price>19.99</price>
</product></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->new();
$type->constrain( maxInclusive => 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->instance(14)
|| die $type->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->{ 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>