=head1 NAME

XML::Compile::Schema - Compile a schema

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

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

 # create and use a reader
 my $read   = $schema->compile(READER => '{myns}mytype');
 my $hash   = $read->($xml);
 
 # 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);

 # show result
 print $xml->toString;

=head1 DESCRIPTION

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

Two implementations use the translator, and more can be added later.  Both
get created with the C<compile> method.

=over 4

=item READER (translate 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.

I<Example:> create an XML reader

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

or

 my $hash   = $msgin->($xml_string);

=item WRITER (translate HASH to XML)

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

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

=back

Be warned that the schema itself is NOT VALIDATED; you can easily
construct schema's which do work with this module, but are not
valid according to W3C.  Only in some cases, the translater will
refuse to accept mistakes: mainly because it cannot produce valid
code.

See chapter L</DETAILS> and learn how the data is processed.

=head1 METHODS

=head2 Constructors

$obj-E<gt>B<new>(TOP, OPTIONS)

=over 4

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

=back

=head2 Accessors

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

=over 4

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

=back

$obj-E<gt>B<addSchemas>(NODE|TEXT)

=over 4

Collect all the schemas defined below the NODE.

=back

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

=over 4

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

=back

$obj-E<gt>B<importSchema>(FILENAME|NAMESPACE)

=over 4

Import (parse) the XML found in the specified file.  Some NAMESPACES
are linked to predefined filenames, especially the schema defining files.
The FILENAME can be relative, see L<findSchemaFile()|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

$obj-E<gt>B<top>

=over 4

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

=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'), ELEMENT, OPTIONS)

=over 4

Translate the specified ELEMENT into a CODE reference which is able to
translate between XML-text and a HASH.

The ELEMENT is the starting-point for processing in the data-structure.
It can either be a global element, or a global type.  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 parsed XML (an L<XML::LibXML::Node>) or an XML text.
Returned is a nested HASH structure which contains the data from
contained in the XML.  When a simple element type is addressed, you
will get a single value back,

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

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

 Option              --Defined in     --Default
 attributes_qualified                   <undef>
 check_occurs                           <false>
 check_values                           <true>
 elements_qualified                     <undef>
 ignore_facets                          <false>
 include_namespaces                     <true>
 invalid                                DIE
 namespace_reset                        <false>
 output_namespaces                      {}
 path                                   <expanded name of type>
 sloppy_integers                        <false>

. attributes_qualified BOOLEAN

=over 4

When defined, this will overrule the C<attributeFormDefault> flags in
all schema's.  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 complain about elements which
should or should not appear, and is between bounds or not.
Elements which may have more than 1 occurence will still always
be represented by an ARRAY.

=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 significantly, but is
(of course) much less unsafer.  Do not set it off when you expect
data from external sources.

=back

. elements_qualified BOOLEAN

=over 4

When defined, this will overrule the C<elementFormDefault> flags in
all schema's.  When not qualified, the xml will not produce or
process prefixes on the elements.

=back

. ignore_facets BOOLEAN

=over 4

Facets influence the formatting and range of values. This does
not come cheap, so can be turned off.  Affects the restrictions
set for a simpleType.

=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

. invalid 'IGNORE','WARN','DIE',CODE

=over 4

What to do in invalid values (ignored when not checking). See
L<invalidsErrorHandler()|XML::Compile::Schema/"Compilers"> who initiates this handler.

=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

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

=back

. path STRING

=over 4

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

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

=back

=back

$obj-E<gt>B<elements>

=over 4

List all elements, defined by all schemas sorted alphabetically.

=back

$obj-E<gt>B<invalidsErrorHandler>('IGNORE','USE'.'WARN','DIE',CODE)

=over 4

What to do when a validation error appears during validation?  This method
translates all string options into a single code reference which is
returned.  Please use the C<invalid> options of L<compile()|XML::Compile::Schema/"Compilers">
which will call this method indirectly.

When C<IGNORE> is specified, the process will ignore the specified
value as if it was not specified at all.  C<USE> will not complain,
and use the value found. With C<WARN>, it will continue with the value
but a warning is printed first.  On C<DIE> it will stop processing,
as will the program (catch it with C<eval>).

When a CODE reference is specified, that will be called specifying
the type path, actual type expected (expanded name), the errorneous
value, and an error string.

=back

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

=over 4

WARNING: under development!  The implementation is far from complete.

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.

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

. attributes_qualified BOOLEAN

. elements_qualified 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 Addressing components

Normally, external users can only address elements within a schema,
and types are hidden to be used by other schema's 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<{url}name>, for instance

 {http://library}book

refers to the built-in C<int> data-type.  You may also start with

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

as long as this ID refers to an element.

Wildcard elements C<any> and C<anyAttribute> elements frustrate our
attempt for simplification.  Where we normally know which name-space
we are dealing with, these wildcard elements can use any name-space.
Therefore, in the HASH, these elements will use keys like C<{url}name>,
in stead of simply the 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.

I<Example:> typical simpleType

In XML, it looks like this:

 <test1>42</test1>

In the HASH structure, the data will be represented as

 test1 => 42

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

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

I<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' }

=back

=head2 Processing elements

A second factor which determines the data-structure is the element
occurence.  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 can appear multiple times.  Multiple values will
be kept in an ARRAY within the HASH.  Non-schema based XML processors
will not return a single value as an ARRAY, which makes that code more
complicated.

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

I<Example:> two values for C<a>

 <test4><a>12</a><a>13</a><b>14</b></test4>

will become

 test4 => { a => [12, 13], b => 14 };

I<Example:> always an array

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}} ) {...}

=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 List type

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

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

I<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}

=head1 SEE ALSO

This module is part of XML-Compile distribution version 0.12,
built on December 19, 2006. Website: F<http://perl.overmeer.net/xml-compile/>

=head1 LICENSE

Copyrights 2006 by Mark Overmeer. For 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>

