NAME

XML::Pastor::SimpleType - Ancestor of all simple classes generated by XML::Pastor and also the builtin simple classes.

ISA

This class descends from XML::Pastor::Type.

DESCRIPTION

XML::Pastor::SimpleType is an abstract ancestor of all simple classes (those global and implicit Simple Type definitions in the schema, including builtin ones) generated by XML::Pastor which is a Perl code generator from W3C XSD schemas. For an introduction, please refer to the documentation of XML::Pastor.

XML::Pastor::SimpleType defines some overloads (stringification, numification, boolification) and method overrides from XML::Pastor::Type.

XML::Pastor::SimpleType contains (actually inherits from XML::Pastor::Type) a class data accessor called "XmlSchemaType()" with the help of Class::Data::Inheritable. This accessor is normally used by many other methods to access the W3C schema meta information related to the class at hand. But at this stage, "XmlSchemaType()" does not contain any information and this is why XML::Pastor::ComplexType remains abstract.

The generated subclasses set "XmlSchemaType()" to information specific to the W3C schema type. It is then used for the XML binding and validation methods.

OVERLOADS

Several overloads are performed so that a XML::Pastor::SimpleType object looks like a regular scalar. Basically, they all use the 'value' field as the scalar.

stringification

This is done with the stringify (overridable) method. The returned value is the stringification of the contents of the 'value' field.

numification

This is done with the numify (overridable) method. The returned value is the numification of the contents of the 'value' field.

boolification

This is done with the boolify (overridable) method. The returned value is the boolification of the contents of the 'value' field. This method is indeed overriden by the XML::Pastor::Builtin::boolean class in order to count the string 'false' as a false value.

METHODS

CONSTRUCTORS

new()

  $class->new($value)
  $class->new(%fields)

CONSTRUCTOR overriden from XML::Pastor::Type.

The new() constructor method instantiates a new XML::Pastor::SimpleType object. It is inheritable, and indeed inherited, by the generated decsendant classes. Normally, you do not call the new method on XML::Pastor::SimpleType. You rather call it on your generated subclasses.

Any -named- fields that are passed as parameters are initialized to those values within the newly created object. The only field that makes any sense at this time is the 'value' field. This is why it has been made easier to pass value as the one and only parameter.

The following two calls are equivalent:

  my $object = $class->new($value);
  my $object = $class->new(value => $value);

Stick with the first one, as the second one requires the knowledge of the internal organization of the object.

from_xml_dom()

        my $object = $class->from_xml_dom($node);
        

CONSTRUCTOR that should be called upon your generated class rather than XML::Pastor::ComplexType.

This method instatiates an object of the generated class from a DOM object passed as a parameter. Currently, the DOM object must be either of type XML::LibXML::Attr, XML::LibXML::Text or of type XML::LibXML::Element (with textContent).

Currently, the method is quite forgiving as to the actual contents of the DOM. No validation is performed during this call.

.

CLASS DATA ACCESSORS

XmlSchemaType()

  my $type = $class->XmlSchemaType()

CLASS METHOD, but may also be called directly on an OBJECT.

XML::Pastor::SimpleType defines (thanks to Class::Data::Inheritable) a class data acessor XmlSchemaType which returns undef.

This data accessor is set by each generated simple class to the meta information coming from your W3C Schema. This data is of class XML::Pastor::Schema::SimpleType.

You don't really need to know much about XmlSchemaType. It's used internally by Pastor's XML binding and validation methods as meta information about the generated class.

ACCESSORS

value()

  $currentValue = $object->value();     # GET
  $object->value($newValue);            # SET

Gets and sets the value of the 'value' field, which is the actual SCALAR value of the object.

OTHER METHODS

is_xml_valid()

  $bool = $object->is_xml_valid();

OBJECT METHOD, inherited from XML::Pastor::Type. Documented here for completeness.

'is_xml_valid' is similar to "xml_validate" except that it will not die on failure. Instead, it will just return FALSE (0).

The implementation of this method, inherited from XML::Pastor::Type, is very simple. Currently, it just calls "xml_validate" in an eval block and will return FALSE (0) if "xml_validate" dies. Otherwise, it will just return the same value as "xml_validate".

In case of failure, the contents of the special variable $@ will be left untouched in case you would like to access the error message that resulted from the death of "xml_validate".

.

xml_validate()

        $object->xml_validate();        # Will die on failure

OBJECT METHOD, overriden from XML::Pastor::Type.

'xml_validate' validates a Pastor XML object (of a generated class) with respect to the META information that had originally be extracted from your original W3C XSD Schema.

On sucess, xml_validate returns TRUE (1). On failure, it will die on you on validation errors.

The W3C recommendations have been observed as closely as possible for the implementation of this method. Neverthless, it remains somewhat more relaxed and easy compared to Castor for example.

The following properties of XML Simple Type declarations in the W3C schema are observed:

length

The string length of the value.

minLength, maxLength

The minimum and maximum string lengths for the value.

pattern

One ore more W3C regex patterns that the value must match. If more than one is present, any one match is considered sufficient for validity.

regex (not present in W3C schema)

Like 'pattern', but guaranteed to be a Perl regular expression even if the W3C 'pattern' diverges from this in the future. This is used internally for builtin types. Like 'pattern', one or more regexes can be present.

enumeration

A hash of enumeration values.

minInclusive, maxInclusive

Minimum and maximum inclusive values.

minExclusive, maxExclusive

Minimum and maximum exclusive values.

totalDigits, fractionDigits

The total and fraction digits (in a floating point number) respectively.

These properties are obtained from the schema type object returned from the "XmlSchemaType" class data accessor call.

The builtin types use these properties extensively to enforce vaildity. The 'regex' property is used heavily for builtin types.

After checking the conformity with these properties, xml_validate calls "xml_validate_further" to perform extra checks. For XML::Pastor::SimpleType this always returns TRUE, but some builtin types (like XML::Pastor::Builtin::date and XML::Pastor::Builtin::dateTime) actually perform some extra validation during this call.

Then, the xml_validate method is called on any capable ancestors in the ISA array. A failure in any one of these calls will result in the failure of xml_validate which will consequently die.

xml_validate_further()

        $object->xml_validate_further();        # Never called directly.

OBJECT METHOD, overriden from XML::Pastor::Type.

'xml_validate_further' should perform extra validation on a Pastor XML object (of a generated class).

It is called by "xml_validate" after performing rutine validations.

This method should return TRUE(1) on success, and die on failure with an error message.

For XML::Pastor::SimpleType, this method simple returns TRUE(1).

This method may be overriden by subclasses and it is indeed oevrriden by several builtin classes like like XML::Pastor::Builtin::date and XML::Pastor::Builtin::dateTime.

BUGS & CAVEATS

There no known bugs at this time, but this doesn't mean there are aren't any. Note that, although some testing was done prior to releasing the module, this should still be considered alpha code. So use it at your own risk.

Note that there may be other bugs or limitations that the author is not aware of.

AUTHOR

Ayhan Ulusoy <dev(at)ulusoy(dot)name>

COPYRIGHT

  Copyright (C) 2006-2007 Ayhan Ulusoy. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

See also XML::Pastor::Type, XML::Pastor::ComplexType, XML::Pastor

And if you are curious about the implementation, see Class::Accessor, Class::Data::Inheritable