Manual Reference Pages - XML::PASTOR::SIMPLETYPE (3)
XML::Pastor::SimpleType - Ancestor of all simple classes generated by XML::Pastor and also the builtin simple classes.
This class descends from XML::Pastor::Type.
<B>XML::Pastor::SimpleTypeB> is an <B>abstractB> 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.
<B>XML::Pastor::SimpleTypeB> defines some overloads (stringification, numification, boolification) and method overrides
<B>XML::Pastor::SimpleTypeB> 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 <B>XML::Pastor::ComplexTypeB> 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.
Several overloads are performed so that a <B>XML::Pastor::SimpleTypeB> object looks like a regular scalar. Basically, they all use the value field as the scalar.
This is done with the <B>stringifyB> (overridable) method. The returned value is the stringification of the contents of the value field.
This is done with the <B>numifyB> (overridable) method. The returned value is the numification of the contents of the value field.
This is done with the <B>boolifyB> (overridable) method. The returned value is the boolification of the contents of the value field. This method is
indeed overriden by the <B>XML::Pastor::Builtin::booleanB> class in order to count the string false as a false value.
<B>CONSTRUCTORB> overriden from XML::Pastor::Type.
The new() constructor method instantiates a new <B>XML::Pastor::SimpleTypeB> object. It is inheritable, and indeed inherited,
by the generated decsendant classes. Normally, you do not call the <B>newB> method on <B>XML::Pastor::SimpleTypeB>. 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.
my $object = $class->from_xml_dom($node);
<B>CONSTRUCTORB> that should be called upon your generated class rather than <B>XML::Pastor::ComplexTypeB>.
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
my $type = $class->XmlSchemaType()
<B>CLASS METHODB>, but may also be called directly on an <B>OBJECTB>.
<B>XML::Pastor::SimpleTypeB> defines (thanks to Class::Data::Inheritable)
a class data acessor <B>XmlSchemaTypeB> which returns <B>undefB>.
This data accessor is set by each generated simple class to the meta information coming from your <B>W3C SchemaB>.
This data is of class XML::Pastor::Schema::SimpleType.
You dont really need to know much about <B>XmlSchemaTypeB>. Its used internally by Pastors XML binding and validation
methods as meta information about the generated class.
$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.
$bool = $object->is_xml_valid();
<B>OBJECT METHODB>, inherited from XML::Pastor::Type. Documented here for completeness.
<B>is_xml_validB> is similar to xml_validate except that it will not <B>dieB> on failure.
Instead, it will just return FALSE \fIs0(0).
The implementation of this method, inherited from XML::Pastor::Type, is very simple. Currently,
it just calls xml_validate in an <B>evalB> block and will return FALSE \fIs0(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.
$object->xml_validate(); # Will die on failure
<B>B><B>OBJECT METHODB>, overriden from XML::Pastor::Type.
<B>xml_validateB> validates a Pastor XML object (of a generated class) with respect to the META information that
had originally be extracted from your original <B>W3C XSD SchemaB>.
On sucess, <B>xml_validateB> returns TRUE \fIs0(1). On failure, it will <B>dieB> 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 <B>CastorB> for example.
The following properties of XML Simple Type declarations in the W3C schema are observed:
These properties are obtained from the schema type object returned from the XmlSchemaType class data accessor call.
The string length of the value.
The minimum and maximum string lengths for the value.
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.
A hash of enumeration values.
Minimum and maximum inclusive values.
Minimum and maximum exclusive values.
The total and fraction digits (in a floating point number) respectively.
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, <B>xml_validateB> calls xml_validate_further to perform
extra checks. For <B>XML::Pastor::SimpleTypeB> 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 <B>xml_validateB> 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 <B>xml_validateB> which will consequently die.
$object->xml_validate_further(); # Never called directly.
<B>OBJECT METHODB>, overriden from XML::Pastor::Type.
<B>xml_validate_furtherB> 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 <B>XML::Pastor::SimpleTypeB>, 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 doesnt mean there are arent 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.
Ayhan Ulusoy <dev(at)ulusoy(dot)name>
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 XML::Pastor::Type, XML::Pastor::ComplexType, XML::Pastor
And if you are curious about the implementation, see Class::Accessor, Class::Data::Inheritable
|perl v5.20.3 ||XML::PASTOR::SIMPLETYPE (3) ||2012-12-01 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.