Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  XML::PASTOR::COMPLEXTYPE (3)

.ds Aq ’


XML::Pastor::ComplexType - Ancestor of all complex classes generated by XML::Pastor



This class descends from XML::Pastor::Type. All your generated complex classes descend from this class.


First, you need to generate your classes using XML::Pastor. See the documentation of XML::Pastor for more examples of this. XML::Pastor will then generate classes corresponding to the global elements and type definitions (complex and simple) in your W3C schema.

  use XML::Pastor;
  my $pastor = XML::Pastor->new();

  # Generate MULTIPLE modules, one module for each class, and put them under destination. 
                        mode =>offline,
                        style => multiple,

And somewhere in an other place of the code ... (Assuming a global XML element ’country’ existed in you schema and hence been generated by Pastor).

  my $country = MyApp::Data::country->from_xml_file(/some/path/to/country.xml);    # retrieve from a file   
  $country = MyApp::Data::country->from_xml_url(http://some/url/to/country.xml);       # or from a URL
  $country = MyApp::Data::country->from_xml_fh($fh);    # or from a file handle 
  $country = MyApp::Data::country->from_xml_dom($dom);  # or from DOM  (a XML::LibXML::Node or XML::LibXML::Document)

  # or from an XML string
  $country = MyApp::Data::country->from_xml_string(<<EOF);
  <?xml version="1.0"?>
  <country code="FR" name="France">
    <city code="PAR" name="Paris"/>
    <city code="LYO" name="Lyon"/>   
  # or if you dont know if you have a file, URL, FH, or string
  $country = MyApp::Data::country->from_xml(http://some/url/to/country.xml);
  # Now you can manipulate your country object. 
  print $country->name;                                 # prints "France"
  print $country->city->[0]->name;              # prints "Paris"
  # Lets make some changes 
  my $class=$country->xml_field_class(city);
  my $city = $class->new();
  push @{$country->city}, $city;
  print $country->city->[2]->name;      # prints "Marseille"
  # Time to validate our XML
  $country->xml_validate();                     # This one will DIE on failure
  if ($country->is_xml_valid()) {       # This one will not die.
    print "ok\n";
  }else {
    print "Validation error : $@\n";  # Note that $@ contains the error message
  # Time to write the the object back to XML
  $country->to_xml_file(some/path/to/country.xml);            # To a file 
  $country->to_xml_url(http://some/url/to/country.xml);       # To a URL 
  $country->to_xml_fh($fh);                                     # To a FILE HANDLE 

  my $dom=$country->to_xml_dom();                       # To a DOM Node (XML::LibXML::Node)
  my $dom=$country->to_xml_dom_document();      # To a DOM Document  (XML::LibXML::Document)
  my $xml=$country->to_xml_string();            # To a string 
  my $frag=$country->to_xml_fragment();         # Same thing without the <?xml version="1.0?> part


<B>XML::Pastor::ComplexTypeB> is an <B>abstractB> ancestor of all complex classes (including those corresponding to global elements) 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::ComplexTypeB> defines several methods that serve mainly to achieve the XML binding of generated classes that inherit from it. Yet, this class remains abstract because it is void of meta information related to the W3C schema that is defined for each generated class.

In fact, <B>XML::Pastor::ComplexTypeB> 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.

The generated classes also automatically define accessor methods for the attributes and child elements of the complex type (or element) at hand. (See ACCESSORS for more information).

Notice that you can set any other field in the object that can be used as a hash key. It doesn’t have to be a valid XML attribute or child element. You may then access the same field using the usual hash access. You can use this feature to save state information that will not be written back to XML. Just make sure that the names of any such fields do not coincide with the name of an actual attribute or child element. Any such field will be silently ignored when writing to or validating XML. However, note that there won’t be any auto-generated accessor for such fields. But you can actually achieve this by using the <B>mk_accessorsB> method from Class::Accessor somewhere else in your code as <B>XML::ComplexTypeB> eventually inherits from Class::Accessor.

Generated classes for simple types do not descend from this class. Instead, they descend from XML::Pastor::SimpleType (although both have a common ancestor called XML::Pastor::Type).



<B>WARNING 1B> : Normally, you never call the methods defined by <B>XML::Pastor::ComplexTypeB> on this class itself. Instead, you call them on your descendant generated classes which inherit all these methods.

<B>WARNING 2B> : You should not use the names of these methods for the attributes and child elements within your W3C schemas. If you do, the behavior is undefined! You have been warned! If you follow the naming conventions given by XML::Pastor, you should be OK in any case. See SUGGESTED NAMING CONVENTIONS FOR XML TYPES, ELEMENTS AND ATTRIBUTES IN W3C SCHEMAS in XML::Pastor for more info.



<B>XML::Pastor::ComplexTypeB> does not define accessors on itself, but the generated classes that correspond to complex types and global elements will have accessors defined for their <B>attributesB> and <B>child elementsB>. This is done via Class::Accessor.

The accessors will be in the usual Perl form, meaning the name of the accessor will be the same of the <B>attributeB> or <B>child elementB>. When called without any arguments, the accessor serves as a GETTER, and when called with a single argument it serves as a SETTER.

For attributes and <B>singletonB> child elements with simple content, the accesors (GET) will return an object of a class that descends eventually from XML::Pastor::SimpleType. This may be a builtin class defined by XML::Pastor::Builtin or a generated class that derives from one if you have defined the type in your <B>W3C schemaB>. When setting a value of an attribute or a child element with simple content, you can either use an object of that same class or otherwise you can just use a SCALAR or a completely different object that stringifies to the desired value. But be warned that the accessor does not change your SCALAR or object into an object of correct class. <B>XML::PastorB> is just clever enough to convert those into the desired class on the fly upon validation or storage.

A child element that is a <B>singletonB> (i.e., the <B>maxOccursB> schema property is undefined or ’1’), its accessor will return an object of a class that eventually descends from <B>XML::Pastor::ComplexTypeB>. This will typically be a generated class that derives from your <B>W3C schemaB>. When setting the value of such a child element, you should use an object of that same class (or one that derives from it). In fact, currently, you may also use a plain hash but this is an experimental feature so don’t count on it to work.

For a child element that is <B>notB> a <B>singletonB> (i.e. the <B>maxOccursB> schema property is greater than ’1’ or is ’<B>unboundedB>’), the accessor will return a XML::Pastor::NodeArray object (which is just a blessed array with some overloading functionality) that will contain one item for each child element with the same name in the order that they appear in the XML. Each item will be an object of a class that descends eventually from <B>XML::Pastor::ComplexTypeB> or XML::Pastor::SimpleType depending on whether the element has simple or complex content. When setting the value of such a child element with <B>multiplicityB>, you will have great freedom. The preffered way is to use a XML::Pastor::NodeArray object just as it is returned by the accessor (GETTER). But you don’t have to. You can use a plain array instead. Currently, you can even use a single object (without an array) if you know that you will only put one element in there. But this is not such a good way of doing things. Besides, this feature is experimental so it may go away in the future. So try to stick with at least a plain array and you should be fine. The items in the array can even be plain scalars if the child element has simple content (see above for the attribute case).





  $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.



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::Type, XML::Pastor::SimpleType, XML::Pastor

And if you are more curious, see XML::Pastor::Type (the ancestor of this class), XML::Pastor::Schema::ComplexType (meta type information from your <B>W3C schemaB>)

And if you are even more curious, see Class::Accessor, Class::Data::Inheritable

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 XML::PASTOR::COMPLEXTYPE (3) 2008-08-02

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.