XML::Compile - Compilation based XML processing
XML::Compile is extended by
# See XML::Compile::Schema / ::WSDL / ::SOAP11 etc
Many (professional) applications process XML messages based on a formal
specification, expressed in XML Schemas. XML::Compile translates between XML
and Perl with the help of such schemas. Your Perl program only handles a tree
of nested HASHes and ARRAYs, and does not need to understand namespaces and
other general XML and schema nastiness.
Three serious WARNINGS:
- The focus is on data-centric XML, which means that mixed elements
are not handler automatically: you need to work with XML::LibXML nodes
yourself, on these spots.
- The data is not strictly validated, still a large number of
compile-time errors can be reported. Values are checked quite thoroughly.
Structure as well.
- Imports and includes, as used in the schemas, are NOT performed
automatically. Schema's and such are NOT collected from internet
dynamically; you have to call
XML::Compile::Schema::importDefinitions() explicitly with filenames
of locally stored copies. Includes do only work if they have a
targetNamespace defined, which is the same as that of the schema it is
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!
These constructors are base class methods to be extended, and therefore should
not be accessed directly.
- XML::Compile->new( [$xmldata], %options )
- The $xmldata is a source of XML. See dataToXML() for valid ways,
for example as filename, string or "undef".
If you have compiled all readers and writers you need, you may simply
terminate the compiler object: that will clean-up (most of) the
- parser_options => HASH|ARRAY
- See XML::LibXML::Parser for a list of available options which can be used
to create an XML parser (the new method). The default will set you in a
secure mode. See initParser().
- 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.
- 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 tried as last resort). The constructor option
"schema_dirs" is a little more favorite.
Values which are "undef" are skipped. ARRAYs are flattened.
Arguments are split at colons (on UNIX) or semi-colons (windows) after
flattening. The list of directories is returned, in all but VOID context.
When a ".pm" package $filename is given, then the directory to be
used is calculated from it (platform independently). So,
"something/XML/Compile/xsd/". This way, modules can simply add
their definitions via "XML::Compile->addSchemaDirs(__FILE__)"
in a BEGIN block or in main. ExtUtils::MakeMaker will install everything
what is found in the "lib/" tree, so also your xsd files.
Probably, you also want to use knownNamespace().
example: adding xsd's from your own distribution
# file xxxxx/lib/My/Package.pm
# now xxxxx/lib/My/Package/xsd/ is also in the search path
use constant MYNS => 'http://my-namespace-uri';
XML::Compile->knownNamespace(&MYNS => 'my-schema-file.xsd');
- Collect $xml data, from a wide variety of sources. In SCALAR context, an
XML::LibXML::Element or XML::LibXML::Document is returned. In LIST
context, pairs of additional information follow the scalar result.
When a ready XML::LibXML::Node (::Element or ::Document) $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.
According the XML::LibXML::Parser manual page, passing a $fh is much slower
than pasing a $filename. However, it may be needed to open a file with an
my $xml = $schema->dataToXML('/etc/config.xml');
my ($xml, %details) = $schema->dataToXML($something);
my $xml = XML::Compile->dataToXML('/etc/config.xml');
- Create a new parser, an XML::LibXML::Parser object. By default, the
parsing is set in a safe mode, avoiding exploits. You may explicitly
overrule it, especially if you need to process entities.
- 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 is needed. An "undef" is returned
when the file is not found, otherwise a full path to the file is returned
to the caller.
Although the file may be found, it still could be unreadible.
- If used with only one $ns, it returns the filename in the distribution
(not the full path) which contains the definition.
When PAIRS of $ns-FILENAME are given, then those get defined. This is
typically called during the initiation of modules, like
XML::Compile::WSDL11 and XML::Compile::SOAP. The definitions are global:
not related to specific instances.
The FILENAMES are relative to the directories as specified with some
- $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
For end-users, the following packages are of interest (the other are support
Interpret schema elements and types: create processors for XML
Helps you administer compiled readers and writers, especially useful it
there are a lot of them. Extends XML::Compile::Schema.
Implements the SOAP 1.1 protocol. client side.
Implements the SOAP 1.2 protocol.
Use SOAP with a WSDL version 1.1 communication specification file.
Create a SOAP daemon, directly from a WSDL file.
Helps you write regression tests.
Clean-up XML structures: beautify, simplify, extract.
Enables you to save pre-compiled XML handlers, the results of any
"compileClient". However, this results in huge files, so this
may not be worth the effort.
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 fitting in Perl's idea of longs.
XML::Compile also supports all 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.
This module is part of XML-Compile distribution version 1.61, built on November
09, 2018. Website: http://perl.overmeer.net/xml-compile/
Copyrights 2006-2018 by [Mark Overmeer <firstname.lastname@example.org>]. 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://dev.perl.org/licenses/