.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "XML::Compile::Schema 3pm" .TH XML::Compile::Schema 3pm "2022-11-27" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" XML::Compile::Schema \- Compile a schema into CODE .SH "INHERITANCE" .IX Header "INHERITANCE" .Vb 2 \& XML::Compile::Schema \& is a XML::Compile \& \& XML::Compile::Schema is extended by \& XML::Compile::Cache .Ve .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& # 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); \& \& # get schema from file (most used) \& my $schema = XML::Compile::Schema\->new($filename); \& my $schema = XML::Compile::Schema\->new([glob "*.xsd"]); \& \& # the "::Cache" extension has more power \& my $schema = XML::Compile::Cache\->new(\e@xsdfiles); \& \& # adding more schemas, from parsed XML \& $schema\->addSchemas($tree); \& \& # adding more schemas from files \& # three times the same: well\-known url, filename in schemadir, url \& # Just as example: usually not needed. \& $schema\->importDefinitions(\*(Aqhttp://www.w3.org/2001/XMLSchema\*(Aq); \& $schema\->importDefinitions(\*(Aq2001\-XMLSchema.xsd\*(Aq); \& $schema\->importDefinitions(SCHEMA2001); # from ::Util \& \& # alternatively \& my @specs = (\*(Aqone.xsd\*(Aq, \*(Aqtwo.xsd\*(Aq, $schema_as_string); \& my $schema = XML::Compile::Schema\->new(\e@specs); # ARRAY! \& \& # see what types are defined \& $schema\->printIndex; \& \& # create and use a reader \& use XML::Compile::Util qw/pack_type/; \& my $elem = pack_type \*(Aqmy\-namespace\*(Aq, \*(Aqmy\-local\-name\*(Aq; \& # $elem eq "{my\-namespace}my\-local\-name" \& my $read = $schema\->compile(READER => $elem); \& my $data = $read\->($xmlnode); \& my $data = $read\->("filename.xml"); \& \& # when you do not know the element type beforehand \& use XML::Compile::Util qw/type_of_node/; \& my $elem = type_of_node $xml\->documentElement; \& my $reader = $reader_cache{$type} # either exists \& ||= $schema\->compile(READER => $elem); # or create \& my $data = $reader\->($xmlmsg); \& \& # create and use a writer \& my $doc = XML::LibXML::Document\->new(\*(Aq1.0\*(Aq, \*(AqUTF\-8\*(Aq); \& my $write = $schema\->compile(WRITER => \*(Aq{myns}mytype\*(Aq); \& my $xml = $write\->($doc, $hash); \& $doc\->setDocumentElement($xml); \& \& # show result \& print $doc\->toString(1); \& \& # to create the type nicely \& use XML::Compile::Util qw/pack_type/; \& my $type = pack_type \*(Aqmyns\*(Aq, \*(Aqmytype\*(Aq; \& print $type; # shows {myns}mytype \& \& # using a compiled routines cache \& use XML::Compile::Cache; # separate distribution \& my $schema = XML::Compile::Cache\->new(...); \& \& # Show which data\-structure is expected \& print $schema\->template(PERL => $type); \& \& # Error handling tricks with Log::Report \& use Log::Report mode => \*(AqDEBUG\*(Aq; # enable debugging \& dispatcher SYSLOG => \*(Aqsyslog\*(Aq; # errors to syslog as well \& try { $reader\->($data) }; # catch errors in $@ .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module collects knowledge about one or more schemas. The most important method provided is \fBcompile()\fR, which can create \s-1XML\s0 file readers and writers based on the schema information and some selected element or attribute type. .PP Various implementations use the translator, and more can be added later: .ie n .IP """$schema\->compile(\*(AqREADER\*(Aq...)"" translates \s-1XML\s0 to \s-1HASH\s0" 4 .el .IP "\f(CW$schema\->compile(\*(AqREADER\*(Aq...)\fR translates \s-1XML\s0 to \s-1HASH\s0" 4 .IX Item "$schema->compile(READER...) translates XML to HASH" The \s-1XML\s0 reader produces a \s-1HASH\s0 from a XML::LibXML::Node tree or an \&\s-1XML\s0 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. .Sp The \s-1CODE\s0 reference which is returned can be called with anything accepted by \fBdataToXML()\fR. .Sp Example: create an \s-1XML\s0 reader .Sp .Vb 4 \& my $msgin = $rules\->compile(READER => \*(Aq{myns}mytype\*(Aq); \& # or ... = $rules\->compile(READER => pack_type(\*(Aqmyns\*(Aq, \*(Aqmytype\*(Aq)); \& my $xml = $parser\->parse("some\-xml.xml"); \& my $hash = $msgin\->($xml); .Ve .Sp or .Sp .Vb 3 \& my $hash = $msgin\->(\*(Aqsome\-xml.xml\*(Aq); \& my $hash = $msgin\->($xml_string); \& my $hash = $msgin\->($xml_node); .Ve .Sp with XML::Compile::Cache as schema object: .Sp .Vb 2 \& $rules\->addPrefix(m => \*(Aqmyns\*(Aq); \& my $hash = $rules\->reader(\*(Aqm:mytype\*(Aq)\->($xml); .Ve .ie n .IP """$schema\->compile(\*(AqWRITER\*(Aq, ...)"" translates \s-1HASH\s0 to \s-1XML\s0" 4 .el .IP "\f(CW$schema\->compile(\*(AqWRITER\*(Aq, ...)\fR translates \s-1HASH\s0 to \s-1XML\s0" 4 .IX Item "$schema->compile(WRITER, ...) translates HASH to XML" The writer produces schema compliant \s-1XML,\s0 based on a Perl \s-1HASH.\s0 To get the data encoding correctly, you are required to pass a document object in which the \s-1XML\s0 nodes may get a place later. .Sp Create an \s-1XML\s0 writer .Sp .Vb 4 \& my $doc = XML::LibXML::Document\->new(\*(Aq1.0\*(Aq, \*(AqUTF\-8\*(Aq); \& my $write = $schema\->compile(WRITER => \*(Aq{myns}mytype\*(Aq); \& my $xml = $write\->($doc, $hash); \& print $xml\->toString; .Ve .Sp alternative .Sp .Vb 1 \& my $write = $schema\->compile(WRITER => \*(Aqmyns#myid\*(Aq); .Ve .Sp with XML::Compile::Cache as schema object: .Sp .Vb 2 \& $rules\->addPrefix(m => \*(Aqmyns\*(Aq); \& my $xml = $rules\->writer(\*(Aqm:mytype\*(Aq)\->($doc, $hash); .Ve .ie n .IP """$schema\->template(\*(AqXML\*(Aq, ...)"" creates an \s-1XML\s0 example" 4 .el .IP "\f(CW$schema\->template(\*(AqXML\*(Aq, ...)\fR creates an \s-1XML\s0 example" 4 .IX Item "$schema->template(XML, ...) creates an XML example" Based on the schema, this produces an \s-1XML\s0 message as example. Schemas are usually so complex that people loose overview. This example may put you back on track, and used as starting point for many creating the \&\s-1XML\s0 version of the message. .ie n .IP """$schema\->template(\*(AqPERL\*(Aq, ...)"" creates an Perl example" 4 .el .IP "\f(CW$schema\->template(\*(AqPERL\*(Aq, ...)\fR creates an Perl example" 4 .IX Item "$schema->template(PERL, ...) creates an Perl example" Based on the schema, this produces an Perl \s-1HASH\s0 structure (a bit like the output by Data::Dumper), which can be used as template for creating messages. The output contains documentation, and is usually much clearer than the schema itself. .ie n .IP """$schema\->template(\*(AqTREE\*(Aq, ...)"" creates a parse tree" 4 .el .IP "\f(CW$schema\->template(\*(AqTREE\*(Aq, ...)\fR creates a parse tree" 4 .IX Item "$schema->template(TREE, ...) creates a parse tree" To be able to produce Perl-text and \s-1XML\s0 examples, the templater generates an abstract tree from the schema. That tree is returned here. Be warned that the structure is not fixed over releases: add regression tests for this to your project. .PP Be warned that the \fBschema is not validated\fR; you can develop schemas which do work well with this module, but are not valid according to W3C. In many cases, however, the translater will refuse to accept mistakes: mainly because it cannot produce valid code. .PP The values (both for reading as for writing) are strictly validated. However, the reader is sloppy with unexpected attributes, and many other things: that's too expensive to check. .PP Extends \*(L"\s-1DESCRIPTION\*(R"\s0 in XML::Compile. .SH "METHODS" .IX Header "METHODS" Extends \*(L"\s-1METHODS\*(R"\s0 in XML::Compile. .SS "Constructors" .IX Subsection "Constructors" Extends \*(L"Constructors\*(R" in XML::Compile. .ie n .IP "XML::Compile::Schema\->\fBnew\fR( [$xmldata], %options )" 4 .el .IP "XML::Compile::Schema\->\fBnew\fR( [$xmldata], \f(CW%options\fR )" 4 .IX Item "XML::Compile::Schema->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) .Sp The initial information is extracted from the \f(CW$xmldata\fR source. The \f(CW$xmldata\fR can be anything what is acceptable by \fBimportDefinitions()\fR, which is everything accepted by \fBdataToXML()\fR or an \s-1ARRAY\s0 of those things. You may also add any \s-1OPTION\s0 accepted by \fBaddSchemas()\fR to guide the understanding of the schema. When no \f(CW$xmldata\fR is provided, you can add it later with \fBimportDefinitions()\fR .Sp 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. .Sp .Vb 9 \& \-Option \-\-Defined in \-\-Default \& block_namespace [] \& hook undef \& hooks [] \& ignore_unused_tags \& key_rewrite [] \& parser_options XML::Compile \& schema_dirs XML::Compile undef \& typemap {} .Ve .RS 4 .IP "block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY" 2 .IX Item "block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY" See \fBblockNamespace()\fR .ie n .IP "hook => $hook|ARRAY" 2 .el .IP "hook => \f(CW$hook\fR|ARRAY" 2 .IX Item "hook => $hook|ARRAY" See \fBaddHook()\fR. Adds one \f(CW$hook\fR (\s-1HASH\s0) or more at once. .IP "hooks => \s-1ARRAY\s0" 2 .IX Item "hooks => ARRAY" Add one or more hooks. See \fBaddHooks()\fR. .IP "ignore_unused_tags => BOOLEAN|REGEXP" 2 .IX Item "ignore_unused_tags => BOOLEAN|REGEXP" (\s-1WRITER\s0) Usually, a \f(CW\*(C`mistake\*(C'\fR warning is produced when a user provides a data structure which contains more data than is needed for the \s-1XML\s0 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. .Sp With a \s-1REGEXP,\s0 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 \*(L"Typemaps\*(R" .IP "key_rewrite => HASH|CODE|ARRAY" 2 .IX Item "key_rewrite => HASH|CODE|ARRAY" Translate \s-1XML\s0 element local-names into different Perl keys. See \*(L"Key rewrite\*(R". .IP "parser_options => HASH|ARRAY" 2 .IX Item "parser_options => HASH|ARRAY" .PD 0 .ie n .IP "schema_dirs => $directory|ARRAY\-OF\-directories" 2 .el .IP "schema_dirs => \f(CW$directory\fR|ARRAY\-OF\-directories" 2 .IX Item "schema_dirs => $directory|ARRAY-OF-directories" .IP "typemap => \s-1HASH\s0" 2 .IX Item "typemap => HASH" .PD \&\s-1HASH\s0 of Schema type to Perl object or Perl class. See \*(L"Typemaps\*(R", the serialization of objects. .RE .RS 4 .RE .SS "Accessors" .IX Subsection "Accessors" Extends \*(L"Accessors\*(R" in XML::Compile. .ie n .IP "$obj\->\fBaddHook\fR($hook|LIST|undef)" 4 .el .IP "\f(CW$obj\fR\->\fBaddHook\fR($hook|LIST|undef)" 4 .IX Item "$obj->addHook($hook|LIST|undef)" A \f(CW$hook\fR is specified as \s-1HASH\s0 or a \s-1LIST\s0 of \s-1PAIRS.\s0 When \f(CW\*(C`undef\*(C'\fR, this call is ignored. See \fBaddHooks()\fR and \*(L"Schema hooks\*(R" below. .ie n .IP "$obj\->\fBaddHooks\fR( $hook, [$hook, ...] )" 4 .el .IP "\f(CW$obj\fR\->\fBaddHooks\fR( \f(CW$hook\fR, [$hook, ...] )" 4 .IX Item "$obj->addHooks( $hook, [$hook, ...] )" Add multiple hooks at once. These must all be HASHes. See \*(L"Schema hooks\*(R" and \fBaddHook()\fR. \f(CW\*(C`undef\*(C'\fR values are ignored. .ie n .IP "$obj\->\fBaddKeyRewrite\fR($predef|CODE|HASH, ...)" 4 .el .IP "\f(CW$obj\fR\->\fBaddKeyRewrite\fR($predef|CODE|HASH, ...)" 4 .IX Item "$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. .Sp \&\f(CW\*(C`PREFIXED\*(C'\fR 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 \*(L"Key rewrite\*(R". .ie n .IP "$obj\->\fBaddSchemaDirs\fR(@directories|$filename)" 4 .el .IP "\f(CW$obj\fR\->\fBaddSchemaDirs\fR(@directories|$filename)" 4 .IX Item "$obj->addSchemaDirs(@directories|$filename)" .PD 0 .IP "XML::Compile::Schema\->\fBaddSchemaDirs\fR(@directories|$filename)" 4 .IX Item "XML::Compile::Schema->addSchemaDirs(@directories|$filename)" .PD Inherited, see \*(L"Accessors\*(R" in XML::Compile .ie n .IP "$obj\->\fBaddSchemas\fR($xml, %options)" 4 .el .IP "\f(CW$obj\fR\->\fBaddSchemas\fR($xml, \f(CW%options\fR)" 4 .IX Item "$obj->addSchemas($xml, %options)" Collect all the schemas defined in the \f(CW$xml\fR data. The \f(CW$xml\fR parameter must be a XML::LibXML node, therefore it is advised to use \&\fBimportDefinitions()\fR, which has a much more flexible way to specify the data. .Sp When the object extends XML::Compile::Cache, the prefixes declared on the schema element will be taken as default prefixes. .Sp .Vb 6 \& \-Option \-\-Default \& attribute_form_default \& element_form_default \& filename undef \& source undef \& target_namespace .Ve .RS 4 .IP "attribute_form_default => 'qualified'|'unqualified'" 2 .IX Item "attribute_form_default => 'qualified'|'unqualified'" .PD 0 .IP "element_form_default => 'qualified'|'unqualified'" 2 .IX Item "element_form_default => 'qualified'|'unqualified'" .PD Overrule the default as found in the schema. Many old schemas (like \&\s-1WSDL11\s0 and \s-1SOAP11\s0) do not specify the correct default element form in the schema but only in the text. .IP "filename => \s-1FILENAME\s0" 2 .IX Item "filename => FILENAME" Explicitly state from which file the data is coming. .IP "source => \s-1STRING\s0" 2 .IX Item "source => STRING" An indication where this schema data was found. If you use \fBdataToXML()\fR in \s-1LIST\s0 context, you get such an indication. .IP "target_namespace => \s-1NAMESPACE\s0" 2 .IX Item "target_namespace => NAMESPACE" Overrule (or set) the target namespace in the schema. .RE .RS 4 .RE .ie n .IP "$obj\->\fBaddTypemap\fR(\s-1PAIR\s0)" 4 .el .IP "\f(CW$obj\fR\->\fBaddTypemap\fR(\s-1PAIR\s0)" 4 .IX Item "$obj->addTypemap(PAIR)" Synonym for \fBaddTypemap()\fR. .ie n .IP "$obj\->\fBaddTypemaps\fR(\s-1PAIRS\s0)" 4 .el .IP "\f(CW$obj\fR\->\fBaddTypemaps\fR(\s-1PAIRS\s0)" 4 .IX Item "$obj->addTypemaps(PAIRS)" Add new XML-Perl type relations. See \*(L"Typemaps\*(R". .ie n .IP "$obj\->\fBblockNamespace\fR($ns|$type|HASH|CODE|ARRAY)" 4 .el .IP "\f(CW$obj\fR\->\fBblockNamespace\fR($ns|$type|HASH|CODE|ARRAY)" 4 .IX Item "$obj->blockNamespace($ns|$type|HASH|CODE|ARRAY)" Block all references to a \f(CW$ns\fR or full \f(CW$type\fR, 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. .Sp These values can also be passed with new(block_namespace) and compile(block_namespace). .ie n .IP "$obj\->\fBhooks\fR( [<'\s-1READER\s0'|'\s-1WRITER\s0'>] )" 4 .el .IP "\f(CW$obj\fR\->\fBhooks\fR( [<'\s-1READER\s0'|'\s-1WRITER\s0'>] )" 4 .IX Item "$obj->hooks( [<'READER'|'WRITER'>] )" Returns the \s-1LIST\s0 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. .ie n .IP "$obj\->\fBuseSchema\fR( $schema, [$schema, ...] )" 4 .el .IP "\f(CW$obj\fR\->\fBuseSchema\fR( \f(CW$schema\fR, [$schema, ...] )" 4 .IX Item "$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 \f(CW$schema\fR objects are checked in the order as they were added. .Sp Searches for definitions do not recurse into schemas which are used by the used schema. .Sp example: use other Schema .Sp .Vb 3 \& my $wsdl = XML::Compile::WSDL\->new($wsdl); \& my $geo = Geo::GML\->new(version => \*(Aq3.2.1\*(Aq); \& # both $wsdl and $geo extend XML::Compile::Schema \& \& $wsdl\->useSchema($geo); .Ve .SS "Compilers" .IX Subsection "Compilers" Extends \*(L"Compilers\*(R" in XML::Compile. .ie n .IP "$obj\->\fBcompile\fR( <'\s-1READER\s0'|'\s-1WRITER\s0'>, $type, %options )" 4 .el .IP "\f(CW$obj\fR\->\fBcompile\fR( <'\s-1READER\s0'|'\s-1WRITER\s0'>, \f(CW$type\fR, \f(CW%options\fR )" 4 .IX Item "$obj->compile( <'READER'|'WRITER'>, $type, %options )" Translate the specified \s-1ELEMENT\s0 (found in one of the read schemas) into a \s-1CODE\s0 reference which is able to translate between XML-text and a \s-1HASH.\s0 When the \f(CW$type\fR is \f(CW\*(C`undef\*(C'\fR, an empty \s-1LIST\s0 is returned. .Sp The indicated \f(CW$type\fR is the starting-point for processing in the data-structure, a toplevel element or attribute name. The name must be specified in \f(CW\*(C`{url}name\*(C'\fR format, there the url is the name-space. An alternative is the \f(CW\*(C`url#id\*(C'\fR which refers to an element or type with the specific \f(CW\*(C`id\*(C'\fR attribute value. .Sp When a \s-1READER\s0 is created, a \s-1CODE\s0 reference is returned which needs to be called with \s-1XML,\s0 as accepted by \fBXML::Compile::dataToXML()\fR. Returned is a nested \s-1HASH\s0 structure which contains the data from contained in the \s-1XML.\s0 The transformation rules are explained below. .Sp When a \s-1WRITER\s0 is created, a \s-1CODE\s0 reference is returned which needs to be called with an XML::LibXML::Document object and a \s-1HASH,\s0 and returns a XML::LibXML::Node. .Sp Many \f(CW%options\fR below are \fBexplained in more detailed\fR in the manual-page XML::Compile::Translate, which implements the compilation. .Sp .Vb 10 \& \-Option \-\-Default \& abstract_types \*(AqERROR\*(Aq \& any_attribute undef \& any_element undef \& any_type \& attributes_qualified \& block_namespace [] \& check_occurs \& check_values \& default_values \& elements_qualified \& hook undef \& hooks undef \& ignore_facets \& ignore_unused_tags \& include_namespaces \& interpret_nillable_as_optional \& json_friendly \& key_rewrite [] \& mixed_elements \*(AqATTRIBUTES\*(Aq \& namespace_reset \& output_namespaces undef \& path \& permit_href \& prefixes {} \& sloppy_floats \& sloppy_integers \& typemap {} \& use_default_namespace \& validation \& xsi_type {} \& xsi_type_everywhere .Ve .RS 4 .IP "abstract_types => '\s-1ERROR\s0'|'\s-1ACCEPT\s0'" 2 .IX Item "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 \f(CW\*(C`ERROR\*(C'\fR, an error will be produced whenever an abstract type is encountered. \&\f(CW\*(C`ACCEPT\*(C'\fR will ignore the fact that the types are abstract, and treat them as non-abstract types. .IP "any_attribute => CODE|'\s-1TAKE_ALL\s0'|'\s-1SKIP_ALL\s0'" 2 .IX Item "any_attribute => CODE|'TAKE_ALL'|'SKIP_ALL'" [0.89, reader] In general, \f(CW\*(C`anyAttribute\*(C'\fR schema components cannot be handled automatically. If you need to create or process anyAttribute information, then read about wildcards in the \s-1DETAILS\s0 chapter of the manual-page for the specific back-end. [pre\-0.89] this option was named \f(CW\*(C`anyElement\*(C'\fR, which will still work. .IP "any_element => CODE|'\s-1TAKE_ALL\s0'|'\s-1SKIP_ALL\s0'" 2 .IX Item "any_element => CODE|'TAKE_ALL'|'SKIP_ALL'" [0.89, reader] In general, \f(CW\*(C`any\*(C'\fR schema components cannot be handled automatically. If you need to create or process any information, then read about wildcards in the \s-1DETAILS\s0 chapter of the manual-page for the specific back-end. [pre\-0.89] this option was named \f(CW\*(C`anyElement\*(C'\fR, which will still work. .IP "any_type => \s-1CODE\s0" 2 .IX Item "any_type => CODE" [1.07] how to handle \*(L"anyType\*(R" type elements. Supported values depends on the backend, specializations of XML::Compile::Translate. .ie n .IP "attributes_qualified => ""ALL""|""NONE""|BOOLEAN" 2 .el .IP "attributes_qualified => \f(CWALL\fR|\f(CWNONE\fR|BOOLEAN" 2 .IX Item "attributes_qualified => ALL|NONE|BOOLEAN" [1.44] Like option \f(CW\*(C`elements_qualified\*(C'\fR, but then for attributes. .IP "block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY" 2 .IX Item "block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY" [reader] See \fBblockNamespace()\fR. .IP "check_occurs => \s-1BOOLEAN\s0" 2 .IX Item "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 \s-1ARRAY,\s0 but now of unrestricted length. .IP "check_values => \s-1BOOLEAN\s0" 2 .IX Item "check_values => BOOLEAN" Whether code will be produce to check that the \s-1XML\s0 fields contain the expected data format. .Sp 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 \s-1XML.\s0 .IP "default_values => '\s-1MINIMAL\s0'|'\s-1IGNORE\s0'|'\s-1EXTEND\s0'" 2 .IX Item "default_values => 'MINIMAL'|'IGNORE'|'EXTEND'" [reader] How to treat default values as provided by the schema. With \f(CW\*(C`IGNORE\*(C'\fR (the writer default), you will see exactly what is specified in the \s-1XML\s0 or \s-1HASH.\s0 With \f(CW\*(C`EXTEND\*(C'\fR (the reader default) will show the default and fixed values in the result. \f(CW\*(C`MINIMAL\*(C'\fR does remove all fields which are the same as the default setting: simplifies. See \*(L"Default Values\*(R". .ie n .IP "elements_qualified => ""TOP""|""ALL""|""NONE""|BOOLEAN" 2 .el .IP "elements_qualified => \f(CWTOP\fR|\f(CWALL\fR|\f(CWNONE\fR|BOOLEAN" 2 .IX Item "elements_qualified => TOP|ALL|NONE|BOOLEAN" When defined, this will overrule the use of namespaces (as prefix) on elements in all schemas. When \f(CW\*(C`ALL\*(C'\fR or a true value is given, then all elements will be used qualified. When \f(CW\*(C`NONE\*(C'\fR or a false value is given, the \s-1XML\s0 will not produce or process prefixes on any element. .Sp 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 \f(CW\*(C`TOP\*(C'\fR setting, the compiler checks that the targetNamespace exists. .Sp The \f(CW\*(C`form\*(C'\fR 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. .Sp With \f(CW\*(C`element_form_default\*(C'\fR, you can correct whole schema's about their name-space behavior. .Sp Change in [1.44]: \f(CW\*(C`TOP\*(C'\fR 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 \f(CW\*(C`TOP\*(C'\fR checks that the globals have a targetNamespace. .ie n .IP "hook => $hook|ARRAY\-OF\-hooks" 2 .el .IP "hook => \f(CW$hook\fR|ARRAY\-OF\-hooks" 2 .IX Item "hook => $hook|ARRAY-OF-hooks" Define one or more processing \f(CW$hooks\fR. See \*(L"Schema hooks\*(R" below. These hooks are only active for this compiled entity, where \fBaddHook()\fR and \fBaddHooks()\fR can be used to define hooks which are used for all results of \fBcompile()\fR. The hooks specified with the \f(CW\*(C`hook\*(C'\fR or \f(CW\*(C`hooks\*(C'\fR option are run before the global definitions. .ie n .IP "hooks => $hook|ARRAY\-OF\-hooks" 2 .el .IP "hooks => \f(CW$hook\fR|ARRAY\-OF\-hooks" 2 .IX Item "hooks => $hook|ARRAY-OF-hooks" Alternative for option \f(CW\*(C`hook\*(C'\fR. .IP "ignore_facets => \s-1BOOLEAN\s0" 2 .IX Item "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 \s-1XML:\s0 please do not turn this off when the data comes from external sources. .IP "ignore_unused_tags => BOOLEAN|REGEXP" 2 .IX Item "ignore_unused_tags => BOOLEAN|REGEXP" [writer] Overrules what is set with new(ignore_unused_tags). .IP "include_namespaces => BOOLEAN|CODE" 2 .IX Item "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 \s-1XML\s0 components into one, and add the namespaces later. No namespace definition can be added the production rule produces an attribute. .Sp When a \s-1CODE\s0 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 \s-1CODE\s0 is called with a namespace, its prefix, and the number of times it was used for that schema element translator. .IP "interpret_nillable_as_optional => \s-1BOOLEAN\s0" 2 .IX Item "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 \s-1WRITER,\s0 you still have to state \&\s-1NIL\s0 explicitly, but the elements are not constructed. The \s-1READER\s0 will output \s-1NIL\s0 when the nillable elements are missing. .IP "json_friendly => \s-1BOOLEAN\s0" 2 .IX Item "json_friendly => BOOLEAN" [1.55] When enabled, booleans will be blessed in Types::Serialiser booleans. Floats get nummified. Together, this will make the output of the reader usable as \s-1JSON\s0 without any further conversion. .IP "key_rewrite => HASH|CODE|ARRAY" 2 .IX Item "key_rewrite => HASH|CODE|ARRAY" Add key rewrite rules to the front of the list of rules, as set by new(key_rewrite) and \fBaddKeyRewrite()\fR. See \*(L"Key rewrite\*(R" .IP "mixed_elements => CODE|PREDEFINED" 2 .IX Item "mixed_elements => CODE|PREDEFINED" [reader] What to do when mixed schema elements are to be processed. Read more in the \*(L"\s-1DETAILS\*(R"\s0 section below. .IP "namespace_reset => \s-1BOOLEAN\s0" 2 .IX Item "namespace_reset => BOOLEAN" [writer] Use the same prefixes in \f(CW\*(C`prefixes\*(C'\fR as with some other compiled piece, but reset the counts to zero first. .IP "output_namespaces => HASH|ARRAY\-of\-PAIRS" 2 .IX Item "output_namespaces => HASH|ARRAY-of-PAIRS" [Pre\-0.87] name for the \f(CW\*(C`prefixes\*(C'\fR option. Deprecated. .IP "path => \s-1STRING\s0" 2 .IX Item "path => STRING" Prepended to each error report, to indicate the location of the error in the XML-Scheme tree. .IP "permit_href => \s-1BOOLEAN\s0" 2 .IX Item "permit_href => BOOLEAN" [reader] When parsing SOAP-RPC encoded messages, the elements may have a \f(CW\*(C`href\*(C'\fR attribute pointing to an object with \f(CW\*(C`id\*(C'\fR. The \s-1READER\s0 will return the unparsed, unresolved node when the attribute is detected, and the SOAP-RPC decoder will have to discover and resolve it. .IP "prefixes => HASH|ARRAY\-of\-PAIRS" 2 .IX Item "prefixes => HASH|ARRAY-of-PAIRS" Can be used to pre-define prefixes for namespaces (for '\s-1WRITER\s0' or key rewrite) for instance to reserve common abbreviations like \f(CW\*(C`soap\*(C'\fR for external use. Each entry in the hash has as key the namespace uri. The value is a hash which contains \f(CW\*(C`uri\*(C'\fR, \f(CW\*(C`prefix\*(C'\fR, and \f(CW\*(C`used\*(C'\fR fields. Pass a reference to a private hash to catch this index. An \s-1ARRAY\s0 with prefix, uri \s-1PAIRS\s0 is simpler. .Sp .Vb 2 \& prefixes => [ mine => $myns, two => $twons ] \& prefixes => { $myns => \*(Aqmine\*(Aq, $twons => \*(Aqtwo\*(Aq } \& \& # the previous is short for: \& prefixes => { $myns => [ uri => $myns, prefix => \*(Aqmine\*(Aq, used => 0 ] \& , $twons => [ uri => $twons, prefix => \*(Aqtwo\*(Aq, ...] }; .Ve .IP "sloppy_floats => \s-1BOOLEAN\s0" 2 .IX Item "sloppy_floats => BOOLEAN" [reader] The float types of \s-1XML\s0 are all quite big, and support NaN, \s-1INF,\s0 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 \f(CW\*(C`sloppy_integers\*(C'\fR. .IP "sloppy_integers => \s-1BOOLEAN\s0" 2 .IX Item "sloppy_integers => BOOLEAN" [reader] The \s-1XML\s0 \f(CW\*(C`integer\*(C'\fR 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 \f(CW\*(C`int\*(C'\fR type whould have sufficed, but the \s-1XML\s0 designer was lazy. A long is much faster to handle. Set this flag to use \f(CW\*(C`int\*(C'\fR as fast (but inprecise) replacements. .Sp Be aware that \f(CW\*(C`Math::BigInt\*(C'\fR and \f(CW\*(C`Math::BigFloat\*(C'\fR 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. .Sp You can also improve the speed of Math::BigInt by installing Math::BigInt::GMP. Add \f(CW\*(C`use Math::BigInt try => \*(AqGMP\*(Aq;\*(C'\fR to the top of your main script to get more performance. .IP "typemap => \s-1HASH\s0" 2 .IX Item "typemap => HASH" Add this typemap to the relations defined by new(typemap) or \&\fBaddTypemaps()\fR .IP "use_default_namespace => \s-1BOOLEAN\s0" 2 .IX Item "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. .IP "validation => \s-1BOOLEAN\s0" 2 .IX Item "validation => BOOLEAN" \&\s-1XML\s0 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 \f(CW\*(C`check_values\*(C'\fR, \&\f(CW\*(C`check_occurs\*(C'\fR, and \f(CW\*(C`ignore_facets\*(C'\fR. .IP "xsi_type => \s-1HASH\s0" 2 .IX Item "xsi_type => HASH" See \*(L"Handling xsi:type\*(R". The \s-1HASH\s0 maps types as mentioned in the schema, to extensions of those types which are addressed via the horrible \f(CW\*(C`xsi:type\*(C'\fR construct. When you specify \f(CW\*(C`AUTO\*(C'\fR 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. .IP "xsi_type_everywhere => \s-1BOOLEAN\s0" 2 .IX Item "xsi_type_everywhere => BOOLEAN" [1.48, writer] Add an \f(CW\*(C`xsi:type\*(C'\fR attribute to all elements, for instance as used in \s-1SOAP\s0 RPC/encoded. The type added is the type according to the schema, unless the \f(CW\*(C`xsi:type\*(C'\fR is already present on an element for some other reason. .Sp Be aware that this option has a different purpose from \f(CW\*(C`xsi_type\*(C'\fR. In this case, we do add exactly the type specified in the xsd to each element which does not have an \f(CW\*(C`xsi:type\*(C'\fR attribute yet. The \f(CW\*(C`xsi_type\*(C'\fR on the other hand, implements the (mis\-)feature that the element's content may get replaced by any extended type with this dynamic flag. .RE .RS 4 .RE .ie n .IP "$obj\->\fBcompileType\fR( <'\s-1READER\s0'|'\s-1WRITER\s0'>, $type, %options )" 4 .el .IP "\f(CW$obj\fR\->\fBcompileType\fR( <'\s-1READER\s0'|'\s-1WRITER\s0'>, \f(CW$type\fR, \f(CW%options\fR )" 4 .IX Item "$obj->compileType( <'READER'|'WRITER'>, $type, %options )" This is a hack to be able to process components of \s-1SOAP\s0 messages, which are only specified by type. Probably (hopefully) you do no need it. All \f(CW%options\fR are the same as for \fBcompile()\fR. .ie n .IP "$obj\->\fBdataToXML\fR($node|REF\-XML|XML\-STRING|$filename|$fh|$known)" 4 .el .IP "\f(CW$obj\fR\->\fBdataToXML\fR($node|REF\-XML|XML\-STRING|$filename|$fh|$known)" 4 .IX Item "$obj->dataToXML($node|REF-XML|XML-STRING|$filename|$fh|$known)" .PD 0 .ie n .IP "XML::Compile::Schema\->\fBdataToXML\fR( $node|REF\-XML|XML\-STRING|$filename|$fh|$known )" 4 .el .IP "XML::Compile::Schema\->\fBdataToXML\fR( \f(CW$node\fR|REF\-XML|XML\-STRING|$filename|$fh|$known )" 4 .IX Item "XML::Compile::Schema->dataToXML( $node|REF-XML|XML-STRING|$filename|$fh|$known )" .PD Inherited, see \*(L"Compilers\*(R" in XML::Compile .ie n .IP "$obj\->\fBinitParser\fR(%options)" 4 .el .IP "\f(CW$obj\fR\->\fBinitParser\fR(%options)" 4 .IX Item "$obj->initParser(%options)" .PD 0 .IP "XML::Compile::Schema\->\fBinitParser\fR(%options)" 4 .IX Item "XML::Compile::Schema->initParser(%options)" .PD Inherited, see \*(L"Compilers\*(R" in XML::Compile .ie n .IP "$obj\->\fBtemplate\fR( <'\s-1XML\s0'|'\s-1PERL\s0'|'\s-1TREE\s0'>, $element, %options )" 4 .el .IP "\f(CW$obj\fR\->\fBtemplate\fR( <'\s-1XML\s0'|'\s-1PERL\s0'|'\s-1TREE\s0'>, \f(CW$element\fR, \f(CW%options\fR )" 4 .IX Item "$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 \f(CW$element\fR shown as \s-1XML\s0 or Perl is organized in practice. .Sp The '\s-1TREE\s0' template returns the intermediate parse tree, which gets formatted into the \s-1XML\s0 or Perl example. This is not a very stable interface: it may change without much notice. .Sp Some \f(CW%options\fR are explained in XML::Compile::Translate. There are some extra \f(CW%options\fR defined for the final output process. .Sp The templates produced are \fBnot always correct\fR. Please contribute improvements: read and understand the comments in the text. .Sp .Vb 10 \& \-Option \-\-Default \& abstract_types \*(AqERROR\*(Aq \& attributes_qualified \& elements_qualified \& include_namespaces \& indent " " \& key_rewrite [] \& output_style 1 \& show_comments ALL \& skip_header .Ve .RS 4 .IP "abstract_types => '\s-1ERROR\s0'|'\s-1ACCEPT\s0'" 2 .IX Item "abstract_types => 'ERROR'|'ACCEPT'" By default, do not show abstract types in the output. .IP "attributes_qualified => \s-1BOOLEAN\s0" 2 .IX Item "attributes_qualified => BOOLEAN" .PD 0 .IP "elements_qualified => '\s-1ALL\s0'|'\s-1TOP\s0'|'\s-1NONE\s0'|BOOLEAN" 2 .IX Item "elements_qualified => 'ALL'|'TOP'|'NONE'|BOOLEAN" .IP "include_namespaces => BOOLEAN|CODE" 2 .IX Item "include_namespaces => BOOLEAN|CODE" .IP "indent => \s-1STRING\s0" 2 .IX Item "indent => STRING" .PD The leading indentation string per nesting. Must start with at least one blank. .IP "key_rewrite => HASH|CODE|ARRAY" 2 .IX Item "key_rewrite => HASH|CODE|ARRAY" .PD 0 .IP "output_style => 1|2" 2 .IX Item "output_style => 1|2" .PD [1.61] Style 2 is a little different. .IP "show_comments => STRING|'\s-1ALL\s0'|'\s-1NONE\s0'" 2 .IX Item "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: \f(CW\*(C`struct\*(C'\fR, \f(CW\*(C`type\*(C'\fR, \&\f(CW\*(C`occur\*(C'\fR, \f(CW\*(C`facets\*(C'\fR. A value of \f(CW\*(C`ALL\*(C'\fR will select all available comments. The \f(CW\*(C`NONE\*(C'\fR or empty string will exclude all comments. .IP "skip_header => \s-1BOOLEAN\s0" 2 .IX Item "skip_header => BOOLEAN" Skip the comment header from the output. .RE .RS 4 .RE .SS "Administration" .IX Subsection "Administration" Extends \*(L"Administration\*(R" in XML::Compile. .ie n .IP "$obj\->\fBdoesExtend\fR($exttype, $basetype)" 4 .el .IP "\f(CW$obj\fR\->\fBdoesExtend\fR($exttype, \f(CW$basetype\fR)" 4 .IX Item "$obj->doesExtend($exttype, $basetype)" Returns true when the \f(CW$exttype\fR extends the \f(CW$basetype\fR. See \&\fBXML::Compile::Schema::NameSpaces::doesExtend()\fR .ie n .IP "$obj\->\fBelements\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBelements\fR()" 4 .IX Item "$obj->elements()" List all elements, defined by all schemas sorted alphabetically. .ie n .IP "$obj\->\fBfindSchemaFile\fR($filename)" 4 .el .IP "\f(CW$obj\fR\->\fBfindSchemaFile\fR($filename)" 4 .IX Item "$obj->findSchemaFile($filename)" .PD 0 .IP "XML::Compile::Schema\->\fBfindSchemaFile\fR($filename)" 4 .IX Item "XML::Compile::Schema->findSchemaFile($filename)" .PD Inherited, see \*(L"Administration\*(R" in XML::Compile .ie n .IP "$obj\->\fBimportDefinitions\fR($xmldata, %options)" 4 .el .IP "\f(CW$obj\fR\->\fBimportDefinitions\fR($xmldata, \f(CW%options\fR)" 4 .IX Item "$obj->importDefinitions($xmldata, %options)" Import (include) the schema information included in the \f(CW$xmldata\fR. The \&\f(CW$xmldata\fR must be acceptable for \fBdataToXML()\fR. The resulting node and all the \f(CW%options\fR are passed to \fBaddSchemas()\fR. The schema node does not need to be the top element: any schema node found in the data will be decoded. .Sp Returned is a list of XML::Compile::Schema::Instance objects, for each processed schema component. .Sp 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 duplications will not work for open files or pre-parsed \&\s-1XML\s0 structures. .Sp As an extension to the handling \fBdataToXML()\fR provides, you can specify an \&\s-1ARRAY\s0 of things which are acceptable to \f(CW\*(C`dataToXML\*(C'\fR. This way, you can specify multiple resources at once, each of which will be processed with the same \f(CW%options\fR. .Sp .Vb 2 \& \-Option \-\-Default \& details .Ve .RS 4 .IP "details => \s-1HASH\s0" 2 .IX Item "details => HASH" Overrule the details information about the source of the data. .RE .RS 4 .Sp example: of use of importDefinitions .Sp .Vb 2 \& my $schema = XML::Compile::Schema\->new; \& $schema\->importDefinitions(\*(Aqmy\-spec.xsd\*(Aq); \& \& my $other = "..."; # use \*(AqHERE\*(Aq documents! \& my @specs = (\*(Aqmy\-spec.xsd\*(Aq, \*(Aqtypes.xsd\*(Aq, $other); \& $schema\->importDefinitions(\e@specs, @options); .Ve .RE .ie n .IP "$obj\->\fBknownNamespace\fR($ns|PAIRS)" 4 .el .IP "\f(CW$obj\fR\->\fBknownNamespace\fR($ns|PAIRS)" 4 .IX Item "$obj->knownNamespace($ns|PAIRS)" .PD 0 .IP "XML::Compile::Schema\->\fBknownNamespace\fR($ns|PAIRS)" 4 .IX Item "XML::Compile::Schema->knownNamespace($ns|PAIRS)" .PD Inherited, see \*(L"Administration\*(R" in XML::Compile .ie n .IP "$obj\->\fBnamespaces\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBnamespaces\fR()" 4 .IX Item "$obj->namespaces()" Returns the XML::Compile::Schema::NameSpaces object which is used to collect schemas. .ie n .IP "$obj\->\fBprintIndex\fR( [$fh], %options )" 4 .el .IP "\f(CW$obj\fR\->\fBprintIndex\fR( [$fh], \f(CW%options\fR )" 4 .IX Item "$obj->printIndex( [$fh], %options )" Print all the elements which are defined in the schemas to the \f(CW$fh\fR (by default the selected handle). \f(CW%options\fR are passed to \&\fBXML::Compile::Schema::NameSpaces::printIndex()\fR and \&\fBXML::Compile::Schema::Instance::printIndex()\fR. .ie n .IP "$obj\->\fBtypes\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBtypes\fR()" 4 .IX Item "$obj->types()" List all types, defined by all schemas sorted alphabetically. .ie n .IP "$obj\->\fBwalkTree\fR($node, \s-1CODE\s0)" 4 .el .IP "\f(CW$obj\fR\->\fBwalkTree\fR($node, \s-1CODE\s0)" 4 .IX Item "$obj->walkTree($node, CODE)" Inherited, see \*(L"Administration\*(R" in XML::Compile .SH "DETAILS" .IX Header "DETAILS" Extends \*(L"\s-1DETAILS\*(R"\s0 in XML::Compile. .SS "Distribution collection overview" .IX Subsection "Distribution collection overview" Extends \*(L"Distribution collection overview\*(R" in XML::Compile. .SS "Comparison" .IX Subsection "Comparison" Extends \*(L"Comparison\*(R" in XML::Compile. .SS "Collecting definitions" .IX Subsection "Collecting definitions" When starting an application, you will need to read the schema definitions. This is done by instantiating an object via \&\fBXML::Compile::Schema::new()\fR or \fBXML::Compile::WSDL11::new()\fR. The \s-1WSDL11\s0 object has a schema object internally. .PP Schemas may contains \f(CW\*(C`import\*(C'\fR and \f(CW\*(C`include\*(C'\fR statements, which specify other resources for definitions. In the idea of the \s-1XML\s0 design team, those files should be retrieved automatically via an internet connection from the \f(CW\*(C`schemaLocation\*(C'\fR. However, this is a bad concept; in XML::Compile modules you will have to explicitly provide filenames on local disk using \fBimportDefinitions()\fR or \fBXML::Compile::WSDL11::addWSDL()\fR. .PP There are various reasons why I, the author of this module, think the dynamic automatic internet imports are a bad idea. First: you do not always have a working internet connection (travelling with a laptop in a train). Your implementation should work the same way under all environmental circumstances! Besides, I do not trust remote files on my system, without inspecting them. Most important: I want to run my regression tests before using a new version of the definitions, so I do not want to have a remote server change the agreements without my knowledge. .PP So: before you start, you will need to scan (recursively) the initial schema or wsdl file for \f(CW\*(C`import\*(C'\fR and \f(CW\*(C`include\*(C'\fR statements, and collect all these files from their \f(CW\*(C`schemaLocation\*(C'\fR into files on local disk. In your program, call \fBimportDefinitions()\fR on all of them \-in any order\- before you call \fBcompile()\fR. .PP \fIOrganizing your definitions\fR .IX Subsection "Organizing your definitions" .PP One nice feature to help you organize (especially useful when you package your code in a distribution), is to add these lines to the beginning of your code: .PP .Vb 3 \& package My::Package; \& XML::Compile\->addSchemaDirs(_\|_FILE_\|_); \& XML::Compile\->knownNamespace(\*(Aqhttp://myns\*(Aq => \*(Aqmyns.xsd\*(Aq, ...); .Ve .PP Now, if the package file is located at \f(CW\*(C`SomeThing/My/Package.pm\*(C'\fR, the definion of the namespace should be kept in \&\f(CW\*(C`SomeThing/My/Package/xsd/myns.xsd\*(C'\fR. .PP Somewhere in your program, you have to load these definitions: .PP .Vb 2 \& # absolute or relative path is always possible \& $schema\->importDefinitions(\*(AqSomeThing/My/Package/xsd/myns.xsd\*(Aq); \& \& # relative search path extended by addSchemaDirs \& $schema\->importDefinitions(\*(Aqmyns.xsd\*(Aq); \& \& # knownNamespace improves abstraction \& $schema\->importDefinitions(\*(Aqhttp://myns\*(Aq); .Ve .PP Very probably, the namespace is already in some variable: .PP .Vb 2 \& use XML::Compile::Schema; \& use XML::Compile::Util \*(Aqpack_type\*(Aq; \& \& my $myns = \*(Aqhttp://some\-very\-long\-uri\*(Aq; \& my $schema = XML::Compile::Schema\->new($myns); \& my $mytype = pack_type $myns, $myelement; \& my $reader = $schema\->compileClient(READER => $mytype); .Ve .SS "Addressing components" .IX Subsection "Addressing components" Normally, external users can only address elements within a schema, and types are hidden to be used by other schemas only. For this reason, it is permitted to create an element and a type with the same name. .PP 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 \f(CW\*(C`{namespace\-uri}localname\*(C'\fR, for instance .PP .Vb 1 \& {http://library}book .Ve .PP You may also start with .PP .Vb 1 \& http://www.w3.org/2001/XMLSchema#float .Ve .PP as long as this \s-1ID\s0 refers to a top-level element, not a type. .PP When you use a schema without \f(CW\*(C`targetNamespace\*(C'\fR (which is bad practice, but sometimes people really do not understand the beneficial aspects of the use of namespaces) then the elements can be addressed as \f(CW\*(C`{}name\*(C'\fR or simple \f(CW\*(C`name\*(C'\fR. .SS "Representing data-structures" .IX Subsection "Representing data-structures" The code will do its best to produce a correct translation. For instance, an accidental \f(CW1.9999\fR will be converted into \f(CW2\fR when the schema says that the field is an \f(CW\*(C`int\*(C'\fR. It will also strip superfluous blanks when the data-type permits. Especially watch-out for the \f(CW\*(C`Integer\*(C'\fR types, which produce Math::BigInt objects unless compile(sloppy_integers) is used. .PP Elements can be complex, and themselve contain elements which are complex. In the Perl representation of the data, this will be shown as nested hashes with the same structure as the \s-1XML.\s0 .PP You should not take tare of character encodings, whereas XML::LibXML is doing that for us: you shall not escape characters like \*(L"<\*(R" yourself. .PP The schemas define 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. .PP \fIsimpleType\fR .IX Subsection "simpleType" .PP A single value. A lot of single value data-types are built-in (see XML::Compile::Schema::BuiltInTypes). .PP 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. .PP Note that some of the reader hooks will alter the single value of these elements into a \s-1HASH\s0 like used for the complexType/simpleContent (next paragraph), to be able to return some extra collected information. .PP \&\fB. Example: typical simpleType\fR .PP In \s-1XML,\s0 it looks like this: .PP .Vb 1 \& 42 .Ve .PP In the \s-1HASH\s0 structure, the data will be represented as .PP .Vb 1 \& test1 => 42 .Ve .PP With reader hook \f(CW\*(C`after => \*(AqXML_NODE\*(Aq\*(C'\fR hook applied, it will become .PP .Vb 3 \& test1 => { _ => 42 \& , _XML_NODE => $obj \& } .Ve .PP \fIcomplexType/simpleContent\fR .IX Subsection "complexType/simpleContent" .PP In this case, the single value container may have attributes. The number of attributes can be endless, and the value is only one. This value has no name, and therefore gets a predefined name \f(CW\*(C`_\*(C'\fR. .PP When passed to the writer, you may specify a single value (not the whole \&\s-1HASH\s0) when no attributes are used. .PP \&\fB. typical simpleContent example\fR .PP In \s-1XML,\s0 this looks like this: .PP .Vb 1 \& 42 .Ve .PP As a \s-1HASH,\s0 this shows as .PP .Vb 3 \& test2 => { _ => 42 \& , question => \*(Aqeverything\*(Aq \& } .Ve .PP When specified in the writer, when no attributes are need, you can use either form: .PP .Vb 2 \& test3 => { _ => 7 } \& test3 => 7 .Ve .PP \fIcomplexType and complexType/complexContent\fR .IX Subsection "complexType and complexType/complexContent" .PP These containers not only have attributes, but also multiple values as content. The \f(CW\*(C`complexContent\*(C'\fR is used to create inheritance structures in the data-type definition. This does not affect the \&\s-1XML\s0 data package itself. .PP \&\fB. Example: typical complexType element\fR .PP The \s-1XML\s0 could look like: .PP .Vb 4 \& \& 42 \& 5 billion BC \& .Ve .PP Represented as \s-1HASH,\s0 this looks like .PP .Vb 5 \& test3 => { question => \*(Aqeverything\*(Aq \& , by => \*(Aqmouse\*(Aq \& , answer => 42 \& , when => \*(Aq5 billion BC\*(Aq \& } .Ve .PP \fIManually produced \s-1XML NODE\s0\fR .IX Subsection "Manually produced XML NODE" .PP For a \s-1WRITER,\s0 you may also specify a XML::LibXML::Node anywhere. .PP .Vb 2 \& test1 => $doc\->createTextNode(\*(Aq42\*(Aq); \& test3 => $doc\->createElement(\*(Aqariba\*(Aq); .Ve .PP This data-structure is used without validation, so you are fully on your own with this one. Typically, nodes are produced by hooks to implement work-arounds. .PP \fIOccurence\fR .IX Subsection "Occurence" .PP A second factor which determines the data-structure is the element occurrence. Usually, elements have to appear once and exactly once on a certain location in the \s-1XML\s0 data structure. This order is automatically produced by this module. But elements may appear multiple times. .IP "usual case" 4 .IX Item "usual case" The default behavior for an element (in a sequence container) is to appear exactly once. When missing, this is an error. .IP "maxOccurs larger than 1" 4 .IX Item "maxOccurs larger than 1" In this case, the element or particle block can appear multiple times. Multiple values are kept in an \s-1ARRAY\s0 within the \s-1HASH.\s0 Non-schema based \&\s-1XML\s0 modules do not return a single value as an \s-1ARRAY,\s0 which makes that code more complicated. But in our case, we know the expected amount beforehand. .Sp When the maxOccurs larger than 1 is specified for an element, an \s-1ARRAY\s0 of those elements is produced. When it is specified for a block (sequence, choice, all, group), then an \s-1ARRAY\s0 of HASHes is returned. See the special section about this subject. .Sp An error is produced when the number of elements found is less than \&\f(CW\*(C`minOccurs\*(C'\fR (defaults to 1) or more than \f(CW\*(C`maxOccurs\*(C'\fR (defaults to 1), unless compile(check_occurs) is \f(CW\*(C`false\*(C'\fR. .Sp Example elements with maxOccurs larger than 1. In the schema: .Sp .Vb 2 \& \& .Ve .Sp In the \s-1XML\s0 message: .Sp .Vb 1 \& 121314 .Ve .Sp In the Perl representation: .Sp .Vb 1 \& a => [12, 13], b => 14 .Ve .ie n .IP "value is ""NIL""" 4 .el .IP "value is \f(CWNIL\fR" 4 .IX Item "value is NIL" When an element is nillable, that is explicitly represented as a \f(CW\*(C`NIL\*(C'\fR constant string. .ie n .IP "use=""optional"" or minOccurs=""0""" 4 .el .IP "use=``optional'' or minOccurs=``0''" 4 .IX Item "use=optional or minOccurs=0" The element may be skipped. When found it is a single value. .ie n .IP "use=""forbidden""" 4 .el .IP "use=``forbidden''" 4 .IX Item "use=forbidden" When the element is found, an error is produced. .ie n .IP "default=""value""" 4 .el .IP "default=``value''" 4 .IX Item "default=value" When the \s-1XML\s0 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. .ie n .IP "fixed=""value""" 4 .el .IP "fixed=``value''" 4 .IX Item "fixed=value" Produce an error when the value is not present or different (after the white-space rules where applied). .PP \fIDefault Values\fR .IX Subsection "Default Values" .PP [added in v0.91] With compile(default_values) you can control how much information about default values defined by the schema will be passed into your program. .PP The choices, available for both \s-1READER\s0 and \s-1WRITER,\s0 are: .ie n .IP """IGNORE"" (the \s-1WRITER\s0's standard behavior)" 4 .el .IP "\f(CWIGNORE\fR (the \s-1WRITER\s0's standard behavior)" 4 .IX Item "IGNORE (the WRITER's standard behavior)" Only include element and attribute values in the result if they are in the \s-1XML\s0 message. Behaviorally, this treats elements with default values as if they are just optional. The \s-1WRITER\s0 does not try to be smarter than you. .ie n .IP """EXTEND"" (the \s-1READER\s0's standard behavior)" 4 .el .IP "\f(CWEXTEND\fR (the \s-1READER\s0's standard behavior)" 4 .IX Item "EXTEND (the READER's standard behavior)" If some element or attribute is not in the source but has a default in the schema, that value will be produced. This is very convenient for the \&\s-1READER,\s0 because your application does not have to hard-code the same constant values as defaults as well. .ie n .IP """MINIMAL""" 4 .el .IP "\f(CWMINIMAL\fR" 4 .IX Item "MINIMAL" Only produce the values which differ from the defaults. This choice is useful when producing \s-1XML,\s0 to reduce the size of the output. .PP \&\fB. Example: use of default_values \s-1EXTEND\s0\fR .PP Let us process a schema using the schema schema. A schema file can contain lines like this: .PP .Vb 1 \& .Ve .PP In mode \f(CW\*(C`EXTEND\*(C'\fR (the \s-1READER\s0 default), this gets translated into: .PP .Vb 2 \& element => { ref => \*(Aqmyelem\*(Aq, maxOccurs => 1 \& , minOccurs => 0, nillable => 0 }; .Ve .PP With \f(CW\*(C`EXTEND\*(C'\fR in the \s-1READER,\s0 all schema information is used to provide a complete overview of available information. Your code does not need to check whether the attributes were available or not: attributes with defaults or fixed values are automatically added. .PP Again mode \f(CW\*(C`EXTEND\*(C'\fR, now for the writer: .PP .Vb 2 \& element => { ref => \*(Aqmyelem\*(Aq, minOccurs => 0 }; \& .Ve .PP \&\fB. Example: use of default_values \s-1IGNORE\s0\fR .PP With option \f(CW\*(C`default_values\*(C'\fR set to \f(CW\*(C`IGNORE\*(C'\fR (the \s-1WRITER\s0 default), you would get .PP .Vb 2 \& element => { ref => \*(Aqmyelem\*(Aq, maxOccurs => 1, minOccurs => 0 } \& .Ve .PP The same in both translation directions. The nillable attribute is not used, so will not be shown by the \s-1READER.\s0 The writer does not try to be smart, so does not add the nillable default. .PP \&\fB. Example: use of default_values \s-1MINIMAL\s0\fR .PP With option \f(CW\*(C`default_values\*(C'\fR set to \f(CW\*(C`MINIMAL\*(C'\fR, the \s-1READER\s0 would do this: .PP .Vb 2 \& \& element => { ref => \*(Aqmyelem\*(Aq, minOccurs => 0 } .Ve .PP The maxOccurs default is \*(L"1\*(R", so will not be included, minimalizing the size of the \s-1HASH.\s0 .PP For the \s-1WRITER:\s0 .PP .Vb 2 \& element => { ref => \*(Aqmyelem\*(Aq, minOccurs => 0, nillable => 0 } \& .Ve .PP because the default value for nillable is '0', it will not show as attribute value. .PP \fIRepetative blocks\fR .IX Subsection "Repetative blocks" .PP Particle blocks come in four shapes: \f(CW\*(C`sequence\*(C'\fR, \f(CW\*(C`choice\*(C'\fR, \f(CW\*(C`all\*(C'\fR, and \f(CW\*(C`group\*(C'\fR (an indirect block). This also affects \f(CW\*(C`substitutionGroups\*(C'\fR. .PP repetative sequence, choice, all .IX Subsection "repetative sequence, choice, all" .PP In situations like this: .PP .Vb 11 \& \& \& \& \& \& \& \& \& \& \& .Ve .PP (yes, schemas are verbose) the data structure is .PP .Vb 1 \& 1 2 3 .Ve .PP the Perl representation is \fIflattened\fR, into .PP .Vb 1 \& example => { a => 1, b => 2, c => 3 } .Ve .PP Ok, this is very simple. However, schemas can use repetition: .PP .Vb 11 \& \& \& \& \& \& \& \& \& \& \& .Ve .PP The \s-1XML\s0 message may be: .PP .Vb 1 \& 1 2 3 4 5 .Ve .PP Now, the perl representation needs to produce an array of the data in the repeated block. This array needs to have a name, because more of these blocks may appear together in a construct. The \fBname of the block\fR is derived from the \fItype of block\fR and the name of the \fIfirst element\fR in the block, regardless whether that element is present in the data or not. .PP So, our example data is translated into (and vice versa) .PP .Vb 5 \& example => \& { a => 1 \& , seq_b => [ {b => 2}, {b => 3}, {b => 4} ] \& , c => 5 \& } .Ve .PP The following label is used, based on the name of the first element (say \f(CW\*(C`xyz\*(C'\fR) as defined in the schema (not in the actual message): seq_xyz sequence with maxOccurs > 1 cho_xyz choice with maxOccurs > 1 all_xyz all with maxOccurs > 1 .PP When you have compile(key_rewrite) option \s-1PREFIXED,\s0 and you have explicitly assigned the prefix \f(CW\*(C`xs\*(C'\fR to the schema namespace (See compile(prefixes)), then those names will respectively be \f(CW\*(C`seq_xs_xyz\*(C'\fR, \f(CW\*(C`cho_xs_xyz\*(C'\fR, \&\f(CW\*(C`all_xs_xyz\*(C'\fR. .PP \&\fB. Example: always an array with maxOccurs larger than 1\fR .PP Even when there is only one element found, it will be returned as \&\s-1ARRAY\s0 (of one element). Therefore, you can write .PP .Vb 2 \& my $data = $reader\->($xml); \& foreach my $a ( @{$data\->{a}} ) {...} .Ve .PP \&\fB. Example: blocks with maxOccurs larger than 1\fR .PP In the schema: .PP In the \s-1XML\s0 message: 15161718 .PP In Perl representation: seq_a => [ {a => 15, b => 16}, {a => 17, b => 18} ] .PP repetative groups .IX Subsection "repetative groups" .PP [behavioral change in 0.93] In contrast to the normal particle blocks, as described above, do the groups have names. In this case, we do not need to take the name of the first element, but can use the group name. It will still have \f(CW\*(C`gr_\*(C'\fR appended, because groups can have the same name as an element or a type(!) .PP Blocks within the group definition cannot be repeated. .PP \&\fB. Example: groups with maxOccurs larger than 1\fR .PP .Vb 7 \& \& \& \& \& \& \& \& \& \& \& \& \& \& .Ve .PP translates into .PP .Vb 1 \& gr_xyz => [ {a => 42, b => 43}, {a => 44, b => 45} ] .Ve .PP repetative substitutionGroups .IX Subsection "repetative substitutionGroups" .PP For \fBsubstitutionGroup\fRs which are repeating, the \fIname of the base element\fR is used (the element which has attribute \f(CW\*(C`. We do need this array, because the order of the elements within the group may be important; we cannot group the elements based to the extended element's name. .PP In an example substitutionGroup, the Perl representation will be something like this: .PP .Vb 4 \& base\-element\-name => \& [ { extension\-name => $data1 } \& , { other\-extension => $data2 } \& ] .Ve .PP Each \s-1HASH\s0 has only one key. .PP \&\fB. Example: with a list of ints\fR .PP .Vb 1 \& 3 8 12 .Ve .PP as Perl structure: .PP .Vb 1 \& test5 => [3, 8, 12] .Ve .PP \&\fB. Example: substitutionGroup\fR .PP .Vb 3 \& \& \& \& \& \& \& \& \& \& .Ve .PP Now, valid \s-1XML\s0 data is .PP .Vb 4 \& \& Ball \& 12 \& .Ve .PP and .PP .Vb 4 \& \& Ball \& 6 \& .Ve .PP The \s-1HASH\s0 repesentation is respectively .PP .Vb 2 \& product => {name => \*(AqBall\*(Aq, euro => 12} \& product => {name => \*(AqBall\*(Aq, dollar => 6} .Ve .PP \&\fB. Example: of HOOKs:\fR .PP .Vb 4 \& my $hook = { type => \*(Aq{my_ns}my_type\*(Aq \& , before => sub { ... } \& , action => \*(AqWRITER\*(Aq \& }; \& \& my $hook = { path => qr/\e(volume\e)/ \& , replace => \*(AqSKIP\*(Aq \& , action => \*(AqREADER\*(Aq \& }; \& \& # path contains "volume" or id is \*(Aqaap\*(Aq or id is \*(Aqnoot\*(Aq \& my $hook = { path => qr/\ebvolume\eb/ \& , id => [ \*(Aqaap\*(Aq, \*(Aqnoot\*(Aq ] \& , before => [ sub {...}, sub { ... } ] \& , after => sub { ... } \& }; .Ve .PP \&\fB. Example: use of the type selector\fR .PP .Vb 4 \& type => \*(Aqint\*(Aq \& type => \*(Aq{http://www.w3.org/2000/10/XMLSchema}int\*(Aq \& type => qr/\e}xml_/ # type start with xml_ \& type => [ qw/int float/ ]; \& \& use XML::Compile::Util qw/pack_type SCHEMA2000/; \& type => pack_type(SCHEMA2000, \*(Aqint\*(Aq) \& \& # with XML::Compile::Cache \& $schema\->addPrefixes(xsd => SCHEMA2000); \& type => \*(Aqxsd:int\*(Aq .Ve .PP \&\fB. Example: type hook with XML::Compile::Cache\fR .PP .Vb 5 \& use XML::Compile::Util qw/SCHEMA2001/; \& my $schemas = XML::Compile::Cache\->new(...); \& $schemas\->addPrefixes(xsd => SCHEMA2001, mine => \*(Aqhttp://somens\*(Aq); \& $schemas\->addHook(type => \*(Aqxsd:int\*(Aq, ...); \& $schemas\->addHook(type => \*(Aqmine:sometype\*(Aq, ...); .Ve .PP \&\fB. Example: use of the \s-1ID\s0 selector\fR .PP .Vb 5 \& # default schema types have id\*(Aqs with same name \& id => \*(AqABC\*(Aq \& id => \*(Aqhttp://www.w3.org/2001/XMLSchema#int\*(Aq \& id => qr/\e#xml_/ # id which start with xml_ \& id => [ qw/ABC fgh/ ]; \& \& use XML::Compile::Util qw/pack_id SCHEMA2001/; \& id => pack_id(SCHEMA2001, \*(AqABC\*(Aq) .Ve .PP \&\fB. Example: anyAttribute in a \s-1READER\s0\fR .PP Say your schema looks like this: .PP .Vb 10 \& \& \& \& \& \& \& \& \& \& \& .Ve .PP Then, in an application, you write: .PP .Vb 5 \& my $r = $schema\->compile \& ( READER => pack_type(\*(Aqhttp://mine\*(Aq, \*(Aqel\*(Aq) \& , anyAttribute => \*(AqALL\*(Aq \& ); \& # or lazy: READER => \*(Aq{http://mine}el\*(Aq \& \& my $h = $r\->( <<\*(Aq_\|_XML\*(Aq ); \& \& 42 \& \& everything \& \& \& _\|_XML \& \& use Data::Dumper \*(AqDumper\*(Aq; \& print Dumper $h; \& _\|_XML_\|_ .Ve .PP The output is something like .PP .Vb 5 \& $VAR1 = \& { a => 42 \& , \*(Aq{http://mine}a\*(Aq => ... # XML::LibXML::Node with 42 \& , \*(Aq{http://mine}b\*(Aq => ... # XML::LibXML::Node with everything \& }; .Ve .PP You can improve the reader with a callback. When you know that the extra attribute is always of type \f(CW\*(C`non\-empty\*(C'\fR, then you can do .PP .Vb 4 \& my $read = $schema\->compile \& ( READER => \*(Aq{http://mine}el\*(Aq \& , anyAttribute => \e&filter \& ); \& \& my $anyAttRead = $schema\->compile \& ( READER => \*(Aq{http://mine}non\-empty\*(Aq \& ); \& \& sub filter($$$$) \& { my ($fqn, $xml, $path, $translator) = @_; \& return () if $fqn ne \*(Aq{http://mine}b\*(Aq; \& (b => $anyAttRead\->($xml)); \& } \& \& my $h = $r\->( see above ); \& print Dumper $h; .Ve .PP Which will result in .PP .Vb 4 \& $VAR1 = \& { a => 42 \& , b => \*(Aqeverything\*(Aq \& }; .Ve .PP The filter will be called twice, but return nothing in the first case. You can implement any kind of complex processing in the filter. .PP \&\fB. Example: to trace the paths\fR .PP .Vb 5 \& $schema\->addHook \& ( action => \*(AqREADER\*(Aq \& , path => qr/./ \& , before => \*(AqPRINT_PATH\*(Aq \& ); .Ve .PP \&\fB. Example: specify anyAttribute\fR .PP .Vb 1 \& use XML::Compile::Util qw/pack_type/; \& \& my $attr = $doc\->createAttributeNS($somens, $sometype, 42); \& my $h = { a => 12 # normal element or attribute \& , "{$somens}$sometype" => $attr # anyAttribute \& , pack_type($somens, $mytype) => $attr # nicer \& , "$prefix:$sometype" => $attr # [1.28] \& }; .Ve .PP \&\fB. Example: before hook on user-provided \s-1HASH.\s0\fR .PP .Vb 2 \& sub beforeOnComplex($$$$) \& { my ($doc, $values, $path, $fulltype) = @_; \& \& my %copy = %$values; \& $copy{extra} = 42; \& delete $copy{superfluous}; \& $copy{count} =~ s/\eD//g; # only digits \& \e%copy; \& } .Ve .PP \&\fB. Example: before hook on simpleType data\fR .PP .Vb 4 \& sub beforeOnSimple($$$$) \& { my ($doc, $value, $path, $fulltype) = @_; \& $value * 100; # convert euro to euro\-cents \& } .Ve .PP \&\fB. Example: before hook with object for complexType\fR .PP .Vb 2 \& sub beforeOnObject($$$$) \& { my ($doc, $obj, $path, $fulltype) = @_; \& \& +{ name => $obj\->name \& , price => $obj\->euro \& , currency => \*(AqEUR\*(Aq \& }; \& } .Ve .PP \&\fB. Example: replace hook\fR .PP .Vb 6 \& sub replace($$$$$) \& { my ($doc, $values, $path, $tag, $r, $fulltype) = @_ \& my $node = $doc\->createElement($tag); \& $node\->appendText($values\->{text}); \& $node; \& } .Ve .PP \&\fB. Example: add an extra sibbling after the usual process\fR .PP .Vb 6 \& sub after($$$$) \& { my ($doc, $node, $path, $values, $fulltype) = @_; \& my $child = $doc\->createAttributeNS($myns, earth => 42); \& $node\->addChild($child); \& $node; \& } .Ve .PP \&\fB. Example: creating nodes with text\fR .PP .Vb 1 \& { my $text; \& \& sub before($$$) \& { my ($doc, $values, $path) = @_; \& my %copy = %$values; \& $text = delete $copy{text}; \& \e%copy; \& } \& \& sub after($$$) \& { my ($doc, $node, $path) = @_; \& $node\->addChild($doc\->createTextNode($text)); \& $node; \& } \& \& $schema\->addHook \& ( action => \*(AqWRITER\*(Aq \& , type => \*(Aqmixed\*(Aq \& , before => \e&before \& , after => \e&after \& ); \& } .Ve .PP \fIList type\fR .IX Subsection "List type" .PP List simpleType objects are also represented as \s-1ARRAY,\s0 like elements with a minOccurs or maxOccurs unequal 1. .PP \fIUsing substitutionGroup constructs\fR .IX Subsection "Using substitutionGroup constructs" .PP A substitution group is kind-of choice between alternative (complex) types. However, in this case roles have reversed: instead a \f(CW\*(C`choice\*(C'\fR which lists the alternatives, here the alternative elements register themselves as valid for an abstract (\fIhead\fR) element. All alternatives should be extensions of the head element's type, but there is no way to check that. .PP \fIWildcards via any and anyAttribute\fR .IX Subsection "Wildcards via any and anyAttribute" .PP The \f(CW\*(C`any\*(C'\fR and \f(CW\*(C`anyAttribute\*(C'\fR elements are referred to as \f(CW\*(C`wildcards\*(C'\fR: they specify (huge, generic) groups of elements and attributes which are accepted, instead of being explicit. .PP The author of this module advices \fBagainst the use of wildcards\fR in schemas: the purpose of schemas is to be \fIexplicit\fR about the message in the interface, and that basic idea is simply thrown away by these wildcards. Let people cleanly extend the schema with inheritance! There is always a substitutionGroup alternative possible. .PP Because wildcards are not explicit about the types to expect, the \&\f(CW\*(C`XML::Compile\*(C'\fR module can not prepare for them at run-time. You need to go read the documentation and do some tricky manual work to get it to work. .PP Read about the processing of wildcards in the manual page for each of the back-ends (XML::Compile::Translate::Reader, XML::Compile::Translate::Writer, ...). .PP \fIComplexType with \*(L"mixed\*(R" attribute\fR .IX Subsection "ComplexType with mixed attribute" .PP [largely improved in 0.86, reader only] ComplexType and ComplexContent components can be declared with the \&\f(CW\*(C` attribute. This implies that text is not limited to the content of containers, but may also be used inbetween elements. Usually, you will only find ignorable white-space between elements. .PP In this example, the \f(CW\*(C`a\*(C'\fR container is marked to be mixed: before 2 after .PP Each back-end has its own way of handling mixed elements. The compile(mixed_elements) currently only modifies the reader's behavior; the writer's capabilities are limited. See XML::Compile::Translate::Reader. .PP \fIhexBinary and base64Binary\fR .IX Subsection "hexBinary and base64Binary" .PP These are used to include images and such in an \s-1XML\s0 message. Usually, they are quite large with respect to the other elements. When you use \&\s-1SOAP,\s0 you may wish to use XML::Compile::XOP instead. .PP The element values which you need to pass for fields of these types is a binary \s-1BLOB,\s0 something Perl does not have. So, it is a string containing binary data but not specially marked that way. .PP If you need to store an integer in such a binary field, you first have to promote it into a \s-1BLOB\s0 (string) like this .PP .Vb 2 \& { color => pack(\*(AqN\*(Aq, $i) } # writer \& my $i = unpack(\*(AqN\*(Aq, $d\->{color}); # reader .Ve .PP Module Geo::KML implemented a nice hook to avoid the explicit need for this \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR. The \s-1KML\s0 schema designers liked colors to be written as \f(CW\*(C`ffc0c0c0\*(C'\fR and abused \f(CW\*(C`hexBinary\*(C'\fR for that purpose. The \f(CW\*(C`colorType\*(C'\fR fields in \s-1KML\s0 are treated as binary, but just represent an int. Have a look in that Geo::KML code if your schema has some of those tricks. Only available in Backpan, withdrawn from \s-1CPAN.\s0 .SS "Schema hooks" .IX Subsection "Schema hooks" You can use hooks, for instance, to block processing parts of the message, to create work-arounds for schema bugs, or to extract more information during the process than done by default. .PP \fIDefining hooks\fR .IX Subsection "Defining hooks" .PP Multiple hooks can active during the compilation process of a type, when \f(CW\*(C`compile()\*(C'\fR is called. During Schema translation, each of the hooks is checked for all types which are processed. When multiple hooks select the object to get a modified behavior, then all are evaluated in order of definition. .PP Defining a \fBglobal\fR hook (where \s-1HOOKDATA\s0 is the \s-1LIST\s0 of \s-1PAIRS\s0 with hook parameters, and \s-1HOOK\s0 a \s-1HASH\s0 with such \s-1HOOKDATA\s0): .PP .Vb 5 \& my $schema = XML::Compile::Schema\->new \& ( ... \& , hook => HOOK \& , hooks => [ HOOK, HOOK ] \& ); \& \& $schema\->addHook(HOOKDATA | HOOK); \& $schema\->addHooks(HOOK, HOOK, ...); \& \& my $wsdl = XML::Compile::WSDL\->new(...); \& $wsdl\->addHook(HOOKDATA | HOOK); .Ve .PP \&\fBlocal\fR hooks are only used for one reader or writer. They are evaluated before the global hooks. .PP .Vb 2 \& my $reader = $schema\->compile(READER => $type \& , hook => HOOK, hooks => [ HOOK, HOOK, ...]); .Ve .PP \fIGeneral syntax\fR .IX Subsection "General syntax" .PP Each hook has three kinds of parameters: .IP ". selectors" 4 .IX Item ". selectors" .PD 0 .IP ". processors" 4 .IX Item ". processors" .IP ". action ('\s-1READER\s0' or '\s-1WRITER\s0', defaults to both)" 4 .IX Item ". action ('READER' or 'WRITER', defaults to both)" .PD .PP Selectors define the schema component of which the processing is modified. When one of the selectors matches, the processing information for the hook is used. When no selector is specified, then the hook will be used on all elements. .PP Available selectors (see below for details on each of them): .IP ". type" 4 .IX Item ". type" .PD 0 .IP ". extends" 4 .IX Item ". extends" .IP ". id" 4 .IX Item ". id" .IP ". path" 4 .IX Item ". path" .PD .PP As argument, you can specify one element as \s-1STRING,\s0 a regular expression to select multiple elements, or an \s-1ARRAY\s0 of STRINGs and REGEXes. .PP Next to where the hook is placed, we need to known what to do in the case: the hook contains processing information. When more than one hook matches, then all of these processors are called in order of hook definition. However, first the compile hooks are taken, and then the global hooks. .PP How the processing works exactly depends on the compiler back-end. There are major differences. Each of those manual-pages lists the specifics. The label tells us when the processing is initiated. Available labels are \&\f(CW\*(C`before\*(C'\fR, \f(CW\*(C`replace\*(C'\fR, and \f(CW\*(C`after\*(C'\fR. .PP \fIHooks on matching types\fR .IX Subsection "Hooks on matching types" .PP The \f(CW\*(C`type\*(C'\fR selector specifies a complexType of simpleType by name. Best is to base the selection on the full name, like \f(CW\*(C`{ns}type\*(C'\fR, which will avoid all kinds of name-space conflicts in the future. However, you may also specify only the \f(CW\*(C`local type\*(C'\fR (in any name-space). Any \s-1REGEX\s0 will be matched to the full type name. Be careful with the pattern archors. .PP If you use XML::Compile::Cache [release 0.90], then you can use \&\f(CW\*(C`prefix:type\*(C'\fR as type specification as well. You have to explicitly define prefix to namespace beforehand. .PP \fIHooks on extended type\fR .IX Subsection "Hooks on extended type" .PP [1.48] This hook will match all elements which use a type which is equal or based on the given type. In the schema, you will find extension and restriction constructs. You may only pass a single full type (no arrays of types or local names) per 'extend' hook. .PP Using a hooks on extended types is quite expensive for the compiler. .PP example: .PP .Vb 2 \& $schemas\->addHook(extends => "{ns}local", ...); \& $schemas\->addHook(extends => \*(Aqmine:sometype\*(Aq, ...); # need ::Cache .Ve .PP \fIHooks on matching ids\fR .IX Subsection "Hooks on matching ids" .PP Matching based on IDs can reach more schema elements: some types are anonymous but still have an \s-1ID.\s0 Best is to base selection on the full \&\s-1ID\s0 name, like \f(CW\*(C`ns#id\*(C'\fR, to avoid all kinds of name-space conflicts in the future. .PP \fIHooks on matching paths\fR .IX Subsection "Hooks on matching paths" .PP When you see error messages, you always see some representation of the path where the problem was discovered. You can use this path as selector, when you know what it is... \s-1BE WARNED,\s0 that the current structure of the path is not really consequent hence will be improved in one of the future releases, breaking backwards compatibility. .SS "Typemaps" .IX Subsection "Typemaps" Often, \s-1XML\s0 will be used in object oriented programs, where the facts which are transported in the \s-1XML\s0 message are attributes of Perl objects. Of course, you can always collect the data from each of the Objects into the required (huge) \s-1HASH\s0 manually, before triggering the reader or writer. As alternative, you can connect types in the \s-1XML\s0 schema with Perl objects and classes, which results in cleaner code. .PP You can also specify typemaps with new(typemap), \fBaddTypemaps()\fR, and compile(typemap). Each type will only refer to the last map for that type. When an \f(CW\*(C`undef\*(C'\fR is given for a type, then the older definition will be cancelled. Examples of the three ways to specify typemaps: .PP .Vb 2 \& my %map = ($x1 => $p1, $x2 => $p2); \& my $schema = XML::Compile::Schema\->new(...., typemap => \e%map); \& \& $schema\->addTypemaps($x3 => $p3, $x4 => $p4, $x1 => undef); \& \& my $call = $schema\->compile(READER => $type, typemap => \e%map); .Ve .PP The latter only has effect for the type being compiled. The definitions are cumulative. In the second example, the \f(CW$x1\fR gets disabled. .PP Objects can come in two shapes: either they do support the connection with XML::Compile (implementing two methods with predefined names), or they don't, in which case you will need to write a little wrapper. .PP .Vb 5 \& use XML::Compile::Util qw/pack_type/; \& my $t1 = pack_type $myns, $mylocal; \& $schema\->typemap($t1 => \*(AqMy::Perl::Class\*(Aq); \& $schema\->typemap($t1 => $some_object); \& $schema\->typemap($t1 => sub { ... }); .Ve .PP The implementation of the \s-1READER\s0 and \s-1WRITER\s0 differs. In the \s-1READER\s0 case, the typemap is implemented as an 'after' hook which calls a \f(CW\*(C`fromXML\*(C'\fR method. The \s-1WRITER\s0 is a 'before' hook which calls a \f(CW\*(C`toXML\*(C'\fR method. See respectively the XML::Compile::Translate::Reader and XML::Compile::Translate::Writer. .PP \fIPrivate variables in objects\fR .IX Subsection "Private variables in objects" .PP When you design a new object, it is possible to store the information exactly like the corresponding \s-1XML\s0 type definition. The only thing the \f(CW\*(C`fromXML\*(C'\fR has to do, is bless the data-structure into its class: .PP .Vb 4 \& $schema\->typemap($xmltype => \*(AqMy::Perl::Class\*(Aq); \& package My::Perl::Class; \& sub fromXML { bless $_[1], $_[0] } # for READER \& sub toXML { $_[0] } # for WRITER .Ve .PP However... the object may also need so need some private variables. If you store them in the same \s-1HASH\s0 for your object, you will get \&\*(L"unused tags\*(R" warnings from the writer. To avoid that, choose one of the following alternatives: .PP .Vb 2 \& # never complain about unused tags \& ::Schema\->new(..., ignore_unused_tags => 1); \& \& # only complain about unused tags not matching regexp \& my $not_for_xml = qr/^[A\-Z]/; # my XML only has lower\-case \& ::Schema\->new(..., ignore_unused_tags => $not_for_xml); \& \& # only for one compiled WRITER (not used with READER) \& ::Schema\->compile(..., ignore_unused_tags => 1); \& ::Schema\->compile(..., ignore_unused_tags => $not_for_xml); .Ve .PP \fITypemap limitations\fR .IX Subsection "Typemap limitations" .PP There are some things you need to know: .IP "." 4 Many schemas define very complex types. These may often not translate cleanly into objects. You may need to create a typemap relation for some parent type. The \s-1CODE\s0 reference may be very useful in this case. .IP "." 4 A same kind of problem appears when you have a list in your object, which often is not named in the schema. .SS "Handling xsi:type" .IX Subsection "Handling xsi:type" [1.10] The \f(CW\*(C`xsi:type\*(C'\fR is an old-fashioned mechanism, and should be avoided! In this case, the schema does tell you that a certain element has a certrain type, but at run\-time(!) that is changed. When an \s-1XML\s0 element has a \f(CW\*(C`xsi:type\*(C'\fR attribute, it tells you simply to have an extension of the original type. This whole mechanism does bite the \&\*(L"compilation\*(R" idea of XML::Compile... however with some help, it will work. .PP To make \f(CW\*(C`xsi:type\*(C'\fR work at run-time, you have to pass a table of which types you expect at compile-time. Example: .PP .Vb 4 \& my %xsi_type_table = \& ( $base_type1 => [ $ext1_of_type1, $ext2_of_type2 ] \& , $base_type2 => [ $ext1_of_type2 ] \& ); \& \& my $r = $schema\->compile(READER => $type \& , xsi_type => \e%xsi_type_table \& ); .Ve .PP When your schema is an XML::Compile::Cache (version at least 0.93), your types look like \f(CW\*(C`prefix:local\*(C'\fR. With a plain XML::Compile::Schema, they will look like \f(CW\*(C`{namespace}local\*(C'\fR, typically produced with \&\fBXML::Compile::Util::pack_type()\fR. .PP When used in a reader, the resulting data-set will contain a \f(CW\*(C`XSI_TYPE\*(C'\fR key inbetween the facts which were taken from the element. The type is is long syntax \f(CW"{$ns}$type"\fR. See \fBXML::Compile::Util::unpack_type()\fR .PP With the writer, you have to provide such an \f(CW\*(C`XSI_TYPE\*(C'\fR value or the element's base type will be used (and no \f(CW\*(C`xsi:type\*(C'\fR attribute created). This will probably cause warnings about unused tags. The type can be provided in full (see \fBXML::Compile::Util::pack_type()\fR) or [1.31] prefixed. .PP [1.25] then the value is not an \s-1ARRAY,\s0 but only the keyword \f(CW\*(C`AUTO\*(C'\fR, the parser will try to auto-detect all types which are valid alternatives. This currently only works for non-builtin types. The auto-detection might be slow and (because many schemas are broken) not produce a complete list. When debugging is enabled (\*(L"use Log::Report mode => 3;\*(R") you will see to which list this \s-1AUTO\s0 gets expanded. .PP .Vb 1 \& xsi_type => { $base_type => \*(AqAUTO\*(Aq } # requires X::C v1.25 .Ve .PP XML::Compile::Cache (since v1.01) makes using \f(CW\*(C`xsi:type\*(C'\fR easier. When you have a ::Cache based object (for instance a XML::Compile::WSDL11) you can simply say .PP .Vb 1 \& $wsdl\->addXsiType( $base_type => \*(AqAUTO\*(Aq ) .Ve .PP Now, you do not need to pass the xsi table to each compilation call. .SS "Key rewrite" .IX Subsection "Key rewrite" [improved with release 1.10] The standard practice is to use the localName of the \s-1XML\s0 elements as key in the Perl \s-1HASH\s0; the key rewrite mechanism is used to change that, sometimes to separate elements which have the same localName within different name-spaces, or when an element and an attribute share a name (key rewrite is applied to elements \s-1AND\s0 attributes) in other cases just for fun or convenience. .PP Rewrite rules are interpreted at \*(L"compile-time\*(R", which means that they \&\fBdo not slow-down\fR the \s-1XML\s0 construction or deconstruction. The rules work the same for readers and writers, because they are applied to name found in the schema. .PP Key rewrite rules can be set during schema object initiation with new(key_rewrite) and to an existing schema object with \&\fBaddKeyRewrite()\fR. These rules will be used in all calls to \&\fBcompile()\fR. .PP Next, you can use compile(key_rewrite) to add rules which are only used for a single compilation. These are applied before the global rules. All rules will always be attempted, and the rulle will me applied to the result of the previous change. .PP The last defined rewrite rules will be applied first, with one major exception: the \f(CW\*(C`PREFIXED\*(C'\fR rules will be executed before any other rule. .PP \fIkey_rewrite via table\fR .IX Subsection "key_rewrite via table" .PP When a \s-1HASH\s0 is provided as rule, then the \s-1XML\s0 element name is looked-up. If found, the value is used as translated key. .PP First full name of the element is tried, and then the localName of the element. The full name can be created with \&\fBXML::Compile::Util::pack_type()\fR or by hand: .PP .Vb 1 \& use XML::Compile::Util qw/pack_type/; \& \& my %table = \& ( pack_type($myns, \*(Aqel1\*(Aq) => \*(Aqnice_name1\*(Aq \& , "{$myns}el2" => \*(AqalsoNice\*(Aq \& , el3 => \*(Aqin any namespace\*(Aq \& ); \& $schema\->addKeyRewrite( \e%table ); .Ve .PP \fIRewrite via function\fR .IX Subsection "Rewrite via function" .PP When a \s-1CODE\s0 reference is provided, it will get called for each key which is found in the schema. Passed are the name-space of the element and its local-name. Returned is the key, which may be the local-name or something else. .PP For instance, some people use capitals in element names and personally I do not like them: .PP .Vb 5 \& sub dont_like_capitals($$) \& { my ($ns, $local) = @_; \& lc $local; \& } \& $schema\->addKeyRewrite( \e&dont_like_capitals ); .Ve .PP for short: .PP .Vb 2 \& my $schema = XML::Compile::Schema\->new( ..., \& key_rewrite => sub { lc $_[1] } ); .Ve .PP \fIkey_rewrite when localNames collide\fR .IX Subsection "key_rewrite when localNames collide" .PP Let's start with an apology: we cannot auto-detect when these rewrite rules are needed, because the colliding keys are within the same \s-1HASH,\s0 but the processing is fragmented over various (sequence) blocks: the parser does not have the overview on which keys of the \s-1HASH\s0 are used for which elements. .PP The problem occurs when one complex type or substitutionGroup contains multiple elements with the same localName, but from different name-spaces. In the perl representation of the data, the name-spaces get ignored (to make the programmer's life simple) but that may cause these nasty conflicts. .PP \fIRewrite for convenience\fR .IX Subsection "Rewrite for convenience" .PP In \s-1XML,\s0 we often see names like \f(CW\*(C`my\-elem\-name\*(C'\fR, which in Perl would be accessed as .PP .Vb 1 \& $h\->{\*(Aqmy\-elem\-name\*(Aq} .Ve .PP In this case, you cannot leave-out the quotes in your perl code, which is quite inconvenient, because only 'barewords' can be used as keys unquoted. When you use option \f(CW\*(C`key_rewrite\*(C'\fR for \fBcompile()\fR or \fBnew()\fR, you could decide to map dashes onto underscores. .PP .Vb 2 \& key_rewrite \& => sub { my ($ns, $local) = @_; $local =~ s/\e\-/_/g; $local } \& \& key_rewrite => sub { $_[1] =~ s/\e\-/_/g; $_[1] } .Ve .PP then \f(CW\*(C`my\-elem\-name\*(C'\fR in \s-1XML\s0 will get mapped onto \f(CW\*(C`my_elem_name\*(C'\fR in Perl, both in the \s-1READER\s0 as the \s-1WRITER.\s0 Be warned that the substitute command returns the success, not the modified value! .PP \fIPre-defined key_rewrite rules\fR .IX Subsection "Pre-defined key_rewrite rules" .IP "\s-1UNDERSCORES\s0" 4 .IX Item "UNDERSCORES" Replace dashes (\-) with underscores (_). .IP "\s-1SIMPLIFIED\s0" 4 .IX Item "SIMPLIFIED" Rewrite rule with the constant name (\s-1STRING\s0) \f(CW\*(C`SIMPLIFIED\*(C'\fR will replace all dashes with underscores, translate capitals into lowercase, and remove all other characters which are none-bareword (if possible, I am too lazy to check) .IP "\s-1PREFIXED\s0" 4 .IX Item "PREFIXED" This requires a table for prefix to name-space translations, via compile(prefixes), which defines at least one non-empty (default) prefix. The keys which represent elements in any name-space which has a prefix defined will have that prefix and an underscore prepended. .Sp Be warned that the name-spaces which you provide are used, not the once used in the schema. Example: .Sp .Vb 5 \& my $r = $schema\->compile \& ( READER => $type \& , prefixes => [ mine => $myns ] \& , key_rewrite => \*(AqPREFIXED\*(Aq \& ); \& \& my $xml = $r\->( <<_\|_XML ); \&42 \&_\|_XML \& \& print join \*(Aq => \*(Aq, %$xml; # mine_x => 42 .Ve .IP "\s-1PREFIXED\s0(...)" 4 .IX Item "PREFIXED(...)" Like the previous, but now only use a selected sub-set of the available prefixes. This is particular useful in writers, when explicit prefixes are also used to beautify the output. .Sp The prefixes are not checked against the prefix list, and may have surrounding blanks. .Sp .Vb 1 \& key_rewrite => \*(AqPREFIXED(opt,sar)\*(Aq .Ve .Sp Above is equivalent to: .Sp .Vb 1 \& key_rewrite => [ \*(AqPREFIXED(opt)\*(Aq, \*(AqPREFIXED(sar)\*(Aq ] .Ve .Sp Special care is taken that the prefix will not be added twice. For instance, if the same prefix appears twice, or a \f(CW\*(C`PREFIXED\*(C'\fR rule is provided as well, then still only one prefix is added. .SH "SEE ALSO" .IX Header "SEE ALSO" This module is part of XML-Compile distribution version 1.63, built on July 02, 2019. Website: \fIhttp://perl.overmeer.net/xml\-compile/\fR .SH "LICENSE" .IX Header "LICENSE" Copyrights 2006\-2019 by [Mark Overmeer ]. For other contributors see ChangeLog. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See \fIhttp://dev.perl.org/licenses/\fR