NAME
XML::Pastor::Schema::Model - Class representing an internal W3C schema model (info set) for XML::Pastor.
WARNING
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.
ISA
This class descends from Class::Accessor.
SYNOPSIS
my $model = XML::Pastor::Schema::Model->new();
$model->add(object->$object1);
$model->add(object->$object2);
$model->add(object->$object3);
$model->resolve();DESCRIPTION
XML::Pastor::Schema::Model is used internally by XML::Pastor for representinng the parsed information set of a group of W3C schemas.
A model is produced typically by parsing with the "parse()" in XML::Pastor::Schema::Parser method. However, it is theoratically possible to produce it by other means.
A model contains information about all the type, element, attribute, group, and attribute group definitions that come from the set of schemas that constitute the source of the model. This includes all global and implicit types and elements.
Once produced, you can't do much with a model except resolve it. Resolving the model means things such as resolving all references (such as those pointing to global elements or groups) and computing the Perl class names that correspond to each generated class. See "resolve()" for more details.
Once resolved, the model is then ready to be used for code generation.
METHODS
CONSTRUCTORS
new()
XML::Pastor::Schema::Model->new(%fields)CONSTRUCTOR.
The new() constructor method instantiates a new object. It is inheritable.
Any -named- fields that are passed as parameters are initialized to those values within the newly created object.
The new() method will create the type, element, attribute, group, and attributeGroup fields if it is not passed values for those fields.
.
ACCESSORS
type()
A hash of all (global and implicit) type definitions (simple or complex) that are obtained from the processed W3C schemas. The hash key is the name of the type and the value is an object of type XML::Pastor::Schema::SimpleType or XML::Pastor::Schema::ComplexType, depending on whether this is a simple or complex type.
A straight forward consequence is that simple and complex types cannot have name collisions among each other. This conforms with the W3C specifications.
Note that this hash is obtained from a merge of all the information coming from the various W3C schemas. So it represents information coming from all the concerned schemas.
Note that each item of this hash later becomes a generated class under the "Type" subtree when code generation is performed
element()
A hash of all global elements obtained from the W3C schemas. The hash key is the name of the global element and the value is an object of type XML::Pastor::Schema::Element.
Note that this hash is obtained from a merge of all the information coming from the various W3C schemas. So it represents information coming from all the concerned schemas.
Note that each item of this hash later becomes a generated class when code generation is performed.
attribute()
A hash of all global attributes obtained from the W3C schemas. The hash key is the name of the global attribute and the value is an object of type XML::Pastor::Schema::Attribute.
Note that this hash is obtained from a merge of all the information coming from the various W3C schemas. So it represents information coming from all the concerned schemas.
Note that no code generation is perfomed for the items in this hash. They are used internally by the "type" hash once the referenes to them are resolved.
group()
A hash of all global groups obtained from the W3C schemas. The hash key is the name of the global group and the value is an object of type XML::Pastor::Schema::Group.
Note that this hash is obtained from a merge of all the information coming from the various W3C schemas. So it represents information coming from all the concerned schemas.
Note that no code generation is perfomed for the items in this hash. They are used internally by the "type" hash once the referenes to them are resolved.
attributeGroup()
A hash of all global attribute groups obtained from the W3C schemas. The hash key is the name of the global attribute group and the value is an object of type XML::Pastor::Schema::AttributeGroup.
Note that this hash is obtained from a merge of all the information coming from the various W3C schemas. So it represents information coming from all the concerned schemas.
Note that no code generation is perfomed for the items in this hash. They are used internally by the "type" hash once the referenes to them are resolved.
.
OTHER METHODS
add()
$model->add(object=>$object);Add a schema object to the model (to the corresponding hash). Aliases of 'object' are 'item' and 'node'. So the following are equivalent to the above:
$model->add(item=>$object);
$model->add(node=>$object);In the above, the actual hash where the object will be placed is deduced from the type of the object. Possible types are descendents of:
- XML::Pastor::Schema::Type (where XML::Pastor::Schema::SimpleType and XML::Pastor::Schema::ComplexType descend.)
- XML::Pastor::Schema::Element
- XML::Pastor::Schema::Group
- XML::Pastor::Schema::Attribute
- XML::Pastor::Schema::AttributeGroup
One can also pass the name of the hash that one would like the object to be added. Examples:
$model->add(type=>$object);
$model->add(element=>$object);
$model->add(group=>$object);
$model->add(attribute=>$object);
$model->add(attributeGroup=>$object);In this case, the type of the object is not taken into consideration.
Normally, when a schema object is already defined within the model, it is an error to attempt to add it again to the model. This means that the object is defined twice in the W3C schema. However, this rule is relaxed when the object within the sceham is marked as redefinable (see "isRedefinable()" in XML::Pastor::Schema::Object). This is typically the case when we are in a redefine block (when a schema is included wit the redefine tag).
xml_item($name, [$nsUri])
Returns the Schema Model item for a given name, and optionally, a namespace URI. If namespace URI is omitted, then the default namespace URI for the model is used.
This method does a search on the different hashes kept by the model (element, type, group, attribute, attributeGroup) in that order, and will return the first encountred item.
xml_item_class($name, [$nsUri])
Returns the class name of a Schema Model item for a given name, and optionally, a namespace URI. If namespace URI is omitted, then the default namespace URI for the model is used.
This is in fact a shortcut for: $model->xml_item($name)->class();
resolve()
$model->resolve(%options);OBJECT METHOD.
This method will resolve the model. In other words, thhis method will prepare the produced model to be processed for code gerenartion.
Resolving a model means: resolving references to global objects (elements and attributes); replacing group and attributeGroup references with actual contents of the referenced group; computing the Perl class names of the types and elements to be generated; and figuring out the inheritance relationships between classes.
The builtin classes are known to the method so that the Perl classes for them will not be generated but rather referenced from the XML::Pastor::Builtin module.
OPTIONS
- class_prefix
-
If present, the names of the generated classes will be prefixed by this value. You may end the value with '::' or not, it's up to you. It will be autocompleted. In other words both 'MyApp::Data' and 'MyApp::Data::' are valid.
- complex_isa
-
Via this parameter, it is possible to indicate a common ancestor (or ancestors) of all complex types that are generated by XML::Pastor. The generated complex types will still have XML::Pastor::ComplexType as their last ancestor in their @ISA, but they will also have the class whose name is given by this parameter as their first ancestor. Handy if you would like to add common behaviour to all your generated classes.
This parameter can have a string value (the usual case) or an array reference to strings. In the array case, each item is added to the @ISA array (in that order) of the generated classes.
- simple_isa
-
Via this parameter, it is possible to indicate a common ancestor (or ancestors) of all simple types that are generated by XML::Pastor. The generated simple types will still have XML::Pastor::SimpleType as their last ancestor in their @ISA, but they will also have the class whose name is given by this parameter as their first ancestor. Handy if you would like to add common behaviour to all your generated classes.
This parameter can have a string value (the usual case) or an array reference to strings. In the array case, each item is added to the @ISA array (in that order) of the generated classes.
.
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, XML::Pastor::ComplexType, XML::Pastor::SimpleType
If you are curious about the implementation, see XML::Pastor::Schema::Parser, 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