METHODS

Methods found in this manual page are shared by the end-user modules, and should not be used directly: objects of type XML::Compile do not exist!

Constructors

These constructors are base class methods to be extended, and therefore should not be accessed directly.

$class->new( [$xmldata], %options )

The $xmldata is a source of XML. See dataToXML() for valid ways, for example as filename, string or undef.

If you have compiled all readers and writers you need, you may simply terminate the compiler object: that will clean-up (most of) the XML::LibXML objects.

Option Default

parser_options

<many>

schema_dirs

undef

parser_options => HASH|ARRAY
See XML::LibXML::Parser for a list of available options which can be used to create an XML parser (the new method). The default will set you in a secure mode. See initParser().
schema_dirs => $directory|ARRAY-OF-directories
Where to find schema's. This can be specified with the environment variable SCHEMA_DIRECTORIES or with this option. See addSchemaDirs() for a detailed explanation.

Accessors

$obj->addSchemaDirs( @directories|$filename )
$class->addSchemaDirs( @directories|$filename )

Each time this method is called, the specified @directories will be added in front of the list of already known schema directories. Initially, the value of the environment variable SCHEMA_DIRECTORIES is added (therefore tried as last resort). The constructor option schema_dirs is a little more favorite.

Values which are undef are skipped. ARRAYs are flattened. Arguments are split at colons (on UNIX) or semi-colons (windows) after flattening. The list of directories is returned, in all but VOID context.

When a .pm package $filename is given, then the directory to be used is calculated from it (platform independently). So, something/XML/Compile.pm becomes something/XML/Compile/xsd/. This way, modules can simply add their definitions via < XML::Compile->addSchemaDirs(__FILE__) > in a BEGIN block or in main. ExtUtils::MakeMaker will install everything what is found in the lib/ tree, so also your xsd files. Probably, you also want to use knownNamespace().

» Example: adding xsd's from your own distribution
  # file xxxxx/lib/My/Package.pm
  package My::Package;

  use XML::Compile;
  XML::Compile->addSchemaDirs(__FILE__);
  # now xxxxx/lib/My/Package/xsd/ is also in the search path

  use constant MYNS => 'http://my-namespace-uri';
  XML::Compile->knownNamespace(&MYNS => 'my-schema-file.xsd');
  $schemas->importDefinitions(MYNS);

Compilers

$obj->dataToXML( $node|REF-XML|XML-STRING|$filename|$fh|$known )
$class->dataToXML( $node|REF-XML|XML-STRING|$filename|$fh|$known )

Collect $xml data, from a wide variety of sources. In SCALAR context, an XML::LibXML::Element or XML::LibXML::Document is returned. In LIST context, pairs of additional information follow the scalar result.

When a ready XML::LibXML::Node (::Element or ::Document) $node is provided, it is returned immediately and unchanged. A SCALAR reference is interpreted as reference to $xml as plain text ($xml texts can be large, and you can improve performance by passing it around by reference instead of copy). Any value which starts with blanks followed by a '<' is interpreted as $xml text.

You may also specify a pre-defined known name-space URI. A set of definition files is included in the distribution, and installed somewhere when this all gets installed. Either define an environment variable named SCHEMA_LOCATION or use new(schema_dirs) (option available to all end-user objects) to inform the library where to find these files.

According the XML::LibXML::Parser manual page, passing a $fh is much slower than pasing a $filename. However, it may be needed to open a file with an explicit character-set.

» Example:
  my $xml = $schema->dataToXML('/etc/config.xml');
  my ($xml, %details) = $schema->dataToXML($something);

  my $xml = XML::Compile->dataToXML('/etc/config.xml');
$obj->initParser( %options )
$class->initParser( %options )

Create a new parser, an XML::LibXML::Parser object. By default, the parsing is set in a safe mode, avoiding exploits. You may explicitly overrule it, especially if you need to process entities.

Administration

$obj->findSchemaFile( $filename )
$class->findSchemaFile( $filename )

Runs through all defined schema directories (see addSchemaDirs()) in search of the specified $filename. When the $filename is absolute, that will be used, and no search is needed. An undef is returned when the file is not found, otherwise a full path to the file is returned to the caller.

Although the file may be found, it still could be unreadible.

$obj->knownNamespace( $ns|PAIRS )
$class->knownNamespace( $ns|PAIRS )

If used with only one $ns, it returns the filename in the distribution (not the full path) which contains the definition.

When PAIRS of $ns-FILENAME are given, then those get defined. This is typically called during the initiation of modules, like XML::Compile::WSDL11 and XML::Compile::SOAP. The definitions are global: not related to specific instances.

The FILENAMES are relative to the directories as specified with some addSchemaDirs() call.

$obj->walkTree( $node, CODE )

Walks the whole tree from $node downwards, calling the CODE reference for each $node found. When that routine returns false, the child nodes will be skipped.