| XML::Compile::Cache(3pm) | User Contributed Perl Documentation | XML::Compile::Cache(3pm) |
XML::Compile::Cache - Cache compiled XML translators
XML::Compile::Cache is a XML::Compile::Schema is a XML::Compile
my $cache = XML::Compile::Cache->new(...);
$cache->declare('READER', $type, @options);
$cache->declare(RW => \@types, @options);
$cache->declare(WRITER => $type, \@options);
$cache->compileAll;
$cache->compileAll('RW');
# get the cached code ref for the reader
my $reader = $cache->reader($type, @opts);
use Data::Dumper;
print Dumper $reader->($xml);
# get the cached code ref for the writer, and use it
my $doc = XML::LibXML::Document->new('1.0', 'UTF-8');
my $xml = $cache->writer($type)->($doc, $perl);
print $xml->toString(1);
# use the base-class uncached, the XML::Compile::Schema
my $do = $cache->compile(READER => $type, @opts);
Extends "DESCRIPTION" in XML::Compile::Schema.
Extends "METHODS" in XML::Compile::Schema.
Extends "Constructors" in XML::Compile::Schema.
-Option --Defined in --Default
allow_undeclared <false>
any_element 'ATTEMPT'
block_namespace XML::Compile::Schema []
hook XML::Compile::Schema undef
hooks XML::Compile::Schema []
ignore_unused_tags XML::Compile::Schema <false>
key_rewrite XML::Compile::Schema []
opts_readers []
opts_rw []
opts_writers []
parser_options XML::Compile <many>
prefixes <smart>
schema_dirs XML::Compile undef
typemap {}
xsi_type {}
[1.02] the default is to ATTEMPT compiling any handlers automatically. Before version 1.02, the default was to SKIP_ALL elements which would match the occurs and namespace restrictions of the any specification. However, that fails for reperative blocks (for instance, it fails for an choice which may occur unbounded times)
Specify an ARRAY of (prefix, name-space) pairs, or a HASH which maps name-spaces to prefixes (HASH order is reversed from ARRAY order!) When you wish to collect the results, like usage counts, of the translation processing, you will need to specify a HASH.
prefixes => [ mine => $myns, your => $yourns ]
prefixes => { $myns => 'mine', $yourns => 'your' }
# the previous is short for:
prefixes => { $myns => [ uri => $myns, prefix => 'mine', used => 0 ]
, $yourns => [ uri => $yourns, prefix => 'your', ...] }
Extends "Accessors" in XML::Compile::Schema.
The value component can be 'AUTO' to automatically detect the "xsi:type" extensions. This does only work for complex types.
Reader: "ATTEMPT" will convert all any elements, applying the reader for each element found. When an element is not found in a schema, it will be included as XML::LibXML::Element node.
[0.93] Reader: With "SLOPPY", first automatic typed conversion is attempted. But is the type is not known, XML::LibXML::Simple::XMLin() is called to the resque.
The cache layer on top of XML::Compile::Schema adds smart use of prefixes. Of course, smartness comes with a small performance cost, but the code gets much cleaner.
When the BASE already ends on a number, that number will get counted.
example:
my $prefix = $schema->addNicePrefix('call', $myns);
# $prefix now can be call, call01, call02 etc
The best way to add prefixes is via new(prefixes), which will give your names preference over the names found in the schema's which get loaded. For instance, use "::WSDL->new(prefixes => [ $prefix => $ns ]"
[0.995] Returns the HASH with prefix to name-space translations. You should not modify the returned HASH: new PAIRS of prefix to namespace relations can be passed as arguments.
[0.14] If a name-space appears for the second time, then the new prefix will be recognized by findName(), but not used in the output. When the prefix already exists for a different namespace, then an error will be casted.
[0.90] You may also provide an ARRAY of pairs or a HASH.
[0.993] When your $type is not in packed form, you can specify a namespace and $local type name as separate arguments.
example:
print $schema->prefixed($type) || $type;
print $schema->prefixed($ns, $local);
The name of this module refers to its power to administer compiled XML encoders (writers) and decoders (readers). This means that your program only need to pass on a ::Cache object (for instance a XML::Compile::WSDL11, not a CODE reference for each compiled translator.
Extends "Compilers" in XML::Compile::Schema.
By default, the processors are only compiled when used. This method is especially useful in a daemon process, where preparations can take as much time as they want to... and running should be as fast as possible.
The reader will be compiled the first time that it is used, and that same CODE reference will be returned each next request for the same $type. Call compileAll() to have all readers compiled by force.
-Option --Default
is_type <false>
example:
my $schema = XML::Compile::Cache->new(\@xsd,
prefixes => [ gml => $GML_NAMESPACE ] );
my $data = $schema->reader('gml:members')->($xml);
my $getmem = $schema->reader('gml:members');
my $data = $getmem->($xml);
The writer will be compiled the first time that it is used, and that same CODE reference will be returned each next request for the same type.
-Option --Default
is_type <false>
example:
my $xml = $cache->writer('gml:members')->($doc, $data);
my $doc = XML::LibXML::Document->new('1.0', 'UTF-8');
my $wr = $cache->writer('gml:members');
my $xml = $wr->($doc, $data);
$doc->setDocumentElement($xml);
print $doc->toString(1);
Extends "Administration" in XML::Compile::Schema.
The $type should be understood by findName(), so may be prefixed.
example:
$cache->declare(READER => 'pref:count', sloppy_integers => 1)
->declare(RW => '{myns}mylocal');
$cache->declare(WRITER => [ 'xsd:int', '{http://}aap' ]);
When the form is 'myns:' (so without local name), the namespace uri is returned.
example: of findName()
$schema->addPrefixes(pre => 'http://namespace');
my $type = $schema->findName('pre:name');
print $type; # {http://namespace}name
my $ns = $schema->findName('pre:');
print $ns; # http://namespace
my $type = $schema->findName('{somens}name');
print $type; # {somens}name [a no-op]
-Option --Default
show_declared <true>
Extends "DETAILS" in XML::Compile::Schema.
"XML::Compile::Cache" is the smart brother of XML::Compile::Schema; it keeps track of your compiled readers and writers, and also helps you administer the parameters to handle compilation. Besides, it lat you use easy prefixes instead of full namespaces.
With XML::Compile::Schema::compile() (defined in the SUPER class of this module) you can construct translators from XML to Perl and back. These translators are code references, which are "expensive" to create, but "cheap" in use; call them as often as you want. This module helps you administer them.
When the schemas grow larger, it gets harder to see which code reference have already be created and which not. And, these code references need compile options which you do not want to distribute over your whole program. Finally, in a daemon application, you do not want to create the translators when used (which can be in every client again), but once during the initiation of the daemon.
One of the most important contributions to the compile management, is the addition of smart prefix handling. This means that you can use prefixed names in stead of full types, often created with XML::Compile::Util::pack_type().
This module is part of XML-Compile-Cache distribution version 1.06, built on March 04, 2018. Website: http://perl.overmeer.net/xml-compile/
Copyrights 2008-2018 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/
| 2018-03-20 | perl v5.26.1 |