The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XML-Compile-Cache-0.995
River stage two • 20 direct dependents • 54 total dependents
1 ++
/ XML::Compile::Cache

NAME

XML::Compile::Cache - Cache compiled XML translators

INHERITANCE

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

SYNOPSIS

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

DESCRIPTION

See documentation in the base class.

METHODS

See documentation in the base class.

Constructors

See documentation in the base class.

XML::Compile::Cache->new(OPTIONS)
 -Option            --Defined in          --Default
  allow_undeclared                          <false>
  any_element                               'SKIP_ALL'
  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                                  {}
allow_undeclared => BOOLEAN

When true, you may call the reader or writer with types which were not registered with declare(). In that case, the reader or writer may also get options passed for the compiler, as long as they are consistent over each use of the type.

any_element => CODE|'TAKE_ALL'|'SKIP_ALL'|'ATTEMPT'|'SLOPPY'

See anyElement().

block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY
hook => ARRAY-WITH-HOOKDATA | HOOK
hooks => ARRAY-OF-HOOK
ignore_unused_tags => BOOLEAN|REGEXP
key_rewrite => HASH|CODE|ARRAY-of-HASH-and-CODE
opts_readers => HASH|ARRAY-of-PAIRS
opts_rw => HASH|ARRAY-of-PAIRS

Options added to both READERs and WRITERS. Options which are passed with declare() and opts_readers or opts_writers will overrule these. See addCompileOptions().

opts_writers => HASH|ARRAY-of-PAIRS
parser_options => HASH|ARRAY
prefixes => HASH|ARRAY-of-PAIRS

Define prefix name to name-space mappings. Passed to compile(prefixes) for each reader and writer, but also used to permit findName() to accept types which use a prefix.

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', ...] }
schema_dirs => DIRECTORY|ARRAY-OF-DIRECTORIES
typemap => HASH|ARRAY
xsi_type => HASH|ARRAY

Accessors

See documentation in the base class.

$obj->addHook(HOOKDATA|HOOK|undef)

See "Accessors" in XML::Compile::Schema

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

See "Accessors" in XML::Compile::Schema

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

See "Accessors" in XML::Compile::Schema

$obj->addSchemaDirs(DIRECTORIES|FILENAME)
XML::Compile::Cache->addSchemaDirs(DIRECTORIES|FILENAME)

See "Accessors" in XML::Compile

$obj->addSchemas(XML, OPTIONS)

See "Accessors" in XML::Compile::Schema

$obj->addTypemap(PAIR)

See "Accessors" in XML::Compile::Schema

$obj->addTypemaps(PAIRS)

See "Accessors" in XML::Compile::Schema

$obj->allowUndeclared([BOOLEAN])

Whether it is permitted to create readers and writers which are not declared cleanly.

$obj->anyElement('ATTEMPT'|'SLOPPY'|'SKIP_ALL'|'TAKE_ALL'|CODE)

[as method since 0.99] How to process ANY elements, see also new(any_element).

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.

$obj->blockNamespace(NAMESPACE|TYPE|HASH|CODE|ARRAY)

See "Accessors" in XML::Compile::Schema

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

See "Accessors" in XML::Compile::Schema

$obj->typemap([HASH|ARRAY|PAIRS])

[0.98] Add global knowledge on typemaps. Returns the typemap.

$obj->useSchema(SCHEMA, [SCHEMA])

See "Accessors" in XML::Compile::Schema

$obj->xsiType([HASH|ARRAY|LIST])

[0.98] add global xsi_type declarations. Returns the xsiType set. The ARRAY or LIST contains pairs, just like the HASH.

The value component can be 'AUTO' to automatically detect the xsi:type extensions. This does only work for complex types.

Prefix management

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.

$obj->addPrefixes([PAIRS|ARRAY|HASH])

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

$obj->learnPrefixes(NODE)

[0.993] Take all the prefixes defined in the NODE, and XML::LibXML::Element. This is not recursive: only on those defined at the top NODE.

$obj->prefix(PREFIX)

Lookup a prefix definition. This returns a HASH with namespace info.

$obj->prefixFor(URI)

Lookup the preferred prefix for the URI.

$obj->prefixed(TYPE|(NAMESPACE,LOCAL))

Translate the fully qualified TYPE into a prefixed version. Will produce undef if the namespace is unknown.

[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);
$obj->prefixes([PARAMS])

Return prefixes table. The PARAMS are deprecated since [0.995], see addPrefixes().

Compilers

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.

See documentation in the base class.

$obj->addCompileOptions(['READERS'|'WRITERS'|'RW'], OPTIONS)

[0.99] You may provide global compile options with new(opts_rw), opts_readers and opts_writers, but also later using this method.

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

See "Compilers" in XML::Compile::Schema

$obj->compileAll(['READERS'|'WRITERS'|'RW', [NAMESPACE]])

Compile all the declared readers and writers with the default 'RW'). You may also select to pre-compile only the READERS or only the WRITERS. The selection can be limited further by specifying a NAMESPACE.

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.

$obj->dataToXML(NODE|REF-XML-STRING|XML-STRING|FILENAME|FILEHANDLE|KNOWN)
XML::Compile::Cache->dataToXML(NODE|REF-XML-STRING|XML-STRING|FILENAME|FILEHANDLE|KNOWN)

See "Compilers" in XML::Compile

$obj->initParser(OPTIONS)
XML::Compile::Cache->initParser(OPTIONS)

See "Compilers" in XML::Compile

$obj->reader(TYPE|NAME, OPTIONS)

Returns the reader CODE for the TYPE or NAME (see findName()). OPTIONS are only permitted if new(allow_undeclared) is true, and the same as the previous call to this method.

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.

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);
$obj->template('XML'|'PERL'|'TREE', ELEMENT, OPTIONS)

See "Compilers" in XML::Compile::Schema

$obj->writer(TYPE|NAME)

Returns the writer CODE for the TYPE or NAME (see findName()). OPTIONS are only permitted if new(allow_undeclared) is true, and the same as the previous call to this method.

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.

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

Administration

See documentation in the base class.

$obj->declare('READER'|'WRITER'|'RW', TYPE|ARRAY-of-TYPES, OPTIONS)

Register that the indicated TYPE (or TYPES) may be used, and needs to be translated with the OPTIONS (either specified as ARRAY or LIST). Specify whether it may get used as READER, WRITER, or both (RW). If the READER and WRITER need different options, then you need to declare them separately; in that case you cannot use RW.

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' ]);
$obj->doesExtend(EXTTYPE, BASETYPE)

See "Administration" in XML::Compile::Schema

$obj->elements()

See "Administration" in XML::Compile::Schema

$obj->findName(NAME)

Translate the NAME specification into a schema defined full type. The NAME can be a full type (like '{namespace}localname', usually created with XML::Compile::Util::pack_type()) or a prefixed type (like 'myns:localname', where myns is defined via new(prefixes) or prefixes()).

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]
$obj->findSchemaFile(FILENAME)
XML::Compile::Cache->findSchemaFile(FILENAME)

See "Administration" in XML::Compile

$obj->importDefinitions(XMLDATA, OPTIONS)

See "Administration" in XML::Compile::Schema

$obj->knownNamespace(NAMESPACE|PAIRS)
XML::Compile::Cache->knownNamespace(NAMESPACE|PAIRS)

See "Administration" in XML::Compile

$obj->namespaces()

See "Administration" in XML::Compile::Schema

$obj->printIndex([FILEHANDLE], OPTIONS)
 -Option       --Default
  show_declared  <true>
show_declared => BOOLEAN

Add an indicator to each line, about whether readers and writers are declare for the type. Declared readers and writers will show flags r and w respectively. Compiled readers and writers carry a R and/or W.

$obj->types()

See "Administration" in XML::Compile::Schema

$obj->walkTree(NODE, CODE)

See "Administration" in XML::Compile

DETAILS

See documentation in the base class.

DESCRIPTIONS

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

SEE ALSO

This module is part of XML-Compile-Cache distribution version 0.995, built on August 10, 2013. Website: http://perl.overmeer.net/xml-compile/

Other distributions in this suite: XML::Compile, XML::Compile::SOAP, XML::Compile::SOAP12, XML::Compile::SOAP::Daemon, XML::Compile::SOAP::WSA, XML::Compile::C14N, XML::Compile::WSS, XML::Compile::WSS::Signature, XML::Compile::Tester, XML::Compile::Cache, XML::Compile::Dumper, XML::Compile::RPC, XML::Rewrite and XML::LibXML::Simple.

Please post questions or ideas to the mailinglist at http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile . For live contact with other developers, visit the #xml-compile channel on irc.perl.org.

LICENSE

Copyrights 2008-2013 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://www.perl.com/perl/misc/Artistic.html