<!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::Facet</h1>
<ul>
The module implements XML Schema facets for constraining
values of 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>
<tr valign="top">
<td>
<li><b><a href="#section_Methods">Methods</a></b>
</td>
<td>
<b>:<b>
</td>
<td>
<small><a href="#method_new">new()</a>, <a href="#method_init">init()</a>, <a href="#method_valid">valid()</a>, <a href="#method_invalid">invalid()</a>, <a href="#method_name">name()</a>, <a href="#method_value">value()</a>, <a href="#method_annotation">annotation()</a></small>
<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::Facet::MyFacet;
use base qw( XML::Schema::Facet );
sub valid {
my ($self, $instance, $type) = @_;
my $value = $instance->{ value };
# ..more code here...
return $some_condition ? 1 : 0;
}
package main;
my $facet = XML::Schema::Facet::MyFacet->new(...);
my $instance = {
value => 'some data value',
};
print $facet->valid($instance) ? "valid" : "invalid";</b></pre></ul>
<hr width="100%" size="1" noshade="1"><a name="section_Description"><h2>Description</h2></a>
This modules implements a base class for objects representing XML
Schema facets. A facet is a constraint which can be applied to a
simple type to ensure that its values match some criteria,
e.g. conform to a regular expression pattern, fall within a
particular numerical range, do not exceed a particular string
length, etc.
<hr width="100%" size="1" noshade="1"><a name="section_Methods"><h2>Methods</h2></a><ul>
<li><p>
<a name="method_new"><b>new()</b></a>
<br>
<p>
Base class constructor method used to create a new facet
object or subclass thereof. A list of
'<code><b>key => value</b></code>
' pairs can be
specified as command line arguments, or alternately, a hash
reference can be passed which contains these configuration
values. The method returns a newly instantiated facet object on
success. On error it returns undef and sets an internal error
message which can be retrieved by calling <a href="../../../modules/XML/Schema/Base.html#method_error"><code><b>error()</b></code></a> as a class method.
<ul><pre><p># list of options
my $facet = XML::Schema::Facet::MyFacet->new( value => 10 )
|| die XML::Schema::Facet::MyFacet->error();
# hash ref of options
my $facet = XML::Schema::Facet::MyFacet->new( { value => 10 } )
|| die XML::Schema::Facet::MyFacet->error();</b></pre></ul>
</p>
<p>
The following configuration options may be specifed:
</p>
<p>
<!-- table -->
<table border="0" cellpadding="4" cellspacing="1"
bgcolor="#000044">
<!-- table content -->
<tr bgcolor="#ccccff">
<td><b><small>Name</b></td><td><b><small>Typical Values</b></td><td><b><small>Description</b></td></tr>
<tr valign="top" bgcolor="#eeeeff">
<td>
<a name="config_value"><code><b>value</b></code></a>
</td>
<td>
<code><b>$value</b></code>
</td>
<td>
The constraining value for the facet. This item is mandatory
as all facets require at least one configuring value. However,
subclassed facets may expect and interpet this value differently.
</td>
</tr>
<tr valign="top" bgcolor="#eeeeff">
<td>
<a name="config_name"><code><b>name</b></code></a>
</td>
<td>
<code><b>'myfacet'</b></code>
</td>
<td>
The name of the facet. This item is optional and if not
specified, will be taken as the last element of the package
name (e.g. <code><b>XML::Schema::Facet::minLength</b></code>
= '<code><b>minLength</b></code>
'.
</td>
</tr>
<tr valign="top" bgcolor="#eeeeff">
<td>
<a name="config_errmsg"><code><b>errmsg</b></code></a>
</td>
<td>
<code><b>'failed to match my criteria'</b></code>
</td>
<td>
An optional error message to report when an instance of a
simple type constrained by this facet fails to meet the
required criteria.
</td>
</tr>
<tr valign="top" bgcolor="#eeeeff">
<td>
<a name="config_annotation"><code><b>annotation</b></code></a>
</td>
<td>
<code><b>'...something interesting...</b></code>
</td>
<td>
An optional annotation. Feel free to add something useful
or just your favourite quote from Homer Simpson.
</td>
</tr>
<!-- end of table content -->
</table>
</p>
</p><li><p>
<a name="method_init"><b>init( \%config )</b></a>
<br>
Initialisation method called by <a href="#method_new"><code><b>new()</b></code></a> passing
a reference to a hash array of configuration arguments. May be
redefined by subclasses to perform more specific per-object
initialisation.
</p><li><p>
<a name="method_valid">
<b>valid( $instance, <a href="../../../modules/XML/Schema/Type/Simple.html">$type</a> )</b>
<br>
</a>
<!-- ignore args -->
<p>
This method is used to validate a potential instance of a type against
the facet. A reference to a hash array is passed as the first argument.
This contains the candidate value defined as the <code><b>value</b></code>
item and may also contain any other data contributed by other validation
facets. This can effectively be considered as a working scratchpad for
facets to share.
</p>
<p>
The second argument passed is a reference to the <a href="../../../modules/XML/Schema/Type/Simple.html">simple type object</a> which
is instantiating this value.
</p>
<p>
Subclassed facets are expected to redefine this method to perform
their own validation.
</p>
</p><li><p>
<a name="method_invalid"><b>invalid( $msg )</b></a>
<br>
This method can be called to indicate a validation failure and to
generate an appropriate error message based on the custom
<a href="#config_errmsg"><code><b>errmsg</b></code></a> value or a constructed message based on the
<code><b>$msg</b></code>
argument passed and the facet's name and
value (e.g. <code><b>"error message (required minLength: 10)"</b></code>
).
</p><li><p>
<a name="method_name"><b>name()</b></a>
<br>
Returns the name of the facet as (optionally) supplied by the
<a href="#config_name"><code><b>name</b></code></a> configuration item.
</p><li><p>
<a name="method_value"><b>value()</b></a>
<br>
Returns the facet value as supplied by the
<a href="#config_value"><code><b>value</b></code></a> configuration item.
</p><li><p>
<a name="method_annotation"><b>annotation()</b></a>
<br>
Returns the annotation value as supplied by the
<a href="#config_annotation"><code><b>annotation</b></code></a> configuration item.
</p></ul>
<div align="center">
<small><b>Perl XML::Schema Documentation</b></small>
</div>
</body>
</html>