NAME

XML::Rewrite - schema based XML cleanups

INHERITANCE

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

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

SYNOPSIS

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

DESCRIPTION

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.

METHODS

Constructors

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.