=head1 NAME

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

=head1 INHERITANCE

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

=head1 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 $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);

=head1 DESCRIPTION

=head1 METHODS

=head2 Constructors

XML::Compile::Cache-E<gt>B<new>(OPTIONS)

=over 4

 Option            --Defined in     --Default
 allow_undeclared                     <false>
 any_attribute                        'SKIP_ALL'
 any_element                          'SKIP_ALL'
 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

=over 4

When true, you may call the reader or writer with types which were
not registered with L<declare()|XML::Compile::Cache/"Administration">.  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.

=back

. any_attribute => CODE|'TAKE_ALL'|'SKIP_ALL'|'ATTEMPT'

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

=over 4

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

=back

. 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

=over 4

Options added to both READERs and WRITERS.  Options which are passed
with L<declare()|XML::Compile::Cache/"Administration"> and C<opts_readers> or C<opts_writers> will overrule
these.

=back

. opts_writers => HASH|ARRAY-of-PAIRS

. prefixes => HASH|ARRAY-of-PAIRS

=over 4

Define prefix name to name-space mappings.  Passed to L<compile(prefixes)|XML::Compile::Schema/"Compilers">
for each reader and writer, but also used to permit L<findName()|XML::Compile::Cache/"Administration"> 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', ...] }

=back

. schema_dirs => DIRECTORY|ARRAY-OF-DIRECTORIES

. typemap => HASH

=back

=head2 Accessors

$obj-E<gt>B<addHook>(HOOKDATA|HOOK|undef)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<addHooks>(HOOK, [HOOK, ...])

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<addKeyRewrite>(CODE|HASH, CODE|HASH, ...)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<addSchemaDirs>(DIRECTORIES|FILENAME)

XML::Compile::Cache-E<gt>B<addSchemaDirs>(DIRECTORIES|FILENAME)

=over 4

See L<XML::Compile/"Accessors">

=back

$obj-E<gt>B<addSchemas>(XML, OPTIONS)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<addTypemap>(PAIR)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<addTypemaps>(PAIRS)

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<allowUndeclared>([BOOLEAN])

=over 4

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

=back

$obj-E<gt>B<hooks>

=over 4

See L<XML::Compile::Schema/"Accessors">

=back

$obj-E<gt>B<prefixes>([PAIRS])

=over 4

Returns the HASH with prefix to name-space translations.  You should not
modify the returned HASH, but can provide PAIRS of additional prefix to
namespace relations.

=back

=head2 Compilers

$obj-E<gt>B<compile>(('READER'|'WRITER'), TYPE, OPTIONS)

=over 4

See L<XML::Compile::Schema/"Compilers">

=back

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

=over 4

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.

=back

$obj-E<gt>B<dataToXML>(NODE|REF-XML-STRING|XML-STRING|FILENAME|FILEHANDLE|KNOWN)

=over 4

See L<XML::Compile/"Compilers">

=back

$obj-E<gt>B<reader>(TYPE|NAME, OPTIONS)

=over 4

Returns the reader for the TYPE, which may be specified as prefixed NAME
(see L<findName()|XML::Compile::Cache/"Administration">).  OPTIONS are only permitted if L<new(allow_undeclared)|XML::Compile::Cache/"Constructors">
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.

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

=back

$obj-E<gt>B<template>('XML'|'PERL', TYPE, OPTIONS)

=over 4

See L<XML::Compile::Schema/"Compilers">

=back

$obj-E<gt>B<writer>(TYPE|NAME)

=over 4

Returns the writer for the TYPE, which may be specified as prefixed NAME
(see L<findName()|XML::Compile::Cache/"Administration">).  OPTIONS are only permitted if L<new(allow_undeclared)|XML::Compile::Cache/"Constructors">
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);

=back

=head2 Administration

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

=over 4

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 L<findName()|XML::Compile::Cache/"Administration">, so may be prefixed.

example: 

  $cache->declare(READER => 'pref:count', sloppy_integers => 1)
        ->declare(RW     => '{myns}mylocal');

  $cache->declare(WRITER => [ 'xsd:int', '{http://}aap' ]);

=back

$obj-E<gt>B<elements>

=over 4

See L<XML::Compile::Schema/"Administration">

=back

$obj-E<gt>B<findName>(NAME)

=over 4

Translate the NAME specification into a schema type.  The NAME
can be a full type (like '{namespace}localname', usually created
with L<XML::Compile::Util::pack_type()|XML::Compile::Util/"Packing">) or a prefixed type (like
'myms:localname', defined with L<new(prefixes)|XML::Compile::Cache/"Constructors"> or L<prefixes()|XML::Compile::Cache/"Accessors">).

=back

$obj-E<gt>B<findSchemaFile>(FILENAME)

=over 4

See L<XML::Compile/"Administration">

=back

$obj-E<gt>B<importDefinitions>(XMLDATA, OPTIONS)

=over 4

See L<XML::Compile::Schema/"Administration">

=back

$obj-E<gt>B<knownNamespace>(NAMESPACE|PAIRS)

XML::Compile::Cache-E<gt>B<knownNamespace>(NAMESPACE|PAIRS)

=over 4

See L<XML::Compile/"Administration">

=back

$obj-E<gt>B<namespaces>

=over 4

See L<XML::Compile::Schema/"Administration">

=back

$obj-E<gt>B<printIndex>([FILEHANDLE], OPTIONS)

=over 4

 Option       --Default
 show_declared  <true>

. show_declared => BOOLEAN

=over 4

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

=back

=back

$obj-E<gt>B<types>

=over 4

See L<XML::Compile::Schema/"Administration">

=back

$obj-E<gt>B<walkTree>(NODE, CODE)

=over 4

See L<XML::Compile/"Administration">

=back

=head1 DETAILS

=head1 DIAGNOSTICS

Error: cannot find pre-installed name-space files

=over 4

Use C<$ENV{SCHEMA_LOCATION}> or L<new(schema_dirs)|XML::Compile/"Constructors"> to express location
of installed name-space files, which came with the L<XML::Compile|XML::Compile>
distribution package.

=back

Error: don't known how to interpret XML data

=over 4

=back

=head1 SEE ALSO

This module is part of XML-Compile-Cache distribution version 0.13,
built on August 01, 2008. Website: F<http://perl.overmeer.net/xml-compile/>

All modules in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Rewrite>,
L<XML::Compile::Dumper>.

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

=head1 LICENSE

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