/ 
XML-Easy-Transform-RationalizeNamespacePrefixes-1.22
River stage zero No dependents
/ XML::Easy::Transform::RationalizeNamespacePrefixes

NAME

XML::Easy::Transform::RationalizeNamespacePrefixes - rationalize namespaces prefixes

SYNOPSIS

use XML::Easy::Transform::RationalizeNamespacePrefixes qw(
   rationalize_namespace_prefixes
);

my $doc = rationalize_namespace_prefixes(
   xml10_read_document($text)
);

DESCRIPTION

This code creates a new tree of XML::Easy::Element nodes by examining an existing XML::Easy::Element tree and producing a new tree that is schemantically identical under the XML Namespaces 1.0 specification but with all namespace declartions moved to the top node of the tree (this may involve renaming several elements in the tree to have different prefixes.)

It supplies one public function that can do this transformation which is exported on request:

rationalize_namespace_prefixes($easy_element)
rationalize_namespace_prefixes($easy_element, $generator_subref)
rationalize_namespace_prefixes($easy_element, $options_hashref)

The first argument is a XML::Easy::Element that you wish a transformed copy of to be returned. An exception will be thrown if thrown if the XML document is not namespace-well-formed (i.e. it breaches the XML Namespaces 1.0 specification.)

The second (optional) argument may be a reference to a function that should, when passed a string containing a xml prefix as its first argument, return a string containing an alternative xml prefix. If no function is passed in then the default renaming function is used, which will append or replace trailing numbers with higher numbers to the prefix.

Alternativly, a hashref may be passed as the (optional) second arguement. The keys of this hash may be:

generator

The prefix generating subroutine reference, as previously described.

namespaces

A hashref containing a mapping of namespace to prefixes that you want to force to be declared. This enables you to control exactly what prefixes are used for what namespaces and to force additional namespace declarations for namespaces not otherwise mentioned in the XML document you are transforming. Specifying more than one namespace that maps to the same prefix will cause an exception to be thrown.

force_attribute_prefix

By default attributes without a prefix have the same namespace as the element that they belong to. Setting this to a true value will force prefixes to be prepended to attribute names even if they could be ommited.

The new XML::Easy::Element will be returned as the only return value of this function.

EXAMPLES

A Basic Transform

After defining a handy utility function:

sub process($) {
  return xml10_write_document(
    rationalize_namespace_prefixes(
      xml10_read_document( $_[0] )
    ),"UTF-8"
  );
}

This code:

print process <<'XML';
<foo>
  <ex1:bar xmlns:ex1="http://www.twoshortplanks.com/namespace/example/1"/>
</foo>
XML

Moves the namespace up and prints:

<foo xmlns:ex1="http://www.twoshortplanks.com/namespace/example/1">
  <ex1:bar/>
</foo>

Creating Prefixes

If you use the same prefix twice in the document to refer to different namespaces then the function will rename one of the prefixes:

print process <<'XML';
<muppet:kermit xmlns:muppet="http://www.twoshortplanks.com/namespace/example/muppetshow">
  <muppet:kermit xmlns:muppet="http://www.twoshortplanks.com/namespace/example/seasmestreet" />
</muppet:kermit>
XML

Prints

<muppet:kermit xmlns:muppet="http://www.twoshortplanks.com/namespace/example/muppetshow" xmlns:muppet2="http://www.twoshortplanks.com/namespace/example/seasmestreet">
  <muppet2:kermit />
</muppet:kermit>

This works for the default namespace too:

print process <<'XML';
<foo>
  <bar xmlns="http://www.twoshortplanks.com/namespace/example/1" />
</foo>
XML

Prints

<foo xmlns:default2="http://www.twoshortplanks.com/namespace/example/1">
  <default2:bar />
</foo>

If you want control on how your prefixes will be renamed you can supply a function as the second arguement to rationalize_namespace_prefixes.

my $transformed = rationalize_namespace_prefixes(
  $xml_easy_element,
  sub {
    my $name = shift;
    $name =~ s/\d+\Z//;
    return $name . int(rand(10000));
  }
);

If your function returns a prefix that has already been used it will be called again and again until it returns an unused prefix. The first time the function is called it will be passed the prefix from the source, and if it is called subsequent times after that because the new prefix it previously returned is already in use it will be passed the prefix the previous call to the function created.

Removing Unneeded Prefixes

This module also removes all unnecessary prefixes:

<wobble xmlns:ex1="http://www.twoshortplanks.com/namespace/example/1">
  <ex1:wibble ex1:jelly="in my tummy" />
  <ex2:bobble xmlns:ex2="http://www.twoshortplanks.com/namespace/example/1" />
</wobble>

Will be transformed into

<wobble xmlns:ex1="http://www.twoshortplanks.com/namespace/example/1">
  <ex1:wibble jelly="in my tummy" />
  <ex1:bobble />
</wobble>

AUTHOR

Written by Mark Fowler <mark@twoshortplanks.com>

Copyright Photobox 2009. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

BUGS

None known.

Please report bugs via RT https://rt.cpan.org/Ticket/Create.html?Queue=XML-Easy-Transform-RationalizeNamespacePrefixes.

The version control system for this module is hosted on github. Please feel free to fork http://github.com/2shortplanks/xml-easy-transform-rationalizenamespaceprefixes and send pull requests.

SEE ALSO

XML::Easy, http://www.w3.org/TR/REC-xml-names/