XML::Rewrite - schema based XML cleanups

 XML::Rewrite
   is a XML::Compile::Cache
   is a XML::Compile::Schema
   is a XML::Compile

 XML::Rewrite is extended by
   XML::Rewrite::Schema

 my $rewriter = XML::Rewriter->new(...);
 my ($type, $data) = $rewriter->process($file);
 my $doc = $rewriter->buildDOM($type => $data);

Often, XML messages and schemas are created by automatic tools. These tools may provide very nice user interfaces, but tend to produce horrible XML. If you have to read these ugly products, you are in for pain. The purpose of this module (and the script xmlrewrite which is part of this distribution) is to be able to rewrite XML messages and Schema's into something maintainable.

The main difference between this module and other beautifiers is that the clean-up is based on schema rules. For instance, it is permitted to remove blanks around and inside integers, but not in strings. Beautifiers which do not look into the schema have only limited possibilities for cleanup, or may accidentally change the message content.

Feel invited to contribute ideas of useful features.

XML::Rewrite->new([SCHEMA], OPTIONS)

The rewrite object is based on an XML::Compile::Cache object, which defines the message structures. The processing instructions can only be specified at instance creation, because we need to be able to reuse the compiled translators when we wish to process multiple messages.

 Option               --Defined in     --Default
 allow_undeclared       XML::Compile::Cache  <true>
 any_attribute          XML::Compile::Cache  'ATTEMPT'
 any_element            XML::Compile::Cache  'ATTEMPT'
 blanks_before                           'NONE'
 change                                  'TRANSFORM'
 comments                                'KEEP'
 defaults_writer                         'IGNORE'
 hook                   XML::Compile::Schema  undef
 hooks                  XML::Compile::Schema  []
 ignore_unused_tags     XML::Compile::Schema  <false>
 key_rewrite            XML::Compile::Schema  []
 opts_readers           XML::Compile::Cache  []
 opts_rw                XML::Compile::Cache  []
 opts_writers           XML::Compile::Cache  []
 output_compression                      <undef>
 output_encoding                         <undef>
 output_standalone                       <undef>
 output_version                          <undef>
 prefixes               XML::Compile::Cache  <smart>
 remove_elements                         []
 schema_dirs            XML::Compile     undef
 typemap                XML::Compile::Schema  {}
 use_default_namespace                   <false>

. allow_undeclared => BOOLEAN

. any_attribute => CODE|'TAKE_ALL'|'SKIP_ALL'|'ATTEMPT'

. any_element => CODE|'TAKE_ALL'|'SKIP_ALL'|'ATTEMPT'

. blanks_before => 'ALL'|'CONTAINERS'|'NONE'

Automatically put a blank line before each child of the root element, for ALL childs, or only those which have childs themselves. But _BLANK_LINE in the HASH output of the reader, to change the selection on specific locations.

. change => 'REPAIR'|'TRANSFORM'

How to behave: either overrule the message settings (repair broken messages), or to change the output. If you wish both a correction and a transformation, you will need to call the rewrite twice (create to rewriter objects).

. comments => 'REMOVE'|'KEEP'

Comments found in the input may get translated in _COMMENT and _COMMENT_AFTER fields in the intermediate HASH. You may add your own, before you reconstruct the DOM. Comments are expected to be used just before the element they belong to.

. defaults_writer => 'EXTEND'|'IGNORE'|'MINIMAL'

See XML::Compile::Schema::compile(default_values)

. hook => ARRAY-WITH-HOOKDATA | HOOK

. hooks => ARRAY-OF-HOOK

. ignore_unused_tags => BOOLEAN|REGEXP

. key_rewrite => HASH|CODE|ARRAY-of-HASH-and-CODE

. opts_readers => HASH|ARRAY-of-PAIRS

. opts_rw => HASH|ARRAY-of-PAIRS

. opts_writers => HASH|ARRAY-of-PAIRS

. output_compression => -1, 0-8

Set output compression level. A value of -1 means that there should be no compression. By default, the compression level of the input document is used.

. output_encoding => CHARSET

The character-set is usually copied from the source document, but you can overrule this. If neither the rewriter object nor the document defined a encoding, then UTF-8 is used.

. output_standalone => BOOLEAN|'yes'|'no'

If specified, it will overrule the value found in the document. If not provided, the value from the source document will be used, but only when present.

. output_version => STRING

The XML version for the document. This overrules the version found in the document. If neither is specified, then 1.0 is used.

. prefixes => HASH|ARRAY-of-PAIRS

. remove_elements => ARRAY

All the selected elements are removed. However: you shall not remove elements which are required.

. schema_dirs => DIRECTORY|ARRAY-OF-DIRECTORIES

. typemap => HASH

. use_default_namespace => BOOLEAN

If true, the blank prefix will be used for the first name-space needed (usually the name-space of the top-level element). Otherwise, the blank prefix will not be used unless already defined explicitly in the provided prefix table.

$obj->addHook(HOOKDATA|HOOK|undef)

See "Accessors" in XML::Compile::Schema

$obj->addHooks(HOOK, [HOOK, ...])

See "Accessors" in XML::Compile::Schema

$obj->addKeyRewrite(CODE|HASH, CODE|HASH, ...)

See "Accessors" in XML::Compile::Schema

$obj->addSchemaDirs(DIRECTORIES|FILENAME)

XML::Rewrite->addSchemaDirs(DIRECTORIES|FILENAME)

See "Accessors" in XML::Compile

$obj->addSchemas(XML, OPTIONS)

See "Accessors" in XML::Compile::Schema

$obj->addTypemap(PAIR)

See "Accessors" in XML::Compile::Schema

$obj->addTypemaps(PAIRS)

See "Accessors" in XML::Compile::Schema

$obj->allowUndeclared([BOOLEAN])

See "Accessors" in XML::Compile::Cache

$obj->hooks

See "Accessors" in XML::Compile::Schema

$obj->prefixes([PAIRS])

See "Accessors" in XML::Compile::Cache

$obj->compile(('READER'|'WRITER'), TYPE, OPTIONS)

See "Compilers" in XML::Compile::Schema

$obj->compileAll(['READER'|'WRITER'|'RW', [NAMESPACE]])

See "Compilers" in XML::Compile::Cache

$obj->dataToXML(NODE|REF-XML-STRING|XML-STRING|FILENAME|FILEHANDLE|KNOWN)

See "Compilers" in XML::Compile

$obj->reader(TYPE|NAME, OPTIONS)

See "Compilers" in XML::Compile::Cache

$obj->template('XML'|'PERL', TYPE, OPTIONS)

See "Compilers" in XML::Compile::Schema

$obj->writer(TYPE|NAME)

See "Compilers" in XML::Compile::Cache

$obj->declare('READER'|'WRITER'|'RW', TYPE|ARRAY-of-TYPES, OPTIONS)

See "Administration" in XML::Compile::Cache

$obj->elements

See "Administration" in XML::Compile::Schema

$obj->findName(NAME)

See "Administration" in XML::Compile::Cache

$obj->findSchemaFile(FILENAME)

See "Administration" in XML::Compile

$obj->importDefinitions(XMLDATA, OPTIONS)

See "Administration" in XML::Compile::Schema

$obj->knownNamespace(NAMESPACE|PAIRS)

XML::Rewrite->knownNamespace(NAMESPACE|PAIRS)

See "Administration" in XML::Compile

$obj->namespaces

See "Administration" in XML::Compile::Schema

$obj->printIndex([FILEHANDLE], OPTIONS)

See "Administration" in XML::Compile::Cache

$obj->types

See "Administration" in XML::Compile::Schema

$obj->walkTree(NODE, CODE)

See "Administration" in XML::Compile

$obj->buildDOM(TYPE, DATA, OPTIONS)

$obj->process(XMLDATA, OPTIONS)

XMLDATA must be XML as accepted by dataToXML(). Returned is LIST of two: the type of the data-structure read, and the HASH representation of the contained data.

 Option--Default
 type    <from root element>

. type => TYPE

Explicit TYPE of the root element, required in case of namespace-less elements or other namespace problems.

$obj->repairXML(TYPE, XML, DETAILS)

The TYPE of the root element, the root XML element, and DETAILS about the xml origin.

$obj->transformData(TYPE, DATA, DETAILS)

The TYPE of the root element, the HASH representation of the DATA of the message, and DETAILS about the xml origin.

Error: cannot find pre-installed name-space files

Use $ENV{SCHEMA_LOCATION} or new(schema_dirs) to express location of installed name-space files, which came with the XML::Compile distribution package.

Error: don't known how to interpret XML data

This module is part of XML-Rewrite distribution version 0.10, built on August 11, 2008. Website: http://perl.overmeer.net/xml-compile/

All modules in this suite: XML::Compile, XML::Compile::SOAP, XML::Compile::SOAP::Daemon, XML::Compile::Tester, XML::Compile::Cache, XML::Rewrite, XML::Compile::Dumper.

Please post questions or ideas to the mailinglist at http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile For life contact with other developers, visit the #xml-compile channel on irc.perl.org.

Copyrights 2008 by Mark Overmeer. 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://www.perl.com/perl/misc/Artistic.html