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

METHODS

Constructors

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                         []
 prefixes                             <smart>
 schema_dirs         XML::Compile     undef
 typemap             XML::Compile::Schema  {}

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

ATTEMPT will convert all any elements, applying the reader for each element found.

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

. opts_writers => HASH|ARRAY-of-PAIRS

. 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

Accessors

$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->blockNamespace(NAMESPACE|TYPE|HASH|CODE|ARRAY)

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

$obj->hooks

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

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

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

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

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.

[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->useSchema(SCHEMA, [SCHEMA])

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

Compilers

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

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

$obj->compileAll(['READER'|'WRITER'|'RW', [NAMESPACE]])

Compile all the declared readers and writers (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.

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

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', TYPE, 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

$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 seperately; 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->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->prefixes(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

DIAGNOSTICS

Error: cannot find pre-installed name-space files

Use $ENV{SCHEMA_LOCATION} or new(schema_dirs) to express location of installed name-space files, which came with the XML::Compile distribution package.

Error: don't known how to interpret XML data

SEE ALSO

This module is part of XML-Compile-Cache distribution version 0.92, built on May 28, 2009. Website: http://perl.overmeer.net/xml-compile/

All modules in this suite: XML::Compile, XML::Compile::SOAP, XML::Compile::SOAP12, XML::Compile::SOAP::Daemon, XML::Compile::Tester, XML::Compile::Cache, XML::Compile::Dumper, 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 life contact with other developers, visit the #xml-compile channel on irc.perl.org.

LICENSE

Copyrights 2008-2009 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