The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
XML-Compile-0.06
River stage two • 40 direct dependents • 68 total dependents
/ XML::Compile::Schema

NAME

XML::Compile::Schema - Compile a schema

INHERITANCE

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

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 => '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 => 'mytype');
 my $xml    = $write->($doc, $hash);

 # show result
 print $xml->toString;

DESCRIPTION

This module collects knowledge about one or more schemas. The most important method is compile() 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 compile method.

XML Reader

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.

XML Writer

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.

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 {url}name, for instance

 {http://library}book

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

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

as long as this ID refers to an element.

Representing data-structures

The schemas defines 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.

simpleType

A single value. A lot of single value data-types are built-in (see XML::Compile::Schema::BuiltInTypes). In XML, it looks like this:

 <test1>42</test1>

In the HASH structure, the data will be represented as

 test1 => 42

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.

complexType/simpleContent

In this case, the single value container may have attributes. In XML, this looks like this:

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

The number of attributes can be endless, and the value is only one. This value has no name, and therefore gets a predefined name _. As a HASH, this looks like

 test2 => { _ => 42, question => 'everything' }
complexType and complexType/complexContent

These containers not only have attributes, but also multiple values as content. 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' }

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.

usual case

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

maxOccurs larger than 1

In this case, the element can appear multiple times. The elements will be kept in an ARRAY within the HASH. So

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

will become

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

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

Non-schema based XML processors will not return a single value within an ARRAY, which makes the code more complicated.

An error will be produced when the number of elements found is less than minOccurs or more than maxOccurs.

use="optional" or minOccurs="0"

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

use="forbidden"

When the element is found, an error is produced.

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.

fixed="value"

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

List type

List simpleType objects are also represented as ARRAY, like elements with a minOccurs or maxOccurs unequal 1. An example with a list of ints:

  <test5>3 8 12</test5>

as Perl structure:

  test5 => [3, 8, 12]

METHODS

Constructors

$obj->new(TOP, OPTIONS)

Accessors

$obj->addSchemaDirs(DIRECTORIES)

$obj->addSchemas(NODE)

    Collect all the schemas defined below the NODE.

$obj->findSchemaFile(FILENAME)

$obj->importSchema(FILENAME|NAMESPACE)

    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 findSchemaFile().

$obj->namespaces

$obj->top

Filters

$obj->walkTree(NODE, CODE)

Compilers

$obj->compile(('READER'|'WRITER'), ELEMENT, OPTIONS)

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

    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>

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

    . check_occurs BOOLEAN

      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.

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

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

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

      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.

    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.

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

    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.

REFERENCES

See the XML::Compile website at http://perl.overmeer.net/xml-compile/ for more details.

COPYRIGHTS

Module version 0.06. 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.