Modules Index

XML Schema Home

# XML::Schema::Type::Simple

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

## Table of Contents

Synopsis |  |  |
Description |  |  |

## Synopsis

    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 };

## Description

The XML::Schema::Type::Simple module implements a base class from which the builtin simple datatypes like string, integer, float and time (all defined in XML::Schema::Type::Builtin) are subclassed. It can also be used as a base class for creating user defined simple types.

Simple data types are used to represent single values in XML documents, appearing as attribute values or the content of simple elements.

Here's an example showing an element with attributes `id` and `price`, with corresponding values `widget99` and `19.99`. The XML Schema fragment for this element would typically define `id` as having simple type integer, and `price` as money,

    <product id="widget99" price="19.99"/>

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 `<price>` as a simple element within `<constant>`, having a content type of money.

    <product id="widget99">
      <price>19.99</price>
    </product>

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. XML::Schema::Type::money) used to represent the value(s) for both attributes and simple elements.

Simple types use validation facets which implement different aspects of validation for different types. These are used internally to specialise existing types. For example, the `positiveInteger` simple type is derived from the `integer` type by adding a facet which encodes the constraint `minInclusive => 1`.

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.

    my $type = XML::Schema::Type::positiveInteger->new();
    $type->constrain( maxInclusive => 32 );

Now, when you try to create an instance of this type via the `instance()` method, the value passed will first be validated against the internal `minInclusive => 1` facet and then against the user-defined `maxInclusive => 32` facet.

    my $item = $type->instance(14)
        || die $type->error();

The value returned from a successful call to `instance()` is a reference to a hash array which represents the infoset 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 `time` simple type returns an infoset containing values for `hour`, `minute`, `second` and so on.

The infoset hash has a `text` item to indicate the original input text. This is copied to the `value` 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.

If all facets validate successfully then the resultant `value` value is copied to the `result` value. If any callbacks have been scheduled for activation then these are called and may modify the `result` further.

    print $item->{ result };

In summary, the hash array returned by the `instance()` should contain at least a `text` member containing the original text, a `value` containing the possibly modified post-validation value, and `result` 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).

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.

Perl XML::Schema Documentation