XML::Overlay - Apply overlays to XML documents


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

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

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

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


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

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


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!




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


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.


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


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


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


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


Inserts the contents of the action tag before each target node


Inserts the contents of the action tag after each target node


Deletes all target nodes and any children thereof


Matt S Trout <>


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