The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
XML-Overlay-0.01
River stage zero No dependents
++
/ XML::Overlay

NAME

XML::Overlay - Apply overlays to XML documents

SYNOPSIS

  # Original XML document:
  <blub>
    <foo meh="3" />
    <bar>
      <spam bleem="3" />
    </bar>
  </blub>

  # Overlay document:
  <Overlay>
    <target xpath="/child::foo">
      <action type="setAttribute" attribute="att">bar</action>
      <action type="insertBefore">
        <spam />
      </action>
      <action type="removeAttribute" attribute="meh" />
    </target>
    <target xpath="//spam">
      <action type="insertAfter">
        <meh1 />
        <meh2 />
      </action>
      <action type="delete" />
    </target>
  </Overlay>

  my $o_tree = XML::Overlay->new(xml => $o_source); # Load overlay doc

  my $d_tree = Class::XML->new(xml => $d_source); # Load initial doc

  $o_tree->process($d_tree);

  print "${d_tree}"; # Class::XML used above for overloaded stringify

  # Outputs:
  <blub>
    
        <spam />
      <foo att="bar" />
    <bar>
      
        <meh1 />
        <meh2 />
      
    </bar>
  </blub>

DESCRIPTION

XML::Overlay is a simple collection of Class::XML modules that provide a mechanism somewhat inspired by Mozilla's XUL Overlays, but designed for manipulating general XML documents. The overlay document contains one or more target elements, each with an xpath attribute which specifies what nodes of the source document should be captured and transformed; each target element contains one or more action elements which specifies the action(s) to perform on each XPath node captured by the parent.

Note that the XPath tree is modified in-place, so ensure you process a copy if you want your original document intact afterwards as well!

DETAILS

Tags

Overlay

The root of an XML::Overlay document; any attributes are ignored, as are any children that aren't a target tag

target

Has a single significant attribute, xpath, which specifies an XPath expression that is evaluated against the document being transformed to work out which nodes this transform should target. Its only significant children are action tags, which each specify a single action which is performed in order of the tags' appearance against the target nodeset. Any other children and attributes are ignored.

action

Has two significant attributes, type and attribute; type specifies the type of action to be performed (see below for a full list). attribute names the attribute to be affected by actions which act upon attributes of the target node(s).

Allowable action types

setAttribute

Sets the attribute specified by the attribute attribute on the action tag to the string value of the tag's contents

removeAttribute

Removed the attribute specified by the attribute attribute on the action tag

appendChild

Appends the contents of the action tag at the end of the child nodes of the target node(s)

insertBefore

Inserts the contents of the action tag before each target node

insertAfter

Inserts the contents of the action tag after each target node

delete

Deletes all target nodes and any children thereof

AUTHOR

Matt S Trout <mstrout@cpan.org>

LICENSE

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