=head1 NAME

XML::Compile::Schema - Compile a schema into CODE

=head1 INHERITANCE

 XML::Compile::Schema
   is a XML::Compile

=head1 SYNOPSIS

 # compile tree yourself
 my $parser = XML::LibXML->new;
 my $tree   = $parser->parse...(...);
 my $schema = XML::Compile::Schema->new($tree);

 # get schema from string
 my $schema = XML::Compile::Schema->new($xml_string);

 # get schema from file
 my $schema = XML::Compile::Schema->new($filename);

 # adding schemas
 $schema->addSchemas($tree);
 $schema->importDefinitions('http://www.w3.org/2001/XMLSchema');
 $schema->importDefinitions('2001-XMLSchema.xsd');

 # alternatively
 my @specs  = ('one.xsd', 'two.xsd', $schema_as_string);
 my $schema = XML::Compile::Schema->new(\@specs); # ARRAY!

 # see what types are defined
 $schema->namespaces->printIndex;

 # create and use a reader
 use XML::Compile::Util qw/pack_type/;
 my $elem   = pack_type 'my-namespace', 'my-local-name';
                # $elem eq "{my-namespace}my-local-name"
 my $read   = $schema->compile(READER => $elem);
 my $data   = $read->($xmlnode);
 my $data   = $read->("filename.xml");
 
 # when you do not know the element type beforehand
 use XML::Compile::Util qw/type_of_node/;
 my $elem   = type_of_node $xml->documentElement;
 my $reader = $reader_cache{$type}               # either exists
          ||= $schema->compile(READER => $elem); #   or create
 my $data   = $reader->($xmlmsg);
 
 # create and use a writer
 my $doc    = XML::LibXML::Document->new('1.0', 'UTF-8');
 my $write  = $schema->compile(WRITER => '{myns}mytype');
 my $xml    = $write->($doc, $hash);
 my $result = $doc->setDocumentElement($xml);

 # show result
 print $xml->toString;

 # to create the type nicely
 use XML::Compile::Util qw/pack_type/;
 my $type   = pack_type 'myns', 'mytype';
 print $type;  # shows  {myns}mytype

=head1 DESCRIPTION

This module collects knowledge about one or more schemas.  The most
important method provided is L<compile()|XML::Compile::Schema/"Compilers">, which can create XML file
readers and writers based on the schema information and some selected
element or attribute type.

Various implementations use the translator, and more can be added
later:

=over 4

=item C<$schema->compile('READER'...)> translates XML to HASH

The XML reader produces a HASH from a XML::LibXML::Node tree or an
XML string.  Those represent the input data.  The values are checked.
An error produced when a value or the data-structure is not according
to the specs.

The CODE reference which is returned can be called with anything
accepted by L<dataToXML()|XML::Compile/"Read XML">.

example: create an XML reader

 my $msgin  = $rules->compile(READER => '{myns}mytype');
 # or  ...  = $rules->compile(READER => pack_type('myns', 'mytype'));
 my $xml    = $parser->parse("some-xml.xml");
 my $hash   = $msgin->($xml);

or

 my $hash   = $msgin->('some-xml.xml');
 my $hash   = $msgin->($xml_string);
 my $hash   = $msgin->($xml_node);

=item C<$schema->compile('WRITER', ...)> translates HASH to XML

The writer produces schema compliant XML, based on a Perl HASH.  To get
the data encoding correctly, you are required to pass a document object
in which the XML nodes may get a place later.

example: create an XML writer

 my $doc    = XML::LibXML::Document->new('1.0', 'UTF-8');
 my $write  = $schema->compile(WRITER => '{myns}mytype');
 my $xml    = $write->($doc, $hash);
 print $xml->toString;
 
alternative

 my $write  = $schema->compile(WRITER => 'myns#myid');

=item C<$schema->template('XML', ...)> creates an XML example

Based on the schema, this produces an XML message as example.  Schemas
are usually so complex that people loose overview.  This example may
put you back on track, and used as starting point for many creating the
XML version of the message.

=item C<$schema->template('PERL', ...)> creates an Perl example

Based on the schema, this produces an Perl HASH structure (a bit
like the output by Data::Dumper), which can be used as template
for creating messages.  The output contains documentation, and is
usually much clearer than the schema itself.

=back

Be warned that the B<schema is not validated>; you can develop schemas
which do work well with this module, but are not valid according to W3C.
In many cases, however, the translater will refuse to accept mistakes:
mainly because it cannot produce valid code.

=head1 METHODS

=head2 Constructors

XML::Compile::Schema-E<gt>B<new>([XMLDATA], OPTIONS)

=over 4

Details about many name-spaces can be organized with only a single
schema object (actually, the data is administered in an internal
L<XML::Compile::Schema::NameSpaces|XML::Compile::Schema::NameSpaces> object)

The initial information is extracted from the XMLDATA source.  The XMLDATA
can be anything what is acceptable by L<importDefinitions()|XML::Compile::Schema/"Accessors">, which is
everything accepted by L<dataToXML()|XML::Compile/"Read XML"> or an ARRAY of those things.

You can specify the hooks before you define the schemas the hooks
work on: all schema information and all hooks are only used when
the readers and writers get compiled.

 Option     --Defined in     --Default
 hook                          undef
 hooks                         []
 schema_dirs  XML::Compile     undef

. hook => ARRAY-WITH-HOOKDATA | HOOK

=over 4

See L<addHook()|XML::Compile::Schema/"Accessors">.  Adds one HOOK (HASH).

=back

. hooks => ARRAY-OF-HOOK

=over 4

See L<addHooks()|XML::Compile::Schema/"Accessors">.

=back

. schema_dirs => DIRECTORY|ARRAY-OF-DIRECTORIES

=back

=head2 Accessors

$obj-E<gt>B<addHook>(HOOKDATA|HOOK|undef)

=over 4

HOOKDATA is a LIST of options as key-value pairs, HOOK is a HASH with
the same data.  C<undef> is ignored. See L<addHooks()|XML::Compile::Schema/"Accessors"> and
L</Schema hooks> below.

=back

$obj-E<gt>B<addHooks>(HOOK, [HOOK, ...])

=over 4

Add multiple hooks at once.  These must all be HASHes. See L</Schema hooks>
and L<addHook()|XML::Compile::Schema/"Accessors">. C<undef> values are ignored.

=back

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

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

=over 4

See L<XML::Compile/"Accessors">

=back

$obj-E<gt>B<addSchemas>(XML, OPTIONS)

=over 4

Collect all the schemas defined in the XML data.  The XML parameter
must be a XML::LibXML node, therefore it is adviced to use
L<importDefinitions()|XML::Compile::Schema/"Accessors">, which has a much more flexible way to
specify the data.

 Option  --Default
 filename  undef
 source    undef

. filename => FILENAME

=over 4

Explicitly state from which file the data is coming.

=back

. source => STRING

=over 4

An indication where this schema data was found.  If you use L<dataToXML()|XML::Compile/"Read XML">
in LIST context, you get such an indication.

=back

=back

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

=over 4

See L<XML::Compile/"Accessors">

=back

$obj-E<gt>B<hooks>

=over 4

Returns the LIST of defined hooks (as HASHes).

=back

$obj-E<gt>B<importDefinitions>(XMLDATA, OPTIONS)

=over 4

Import (include) the schema information included in the XMLDATA.  The
XMLDATA must be acceptable for L<dataToXML()|XML::Compile/"Read XML">.  The resulting node
and the OPTIONS are passed to L<addSchemas()|XML::Compile::Schema/"Accessors">. The schema node does
not need to be the top element: any schema node found in the data
will be decoded.

Returned is a list of L<XML::Compile::Schema::Instance|XML::Compile::Schema::Instance> objects,
for each processed schema component.

If your program imports the same string or file definitions multiple
times, it will re-use the schema information from the first import.
This removal of dupplications will not work for open files or pre-parsed
XML structures.

As an extension to the handling L<dataToXML()|XML::Compile/"Read XML"> provides, you can specify an
ARRAY of things which are acceptable to C<dataToXML>.  This way, you can
specify multiple resources at once, each of which will be processed with
the same OPTIONS.

example: of use of importDefinitions

  my $schema = XML::Compile::Schema->new;
  $schema->importDefinitions('my-spec.xsd');

  my $other = "<schema>...</schema>";  # use 'HERE' documents!
  my @specs = ('my-spec.xsd', 'types.xsd', $other);
  $schema->importDefinitions(\@specs, @options);

=back

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

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

=over 4

See L<XML::Compile/"Accessors">

=back

$obj-E<gt>B<namespaces>

=over 4

Returns the L<XML::Compile::Schema::NameSpaces|XML::Compile::Schema::NameSpaces> object which is used
to collect schemas.

=back

=head2 Read XML

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

=over 4

See L<XML::Compile/"Read XML">

=back

=head2 Filters

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

=over 4

See L<XML::Compile/"Filters">

=back

=head2 Compilers

$obj-E<gt>B<compile>(('READER'|'WRITER'), TYPE, OPTIONS)

=over 4

Translate the specified ELEMENT (found in one of the read schemas) into
a CODE reference which is able to translate between XML-text and a HASH.
When the TYPE is C<undef>, an empty LIST is returned.

The indicated TYPE is the starting-point for processing in the
data-structure, a toplevel element or attribute name.  The name must
be specified in C<{url}name> format, there the url is the name-space.
An alternative is the C<url#id> which refers to an element or type with
the specific C<id> attribute value.

When a READER is created, a CODE reference is returned which needs
to be called with XML, as accepted by L<XML::Compile::dataToXML()|XML::Compile/"Read XML">.
Returned is a nested HASH structure which contains the data from
contained in the XML.  The transformation rules are explained below.

When a WRITER is created, a CODE reference is returned which needs
to be called with an XML::LibXML::Document object and a HASH, and
returns a XML::LibXML::Node.

Most options below are B<explained in more detailed> in the manual-page
L<XML::Compile::Schema::Translate|XML::Compile::Schema::Translate>, which implements the compilation.

 Option                        --Default
 anyAttribute                    undef
 anyElement                      undef
 attributes_qualified            <undef>
 check_occurs                    <true>
 check_values                    <true>
 elements_qualified              <undef>
 hook                            undef
 hooks                           undef
 ignore_facets                   <false>
 ignore_used_tags                <false>
 include_namespaces              <true>
 interpret_nillable_as_optional  <false>
 namespace_reset                 <false>
 output_namespaces               {}
 path                            <expanded name of type>
 permit_href                     <false>
 sloppy_integers                 <false>
 use_default_prefix              <false>
 validation                      <true>

. anyAttribute => CODE

=over 4

In general, C<anyAttribute> schema components cannot be handled
automatically.  If  you need to create or process anyAttribute
information, then read about wildcards in the DETAILS chapter of the
manual-page for the specific back-end.

=back

. anyElement => CODE

=over 4

In general, C<any> schema components cannot be handled automatically.
If  you need to create or process any information, then read about
wildcards in the DETAILS chapter of the manual-page for the specific
back-end.

=back

. attributes_qualified => BOOLEAN

=over 4

When defined, this will overrule the C<attributeFormDefault> flags in
all schemas.  When not qualified, the xml will not produce nor
process prefixes on attributes.

=back

. check_occurs => BOOLEAN

=over 4

Whether code will be produced to do bounds checking on elements and blocks
which may appear more than once. When the schema says that maxOccurs is 1,
then that element becomes optional.  When the schema says that maxOccurs
is larger than 1, then the output is still always an ARRAY, but now of
unrestricted length.

=back

. check_values => BOOLEAN

=over 4

Whether code will be produce to check that the XML fields contain
the expected data format.

Turning this off will improve the processing speed significantly, but is
(of course) much less safe.  Do not set it off when you expect data from
external sources: validation is a crucial requirement for XML.

=back

. elements_qualified => C<TOP>|C<ALL>|C<NONE>|BOOLEAN

=over 4

When defined, this will overrule the C<elementFormDefault> flags in
all schemas.  When C<TOP> is specified, at least the top-element will
be name-space qualified.  When C<ALL> or a true value is given, then all
elements will be used qualified.  When C<NONE> or a false value is given,
the XML will not produce or process prefixes on the elements.

The C<form> attributes will be respected, except on the top element when
C<TOP> is specified.  Use hooks when you need to fix name-space use in
more subtile ways.

=back

. hook => HOOK|ARRAY-OF-HOOKS

=over 4

Define one or more processing hooks.  See L</Schema hooks> below.
These hooks are only active for this compiled entity, where L<addHook()|XML::Compile::Schema/"Accessors">
and L<addHooks()|XML::Compile::Schema/"Accessors"> can be used to define hooks which are used for all
results of L<compile()|XML::Compile::Schema/"Compilers">.  The hooks specified with the C<hook> or C<hooks>
option are run before the global definitions.

=back

. hooks => HOOK|ARRAY-OF-HOOKS

=over 4

Alternative for option C<hook>.

=back

. ignore_facets => BOOLEAN

=over 4

Facets influence the formatting and range of values. This does
not come cheap, so can be turned off.  It affects the restrictions
set for a simpleType.  The processing speed will improve, but validation
is a crucial requirement for XML: please do not turn this off when the
data comes from external sources.

=back

. ignore_used_tags => BOOLEAN

=over 4

(WRITER) Usually, a C<mistake> warning is produced when a user provides
a data structure which contains more data than is needed for the XML
message which is created; this will show structural problems.  However,
in some cases, you may want to play tricks with the data-structure and
therefore disable this precausion.

=back

. include_namespaces => BOOLEAN

=over 4

Indicates whether the WRITER should include the prefix to namespace
translation on the top-level element of the returned tree.  If not,
you may continue with the same name-space table to combine various
XML components into one, and add the namespaces later.

=back

. interpret_nillable_as_optional => BOOLEAN

=over 4

Found in the wild-life, people who think that nillable means optional.
Not too hard to fix.  For the WRITER, you still have to state NIL
explicitly, but the elements are not constructed.  The READER will
output NIL when the nillable elements are missing.

=back

. namespace_reset => BOOLEAN

=over 4

Use the same prefixes in C<output_namespaces> as with some other compiled
piece, but reset the counts to zero first.

=back

. output_namespaces => HASH|ARRAY-of-PAIRS

=over 4

Can be used to predefine an output namespace (when 'WRITER') for instance
to reserve common abbreviations like C<soap> for external use.  Each
entry in the hash has as key the namespace uri.  The value is a hash
which contains C<uri>, C<prefix>, and C<used> fields.  Pass a reference
to a private hash to catch this index.  An ARRAY with prefix, uri PAIRS
is simpler.

=back

. path => STRING

=over 4

Prepended to each error report, to indicate the location of the
error in the XML-Scheme tree.

=back

. permit_href => BOOLEAN

=over 4

When parsing SOAP-RPC encoded messages, the elements may have a C<href>
attribute, pointing to an object with C<id>.  The READER will return the
unparsed, unresolved node when the attribute is detected, and the SOAP-RPC
decoder will have to discover and resolve it.

=back

. sloppy_integers => BOOLEAN

=over 4

The C<decimal> and C<integer> types must support at least 18 digits,
which is larger than Perl's 32 bit internal integers.  Therefore, the
implementation will use Math::BigInt objects to handle them.  However,
often an simple C<int> type whould have sufficed, but the XML designer
was lazy.  A long is much faster to handle.  Set this flag to use C<int>
as fast (but inprecise) replacements.

Be aware that C<Math::BigInt> and C<Math::BigFloat> objects are nearly
but not fully transparent mimicing the behavior of Perl's ints and
floats.  See their respective manual-pages.  Especially when you wish
for some performance, you should optimize access to these objects to
avoid expensive copying which is exactly the spot where the differences
are.

You can also improve the speed of Math::BigInt by installing
Math::BigInt::GMP.  Add C<< use Math::BigInt try => 'GMP'; >> to the
top of your main script to get more performance.

=back

. use_default_prefix => BOOLEAN

=over 4

When mixing qualified and unqualified namespaces, then the use of
a default prefix can be quite confusing.  Therefore, by default, all
qualified elements will have an explicit prefix.

=back

. validation => BOOLEAN

=over 4

XML message must be validated, to lower the chance on abuse.  However,
of course, it costs performance which is only partially compensated by
fewer checks in your code.  This flag overrules the C<check_values>,
C<check_occurs>, and C<ignore_facets>.

=back

=back

$obj-E<gt>B<elements>

=over 4

List all elements, defined by all schemas sorted alphabetically.

=back

$obj-E<gt>B<template>('XML'|'PERL', TYPE, OPTIONS)

=over 4

Schema's can be horribly complex and unreadible.  Therefore, this template
method can be called to create an example which demonstrates how data of
the specified TYPE as XML or Perl is organized in practice.

Some OPTIONS are explained in L<XML::Compile::Schema::Translate|XML::Compile::Schema::Translate>.
There are some extra OPTIONS defined for the final output process.

The templates produced are B<not always correct>.  Please contribute
improvements.

 Option              --Default
 attributes_qualified  <undef>
 elements_qualified    <undef>
 include_namespaces    <true>
 indent                " "
 show                  ALL

. attributes_qualified => BOOLEAN

. elements_qualified => C<ALL>|C<TOP>|C<NONE>|BOOLEAN

. include_namespaces => BOOLEAN

. indent => STRING

=over 4

The leading indentation string per nesting.  Must start with at least one
blank.

=back

. show => STRING|'ALL'|'NONE'

=over 4

A comma seperated list of tokens, which explain what kind of comments need
to be included in the output.  The available tokens are: C<struct>, C<type>,
C<occur>, C<facets>.  A value of C<ALL> will select all available comments.
The C<NONE> or empty string will exclude all comments.

=back

=back

$obj-E<gt>B<types>

=over 4

List all types, defined by all schemas sorted alphabetically.

=back

=head1 DETAILS

=head2 Comparison

=head2 Collecting definitions

When starting an application, you will need to read the schema
definitions.  This is done by instantiating an object via
L<XML::Compile::Schema::new()|XML::Compile::Schema/"Constructors"> or L<XML::Compile::WSDL11::new()|XML::Compile::WSDL11/"Constructors">.
The WSDL11 object has a schema object internally.

Schemas may contains C<import> and C<include> statements, which
specify other resources for definitions.  In the idea of the XML design
team, those files should be retrieved automatically via an internet
connection from the C<schemaLocation>.  However, this is a bad concept; in
XML::Compile modules you will have to explictly provide filenames on local
disk using L<importDefinitions()|XML::Compile::Schema/"Accessors"> or L<XML::Compile::WSDL11::addWSDL()|XML::Compile::WSDL11/"Extension">.

There are various reasons why I, the author of this module, think the
dynamic automatic internet imports are a bad idea.  First: you do not
always have a working internet connection (travelling with a laptop in
a train).  Your implementation should work the same way under all
environmental circumstances!  Besides, I do not trust remote files on
my system, without inspecting them.  Most important: I want to run my
regression tests before using a new version of the definitions, so I do
not want to have a remote server change the agreements without my
knowledge.

So: before you start, you will need to scan (recursively) the initial
schema or wsdl file for C<import> and C<include> statements, and
collect all these files from their C<schemaLocation> into files on
local disk.  In your program, call L<importDefinitions()|XML::Compile::Schema/"Accessors"> on all of
them -in any order- before you call L<compile()|XML::Compile::Schema/"Compilers">.

=head3 Organizing your definitions

One nice feature to help you organize (especially useful when you
package your code in a distribution), is to add these lines to the
beginning of your code:

  package My::Package;
  XML::Compile->addSchemaDirs(__FILE__);
  XML::Compile->knownNamespace('http://myns' => 'myns.xsd', ...);

Now, if the package file is located at C<SomeThing/My/Package.pm>,
the definion of the namespace should be kept in
C<SomeThing/My/Package/xsd/myns.xsd>.

Somewhere in your program, you have to load these definitions:

  # absolute or relative path is always possible
  $schema->importDefinitions('SomeThing/My/Package/xsd/myns.xsd');

  # relative search path extended by addSchemaDirs
  $schema->importDefinitions('myns.xsd');

  # knownNamespace improves abstraction
  $schema->importDefinitions('http://myns');

Very probably, the namespace is already in some variable:

  use XML::Compile::Schema;
  use XML::Compile::Util  'pack_type';

  my $myns   = 'http://some-very-long-uri';
  my $schema = XML::Compile::Schema->new($myns);
  my $mytype = pack_type $myns, $myelement;
  my $reader = $schema->compileClient(READER => $mytype);

=head2 Addressing components

Normally, external users can only address elements within a schema,
and types are hidden to be used by other schemas only.  For this
reason, it is permitted to create an element and a type with the
same name.

The compiler requires a starting-point.  This can either be an
element name or an element's id.  The format of the element name
is C<{namespace-uri}localname>, for instance

 {http://library}book

You may also start with

 http://www.w3.org/2001/XMLSchema#float

as long as this ID refers to a top-level element, not a type.

When you use a schema without C<targetNamespace> (which is bad practice,
but sometimes people really do not understand the beneficial aspects of
the use of namespaces) then the elements can be addressed as C<{}name>
or simple C<name>.

=head2 Representing data-structures

The code will do its best to produce a correct translation. For
instance, an accidental C<1.9999> will be converted into C<2>
when the schema says that the field is an C<int>.  It will also
strip superfluous blanks when the data-type permits.  Especially
watch-out for the C<Integer> types, which produce Math::BigInt
objects unless L<compile(sloppy_integers)|XML::Compile::Schema/"Compilers"> is used.

Elements can be complex, and themselve contain elements which
are complex.  In the Perl representation of the data, this will
be shown as nested hashes with the same structure as the XML.

You should not take tare of character encodings, whereas XML::LibXML is
doing that for us: you shall not escape characters like "E<lt>" yourself.

The schemas define kinds of data types.  There are various ways to define
them (with restrictions and extensions), but for the resulting data
structure is that knowledge not important.

=over 4

=item simpleType

A single value.  A lot of single value data-types are built-in (see
L<XML::Compile::Schema::BuiltInTypes|XML::Compile::Schema::BuiltInTypes>).

Simple types may have range limiting restrictions (facets), which will
be checked by default.  Types may also have some white-space behavior,
for instance blanks are stripped from integers: before, after, but also
inside the number representing string.

Note that some of the reader hooks will alter the single value of these
elements into a HASH like used for the complexType/simpleContent (next
paragraph), to be able to return some extra collected information.

example: typical simpleType

In XML, it looks like this:

 <test1>42</test1>

In the HASH structure, the data will be represented as

 test1 => 42

With reader hook C<< after => 'XML_NODE' >> hook applied, it will become

 test1 => { _ => 42
          , _XML_NODE => $obj
          }
 
=item complexType/simpleContent

In this case, the single value container may have attributes.  The number
of attributes can be endless, and the value is only one.  This value
has no name, and therefore gets a predefined name C<_>.

example: typical simpleContent example

In XML, this looks like this:

 <test2 question="everything">42</test2>

As a HASH, this looks like

 test2 => { _ => 42
          , question => 'everything'
          }

=item complexType and complexType/complexContent

These containers not only have attributes, but also multiple values
as content.  The C<complexContent> is used to create inheritance
structures in the data-type definition.  This does not affect the
XML data package itself.

example: typical complexType element

The XML could look like:

 <test3 question="everything" by="mouse">
   <answer>42</answer>
   <when>5 billion BC</when>
 </test3>

Represented as HASH, this looks like

 test3 => { question => 'everything'
          , by       => 'mouse'
          , answer   => 42
          , when     => '5 billion BC'
          }

=item anything by XML NODE

For a WRITER, you may also specify a XML::LibXML::Node anywhere.

 test1 => $doc->createTextNode('42');
 test3 => $doc->createElement('ariba');

This data-structure is used without validation, so you are fully on
your own with this one.

=back

=head2 Processing

A second factor which determines the data-structure is the element
occurrence.  Usually, elements have to appear once and exactly once
on a certain location in the XML data structure.  This order is
automatically produced by this module. But elements may appear multiple
times.

=over 4

=item usual case

The default behavior for an element (in a sequence container) is to
appear exactly once.  When missing, this is an error.

=item maxOccurs larger than 1

In this case, the element or particle block can appear multiple times.
Multiple values are kept in an ARRAY within the HASH.  Non-schema based
XML modules do not return a single value as an ARRAY, which makes that
code more complicated.  But in our case, we know the expected amount
beforehand.

When the maxOccurs larger than 1 is specified for an element, an ARRAY
of those elements is produced.  When it is specified for a block (sequence,
choice, all, group), then an ARRAY of HASHes is returned.  See the special
section about the subject.

An error is produced when the number of elements found is less than
C<minOccurs> (defaults to 1) or more than C<maxOccurs> (defaults to 1),
unless L<compile(check_occurs)|XML::Compile::Schema/"Compilers"> is C<false>.

example: elements with maxOccurs larger than 1

In the schema:
 <element name="a" type="int" maxOccurs="unbounded" />
 <element name="b" type="int" />

In the XML message:
 <a>12</a><a>13</a><b>14</b>

In the Perl representation:
 a => [12, 13], b => 14

=item value is C<NIL>

When an element is nillable, that is explicitly represented as a C<NIL>
constant string.

=item use="optional" or minOccurs="0"

The element may be skipped.  When found it is a single value.

=item use="forbidden"

When the element is found, an error is produced.

=item default="value"

When the XML does not contain the element, the default value is
used... but only if this element's container exists.  This has
no effect on the writer.

=item fixed="value"

Produce an error when the value is not present or different (after
the white-space rules where applied).

=back

=head2 Repetative blocks

Particle blocks come in four shapes: C<sequence>, C<choice>, C<all>,
and C<group> (an indirect block).  This also affects C<substitutionGroups>.

In situations like this:

  <element name="example">
    <complexType>
      <sequence>
        <element name="a" type="int" />
        <sequence>
          <element name="b" type="int" />
        </sequence>
        <element name="c" type="int" />
      </sequence>
    </complexType>
  </element>

(yes, schemas are verbose) the data structure is

  <example> <a>1</a> <b>2</b> <c>3</c> </example>

the Perl representation is I<flattened>, into

  example => { a => 1, b => 2, c => 3 }

Ok, this is very simple.  However, schemas can use repetition:

  <element name="example">
    <complexType>
      <sequence>
        <element name="a" type="int" />
        <sequence minOccurs="0" maxOccurs="unbounded">
          <element name="b" type="int" />
        </sequence>
        <element name="c" type="int" />
      </sequence>
    </complexType>
  </element>

The XML message may be:

  <example> <a>1</a> <b>2</b> <b>3</b> <b>4</b> <c>5</c> </example>

Now, the perl representation needs to produce an array of the data in
the repeated block.  This array needs to have a name, because more of
these blocks may appear together in a construct.  The B<name of the
block> is derived from the I<type of block> and the name of the I<first
element> in the block, regardless whether that element is present in
the data or not.  See L<XML::Compile::Util::block_label()|XML::Compile::Util/"Other">.

So, our example data is translated into (and vice versa)

  example =>
    { a     => 1
    , seq_b => [ {b => 2}, {b => 3}, {b => 4} ]
    , c     => 5
    }

For B<substitutionGroup>s which are repeating, the I<name of the base
element> is used (the element which has attribute C<<abstract="true">>.
We do need this array, because the order of the elements within the group
may be important; we cannot group the elements based to the extended
element's name.

In an example substitutionGroup, the Perl representation will be
something like this:

  base-element-name =>
    [ { extension-name  => $data1 }
    , { other-extension => $data2 }
    ]

Each HASH has only one key.

example: always an array with maxOccurs larger than 1

Even when there is only one element found, it will be returned as
ARRAY (of one element).  Therefore, you can write

 my $data = $reader->($xml);
 foreach my $a ( @{$data->{a}} ) {...}

example: blocks with maxOccurs larger than 1

In the schema:
 <sequence maxOccurs="5">
   <element name="a" type="int" />
   <element name="b" type="int" />
 </sequence>

In the XML message:
 <a>15</a><b>16</b><a>17</a><b>18</b>

In Perl representation:
 seq_a => [ {a => 15, b => 16}, {a => 17, b => 18} ]

=head2 List type

List simpleType objects are also represented as ARRAY, like elements
with a minOccurs or maxOccurs unequal 1.

example: with a list of ints

  <test5>3 8 12</test5>

as Perl structure:

  test5 => [3, 8, 12]

=head2 substitutionGroup

A substitution group is kind-of choice between alternative (complex)
types.  However, in this case roles have reversed: instead a C<choice>
which lists the alternatives, here the alternative elements register
themselves as valid for an abstract (I<head>) element.  All alternatives
should be extensions of the head element's type, but there is no way to
check that.

example: substitutionGroup

 <xs:element name="price"  type="xs:int" abstract="true" />
 <xs:element name="euro"   type="xs:int" substitutionGroup="price" />
 <xs:element name="dollar" type="xs:int" substitutionGroup="price" />

 <xs:element name="product">
   <xs:complexType>
      <xs:element name="name" type="xs:string" />
      <xs:element ref="price" />
   </xs:complexType>
 </xs:element>
 
Now, valid XML data is

 <product>
   <name>Ball</name>
   <euro>12</euro>
 </product>

and

 <product>
   <name>Ball</name>
   <dollar>6</dollar>
 </product>

The HASH repesentation is respectively

 product => {name => 'Ball', euro  => 12}
 product => {name => 'Ball', dollar => 6}

=head2 Wildcards

The C<any> and C<anyAttribute> elements are referred to as C<wildcards>:
they specify groups of elements and attributes which can be used, in
stead of being explicit.

The author of this module advices B<against the use of wildcards> in
schemas, because the purpose of schemas is to be explicit about the
structure of the message, and that basic idea is simply thrown away by
these wildcards.  Let people cleanly extend the schema with inheritance!
If you use a standard schema which facilitates these wildcards, then
please do not use them!

Because wildcards are not explicit about the types to expect, the
C<XML::Compile> module can not prepare for them automatically.
However, as user of the schema you probably know better about the possible
contents of these fields.  Therefore, you can translate that
knowledge into code explicitly.  Read about the processing of wildcards
in the manual page for each of the back-ends, because it is different
in each case.

=head2 Mixed elements

ComplexType and ComplexContent components can be declared with the
C<<mixed="true">> attribute.  This implies that text is not limited
to the content of containers, but also be used inbetween elements.
Usually, you will only find ignorable white-space between elements.

XML::Compile does not have a syntax to express these mixtures of
information and text, so the only way you can use those, is by providing
your self-constructed XML::LibXML node for such element.

There is currently no mechanism to warn you for mixed constructs.

=head2 Schema hooks

You can use hooks, for instance, to block processing parts of the message,
to create work-arounds for schema bugs, or to extract more information
during the process than done by default.

=head3 defining hooks

Multiple hooks can active during the compilation process of a type,
when C<compile()> is called.  During Schema translation, each of the
hooks is checked for all types which are processed.  When multiple
hooks select the object to get a modified behavior, then all are
evaluated in order of definition.

Defining a B<global> hook (where HOOKDATA is the LIST of PAIRS with
hook parameters, and HOOK a HASH with such HOOKDATA):

 my $schema = XML::Compile::Schema->new
  ( ...
  , hook  => HOOK
  , hooks => [ HOOK, HOOK ]
  );

 $schema->addHook(HOOKDATA | HOOK);
 $schema->addHooks(HOOK, HOOK, ...);

 my $wsdl   = XML::Compile::WSDL->new(...);
 $wsdl->schemas->addHook(HOOKDATA | HOOK);

B<local> hooks are only used for one reader or writer.  They are
evaluated before the global hooks.

 my $reader = $schema->compile(READER => $type
  , hook => HOOK, hooks => [ HOOK, HOOK, ...]);

example: of HOOKs:

 my $hook = { type    => '{my_ns}my_type'
            , before  => sub { ... }
            };

 my $hook = { path    => qr/\(volume\)/
            , replace => 'SKIP'
            };

 # path contains "(volume)" or id is 'aap' or id is 'noot'
 my $hook = { path    => qr/\(volume\)/
            , id      => [ 'aap', 'noot' ]
            , before  => [ sub {...}, sub { ... } ]
            , after   => sub { ... }
            };

=head3 general syntax

Each hook has two kinds of parameters: selectors and processors.
Selectors define the schema component of which the processing is modified.
When one of the selectors matches, the processing information for the hook
is used.  When no selector is specified, then the hook will be used on all
elements.

Available selectors (see below for details on each of them):

=over 4

=item . type

=item . id

=item . path

=back

As argument, you can specify one element as STRING, a regular expression
to select multiple elements, or an ARRAY of STRINGs and REGEXes.

Next to where the hook is placed, we need to known what to do in
the case: the hook contains processing information.  When more than
one hook matches, then all of these processors are called in order
of hook definition.  However, first the compile hooks are taken,
and then the global hooks.

How the processing works exactly depends on the compiler back-end.  There
are major differences.  Each of those manual-pages lists the specifics.
The label tells us when the processing is initiated.  Available labels are
C<before>, C<replace>, and C<after>.

=head3 hooks on matching types

The C<type> selector specifies a complexType of simpleType by name.
Best is to base the selection on the full name, like C<{ns}type>,
which will avoid all kinds of name-space conflicts in the future.
However, you may also specify only the C<type> (in any name-space).
Any REGEX will be matched to the full type name. Be careful with the
pattern archors.

example: use of the type selector

 type => 'int'
 type => '{http://www.w3.org/2000/10/XMLSchema}int'
 type => qr/\}xml_/   # type start with xml_
 type => [ qw/int float/ ];

 use XML::Compile::Util qw/pack_type SCHEMA2000/;
 type => pack_type(SCHEMA2000, 'int')

=head3 hooks on matching ids

Matching based on IDs can reach more schema elements: some types are
anonymous but still have an ID.  Best is to base selection on the full
ID name, like C<ns#id>, to avoid all kinds of name-space conflicts in
the future.

example: use of the ID selector

 # default schema types have id's with same name
 id => 'int'
 id => 'http://www.w3.org/2001/XMLSchema#int'
 id => qr/\#xml_/   # id which start with xml_
 id => [ qw/int float/ ];

 use XML::Compile::Util qw/pack_id SCHEMA2001/;
 id => pack_id(SCHEMA2001, int)

=head3 hooks on matching paths

When you see error messages, you always see some representation of
the path where the problem was discovered.  You can use this path
as selector, when you know what it is... BE WARNED, that the current
structure of the path is not really consequent hence will be 
improved in one of the future releases, breaking backwards compatibility.

=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

=head1 SEE ALSO

This module is part of XML-Compile distribution version 0.76,
built on April 13, 2008. Website: F<http://perl.overmeer.net/xml-compile/>

=head1 LICENSE

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

