XML::Pastor::Schema::Object - Ancestor of all Pastor schema object classes.
This module is used internally by XML::Pastor. You do not normally know much about this module to actually use XML::Pastor. It is documented here for completeness and for XML::Pastor developers. Do not count on the interface of this module. It may change in any of the subsequent releases. You have been warned.
This class descends from Class::Accessor.
my $object = XML::Pastor::Schema::Object->new(); $object->setFields(name => 'country', scope=> 'global', nameIsAutoGenerated=>0); $object->type('Country'); print $object->name(); # prints 'country'. print $object->scope(); # prints 'global'. print $object->type(); # prints 'Country'.
XML::Pastor::Schema::Object is an abstract ancestor of all XML::Pastor schema object classes. Schema object classes are those that are the construction blocks of a schema model (see XML::Pastor::Schema::Model). They also constitute the objects that contain the meta information about a W3C schema that are embedded as class data within the generated Perl classes by XML::Pastor.
Some examples of schema object classes include:
$class->new(%fields)
CONSTRUCTOR.
The new() constructor method instantiates a new object. It is inheritable. Normally, one does not call the new method on XML::Pastor::Schema::Object. One rather calls it on the descendant subclasses.
Any -named- fields that are passed as parameters are initialized to those values within the newly created object.
.
my $class = $object->class(); # GET $object->class($class); # SET
This is the Perl class that corresponds to the schema object. It is computed at schema model resolution time. (see "resolve()" in XML::Pastor::Schema::Model).
This accessor is originally created by a call to mk_accessors from Class::Accessor. However, it is further overridden in the source code in order to take into consideration the definition of the object. The SET functionality works as usual, but the GET functionality works as follows: If a value is NOT already defined for this field, but if there is a definition of this object, then the value of the same field is returned from the definition of the object. (See "definition()").
my $definition = $object->definition(); # GET $object->definition($definition); # SET
This field corresponds to the perl reference (ref) to a resolved W3C reference to a global object. It is normally used for elements and attributes. This way, the local element definition is preserved while having a pointer to the actual global definition.
This field is set during the schema model resolution time (see "resolve()" in XML::Pastor::Schema::Model).
This accessor is created by a call to mk_accessors from Class::Accessor.
my $key = $object->key(); # GET $object->key($key); # SET
Returns the hash key that is to be use to hash this object within the model. This is used by the add() method of the schema model (see "add()" in XML::Pastor::Schema::Model). If no key has been previously set, it returns the name of the object.
This accessor is coded manually.
my $id = $object->id(); # GET $object->id($id); # SET
This is a W3C property.
A schema object can have an ID within the W3C schema. Currently, this property is not used by XML::Pastor.
my $bool = $object->isRedefinable(); # GET $object->isRedefinable($bool); # SET
Normally, when an object is not marked as 'redefinable', it is an error to attempt to define it again within the schema model. (see "add()" in XML::Pastor::Schema::Model).
When processing a schema within a 'redefine' block, all schema objects (including types and elements) are marked as redefinable. This way, any subsequent redefinition in the model does not cause an error.
my $name = $object->name(); # GET $object->name($name); # SET
This field is the name of the schema object as defined within the W3C schema or as attributed by the parser. Normally, all global objects (type, element, group, attribute, attributeGroup) will have a named defined in the W3C schema. However, non-global objects (such as local elements) will not have a name that comes from the W3C schema. Such objects will be named by the parser.
my $bool = $object->nameIsAutoGenerated(); # GET $object->nameIsAutoGenerated($bool); # SET
Normally, all global objects (type, element, group, attribute, attributeGroup) will have a named defined in the W3C schema. However, non-global objects (such as local elements) will not have a name that comes from the W3C schema. Such objects will be named by the parser. In this case (when the name is generated automatically), this field will be set to TRUE(1) by the parser on the corresponding sceham object.
my $ref = $object->ref(); # GET $object->ref($ref); # SET
Sometimes in a W3C schema, a local object (such as an element) makes a reference to a global object (such as a global element). In this case, the 'ref' field will contain the name of the referenced global object.
The value of this field comes directly from the W3C schema, and is put into this field by the schema parser.
my $scope = $object->scope(); # GET $object->scope($scope); # SET
All schema objects are defined within a scope. The scope can be 'global' or 'local'. The scope of schema objects are determined by the schema parser and this field is set accordingly at parse time.
my $type = $object->type(); # GET $object->type($type); # SET
Sometimes in a W3C schema, an object (such as an attribute or an element) will refer to a type that is defined globally in the schema set. The value of this field comes directly from the W3C schema, and is put into this field by the schema parser.
$object->setFields(%fields);
OBJECT METHOD.
This method is used to set multiple fields of a schema object all at once. From an interface point of view, it is like the new() method, but instead of constructing a new object, it works on an existing object.
Example :
$object->setFields( name=> country, scope=>global );
This is used heavily by the parser in order to set multiple fields that are obtained by parsing attributes from the schema nodes.
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.
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, XML::Pastor::ComplexType, XML::Pastor::SimpleType
If you are curious about the implementation, see XML::Pastor::Schema::Parser, XML::Pastor::Schema::Model, XML::Pastor::Generator.
If you really want to dig in, see XML::Pastor::Schema::Attribute, XML::Pastor::Schema::AttributeGroup, XML::Pastor::Schema::ComplexType, XML::Pastor::Schema::Element, XML::Pastor::Schema::Group, XML::Pastor::Schema::List, XML::Pastor::Schema::SimpleType, XML::Pastor::Schema::Type, XML::Pastor::Schema::Object
To install XML::Pastor, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::Pastor
CPAN shell
perl -MCPAN -e shell install XML::Pastor
For more information on module installation, please visit the detailed CPAN module installation guide.