The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
MARKOV / XML-Compile-1.55 / lib / XML / Compile.pod 
=encoding utf8

=head1 NAME

XML::Compile - Compilation based XML processing

=head1 INHERITANCE

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

=head1 SYNOPSIS

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

=head1 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:

=over 4

=item *

The focus is on B<data-centric XML>, which means that mixed elements
are not handler automatically: you need to work with XML::LibXML nodes
yourself, on these spots.

=item *

The B<data is not strictly validated>, still a large number of
compile-time errors can be reported.  Values are checked quite thoroughly.
Structure as well.

=item *

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 L<XML::Compile::Schema::importDefinitions()|XML::Compile::Schema/"Administration">
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.

=back

=head1 METHODS

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

=head2 Constructors

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

=over 4

=item XML::Compile-E<gt>B<new>( [$xmldata], %options )

The $xmldata is a source of XML. See L<dataToXML()|XML::Compile/"Compilers"> for valid ways,
for example as filename, string or C<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

=over 2

=item 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 L<initParser()|XML::Compile/"Compilers">.

=item schema_dirs => DIRECTORY|ARRAY-OF-DIRECTORIES

Where to find schema's.  This can be specified with the
environment variable C<SCHEMA_DIRECTORIES> or with this option.
See L<addSchemaDirs()|XML::Compile/"Accessors"> for a detailed explanation.

=back

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<addSchemaDirs>(@directories|$filename)

=item XML::Compile-E<gt>B<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 C<SCHEMA_DIRECTORIES> is added
(therefore tried as last resort). The constructor option C<schema_dirs>
is a little more favorite.

Values which are C<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 C<.pm> package $filename is given, then the directory
to be used is calculated from it (platform independently).  So,
C<something/XML/Compile.pm> becomes C<something/XML/Compile/xsd/>.
This way, modules can simply add their definitions via C<<
XML::Compile->addSchemaDirs(__FILE__) >> in a BEGIN block or in main.
ExtUtils::MakeMaker will install everything what is found in the
C<lib/> tree, so also your xsd files.  Probably, you also want to use
L<knownNamespace()|XML::Compile/"Administration">.

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

=back

=head2 Compilers

=over 4

=item $obj-E<gt>B<dataToXML>($node|REF-XML|XML-STRING|$filename|$fh|$known)

=item XML::Compile-E<gt>B<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
'E<lt>' is interpreted as $xml text.

You may also specify a pre-defined I<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 L<new(schema_dirs)|XML::Compile/"Constructors"> (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');

=item $obj-E<gt>B<initParser>(%options)

=item XML::Compile-E<gt>B<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.

=back

=head2 Administration

=over 4

=item $obj-E<gt>B<findSchemaFile>($filename)

=item XML::Compile-E<gt>B<findSchemaFile>($filename)

Runs through all defined schema directories (see L<addSchemaDirs()|XML::Compile/"Accessors">)
in search of the specified $filename.  When the $filename is absolute,
that will be used, and no search is needed.  An C<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.

=item $obj-E<gt>B<knownNamespace>($ns|PAIRS)

=item XML::Compile-E<gt>B<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
L<XML::Compile::WSDL11|XML::Compile::WSDL11> and L<XML::Compile::SOAP|XML::Compile::SOAP>.  The definitions
are global: not related to specific instances.

The FILENAMES are relative to the directories as specified with some
L<addSchemaDirs()|XML::Compile/"Accessors"> call.

=item $obj-E<gt>B<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.

=back

=head1 DETAILS

=head2 Distribution collection overview

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

=over 4

=item * L<XML::Compile::Schema|XML::Compile::Schema>

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

=item * L<XML::Compile::Cache|XML::Compile::Cache>

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

=item * L<XML::Compile::SOAP|XML::Compile::SOAP>

Implements the SOAP 1.1 protocol. client side.

=item * L<XML::Compile::SOAP12|XML::Compile::SOAP12>

Implements the SOAP 1.2 protocol.

=item * L<XML::Compile::WSDL11|XML::Compile::WSDL11>

Use SOAP with a WSDL version 1.1 communication specification file.

=item * L<XML::Compile::SOAP::Daemon|XML::Compile::SOAP::Daemon>

Create a SOAP daemon, directly from a WSDL file.

=item * L<XML::Compile::Tester|XML::Compile::Tester>

Helps you write regression tests.

=item * L<XML::Rewrite|XML::Rewrite>

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

=item * L<XML::Compile::Dumper|XML::Compile::Dumper>

Enables you to save pre-compiled XML handlers, the results of any
C<compileClient>.  However, this results in huge files, so this may
not be worth the effort.

=back

=head2 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 C<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 C<list>,
C<union>, C<substitutionGroup> (unions on complex type level), and even
the nasty C<any> and C<anyAttribute>, which is rarely the case for the
other modules.

=head1 SEE ALSO

This module is part of XML-Compile distribution version 1.55,
built on March 08, 2017. Website: F<http://perl.overmeer.net/xml-compile/>

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

=head1 LICENSE

Copyrights 2006-2017 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the Artistic license.
See F<http://dev.perl.org/licenses/artistic.html>