XML::C...::Cache(3pm)

📦
version 1.06 · 3 versions
, in ubuntu jammy, ubuntu noble

✨ NAME ✨

XML::Compile::Cache — Cache compiled XML translators 💅

okay so real talk, this is the XML::C...::Cache(3pm) page from the User Contributed Perl Documentation crowd, and bestie, it's a whole personality. let's go 🫶

🧬 INHERITANCE 🧬

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

it's giving "family tree of slay" — your girl inherits from XML::Compile::Schema, which itself 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);

look at that. compile once, reuse forever. main character energy, no cap 👑

🦋 DESCRIPTION 🦋

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

that's literally the whole description, bestie. short and iconic, she said "go read my parent page, iykyk" 🌸

🛠 METHODS 🛠

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

🎀 Constructors

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

XML::Compile::Cache->new( [$xml], %options )

here's the full option table, verbatim, because we do not skip the boring parts in this house:

-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                                  {}

and now, one by one, like the little icons they are 💖

  • allow_undeclared => BOOLEAN — when it's 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 — inherited straight from XML::Compile::Schema, no extra tea spilled on this page 🍓
  • hook => $hook|ARRAY — also from XML::Compile::Schema, same deal 💜
  • hooks => ARRAY — yep, XML::Compile::Schema again 🦋
  • ignore_unused_tags => BOOLEAN|REGEXP — inherited from XML::Compile::Schema 🎀
  • key_rewrite => HASH|CODE|ARRAY — inherited from XML::Compile::Schema 🌸
  • opts_readers => HASH|ARRAY-of-PAIRS — inherited from XML::Compile::Schema 💫
  • 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 — inherited from XML::Compile::Schema ⭐
  • parser_options => HASH|ARRAY — coming at you from XML::Compile 🫶
  • 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', ...] }

lowkey obsessed with how the HASH order is flipped, watch out for that bestie 👀

  • schema_dirs => $directory|ARRAY-OF-directories — from XML::Compile 🧚
  • typemap => HASH|ARRAY — inherited from XML::Compile::Schema 💜
  • xsi_type => HASH|ARRAY — inherited from XML::Compile::Schema 🌈

🫶 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. ✨ (worth it, honestly)

  • $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(). 🚫 (deprecated, bestie, don't do it)

💻 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) — hands you back the reader CODE for that $type or $name (peep findName() for how names get resolved). 💖

The %options are only allowed if new(allow_undeclared) is true — and they have to be the same as the options you passed in the previous call to this method. no switching up on it mid-way, bestie.

The reader gets compiled the very first time it's actually used, and then that same CODE reference comes back every single time you ask for the same $type. Want them all built up front instead of on-demand? 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 (again, findName() is your girl for name stuff). OPTIONS are only permitted if new(allow_undeclared) is true, and they're the same as the previous call to this method. same rules, different direction. 💅

The writer gets compiled the first time it's used, and that same CODE reference will be returned each next request for the same type. periodt.

 -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 ) — registers that the indicated $type (or an ARRAY full of them) is allowed to be used, and needs to be translated with the %options (either handed over as an ARRAY or as PAIRS). Then you say whether it can be used as a READER, a WRITER, or both at once (RW). 👑
Heads up though: if the READER and the WRITER need different options, you have to declare them separately — in that case you literally cannot use RW. 💀

The $type should be something findName() can understand, so it 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) — translates the $name spec into a schema-defined full type. The $name can be a full type (like '{namespace}localname', usually built with XML::Compile::Util::pack_type()) or a prefixed type (like 'myns:localname', where "myns" got defined through new(prefixes) or prefixes()). 🌟

When the form is 'myns:' (so, no local name at all), the namespace uri is what comes back. 🦋

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 — adds an indicator to every line, telling you whether readers and writers are declared for the type. Declared readers and writers show up with the 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 it also helps you administer the parameters used to handle compilation. On top of all that, it lets you use easy prefixes instead of full namespaces. iconic behaviour, honestly. 👑

With XML::Compile::Schema::compile() (defined over 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 — so call them as often as you want. This module is the one that helps you administer them. 💖

When the schemas grow larger, it gets harder to see which code references have already been created and which have not. And those code references need compile options that you absolutely do not want scattered all over your whole program. Finally, in a daemon application, you do not want to create the translators when they get used (which can be in every client again) — you want them made once, during the initiation of the daemon. no cap. ✨

One of the most important contributions to the compile management is the addition of smart prefix handling. This means you can use prefixed names in stead of full types, which are 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/ 💜

and that's a wrap, bestie 🎀 this page ships as perl v5.26.2, dated 2018-03-20, and it's XML::C...::Cache(3pm) — go forth and cache responsibly 💅✨

📦 where this page comes from