=head1 NAME

XML::Compile - Compilation based XML processing

=head1 INHERITANCE

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

=head1 SYNOPSIS

 # See XML::Compile::Schema / ::WSDL / ::SOAP

=head1 DESCRIPTION

Many (professional) applications process XML based on a formal
specification, expressed as XML Schema.  XML::Compile processes XML with
the help of such schemas.  The Perl program only handles a tree of nested
HASHes and ARRAYs.

Three serious WARNINGS:

=over 4

=item .

The compiler does only support B<namespace schemas>.  It is possible,
but generally seen as weakness, to make schemas which do not use
namespaces, but for the moment XML::Compile does not handle those.
Check for a C<targetNamespace> attribute on C<schema> in your C<xsd>
file.

=item .

The focus is on B<data-centric XML>, which means that mixed elements
are not understood automatically.  However, with using hooks, you can
work around this.

=item .

The provided B<schema is not validated>!  In many cases, compile-time
and run-time errors will get reported.  On the other hand, the processed
B<data is strictly validated>: both input and output will follow the
specs closely.

=back

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: process XML messages.

=item L<XML::Compile::WSDL|XML::Compile::WSDL> and XML::Compile::SOAP

Use the SOAP protocol. (implementation in progress)

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

Save pre-compiled converters in pure perl packages.

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

XML::Compile-E<gt>B<new>(TOP, OPTIONS)

=over 4

The TOP is the source of XML. See L<dataToXML()|XML::Compile/"Read XML"> for valid options.

If you have compiled/collected 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
 schema_dirs  undef

. schema_dirs => DIRECTORY|ARRAY-OF-DIRECTORIES

=over 4

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

$obj-E<gt>B<addSchemaDirs>(DIRECTORIES)

XML::Compile-E<gt>B<addSchemaDirs>(DIRECTORIES)

=over 4

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 used last), then the constructor option C<schema_dirs>
is processed.

If a pm filename is provided, then the directory to be used is
calculated from it (platform independent).  So, C<lib/XML/Compile.pm>
becomes C<lib/XML/Compile/xsd/>.  This way, modules can simply add
their definitions via C<< XML::Compile->addSchemaDirs(__FILE__) >>

Values which are C<undef> are skipped.  ARRAYs are flattened.  
Arguments are split on colons (only when on UNIX) after flattening.
The list of directories is returned, in all but VOID context.

=back

$obj-E<gt>B<findSchemaFile>(FILENAME)

=over 4

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 will take place.  An C<undef> is returned
when the file is not found or not readible, otherwise a full path to
the file is returned to the caller.

=back

$obj-E<gt>B<knownNamespace>(NAMESPACE|PAIRS)

XML::Compile-E<gt>B<knownNamespace>(NAMESPACE|PAIRS)

=over 4

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 and XML::Compile::SOAP.  The definitions are global.

=back

=head2 Read XML

$obj-E<gt>B<dataToXML>(NODE|REF-XML-STRING|XML-STRING|FILENAME|KNOWN)

=over 4

Collect XML data.  When a ready XML::LibXML 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.

=back

=head2 Filters

$obj-E<gt>B<walkTree>(NODE, CODE)

=over 4

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 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 just Perl's idea of longs.

XML::Compile suppoer the 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 DIAGNOSTICS

Error: cannot find pre-installed name-space files

=over 4

Use C<$ENV{SCHEMA_LOCATION}> or L<new(schema_dirs)|XML::Compile/"Constructors"> to express location
of installed name-space files, which came with the L<XML::Compile|XML::Compile>
distribution package.

=back

Error: don't known how to interpret XML data

=over 4

=back

Error: no XML data specified

=over 4

=back

=head1 SEE ALSO

This module is part of XML-Compile distribution version 0.55,
built on September 26, 2007. Website: F<http://perl.overmeer.net/xml-compile/>

=head1 LICENSE

Copyrights 2006-2007 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 F<http://www.perl.com/perl/misc/Artistic.html>