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 included into.

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.pm becomes 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().

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 explicit character-set.

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.

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 addSchemaDirs() call.

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.