XML::Compile::Schema - Compile a schema
XML::Compile::Schema is a XML::Compile
# preparation my $parser = XML::LibXML->new; my $tree = $parser->parse...(...); my $schema = XML::Compile::Schema->new($tree); my $schema = XML::Compile::Schema->new($xml_string); my $read = $schema->compile(READER => 'mytype'); my $hash = $read->($xml); my $doc = XML::LibXML::Document->new('1.0', 'UTF-8'); my $write = $schema->compile(WRITER => 'mytype'); my $xml = $write->($doc, $hash); print $xml->toString;
This module collects knowledge about a schema. The most important method is compile() which can create XML file readers and writers based on the schema information and some selected type.
WARNING: The compiler is implemented in XML::Compile::Schema::Translate, which is NOT FINISHED. See that manual page about the specific behavior and its (current) limitations! Please help to find missing pieces and mistakes.
WARNING: the provided schema is not validated! In some cases, compile-time and run-time errors will be reported, but typically only in cases that the parser has no idea what to do with such a mistake. On the other hand, the processed data is validated: the output should follow the specs closely.
Two implementations use the translator, and more can be added later. Both get created with the compile() method.
The XML reader produces a hash from a XML::LibXML::Node tree, or an XML string. The values are checked and will be ignored if the value is not according to the specs.
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.
$obj->new(TOP, OPTIONS)
See "Constructors" in XML::Compile
$obj->addSchemas(NODE)
Collect all the schemas defined below the NODE.
$obj->namespaces
Returns the XML::Compile::Schema::NameSpaces object which is used to collect schemas.
$obj->top
See "Accessors" in XML::Compile
$obj->walkTree(NODE, CODE)
See "Filters" in XML::Compile
$obj->compile(('READER'|'WRITER'), NAME, OPTIONS)
Translate the specified TYPE into a CODE reference which is able to translate between XML-text and a HASH.
The NAME 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 {url}name format, there the url is the name-space. An alternative is the url#id which refers to an element or type with the specific id attribute value.
{url}name
url#id
id
When a READER is created, a CODE reference is returned which needs to be called with parsed XML (an 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 XML::Compile::Schema::Translate.
-Option --Defined in --Default attributes_qualified <undef> check_occurs <true> 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>
false
. attributes_qualified BOOLEAN
When defined, this will overrule the attributeFormDefault flags in all schema's. When not qualified, the xml will not produce nor process prefixes on attributes.
attributeFormDefault
. check_occurs BOOLEAN
Whether code will be produced to complain about elements which should or should not appear, and is between bounds or not.
. check_values BOOLEAN
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.
. elements_qualified BOOLEAN
When defined, this will overrule the elementFormDefault flags in all schema's. When not qualified, the xml will not produce or process prefixes on the elements.
elementFormDefault
. ignore_facets BOOLEAN
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.
. include_namespaces BOOLEAN
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.
. invalid 'IGNORE','WARN','DIE',CODE
What to do in invalid values (ignored when not checking). See invalidsErrorHandler() who initiates this handler.
. namespace_reset BOOLEAN
Use the same prefixes in output_namespaces as with some other compiled piece, but reset the counts to zero first.
output_namespaces
. output_namespaces HASH
Can be used to predefine an output namespace (when 'WRITER') for instance to reserve common abbreviations like soap for external use. Each entry in the hash has as key the namespace uri. The value is a hash which contains uri, prefix, and used fields. Pass a reference to a private hash to catch this index.
soap
uri
prefix
used
. path STRING
Prepended to each error report, to indicate the location of the error in the XML-Scheme tree.
. sloppy_integers BOOLEAN
The decimal and 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 int type whould have sufficed, but the XML designer was lazy. A long is much faster to handle. Set this flag to use int as fast (but inprecise) replacements.
decimal
integer
int
Be aware that Math::BigInt and 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.
Math::BigInt
Math::BigFloat
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);
Example: create an XML writer
my $msgout = $rules->compile(WRITER => 'myns#mytype'); my $xml = $msgout->($hash); print $xml->toString;
$obj->elements
List all elements, defined by all schemas sorted alphabetically.
$obj->invalidsErrorHandler('IGNORE','USE'.'WARN','DIE',CODE)
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 invalid options of compile() which will call this method indirectly.
invalid
When IGNORE is specified, the process will ignore the specified value as if it was not specified at all. USE will not complain, and use the value found. With WARN, it will continue with the value but a warning is printed first. On DIE it will stop processing, as will the program (catch it with eval).
IGNORE
USE
WARN
DIE
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.
$obj->template(OPTIONS)
This method will try to produce a HASH template, to express how Perl's side of the data structure could look like. NOT IMPLEMENTED YET
$obj->types
List all types, defined by all schemas sorted alphabetically.
See the XML::Compile website at http://perl.overmeer.net/xml-compile/ for more details.
Module version 0.05. Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for other contributors.
Copyright (c) 2006 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install XML::Compile, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::Compile
CPAN shell
perl -MCPAN -e shell install XML::Compile
For more information on module installation, please visit the detailed CPAN module installation guide.