NAME

       XML::Compile - Compilation based XML processing

INHERITANCE

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

SYNOPSIS

        # See XML::Compile::Schema / ::WSDL / ::SOAP11 etc

DESCRIPTION

       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.

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([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 XML::LibXML objects.

            -Option        --Default
             parser_options  <many>
             schema_dirs     undef

           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.

   Accessors
       $obj->addSchemaDirs(DIRECTORIES|FILENAME)
       XML::Compile->addSchemaDirs(DIRECTORIES|FILENAME)
           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().

           example: adding xsd's from your own distribution

             # file xxxxx/lib/My/Package.pm
             package My::Package;

             use XML::Compile;
             XML::Compile->addSchemaDirs(__FILE__);
             # 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');
             $schemas->importDefinitions(MYNS);

   Compilers
       $obj->dataToXML( NODE|REF-XML-STRING|XML-STRING|FILENAME|FILEHANDLE|KNOWN )
       XML::Compile->dataToXML( NODE|REF-XML-STRING|XML-STRING|FILENAME|FILEHANDLE|KNOWN )
           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 FILEHANDLE is much slower
           than pasing a FILENAME.  However, it may be needed to open a file with an explicit
           character-set.

           example:

             my $xml = $schema->dataToXML('/etc/config.xml');
             my ($xml, %details) = $schema->dataToXML($something);

             my $xml = XML::Compile->dataToXML('/etc/config.xml');

       $obj->initParser(OPTIONS)
       XML::Compile->initParser(OPTIONS)
           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.

   Administration
       $obj->findSchemaFile(FILENAME)
       XML::Compile->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
           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.

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

       $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

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

       •   XML::Compile::Schema

           Interpret schema elements and types: create processors for XML messages.

       •   XML::Compile::Cache

           Helps you administer compiled readers and writers, especially useful it there are a
           lot of them.  Extends XML::Compile::Schema.

       •   XML::Compile::SOAP

           Implements the SOAP 1.1 protocol. client side.

       •   XML::Compile::SOAP12

           Implements the SOAP 1.2 protocol.

       •   XML::Compile::WSDL11

           Use SOAP with a WSDL version 1.1 communication specification file.

       •   XML::Compile::SOAP::Daemon

           Create a SOAP daemon, directly from a WSDL file.

       •   XML::Compile::Tester

           Helps you write regression tests.

       •   XML::Rewrite

           Clean-up XML structures: beautify, simplify, extract.

       •   XML::Compile::Dumper

           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.

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

SEE ALSO

       This module is part of XML-Compile distribution version 1.42, built on January 06, 2014.
       Website: http://perl.overmeer.net/xml-compile/

       Other distributions in this suite: XML::Compile, XML::Compile::SOAP, XML::Compile::WSDL11,
       XML::Compile::SOAP12, XML::Compile::SOAP::Daemon, XML::Compile::SOAP::WSA,
       XML::Compile::C14N, XML::Compile::WSS, XML::Compile::WSS::Signature, XML::Compile::Tester,
       XML::Compile::Cache, XML::Compile::Dumper, XML::Compile::RPC, XML::Rewrite and
       XML::LibXML::Simple.

       Please post questions or ideas to the mailinglist at
       http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile .  For live contact with
       other developers, visit the "#xml-compile" channel on "irc.perl.org".

LICENSE

       Copyrights 2006-2014 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