/ 
XML-Compile-0.60
River stage two • 39 direct dependents • 66 total dependents
/ XML::Compile

NAME

XML::Compile - Compilation based XML processing

INHERITANCE

XML::Compile is extended by
  XML::Compile::Schema
  XML::Compile::WSDL11

SYNOPSIS

# See XML::Compile::Schema / ::WSDL / ::SOAP

DESCRIPTION

Many (professional) applications process XML based on a formal specification, expressed as XML Schema. XML::Compile processes XML with the help of such schemas. The Perl program only handles a tree of nested HASHes and ARRAYs.

Three serious WARNINGS:

.

The compiler only supports namespace schemas. It is possible, but generally seen as weakness, to make schemas which do not use namespaces, but for the moment, XML::Compile does not handle those. Check for a targetNamespace attribute on schema in your xsd file.

.

The focus is on data-centric XML, which means that mixed elements are not understood automatically. However, with using hooks you can work around this.

.

The provided schema is not validated. In many cases, compile-time errors will get reported. On the other hand, the processed data is strictly validated: both input and output will follow the specs closely (unless disabled).

For end-users, the following packages are of interest (the other are support packages):

XML::Compile::Schema

Interpret schema elements and types: process XML messages.

XML::Compile::WSDL and XML::Compile::SOAP

Use the SOAP protocol, client side. Requires the installation of the XML-Compile-SOAP distribition. Implementation in progress.

XML::Compile::SOAP::Daemon

Create a SOAP daemon. Requires the installation of the XML-Compile-SOAP-Daemon distribition. Implementation in progress.

METHODS

Methods found in this manual page are shared by the end-user modules, and should not be used directly: objects of type XML::Compile do not exist.

Constructors

These constructors are base class methods to be extended, and therefore should not be accessed directly.

XML::Compile->new(TOP, OPTIONS)

    The TOP is the source of XML. See dataToXML() for valid options.

    If you have compiled/collected all readers and writers you need, you may simply terminate the compiler object: that will clean-up (most of) the XML::LibXML objects.

    Option     --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)

XML::Compile->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.

    If a pm filename is provided, then the directory to be used is calculated from it (platform independent). So, lib/XML/Compile.pm becomes lib/XML/Compile/xsd/. This way, modules can simply add their definitions via XML::Compile->addSchemaDirs(__FILE__)

    Values which are undef are skipped. ARRAYs are flattened. Arguments are split on colons (only when on UNIX) after flattening. The list of directories is returned, in all but VOID context.

$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->knownNamespace(NAMESPACE|PAIRS)

XML::Compile->knownNamespace(NAMESPACE|PAIRS)

    If used with only one NAMESPACE, it returns the filename in the distribution (not the full path) which contains the definition.

    When PAIRS of NAMESPACE-FILENAME are given, then those get defined. This is typically called during the initiation of modules, like XML::Compile and XML::Compile::SOAP. The definitions are global.

Read XML

$obj->dataToXML(NODE|REF-XML-STRING|XML-STRING|FILENAME|KNOWN)

    Collect XML data. When a ready XML::LibXML NODE is provided, it is returned immediately and unchanged. A SCALAR reference is interpreted as reference to XML as plain text (XML texts can be large, and you can improve performance by passing it around by reference instead of copy). Any value which starts with blanks followed by a '<' is interpreted as XML text.

    You may also specify a pre-defined known name-space URI. A set of definition files is included in the distribution, and installed somewhere when this all gets installed. Either define an environment variable named SCHEMA_LOCATION or use new(schema_dirs) (option available to all end-user objects) to inform the library where to find these files.

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.

DETAILS

Comparison

Where other Perl modules, like SOAP::WSDL help you using these schemas (often with a lot of run-time [XPath] searches), XML::Compile takes a different approach: instead of run-time processing of the specification, it will first compile the expected structure into a pure Perl CODE reference, and then use that to process the data as often as needed.

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 by the other modules), we can validate the data. XML requires validation but quite a number of modules simply ignore that.

Next to this, data-types are formatted and processed correctly; for instance, the specification prescribes that the Integer data-type must accept values of at least 18 digits... not just Perl's idea of longs.

XML::Compile supports the more complex data-types like list, union, substitutionGroup (unions on complex type level), and even the nasty any and anyAttribute, which is rarely the case for the other modules.

DIAGNOSTICS

Error: cannot find pre-installed name-space files

    Use $ENV{SCHEMA_LOCATION} or new(schema_dirs) to express location of installed name-space files, which came with the XML::Compile distribution package.

Error: don't known how to interpret XML data

Error: no XML data specified

SEE ALSO

This module is part of XML-Compile distribution version 0.60, built on March 09, 2008. Website: http://perl.overmeer.net/xml-compile/

LICENSE

Copyrights 2006-2008 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html