1=encoding utf8
2
3=head1 NAME
4
5XML::Compile::Cache - Cache compiled XML translators
6
7=head1 INHERITANCE
8
9 XML::Compile::Cache
10   is a XML::Compile::Schema
11   is a XML::Compile
12
13=head1 SYNOPSIS
14
15 my $cache = XML::Compile::Cache->new(...);
16
17 $cache->declare('READER',  $type,  @options);
18 $cache->declare(RW     => \@types, @options);
19 $cache->declare(WRITER =>  $type, \@options);
20
21 $cache->compileAll;
22 $cache->compileAll('RW');
23
24 # get the cached code ref for the reader
25 my $reader = $cache->reader($type, @opts);
26 use Data::Dumper;
27 print Dumper $reader->($xml);
28
29 # get the cached code ref for the writer, and use it
30 my $doc = XML::LibXML::Document->new('1.0', 'UTF-8');
31 my $xml = $cache->writer($type)->($doc, $perl);
32 print $xml->toString(1);
33
34 # use the base-class uncached, the XML::Compile::Schema
35 my $do = $cache->compile(READER => $type, @opts);
36
37=head1 DESCRIPTION
38
39Extends L<"DESCRIPTION" in XML::Compile::Schema|XML::Compile::Schema/"DESCRIPTION">.
40
41=head1 METHODS
42
43Extends L<"METHODS" in XML::Compile::Schema|XML::Compile::Schema/"METHODS">.
44
45=head2 Constructors
46
47Extends L<"Constructors" in XML::Compile::Schema|XML::Compile::Schema/"Constructors">.
48
49=over 4
50
51=item XML::Compile::Cache-E<gt>B<new>( [$xml], %options )
52
53 -Option            --Defined in          --Default
54  allow_undeclared                          <false>
55  any_element                               'ATTEMPT'
56  block_namespace     XML::Compile::Schema  []
57  hook                XML::Compile::Schema  undef
58  hooks               XML::Compile::Schema  []
59  ignore_unused_tags  XML::Compile::Schema  <false>
60  key_rewrite         XML::Compile::Schema  []
61  opts_readers                              []
62  opts_rw                                   []
63  opts_writers                              []
64  parser_options      XML::Compile          <many>
65  prefixes                                  <smart>
66  schema_dirs         XML::Compile          undef
67  typemap                                   {}
68  xsi_type                                  {}
69
70=over 2
71
72=item allow_undeclared => BOOLEAN
73
74When true, you may call the reader or writer with types which were
75not registered with L<declare()|XML::Compile::Cache/"Administration">.  In that case, the reader or
76writer may also get options passed for the compiler, as long as
77they are consistent over each use of the type.
78
79=item any_element => CODE|'TAKE_ALL'|'SKIP_ALL'|'ATTEMPT'|'SLOPPY'
80
81See L<anyElement()|XML::Compile::Cache/"Accessors">.
82
83[1.02] the default is to ATTEMPT compiling any handlers automatically.
84Before version 1.02, the default was to SKIP_ALL elements which would
85match the occurs and namespace restrictions of the any specification.
86However, that fails for reperative blocks (for instance, it fails for
87an choice which may occur unbounded times)
88
89=item block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY
90
91=item hook => $hook|ARRAY
92
93=item hooks => ARRAY
94
95=item ignore_unused_tags => BOOLEAN|REGEXP
96
97=item key_rewrite => HASH|CODE|ARRAY
98
99=item opts_readers => HASH|ARRAY-of-PAIRS
100
101=item opts_rw => HASH|ARRAY-of-PAIRS
102
103Options added to both READERs and WRITERS.  Options which are passed
104with L<declare()|XML::Compile::Cache/"Administration"> and C<opts_readers> or C<opts_writers> will overrule
105these.  See L<addCompileOptions()|XML::Compile::Cache/"Compilers">.
106
107=item opts_writers => HASH|ARRAY-of-PAIRS
108
109=item parser_options => HASH|ARRAY
110
111=item prefixes => HASH|ARRAY-of-PAIRS
112
113Define prefix name to name-space mappings.  Passed to L<compile(prefixes)|XML::Compile::Schema/"Compilers">
114for each reader and writer, but also used to permit L<findName()|XML::Compile::Cache/"Administration"> to
115accept types which use a prefix.
116
117Specify an ARRAY of (prefix, name-space) pairs, or a HASH which maps
118name-spaces to prefixes (HASH order is reversed from ARRAY order!)  When
119you wish to collect the results, like usage counts, of the translation
120processing, you will need to specify a HASH.
121
122 prefixes => [ mine => $myns, your => $yourns ]
123 prefixes => { $myns => 'mine', $yourns => 'your' }
124
125 # the previous is short for:
126 prefixes => { $myns => [ uri => $myns, prefix => 'mine', used => 0 ]
127             , $yourns => [ uri => $yourns, prefix => 'your', ...] }
128
129=item schema_dirs => $directory|ARRAY-OF-directories
130
131=item typemap => HASH|ARRAY
132
133=item xsi_type => HASH|ARRAY
134
135=back
136
137=back
138
139=head2 Accessors
140
141Extends L<"Accessors" in XML::Compile::Schema|XML::Compile::Schema/"Accessors">.
142
143=over 4
144
145=item $obj-E<gt>B<addHook>($hook|LIST|undef)
146
147Inherited, see L<XML::Compile::Schema/"Accessors">
148
149=item $obj-E<gt>B<addHooks>( $hook, [$hook, ...] )
150
151Inherited, see L<XML::Compile::Schema/"Accessors">
152
153=item $obj-E<gt>B<addKeyRewrite>($predef|CODE|HASH, ...)
154
155Inherited, see L<XML::Compile::Schema/"Accessors">
156
157=item $obj-E<gt>B<addSchemaDirs>(@directories|$filename)
158
159=item XML::Compile::Cache-E<gt>B<addSchemaDirs>(@directories|$filename)
160
161Inherited, see L<XML::Compile/"Accessors">
162
163=item $obj-E<gt>B<addSchemas>($xml, %options)
164
165Inherited, see L<XML::Compile::Schema/"Accessors">
166
167=item $obj-E<gt>B<addTypemap>(PAIR)
168
169Inherited, see L<XML::Compile::Schema/"Accessors">
170
171=item $obj-E<gt>B<addTypemaps>(PAIRS)
172
173Inherited, see L<XML::Compile::Schema/"Accessors">
174
175=item $obj-E<gt>B<addXsiType>( [HASH|ARRAY|LIST] )
176
177[1.01] add global xsi_type declarations.  Returns the xsiType set.
178The ARRAY or LIST contains pairs, just like the HASH.
179
180The value component can be 'AUTO' to automatically detect the C<xsi:type>
181extensions.  This does only work for complex types.
182
183=item $obj-E<gt>B<allowUndeclared>( [BOOLEAN] )
184
185Whether it is permitted to create readers and writers which are not
186declared cleanly.
187
188=item $obj-E<gt>B<anyElement>('ATTEMPT'|'SLOPPY'|'SKIP_ALL'|'TAKE_ALL'|CODE)
189
190[as method since 0.99] How to process ANY elements, see also
191L<new(any_element)|XML::Compile::Cache/"Constructors">.
192
193Reader: C<ATTEMPT> will convert all any elements, applying the reader for
194each element found. When an element is not found in a schema, it will
195be included as XML::LibXML::Element node.
196
197[0.93] Reader: With C<SLOPPY>, first automatic typed conversion is
198attempted. But is the type is not known, L<XML::LibXML::Simple::XMLin()|XML::LibXML::Simple/"Translators">
199is called to the resque.
200
201=item $obj-E<gt>B<blockNamespace>($ns|$type|HASH|CODE|ARRAY)
202
203Inherited, see L<XML::Compile::Schema/"Accessors">
204
205=item $obj-E<gt>B<hooks>( [<'READER'|'WRITER'>] )
206
207Inherited, see L<XML::Compile::Schema/"Accessors">
208
209=item $obj-E<gt>B<typemap>( [HASH|ARRAY|PAIRS] )
210
211[0.98] Add global knowledge on typemaps.  Returns the typemap.
212
213=item $obj-E<gt>B<useSchema>( $schema, [$schema, ...] )
214
215Inherited, see L<XML::Compile::Schema/"Accessors">
216
217=back
218
219=head2 Prefix management
220
221The cache layer on top of L<XML::Compile::Schema|XML::Compile::Schema> adds smart use of
222prefixes.  Of course, smartness comes with a small performance cost,
223but the code gets much cleaner.
224
225=over 4
226
227=item $obj-E<gt>B<addNicePrefix>(BASE, NAMESPACE)
228
229[1.03] Register NAMESPACE -if not yet defined- with prefix name BASE.  When
230that prefix name is already in use for some other namespace, BASE followed
231by a number are attempted (starting with 01).  The prefix is returned.
232
233When the BASE already ends on a number, that number will get counted.
234
235example:
236
237  my $prefix = $schema->addNicePrefix('call', $myns);
238  # $prefix now can be call, call01, call02 etc
239
240=item $obj-E<gt>B<addPrefixes>( [PAIRS|ARRAY|HASH] )
241
242The X::C logic does auto-detect prefix/namespaces combinations from
243the XML, but does not search extensively for namespace declarations.
244Also, sometimes the same namespace is used with different prefixes.
245Sometimes, the same prefix is used for different namesapces.  To complete
246the list, or control the actual prefix being used, you explicitly declare
247combinations.
248
249The B<best way> to add prefixes is via L<new(prefixes)|XML::Compile::Cache/"Constructors">, which will give
250your names preference over the names found in the schema's which get loaded.
251For instance, use C<< ::WSDL->new(prefixes => [ $prefix => $ns ] >>
252
253[0.995] Returns the HASH with prefix to name-space translations.  You should
254not modify the returned HASH: new PAIRS of prefix to namespace relations
255can be passed as arguments.
256
257[0.14] If a name-space appears for the second time, then the new
258prefix will be recognized by L<findName()|XML::Compile::Cache/"Administration">, but not used in the output.
259When the prefix already exists for a different namespace, then an error
260will be casted.
261
262[0.90] You may also provide an ARRAY of pairs or a HASH.
263
264=item $obj-E<gt>B<learnPrefixes>($node)
265
266[0.993] Take all the prefixes defined in the $node, and XML::LibXML::Element.
267This is not recursive: only on those defined at the top $node.
268
269=item $obj-E<gt>B<prefix>($prefix)
270
271Lookup a prefix definition.  This returns a HASH with namespace info.
272
273=item $obj-E<gt>B<prefixFor>($uri)
274
275Lookup the preferred prefix for the $uri.
276
277=item $obj-E<gt>B<prefixed>( $type|<$ns,$local> )
278
279Translate the fully qualified $type into a prefixed version.  Will produce
280undef if the namespace is unknown.
281
282[0.993] When your $type is not in packed form, you can specify a namespace
283and $local type name as separate arguments.
284
285example:
286
287   print $schema->prefixed($type) || $type;
288   print $schema->prefixed($ns, $local);
289
290=item $obj-E<gt>B<prefixes>( [$params] )
291
292Return prefixes table.  The $params are deprecated since [0.995], see
293L<addPrefixes()|XML::Compile::Cache/"Prefix management">.
294
295=back
296
297=head2 Compilers
298
299The name of this module refers to its power to administer compiled
300XML encoders (writers) and decoders (readers).  This means that
301your program only need to pass on a ::Cache object (for instance
302a XML::Compile::WSDL11, not a CODE reference for each compiled
303translator.
304
305Extends L<"Compilers" in XML::Compile::Schema|XML::Compile::Schema/"Compilers">.
306
307=over 4
308
309=item $obj-E<gt>B<addCompileOptions>( ['READERS'|'WRITERS'|'RW'], %options )
310
311[0.99] You may provide global compile options with L<new(opts_rw)|XML::Compile::Cache/"Constructors">,
312C<opts_readers> and C<opts_writers>, but also later using this method.
313
314=item $obj-E<gt>B<compile>( <'READER'|'WRITER'>, $type, %options )
315
316Inherited, see L<XML::Compile::Schema/"Compilers">
317
318=item $obj-E<gt>B<compileAll>( ['READERS'|'WRITERS'|'RW', [$ns]] )
319
320Compile all the declared readers and writers with the default 'RW').  You may
321also select to pre-compile only the READERS or only the WRITERS.  The
322selection can be limited further by specifying a $ns.
323
324By default, the processors are only compiled when used.  This method is
325especially useful in a B<daemon process>, where preparations can take as
326much time as they want to... and running should be as fast as possible.
327
328=item $obj-E<gt>B<compileType>( <'READER'|'WRITER'>, $type, %options )
329
330Inherited, see L<XML::Compile::Schema/"Compilers">
331
332=item $obj-E<gt>B<dataToXML>($node|REF-XML|XML-STRING|$filename|$fh|$known)
333
334=item XML::Compile::Cache-E<gt>B<dataToXML>($node|REF-XML|XML-STRING|$filename|$fh|$known)
335
336Inherited, see L<XML::Compile/"Compilers">
337
338=item $obj-E<gt>B<initParser>(%options)
339
340=item XML::Compile::Cache-E<gt>B<initParser>(%options)
341
342Inherited, see L<XML::Compile/"Compilers">
343
344=item $obj-E<gt>B<reader>($type|$name, %options)
345
346Returns the reader CODE for the $type or $name (see L<findName()|XML::Compile::Cache/"Administration">).
347%options are only permitted if L<new(allow_undeclared)|XML::Compile::Cache/"Constructors"> is true, and the
348same as the previous call to this method.
349
350The reader will be compiled the first time that it is used, and that
351same CODE reference will be returned each next request for the same
352$type.  Call L<compileAll()|XML::Compile::Cache/"Compilers"> to have all readers compiled by force.
353
354 -Option --Default
355  is_type  <false>
356
357=over 2
358
359=item is_type => BOOLEAN
360
361[1.03] use L<compileType()|XML::Compile::Schema/"Compilers"> with the given element, to replace L<compile()|XML::Compile::Schema/"Compilers">
362You probably want an additional C<element> parameter.
363
364=back
365
366example:
367
368  my $schema = XML::Compile::Cache->new(\@xsd,
369     prefixes => [ gml => $GML_NAMESPACE ] );
370  my $data   = $schema->reader('gml:members')->($xml);
371
372  my $getmem = $schema->reader('gml:members');
373  my $data   = $getmem->($xml);
374
375=item $obj-E<gt>B<template>( <'XML'|'PERL'|'TREE'>, $element, %options )
376
377Inherited, see L<XML::Compile::Schema/"Compilers">
378
379=item $obj-E<gt>B<writer>($type|$name)
380
381Returns the writer CODE for the $type or $name (see L<findName()|XML::Compile::Cache/"Administration">).
382OPTIONS are only permitted if L<new(allow_undeclared)|XML::Compile::Cache/"Constructors"> is true, and the
383same as the previous call to this method.
384
385The writer will be compiled the first time that it is used, and that
386same CODE reference will be returned each next request for the same
387type.
388
389 -Option --Default
390  is_type  <false>
391
392=over 2
393
394=item is_type => BOOLEAN
395
396[1.03] use L<compileType()|XML::Compile::Schema/"Compilers"> with the given element, to replace L<compile()|XML::Compile::Schema/"Compilers">
397You probably want an additional C<element> parameter.
398
399=back
400
401example:
402
403  my $xml = $cache->writer('gml:members')->($doc, $data);
404
405  my $doc = XML::LibXML::Document->new('1.0', 'UTF-8');
406  my $wr  = $cache->writer('gml:members');
407  my $xml = $wr->($doc, $data);
408  $doc->setDocumentElement($xml);
409  print $doc->toString(1);
410
411=back
412
413=head2 Administration
414
415Extends L<"Administration" in XML::Compile::Schema|XML::Compile::Schema/"Administration">.
416
417=over 4
418
419=item $obj-E<gt>B<declare>( <'READER'|'WRITER'|'RW'>, <$type|ARRAY>, %options )
420
421Register that the indicated $type (or ARRAY of them) may be used, and needs to
422be translated with the %options (either specified as ARRAY or PAIRS).
423Specify whether it may get used as READER, WRITER, or both (RW).  If the
424READER and WRITER need different options, then you need to declare them
425separately; in that case you cannot use RW.
426
427The $type should be understood by L<findName()|XML::Compile::Cache/"Administration">, so may be prefixed.
428
429example:
430
431  $cache->declare(READER => 'pref:count', sloppy_integers => 1)
432        ->declare(RW     => '{myns}mylocal');
433
434  $cache->declare(WRITER => [ 'xsd:int', '{http://}aap' ]);
435
436=item $obj-E<gt>B<doesExtend>($exttype, $basetype)
437
438Inherited, see L<XML::Compile::Schema/"Administration">
439
440=item $obj-E<gt>B<elements>()
441
442Inherited, see L<XML::Compile::Schema/"Administration">
443
444=item $obj-E<gt>B<findName>($name)
445
446Translate the $name specification into a schema defined full type.
447The $name can be a full type (like '{namespace}localname', usually
448created with L<XML::Compile::Util::pack_type()|XML::Compile::Util/"Packing">) or a prefixed type
449(like 'myns:localname', where C<myns> is defined via L<new(prefixes)|XML::Compile::Cache/"Constructors">
450or L<prefixes()|XML::Compile::Cache/"Prefix management">).
451
452When the form is 'myns:' (so without local name), the namespace uri is
453returned.
454
455example: of findName()
456
457  $schema->addPrefixes(pre => 'http://namespace');
458
459  my $type = $schema->findName('pre:name');
460  print $type;   # {http://namespace}name
461
462  my $ns   = $schema->findName('pre:');
463  print $ns;     # http://namespace
464
465  my $type = $schema->findName('{somens}name');
466  print $type;   # {somens}name    [a no-op]
467
468=item $obj-E<gt>B<findSchemaFile>($filename)
469
470=item XML::Compile::Cache-E<gt>B<findSchemaFile>($filename)
471
472Inherited, see L<XML::Compile/"Administration">
473
474=item $obj-E<gt>B<importDefinitions>($xmldata, %options)
475
476Inherited, see L<XML::Compile::Schema/"Administration">
477
478=item $obj-E<gt>B<knownNamespace>($ns|PAIRS)
479
480=item XML::Compile::Cache-E<gt>B<knownNamespace>($ns|PAIRS)
481
482Inherited, see L<XML::Compile/"Administration">
483
484=item $obj-E<gt>B<namespaces>()
485
486Inherited, see L<XML::Compile::Schema/"Administration">
487
488=item $obj-E<gt>B<printIndex>( [$fh], %options )
489
490 -Option       --Default
491  show_declared  <true>
492
493=over 2
494
495=item show_declared => BOOLEAN
496
497Add an indicator to each line, about whether readers and writers are
498declare for the type.  Declared readers and writers will show flags
499C<r> and C<w> respectively.  Compiled readers and writers carry a
500C<R> and/or C<W>.
501
502=back
503
504=item $obj-E<gt>B<types>()
505
506Inherited, see L<XML::Compile::Schema/"Administration">
507
508=item $obj-E<gt>B<walkTree>($node, CODE)
509
510Inherited, see L<XML::Compile/"Administration">
511
512=back
513
514=head1 DETAILS
515
516Extends L<"DETAILS" in XML::Compile::Schema|XML::Compile::Schema/"DETAILS">.
517
518=head1 DESCRIPTIONS
519
520C<XML::Compile::Cache> is the smart brother of L<XML::Compile::Schema|XML::Compile::Schema>;
521it keeps track of your compiled readers and writers, and also helps
522you administer the parameters to handle compilation.  Besides, it
523lat you use easy prefixes instead of full namespaces.
524
525With L<XML::Compile::Schema::compile()|XML::Compile::Schema/"Compilers"> (defined in the SUPER class of
526this module) you can construct translators from XML to Perl and back.
527These translators are code references, which are "expensive" to create,
528but "cheap" in use; call them as often as you want.  This module helps
529you administer them.
530
531When the schemas grow larger, it gets harder to see which code reference
532have already be created and which not. And, these code references need
533compile options which you do not want to distribute over your whole
534program.  Finally, in a daemon application, you do not want to create
535the translators when used (which can be in every client again), but once
536during the initiation of the daemon.
537
538One of the most important contributions to the compile management, is
539the addition of smart prefix handling. This means that you can use
540prefixed names in stead of full types, often created with
541L<XML::Compile::Util::pack_type()|XML::Compile::Util/"Packing">.
542
543=head1 SEE ALSO
544
545This module is part of XML-Compile-Cache distribution version 1.06,
546built on March 04, 2018. Website: F<http://perl.overmeer.net/xml-compile/>
547
548=head1 LICENSE
549
550Copyrights 2008-2018 by [Mark Overmeer]. For other contributors see ChangeLog.
551
552This program is free software; you can redistribute it and/or modify it
553under the same terms as Perl itself.
554See F<http://dev.perl.org/licenses/>
555
556