NAME
XML::Compile - Compilation based XML processing
SYNOPSIS
# See XML::Compile::SchemaDESCRIPTION
Many professional applications which process data-centric XML do that based on a formal specification, expressed as XML Schema. XML::Compile reads and writes XML data with the help of such schema's. On the Perl side, the module uses a tree of nested hashes with the same structure.
Where other Perl modules, like SOAP::WSDL help you using these schema's (often with a lot of run-time [XPath] searches), this module takes a different approach: in stead of run-time processing of the specification, it will first compile the expected structure into real Perl, and then use that to process the data.
There are many perl modules with the same intention as this one: translate between XML and nested hashes. However, there are a few serious differences: because the schema is used here (and not in the other modules), we can validate the data. XML requires validation. Next to this, data-types are formatted and processed correctly. for instance, the specification prescribes that the integer data-type must accept huge values of at least 18 digits. Also more complex data-types like list, union, and substitutionGroup (unions on complex type level) are supported, which is rarely the case in other modules.
In general two WARNINGS:
- .
-
The compiler is implemented in XML::Compile::Schema::Translate, which is not finished. See that manual page about the specific behavior and its (current) limitations! Please help to find missing pieces and mistakes.
- .
-
The provided schema is not validated! In some cases, compile-time and run-time errors will be reported, but typically only in cases that the parser has no idea what to do with such a mistake. On the other hand, the processed data is validated: the output will follow the specs closely.
METHODS
Constructors
These constructors are base class methods to be extended, and therefore should not be accessed directly.
$obj->new(TOP, OPTIONS)
The TOP is a XML::LibXML::Document (a direct result from parsing activities) or a XML::LibXML::Node (a sub-tree). It may also be a text which represents one or more schema's, as long as it is one node.
If you have compiled/collected all the information you need, you may simply terminate the compiler object: that will clean-up (most of) the XML::LibXML objects.
Option --Defined in--Default
schema_dirs undef. schema_dirs DIRECTORY|ARRAY-OF-DIRECTORIES
Where to find schema's. This can be specified with the environment variable SCHEMA_DIRECTORIES or with this option. See addSchemaDirs() for a detailed explanation.
Accessors
$obj->addSchemaDirs(DIRECTORIES)
Each time this method is called, the specified DIRECTORIES will be added in front of the list of already known schema directories. Initially, the value of the environment variable SCHEMA_DIRECTORIES is added (therefore used last), then the constructor option schema_dirs is processed.
Values which are undef are skipped. ARRAYs are flattened. Arguments are split on colons (only when on UNIX) after flattening.
$obj->findSchemaFile(FILENAME)
Runs through all defined schema directories (see addSchemaDirs()) in search of the specified FILENAME. When the FILENAME is absolute, that will be used, and no search will take place. An undef is returned when the file is not found or not readible, otherwise a full path to the file is returned to the caller.
$obj->top
Returns the XML::LibXML object tree which needs to be compiled.
Filters
$obj->walkTree(NODE, CODE)
Walks the whole tree from NODE downwards, calling the CODE reference for each NODE found. When that routine returns false, the child nodes will be skipped.
REFERENCES
See the XML::Compile website at http://perl.overmeer.net/xml-compile/ for more details.
COPYRIGHTS
Module version 0.10. Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for other contributors.
Copyright (c) 2006 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.