METHODS

See METHODS in XML::Compile

Constructors

See Constructors in XML::Compile

$class->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

$obj->addHook( $hook|LIST|undef )
See addHook in XML::Compile::Schema.
$obj->addHooks( $hook, [$hook, ...] )
See addHooks in XML::Compile::Schema.
$obj->addKeyRewrite( $predef|CODE|HASH, ... )
See addKeyRewrite in XML::Compile::Schema.
$obj->addSchemaDirs( @directories|$filename )
$class->addSchemaDirs( @directories|$filename )
See addSchemaDirs in XML::Compile.
$obj->addSchemas( $xml, %options )
See addSchemas in XML::Compile::Schema.
$obj->addTypemap( PAIR )
See addTypemap in XML::Compile::Schema.
$obj->addTypemaps( PAIRS )
See addTypemaps 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 subroutine XMLin is called to the resque.

$obj->blockNamespace( $ns|$type|HASH|CODE|ARRAY )
See blockNamespace in XML::Compile::Schema.
$obj->hooks( [<'READER'|'WRITER'>] )
See hooks in XML::Compile::Schema.
$obj->typemap( [HASH|ARRAY|PAIRS] )

[0.98] Add global knowledge on typemaps. Returns the typemap.

$obj->useSchema( $schema, [$schema, ...] )
See useSchema 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.

$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 )
See compile 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 )
See compileType in XML::Compile::Schema.
$obj->dataToXML( $node|REF-XML|XML-STRING|$filename|$fh|$known )
$class->dataToXML( $node|REF-XML|XML-STRING|$filename|$fh|$known )
See dataToXML in XML::Compile.
$obj->initParser( %options )
$class->initParser( %options )
See initParser 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 )
See template 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

$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 )
See doesExtend in XML::Compile::Schema.
$obj->elements
See elements 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 )
$class->findSchemaFile( $filename )
See findSchemaFile in XML::Compile.
$obj->importDefinitions( $xmldata, %options )
See importDefinitions in XML::Compile::Schema.
$obj->knownNamespace( $ns|PAIRS )
$class->knownNamespace( $ns|PAIRS )
See knownNamespace in XML::Compile.
$obj->namespaces
See namespaces 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
See types in XML::Compile::Schema.
$obj->walkTree( $node, CODE )
See walkTree in XML::Compile.