NAME

XML::Compile::Schema::Translate - create an XML data parser

SYNOPSIS

# for internal use only
my $code = XML::Compile::Schema::Translate->compileTree(...);

DESCRIPTION

This module converts a schema type definition into a code reference which can be used to interpret a schema. The sole public function in this package is compileTree(), and is called by XML::Compile::Schema::compile(), which does a lot of set-ups. Please do not try to use this package directly!

The code in this package interprets schemas; it understands, for instance, how complexType definitions work. Then, when the schema syntax is decoded, it will knot the pieces together into one CODE reference which can be used in the main user program.

Unsupported features

This implementation is work in progress, but most structures in W3C schema's are implemented.

Non-namespace schema elements are not implemented, because you shouldn't want that! Therefore, missing are schema noNamespaceSchemaLocation any ##local anyAttribute ##local

Some things do not work in schema's anyway: automatic import include

Used for indexing XML, not for our need: unique, keyref, selector, field

A few nuts are still to crack: any* processContents always interpreted as lax schema version element mixed facets on dates full understanding of patterns (now limited) final notation, annotation explicit ordering within choice and all

Of course, the latter list is all fixed in next release ;-) See chapter "DETAILS" for more on how the tune the translator.

METHODS

XML::Compile::Schema::Translate->compileTree(ELEMENT, OPTIONS)

Do not call this function yourself, but use XML::Compile::Schema::compile() (or wrappers around that).

This function returns a CODE reference, which can translate between Perl datastructures and XML, based on a schema. Before this method is called is the schema already translated into a table of types.

Option--Defined in     --Default
bricks                   <required>
err                      <required>
nss                      <required>

. bricks CLASS

. err CODE

. nss XML::Compile::Schema::NameSpaces

DETAILS

Translator options

performance optimization

The XML::Compile::Schema::compile() method (and wrappers) defines a set options to improve performance or usability. These options are translated into the executed code: compile time, not run-time!

The following options with their implications:

sloppy_integers BOOLEAN

The integer type, as defined by the schema built-in specification, accepts really huge values. Also the derived types, like nonNegativeInteger can contain much larger values than Perl's internal long. Therefore, the module will start to use Math::BigInt for these types if needed.

However, in most cases, people design integer where an int suffices. The use of big-int values comes with heigh performance costs. Set this option to true when you are sure that ALL USES of integer in the scheme will fit into signed longs (are between -2147483648 and 2147483647 inclusive)

check_occurs BOOLEAN

Checking whether the number of occurrences for an item are between minOccurs and maxOccurs (implied for all, sequence, and choice or explictly specified) takes time. Of course, in cases errors must be handled. When this option is set to false, only distinction between single and array elements is made.

ignore_facets BOOLEAN

Facets limit field content in the restriction block of a simpleType. When this option is true, no checks are performed on the values. In some cases, this may cause problems: especially with whiteSpace and digits of floats. However, you may be able to control this yourself. In most cases, luck even plays a part in this. Less checks means a better performance.

Simple type restrictions are not implemented by other XML perl modules. When the schema is nicely detailed, this will give extra security.

qualified XML

The produced XML may not use the name-spaces as defined by the schema's, just to simplify the input and output. The structural definition of the schema's is still in-tact, but name-space collission may appear.

Per schema, it can be specified whether the elements and attributes defined in-there need to be used qualified (with prefix) or not. This can cause horrible output when within an unqualified schema elements are used from an other schema which is qualified.

The suggested solution in articles about the subject is to provide people with both a schema which is qualified as one which is not. Perl is known to be blunt in its approach: we simply define a flag which can force one of both on all schema's together, using elements_qualified and attributes_qualified. May people and applications do not understand name-spaces sufficiently, and these options may make your day!

Name-spaces

The translator does respect name-spaces, but not all senders and receivers of XML are name-space capable. Therefore, you have some options to interfere.

output_namespaces HASH

The translator will create XML elements (WRITER) which use name-spaces, based on its own name-space/prefix mapping administration. This is needed because the XML tree is formed bottom-up, where XML::LibXML can only handle this top-down.

When your pass your own HASH as argument, you can explicitly specify the prefixes you like to be used for which name-space. Found name-spaces will be added to the hash, as well the use count. When a new name-space URI is discovered, an attempt is made to use the prefix as found in the schema. Prefix collisions are actively avoided: when two URIs want the same prefix, a sequence number is added to one of them which makes it unique.

include_namespaces BOOLEAN

When true and WRITER, the top level returned XML element will contain the prefix definitions. Only name-spaces which are actually used will be included (a count is kept by the translator). It may very well list name-spaces which are not in the actual output because the fields which require them are not included for there is not value for those fields.

If you like to combine XML output from separate translated parts (for instance in case of generating SOAP), you may want to delay the inclusion of name-spaces until a higher level of the XML hierarchy which is produced later.

namespace_reset BOOLEAN

You can pass the same HASH to a next call to a reader or writer to get consistent name-space usage. However, when include_namespaces is used, you may get ghost name-space listings. This option will reset the counts on all defined name-spaces.

Wildcards handlers

Wildcards are a serious complication: the any and anyAttribute entities do not describe exactly what can be found, which seriously hinders the quality of validation and the preparation of XML::Compile. Therefore, if you use them then you need to process that parts of XML yourself. See the various backends on how to create or process these elements.

anyElement CODE

This will be called when the type definition contains an any definition, after processing the other element components. By default, all any specifications will be ignored.

anyAttribute CODE|'TAKE_ALL'

This will be called when the type definitions contains an anyAttribute definition, after processing the other attributes. By default, all anyAttribute specifications will be ignored.

SEE ALSO

This module is part of XML-Compile distribution version 0.13, built on January 29, 2007. Website: http://perl.overmeer.net/xml-compile/

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

cpanm XML::Compile

perl -MCPAN -e shell
install XML::Compile