Modules Index

XML Schema Home

# XML::Schema::Facet

The module implements XML Schema facets for constraining values of simple types.

## Table of Contents

Synopsis |  |  |
Description |  |  |
Methods | : | new(), init(), valid(), invalid(), name(), value(), annotation() |

## Synopsis

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

## Description

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.

## Methods

- new()

  Base class constructor method used to create a new facet object or subclass thereof. A list of '`key => value` ' 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 `error()` as a class method.

      # 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();

  The following configuration options may be specifed:

  Name | Typical Values | Description
  `value` | `$value` | 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.
  `name` | `'myfacet'` | 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. `XML::Schema::Facet::minLength` = '`minLength` '.
  `errmsg` | `'failed to match my criteria'` | An optional error message to report when an instance of a simple type constrained by this facet fails to meet the required criteria.
  `annotation` | `'...something interesting...` | An optional annotation. Feel free to add something useful or just your favourite quote from Homer Simpson.

- init( \%config )
  Initialisation method called by `new()` passing a reference to a hash array of configuration arguments. May be redefined by subclasses to perform more specific per-object initialisation.

- valid( $instance, $type )

  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 `value` 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.

  The second argument passed is a reference to the simple type object which is instantiating this value.

  Subclassed facets are expected to redefine this method to perform their own validation.

- invalid( $msg )
  This method can be called to indicate a validation failure and to generate an appropriate error message based on the custom `errmsg` value or a constructed message based on the `$msg` argument passed and the facet's name and value (e.g. `"error message (required minLength: 10)"` ).

- name()
  Returns the name of the facet as (optionally) supplied by the `name` configuration item.

- value()
  Returns the facet value as supplied by the `value` configuration item.

- annotation()
  Returns the annotation value as supplied by the `annotation` configuration item.

Perl XML::Schema Documentation