# for internal use only my $code = XML::Compile::Schema::Translate->compileTree(...);
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.
This implementation is work in progress, but by far most structures in W3C schemas are implemented (and tested!).
Missing are
schema noNamespaceSchemaLocation any ##local anyAttribute ##local
Some things do not work in schemas anyway: import
, include
. They
only work if everyone always has a working connection to internet. You
have to require them manually. Include also does work, because it does not
use namespaces. (see XML::Compile::Schema::importDefinitions())
Ignored, because not for our purpose is the search optimization
information: key, unique, keyref, selector, field
, and de schema
documentation: notation, annotation
. Compile the schema schema itself
to interpret the message if you need them.
A few nuts are still to crack:
any* processContents always interpreted as lax schema version openContent attribute limitiations (facets) on dates full understanding of patterns (now limited) final is not protected QName writer namespace to prefix translation
Of course, the latter list is all fixed in next release ;-) See chapter DETAILS for more on how the tune the translator.
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:
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)
If you do not want limit the number-space, you can safely add
use Math::BigInt try => 'GMP'to the top of your main program, and install Math::BigInt::GMP. Then, a C library will do the work, much faster than the Perl implementation.
Check the validity of the values, before parsing them. This will report errors for the reader, instead of crashes. The writer will not produce invalid data.
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.
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.
When used, it overrules the above check_values
, check_occurs
, and
ignore_facets
options. A true value enables all checks, a false
value will disable them all. Of course, the latter is the fastest but
also less secure: your program will need to validate the values in some
other way.
XML::LibXML has its own validate method, but I have not yet seen any performance figures on that. If you use it, however, it is of course a good idea to turn XML::Compile's validation off.
The produced XML may not use the name-spaces as defined by the schemas, just to simplify the input and output. The structural definition of the schemas 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 schemas together, using
elements_qualified
and attributes_qualified
. May people and
applications do not understand name-spaces sufficiently, and these
options may make your day!
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.
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.
The HASH structure looks like this:
my %namespaces = ( myns => { uri => 'myns', prefix => 'mypref', used => 1} , ... => { uri => ... } ); my $make = $schema->compile ( WRITER => ... , prefixes => \%namespaces ); # share the same namespace defs with an other component my $other = $schema->compile ( WRITER => ... , prefixes => \%namespaces );
When used is specified and larger than 0, then the namespace will
appear in the top-level output element (unless include_namespaces
is false).
Initializing using an ARRAY is a little simpler:
prefixes => [ mypref => 'myns', ... => ... ];
However, be warned that this does not work well with a false value
for include_namespaces
: detected namespaces are added to an
internal HASH now, which is not returned; that information is lost.
You will need to know each used namespace beforehand.
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.
include_namespaces
is
used, you may get ghost name-space listings. This option will reset
the counts on all defined name-spaces.
You may explicitly specify a blank prefix with prefixes
,
which will be used when applicable.
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.
any
definition, after processing the other element components. By
default, all any
specifications will be ignored.
anyAttribute
definition, after processing the other attributes.
By default, all anyAttribute
specifications will be ignored.