=encoding utf8

=head1 NAME

XML::Rewrite - schema based XML cleanups

=head1 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

=head1 SYNOPSIS

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

=head1 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 C<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.

Extends L<"DESCRIPTION" in XML::Compile::Cache|XML::Compile::Cache/"DESCRIPTION">.
 
=head1 METHODS

Extends L<"METHODS" in XML::Compile::Cache|XML::Compile::Cache/"METHODS">.
 
=head2 Constructors

Extends L<"Constructors" in XML::Compile::Cache|XML::Compile::Cache/"Constructors">.
 
=over 4

=item XML::Rewrite-E<gt>B<new>( [SCHEMA], OPTIONS )

The rewrite object is based on an L<XML::Compile::Cache|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 B<multiple messages>.

 -Option               --Defined in          --Default
  allow_undeclared       XML::Compile::Cache   <true>
  any_element            XML::Compile::Cache   'ATTEMPT'
  blanks_before                                'NONE'
  block_namespace        XML::Compile::Schema  []
  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>
  parser_options         XML::Compile          <many>
  prefixes               XML::Compile::Cache   <smart>
  remove_elements                              []
  schema_dirs            XML::Compile          undef
  typemap                XML::Compile::Cache   {}
  use_default_namespace                        <false>
  xsi_type               XML::Compile::Cache   {}

=over 2

=item allow_undeclared => BOOLEAN

=item any_element => CODE|'TAKE_ALL'|'SKIP_ALL'|'ATTEMPT'|'SLOPPY'

=item 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.

=item block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY

=item 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).

=item comments => 'REMOVE'|'KEEP'

Comments found in the input may get translated in C<_COMMENT> and
C<_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.

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

See L<XML::Compile::Schema::compile(default_values)|XML::Compile::Schema/"Compilers">

=item hook => $hook|ARRAY

=item hooks => ARRAY

=item ignore_unused_tags => BOOLEAN|REGEXP

=item key_rewrite => HASH|CODE|ARRAY

=item opts_readers => HASH|ARRAY-of-PAIRS

=item opts_rw => HASH|ARRAY-of-PAIRS

=item opts_writers => HASH|ARRAY-of-PAIRS

=item output_compression => -1, 0-8

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

=item 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 C<UTF-8> is used.

=item 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.

=item output_version => STRING

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

=item parser_options => HASH|ARRAY

=item prefixes => HASH|ARRAY-of-PAIRS

=item remove_elements => ARRAY

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

=item schema_dirs => $directory|ARRAY-OF-directories

=item typemap => HASH|ARRAY

=item 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.

=item xsi_type => HASH|ARRAY

=back

=back

=head2 Accessors

Extends L<"Accessors" in XML::Compile::Cache|XML::Compile::Cache/"Accessors">.
 
=over 4

=item $obj-E<gt>B<addHook>($hook|LIST|undef)

Inherited, see L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<addHooks>( $hook, [$hook, ...] )

Inherited, see L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<addKeyRewrite>($predef|CODE|HASH, ...)

Inherited, see L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<addSchemaDirs>(@directories|$filename)

=item XML::Rewrite-E<gt>B<addSchemaDirs>(@directories|$filename)

Inherited, see L<XML::Compile/"Accessors">

=item $obj-E<gt>B<addSchemas>($xml, %options)

Inherited, see L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<addTypemap>(PAIR)

Inherited, see L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<addTypemaps>(PAIRS)

Inherited, see L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<addXsiType>( [HASH|ARRAY|LIST] )

Inherited, see L<XML::Compile::Cache/"Accessors">

=item $obj-E<gt>B<allowUndeclared>( [BOOLEAN] )

Inherited, see L<XML::Compile::Cache/"Accessors">

=item $obj-E<gt>B<anyElement>('ATTEMPT'|'SLOPPY'|'SKIP_ALL'|'TAKE_ALL'|CODE)

Inherited, see L<XML::Compile::Cache/"Accessors">

=item $obj-E<gt>B<blockNamespace>($ns|$type|HASH|CODE|ARRAY)

Inherited, see L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<hooks>( [<'READER'|'WRITER'>] )

Inherited, see L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<typemap>( [HASH|ARRAY|PAIRS] )

Inherited, see L<XML::Compile::Cache/"Accessors">

=item $obj-E<gt>B<useSchema>( $schema, [$schema, ...] )

Inherited, see L<XML::Compile::Schema/"Accessors">

=back

=head2 Prefix management

Extends L<"Prefix management" in XML::Compile::Cache|XML::Compile::Cache/"Prefix management">.
 
=over 4

=item $obj-E<gt>B<addNicePrefix>(BASE, NAMESPACE)

Inherited, see L<XML::Compile::Cache/"Prefix management">

=item $obj-E<gt>B<addPrefixes>( [PAIRS|ARRAY|HASH] )

Inherited, see L<XML::Compile::Cache/"Prefix management">

=item $obj-E<gt>B<learnPrefixes>($node)

Inherited, see L<XML::Compile::Cache/"Prefix management">

=item $obj-E<gt>B<prefix>($prefix)

Inherited, see L<XML::Compile::Cache/"Prefix management">

=item $obj-E<gt>B<prefixFor>($uri)

Inherited, see L<XML::Compile::Cache/"Prefix management">

=item $obj-E<gt>B<prefixed>( $type|<$ns,$local> )

Inherited, see L<XML::Compile::Cache/"Prefix management">

=item $obj-E<gt>B<prefixes>( [$params] )

Inherited, see L<XML::Compile::Cache/"Prefix management">

=back

=head2 Compilers

Extends L<"Compilers" in XML::Compile::Cache|XML::Compile::Cache/"Compilers">.
 
=over 4

=item $obj-E<gt>B<addCompileOptions>( ['READERS'|'WRITERS'|'RW'], %options )

Inherited, see L<XML::Compile::Cache/"Compilers">

=item $obj-E<gt>B<compile>( <'READER'|'WRITER'>, $type, %options )

Inherited, see L<XML::Compile::Schema/"Compilers">

=item $obj-E<gt>B<compileAll>( ['READERS'|'WRITERS'|'RW', [$ns]] )

Inherited, see L<XML::Compile::Cache/"Compilers">

=item $obj-E<gt>B<compileType>( <'READER'|'WRITER'>, $type, %options )

Inherited, see L<XML::Compile::Schema/"Compilers">

=item $obj-E<gt>B<dataToXML>($node|REF-XML|XML-STRING|$filename|$fh|$known)

=item XML::Rewrite-E<gt>B<dataToXML>($node|REF-XML|XML-STRING|$filename|$fh|$known)

Inherited, see L<XML::Compile/"Compilers">

=item $obj-E<gt>B<initParser>(%options)

=item XML::Rewrite-E<gt>B<initParser>(%options)

Inherited, see L<XML::Compile/"Compilers">

=item $obj-E<gt>B<reader>($type|$name, %options)

Inherited, see L<XML::Compile::Cache/"Compilers">

=item $obj-E<gt>B<template>( <'XML'|'PERL'|'TREE'>, $element, %options )

Inherited, see L<XML::Compile::Schema/"Compilers">

=item $obj-E<gt>B<writer>($type|$name)

Inherited, see L<XML::Compile::Cache/"Compilers">

=back

=head2 Administration

Extends L<"Administration" in XML::Compile::Cache|XML::Compile::Cache/"Administration">.
 
=over 4

=item $obj-E<gt>B<declare>( <'READER'|'WRITER'|'RW'>, <$type|ARRAY>, %options )

Inherited, see L<XML::Compile::Cache/"Administration">

=item $obj-E<gt>B<doesExtend>($exttype, $basetype)

Inherited, see L<XML::Compile::Schema/"Administration">

=item $obj-E<gt>B<elements>()

Inherited, see L<XML::Compile::Schema/"Administration">

=item $obj-E<gt>B<findName>($name)

Inherited, see L<XML::Compile::Cache/"Administration">

=item $obj-E<gt>B<findSchemaFile>($filename)

=item XML::Rewrite-E<gt>B<findSchemaFile>($filename)

Inherited, see L<XML::Compile/"Administration">

=item $obj-E<gt>B<importDefinitions>($xmldata, %options)

Inherited, see L<XML::Compile::Schema/"Administration">

=item $obj-E<gt>B<knownNamespace>($ns|PAIRS)

=item XML::Rewrite-E<gt>B<knownNamespace>($ns|PAIRS)

Inherited, see L<XML::Compile/"Administration">

=item $obj-E<gt>B<namespaces>()

Inherited, see L<XML::Compile::Schema/"Administration">

=item $obj-E<gt>B<printIndex>( [$fh], %options )

Inherited, see L<XML::Compile::Cache/"Administration">

=item $obj-E<gt>B<types>()

Inherited, see L<XML::Compile::Schema/"Administration">

=item $obj-E<gt>B<walkTree>($node, CODE)

Inherited, see L<XML::Compile/"Administration">

=back

=head2 Processing

=over 4

=item $obj-E<gt>B<buildDOM>(TYPE, DATA, OPTIONS)

=item $obj-E<gt>B<process>(XMLDATA, OPTIONS)

XMLDATA must be XML as accepted by L<dataToXML()|XML::Compile/"Compilers">.
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>

=over 2

=item type => TYPE

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

=back

=item $obj-E<gt>B<repairXML>(TYPE, XML, DETAILS)

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

=item $obj-E<gt>B<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.

=back

=head1 DETAILS

Extends L<"DETAILS" in XML::Compile::Cache|XML::Compile::Cache/"DETAILS">.
 
=head1 DESCRIPTIONS

Extends L<"DESCRIPTIONS" in XML::Compile::Cache|XML::Compile::Cache/"DESCRIPTIONS">.
 
=head1 SEE ALSO

This module is part of XML-Rewrite distribution version 0.11,
built on May 11, 2018. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

Copyrights 2008-2018 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 F<http://dev.perl.org/licenses/>

