Provided by: libxml-compile-cache-perl_1.06-1_all bug

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

       Extends "DESCRIPTION" in XML::Compile::Schema.

METHODS

       Extends "METHODS" in XML::Compile::Schema.

   Constructors
       Extends "Constructors" in XML::Compile::Schema.

       XML::Compile::Cache->new( [$xml], %options )
            -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                                  {}

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

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

           block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY
           hook => $hook|ARRAY
           hooks => ARRAY
           ignore_unused_tags => BOOLEAN|REGEXP
           key_rewrite => HASH|CODE|ARRAY
           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
       Extends "Accessors" in XML::Compile::Schema.

       $obj->addHook($hook|LIST|undef)
           Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addHooks( $hook, [$hook, ...] )
           Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addKeyRewrite($predef|CODE|HASH, ...)
           Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addSchemaDirs(@directories|$filename)
       XML::Compile::Cache->addSchemaDirs(@directories|$filename)
           Inherited, see "Accessors" in XML::Compile

       $obj->addSchemas($xml, %options)
           Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addTypemap(PAIR)
           Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addTypemaps(PAIRS)
           Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addXsiType( [HASH|ARRAY|LIST] )
           [1.01] 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.

       $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($ns|$type|HASH|CODE|ARRAY)
           Inherited, see "Accessors" in XML::Compile::Schema

       $obj->hooks( [<'READER'|'WRITER'>] )
           Inherited, 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, ...] )
           Inherited, see "Accessors" in XML::Compile::Schema

   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->addNicePrefix(BASE, NAMESPACE)
           [1.03] Register NAMESPACE -if not yet defined- with prefix name BASE.  When that
           prefix name is already in use for some other namespace, BASE followed by a number are
           attempted (starting with 01).  The prefix is returned.

           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

       $obj->addPrefixes( [PAIRS|ARRAY|HASH] )
           The X::C logic does auto-detect prefix/namespaces combinations from the XML, but does
           not search extensively for namespace declarations.  Also, sometimes the same namespace
           is used with different prefixes.  Sometimes, the same prefix is used for different
           namesapces.  To complete the list, or control the actual prefix being used, you
           explicitly declare combinations.

           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.

       $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|<$ns,$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.

       Extends "Compilers" in XML::Compile::Schema.

       $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 )
           Inherited, see "Compilers" in XML::Compile::Schema

       $obj->compileAll( ['READERS'|'WRITERS'|'RW', [$ns]] )
           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 $ns.

           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->compileType( <'READER'|'WRITER'>, $type, %options )
           Inherited, see "Compilers" in XML::Compile::Schema

       $obj->dataToXML( $node|REF-XML|XML-STRING|$filename|$fh|$known )
       XML::Compile::Cache->dataToXML( $node|REF-XML|XML-STRING|$filename|$fh|$known )
           Inherited, see "Compilers" in XML::Compile

       $obj->initParser(%options)
       XML::Compile::Cache->initParser(%options)
           Inherited, 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.

            -Option --Default
             is_type  <false>

           is_type => BOOLEAN
             [1.03] use compileType() with the given element, to replace compile() You probably
             want an additional "element" parameter.

           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 )
           Inherited, 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.

            -Option --Default
             is_type  <false>

           is_type => BOOLEAN
             [1.03] use compileType() with the given element, to replace compile() You probably
             want an additional "element" parameter.

           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
       Extends "Administration" in XML::Compile::Schema.

       $obj->declare( <'READER'|'WRITER'|'RW'>, <$type|ARRAY>, %options )
           Register that the indicated $type (or ARRAY of them) may be used, and needs to be
           translated with the %options (either specified as ARRAY or PAIRS).  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)
           Inherited, see "Administration" in XML::Compile::Schema

       $obj->elements()
           Inherited, 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)
           Inherited, see "Administration" in XML::Compile

       $obj->importDefinitions($xmldata, %options)
           Inherited, see "Administration" in XML::Compile::Schema

       $obj->knownNamespace($ns|PAIRS)
       XML::Compile::Cache->knownNamespace($ns|PAIRS)
           Inherited, see "Administration" in XML::Compile

       $obj->namespaces()
           Inherited, see "Administration" in XML::Compile::Schema

       $obj->printIndex( [$fh], %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()
           Inherited, see "Administration" in XML::Compile::Schema

       $obj->walkTree($node, CODE)
           Inherited, see "Administration" in XML::Compile

DETAILS

       Extends "DETAILS" in XML::Compile::Schema.

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 1.06, built on March 04,
       2018. Website: http://perl.overmeer.net/xml-compile/

LICENSE

       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/