METHODS

See METHODS in XML::Compile

Constructors

See Constructors in XML::Compile

$class->new( [$xmldata], %options )

Details about many name-spaces can be organized with only a single schema object (actually, the data is administered in an internal XML::Compile::Schema::NameSpaces object)

The initial information is extracted from the $xmldata source. The $xmldata can be anything what is acceptable by importDefinitions(), which is everything accepted by dataToXML() or an ARRAY of those things. You may also add any OPTION accepted by addSchemas() to guide the understanding of the schema. When no $xmldata is provided, you can add it later with importDefinitions()

You can specify the hooks before you define the schemas the hooks work on: all schema information and all hooks are only used when the readers and writers get compiled.

Option Defined in Default

block_namespace

[]

hook

undef

hooks

[]

ignore_unused_tags

<false>

key_rewrite

[]

parser_options

XML::Compile

<many>

schema_dirs

XML::Compile

undef

typemap

{}

block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY
See blockNamespace()
hook => $hook|ARRAY
See addHook(). Adds one $hook (HASH) or more at once.
hooks => ARRAY
Add one or more hooks. See addHooks().
ignore_unused_tags => BOOLEAN|REGEXP
(WRITER) Usually, a mistake warning is produced when a user provides a data structure which contains more data than is needed for the XML message which is created; this will show structural problems. However, in some cases, you may want to play tricks with the data-structure and therefore disable this precausion.
With a REGEXP, you can have more control. Only keys which do match the expression will be ignored silently. Other keys (usually typos and other mistakes) will get reported. See Typemaps
key_rewrite => HASH|CODE|ARRAY
Translate XML element local-names into different Perl keys. See Key rewrite.
parser_options => HASH|ARRAY
schema_dirs => $directory|ARRAY-OF-directories
typemap => HASH
HASH of Schema type to Perl object or Perl class. See Typemaps, the serialization of objects.

Accessors

$obj->addHook( $hook|LIST|undef )

A $hook is specified as HASH or a LIST of PAIRS. When undef, this call is ignored. See addHooks() and Schema hooks below.

$obj->addHooks( $hook, [$hook, ...] )

Add multiple hooks at once. These must all be HASHes. See Schema hooks and addHook(). undef values are ignored.

$obj->addKeyRewrite( $predef|CODE|HASH, ... )

Add new rewrite rules to the existing list (initially provided with new(key_rewrite)). The whole list of rewrite rules is returned.

PREFIXED rules will be applied first. Special care is taken that the prefix will not be called twice. The last added set of rewrite rules will be applied first. See Key rewrite.

$obj->addSchemaDirs( @directories|$filename )
$class->addSchemaDirs( @directories|$filename )
See addSchemaDirs in XML::Compile.
$obj->addSchemas( $xml, %options )

Collect all the schemas defined in the $xml data. The $xml parameter must be a XML::LibXML node, therefore it is advised to use importDefinitions(), which has a much more flexible way to specify the data.

When the object extends XML::Compile::Cache, the prefixes declared on the schema element will be taken as default prefixes.

Option Default

attribute_form_default

<undef>

element_form_default

<undef>

filename

undef

source

undef

target_namespace

<undef>

attribute_form_default => 'qualified'|'unqualified'
element_form_default => 'qualified'|'unqualified'
Overrule the default as found in the schema. Many old schemas (like WSDL11 and SOAP11) do not specify the correct default element form in the schema but only in the text.
filename => FILENAME
Explicitly state from which file the data is coming.
source => STRING
An indication where this schema data was found. If you use dataToXML() in LIST context, you get such an indication.
target_namespace => NAMESPACE
Overrule (or set) the target namespace in the schema.
$obj->addTypemap( PAIR )

Synonym for addTypemap().

$obj->addTypemaps( PAIRS )

Add new XML-Perl type relations. See Typemaps.

$obj->blockNamespace( $ns|$type|HASH|CODE|ARRAY )

Block all references to a $ns or full $type, as if they do not appear in the schema. Specially useful if the schema includes references to old (deprecated) versions of itself which are not being used. It can also be used to block inclusion of huge structures which are not used, for increased compile performance, or to avoid buggy constructs.

These values can also be passed with new(block_namespace) and compile(block_namespace).

$obj->hooks( [<'READER'|'WRITER'>] )

Returns the LIST of defined hooks (as HASHes). [1.36] When an action parameter is provided, it will only return a list with hooks added with that action value or no action at all.

$obj->useSchema( $schema, [$schema, ...] )

Pass a XML::Compile::Schema object, or extensions like XML::Compile::Cache, to be used as definitions as well. First, elements are looked-up in the current schema definition object. If not found the other provided $schema objects are checked in the order as they were added.

Searches for definitions do not recurse into schemas which are used by the used schema.

» Example: use other Schema
  my $wsdl = XML::Compile::WSDL->new($wsdl);
  my $geo  = Geo::GML->new(version => '3.2.1');
  # both $wsdl and $geo extend XML::Compile::Schema

  $wsdl->useSchema($geo);

Compilers

$obj->compile( <'READER'|'WRITER'>, $type, %options )

Translate the specified ELEMENT (found in one of the read schemas) into a CODE reference which is able to translate between XML-text and a HASH. When the $type is undef, an empty LIST is returned.

The indicated $type is the starting-point for processing in the data-structure, a toplevel element or attribute name. 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 XML, as accepted by XML::Compile::dataToXML(). Returned is a nested HASH structure which contains the data from contained in the XML. The transformation rules are explained below.

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

Many %options below are explained in more detailed in the manual-page XML::Compile::Translate, which implements the compilation.

Option Default

abstract_types

'ERROR'

any_attribute

undef

any_element

undef

any_type

<returns string or node>

attributes_qualified

<undef>

block_namespace

[]

check_occurs

<true>

check_values

<true>

default_values

<depends on backend>

elements_qualified

<undef>

hook

undef

hooks

undef

ignore_facets

<false>

ignore_unused_tags

<false>

include_namespaces

<true>

interpret_nillable_as_optional

<false>

json_friendly

<false>

key_rewrite

[]

mixed_elements

'ATTRIBUTES'

namespace_reset

<false>

output_namespaces

undef

path

<expanded name of type>

permit_href

<false>

prefixes

{}

sloppy_floats

<false>

sloppy_integers

<false>

typemap

{}

use_default_namespace

<false>

validation

<true>

xsi_type

{}

xsi_type_everywhere

<false>

abstract_types => 'ERROR'|'ACCEPT'
How to handle the use abstract types. Of course, they should not be used, but sometime they accidentally are. When set to ERROR, an error will be produced whenever an abstract type is encountered. ACCEPT will ignore the fact that the types are abstract, and treat them as non-abstract types.
any_attribute => CODE|'TAKE_ALL'|'SKIP_ALL'
[0.89, reader] In general, anyAttribute schema components cannot be handled automatically. If you need to create or process anyAttribute information, then read about wildcards in the DETAILS chapter of the manual-page for the specific back-end. [pre-0.89] this option was named anyElement, which will still work.
any_element => CODE|'TAKE_ALL'|'SKIP_ALL'
[0.89, reader] In general, any schema components cannot be handled automatically. If you need to create or process any information, then read about wildcards in the DETAILS chapter of the manual-page for the specific back-end. [pre-0.89] this option was named anyElement, which will still work.
any_type => CODE
[1.07] how to handle "anyType" type elements. Supported values depends on the backend, specializations of XML::Compile::Translate.
attributes_qualified => ALL|NONE|BOOLEAN
[1.44] Like option elements_qualified, but then for attributes.
block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY
[reader] See blockNamespace().
check_occurs => BOOLEAN
Whether code will be produced to do bounds checking on elements and blocks which may appear more than once. When the schema says that maxOccurs is 1, then that element becomes optional. When the schema says that maxOccurs is larger than 1, then the output is still always an ARRAY, but now of unrestricted length.
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 speed significantly, but is (of course) much less safe. Do not set it off when you expect data from external sources: validation is a crucial requirement for XML.
default_values => 'MINIMAL'|'IGNORE'|'EXTEND'
[reader] How to treat default values as provided by the schema. With IGNORE (the writer default), you will see exactly what is specified in the XML or HASH. With EXTEND (the reader default) will show the default and fixed values in the result. MINIMAL does remove all fields which are the same as the default setting: simplifies. See Default Values.
elements_qualified => TOP|ALL|NONE|BOOLEAN
When defined, this will overrule the use of namespaces (as prefix) on elements in all schemas. When ALL or a true value is given, then all elements will be used qualified. When NONE or a false value is given, the XML will not produce or process prefixes on any element.
All top-level elements (and attributes) will be used in a name-space qualified way, if they have a targetNamespace. Some applications require some global element with qualification, so refuse global elements which have no qualification. Using the TOP setting, the compiler checks that the targetNamespace exists.
The form attributes in the schema will be respected; overrule the effects of this option. Use hooks when you need to fix name-space use in more subtile ways.
With element_form_default, you can correct whole schema's about their name-space behavior.
Change in [1.44]: TOP before enforced a name-space on the top-level. There should always be a name-space on the top element. It got changed into that TOP checks that the globals have a targetNamespace.
hook => $hook|ARRAY-OF-hooks
Define one or more processing $hooks. See Schema hooks below. These hooks are only active for this compiled entity, where addHook() and addHooks() can be used to define hooks which are used for all results of compile(). The hooks specified with the hook or hooks option are run before the global definitions.
hooks => $hook|ARRAY-OF-hooks
Alternative for option hook.
ignore_facets => BOOLEAN
Facets influence the formatting and range of values. This does not come cheap, so can be turned off. It affects the restrictions set for a simpleType. The processing speed will improve, but validation is a crucial requirement for XML: please do not turn this off when the data comes from external sources.
ignore_unused_tags => BOOLEAN|REGEXP
[writer] Overrules what is set with new(ignore_unused_tags).
include_namespaces => BOOLEAN|CODE
[writer] Indicates whether the namespace declaration should be included on the top-level element. If not, you may continue with the same name-space table to combine various XML components into one, and add the namespaces later. No namespace definition can be added the production rule produces an attribute.
When a CODE reference is passed, it will be called for each namespace to decide whether it should be included or not. When true, it will we added. The CODE is called with a namespace, its prefix, and the number of times it was used for that schema element translator.
interpret_nillable_as_optional => BOOLEAN
Found in the schema wild-life: people who think that nillable means optional. Not too hard to fix. For the WRITER, you still have to state NIL explicitly, but the elements are not constructed. The READER will output NIL when the nillable elements are missing.
json_friendly => BOOLEAN
[1.55] When enabled, booleans will be blessed in Types::Serializer booleans. Floats get nummified. Together, this will make the output of the reader usable as JSON without any further conversion.
key_rewrite => HASH|CODE|ARRAY
Add key rewrite rules to the front of the list of rules, as set by new(key_rewrite) and addKeyRewrite(). See Key rewrite
mixed_elements => CODE|PREDEFINED
[reader] What to do when mixed schema elements are to be processed. Read more in the DETAILS section below.
namespace_reset => BOOLEAN
[writer] Use the same prefixes in prefixes as with some other compiled piece, but reset the counts to zero first.
output_namespaces => HASH|ARRAY-of-PAIRS
[Pre-0.87] name for the prefixes option. Deprecated.
path => STRING
Prepended to each error report, to indicate the location of the error in the XML-Scheme tree.
permit_href => BOOLEAN
[reader] When parsing SOAP-RPC encoded messages, the elements may have a href attribute pointing to an object with id. The READER will return the unparsed, unresolved node when the attribute is detected, and the SOAP-RPC decoder will have to discover and resolve it.
prefixes => HASH|ARRAY-of-PAIRS
Can be used to pre-define prefixes for namespaces (for 'WRITER' or key rewrite) 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. An ARRAY with prefix, uri PAIRS is simpler.
 prefixes => [ mine => $myns, two => $twons ]
 prefixes => { $myns => 'mine', $twons => 'two' }

 # the previous is short for:
 prefixes => { $myns  => [ uri => $myns, prefix => 'mine', used => 0 ]
             , $twons => [ uri => $twons, prefix => 'two', ...] };
sloppy_floats => BOOLEAN
[reader] The float types of XML are all quite big, and support NaN, INF, and -INF. Perl's normal floats do not, and therefore Math::BigFloat is used. This, however, is slow. When true, you will crash on any value which is not understood by Perl's default float... but run much faster. See also sloppy_integers.
sloppy_integers => BOOLEAN
[reader] The XML integer data-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 transparently mimicking 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 differences are.
You can also improve the speed of Math::BigInt by installing Math::BigInt::GMP. Add < use Math::BigInt try = 'GMP'; >> to the top of your main script to get more performance.
typemap => HASH
Add this typemap to the relations defined by new(typemap) or addTypemaps()
use_default_namespace => BOOLEAN
[0.91, writer] When mixing qualified and unqualified namespaces, then the use of a default namespace can be quite confusing: a name-space without prefix. Therefore, by default, all qualified elements will have an explicit prefix.
validation => BOOLEAN
XML message must be validated, to lower the chance on abuse. However, of course, it costs performance which is only partially compensated by fewer checks in your code. This flag overrules the check_values, check_occurs, and ignore_facets.
xsi_type => HASH
See Handling xsi:type. The HASH maps types as mentioned in the schema, to extensions of those types which are addressed via the horrible xsi:type construct. When you specify AUTO as value for some type, the translator tries collect possible xsi:type values from the loaded schemas. This may be slow and may produce imperfect results.
xsi_type_everywhere => BOOLEAN
[1.48, writer] Add an xsi:type attribute to all elements, for instance as used in SOAP RPC/encoded. The type added is the type according to the schema, unless the xsi:type is already present on an element for some other reason.
Be aware that this option has a different purpose from xsi_type. In this case, we do add exactly the type specified in the xsd to each element which does not have an xsi:type attribute yet. The xsi_type on the other hand, implements the (mis-)feature that the element's content may get replaced by any extended type with this dynamic flag.
$obj->compileType( <'READER'|'WRITER'>, $type, %options )

This is a hack to be able to process components of SOAP messages, which are only specified by type. Probably (hopefully) you do no need it. All %options are the same as for compile().

$obj->dataToXML( $node|REF-XML|XML-STRING|$filename|$fh|$known )
$class->dataToXML( $node|REF-XML|XML-STRING|$filename|$fh|$known )
See dataToXML in XML::Compile.
$obj->initParser( %options )
$class->initParser( %options )
See initParser in XML::Compile.
$obj->template( <'XML'|'PERL'|'TREE'>, $element, %options )

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 $element shown as XML or Perl is organized in practice.

The 'TREE' template returns the intermediate parse tree, which gets formatted into the XML or Perl example. This is not a very stable interface: it may change without much notice.

Some %options are explained in XML::Compile::Translate. There are some extra %options defined for the final output process.

The templates produced are not always correct. Please contribute improvements: read and understand the comments in the text.

Option Default

abstract_types

'ERROR'

attributes_qualified

<undef>

elements_qualified

<undef>

include_namespaces

<true>

indent

" "

key_rewrite

[]

show_comments

ALL

skip_header

<false>

abstract_types => 'ERROR'|'ACCEPT'
By default, do not show abstract types in the output.
attributes_qualified => BOOLEAN
elements_qualified => 'ALL'|'TOP'|'NONE'|BOOLEAN
include_namespaces => BOOLEAN|CODE
indent => STRING
The leading indentation string per nesting. Must start with at least one blank.
key_rewrite => HASH|CODE|ARRAY
show_comments => STRING|'ALL'|'NONE'
A comma separated list of tokens, which explain what kind of comments need to be included in the output. The available tokens are: struct, type, occur, facets. A value of ALL will select all available comments. The NONE or empty string will exclude all comments.
skip_header => BOOLEAN
Skip the comment header from the output.

Administration

$obj->doesExtend( $exttype, $basetype )

Returns true when the $exttype extends the $basetype. See XML::Compile::Schema::NameSpaces::doesExtend()

$obj->elements

List all elements, defined by all schemas sorted alphabetically.

$obj->findSchemaFile( $filename )
$class->findSchemaFile( $filename )
See findSchemaFile in XML::Compile.
$obj->importDefinitions( $xmldata, %options )

Import (include) the schema information included in the $xmldata. The $xmldata must be acceptable for dataToXML(). The resulting node and all the %options are passed to addSchemas(). The schema node does not need to be the top element: any schema node found in the data will be decoded.

Returned is a list of XML::Compile::Schema::Instance objects, for each processed schema component.

If your program imports the same string or file definitions multiple times, it will re-use the schema information from the first import. This removal of dupplications will not work for open files or pre-parsed XML structures.

As an extension to the handling dataToXML() provides, you can specify an ARRAY of things which are acceptable to dataToXML. This way, you can specify multiple resources at once, each of which will be processed with the same %options.

Option Default

details

<from XMLDATA>

details => HASH
Overrule the details information about the source of the data.
» Example: of use of importDefinitions
  my $schema = XML::Compile::Schema->new;
  $schema->importDefinitions('my-spec.xsd');

  my $other = "<schema>...</schema>";  # use 'HERE' documents!
  my @specs = ('my-spec.xsd', 'types.xsd', $other);
  $schema->importDefinitions(\@specs, @options);
$obj->knownNamespace( $ns|PAIRS )
$class->knownNamespace( $ns|PAIRS )
See knownNamespace in XML::Compile.
$obj->namespaces

Returns the XML::Compile::Schema::NameSpaces object which is used to collect schemas.

$obj->printIndex( [$fh], %options )

Print all the elements which are defined in the schemas to the $fh (by default the selected handle). %options are passed to XML::Compile::Schema::NameSpaces::printIndex() and XML::Compile::Schema::Instance::printIndex().

$obj->types

List all types, defined by all schemas sorted alphabetically.

$obj->walkTree( $node, CODE )
See walkTree in XML::Compile.