XML::Compile(3pm)

💖 XML::Compile 💖

okay so bestie, welcome to the manual page for XML::Compile (that's the 3pm one, the Perl one, obviously) — Compilation based XML processing ✨. Pull up a chair, grab a boba, we're doing XML and we're doing it correctly.

---

🦋 INHERITANCE 🦋

XML::Compile is extended by

• XML::Compile::Schema

---

✨ SYNOPSIS ✨

# See XML::Compile::Schema / ::WSDL / ::SOAP11 etc

---

🌸 DESCRIPTION 🌸

So, a lot of (professional, serious, wearing-a-blazer) applications process XML messages that follow a formal specification written in XML Schemas. XML::Compile is the girl who translates between XML and Perl with the help of those schemas. Your Perl program only ever touches a tree of nested HASHes and ARRAYs — it does not need to understand namespaces and all that other general XML-and-schema nastiness. She handles it. You just vibe. 💅

Three serious WARNINGS, and I mean serious, no cap:

• The focus here is on data-centric XML, which means mixed elements are not handled automatically: on those spots you need to work with XML::LibXML nodes yourself. 🙈
• The data is not strictly validated, but still a large number of compile-time errors can be reported. Values get checked quite thoroughly. Structure as well.
• Imports and includes, as used in the schemas, are NOT performed automatically. Schema's and such are NOT collected from internet dynamically; you have to call XML::Compile::Schema::importDefinitions() explicitly, with filenames of locally stored copies. Includes do only work if they have a targetNamespace defined, which is the same as that of the schema it is included into.

not me having to say this three times but it's giving important 💀

---

👑 METHODS 👑

The methods on this manual page are shared by the end-user modules, and you should not use them directly: objects of type XML::Compile do not exist! Like, at all. She's a base class, she's the mother of the group chat, not a member of it.

🎀 Constructors 🎀

These constructors are base class methods to be extended, and therefore should not be accessed directly. (Respectfully. From a distance. 🫶)

XML::Compile->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. Slay. ✨

(scroll down bestie, here's the real list 💖)

• parser_options — default: <many>
• schema_dirs — default: 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.

example, because we love a demonstration:

my $xml = XML::Compile->new(parser_options => { huge => 1 });

🌈 Accessors 🌈

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

XML::Compile->addSchemaDirs(@directories|$filename)

Each time this method is called, the specified @directories get 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)

XML::Compile->dataToXML($node|REF-XML|XML-STRING|$filename|$fh|$known)

Collect $xml data, from a wide variety of sources, she's flexible like that. 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)

XML::Compile->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. (Be careful with that, bestie 🫶)

💜 Administration 💜

$obj->findSchemaFile($filename)

XML::Compile->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)

XML::Compile->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.

---

🧚 DETAILS 🧚

💫 Distribution collection overview 💫

For end-users, the following packages are of interest (the other are support packages):

• XML::Compile::Schema Interpret schema elements and types: create processors for XML messages.
• XML::Compile::Cache Helps you administer compiled readers and writers, especially useful it there are a lot of them. Extends XML::Compile::Schema.
• XML::Compile::SOAP Implements the SOAP 1.1 protocol. client side.
• XML::Compile::SOAP12 Implements the SOAP 1.2 protocol.
• XML::Compile::WSDL11 Use SOAP with a WSDL version 1.1 communication specification file.
• XML::Compile::SOAP::Daemon Create a SOAP daemon, directly from a WSDL file.
• XML::Compile::Tester Helps you write regression tests.
• XML::Rewrite Clean-up XML structures: beautify, simplify, extract.
• XML::Compile::Dumper Enables you to save pre-compiled XML handlers, the results of any compileClient. However, this results in huge files, so this may not be worth the effort.

🔥 Comparison 🔥

Where other Perl modules (like SOAP::WSDL) help you using these schemas (often with a lot of run-time XPath searches), XML::Compile takes a different approach: instead of run-time processing of the specification, it will first compile the expected structure into a pure Perl CODE reference, and then use that to process the data as often as needed. Precompiled. Efficient. Main character energy. 👑

There are many Perl modules with the same intention as this one: translate between XML and nested hashes. However, there are a few serious differences: because the schema is used here (and not by the other modules), we can validate the data. XML requires validation but quite a number of modules simply ignore that. 💀

Next to this, data-types are formatted and processed correctly; for instance, the specification prescribes that the Integer data-type must accept values of at least 18 digits... not fitting in Perl's idea of longs.

XML::Compile also supports all more complex data-types like list, union, substitutionGroup (unions on complex type level), and even the nasty any and anyAttribute, which is rarely the case for the other modules. She ate. 💅

---

🌟 SEE ALSO 🌟

This module is part of XML-Compile distribution version 1.64, built on October 21, 2024. Website: http://perl.overmeer.net/xml-compile/

---

🍓 LICENSE 🍓

Copyrights 2006-2024 by [Mark Overmeer <markov@cpan.org>]. 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 the whole page bestie!! 🎀 this one shipped as perl v5.40.0, dated 2024-10-27, and it's the XML::Compile(3pm) manual — go forth and compile, you absolute icon ✨🦋💖