Ubuntu Manpage: XML::Compile - Compilation based XML processing

Provided by: libxml-compile-perl_1.63-3_all

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|XML-STRING|$filename|$fh|$known)
       XML::Compile->dataToXML($node|REF-XML|XML-STRING|$filename|$fh|$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 $fh 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($ns|PAIRS)
       XML::Compile->knownNamespace($ns|PAIRS)
           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.

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

LICENSE

       Copyrights 2006-2019 by [Mark Overmeer <markov@cpan.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/

perl v5.36.0                                       2022-11-27                                  XML::Compile(3pm)