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