Name

Data::Edit::Xml - Edit data held in the XML format.

Synopsis

Create a new XML parse tree:

  my $a = Data::Edit::Xml::new q(<a><b><c/></b><d><c/></d></a>);

use:

  say STDERR -p $a;

to print:

  <a>
    <b>
      <c/>
    </b>
    <d>
      <c/>
    </d>
  </a>

Cut out c under b but not under d in the created tree by traversing in post-order applying a sub to each node to cut out c when we are at c under b under a.

  $a -> by(sub {$_ -> cut_c_b_a});

Or if you know when you are going:

  $a -> go_b_c__cut;

To get:

  <a>
    <b/>
    <d>
      <c/>
    </d>
  </a>

Bullets to unordered list

To transform a series of bullets into <ul><li>...</li></ul>, parse the input XML:

  my $a = Data::Edit::Xml::new(<<END);
<a>
<p>• Minimum 1 number</p>
<p>•   No leading, trailing, or embedded spaces</p>
<p>• Not case-sensitive</p>
</a>
END

Traverse the resulting parse tree, removing bullets and changing to <li>, <a> to <ul>:

  $a->change_ul->by(sub
   {$_->up__change_li if $_->text_p and $_->text =~ s/\A•\s*//s
   });

Print to get:

  ok -p $a eq <<END;                                                            # Results
<ul>
  <li>Minimum 1 number</li>
  <li>No leading, trailing, or embedded spaces</li>
  <li>Not case-sensitive</li>
</ul>
END

DocBook to Dita

To transform some DocBook XML into Dita:

  use Data::Edit::Xml;

  # Parse the DocBook XML

  my $a = Data::Edit::Xml::new(<<END);
<sli>
  <li>
    <p>Diagnose the problem</p>
    <p>This can be quite difficult</p>
    <p>Sometimes impossible</p>
  </li>
  <li>
  <p><pre>ls -la</pre></p>
  <p><pre>
drwxr-xr-x  2 phil phil   4096 Jun 15  2016 Desktop
drwxr-xr-x  2 phil phil   4096 Nov  9 20:26 Downloads
</pre></p>
  </li>
</sli>
END

  # Transform to Dita step 1

  $a->by(sub
   {my ($o, $p) = @_;
    if ($o->at(qw(pre p li sli)) and $o->isOnlyChild)
     {$o->change($p->isFirst ? qw(cmd) : qw(stepresult));
      $p->unwrap;
     }
    elsif ($o->at(qw(li sli))    and $o->over(qr(\Ap( p)+\Z)))
     {$_->change($_->isFirst ? qw(cmd) : qw(info)) for $o->contents;
     }
   });

  # Transform to Dita step 2

  $a->by(sub
  {my ($o) = @_;
   $o->change(qw(step))          if $o->at(qw(li sli));
   $o->change(qw(steps))         if $o->at(qw(sli));
   $o->id = 's'.($o->position+1) if $o->at(qw(step));
   $o->id = 'i'.($o->index+1)    if $o->at(qw(info));
   $o->wrapWith(qw(screen))      if $o->at(qw(CDATA stepresult));
  });

  # Print the results

  say STDERR -p $a;

Produces:

  <steps>
    <step id="s1">
      <cmd>Diagnose the problem
      </cmd>
      <info id="i1">This can be quite difficult
      </info>
      <info id="i2">Sometimes impossible
      </info>
    </step>
    <step id="s2">
      <cmd>ls -la
      </cmd>
      <stepresult>
        <screen>
  drwxr-xr-x  2 phil phil   4096 Jun 15  2016 Desktop
  drwxr-xr-x  2 phil phil   4096 Nov  9 20:26 Downloads
        </screen>
      </stepresult>
    </step>
  </steps>

Description

Edit data held in the XML format.

The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.

Immediately useful methods

These methods are the ones most likely to be of immediate use to anyone using this module for the first time:

Confirm that the specified $node has the specified ancestry and return the specified $node if it does else undef. Ancestry is specified by providing the expected tags that the $node's parent, the parent's parent etc. must match at each level. If undef is specified then any tag is assumed to match at that level. If a regular expression is specified then the current parent node tag must match the regular expression at that level. If all supplied tags match successfully then the starting node is returned else undef

attr

Return the value of an attribute of the current node as an lvalue sub.

Post-order traversal of a parse tree or sub tree calling the specified sub at each node and returning the specified starting node. The sub is passed references to the current node and all of its ancestors. A reference to the current node is also made available via $_. This is equivalent to the x= operator.

change

Change the name of the specified $node, optionally confirming that the $node is in a specified context and return the $node.

cut

Cut out the specified $node so that it can be reinserted else where in the parse tree.

Return the node reached from the specified $node via the specified path: (index position?)* where index is the tag of the next node to be chosen and position is the optional zero based position within the index of those tags under the current node. Position defaults to zero if not specified. Position can also be negative to index back from the top of the index array. * can be used as the last position to retrieve all nodes with the final tag.

new

Create a new parse tree - call this method statically as in Data::Edit::Xml::new(file or string) to parse a file or string or with no parameters and then use "input", "inputFile", "inputString", "errorFile" to provide specific parameters for the parse, then call "parse" to perform the parse and return the parse tree.

prettyString

Return a readable string representing a node of a parse tree and all the nodes below it. Or use -p $node

putLast

Place a cut out or new node last in the content of the specified $node and return the new node. See addLast to perform this operation conditionally.

unwrap

Unwrap the specified $node by inserting its content into its parent at the point containing the specified $node and return the parent node.

wrapWith

Wrap the specified $node in a new node created from the specified $tag and %attributes forcing the specified $node down - deepening the parse tree - return the new wrapping node. See addWrapWith to perform this operation conditionally.

Construction

Create a parse tree, either by parsing a file or string, or, node by node, or, from another parse tree.

File or String

Construct a parse tree from a file or a string

new($)

     Parameter          Description
  1  $fileNameOrString  Optional file name or string from which to construct the parse tree

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

This is a static method and so should be invoked as:

  Data::Edit::Xml::new

cdata()

The name of the tag to be used to represent text - this tag must not also be used as a command tag otherwise the parser will confess.

Example:

   {ok Data::Edit::Xml::cdata eq q(CDATA);

parse($)

Parse input XML specified via: inputFile, input or inputString.

     Parameter  Description
  1  $parser    Parser created by L</new>

Example:

   {my $x = Data::Edit::Xml::new;

       $x->inputString = <<END;
  <a id="aa"><b id="bb"><c id="cc"/></b></a>
  END

       $x->parse;

       ok -p $x eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"/>
    </b>
  </a>
  END

Node by Node

Construct a parse tree node by node.

newText($$)

Create a new text node.

     Parameter  Description
  1  undef      Any reference to this package
  2  $text      Content of new text node

Example:

    ok -p $x eq <<END;
  <a class="aa" id="1">
    <b class="bb" id="2"/>
  </a>
  END

    $x->putLast($x->newText("t"));

    ok -p $x eq <<END;
  <a class="aa" id="1">
    <b class="bb" id="2"/>
  t
  </a>
  END

newTag($$%)

Create a new non text node.

     Parameter    Description
  1  undef        Any reference to this package
  2  $command     The tag for the node
  3  %attributes  Attributes as a hash.

Example:

   {my $x = Data::Edit::Xml::newTree("a", id=>1, class=>"aa");

    $x->putLast($x->newTag("b", id=>2, class=>"bb"));

    ok -p $x eq <<END;
  <a class="aa" id="1">
    <b class="bb" id="2"/>
  </a>
  END

newTree($%)

Create a new tree.

     Parameter    Description
  1  $command     The name of the root node in the tree
  2  %attributes  Attributes of the root node in the tree as a hash.

Example:

   {my $x = Data::Edit::Xml::newTree("a", id=>1, class=>"aa");

    ok -s $x eq '<a class="aa" id="1"/>';

replaceSpecialChars($)

Replace < > " & with < > " & Larry Wall's excellent Xml parser unfortunately replaces < > " & etc. with their expansions in text by default and does not seem to provide an obvious way to stop this behavior, so we have to put them back again using this method.

     Parameter  Description
  1  $string    String to be edited.

Example:

    ok Data::Edit::Xml::replaceSpecialChars(q(<">)) eq "&lt;&quot;&gt;";

Parse tree attributes

Attributes of a node in a parse tree. For instance the attributes associated with an XML tag are held in the attributes attribute. It should not be necessary to use these attributes directly unless you are writing an extension to this module. Otherwise you should probably use the methods documented in other sections to manipulate the parse tree as they offer a safer interface at a higher level.

content :lvalue

Content of command: the nodes immediately below the specified $node in the order in which they appeared in the source text, see also "Contents".

numbers :lvalue

Nodes by number.

data :lvalue

A hash added to the node for use by the programmer during transformations. The data in this hash will not be printed by any of the printed methods and so can be used to add data to the parse tree that will not be seen in any output xml produced from the parse tree.

attributes :lvalue

The attributes of the specified $node, see also: "Attributes". The frequently used attributes: class, id, href, outputclass can be accessed by an lvalue method as in: $node->id = 'c1'.

conditions :lvalue

Conditional strings attached to a node, see "Conditions".

forestNumbers :lvalue

Index to node by forest number as set by numberForest.

indexes :lvalue

Indexes to sub commands by tag in the order in which they appeared in the source text.

labels :lvalue

The labels attached to a node to provide addressability from other nodes, see: "Labels".

errorsFile :lvalue

Error listing file. Use this parameter to explicitly set the name of the file that will be used to write any parse errors to. By default this file is named: zzzParseErrors/out.data.

inputFile :lvalue

Source file of the parse if this is the parser root node. Use this parameter to explicitly set the file to be parsed.

input :lvalue

Source of the parse if this is the parser root node. Use this parameter to specify some input either as a string or as a file name for the parser to convert into a parse tree.

inputString :lvalue

Source string of the parse if this is the parser root node. Use this parameter to explicitly set the string to be parsed.

numbering :lvalue

Last number used to number a node in this parse tree.

number :lvalue

Number of the specified $node, see findByNumber.

parent :lvalue

Parent node of the specified $node or undef if the parser root node. See also "Traversal" and "Navigation". Consider as read only.

parser :lvalue

Parser details: the root node of a tree is the parser node for that tree. Consider as read only.

tag :lvalue

Tag name for the specified $node, see also "Traversal" and "Navigation". Consider as read only.

text :lvalue

Text of the specified $node but only if it is a text node, i.e. the tag is cdata() <=> "isText" is true.

Parse tree

Construct a parse tree from another parse tree.

renew($@)

Returns a renewed copy of the parse tree, optionally checking that the starting node is in a specified context: use this method if you have added nodes via the "Put as text" methods and wish to traverse their parse tree.

Returns the starting node of the new parse tree or undef if the optional context constraint was supplied but not satisfied.

     Parameter  Description
  1  $node      Node to renew from
  2  @context   Optional context

Use the optional @context parameter to test the context of the specified $node as understood by method at. If the context is supplied and $node is not in this context then this method returns undef immediately.

Example:

   {my $a = Data::Edit::Xml::new("<a/>");

    $a->putFirstAsText(qq(<b/>));

    ok !$a->go(q(b));

    my $A = $a->renew;

    ok -t $A->go(q(b)) eq q(b)

clone($@)

Return a clone of the parse tree optionally checking that the starting node is in a specified context: the parse tree is cloned without converting it to string and reparsing it so this method will not renew any nodes added as text.

Returns the starting node of the new parse tree or undef if the optional context constraint was supplied but not satisfied.

     Parameter  Description
  1  $node      Node to clone from
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new("<a> </a>");

    my $A = $a->clone;

    ok -s $A eq q(<a/>);

    ok $a->equals($A);

   {my $x = Data::Edit::Xml::new(<<END);
  <x>
    <a>aaa
      <b>bbb</b>
      ccc
      <d>ddd</d>
      eee
    </a>
  </x>
  END

    my $y = $x->clone;

    ok !$x->diff($y);

equals($$)

Return the first node if the two parse trees have identical representations via string, else undef.

     Parameter  Description
  1  $node1     Parse tree 1
  2  $node2     Parse tree 2.

Example:

   {my $a = Data::Edit::Xml::new("<a> </a>");

    my $A = $a->clone;

    ok -s $A eq q(<a/>);

    ok $a->equals($A);

equalsIgnoringAttributes($$@)

Return the first node if the two parse trees have identical representations via string if the specified attributes are ignored, else undef.

     Parameter    Description
  1  $node1       Parse tree 1
  2  $node2       Parse tree 2
  3  @attributes  Attributes to ignore during comparison

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b   id="1" outputclass="1" name="b">
      <c id="2" outputclass="2" name="c"/>
    </b>
  </a>
  END

    my $A = Data::Edit::Xml::new(<<END);
  <a>
    <b   id="11" outputclass="11" name="b">
      <c id="22" outputclass="22" name="c"/>
    </b>
  </a>
  END

    ok !$a->equals($A);

    ok !$a->equalsIgnoringAttributes($A, qw(id));

    ok  $a->equalsIgnoringAttributes($A, qw(id outputclass));

diff($$$)

Return () if the dense string representations of the two nodes are equal, else up to the first N (default 16) characters of the common prefix before the point of divergence and the remainder of the string representation of each node from the point of divergence. All  comments are ignored during this comparison and all spans of white space are reduced to a single blank.

     Parameter  Description
  1  $first     First node
  2  $second    Second node
  3  $N         Maximum length of difference strings to return

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <x>
    <a>aaa
      <b>bbb</b>
      ccc
      <d>ddd</d>
      eee
    </a>
  </x>
  END

    ok !$x->diff($x);

    my $y = $x->clone;

    ok !$x->diff($y);

    $y->first->putLast($x->newTag(q(f)));

    ok nws(<<END) eq nws(-p $y);
  <x>
    <a>aaa
      <b>bbb</b>
      ccc
      <d>ddd</d>
      eee
      <f/>
    </a>
  </x>
  END

    is_deeply [$x->diff($y)],    ["<d>ddd</d> eee <", "/a></x>", "f/></a></x>"];

    is_deeply [diff(-p $x, $y)], ["<d>ddd</d> eee <", "/a></x>", "f/></a></x>"];

    is_deeply [$x->diff(-p $y)], ["<d>ddd</d> eee <", "/a></x>", "f/></a></x>"];

    my $X = writeFile(undef, -p $x);

    my $Y = writeFile(undef, -p $y);

    is_deeply [diff($X, $Y)],    ["<d>ddd</d> eee <", "/a></x>", "f/></a></x>"];

save($$)

Save a copy of the parse tree to a file which can be restored and return the saved node. This method uses Storable which is fast but produces large files that do not compress well. Use writeCompressedFile to produce smaller save files at the cost of more time.

     Parameter  Description
  1  $node      Parse tree
  2  $file      File.

Example:

      $y->save($f);

      my $Y = Data::Edit::Xml::restore($f);

      ok $Y->equals($y);

restore($)

Return a parse tree from a copy saved in a file by save.

     Parameter  Description
  1  $file      File

Example:

      $y->save($f);

      my $Y = Data::Edit::Xml::restore($f);

      ok $Y->equals($y);

This is a static method and so should be invoked as:

  Data::Edit::Xml::restore

expandIncludes($)

Expand the includes mentioned in a parse tree: any tag that ends in include is assumed to be an include directive. The file to be included is named on the href keyword. If the file to be included is a relative file name, i.e. it does not begin with / then this file is made absolute relative to the file from which this parse tree was obtained.

     Parameter  Description
  1  $x         Parse tree

Example:

   {my @files =

     (writeFile("in1/a.xml", q(<a id="a"><include href="../in2/b.xml"/></a>)),

      writeFile("in2/b.xml", q(<b id="b"><include href="c.xml"/></b>)),

      writeFile("in2/c.xml", q(<c id="c"/>)));

    my $x = Data::Edit::Xml::new(fpf(currentDirectory, $files[0]));

       $x->expandIncludes;

    ok <<END eq -p $x;
  <a id="a">
    <b id="b">
      <c id="c"/>
    </b>
  </a>
  END

Print

Create a string representation of the parse tree with optional selection of nodes via conditions.

Normally use the methods in Pretty to format the XML in a readable yet reparseable manner; use Dense string to format the XML densely in a reparseable manner; use the other methods to produce unreparseable strings conveniently formatted to assist various specialized operations such as debugging CDATA, using labels or creating tests. A number of the file test operators can also be conveniently used to print parse trees in these formats.

Pretty

Pretty print the parse tree.

prettyString($$)

Return a readable string representing a node of a parse tree and all the nodes below it. Or use -p $node

     Parameter  Description
  1  $node      Start node
  2  $depth     Optional depth.

Example:

   {my $s = <<END;
  <a>
    <b>
      <A/>
      <B/>
    </b>
    <c>
      <C/>
      <D/>
    </c>
  </a>
  END

    my $a = Data::Edit::Xml::new($s);

    ok $s eq $a->prettyString;

    ok $s eq -p $a;

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>bbb</b>.
    <c>ccc</c>.
  </a>
  END

    ok nn(-p $a) eq qq(<a>N  <b>bbb</b>.NN  N  <c>ccc</c>.NNN</a>N);

prettyStringDitaHeaders($)

Return a readable string representing the parse tree below the specified $node with appropriate headers as determined by ditaOrganization . Or use -x $node

     Parameter  Description
  1  $node      Start node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <concept/>
  END

    Data::Edit::Xml::ditaOrganization = q(ACT);

    ok $a->prettyStringDitaHeaders eq <<END;
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE concept PUBLIC "-//ACT//DTD DITA Concept//EN" "concept.dtd" []>
  <concept/>
  END

    ok -x $a eq <<END;
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE concept PUBLIC "-//ACT//DTD DITA Concept//EN" "concept.dtd" []>
  <concept/>
  END

prettyStringNumbered($$)

Return a readable string representing a node of a parse tree and all the nodes below it with a number attached to each tag. The node numbers can then be used as described in Order to monitor changes to the parse tree.

     Parameter  Description
  1  $node      Start node
  2  $depth     Optional depth.

Example:

   {my $s = <<END;
  <a>
    <b>
      <A/>
      <B/>
    </b>
    <c>
      <C/>
      <D/>
    </c>
  </a>
  END

    $a->numberTree;

    ok $a->prettyStringNumbered eq <<END;
  <a id="1">
    <b id="2">
      <A id="3"/>
      <B id="4"/>
    </b>
    <c id="5">
      <C id="6"/>
      <D id="7"/>
    </c>
  </a>
  END

prettyStringCDATA($$)

Return a readable string representing a node of a parse tree and all the nodes below it with the text fields wrapped with <CDATA>...</CDATA>.

     Parameter  Description
  1  $node      Start node
  2  $depth     Optional depth.

Example:

   {my $a = Data::Edit::Xml::new("<a><b>A</b></a>");

    my $b = $a->first;

       $b->first->replaceWithBlank;

    ok $a->prettyStringCDATA eq <<END;
  <a>
      <b><CDATA> </CDATA></b>
  </a>
  END

prettyStringContent($)

Return a readable string representing all the nodes below a node of a parse tree.

     Parameter  Description
  1  $node      Start node.

Example:

   {my $s = <<END;
  <a>
    <b>
      <A/>
      <B/>
    </b>
    <c>
      <C/>
      <D/>
    </c>
  </a>
  END

    ok $a->prettyStringContent eq <<END;
  <b>
    <A/>
    <B/>
  </b>
  <c>
    <C/>
    <D/>
  </c>
  END

prettyStringContentNumbered($)

Return a readable string representing all the nodes below a node of a parse tree with numbering added.

     Parameter  Description
  1  $node      Start node.

Example:

   {my $s = <<END;
  <a>
    <b>
      <c/>
    </b>
  </a>
  END

    my $a = Data::Edit::Xml::new($s);

    $a->numberTree;

    ok $a->prettyStringContentNumbered eq <<END;
  <b id="2">
    <c id="3"/>
  </b>
  END

    ok $a->go(qw(b))->prettyStringContentNumbered eq <<END;
  <c id="3"/>
  END

xmlHeader($)

Add the standard xml header to a string

     Parameter  Description
  1  $string    String to which a standard xml header should be prefixed

Example:

  ok xmlHeader("<a/>") eq <<END;
  <?xml version="1.0" encoding="UTF-8"?>
  <a/>
  END

This is a static method and so should be invoked as:

  Data::Edit::Xml::xmlHeader

Dense

Print the parse tree.

string($)

Return a dense string representing a node of a parse tree and all the nodes below it. Or use -s $node

     Parameter  Description
  1  $node      Start node.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    ok -s $a eq '<a><b><c id="42" match="mm"/></b><d><e/></d></a>';

stringQuoted($)

Return a quoted string representing a parse tree a node of a parse tree and all the nodes below it. Or use -o $node

     Parameter  Description
  1  $node      Start node

Example:

   {my $s = <<END;
  <a>
    <b>
      <A/>
      <B/>
    </b>
    <c>
      <C/>
      <D/>
    </c>
  </a>
  END

    ok $a->stringQuoted eq q('<a><b><A/><B/></b><c><C/><D/></c></a>');

stringReplacingIdsWithLabels($)

Return a string representing the specified parse tree with the id attribute of each node set to the Labels attached to each node.

     Parameter  Description
  1  $node      Start node.

Example:

    ok $x->stringReplacingIdsWithLabels eq '<a><b><c/></b></a>';

    $b->addLabels(1..4);

    $c->addLabels(5..8);

    ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c id="5, 6, 7, 8"/></b></a>';

    my $s = $x->stringReplacingIdsWithLabels;

    ok $s eq '<a><b id="1, 2, 3, 4"><c id="5, 6, 7, 8"/></b></a>';

stringExtendingIdsWithLabels($)

Return a string representing the specified parse tree with the id attribute of each node extended by the Labels attached to each node.

     Parameter  Description
  1  $node      Start node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a id="a">
    <b id="b">
      <c id="c"/>
    </b>
    <b id="B">
      <c id="C"/>
    </b>
  </a>
  END

    my $N = 0; $a->by(sub{$_->addLabels((-t $_).++$N)});

    ok -p (new $a->stringExtendingIdsWithLabels) eq <<END;
  <a id="a, a5">
    <b id="b, b2">
      <c id="c, c1"/>
    </b>
    <b id="B, b4">
      <c id="C, c3"/>
    </b>
  </a>
  END

stringContent($)

Return a string representing all the nodes below a node of a parse tree.

     Parameter  Description
  1  $node      Start node.

Example:

   {my $s = <<END;
  <a>
    <b>
      <A/>
      <B/>
    </b>
    <c>
      <C/>
      <D/>
    </c>
  </a>
  END

    ok $a->stringContent eq "<b><A/><B/></b><c><C/><D/></c>";

stringNode($)

Return a string representing a node showing the attributes, labels and node number

     Parameter  Description
  1  $node      Node.

Example:

    ok $x->stringReplacingIdsWithLabels eq '<a><b><c/></b></a>';

    my $b = $x->go(q(b));

    $b->addLabels(1..2);

    $b->addLabels(3..4);

    ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c/></b></a>';

    $b->numberTree;

    ok -S $b eq "b(2) 0:1 1:2 2:3 3:4";

Conditions

Print a subset of the the parse tree determined by the conditions attached to it.

stringWithConditions($@)

Return a string representing the specified $node of a parse tree and all the nodes below it subject to conditions to select or reject some nodes.

     Parameter    Description
  1  $node        Start node
  2  @conditions  Conditions to be regarded as in effect.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
    </b>
  </a>
  END

    my $b = $a >= 'b';

    my ($c, $d) = $b->contents;

    $b->addConditions(qw(bb BB));

    $c->addConditions(qw(cc CC));

    ok $a->stringWithConditions         eq '<a><b><c/><d/></b></a>';

    ok $a->stringWithConditions(qw(bb)) eq '<a><b><d/></b></a>';

    ok $a->stringWithConditions(qw(cc)) eq '<a/>';

condition($$@)

Return the node if it has the specified condition and is in the optional context, else return undef

     Parameter   Description
  1  $node       Node
  2  $condition  Condition to check
  3  @context    Optional context

Example:

    $b->addConditions(qw(bb BB));

    $c->addConditions(qw(cc CC));

    ok  $c->condition(q(cc));

    ok !$c->condition(q(dd));

    ok  $c->condition(q(cc), qw(c b a));

anyCondition($@)

Return the node if it has any of the specified conditions, else return undef

     Parameter    Description
  1  $node        Node
  2  @conditions  Conditions to check

Example:

    $b->addConditions(qw(bb BB));

    $c->addConditions(qw(cc CC));

    ok  $b->anyCondition(qw(bb cc));

    ok !$b->anyCondition(qw(cc CC));

allConditions($@)

Return the node if it has all of the specified conditions, else return undef

     Parameter    Description
  1  $node        Node
  2  @conditions  Conditions to check

Example:

    $b->addConditions(qw(bb BB));

    $c->addConditions(qw(cc CC));

    ok  $b->allConditions(qw(bb BB));

    ok !$b->allConditions(qw(bb cc));

addConditions($@)

Add conditions to a node and return the node.

     Parameter    Description
  1  $node        Node
  2  @conditions  Conditions to add.

Example:

    $b->addConditions(qw(bb BB));

    ok join(' ', $b->listConditions) eq 'BB bb';

deleteConditions($@)

Delete conditions applied to a node and return the node.

     Parameter    Description
  1  $node        Node
  2  @conditions  Conditions to add.

Example:

    ok join(' ', $b->listConditions) eq 'BB bb';

    $b->deleteConditions(qw(BB));

    ok join(' ', $b->listConditions) eq 'bb';

listConditions($)

Return a list of conditions applied to a node.

     Parameter  Description
  1  $node      Node.

Example:

    $b->addConditions(qw(bb BB));

    ok join(' ', $b->listConditions) eq 'BB bb';

Attributes

Get or set the attributes of nodes in the parse tree. Well Known Attributes can be set directly via lvalue subs. To set or get the values of other attributes use Get or Set Attributes. To delete or rename attributes see: Other Operations on Attributes.

Well Known Attributes

Get or set these attributes of nodes via lvalue subs as in:

  $x->href = "#ref";

audience :lvalue

Attribute audience for a node as an lvalue sub. Use audienceX() to return q() rather than undef.

class :lvalue

Attribute class for a node as an lvalue sub. Use classX() to return q() rather than undef.

guid :lvalue

Attribute guid for a node as an lvalue sub. Use guidX() to return q() rather than undef.

href :lvalue

Attribute href for a node as an lvalue sub. Use hrefX() to return q() rather than undef.

id :lvalue

Attribute id for a node as an lvalue sub. Use idX() to return q() rather than undef.

lang :lvalue

Attribute lang for a node as an lvalue sub. Use langX() to return q() rather than undef.

navtitle :lvalue

Attribute navtitle for a node as an lvalue sub. Use navtitleX() to return q() rather than undef.

otherprops :lvalue

Attribute otherprops for a node as an lvalue sub. Use otherpropsX() to return q() rather than undef.

outputclass :lvalue

Attribute outputclass for a node as an lvalue sub. Use outputclassX() to return q() rather than undef.

props :lvalue

Attribute props for a node as an lvalue sub. Use propsX() to return q() rather than undef.

style :lvalue

Attribute style for a node as an lvalue sub. Use styleX() to return q() rather than undef.

type :lvalue

Attribute type for a node as an lvalue sub. Use typeX() to return q() rather than undef.

Get or Set Attributes

Get or set the attributes of nodes.

attr($$)

Return the value of an attribute of the current node as an lvalue sub.

     Parameter   Description
  1  $node       Node in parse tree
  2  $attribute  Attribute name.

Example:

   {my $x = Data::Edit::Xml::new(my $s = <<END);
  <a number="1"/>
  END

    ok $x->attr(qq(number)) == 1;

       $x->attr(qq(number))  = 2;

    ok $x->attr(qq(number)) == 2;

    ok -s $x eq '<a number="2"/>';

set($%)

Set the values of some attributes in a node and return the node. Identical in effect to setAttr.

     Parameter  Description
  1  $node      Node in parse tree
  2  %values    (attribute name=>new value)*

Example:

    ok q(<a a="1" b="1" id="aa"/>) eq -s $a;

    $a->set(a=>11, b=>undef, c=>3, d=>4, e=>5);

   }

setAttr($%)

Set the values of some attributes in a node and return the node. Identical in effect to set.

     Parameter  Description
  1  $node      Node in parse tree
  2  %values    (attribute name=>new value)*

Example:

    ok -s $x eq '<a number="2"/>';

    $x->setAttr(first=>1, second=>2, last=>undef);

    ok -s $x eq '<a first="1" number="2" second="2"/>';

Other Operations on Attributes

Perform operations other than get or set on the attributes of a node

attrs($@)

Return the values of the specified attributes of the current node as a list

     Parameter    Description
  1  $node        Node in parse tree
  2  @attributes  Attribute names.

Example:

    ok -s $x eq '<a first="1" number="2" second="2"/>';

    is_deeply [$x->attrs(qw(third second first ))], [undef, 2, 1];

attrCount($@)

Return the number of attributes in the specified $node, optionally ignoring the specified names from the count.

     Parameter  Description
  1  $node      Node in parse tree
  2  @exclude   Optional attribute names to exclude from the count.

Example:

    ok -s $x eq '<a first="1" number="2" second="2"/>';

    ok $x->attrCount == 3;

    ok $x->attrCount(qw(first second third)) == 1;

getAttrs($)

Return a sorted list of all the attributes on the specified $node.

     Parameter  Description
  1  $node      Node in parse tree.

Example:

    ok -s $x eq '<a first="1" number="2" second="2"/>';

    is_deeply [$x->getAttrs], [qw(first number second)];

deleteAttr($$$)

Delete the named attribute in the specified $node, optionally check its value first, return the node regardless.

     Parameter  Description
  1  $node      Node
  2  $attr      Attribute name
  3  $value     Optional attribute value to check first.

Example:

    ok -s $x eq '<a delete="me" number="2"/>';

    $x->deleteAttr(qq(delete));

    ok -s $x eq '<a number="2"/>';

deleteAttrs($@)

Delete the specified attributes of the specified $node without checking their values and return the node.

     Parameter  Description
  1  $node      Node
  2  @attrs     Names of the attributes to delete

Example:

    ok -s $x eq '<a first="1" number="2" second="2"/>';

    $x->deleteAttrs(qw(first second third number));

    ok -s $x eq '<a/>';

renameAttr($$$)

Change the name of an attribute in the specified $node regardless of whether the new attribute already exists or not and return the node. To prevent inadvertent changes to an existing attribute use changeAttr.

     Parameter  Description
  1  $node      Node
  2  $old       Existing attribute name
  3  $new       New attribute name.

Example:

    ok $x->printAttributes eq qq( no="1" word="first");

    $x->renameAttr(qw(no number));

    ok $x->printAttributes eq qq( number="1" word="first");

changeAttr($$$)

Change the name of an attribute in the specified $node unless it has already been set and return the node. To make changes regardless of whether the new attribute already exists use renameAttr.

     Parameter  Description
  1  $node      Node
  2  $old       Existing attribute name
  3  $new       New attribute name.

Example:

    ok $x->printAttributes eq qq( number="1" word="first");

    $x->changeAttr(qw(number word));

    ok $x->printAttributes eq qq( number="1" word="first");

renameAttrValue($$$$$)

Change the name and value of an attribute in the specified $node regardless of whether the new attribute already exists or not and return the node. To prevent inadvertent changes to existing attributes use changeAttrValue.

     Parameter  Description
  1  $node      Node
  2  $old       Existing attribute name
  3  $oldValue  Existing attribute value
  4  $new       New attribute name
  5  $newValue  New attribute value.

Example:

    ok $x->printAttributes eq qq( number="1" word="first");

    $x->renameAttrValue(qw(number 1 numeral I));

    ok $x->printAttributes eq qq( numeral="I" word="first");

changeAttrValue($$$$$)

Change the name and value of an attribute in the specified $node unless it has already been set and return the node. To make changes regardless of whether the new attribute already exists use renameAttrValue.

     Parameter  Description
  1  $node      Node
  2  $old       Existing attribute name
  3  $oldValue  Existing attribute value
  4  $new       New attribute name
  5  $newValue  New attribute value.

Example:

    ok $x->printAttributes eq qq( numeral="I" word="first");

    $x->changeAttrValue(qw(word second greek mono));

    ok $x->printAttributes eq qq( numeral="I" word="first");

    $x->changeAttrValue(qw(word first greek mono));

    ok $x->printAttributes eq qq( greek="mono" numeral="I");

changeAttributeValue($$$@)

Apply a sub to the value of an attribute of the specified $node. The value to be changed is supplied and returned in: $_.

     Parameter   Description
  1  $node       Node
  2  $attribute  Attribute name
  3  $sub        Change sub
  4  @context    Optional context;

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a aa="abc"/>
  END

    $a->changeAttributeValue(q(aa), sub{s(b) (B)});

    ok -p $a eq <<END;
  <a aa="aBc"/>
  END

copyAttrs($$@)

Copy all the attributes of the source node to the target node, or, just the named attributes if the optional list of attributes to copy is supplied, overwriting any existing attributes in the target node and return the source node.

     Parameter  Description
  1  $source    Source node
  2  $target    Target node
  3  @attr      Optional list of attributes to copy

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <x>
    <a a="1" b="2"/>
    <b b="3" c="4"/>
    <c/>
  </x>
  END

    my ($a, $b, $c) = $x->contents;

    $a->copyAttrs($b, qw(aa bb));

    ok <<END eq -p $x;
  <x>
    <a a="1" b="2"/>
    <b b="3" c="4"/>
    <c/>
  </x>
  END

    $a->copyAttrs($b);

    ok <<END eq -p $x;
  <x>
    <a a="1" b="2"/>
    <b a="1" b="2" c="4"/>
    <c/>
  </x>
  END

copyNewAttrs($$@)

Copy all the attributes of the source node to the target node, or, just the named attributes if the optional list of attributes to copy is supplied, without overwriting any existing attributes in the target node and return the source node.

     Parameter  Description
  1  $source    Source node
  2  $target    Target node
  3  @attr      Optional list of attributes to copy

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <x>
    <a a="1" b="2"/>
    <b b="3" c="4"/>
    <c/>
  </x>
  END

    my ($a, $b, $c) = $x->contents;

    $a->copyNewAttrs($b, qw(aa bb));

    ok <<END eq -p $x;
  <x>
    <a a="1" b="2"/>
    <b b="3" c="4"/>
    <c/>
  </x>
  END

    $a->copyNewAttrs($b);

    ok <<END eq -p $x;
  <x>
    <a a="1" b="2"/>
    <b a="1" b="3" c="4"/>
    <c/>
  </x>
  END

moveAttrs($$@)

Move all the attributes of the source node to the target node, or, just the named attributes if the optional list of attributes to move is supplied, overwriting any existing attributes in the target node and return the source node.

     Parameter  Description
  1  $source    Source node
  2  $target    Target node
  3  @attr      Attributes to move

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <x>
    <a a="1" b="2"/>
    <b b="3" c="4"/>
    <c/>
  </x>
  END

    my ($a, $b, $c) = $x->contents;

    $a->moveAttrs($c, qw(aa bb));

    ok <<END eq -p $x;
  <x>
    <a a="1" b="2"/>
    <b a="1" b="2" c="4"/>
    <c/>
  </x>
  END

    $b->moveAttrs($c);

    ok <<END eq -p $x;
  <x>
    <a a="1" b="2"/>
    <b/>
    <c a="1" b="2" c="4"/>
  </x>
  END

moveNewAttrs($$@)

Move all the attributes of the source node to the target node, or, just the named attributes if the optional list of attributes to copy is supplied, without overwriting any existing attributes in the target node and return the source node.

     Parameter  Description
  1  $source    Source node
  2  $target    Target node
  3  @attr      Optional list of attributes to move

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <x>
    <a a="1" b="2"/>
    <b b="3" c="4"/>
    <c/>
  </x>
  END

    my ($a, $b, $c) = $x->contents;

    $b->moveNewAttrs($c, qw(aa bb));

    ok <<END eq -p $x;
  <x>
    <a a="1" b="2"/>
    <b a="1" b="3" c="4"/>
    <c/>
  </x>
  END

    $b->moveNewAttrs($c);

    ok <<END eq -p $x;
  <x>
    <a a="1" b="2"/>
    <b/>
    <c a="1" b="3" c="4"/>
  </x>
  END

    ok <<END eq -p $x;
  <x>
    <c a="1" b="3" c="4"/>
    <b/>
    <a a="1" b="2"/>
  </x>
  END

Traversal

Traverse the parse tree in various orders applying a sub to each node.

Post-order

This order allows you to edit children before their parents.

by($$@)

     Parameter  Description
  1  $node      Starting node
  2  $sub       Sub to call for each sub node
  3  @context   Accumulated context.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

     {my $s; $a->by(sub{$s .= $_->tag}); ok $s eq "cbeda"

byX($$)

Post-order traversal of a parse tree calling the specified sub at each node as long as this sub does not die. The traversal is halted if the called sub does die on any call with the reason in ?@ The sub is passed references to the current node and all of its ancestors up to the node on which this sub was called. A reference to the current node is also made available via $_.

Returns the start node regardless of the outcome of calling sub.

     Parameter  Description
  1  $node      Start node
  2  $sub       Sub to call

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

     {my $s; $a->byX(sub{$s .= $_->tag}); ok $s eq "cbeda"

  sub byX($$)
   {my ($node, $sub) = @_;                                                        # Start node, sub to call
    eval {$node->byX2($sub)};                                                     # Trap any errors that occur
    $node
   }

byList($@)

Return a list of all the nodes at and below a specified $node in pre-order or the empty list if the $node is not in the optional context.

     Parameter  Description
  1  $node      Starting node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    ok -c $e eq q(e d a);

byReverse($$@)

Reverse post-order traversal of a parse tree or sub tree calling the specified sub at each node and returning the specified starting $node. The sub is passed references to the current node and all of its ancestors. The value of the current node is also made available via $_.

     Parameter  Description
  1  $node      Starting node
  2  $sub       Sub to call for each sub node
  3  @context   Accumulated context.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

     {my $s; $a->byReverse(sub{$s .= $_->tag}); ok $s eq "edcba"

byReverseX($$@)

Reverse post-order traversal of a parse tree or sub tree below the specified $node calling the specified sub within eval{} at each node and returning the specified starting $node. The sub is passed references to the current node and all of its ancestors. The value of the current node is also made available via $_.

     Parameter  Description
  1  $node      Starting node
  2  $sub       Sub to call for each sub node
  3  @context   Accumulated context.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

     {my $s; $a->byReverse(sub{$s .= $_->tag}); ok $s eq "edcba"

byReverseList($@)

Return a list of all the nodes at and below a specified $node in reverse preorder or the empty list if the specified $node is not in the optional context.

     Parameter  Description
  1  $node      Starting node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

      my ($E, $D, $C, $B) = $a->byReverseList;

      ok -A $C eq q(c id="42" match="mm");

Pre-order

This order allows you to edit children after their parents

down($$@)

Pre-order traversal down through a parse tree or sub tree calling the specified sub at each node and returning the specified starting node. The sub is passed references to the current node and all of its ancestors. The value of the current node is also made available via $_.

     Parameter  Description
  1  $node      Starting node
  2  $sub       Sub to call for each sub node
  3  @context   Accumulated context.

Example:

     {my $s; $a->down(sub{$s .= $_->tag}); ok $s eq "abcde"

downX($$)

Pre-order traversal of a parse tree calling the specified sub at each node as long as this sub does not die. The traversal is halted if the called sub does die on any call with the reason in ?@ The sub is passed references to the current node and all of its ancestors up to the node on which this sub was called. A reference to the current node is also made available via $_.

Returns the start node regardless of the outcome of calling sub.

     Parameter  Description
  1  $node      Start node
  2  $sub       Sub to call

Example:

     {my $s; $a->down(sub{$s .= $_->tag}); ok $s eq "abcde"

  sub downX($$)
   {my ($node, $sub) = @_;                                                        # Start node, sub to call
    eval {$node->downX2($sub)};                                                   # Trap any errors that occur
    $node
   }

downReverse($$@)

Reverse pre-order traversal down through a parse tree or sub tree calling the specified sub at each node and returning the specified starting node. The sub is passed references to the current node and all of its ancestors. The value of the current node is also made available via $_.

     Parameter  Description
  1  $node      Starting node
  2  $sub       Sub to call for each sub node
  3  @context   Accumulated context.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

     {my $s; $a->downReverse(sub{$s .= $_->tag}); ok $s eq "adebc"

downReverseX($$@)

Reverse pre-order traversal down through a parse tree or sub tree calling the specified sub within eval{} at each node and returning the specified starting node. The sub is passed references to the current node and all of its ancestors. The value of the current node is also made available via $_.

     Parameter  Description
  1  $node      Starting node
  2  $sub       Sub to call for each sub node
  3  @context   Accumulated context.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

     {my $s; $a->downReverse(sub{$s .= $_->tag}); ok $s eq "adebc"

Pre and Post order

Visit the parent first, then the children, then the parent again.

through($$$@)

Traverse parse tree visiting each node twice calling the specified sub at each node and returning the specified starting node. The subs are passed references to the current node and all of its ancestors. The value of the current node is also made available via $_.

     Parameter  Description
  1  $node      Starting node
  2  $before    Sub to call when we meet a node
  3  $after     Sub to call we leave a node
  4  @context   Accumulated context.

Example:

     {my $s; my $n = sub{$s .= $_->tag}; $a->through($n, $n);

      ok $s eq "abccbdeeda"

throughX($$$@)

Traverse parse tree visiting each node twice calling the specified sub within eval{} at each node and returning the specified starting node. The sub is passed references to the current node and all of its ancestors. The value of the current node is also made available via $_.

     Parameter  Description
  1  $node      Starting node
  2  $before    Sub to call when we meet a node
  3  $after     Sub to call we leave a node
  4  @context   Accumulated context.

Example:

     {my $s; my $n = sub{$s .= $_->tag}; $a->through($n, $n);

      ok $s eq "abccbdeeda"

Range

Ranges of nodes

from($@)

Return a list consisting of the specified node and its following siblings optionally including only those nodes that match one of the tags in the specified list.

     Parameter  Description
  1  $start     Start node
  2  @match     Optional list of tags to match

Example:

    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <e id="4"/>
      </c>
      <d id="5">
        <e id="6"/>
      </d>
      <c id="7">
        <d id="8">
          <e id="9"/>
        </d>
      </c>
      <d id="10">
        <e id="11"/>
      </d>
      <c id="12">
        <d id="13">
          <e id="14"/>
        </d>
      </c>
    </b>
  </a>
  END

     {my ($d, $c, $D) = $a->findByNumbers(5, 7, 10);

      my @f = $d->from;

      ok @f == 4;

      ok $d == $f[0];

      my @F = $d->from(qw(c));

      ok @F == 2;

      ok -M $F[1] == 12;

      ok $D == $t[-1];

to($@)

Return a list of the sibling nodes preceding the specified node optionally including only those nodes that match one of the tags in the specified list.

     Parameter  Description
  1  $end       End node
  2  @match     Optional list of tags to match

Example:

    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <e id="4"/>
      </c>
      <d id="5">
        <e id="6"/>
      </d>
      <c id="7">
        <d id="8">
          <e id="9"/>
        </d>
      </c>
      <d id="10">
        <e id="11"/>
      </d>
      <c id="12">
        <d id="13">
          <e id="14"/>
        </d>
      </c>
    </b>
  </a>
  END

     {my ($d, $c, $D) = $a->findByNumbers(5, 7, 10);

      my @t = $D->to;

      ok @t == 4;

      my @T = $D->to(qw(c));

      ok @T == 2;

      ok -M $T[1] == 7;

fromTo($$@)

Return a list of the nodes between the specified start and end nodes optionally including only those nodes that match one of the tags in the specified list.

     Parameter  Description
  1  $start     Start node
  2  $end       End node
  3  @match     Optional list of tags to match

Example:

    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <e id="4"/>
      </c>
      <d id="5">
        <e id="6"/>
      </d>
      <c id="7">
        <d id="8">
          <e id="9"/>
        </d>
      </c>
      <d id="10">
        <e id="11"/>
      </d>
      <c id="12">
        <d id="13">
          <e id="14"/>
        </d>
      </c>
    </b>
  </a>
  END

     {my ($d, $c, $D) = $a->findByNumbers(5, 7, 10);

      my @r = $d->fromTo($D);

      ok @r == 3;

      my @R = $d->fromTo($D, qw(c));

      ok @R == 1;

      ok -M $R[0] == 7;

      ok !$D->fromTo($d);

      ok 1 == $d->fromTo($d);

Position

Confirm that the position navigated to is the expected position.

at($@)

     Parameter  Description
  1  $start     Starting node
  2  @context   Ancestry.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c> <d/> </c>
      <c> <e/> </c>
      <c> <f/> </c>
    </b>
  </a>
  END

    ok  $a->go(qw(b c -1 f))->at(qw(f c b a));

    ok  $a->go(qw(b c  1 e))->at(undef, qr(c|d), undef, qq(a));

    ok $d->context eq q(d c b a);

    ok  $d->at(qw(d c b), undef);

    ok !$d->at(qw(d c b), undef, undef);

    ok !$d->at(qw(d e b));

not($@)

Return the specified $node if it does not match any of the specified tags, else undef

     Parameter  Description
  1  $node      Node
  2  @tags      Tags not to match

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
  </a>
  END

    ok $a->first->not_a_c;

atOrBelow($@)

Confirm that the node or one of its ancestors has the specified context as recognized by at and return the first node that matches the context or undef if none do.

     Parameter  Description
  1  $start     Starting node
  2  @context   Ancestry.

Example:

    ok $d->context eq q(d c b a);

    ok  $d->atOrBelow(qw(d c b a));

    ok  $d->atOrBelow(qw(  c b a));

    ok  $d->atOrBelow(qw(    b a));

    ok !$d->atOrBelow(qw(  c   a));

adjacent($$)

Return the first node if it is adjacent to the second node else undef.

     Parameter  Description
  1  $first     First node
  2  $second    Second node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    ok !$a->adjacent($B);

    ok  $b->adjacent($B);

ancestry($)

Return a list containing: (the specified $node, its parent, its parent's parent etc..). Or use upn to go up the specified number of levels.

     Parameter  Description
  1  $node      Starting node.

Example:

    $a->numberTree;

    ok $a->prettyStringNumbered eq <<END;
  <a id="1">
    <b id="2">
      <A id="3"/>
      <B id="4"/>
    </b>
    <c id="5">
      <C id="6"/>
      <D id="7"/>
    </c>
  </a>
  END

    is_deeply [map {-t $_} $a->findByNumber(7)->ancestry], [qw(D c a)];

context($)

Return a string containing the tag of the starting node and the tags of all its ancestors separated by single spaces.

     Parameter  Description
  1  $node      Starting node.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    ok $a->go(qw(d e))->context eq 'e d a';

containsSingleText($@)

Return the single text element below the specified $node else return undef.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new("<a><b>bb</b><c>cc<d/>ee</c></a>");

    ok  $a->go(q(b))->containsSingleText->text eq q(bb);

    ok !$a->go(q(c))->containsSingleText;

depth($)

Returns the depth of the specified $node, the depth of a root node is zero.

     Parameter  Description
  1  $node      Node.

Example:

    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <e id="4"/>
      </c>
      <d id="5">
        <e id="6"/>
      </d>
      <c id="7">
        <d id="8">
          <e id="9"/>
        </d>
      </c>
      <d id="10">
        <e id="11"/>
      </d>
      <c id="12">
        <d id="13">
          <e id="14"/>
        </d>
      </c>
    </b>
  </a>
  END

    ok 0 == $a->depth;

    ok 4 == $a->findByNumber(14)->depth;

isFirst($@)

Return the specified $node if it is first under its parent and optionally has the specified context, else return undef

     Parameter  Description
  1  $node      Node
  2  @context   Optional context

Use isFirstNonBlank to skip a (rare) initial blank text CDATA. Use isFirstNonBlankX to die rather then receive a returned undef or false result.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    ok $a->go(q(b))->isFirst;

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    ok  $a->isFirst;

isFirstToDepth($$@)

Return the specified $node if it is first to the specified depth else return undef

     Parameter  Description
  1  $node      Node
  2  $depth     Depth
  3  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $f, $e) = $a->byList;

    ok  $d->isFirstToDepth(4);

    ok !$f->isFirstToDepth(2);

    ok  $f->isFirstToDepth(1);

    ok !$f->isFirstToDepth(3);

isLast($@)

Return the specified $node if it is last under its parent and optionally has the specified context, else return undef

     Parameter  Description
  1  $node      Node
  2  @context   Optional context

Use isLastNonBlank to skip a (rare) initial blank text CDATA. Use isLastNonBlankX to die rather then receive a returned undef or false result.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    ok $a->go(q(d))->isLast;

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    ok  $a->isLast;

isLastToDepth($$@)

Return the specified $node if it is last to the specified depth else return undef

     Parameter  Description
  1  $node      Node
  2  $depth     Depth
  3  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $f, $e) = $a->byList;

    ok  $c->isLastToDepth(1);

    ok !$c->isLastToDepth(3);

    ok  $d->isLastToDepth(2);

    ok !$d->isLastToDepth(4);

isOnlyChild($@)

Return the specified $node if it is the only node under its parent ignoring any surrounding blank text.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $f, $e) = $a->byList;

    ok  $d->isOnlyChild;

    ok !$d->isOnlyChild(qw(b));

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    ok  $a->isOnlyChild;

isOnlyChildToDepth($$@)

Return the specified $node if it and its ancestors are only children to the specified depth else return undef. isOnlyChildToDepth(1) is the same as isOnlychild

     Parameter  Description
  1  $node      Node
  2  $depth     Depth to which each parent node must also be an only child
  3  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $f, $e) = $a->byList;

    ok  $d->isOnlyChildToDepth(1, qw(d c b a));

    ok  $d->isOnlyChildToDepth(2, qw(d c b a));

    ok !$d->isOnlyChildToDepth(3, qw(d c b a));

singleChild($@)

Return the only child of the specified $node if the child is the only node under its parent ignoring any surrounding blank text and has the optional specified context, else return undef.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b   id="b" b="bb">
      <b id="c" c="cc"/>
    </b>
  </a>
  END

    my ($c, $b) = $a->byList;

    is_deeply [$b->id, $c->id], [qw(b c)];

    ok $c == $b->singleChild;

    ok $b == $a->singleChild;

singleChildToDepth($$@)

Return the specified $node if it has single children to at least the specified depth else return undef. singleChildToDepth(0) is equivalent to singleChild.

     Parameter  Description
  1  $node      Node
  2  $depth     Depth
  3  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    ok $h == $g->singleChildToDepth(1);

    ok $i == $g->singleChildToDepth(2);

    ok      !$g->singleChildToDepth(0);

    ok      !$g->singleChildToDepth(3);

    ok $i == $i->singleChildToDepth(0);

isEmpty($@)

Confirm that the specified $node is empty, that is: the specified $node has no content, not even a blank string of text. To test for blank nodes, see isAllBlankText.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>

  </a>
  END

    ok $x->isEmpty;

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $f, $e) = $a->byList;

    ok  $d->isEmpty;

over($$@)

Confirm that the string representing the tags at the level below the specified $node match a regular expression where each pair of tags is separated by a single space. Use contentAsTags to visualize the tags at the next level.

     Parameter  Description
  1  $node      Node
  2  $re        Regular expression
  3  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok $x->go(q(b))->over(qr(d.+e));

over2($$@)

Confirm that the string representing the tags at the level below the specified $node match a regular expression where each pair of tags have two spaces between them and the first tag is preceded by a single space and the last tag is followed by a single space. This arrangement simplifies the regular expression used to detect combinations like p+ q? . Use contentAsTags2 to visualize the tags at the next level.

     Parameter  Description
  1  $node      Node
  2  $re        Regular expression
  3  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok $x->go(q(b))->over2(qr(\A c  d  e  f  g \Z));

    ok $x->go(q(b))->contentAsTags  eq q(c d e f g) ;

overAllTags($@)

Return the specified b<$node> if all of it's child nodes match the specified <@tags> else return undef.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
    <c/>
    <d/>
  </a>
  END

    ok  $a->overAllTags_b_c_d;
    ok !$a->overAllTags_b_c;
    ok !$a->overAllTags_b_c_d_e;
    ok  $a->oat_b_c_d;
    ok !$a->oat_B_c_d;

    ok  $a->overFirstTags_b_c_d;
    ok  $a->overFirstTags_b_c;
    ok !$a->overFirstTags_b_c_d_e;
    ok  $a->oft_b_c;
    ok !$a->oft_B_c;

    ok  $a->overLastTags_b_c_d;
    ok  $a->overLastTags_c_d;
    ok !$a->overLastTags_b_c_d_e;
    ok  $a->olt_c_d;
    ok !$a->olt_C_d;
   }

oat is a synonym for overAllTags.

overFirstTags($@)

Return the specified b<$node> if the first of it's child nodes match the specified <@tags> else return undef.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
    <c/>
    <d/>
  </a>
  END

    ok  $a->overAllTags_b_c_d;
    ok !$a->overAllTags_b_c;
    ok !$a->overAllTags_b_c_d_e;
    ok  $a->oat_b_c_d;
    ok !$a->oat_B_c_d;

    ok  $a->overFirstTags_b_c_d;
    ok  $a->overFirstTags_b_c;
    ok !$a->overFirstTags_b_c_d_e;
    ok  $a->oft_b_c;
    ok !$a->oft_B_c;

    ok  $a->overLastTags_b_c_d;
    ok  $a->overLastTags_c_d;
    ok !$a->overLastTags_b_c_d_e;
    ok  $a->olt_c_d;
    ok !$a->olt_C_d;
   }

oft is a synonym for overFirstTags.

overLastTags($@)

Return the specified b<$node> if the last of it's child nodes match the specified <@tags> else return undef.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
    <c/>
    <d/>
  </a>
  END

    ok  $a->overAllTags_b_c_d;
    ok !$a->overAllTags_b_c;
    ok !$a->overAllTags_b_c_d_e;
    ok  $a->oat_b_c_d;
    ok !$a->oat_B_c_d;

    ok  $a->overFirstTags_b_c_d;
    ok  $a->overFirstTags_b_c;
    ok !$a->overFirstTags_b_c_d_e;
    ok  $a->oft_b_c;
    ok !$a->oft_B_c;

    ok  $a->overLastTags_b_c_d;
    ok  $a->overLastTags_c_d;
    ok !$a->overLastTags_b_c_d_e;
    ok  $a->olt_c_d;
    ok !$a->olt_C_d;
   }

olt is a synonym for overLastTags.

matchAfter($$@)

Confirm that the string representing the tags following the specified $node matches a regular expression where each pair of tags is separated by a single space. Use contentAfterAsTags to visualize these tags.

     Parameter  Description
  1  $node      Node
  2  $re        Regular expression
  3  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok $x->go(qw(b e))->matchAfter  (qr(\Af g\Z));

matchAfter2($$@)

Confirm that the string representing the tags following the specified $node matches a regular expression where each pair of tags have two spaces between them and the first tag is preceded by a single space and the last tag is followed by a single space. This arrangement simplifies the regular expression used to detect combinations like p+ q? Use contentAfterAsTags2 to visualize these tags.

     Parameter  Description
  1  $node      Node
  2  $re        Regular expression
  3  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok $x->go(qw(b e))->matchAfter2 (qr(\A f  g \Z));

matchBefore($$@)

Confirm that the string representing the tags preceding the specified $node matches a regular expression where each pair of tags is separated by a single space. Use contentBeforeAsTags to visualize these tags.

     Parameter  Description
  1  $node      Node
  2  $re        Regular expression
  3  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok $x->go(qw(b e))->matchBefore (qr(\Ac d\Z));

matchBefore2($$@)

Confirm that the string representing the tags preceding the specified $node matches a regular expression where each pair of tags have two spaces between them and the first tag is preceded by a single space and the last tag is followed by a single space. This arrangement simplifies the regular expression used to detect combinations like p+ q? Use contentBeforeAsTags2 to visualize these tags.

     Parameter  Description
  1  $node      Node
  2  $re        Regular expression
  3  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok $x->go(qw(b e))->matchBefore2(qr(\A c  d \Z));

path($)

Return a list representing the path to a node from the root of the parse tree which can then be reused by go to retrieve the node as long as the structure of the parse tree has not changed along the path.

     Parameter  Description
  1  $node      Node.

Example:

    my $x = Data::Edit::Xml::new(<<END);
  <a       id='a1'>
    <b     id='b1'>
      <c   id='c1'/>
      <c   id='c2'/>
      <d   id='d1'>
        <e id='e1'/>
      </d>
      <c   id='c3'/>
      <c   id='c4'/>
      <d   id='d2'>
        <e id='e2'/>
      </d>
      <c   id='c5'/>
      <c   id='c6'/>
    </b>
  </a>
  END

    is_deeply [$x->go(qw(b d 1 e))->path], [qw(b d 1 e)];

    $x->by(sub {ok $x->go($_->path) == $_});

pathString($)

Return a string representing the path to the specified $node from the root of the parse tree.

     Parameter  Description
  1  $node      Node.

Example:

    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <e id="4"/>
      </c>
      <d id="5">
        <e id="6"/>
      </d>
      <c id="7">
        <d id="8">
          <e id="9"/>
        </d>
      </c>
      <d id="10">
        <e id="11"/>
      </d>
      <c id="12">
        <d id="13">
          <e id="14"/>
        </d>
      </c>
    </b>
  </a>
  END

    ok $a->findByNumber(9)->pathString eq 'b c 1 d e';

Prev At Next

Locate adjacent nodes that match horizontally and vertically

an($$@)

Return the next node if the specified $node has the specified tag and the next node is in the specified context.

     Parameter  Description
  1  $node      Node
  2  $tag       Tag node must match
  3  @context   Optional context of the next node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    ok  $e == $d->an_d_e_b_a;

    ok  $f == $e->an_e;

    ok !$f->an_f;

ap($$@)

Return the previous node if the specified $node has the specified tag and the previous node is in the specified context.

     Parameter  Description
  1  $node      Node
  2  $tag       Tag node must match
  3  @context   Optional context of the previous node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    ok  $c == $d->ap_d_c_b_a;

    ok  $c == $d->ap_d;

    ok !$c->ap_c;

apn($$$@)

Return (previous node, next node) if the previous and current nodes have the specified tags and the next node is in the specified context else return ().

     Parameter  Description
  1  $node      Current node
  2  $prev      Tag for the previous node
  3  $tag       Tag for specified node
  4  @context   Context for the next node.

Use the @context parameter to test the context of the specified $node as understood by method at. If a context is supplied and $node is not in this context then this method returns an empty list () immediately.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    is_deeply[$c, $e], [$d->apn_c_d_e_b_a];

matchesNextTags($@)

Return the specified b<$node> if the siblings following the specified $node match the specified <@tags> else return undef.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c/><d/><e/><f/></b></a>
  END

    ok  -t $a->first__first__matchesNextTags_d_e eq q(c);
    ok  -t $a->first__first__mnt_d_e             eq q(c);
    ok    !$a->       first__matchesNextTags_d_e;
    ok  -t $a->  last->last__matchesPrevTags_e_d eq q(f);
    ok  -t $a->  last->last__mpt_e_d             eq q(f);
    ok    !$a->        last__matchesPrevTags_e_d;
   }

mnt is a synonym for matchesNextTags.

matchesPrevTags($@)

Return the specified b<$node> if the siblings prior to the specified $node match the specified <@tags> else return undef.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c/><d/><e/><f/></b></a>
  END

    ok  -t $a->first__first__matchesNextTags_d_e eq q(c);
    ok  -t $a->first__first__mnt_d_e             eq q(c);
    ok    !$a->       first__matchesNextTags_d_e;
    ok  -t $a->  last->last__matchesPrevTags_e_d eq q(f);
    ok  -t $a->  last->last__mpt_e_d             eq q(f);
    ok    !$a->        last__matchesPrevTags_e_d;
   }

mpt is a synonym for matchesPrevTags.

Move around in the parse tree.

go($@)

     Parameter  Description
  1  $node      Node
  2  @path      Search specification.

Example:

   {my $x = Data::Edit::Xml::new(my $s = <<END);
  <aa>
    <a>
      <b/>
        <c id="1"/><c id="2"/><c id="3"/><c id="4"/>
      <d/>
    </a>
  </aa>
  END

    ok $x->go(qw(a c))   ->id == 1;

    ok $x->go(qw(a c -2))->id == 3;

    ok $x->go(qw(a c *)) == 4;

    ok 1234 == join '', map {$_->id} $x->go(qw(a c *));

c($$)

Return an array of all the nodes with the specified tag below the specified $node. This method is deprecated in favor of applying grep to contents.

     Parameter  Description
  1  $node      Node
  2  $tag       Tag.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b id="b1"><c id="1"/></b>
    <d id="d1"><c id="2"/></d>
    <e id="e1"><c id="3"/></e>
    <b id="b2"><c id="4"/></b>
    <d id="d2"><c id="5"/></d>
    <e id="e2"><c id="6"/></e>
  </a>
  END

    is_deeply [map{-u $_} $x->c(q(d))],  [qw(d1 d2)];

First

Find nodes that are first amongst their siblings.

first($@)

Return the first node below the specified $node optionally checking its context. See addFirst to ensure that an expected node is in position.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Use firstNonBlank to skip a (rare) initial blank text CDATA. Use firstNonBlankX to die rather then receive a returned undef or false result.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a         id="11">
    <b       id="12">
       <c    id="13"/>
       <d    id="14"/>
       <b    id="15">
          <c id="16"/>
          <d id="17"/>
          <e id="18"/>
          <f id="19"/>
          <g id="20"/>
       </b>
       <f    id="21"/>
       <g    id="22"/>
    </b>
    <b       id="23">
       <c    id="24"/>
       <d    id="25"/>
       <b    id="26">
          <c id="27"/>
          <d id="28"/>
          <e id="29"/>
          <f id="30"/>
          <g id="31"/>
       </b>
       <f    id="32"/>
       <g    id="33"/>
    </b>
  </a>
  END

    ok  $a->go(q(b))->first->id == 13;

    ok  $a->go(q(b))->first(qw(c b a));

    ok !$a->go(q(b))->first(qw(b a));

firstn($$@)

Return the $n'th first node below the specified $node optionally checking its context or undef if there is no such node. firstn(1) is identical in effect to first.

     Parameter  Description
  1  $node      Node
  2  $N         Number of times to go first
  3  @context   Optional context.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><d/><e/><f/></c></b></a>
  END
    ok -p $a eq <<END;
  <a>
    <b>
      <c>
        <d/>
        <e/>
        <f/>
      </c>
    </b>
  </a>
  END
    ok  -t $a->firstn_0 eq q(a);
    ok  -t $a->firstn_1 eq q(b);
    ok  -t $a->firstn_2 eq q(c);
    ok  -t $a->firstn_3 eq q(d);

    ok  -t $a->firstn_3__nextn_0 eq q(d);
    ok  -t $a->firstn_3__nextn_1 eq q(e);
    ok  -t $a->firstn_3__nextn_2 eq q(f);
   }

firstText($@)

Return the first node if it is a text node otherwise undef

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

    ok -p $a eq <<END;
  <a>AA
    <b/>
  BB
    <c/>
  CC
    <d/>
    <e/>
    <f/>
  DD
    <g/>
  HH
  </a>
  END

    ok  $a->firstText;

    ok !$a->go(qw(c))->firstText;

firstTextMatches($$@)

Return the first node under the specified $node if: it is a text mode; its text matches the specified regular expression; the specified $node is in the optional specified context. Else return undef.

     Parameter  Description
  1  $node      Node
  2  $match     Regular expression the text must match
  3  @context   Optional context of specified node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>bb<c>cc</c>BB
    </b>
  </a>
  END

    my ($bb, $cc, $c, $BB, $b) = $a->byList;

    ok $bb->matchesText(qr(bb));

    ok $b->at_b_a &&  $b->firstTextMatches(qr(bb));

    ok                $b->firstTextMatches(qr(bb), qw(b a));

    ok $c->at_c_b &&  $c->firstTextMatches(qr(cc));

    ok $c->at_c_b && !$c->firstTextMatches(qr(bb));

firstBy($@)

Return a list of the first instance of each specified tag encountered in a post-order traversal from the specified $node or a hash of all first instances if no tags are specified.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to search for.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a         id="11">
    <b       id="12">
       <c    id="13"/>
       <d    id="14"/>
       <b    id="15">
          <c id="16"/>
          <d id="17"/>
          <e id="18"/>
          <f id="19"/>
          <g id="20"/>
       </b>
       <f    id="21"/>
       <g    id="22"/>
    </b>
    <b       id="23">
       <c    id="24"/>
       <d    id="25"/>
       <b    id="26">
          <c id="27"/>
          <d id="28"/>
          <e id="29"/>
          <f id="30"/>
          <g id="31"/>
       </b>
       <f    id="32"/>
       <g    id="33"/>
    </b>
  </a>
  END

     {my %f = $a->firstBy;

      ok $f{b}->id == 12;

firstDown($@)

Return a list of the first instance of each specified tag encountered in a pre-order traversal from the specified $node or a hash of all first instances if no tags are specified.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to search for.

Example:

     {my %f = $a->firstDown;

      ok $f{b}->id == 15;

firstIn($@)

Return the first child node matching one of the named tags under the specified parent node.

     Parameter  Description
  1  $node      Parent node
  2  @tags      Child tags to search for.

Example:

    ok $a->prettyStringCDATA eq <<'END';
  <a><CDATA> </CDATA>
      <A/>
  <CDATA>  </CDATA>
      <C/>
  <CDATA>  </CDATA>
      <E/>
  <CDATA>  </CDATA>
      <G/>
  <CDATA>  </CDATA>
  </a>
  END

    ok $a->firstIn(qw(b B c C))->tag eq qq(C);

firstNot($@)

Return the first child node that does not match any of the named @tags under the specified parent $node. Return undef if there is no such child node.

     Parameter  Description
  1  $node      Parent node
  2  @tags      Child tags to avoid.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
    <c/>
    <d/>
    <e/>
    <f/>
  </a>
  END

    my ($b, $c, $d, $e, $f) = $a->byList;

    ok $c == $a->firstNot_a_b;

firstInIndex($@)

Return the specified $node if it is first in its index and optionally at the specified context else undef

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <e id="4"/>
      </c>
      <d id="5">
        <e id="6"/>
      </d>
      <c id="7">
        <d id="8">
          <e id="9"/>
        </d>
      </c>
      <d id="10">
        <e id="11"/>
      </d>
      <c id="12">
        <d id="13">
          <e id="14"/>
        </d>
      </c>
    </b>
  </a>
  END

    ok  $a->findByNumber (5)->firstInIndex;

    ok !$a->findByNumber(7) ->firstInIndex;

firstOf($@)

Return an array of the nodes that are continuously first under their specified parent node and that match the specified list of tags.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to search for.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c/><d/><d/><e/><d/><d/><c/></b></a>
  END

    is_deeply [qw(c d d)], [map {-t $_} $a->go(q(b))->firstOf(qw(c d))];

firstWhile($@)

Go first from the specified $node and continue deeper as long as each first child node matches one of the specified @tags. Return the deepest such node encountered or else return undef if no such node is encountered.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to search for.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><d><e><f/>
  </e></d></c></b>
  <B><C><D><E><F/>
  </E></D></C></B></a>
  END

    my ($f, $e, $d, $c, $b, $F, $E, $D, $C, $B) = $a->byList;

    if (1)

firstUntil($@)

Go first from the specified $node and continue deeper until a first child node matches the specified @context or return undef if there is no such node. Return the first child of the specified $node if no @context is specified.

     Parameter  Description
  1  $node      Node
  2  @context   Context to search for.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><d><e><f/>
  </e></d></c></b>
  <B><C><D><E><F/>
  </E></D></C></B></a>
  END

    my ($f, $e, $d, $c, $b, $F, $E, $D, $C, $B) = $a->byList;

    if (1)

firstContextOf($@)

Return the first node encountered in the specified context in a depth first post-order traversal of the parse tree.

     Parameter  Description
  1  $node      Node
  2  @context   Array of tags specifying context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a        id="a1">
    <b1     id="b1">
       <c   id="c1">
         <d id="d1">DD11</d>
         <e id="e1">EE11</e>
      </c>
    </b1>
    <b2     id="b2">
       <c   id="c2">
         <d id="d2">DD22</d>
         <e id="e2">EE22</e>
      </c>
    </b2>
    <b3     id="b3">
       <c   id="c3">
         <d id="d3">DD33</d>
         <e id="e3">EE33</e>
      </c>
    </b3>
  </a>
  END

    ok $x->firstContextOf(qw(d c))         ->id     eq qq(d1);

    ok $x->firstContextOf(qw(e c b2))      ->id     eq qq(e2);

    ok $x->firstContextOf(qw(CDATA d c b2))->string eq qq(DD22);

firstSibling($@)

Return the first sibling of the specified $node in the optional context else undef

     Parameter  Description
  1  $node      Node
  2  @context   Array of tags specifying context.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a         id="11">
    <b       id="12">
       <c    id="13"/>
       <d    id="14"/>
       <b    id="15">
          <c id="16"/>
          <d id="17"/>
          <e id="18"/>
          <f id="19"/>
          <g id="20"/>
       </b>
       <f    id="21"/>
       <g    id="22"/>
    </b>
    <b       id="23">
       <c    id="24"/>
       <d    id="25"/>
       <b    id="26">
          <c id="27"/>
          <d id="28"/>
          <e id="29"/>
          <f id="30"/>
          <g id="31"/>
       </b>
       <f    id="32"/>
       <g    id="33"/>
    </b>
  </a>
  END

    ok  $a->go(qw(b b))->firstSibling->id == 13;

Last

Find nodes that are last amongst their siblings.

last($@)

Return the last node below the specified $node optionally checking its context. See addLast to ensure that an expected node is in position.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Use lastNonBlank to skip a (rare) initial blank text CDATA. Use lastNonBlankX to die rather then receive a returned undef or false result.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a         id="11">
    <b       id="12">
       <c    id="13"/>
       <d    id="14"/>
       <b    id="15">
          <c id="16"/>
          <d id="17"/>
          <e id="18"/>
          <f id="19"/>
          <g id="20"/>
       </b>
       <f    id="21"/>
       <g    id="22"/>
    </b>
    <b       id="23">
       <c    id="24"/>
       <d    id="25"/>
       <b    id="26">
          <c id="27"/>
          <d id="28"/>
          <e id="29"/>
          <f id="30"/>
          <g id="31"/>
       </b>
       <f    id="32"/>
       <g    id="33"/>
    </b>
  </a>
  END

    ok  $a->go(q(b))->last ->id == 22;

    ok  $a->go(q(b))->last(qw(g b a));

    ok !$a->go(q(b))->last(qw(b a));

    ok !$a->go(q(b))->last(qw(b a));

lastn($$@)

Return the $n'th last node below the specified $node optionally checking its context or undef if there is no such node. lastn(1) is identical in effect to last.

     Parameter  Description
  1  $node      Node
  2  $N         Number of times to go last
  3  @context   Optional context.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><d/><e/><f/></c></b>
     <B><C><D/><E/><F/></C></B></a>
  END
    ok -p $a eq <<END;
  <a>
    <b>
      <c>
        <d/>
        <e/>
        <f/>
      </c>
    </b>
    <B>
      <C>
        <D/>
        <E/>
        <F/>
      </C>
    </B>
  </a>
  END

    ok  -t $a->lastn_0 eq q(a);
    ok  -t $a->lastn_1 eq q(B);
    ok  -t $a->lastn_2 eq q(C);
    ok  -t $a->lastn_3 eq q(F);

    ok  -t $a->lastn_3__prevn_0 eq q(F);
    ok  -t $a->lastn_3__prevn_1 eq q(E);
    ok  -t $a->lastn_3__prevn_2 eq q(D);
   }

lastText($@)

Return the last node if it is a text node otherwise undef

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

    ok -p $a eq <<END;
  <a>AA
    <b/>
  BB
    <c/>
  CC
    <d/>
    <e/>
    <f/>
  DD
    <g/>
  HH
  </a>
  END

    ok  $a->lastText;

    ok !$a->go(qw(c))->lastText;

lastTextMatches($$@)

Return the last node under the specified $node if: it is a text mode; its text matches the specified regular expression; the specified $node is in the optional specified context. Else return undef.

     Parameter  Description
  1  $node      Node
  2  $match     Regular expression the text must match
  3  @context   Optional context of specified  node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>bb<c>cc</c>BB
    </b>
  </a>
  END

    my ($bb, $cc, $c, $BB, $b) = $a->byList;

    ok $BB->matchesText(qr(BB));

    ok $b->at_b_a &&  $b->lastTextMatches(qr(BB));

    ok                $b->lastTextMatches(qr(BB), qw(b a));

    ok $c->at_c_b &&  $c->lastTextMatches(qr(cc));

    ok $c->at_c_b && !$c->lastTextMatches(qr(bb));

lastBy($@)

Return a list of the last instance of each specified tag encountered in a post-order traversal from the specified $node or a hash of all last instances if no tags are specified.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to search for.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a         id="11">
    <b       id="12">
       <c    id="13"/>
       <d    id="14"/>
       <b    id="15">
          <c id="16"/>
          <d id="17"/>
          <e id="18"/>
          <f id="19"/>
          <g id="20"/>
       </b>
       <f    id="21"/>
       <g    id="22"/>
    </b>
    <b       id="23">
       <c    id="24"/>
       <d    id="25"/>
       <b    id="26">
          <c id="27"/>
          <d id="28"/>
          <e id="29"/>
          <f id="30"/>
          <g id="31"/>
       </b>
       <f    id="32"/>
       <g    id="33"/>
    </b>
  </a>
  END

     {my %l = $a->lastBy;

      ok $l{b}->id == 23;

lastDown($@)

Return a list of the last instance of each specified tag encountered in a pre-order traversal from the specified $node or a hash of all last instances if no tags are specified.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to search for.

Example:

     {my %l = $a->lastDown;

      ok $l{b}->id == 26;

lastIn($@)

Return the last child node matching one of the named tags under the specified parent node.

     Parameter  Description
  1  $node      Parent node
  2  @tags      Child tags to search for.

Example:

    ok $a->prettyStringCDATA eq <<'END';
  <a><CDATA> </CDATA>
      <A/>
  <CDATA>  </CDATA>
      <C/>
  <CDATA>  </CDATA>
      <E/>
  <CDATA>  </CDATA>
      <G/>
  <CDATA>  </CDATA>
  </a>
  END

    ok $a->lastIn(qw(e E f F))->tag eq qq(E);

lastNot($@)

Return the last child node that does not match any of the named @tags under the specified parent $node. Return undef if there is no such child node.

     Parameter  Description
  1  $node      Parent node
  2  @tags      Child tags to avoid.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
    <c/>
    <d/>
    <e/>
    <f/>
  </a>
  END

    my ($b, $c, $d, $e, $f) = $a->byList;

    ok $d == $a->lastNot_e_f;

lastOf($@)

Return an array of the nodes that are continuously last under their specified parent node and that match the specified list of tags.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to search for.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c/><d/><d/><e/><d/><d/><c/></b></a>
  END

    is_deeply [qw(d d c)], [map {-t $_} $a->go(q(b))->lastOf (qw(c d))];

lastInIndex($@)

Return the specified $node if it is last in its index and optionally at the specified context else undef

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <e id="4"/>
      </c>
      <d id="5">
        <e id="6"/>
      </d>
      <c id="7">
        <d id="8">
          <e id="9"/>
        </d>
      </c>
      <d id="10">
        <e id="11"/>
      </d>
      <c id="12">
        <d id="13">
          <e id="14"/>
        </d>
      </c>
    </b>
  </a>
  END

    ok  $a->findByNumber(10)->lastInIndex;

    ok !$a->findByNumber(7) ->lastInIndex;

lastContextOf($@)

Return the last node encountered in the specified context in a depth first reverse pre-order traversal of the parse tree.

     Parameter  Description
  1  $node      Node
  2  @context   Array of tags specifying context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a        id="a1">
    <b1     id="b1">
       <c   id="c1">
         <d id="d1">DD11</d>
         <e id="e1">EE11</e>
      </c>
    </b1>
    <b2     id="b2">
       <c   id="c2">
         <d id="d2">DD22</d>
         <e id="e2">EE22</e>
      </c>
    </b2>
    <b3     id="b3">
       <c   id="c3">
         <d id="d3">DD33</d>
         <e id="e3">EE33</e>
      </c>
    </b3>
  </a>
  END

    ok $x-> lastContextOf(qw(d c))         ->id     eq qq(d3);

    ok $x-> lastContextOf(qw(e c b2     )) ->id     eq qq(e2);

    ok $x-> lastContextOf(qw(CDATA e c b2))->string eq qq(EE22);

lastSibling($@)

Return the last sibling of the specified $node in the optional context else undef

     Parameter  Description
  1  $node      Node
  2  @context   Array of tags specifying context.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a         id="11">
    <b       id="12">
       <c    id="13"/>
       <d    id="14"/>
       <b    id="15">
          <c id="16"/>
          <d id="17"/>
          <e id="18"/>
          <f id="19"/>
          <g id="20"/>
       </b>
       <f    id="21"/>
       <g    id="22"/>
    </b>
    <b       id="23">
       <c    id="24"/>
       <d    id="25"/>
       <b    id="26">
          <c id="27"/>
          <d id="28"/>
          <e id="29"/>
          <f id="30"/>
          <g id="31"/>
       </b>
       <f    id="32"/>
       <g    id="33"/>
    </b>
  </a>
  END

    ok  $a->go(qw(b b))->lastSibling ->id == 22;

lastWhile($@)

Go last from the specified $node and continue deeper as long as each last child node matches one of the specified @tags. Return the deepest such node encountered or else return undef if no such node is encountered.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to search for.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><d><e><f/>
  </e></d></c></b>
  <B><C><D><E><F/>
  </E></D></C></B></a>
  END

    my ($f, $e, $d, $c, $b, $F, $E, $D, $C, $B) = $a->byList;

    if (1)

lastUntil($@)

Go last from the specified $node and continue deeper until a last child node matches the specified @context or return undef if there is no such node. Return the last child of the specified $node if no @context is specified.

     Parameter  Description
  1  $node      Node
  2  @context   Context to search for.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><d><e><f/>
  </e></d></c></b>
  <B><C><D><E><F/>
  </E></D></C></B></a>
  END

    my ($f, $e, $d, $c, $b, $F, $E, $D, $C, $B) = $a->byList;

    if (1)

Find sibling nodes after the specified $node.

next($@)

Return the node next to the specified $node, optionally checking its context. See addNext to ensure that an expected node is in position.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Use nextNonBlank to skip a (rare) initial blank text CDATA. Use nextNonBlankX to die rather then receive a returned undef or false result.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a         id="11">
    <b       id="12">
       <c    id="13"/>
       <d    id="14"/>
       <b    id="15">
          <c id="16"/>
          <d id="17"/>
          <e id="18"/>
          <f id="19"/>
          <g id="20"/>
       </b>
       <f    id="21"/>
       <g    id="22"/>
    </b>
    <b       id="23">
       <c    id="24"/>
       <d    id="25"/>
       <b    id="26">
          <c id="27"/>
          <d id="28"/>
          <e id="29"/>
          <f id="30"/>
          <g id="31"/>
       </b>
       <f    id="32"/>
       <g    id="33"/>
    </b>
  </a>
  END

    ok  $a->go(qw(b b e))->next ->id == 19;

    ok  $a->go(qw(b b e))->next(qw(f b b a));

    ok !$a->go(qw(b b e))->next(qw(f b a));

nextn($$@)

Return the $n'th next node after the specified $node optionally checking its context or undef if there is no such node. nextn(1) is identical in effect to next.

     Parameter  Description
  1  $node      Node
  2  $N         Number of times to go next
  3  @context   Optional context.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><d/><e/><f/></c></b></a>
  END
    ok -p $a eq <<END;
  <a>
    <b>
      <c>
        <d/>
        <e/>
        <f/>
      </c>
    </b>
  </a>
  END
    ok  -t $a->firstn_0 eq q(a);
    ok  -t $a->firstn_1 eq q(b);
    ok  -t $a->firstn_2 eq q(c);
    ok  -t $a->firstn_3 eq q(d);

    ok  -t $a->firstn_3__nextn_0 eq q(d);
    ok  -t $a->firstn_3__nextn_1 eq q(e);
    ok  -t $a->firstn_3__nextn_2 eq q(f);
   }

nextText($@)

Return the next node after the specified $node if it is a text node otherwise undef

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

    ok -p $a eq <<END;
  <a>AA
    <b/>
  BB
    <c/>
  CC
    <d/>
    <e/>
    <f/>
  DD
    <g/>
  HH
  </a>
  END

    ok  $a->go(qw(c))->nextText->text eq q(CC);

    ok !$a->go(qw(e))->nextText;

nextTextMatches($$@)

Return the next node to the specified $node if: it is a text mode; its text matches the specified regular expression; the specified $node is in the optional specified context. Else return undef.

     Parameter  Description
  1  $node      Node
  2  $match     Regular expression the text must match
  3  @context   Optional context of specified node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>bb<c>cc</c>BB
    </b>
  </a>
  END

    ok $cc->matchesText(qr(cc));

    ok $c->at_c_b &&  $c->nextTextMatches(qr(BB));

    ok $b->at_b   && !$b->nextTextMatches(qr(BB));

nextIn($@)

Return the nearest sibling after the specified $node that matches one of the named tags or undef if there is no such sibling node.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to search for.

Example:

    ok $a->prettyStringCDATA eq <<'END';
  <a><CDATA> </CDATA>
      <A/>
  <CDATA>  </CDATA>
      <C/>
  <CDATA>  </CDATA>
      <E/>
  <CDATA>  </CDATA>
      <G/>
  <CDATA>  </CDATA>
  </a>
  END

    ok $a->firstIn(qw(b B c C))->nextIn(qw(A G))->tag eq qq(G);

nextOn($@)

Step forwards as far as possible from the specified $node while remaining on nodes with the specified tags. In scalar context return the last such node reached or the starting node if no such steps are possible. In array context return the start node and any following matching nodes.

     Parameter  Description
  1  $node      Start node
  2  @tags      Tags identifying nodes that can be step on to context.

Example:

    ok -p $a eq <<END;
  <a>
    <b>
      <c id="1"/>
      <d id="2"/>
      <c id="3"/>
      <d id="4"/>
      <e id="5"/>
    </b>
  </a>
  END

    ok $c->id == 1;

    ok $e->id == 5;

    ok $c->nextOn(qw(d))  ->id == 2;

    ok $c->nextOn(qw(c d))->id == 4;

    ok $e->nextOn(qw(c d))     == $e;

nextWhile($@)

Go to the next sibling of the specified $node and continue forwards while the tag of each sibling node matches one of the specified @tags. Return the first sibling node that does not match else undef if there is no such sibling.

     Parameter  Description
  1  $node      Node
  2  @tags      Child tags to avoid.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
    <c/>
    <d/>
    <e/>
    <f/>
  </a>
  END

    my ($b, $c, $d, $e, $f) = $a->byList;

    ok $e == $b->nextWhile_c_d;

    ok $c == $b->nextWhile;

nextUntil($@)

Go to the next sibling of the specified $node and continue forwards until the tag of a sibling node matches one of the specified @tags. Return the matching sibling node else undef if there is no such sibling node.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to look for.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
    <c/>
    <d/>
    <e/>
    <f/>
  </a>
  END

    my ($b, $c, $d, $e, $f) = $a->byList;

    ok $e == $b->nextUntil_e_f;

    ok      !$b->nextUntil;

Find sibling nodes before the specified $node.

prev($@)

Return the node before the specified $node, optionally checking its context. See addLast to ensure that an expected node is in position.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Use prevNonBlank to skip a (rare) initial blank text CDATA. Use prevNonBlankX to die rather then receive a returned undef or false result.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a         id="11">
    <b       id="12">
       <c    id="13"/>
       <d    id="14"/>
       <b    id="15">
          <c id="16"/>
          <d id="17"/>
          <e id="18"/>
          <f id="19"/>
          <g id="20"/>
       </b>
       <f    id="21"/>
       <g    id="22"/>
    </b>
    <b       id="23">
       <c    id="24"/>
       <d    id="25"/>
       <b    id="26">
          <c id="27"/>
          <d id="28"/>
          <e id="29"/>
          <f id="30"/>
          <g id="31"/>
       </b>
       <f    id="32"/>
       <g    id="33"/>
    </b>
  </a>
  END

    ok  $a->go(qw(b b e))->prev ->id == 17;

    ok  $a->go(qw(b b e))->prev(qw(d b b a));

    ok !$a->go(qw(b b e))->prev(qw(d b a));

prevText($@)

Return the previous node if it is a text node otherwise undef

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

    ok -p $a eq <<END;
  <a>AA
    <b/>
  BB
    <c/>
  CC
    <d/>
    <e/>
    <f/>
  DD
    <g/>
  HH
  </a>
  END

    ok  $a->go(qw(c))->prevText->text eq q(BB);

    ok !$a->go(qw(e))->prevText;

prevn($$@)

Return the $n'th previous node after the specified $node optionally checking its context or undef if there is no such node. prevn(1) is identical in effect to prev.

     Parameter  Description
  1  $node      Node
  2  $N         Number of times to go prev
  3  @context   Optional context.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><d/><e/><f/></c></b>
     <B><C><D/><E/><F/></C></B></a>
  END
    ok -p $a eq <<END;
  <a>
    <b>
      <c>
        <d/>
        <e/>
        <f/>
      </c>
    </b>
    <B>
      <C>
        <D/>
        <E/>
        <F/>
      </C>
    </B>
  </a>
  END

    ok  -t $a->lastn_0 eq q(a);
    ok  -t $a->lastn_1 eq q(B);
    ok  -t $a->lastn_2 eq q(C);
    ok  -t $a->lastn_3 eq q(F);

    ok  -t $a->lastn_3__prevn_0 eq q(F);
    ok  -t $a->lastn_3__prevn_1 eq q(E);
    ok  -t $a->lastn_3__prevn_2 eq q(D);
   }

prevTextMatches($$@)

Return the previous node to the specified $node if: it is a text mode; its text matches the specified regular expression; the specified $node is in the optional specified context. Else return undef.

     Parameter  Description
  1  $node      Node
  2  $match     Regular expression the text must match
  3  @context   Optional context of specified node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>bb<c>cc</c>BB
    </b>
  </a>
  END

    ok $cc->matchesText(qr(cc));

    ok $c->at_c_b &&  $c->prevTextMatches(qr(bb));

    ok $b->at_b   && !$b->prevTextMatches(qr(bb));

prevIn($@)

Return the nearest sibling node before the specified $node which matches one of the named tags or undef if there is no such sibling node.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to search for.

Example:

    ok $a->prettyStringCDATA eq <<'END';
  <a><CDATA> </CDATA>
      <A/>
  <CDATA>  </CDATA>
      <C/>
  <CDATA>  </CDATA>
      <E/>
  <CDATA>  </CDATA>
      <G/>
  <CDATA>  </CDATA>
  </a>
  END

    ok $a->lastIn(qw(e E f F))->prevIn(qw(A G))->tag eq qq(A);

prevOn($@)

Step backwards as far as possible while remaining on nodes with the specified tags. In scalar context return the last such node reached or the starting node if no such steps are possible. In array context return the start node and any preceding matching nodes.

     Parameter  Description
  1  $node      Start node
  2  @tags      Tags identifying nodes that can be step on to context.

Example:

    ok -p $a eq <<END;
  <a>
    <b>
      <c id="1"/>
      <d id="2"/>
      <c id="3"/>
      <d id="4"/>
      <e id="5"/>
    </b>
  </a>
  END

    ok $c->id == 1;

    ok $e->id == 5;

    ok $e->prevOn(qw(d))  ->id == 4;

    ok $e->prevOn(qw(c d))     == $c;

prevWhile($@)

Go to the previous sibling of the specified $node and continue backwards while the tag of each sibling node matches one of the specified @tags. Return the first sibling node that does not match else undef if there is no such sibling.

     Parameter  Description
  1  $node      Parent node
  2  @tags      Child tags to avoid.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
    <c/>
    <d/>
    <e/>
    <f/>
  </a>
  END

    my ($b, $c, $d, $e, $f) = $a->byList;

    ok $c == $f->prevWhile_e_d;

    ok $b == $c->prevWhile;

prevUntil($@)

Go to the previous sibling of the specified $node and continue backwards until the tag of a sibling node matches one of the specified @tags. Return the matching sibling node else undef if there is no such sibling node.

     Parameter  Description
  1  $node      Node
  2  @tags      Tags to look for.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
    <c/>
    <d/>
    <e/>
    <f/>
  </a>
  END

    my ($b, $c, $d, $e, $f) = $a->byList;

    ok $b == $f->prevUntil_a_b;

    ok      !$c->prevUntil;

Up

Methods for moving up the parse tree from a node.

up($@)

Return the parent of the current node optionally checking the context of the specified $node first or return undef if the specified $node is the root of the parse tree. See addWrapWith to ensure that an expected node is in position.

     Parameter  Description
  1  $node      Start node
  2  @tags      Optional tags identifying context.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><b><b><b><b><c/></b></b></b></b></c></b></a>
  END

    $a->numberTree;
    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <b id="4">
          <b id="5">
            <b id="6">
              <b id="7">
                <c id="8"/>
              </b>
            </b>
          </b>
        </b>
      </c>
    </b>
  </a>
  END

    my $c = $a->findByNumber(8);
    ok -t $c eq q(c);
    ok  $c->up__number == 7;
    ok  $c->upn_2__number == 6;
    ok  $c->upWhile_b__number == 4;
    ok  $c->upWhile_a_b__number == 4;
    ok  $c->upWhile_b_c__number == 2;

    ok  $c->upUntil__number == 7;
    ok  $c->upUntil_b_c__number == 4;
   }

upn($$@)

Go up the specified number of levels from the specified $node and return the node reached or undef if there is no such node.upn(1) is identical in effect to up. Or use ancestry to get the path back to the root node.

     Parameter  Description
  1  $node      Start node
  2  $levels    Number of levels to go up
  3  @context   Optional context.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><b><b><b><b><c/></b></b></b></b></c></b></a>
  END

    $a->numberTree;
    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <b id="4">
          <b id="5">
            <b id="6">
              <b id="7">
                <c id="8"/>
              </b>
            </b>
          </b>
        </b>
      </c>
    </b>
  </a>
  END

    my $c = $a->findByNumber(8);
    ok -t $c eq q(c);
    ok  $c->up__number == 7;
    ok  $c->upn_2__number == 6;
    ok  $c->upWhile_b__number == 4;
    ok  $c->upWhile_a_b__number == 4;
    ok  $c->upWhile_b_c__number == 2;

    ok  $c->upUntil__number == 7;
    ok  $c->upUntil_b_c__number == 4;
   }

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><d><e/></d></c></b></a>
  END

    my ($e, $d, $c, $b) = $a->byList;

    ok $e = $e->upn(0);
    ok $d = $e->upn(1);
    ok $c = $e->upn(2);
    ok $b = $e->upn(3);
    ok $a = $e->upn(4);
    ok     !$e->upn(5);

    is_deeply [$e, $d, $c, $b, $a], [$e->ancestry];
   }

   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><d><e/></d></c></b></a>
  END

    my ($e, $d, $c, $b) = $a->byList;

    ok $e = $e->upn(0);

    ok $d = $e->upn(1);

    ok $c = $e->upn(2);

    ok $b = $e->upn(3);

    ok $a = $e->upn(4);

    ok     !$e->upn(5);

upWhile($@)

Go up one level from the specified $node and then continue up while each node matches on of the specified <@tags>. Return the last matching node or undef if no node matched any of the specified @tags.

     Parameter  Description
  1  $node      Start node
  2  @tags      Tags to match

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><b><b><b><b><c/></b></b></b></b></c></b></a>
  END

    $a->numberTree;
    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <b id="4">
          <b id="5">
            <b id="6">
              <b id="7">
                <c id="8"/>
              </b>
            </b>
          </b>
        </b>
      </c>
    </b>
  </a>
  END

    my $c = $a->findByNumber(8);
    ok -t $c eq q(c);
    ok  $c->up__number == 7;
    ok  $c->upn_2__number == 6;
    ok  $c->upWhile_b__number == 4;
    ok  $c->upWhile_a_b__number == 4;
    ok  $c->upWhile_b_c__number == 2;

    ok  $c->upUntil__number == 7;
    ok  $c->upUntil_b_c__number == 4;
   }

upWhileFirst($@)

Move up from the specified $node as long as each node is a first node or return undef if the specified $node is not a first node.

     Parameter  Description
  1  $node      Start node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    ok  $h == $i->upWhileFirst;

    ok  $a == $c->upWhileFirst;

    ok !$d->upWhileFirst;

upWhileLast($@)

Move up from the specified $node as long as each node is a last node or return undef if the specified $node is not a last node.

     Parameter  Description
  1  $node      Start node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    ok  $j == $j->upWhileLast;

    ok  $a == $l->upWhileLast;

    ok !$d->upWhileLast;

    ok  $i == $k->upUntilLast;

upWhileIsOnlyChild($@)

Move up from the specified $node as long as each node is an only child or return undef if the specified $node is not an only child.

     Parameter  Description
  1  $node      Start node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    ok  $h == $i->upWhileIsOnlyChild;

    ok  $j == $j->upWhileIsOnlyChild;

    ok !$d->upWhileIsOnlyChild;

upUntil($@)

Return the nearest ancestral node to the specified $node that matches the specified @context or undef if there is no such node. Returns the parent node of the specified $node if no @context is specified.

     Parameter  Description
  1  $node      Start node
  2  @context   Context.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c><b><b><b><b><c/></b></b></b></b></c></b></a>
  END

    $a->numberTree;
    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <b id="4">
          <b id="5">
            <b id="6">
              <b id="7">
                <c id="8"/>
              </b>
            </b>
          </b>
        </b>
      </c>
    </b>
  </a>
  END

    my $c = $a->findByNumber(8);
    ok -t $c eq q(c);
    ok  $c->up__number == 7;
    ok  $c->upn_2__number == 6;
    ok  $c->upWhile_b__number == 4;
    ok  $c->upWhile_a_b__number == 4;
    ok  $c->upWhile_b_c__number == 2;

    ok  $c->upUntil__number == 7;
    ok  $c->upUntil_b_c__number == 4;
   }

upUntilFirst($@)

Move up from the specified $node until we reach the root or a first node.

     Parameter  Description
  1  $node      Start node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    ok  $b == $d->upUntilFirst;

upUntilLast($@)

Move up from the specified $node until we reach the root or a last node.

     Parameter  Description
  1  $node      Start node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

upUntilIsOnlyChild($@)

Move up from the specified $node until we reach the root or another only child.

     Parameter  Description
  1  $node      Start node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    ok  $i == $k->upUntilIsOnlyChild;

upThru($@)

Go up the specified path from the specified $node returning the node at the top or undef if no such node exists.

     Parameter  Description
  1  $node      Start node
  2  @tags      Tags identifying path.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d>
        <e/>
        <f/>
      </d>
    </b>
  </a>
  END

    my ($c, $e, $f, $d, $b) = $a->byList;

    ok -t $f                eq q(f);

    ok -t $f->upThru        eq q(f);

    ok -t $f->upThru(qw(d)) eq q(d);

    ok -t eval{$f->upThru(qw(d))->last->prev} eq q(e);

    ok !  eval{$f->upThru(qw(d b))->next};

down

Methods for moving down through the parse tree from a node.

downWhileFirst($@)

Move down from the specified $node as long as each lower node is a first node.

     Parameter  Description
  1  $node      Start node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    ok  $k == $g->downWhileFirst;

    ok  $c == $a->downWhileFirst;

    ok  $c == $c->downWhileFirst;

    ok       !$d->downWhileFirst;

firstLeaf is a synonym for downWhileFirst.

downWhileLast($@)

Move down from the specified $node as long as each lower node is a last node.

     Parameter  Description
  1  $node      Start node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
      <e>
        <j/>
      </e>
      <f/>
    </b>
    <g>
      <h>
        <i>
          <k/>
          <l/>
        </i>
      </h>
    </g>
  </a>
  END

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

    ok  $l == $a->downWhileLast;

    ok  $l == $g->downWhileLast;

    ok       !$d->downWhileLast;

lastLeaf is a synonym for downWhileLast.

downWhileSingleChild($@)

Move down from the specified $node as long as it has a single child else return undef.

     Parameter  Description
  1  $node      Start node
  2  @context   Optional context

Example:

    my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;

Editing

Edit the data in the parse tree and change the structure of the parse tree by wrapping and unwrapping nodes, by replacing nodes, by cutting and pasting nodes, by concatenating nodes, by splitting nodes, by adding new text nodes or swapping nodes.

change($$@)

Change the name of the specified $node, optionally confirming that the $node is in a specified context and return the $node.

     Parameter  Description
  1  $node      Node
  2  $name      New name
  3  @context   Optional context.

Example:

   {my $a = Data::Edit::Xml::new('<a/>');

    $a->change(qq(b));

    ok -s $a eq '<b/>';

changeText($$@)

If the specified $node is a text node in the specified context then the specified sub is passed the text of the node in $_, any changes to which are recorded in the text of the $node.

Returns undef if the specified $node is not a text node in the specified optional context else it returns the result of executing the specified sub.

     Parameter  Description
  1  $node      Text node
  2  $sub       Sub
  3  @context   Optional context.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>Hello World</a>
  END

    $a->first->changeText(sub{s(l) (L)g});

    ok -s $a eq q(<a>HeLLo WorLd</a>);

Cut and Put

Move nodes around in the parse tree by cutting and pasting them.

cut($@)

Cut out the specified $node so that it can be reinserted else where in the parse tree.

     Parameter  Description
  1  $node      Node to cut out
  2  @context   Optional context

Example:

      ok -p $a eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"/>
    </b>
  </a>
  END

      my $c = $a->go(qw(b c))->cut;

      ok -p $a eq <<END;
  <a id="aa">
    <b id="bb"/>
  </a>
  END

deleteContent($@)

Delete the content of the specified $node.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>bb<c>cc</c>BB
    </b>
  </a>
  END

    $b->deleteContent;

    ok -p $a eq <<END;
  <a>
    <b/>
  </a>
  END

putFirst($$@)

Place a cut out or new node at the front of the content of the specified $node and return the new node. See addFirst to perform this operation conditionally.

     Parameter  Description
  1  $old       Original node
  2  $new       New node
  3  @context   Optional context.

Example:

      ok -p $a eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"/>
    </b>
  </a>
  END

      my $c = $a->go(qw(b c))->cut;

      $a->putFirst($c);

      ok -p $a eq <<END;
  <a id="aa">
    <c id="cc"/>
    <b id="bb"/>
  </a>
  END

putFirstCut($$@)

Cut out the second node, place it first under the first node and return the second node.

     Parameter  Description
  1  $old       First node
  2  $new       Second node
  3  @context   Optional context.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
    </b>
  </a>
  END

    my ($c, $d, $b) = $a->byList;

    $c->putFirstCut($d, qw(c b a));

    ok -p $a eq <<END;
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
  </a>
  END

putLast($$@)

Place a cut out or new node last in the content of the specified $node and return the new node. See addLast to perform this operation conditionally.

     Parameter  Description
  1  $old       Original node
  2  $new       New node
  3  @context   Optional context.

Example:

      ok -p $a eq <<END;
  <a id="aa">
    <c id="cc"/>
    <b id="bb"/>
  </a>
  END

      $a->putLast($a->go(qw(c))->cut);

      ok -p $a eq <<END;
  <a id="aa">
    <b id="bb"/>
    <c id="cc"/>
  </a>
  END

putLastCut($$@)

Cut out the second node, place it last under the first node and return the second node.

     Parameter  Description
  1  $old       First node
  2  $new       Second node
  3  @context   Optional context.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
    </b>
  </a>
  END

    my ($c, $d, $b) = $a->byList;

    $a->putLastCut($d, qw(a));

    ok -p $a eq <<END;
  <a>
    <b>
      <c/>
    </b>
    <d/>
  </a>
  END

putNext($$@)

Place a cut out or new node just after the specified $node and return the new node. See addNext to perform this operation conditionally.

     Parameter  Description
  1  $old       Original node
  2  $new       New node
  3  @context   Optional context.

Example:

      ok -p $a eq <<END;
  <a id="aa">
    <b id="bb"/>
    <c id="cc"/>
  </a>
  END

      $a->go(qw(c))->putNext($a->go(q(b))->cut);

      ok -p $a eq <<END;
  <a id="aa">
    <c id="cc"/>
    <b id="bb"/>
  </a>
  END

putNextCut($$@)

Cut out the second node, place it next after the first node and return the second node.

     Parameter  Description
  1  $old       First node
  2  $new       Second node
  3  @context   Optional context.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
    </b>
  </a>
  END

    my ($c, $d, $b) = $a->byList;

    $d->putNextCut($c, qw(d b a));

    ok -p $a eq <<END;
  <a>
    <b>
      <d/>
      <c/>
    </b>
  </a>
  END

putPrev($$@)

Place a cut out or new node just before the specified $node and return the new node. See addPrev to perform this operation conditionally.

     Parameter  Description
  1  $old       Original node
  2  $new       New node
  3  @context   Optional context.

Example:

      ok -p $a eq <<END;
  <a id="aa">
    <c id="cc"/>
    <b id="bb"/>
  </a>
  END

      $a->go(qw(c))->putPrev($a->go(q(b))->cut);

      ok -p $a eq <<END;
  <a id="aa">
    <b id="bb"/>
    <c id="cc"/>
  </a>
  END

putPrevCut($$@)

Cut out the second node, place it before the first node and return the second node.

     Parameter  Description
  1  $old       First node
  2  $new       Second node
  3  @context   Optional context.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
    </b>
  </a>
  END

    my ($c, $d, $b) = $a->byList;

    $c->putPrevCut($d, qw(c b a));

    ok -p $a eq <<END;
  <a>
    <b>
      <d/>
      <c/>
    </b>
  </a>
  END

Add selectively

Add new nodes unless they already exist.

addFirst($$%)

Add a new node first below the specified $node and return the new node unless a node with that tag already exists in which case return the existing $node.

     Parameter    Description
  1  $node        Node
  2  $tag         Tag of new node
  3  %attributes  Attributes for the new node.

Example:

   {my $a = Data::Edit::Xml::newTree(q(a));

    $a->addFirst(qw(b id b)) for 1..2;

    ok -p $a eq <<END;
  <a>
    <b id="b"/>
  </a>
  END

addNext($$%)

Add a new node next to the specified $node and return the new node unless a node with that tag already exists in which case return the existing $node.

     Parameter    Description
  1  $node        Node
  2  $tag         Tag of new node
  3  %attributes  Attributes for the new node.

Example:

    ok -p $a eq <<END;
  <a>
    <b id="b"/>
    <e id="e"/>
  </a>
  END

    $a->addFirst(qw(b id B))->addNext(qw(c id c));

    ok -p $a eq <<END;
  <a>
    <b id="b"/>
    <c id="c"/>
    <e id="e"/>
  </a>
  END

addPrev($$%)

Add a new node before the specified $node and return the new node unless a node with that tag already exists in which case return the existing $node.

     Parameter    Description
  1  $node        Node
  2  $tag         Tag of new node
  3  %attributes  Attributes for the new node.

Example:

    ok -p $a eq <<END;
  <a>
    <b id="b"/>
    <c id="c"/>
    <e id="e"/>
  </a>
  END

    $a->addLast(qw(e id E))->addPrev(qw(d id d));

    ok -p $a eq <<END;
  <a>
    <b id="b"/>
    <c id="c"/>
    <d id="d"/>
    <e id="e"/>
  </a>
  END

addLast($$%)

Add a new node last below the specified $node and return the new node unless a node with that tag already exists in which case return the existing $node.

     Parameter    Description
  1  $node        Node
  2  $tag         Tag of new node
  3  %attributes  Attributes for the new node.

Example:

    ok -p $a eq <<END;
  <a>
    <b id="b"/>
  </a>
  END

    $a->addLast(qw(e id e)) for 1..2;

    ok -p $a eq <<END;
  <a>
    <b id="b"/>
    <e id="e"/>
  </a>
  END

addWrapWith($$%)

Wrap the specified $node with the specified tag if the node is not already wrapped with such a tag and return the new node unless a node with that tag already exists in which case return the existing $node.

     Parameter    Description
  1  $node        Node
  2  $tag         Tag of new node
  3  %attributes  Attributes for the new node.

Example:

   {my $a = Data::Edit::Xml::new(q(<a><b/></a>));

    my $b = $a->first;

    $b->addWrapWith(qw(c id c)) for 1..2;

    ok -p $a eq <<END;
  <a>
    <c id="c">
      <b/>
    </c>
  </a>
  END

addSingleChild($$%)

Wrap the content of a specified $node in a new node with the specified $tag and optional %attribute unless the content is already wrapped in a single child with the specified $tag.

     Parameter    Description
  1  $node        Node
  2  $tag         Tag of new node
  3  %attributes  Attributes for the new node.

Example:

    ok -p $a eq <<END;
  <a>
    <c id="c">
      <b/>
    </c>
  </a>
  END

    $a->addSingleChild(q(d)) for 1..2;

    ok -p $a eq <<END;
  <a>
    <d>
      <c id="c">
        <b/>
      </c>
    </d>
  </a>
  END

Add text selectively

Add new text unless it already exists.

addFirstAsText($$)

Add a new text node first below the specified $node and return the new node unless a text node already exists there and starts with the same text in which case return the existing $node.

     Parameter  Description
  1  $node      Node
  2  $text      Text

Example:

   {my $a = Data::Edit::Xml::newTree(q(a));

    $a->addFirstAsText(q(aaaa)) for 1..2;

    ok -s $a eq q(<a>aaaa</a>);

addNextAsText($$)

Add a new text node after the specified $node and return the new node unless a text node already exists there and starts with the same text in which case return the existing $node.

     Parameter  Description
  1  $node      Node
  2  $text      Text

Example:

   {my $a = Data::Edit::Xml::new(q(<a><b/></a>));

    $a->go(q(b))->addNextAsText(q(bbbb)) for 1..2;

    ok -p $a eq <<END;
  <a>
    <b/>
  bbbb
  </a>
  END

addPrevAsText($$)

Add a new text node before the specified $node and return the new node unless a text node already exists there and ends with the same text in which case return the existing $node.

     Parameter  Description
  1  $node      Node
  2  $text      Text

Example:

    ok -p $a eq <<END;
  <a>
    <b/>
  bbbb
  </a>
  END

    $a->go(q(b))->addPrevAsText(q(aaaa)) for 1..2;

    ok -p $a eq <<END;
  <a>aaaa
    <b/>
  bbbb
  </a>
  END

addLastAsText($$)

Add a new text node last below the specified $node and return the new node unless a text node already exists there and ends with the same text in which case return the existing $node.

     Parameter  Description
  1  $node      Node
  2  $text      Text

Example:

    ok -s $a eq q(<a>aaaa</a>);

    $a->addLastAsText(q(dddd)) for 1..2;

    ok -s $a eq q(<a>aaaadddd</a>);

Fusion

Join consecutive nodes

concatenate($$@)

Concatenate two successive nodes and return the target node.

     Parameter  Description
  1  $target    Target node to replace
  2  $source    Node to concatenate
  3  @context   Optional context of $target

Example:

   {my $s = <<END;
  <a>
    <b>
      <A/>
      <B/>
    </b>
    <c>
      <C/>
      <D/>
    </c>
  </a>
  END

    my $a = Data::Edit::Xml::new($s);

    $a->go(q(b))->concatenate($a->go(q(c)));

    my $t = <<END;
  <a>
    <b>
      <A/>
      <B/>
      <C/>
      <D/>
    </b>
  </a>
  END

    ok $t eq -p $a;

concatenateSiblings($@)

Concatenate preceding and following nodes as long as they have the same tag as the specified $node and return the specified $node.

     Parameter  Description
  1  $node      Concatenate around this node
  2  @context   Optional context.

Example:

    ok -p $a eq <<END;
  <a>
    <b>
      <c id="1"/>
    </b>
    <b>
      <c id="2"/>
    </b>
    <b>
      <c id="3"/>
    </b>
    <b>
      <c id="4"/>
    </b>
  </a>
  END

    $a->go(qw(b 3))->concatenateSiblings;

    ok -p $a eq <<END;
  <a>
    <b>
      <c id="1"/>
      <c id="2"/>
      <c id="3"/>
      <c id="4"/>
    </b>
  </a>
  END

mergeDuplicateChildWithParent($@)

Merge a parent node with its only child if their tags are the same and their attributes do not collide other than possibly the id in which case the parent id is used. Any labels on the child are transferred to the parent. The child node is then unwrapped and the parent node is returned.

     Parameter  Description
  1  $parent    Parent this node
  2  @context   Optional context.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b   id="b" b="bb">
      <b id="c" c="cc"/>
    </b>
  </a>
  END

    my ($c, $b) = $a->byList;

    is_deeply [$b->id, $c->id], [qw(b c)];

    ok $c == $b->singleChild;

    $b->mergeDuplicateChildWithParent;

    ok -p $a eq <<END;
  <a>
    <b b="bb" c="cc" id="b"/>
  </a>
  END

    ok $b == $a->singleChild;

Put as text

Add text to the parse tree.

putFirstAsText($$@)

Add a new text node first under a parent and return the new text node.

     Parameter  Description
  1  $node      The parent node
  2  $text      The string to be added which might contain unparsed Xml as well as text
  3  @context   Optional context.

Example:

    ok -p $x eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"/>
    </b>
  </a>
  END

    $x->go(qw(b c))->putFirstAsText("<d id=\"dd\">DDDD</d>");

    ok -p $x eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"><d id="dd">DDDD</d></c>
    </b>
  </a>
  END

putLastAsText($$@)

Add a new text node last under a parent and return the new text node.

     Parameter  Description
  1  $node      The parent node
  2  $text      The string to be added which might contain unparsed Xml as well as text
  3  @context   Optional context.

Example:

    ok -p $x eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"><d id="dd">DDDD</d></c>
    </b>
  </a>
  END

    $x->go(qw(b c))->putLastAsText("<e id=\"ee\">EEEE</e>");

    ok -p $x eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"><d id="dd">DDDD</d><e id="ee">EEEE</e></c>
    </b>
  </a>
  END

putNextAsText($$@)

Add a new text node following the specified $node and return the new text node.

     Parameter  Description
  1  $node      The parent node
  2  $text      The string to be added which might contain unparsed Xml as well as text
  3  @context   Optional context.

Example:

    ok -p $x eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"><d id="dd">DDDD</d><e id="ee">EEEE</e></c>
    </b>
  </a>
  END

    $x->go(qw(b c))->putNextAsText("<n id=\"nn\">NNNN</n>");

    ok -p $x eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"><d id="dd">DDDD</d><e id="ee">EEEE</e></c>
  <n id="nn">NNNN</n>
    </b>
  </a>
  END

putPrevAsText($$@)

Add a new text node following the specified $node and return the new text node

     Parameter  Description
  1  $node      The parent node
  2  $text      The string to be added which might contain unparsed Xml as well as text
  3  @context   Optional context.

Example:

    ok -p $x eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"><d id="dd">DDDD</d><e id="ee">EEEE</e></c>
  <n id="nn">NNNN</n>
    </b>
  </a>
  END

    $x->go(qw(b c))->putPrevAsText("<p id=\"pp\">PPPP</p>");

    ok -p $x eq <<END;
  <a id="aa">
    <b id="bb"><p id="pp">PPPP</p>
      <c id="cc"><d id="dd">DDDD</d><e id="ee">EEEE</e></c>
  <n id="nn">NNNN</n>
    </b>
  </a>
  END

Break in and out

Break nodes out of nodes or push them back

breakIn($@)

Concatenate the nodes following and preceding the start node, unwrapping nodes whose tag matches the start node and return the start node. To concatenate only the preceding nodes, use breakInBackwards, to concatenate only the following nodes, use breakInForwards.

     Parameter  Description
  1  $start     The start node
  2  @context   Optional context.

Example:

      ok -p $a eq <<END;
  <a>
    <d/>
    <b>
      <c/>
      <c/>
    </b>
    <e/>
    <b>
      <c/>
      <c/>
    </b>
    <d/>
  </a>
  END

      $a->go(qw(b 1))->breakIn;

      ok -p $a eq <<END;
  <a>
    <b>
      <d/>
      <c/>
      <c/>
      <e/>
      <c/>
      <c/>
      <d/>
    </b>
  </a>
  END

breakInForwards($@)

Concatenate the nodes following the start node, unwrapping nodes whose tag matches the start node and return the start node in the manner of breakIn.

     Parameter  Description
  1  $start     The start node
  2  @context   Optional context..

Example:

      ok -p $a eq <<END;
  <a>
    <d/>
    <b>
      <c/>
      <c/>
    </b>
    <e/>
    <b>
      <c/>
      <c/>
    </b>
    <d/>
  </a>
  END

      $a->go(q(b))->breakInForwards;

      ok -p $a eq <<END;
  <a>
    <d/>
    <b>
      <c/>
      <c/>
      <e/>
      <c/>
      <c/>
      <d/>
    </b>
  </a>
  END

breakInBackwards($@)

Concatenate the nodes preceding the start node, unwrapping nodes whose tag matches the start node and return the start node in the manner of breakIn.

     Parameter  Description
  1  $start     The start node
  2  @context   Optional context..

Example:

      ok -p $a eq <<END;
  <a>
    <d/>
    <b>
      <c/>
      <c/>
    </b>
    <e/>
    <b>
      <c/>
      <c/>
    </b>
    <d/>
  </a>
  END

      $a->go(qw(b 1))->breakInBackwards;

      ok -p $a eq <<END;
  <a>
    <b>
      <d/>
      <c/>
      <c/>
      <e/>
      <c/>
      <c/>
    </b>
    <d/>
  </a>
  END

breakOut($@)

Lift child nodes with the specified tags under the specified parent node splitting the parent node into clones and return the cut out original node.

     Parameter  Description
  1  $parent    The parent node
  2  @tags      The tags of the modes to be broken out.

Example:

   {my $A = Data::Edit::Xml::new("<a><b><d/><c/><c/><e/><c/><c/><d/></b></a>");

      $a->go(q(b))->breakOut($a, qw(d e));

      ok -p $a eq <<END;
  <a>
    <d/>
    <b>
      <c/>
      <c/>
    </b>
    <e/>
    <b>
      <c/>
      <c/>
    </b>
    <d/>
  </a>
  END

Replace

Replace nodes in the parse tree with nodes or text

replaceWith($$@)

Replace a node (and all its content) with a new node (and all its content) and return the new node. If the node to be replaced is the root of the parse tree then no action is taken other then returning the new node.

     Parameter  Description
  1  $old       Old node
  2  $new       New node
  3  @context   Optional context..

Example:

     {my $x = Data::Edit::Xml::new(qq(<a><b><c id="cc"/></b></a>));

      $x->go(qw(b c))->replaceWith($x->newTag(qw(d id dd)));

      ok -s $x eq '<a><b><d id="dd"/></b></a>';

replaceWithText($$@)

Replace a node (and all its content) with a new text node and return the new node.

     Parameter  Description
  1  $old       Old node
  2  $text      Text of new node
  3  @context   Optional context.

Example:

     {my $x = Data::Edit::Xml::new(qq(<a><b><c id="cc"/></b></a>));

      $x->go(qw(b c))->replaceWithText(qq(BBBB));

      ok -s $x eq '<a><b>BBBB</b></a>';

replaceWithBlank($@)

Replace a node (and all its content) with a new blank text node and return the new node.

     Parameter  Description
  1  $old       Old node
  2  @context   Optional context.

Example:

     {my $x = Data::Edit::Xml::new(qq(<a><b><c id="cc"/></b></a>));

      $x->go(qw(b c))->replaceWithBlank;

      ok -s $x eq '<a><b> </b></a>';

replaceContentWithMovedContent($@)

Replace the content of a specified target node with the contents of the specified source nodes removing the content from each source node and return the target node.

     Parameter  Description
  1  $node      Target node
  2  @nodes     Source nodes

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
       <b1/>
       <b2/>
    </b>
    <c>
       <c1/>
       <c2/>
    </c>
    <d>
       <d1/>
       <d2/>
    </d>
  </a>
  END

    my ($b, $c, $d) = $a->contents;

    $d->replaceContentWithMovedContent($c, $b);

    ok -p $a eq <<END;
  <a>
    <b/>
    <c/>
    <d>
      <c1/>
      <c2/>
      <b1/>
      <b2/>
    </d>
  </a>
  END

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <d>
       <b>
         <b1/>
         <b2/>
      </b>
      <c>
         <c1/>
         <c2/>
      </c>
    </d>
  </a>
  END

    my ($d)     = $a->contents;

    my ($b, $c) = $d->contents;

    $d->replaceContentWithMovedContent($c, $b);

    ok -p $a eq <<END;
  <a>
    <d>
      <c1/>
      <c2/>
      <b1/>
      <b2/>
    </d>
  </a>
  END

replaceContentWith($@)

Replace the content of a node with the specified nodes and return the replaced content

     Parameter  Description
  1  $node      Node whose content is to be replaced
  2  @content   New content

Example:

     {my $x = Data::Edit::Xml::new(qq(<a><b/><c/></a>));

      $x->replaceContentWith(map {$x->newTag($_)} qw(B C));

      ok -s $x eq '<a><B/><C/></a>';

replaceContentWithText($@)

Replace the content of a node with the specified texts and return the replaced content

     Parameter  Description
  1  $node      Node whose content is to be replaced
  2  @text      Texts to form new content

Example:

     {my $x = Data::Edit::Xml::new(qq(<a><b/><c/></a>));

      $x->replaceContentWithText(qw(b c));

      ok -s $x eq '<a>bc</a>';

Swap

Swap nodes both singly and in blocks

invert($@)

Swap a parent and child node where the child is the only child of the parent and return the parent.

     Parameter  Description
  1  $parent    Parent
  2  @context   Context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b id="b">
      <c id="c">
        <d/>
        <e/>
      </c>
    </b>
  </a>
  END

    $a->first->invert;

    ok -p $a eq <<END;
  <a>
    <c id="c">
      <b id="b">
        <d/>
        <e/>
      </b>
    </c>
  </a>
  END

    $a->first->invert;

    ok -p $a eq <<END;
  <a>
    <b id="b">
      <c id="c">
        <d/>
        <e/>
      </c>
    </b>
  </a>
  END

invertFirst($@)

Swap a parent and child node where the child is the first child of the parent by placing the parent last in the child. Return the parent.

     Parameter  Description
  1  $parent    Parent
  2  @context   Context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
        <e/>
      </c>
      <f/>
      <g/>
    </b>
  </a>
  END

    ok -p $a eq <<END;
  <a>
    <c>
      <d/>
      <e/>
      <b>
        <f/>
        <g/>
      </b>
    </c>
  </a>
  END

invertLast($@)

Swap a parent and child node where the child is the last child of the parent by placing the parent first in the child. Return the parent.

     Parameter  Description
  1  $parent    Parent
  2  @context   Context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
        <e/>
      </c>
      <f/>
      <g/>
    </b>
  </a>
  END

    ok -p $a eq <<END;
  <a>
    <c>
      <d/>
      <e/>
      <b>
        <f/>
        <g/>
      </b>
    </c>
  </a>
  END

    ok -p $a eq <<END;
  <a>
    <b>
      <c>
        <d/>
        <e/>
      </c>
      <f/>
      <g/>
    </b>
  </a>
  END

swap($$@)

Swap two nodes optionally checking that the first node is in the specified context and return the first node.

     Parameter  Description
  1  $first     First node
  2  $second    Second node
  3  @context   Optional context

Example:

    ok <<END eq -p $x;
  <x>
    <a a="1" b="2"/>
    <b/>
    <c a="1" b="3" c="4"/>
  </x>
  END

    $a->swap($c);

    ok <<END eq -p $x;
  <x>
    <c a="1" b="3" c="4"/>
    <b/>
    <a a="1" b="2"/>
  </x>
  END

Wrap and unwrap

Wrap and unwrap nodes to alter the depth of the parse tree

wrapWith($$@)

     Parameter    Description
  1  $node        Node
  2  $tag         Tag for the new node or tag
  3  %attributes  Attributes for the new node or tag.

Example:

    ok -p $x eq <<END;
  <a>
    <b>
      <c id="11"/>
    </b>
  </a>
  END

    $x->go(qw(b c))->wrapWith(qw(C id 1));

    ok -p $x eq <<END;
  <a>
    <b>
      <C id="1">
        <c id="11"/>
      </C>
    </b>
  </a>
  END

wrapUp($@)

Wrap the specified $node in a sequence of new nodes created from the specified @tags forcing the original node down - deepening the parse tree - return the array of wrapping nodes.

     Parameter  Description
  1  $node      Node to wrap
  2  @tags      Tags to wrap the node with - with the uppermost tag rightmost.

Example:

   {my $c = Data::Edit::Xml::newTree("c", id=>33);

    my ($b, $a) = $c->wrapUp(qw(b a));

    ok -p $a eq <<'END';
  <a>
    <b>
      <c id="33"/>
    </b>
  </a>
  END

wrapDown($@)

Wrap the content of the specified $node in a sequence of new nodes forcing the original node up - deepening the parse tree - return the array of wrapping nodes.

     Parameter  Description
  1  $node      Node to wrap
  2  @tags      Tags to wrap the node with - with the uppermost tag rightmost.

Example:

   {my $a = Data::Edit::Xml::newTree("a", id=>33);

    my ($b, $c) = $a->wrapDown(qw(b c));

    ok -p $a eq <<END;
  <a id="33">
    <b>
      <c/>
    </b>
  </a>
  END

wrapContentWith($$@)

Wrap the content of the specified $node in a new node created from the specified <@tag> and %attributes: the specified $node then contains just the new node which, in turn, contains all the content of the specified $node.

Returns the new wrapped node.

     Parameter    Description
  1  $old         Node
  2  $tag         Tag for new node
  3  %attributes  Attributes for new node.

Example:

    ok -p $x eq <<END;
  <a>
    <b>
      <c/>
      <c/>
      <c/>
    </b>
  </a>
  END

    $x->go(q(b))->wrapContentWith(qw(D id DD));

    ok -p $x eq <<END;
  <a>
    <b>
      <D id="DD">
        <c/>
        <c/>
        <c/>
      </D>
    </b>
  </a>
  END

    ok -p $a eq <<END;
  <a>
    <b id="1"/>
    <c id="2"/>
    <d id="3"/>
    <c id="4"/>
    <d id="5"/>
    <e id="6"/>
    <b id="7"/>
    <c id="8"/>
    <d id="9"/>
    <f id="10"/>
  </a>
  END

wrapSiblingsBefore($$@)

If there are any siblings before the specified $node, wrap them with a new node created from the specified <@tag> and %attributes.

Returns the specified $node.

     Parameter    Description
  1  $node        Node to wrap before
  2  $tag         Tag for new node
  3  %attributes  Attributes for new node.

Example:

   {my $a = Data::Edit::Xml::new(q(<a><b/><c/><d/></a>));

    my ($b, $c, $d) = $a->byList;

    $c->wrapSiblingsBefore(q(X));

    ok -p $a eq <<END;
  <a>
    <X>
      <b/>
    </X>
    <c/>
    <d/>
  </a>
  END

wrapSiblingsBetween($$$@)

If there are any siblings between the specified $nodes, wrap them with a new node created from the specified <@tag> and %attributes. Return the wrapping node else undef if there are no nodes to wrap.

     Parameter    Description
  1  $first       First sibling
  2  $last        Last sibling
  3  $tag         Tag for new node
  4  %attributes  Attributes for new node.

Example:

   {my $a = Data::Edit::Xml::new(q(<a><b/><c/><d/></a>));

    my ($b, $c, $d) = $a->byList;

    $b->wrapSiblingsBetween($d, q(Y));

    ok -p $a eq <<END;
  <a>
    <b/>
    <Y>
      <c/>
    </Y>
    <d/>
  </a>
  END

wrapSiblingsAfter($$@)

If there are any siblings after the specified $node, wrap them with a new node created from the specified <@tag> and %attributes.

Return the specified $node.

     Parameter    Description
  1  $node        Node to wrap before
  2  $tag         Tag for new node
  3  %attributes  Attributes for new node.

Example:

   {my $a = Data::Edit::Xml::new(q(<a><b/><c/><d/></a>));

    my ($b, $c, $d) = $a->byList;

    $c->wrapSiblingsAfter(q(Y));

    ok -p $a eq <<END;
  <a>
    <b/>
    <c/>
    <Y>
      <d/>
    </Y>
  </a>
  END

wrapTo($$$@)

Wrap all the nodes from the $start node to the $end node with a new node created from the specified <@tag> and %attributes and return the new node.

Return undef if the $start and $end nodes are not siblings - they must have the same parent for this method to work.

     Parameter    Description
  1  $start       Start node
  2  $end         End node
  3  $tag         Tag for the wrapping node
  4  %attributes  Attributes for the wrapping node

Example:

   {my $x = Data::Edit::Xml::new(my $s = <<END);
  <aa>
    <a>
      <b/>
        <c id="1"/><c id="2"/><c id="3"/><c id="4"/>
      <d/>
    </a>
  </aa>
  END

    $x->go(qw(a c))->wrapTo($x->go(qw(a c -1)), qq(C), id=>1234);

    ok -p $x eq <<END;
  <aa>
    <a>
      <b/>
      <C id="1234">
        <c id="1"/>
        <c id="2"/>
        <c id="3"/>
        <c id="4"/>
      </C>
      <d/>
    </a>
  </aa>
  END

    my $C = $x->go(qw(a C));

    $C->wrapTo($C, qq(D));

    ok -p $x eq <<END;
  <aa>
    <a>
      <b/>
      <D>
        <C id="1234">
          <c id="1"/>
          <c id="2"/>
          <c id="3"/>
          <c id="4"/>
        </C>
      </D>
      <d/>
    </a>
  </aa>
  END

    ok -p $a eq <<END;
  <a>
    <b>
      <D id="DD">
        <c id="0"/>
        <c id="1"/>
      </D>
      <E id="EE">
        <c id="2"/>
      </E>
      <F id="FF">
        <c id="3"/>
      </F>
    </b>
  </a>
  END

wrapFrom($$$%)

Wrap all the nodes from the $start node to the $end node with a new node created from the specified <@tag> and %attributes and return the new node. Return undef if the $start and $end nodes are not siblings - they must have the same parent for this method to work.

     Parameter    Description
  1  $end         End node
  2  $start       Start node
  3  $tag         Tag for the wrapping node
  4  %attributes  Attributes for the wrapping node

Example:

   {my $a = Data::Edit::Xml::new(my $s = <<END);
  <a>
    <b>
      <c id="0"/><c id="1"/><c id="2"/><c id="3"/>
    </b>
  </a>
  END

    my $b = $a->first;

    my @c = $b->contents;

    $c[1]->wrapFrom($c[0], qw(D id DD));

    ok -p $a eq <<END;
  <a>
    <b>
      <D id="DD">
        <c id="0"/>
        <c id="1"/>
      </D>
      <c id="2"/>
      <c id="3"/>
    </b>
  </a>
  END

unwrap($@)

Unwrap the specified $node by inserting its content into its parent at the point containing the specified $node and return the parent node.

     Parameter  Description
  1  $node      Node to unwrap
  2  @context   Optional context.

Example:

    ok -s $x eq "<a>A<b> c </b>B</a>";

    $b->unwrap;

    ok -s $x eq "<a>A c B</a>";

unwrapParentsWithSingleChild($)

Unwrap any immediate ancestors of the specified $node which have only a single child and return the specified $node regardless.

     Parameter  Description
  1  $o         Node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <e/>
  </a>
  END

    $a->go(qw(b c d))->unwrapParentsWithSingleChild;

    ok -p $a eq <<END;
  <a>
    <d/>
    <e/>
  </a>
  END

unwrapContentsKeepingText($@)

Unwrap all the non text nodes below the specified $node adding a leading and a trailing space to prevent unwrapped content from being elided and return the specified $node else undef if not in the optional context.

     Parameter  Description
  1  $node      Node to unwrap
  2  @context   Optional context.

Example:

      ok -p $x eq <<END;
  <a>
    <b>
      <c>
        <d>DD</d>
  EE
        <f>FF</f>
      </c>
    </b>
  </a>
  END

      $x->go(qw(b))->unwrapContentsKeepingText;

      ok -p $x eq <<END;
  <a>
    <b>  DD EE FF  </b>
  </a>
  END

The children of each node.

contents($@)

Return a list of all the nodes contained by the specified $node or an empty list if the node is empty or not in the optional context.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b id="b1"><c id="1"/></b>
    <d id="d1"><c id="2"/></d>
    <e id="e1"><c id="3"/></e>
    <b id="b2"><c id="4"/></b>
    <d id="d2"><c id="5"/></d>
    <e id="e2"><c id="6"/></e>
  </a>
  END

    is_deeply [map{-u $_} $x->contents], [qw(b1 d1 e1 b2 d2 e2)];

contentAfter($@)

Return a list of all the sibling nodes following the specified $node or an empty list if the specified $node is last or not in the optional context.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok 'f g' eq join ' ', map {$_->tag} $x->go(qw(b e))->contentAfter;

contentBefore($@)

Return a list of all the sibling nodes preceding the specified $node or an empty list if the specified $node is last or not in the optional context.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok 'c d' eq join ' ', map {$_->tag} $x->go(qw(b e))->contentBefore;

contentAsTags($@)

Return a string containing the tags of all the child nodes of the specified $node separated by single spaces or the empty string if the node is empty or undef if the node does not match the optional context. Use over to test the sequence of tags with a regular expression.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok $x->go(q(b))->contentAsTags eq 'c d e f g';

contentAsTags2($@)

Return a string containing the tags of all the child nodes of the specified $node separated by two spaces with a single space preceding the first tag and a single space following the last tag or the empty string if the node is empty or undef if the node does not match the optional context. Use over2 to test the sequence of tags with a regular expression. Use over2 to test the sequence of tags with a regular expression.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

    ok $x->go(q(b))->contentAsTags2 eq q( c  d  e  f  g );

contentAfterAsTags($@)

Return a string containing the tags of all the sibling nodes following the specified $node separated by single spaces or the empty string if the node is empty or undef if the node does not match the optional context. Use matchAfter to test the sequence of tags with a regular expression.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok 'f g' eq join ' ', map {$_->tag} $x->go(qw(b e))->contentAfter;

    ok $x->go(qw(b e))->contentAfterAsTags eq 'f g';

contentAfterAsTags2($@)

Return a string containing the tags of all the sibling nodes following the specified $node separated by two spaces with a single space preceding the first tag and a single space following the last tag or the empty string if the node is empty or undef if the node does not match the optional context. Use matchAfter2 to test the sequence of tags with a regular expression.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok $x->go(qw(b e))->contentAfterAsTags2 eq q( f  g );

contentBeforeAsTags($@)

Return a string containing the tags of all the sibling nodes preceding the specified $node separated by single spaces or the empty string if the node is empty or undef if the node does not match the optional context. Use matchBefore to test the sequence of tags with a regular expression.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok 'c d' eq join ' ', map {$_->tag} $x->go(qw(b e))->contentBefore;

    ok $x->go(qw(b e))->contentBeforeAsTags eq 'c d';

contentBeforeAsTags2($@)

Return a string containing the tags of all the sibling nodes preceding the specified $node separated by two spaces with a single space preceding the first tag and a single space following the last tag or the empty string if the node is empty or undef if the node does not match the optional context. Use matchBefore2 to test the sequence of tags with a regular expression.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/><d/><e/><f/><g/>
    </b>
  </a>
  END

    ok $x->go(qw(b e))->contentBeforeAsTags2 eq q( c  d );

position($)

Return the index of the specified $node in the content of the parent of the $node.

     Parameter  Description
  1  $node      Node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a         id="11">
    <b       id="12">
       <c    id="13"/>
       <d    id="14"/>
       <b    id="15">
          <c id="16"/>
          <d id="17"/>
          <e id="18"/>
          <f id="19"/>
          <g id="20"/>
       </b>
       <f    id="21"/>
       <g    id="22"/>
    </b>
    <b       id="23">
       <c    id="24"/>
       <d    id="25"/>
       <b    id="26">
          <c id="27"/>
          <d id="28"/>
          <e id="29"/>
          <f id="30"/>
          <g id="31"/>
       </b>
       <f    id="32"/>
       <g    id="33"/>
    </b>
  </a>
  END

    ok $a->go(qw(b 1 b))->id == 26;

    ok $a->go(qw(b 1 b))->position == 2;

index($)

Return the index of the specified $node in its parent index. Use position to find the position of a node under its parent.

     Parameter  Description
  1  $node      Node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a         id="11">
    <b       id="12">
       <c    id="13"/>
       <d    id="14"/>
       <b    id="15">
          <c id="16"/>
          <d id="17"/>
          <e id="18"/>
          <f id="19"/>
          <g id="20"/>
       </b>
       <f    id="21"/>
       <g    id="22"/>
    </b>
    <b       id="23">
       <c    id="24"/>
       <d    id="25"/>
       <b    id="26">
          <c id="27"/>
          <d id="28"/>
          <e id="29"/>
          <f id="30"/>
          <g id="31"/>
       </b>
       <f    id="32"/>
       <g    id="33"/>
    </b>
  </a>
  END

    ok $a->go(qw(b 1))->id == 23;

    ok $a->go(qw(b 1))->index == 1;

present($@)

Return the count of the number of the specified tag types present immediately under a node or a hash {tag} = count for all the tags present under the node if no names are specified.

     Parameter  Description
  1  $node      Node
  2  @names     Possible tags immediately under the node.

Example:

    is_deeply {$a->first->present}, {c=>2, d=>2, e=>1};

isText($@)

Return the specified $node if the specified $node is a text node, optionally in the specified context, else return undef.

     Parameter  Description
  1  $node      Node to test
  2  @context   Optional context

Example:

    ok $a->prettyStringCDATA eq <<END;
  <a>
      <b><CDATA> </CDATA></b>
  </a>
  END

    ok $b->first->isText;

    ok $b->first->isText(qw(b a));

isFirstText($@)

Return the specified $node if the specified $node is a text node, the first node under its parent and that the parent is optionally in the specified context, else return undef.

     Parameter  Description
  1  $node      Node to test
  2  @context   Optional context for parent

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <x>
    <a>aaa
      <b>bbb</b>
      ccc
      <d>ddd</d>
      eee
    </a>
  </x>
  END

    my $a = $x->first;

    my ($ta, $b, $tc, $d, $te) = $a->contents;

    ok $ta      ->isFirstText(qw(a x));

    ok $b->first->isFirstText(qw(b a x));

    ok $b->prev ->isFirstText(qw(a x));

    ok $d->last ->isFirstText(qw(d a x));

isLastText($@)

Return the specified $node if the specified $node is a text node, the last node under its parent and that the parent is optionally in the specified context, else return undef.

     Parameter  Description
  1  $node      Node to test
  2  @context   Optional context for parent

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <x>
    <a>aaa
      <b>bbb</b>
      ccc
      <d>ddd</d>
      eee
    </a>
  </x>
  END

    ok $d->next ->isLastText (qw(a x));

    ok $d->last ->isLastText (qw(d a x));

    ok $te      ->isLastText (qw(a x));

matchTree($@)

Return a list of nodes that match the specified tree of match expressions, else () if one or more match expressions fail to match nodes in the tree below the specified start node. A match expression consists of [parent node tag, [match expressions to be matched by children of parent]|tags of child nodes to match starting at the first node]. Match expressions for a single item do need to be surrounded with [] and can be merged into their predecessor. The outermost match expression should not be enclosed in [].

     Parameter  Description
  1  $node      Node to start matching from
  2  @match     Tree of match expressions.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
    </b>
    <e>
      <f>
        <g/>
      </f>
    </e>
  </a>
  END
    my ($c, $d, $b, $g, $f, $e) = $a->byList;

    is_deeply [$b, $c, $d], [$b->matchTree(qw(b c d))];
    is_deeply [$e, $f, $g], [$e->matchTree(qr(\Ae\Z), [qw(f g)])];
    is_deeply [$c],         [$c->matchTree(qw(c))];
    is_deeply [$a, $b, $c, $d, $e, $f, $g],
              [$a->matchTree({a=>1}, [qw(b c d)], [qw(e), [qw(f g)]])];
   }

matchesText($$@)

Returns an array of regular expression matches in the text of the specified $node if it is text node and it matches the specified regular expression and optionally has the specified context otherwise returns an empty array.

     Parameter  Description
  1  $node      Node to test
  2  $re        Regular expression
  3  @context   Optional context

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>CDECD</c>
    </b>
  </a>
  END

    my $c = $x->go(qw(b c))->first;

    ok !$c->matchesText(qr(\AD));

    ok  $c->matchesText(qr(\AC), qw(c b a));

    ok !$c->matchesText(qr(\AD), qw(c b a));

    is_deeply [qw(E)], [$c->matchesText(qr(CD(.)CD))];

isBlankText($@)

Return the specified $node if the specified $node is a text node, optionally in the specified context, and contains nothing other than white space else return undef. See also: isAllBlankText

     Parameter  Description
  1  $node      Node to test
  2  @context   Optional context

Example:

    ok $a->prettyStringCDATA eq <<END;
  <a>
      <b><CDATA> </CDATA></b>
  </a>
  END

    ok $b->first->isBlankText;

isAllBlankText($@)

Return the specified $node if the specified $node, optionally in the specified context, does not contain anything or if it does contain something it is all white space else return undef. See also: bitsNodeTextBlank

     Parameter  Description
  1  $node      Node to test
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <z/>
      </c>
    </b>
    <d/>
  </a>
  END

    $a->by(sub{$_->replaceWithBlank(qw(z))});

    my ($b, $c, $d) = $a->firstBy(qw(b c d));

    ok  $c->isAllBlankText;

    ok  $c->isAllBlankText(qw(c b a));

    ok !$c->isAllBlankText(qw(c a));

bitsNodeTextBlank($)

Return a bit string that shows if there are any non text nodes, text nodes or blank text nodes under a node. An empty string is returned if there are no child nodes.

     Parameter  Description
  1  $node      Node to test.

Example:

    ok $x->prettyStringCDATA eq <<END;
  <a>
      <b>
          <C/>
      </b>
      <c>
          <D/>
  <CDATA>
       E
      </CDATA>
      </c>
      <d>
          <F/>
  <CDATA> </CDATA>
          <H/>
      </d>
      <e/>
  </a>
  END

    ok '100' eq -B $x;

    ok '100' eq -B $x->go(q(b));

    ok '110' eq -B $x->go(q(c));

    ok '111' eq -B $x->go(q(d));

    ok !-B $x->go(qw(e));

Number

Number the nodes of a parse tree so that they can be easily retrieved by number - either by a person reading the source xml or programmatically.

findByNumber($$)

Find the node with the specified number as made visible by prettyStringNumbered in the parse tree containing the specified $node and return the found node or undef if no such node exists.

     Parameter  Description
  1  $node      Node in the parse tree to search
  2  $number    Number of the node required.

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c/></b><d><e/></d></a>
  END

    $a->numberTree;
    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3"/>
    </b>
    <d id="4">
      <e id="5"/>
    </d>
  </a>
  END

    ok -t $a->findByNumber_4 eq q(d);
    ok    $a->findByNumber_3__up__number == 2;
   }

    $a->numberTree;

    ok $a->prettyStringNumbered eq <<END;
  <a id="1">
    <b id="2">
      <A id="3"/>
      <B id="4"/>
    </b>
    <c id="5">
      <C id="6"/>
      <D id="7"/>
    </c>
  </a>
  END

    ok q(D) eq -t $a->findByNumber(7);

findByNumbers($@)

Find the nodes with the specified numbers as made visible by prettyStringNumbered in the parse tree containing the specified $node and return the found nodes in a list with undef for nodes that do not exist.

     Parameter  Description
  1  $node      Node in the parse tree to search
  2  @numbers   Numbers of the nodes required.

Example:

    $a->numberTree;

    ok $a->prettyStringNumbered eq <<END;
  <a id="1">
    <b id="2">
      <A id="3"/>
      <B id="4"/>
    </b>
    <c id="5">
      <C id="6"/>
      <D id="7"/>
    </c>
  </a>
  END

    is_deeply [map {-t $_} $a->findByNumbers(1..3)], [qw(a b A)];

numberTree($)

Number the nodes in a parse tree in pre-order so they are numbered in the same sequence that they appear in the source. You can see the numbers by printing the tree with prettyStringNumbered. Nodes can be found using findByNumber. This method differs from forestNumberTrees in that avoids overwriting the id= attribute of each node by using a system attribute instead; this system attribute can then be made visible on the id attribute of each node by printing the parse tree with prettyStringNumbered.

     Parameter  Description
  1  $node      Node

Example:

    $a->numberTree;

    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="42" match="mm"/>
    </b>
    <d id="4">
      <e id="5"/>
    </d>
  </a>
  END

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c/></b><d><e/></d></a>
  END

    $a->numberTree;
    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3"/>
    </b>
    <d id="4">
      <e id="5"/>
    </d>
  </a>
  END

    ok -t $a->findByNumber_4 eq q(d);
    ok    $a->findByNumber_3__up__number == 2;
   }

indexIds($)

Return a map of the ids at and below the specified $node.

     Parameter  Description
  1  $node      Node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a id="A">
    <b id="B">
      <c id="C"/>
      <d id="D">
        <e id="E"/>
        <f id="F"/>
      </d>
    </b>
  </a>
  END

    my $i = $a->indexIds;

    ok $i->{C}->tag eq q(c);

    ok $i->{E}->tag eq q(e);

numberTreesJustIds($$)

Number the ids of the nodes in a parse tree in pre-order so they are numbered in the same sequence that they appear in the source. You can see the numbers by printing the tree with prettyStringNumbered(). This method differs from numberTree in that only non text nodes without ids are numbered. The number applied to each node consists of the concatenation of the specified prefix, an underscore and a number that is unique within the specifed parse tree. Consequently the ids across several trees trees can be made unique by supplying different prefixes for each tree. Nodes can be found using findByNumber. Returns the specified $node.

     Parameter  Description
  1  $node      Node
  2  $prefix    Prefix for each id at and under the specified B<$node>

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>A
    <b id="bb">B
      <c/>
      <d>D
        <e id="ee"/>
          E
        <f/>
          F
      </d>
      G
    </b>
    H
  </a>
  END

    $a->numberTreesJustIds(q(T));

    my $A = Data::Edit::Xml::new(<<END);
  <a id="T_1">A
    <b id="bb">B
      <c id="T_2"/>
      <d id="T_3">D
        <e id="ee"/>
          E
        <f id="T_4"/>
          F
      </d>
      G
    </b>
    H
  </a>
  END

    ok -p $a eq -p $A;

Forest Numbers

Number the nodes of several parse trees so that they can be easily retrieved by forest number - either by a person reading the source xml or programmatically.

forestNumberTrees($$)

Number the ids of the nodes in a parse tree in pre-order so they are numbered in the same sequence that they appear in the source. You can see the numbers by printing the tree with prettyString. This method differs from numberTree in that only non text nodes are numbered and nodes with existing id= attributes have the value of their id= attribute transferred to a label. The number applied to each node consists of the concatenation of the specified tree number, an underscore and a number that is unique within the specified parse tree. Consequently the ids across several trees can be made unique by supplying a different tree number for each tree. Nodes can be found subsequently using findByForestNumber. Returns the specified $node.

     Parameter  Description
  1  $node      Node in parse tree to be numbered
  2  $prefix    Tree number

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b id="b">
      <c/>
    </b>
    <b id="B">
      <d/>
      <e/>
    </b>
  </a>
  END

    my $e = $a->go(qw(b -1 e));

    $e->forestNumberTrees(1);

    ok -p $a eq <<END;
  <a id="1_1">
    <b id="1_2">
      <c id="1_3"/>
    </b>
    <b id="1_4">
      <d id="1_5"/>
      <e id="1_6"/>
    </b>
  </a>
  END

findByForestNumber($$$)

Find the node with the specified forest number as made visible on the id attribute by prettyStringNumbered in the parse tree containing the specified $node and return the found node or undef if no such node exists.

     Parameter  Description
  1  $node      Node in the parse tree to search
  2  $tree      Forest number
  3  $id        Id number of the node required.

Example:

    ok -p $a eq <<END;
  <a id="1_1">
    <b id="1_2">
      <c id="1_3"/>
    </b>
    <b id="1_4">
      <d id="1_5"/>
      <e id="1_6"/>
    </b>
  </a>
  END

    my $B = $e->findByForestNumber(1, 4);

    is_deeply [$B->getLabels], ["B"];

Order

Check the order and relative position of nodes in a parse tree.

above($$@)

Return the first node if the first node is above the second node optionally checking that the first node is in the specified context otherwise return undef

     Parameter  Description
  1  $first     First node
  2  $second    Second node
  3  @context   Optional context

Example:

    my $x = Data::Edit::Xml::new(<<END);
  <a       id='a1'>
    <b     id='b1'>
      <c   id='c1'/>
      <c   id='c2'/>
      <d   id='d1'>
        <e id='e1'/>
      </d>
      <c   id='c3'/>
      <c   id='c4'/>
      <d   id='d2'>
        <e id='e2'/>
      </d>
      <c   id='c5'/>
      <c   id='c6'/>
    </b>
  </a>
  END

    ok $b->id eq 'b1';

    ok $e->id eq "e1";

    ok $E->id eq "e2";

    ok  $b->above($e);

    ok !$E->above($e);

abovePath($$)

Return the nodes along the path from the first node down to the second node when the first node is above the second node else return ().

     Parameter  Description
  1  $first     First node
  2  $second    Second node

Example:

    my $x = Data::Edit::Xml::new(<<END);
  <a       id='a1'>
    <b     id='b1'>
      <c   id='c1'/>
      <c   id='c2'/>
      <d   id='d1'>
        <e id='e1'/>
      </d>
      <c   id='c3'/>
      <c   id='c4'/>
      <d   id='d2'>
        <e id='e2'/>
      </d>
      <c   id='c5'/>
      <c   id='c6'/>
    </b>
  </a>
  END

    my ($a, $b, $c, $d, $e) = $x->firstDown(@tags);

    is_deeply [$b, $d, $e], [$b->abovePath($e)];

    is_deeply [],   [$c->abovePath($d)];

below($$@)

Return the first node if the first node is below the second node optionally checking that the first node is in the specified context otherwise return undef

     Parameter  Description
  1  $first     First node
  2  $second    Second node
  3  @context   Optional context

Example:

    my $x = Data::Edit::Xml::new(<<END);
  <a       id='a1'>
    <b     id='b1'>
      <c   id='c1'/>
      <c   id='c2'/>
      <d   id='d1'>
        <e id='e1'/>
      </d>
      <c   id='c3'/>
      <c   id='c4'/>
      <d   id='d2'>
        <e id='e2'/>
      </d>
      <c   id='c5'/>
      <c   id='c6'/>
    </b>
  </a>
  END

    ok $d->id eq 'd1';

    ok $e->id eq "e1";

    ok !$d->below($e);

belowPath($$)

Return the nodes along the path from the first node up to the second node when the first node is below the second node else return ().

     Parameter  Description
  1  $first     First node
  2  $second    Second node

Example:

    my $x = Data::Edit::Xml::new(<<END);
  <a       id='a1'>
    <b     id='b1'>
      <c   id='c1'/>
      <c   id='c2'/>
      <d   id='d1'>
        <e id='e1'/>
      </d>
      <c   id='c3'/>
      <c   id='c4'/>
      <d   id='d2'>
        <e id='e2'/>
      </d>
      <c   id='c5'/>
      <c   id='c6'/>
    </b>
  </a>
  END

    my ($a, $b, $c, $d, $e) = $x->firstDown(@tags);

    is_deeply [$e, $d, $b], [$e->belowPath($b)];

    is_deeply [$c], [$c->belowPath($c)];

after($$@)

Return the first node if it occurs after the second node in the parse tree optionally checking that the first node is in the specified context or else undef if the node is above, below or before the target.

     Parameter  Description
  1  $first     First node
  2  $second    Second node
  3  @context   Optional context

Example:

    my $x = Data::Edit::Xml::new(<<END);
  <a       id='a1'>
    <b     id='b1'>
      <c   id='c1'/>
      <c   id='c2'/>
      <d   id='d1'>
        <e id='e1'/>
      </d>
      <c   id='c3'/>
      <c   id='c4'/>
      <d   id='d2'>
        <e id='e2'/>
      </d>
      <c   id='c5'/>
      <c   id='c6'/>
    </b>
  </a>
  END

    ok $c->id eq 'c1';

    ok $e->id eq "e1";

    ok $e->after($c);

before($$@)

Return the first node if it occurs before the second node in the parse tree optionally checking that the first node is in the specified context or else undef if the node is above, below or before the target.

     Parameter  Description
  1  $first     First node
  2  $second    Second node
  3  @context   Optional context

Example:

    my $x = Data::Edit::Xml::new(<<END);
  <a       id='a1'>
    <b     id='b1'>
      <c   id='c1'/>
      <c   id='c2'/>
      <d   id='d1'>
        <e id='e1'/>
      </d>
      <c   id='c3'/>
      <c   id='c4'/>
      <d   id='d2'>
        <e id='e2'/>
      </d>
      <c   id='c5'/>
      <c   id='c6'/>
    </b>
  </a>
  END

    ok $e->id eq "e1";

    ok $E->id eq "e2";

    ok $e->before($E);

disordered($@)

Return the first node that is out of the specified order when performing a pre-ordered traversal of the parse tree.

     Parameter  Description
  1  $node      Node
  2  @nodes     Following nodes.

Example:

    my $x = Data::Edit::Xml::new(<<END);
  <a       id='a1'>
    <b     id='b1'>
      <c   id='c1'/>
      <c   id='c2'/>
      <d   id='d1'>
        <e id='e1'/>
      </d>
      <c   id='c3'/>
      <c   id='c4'/>
      <d   id='d2'>
        <e id='e2'/>
      </d>
      <c   id='c5'/>
      <c   id='c6'/>
    </b>
  </a>
  END

    ok $b->id eq 'b1';

    ok $c->id eq 'c1';

    ok $d->id eq 'd1';

    ok $e->id eq "e1";

    ok  $e->disordered($c        )->id eq "c1";

    ok  $b->disordered($c, $e, $d)->id eq "d1";

    ok !$c->disordered($e);

commonAncestor($@)

Find the most recent common ancestor of the specified nodes or undef if there is no common ancestor.

     Parameter  Description
  1  $node      Node
  2  @nodes     @nodes

Example:

    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="3">
        <e id="4"/>
      </c>
      <d id="5">
        <e id="6"/>
      </d>
      <c id="7">
        <d id="8">
          <e id="9"/>
        </d>
      </c>
      <d id="10">
        <e id="11"/>
      </d>
      <c id="12">
        <d id="13">
          <e id="14"/>
        </d>
      </c>
    </b>
  </a>
  END

     {my ($b, $e, @n) = $a->findByNumbers(2, 4, 6, 9);

      ok $e == $e->commonAncestor;

      ok $e == $e->commonAncestor($e);

      ok $b == $e->commonAncestor($b);

      ok $b == $e->commonAncestor(@n);

commonAdjacentAncestors($$)

Given two nodes, find a pair of adjacent ancestral siblings if such a pair exists else return ().

     Parameter  Description
  1  $first     First node
  2  $second    Second node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    is_deeply [$d->commonAdjacentAncestors($C)], [$b, $B];

ordered($@)

Return the first node if the specified nodes are all in order when performing a pre-ordered traversal of the parse tree else return undef.

     Parameter  Description
  1  $node      Node
  2  @nodes     Following nodes.

Example:

    my $x = Data::Edit::Xml::new(<<END);
  <a       id='a1'>
    <b     id='b1'>
      <c   id='c1'/>
      <c   id='c2'/>
      <d   id='d1'>
        <e id='e1'/>
      </d>
      <c   id='c3'/>
      <c   id='c4'/>
      <d   id='d2'>
        <e id='e2'/>
      </d>
      <c   id='c5'/>
      <c   id='c6'/>
    </b>
  </a>
  END

    ok $e->id eq "e1";

    ok $E->id eq "e2";

    ok  $e->ordered($E);

    ok !$E->ordered($e);

    ok  $e->ordered($e);

    ok  $e->ordered;

Patching

Analyze two similar parse trees and create a patch that transforms the first parse tree into the second as long as each tree has the same tag and id structure with each id being unique.

createPatch($$)

Create a patch that moves the source parse tree to the target parse tree node as long as they have the same tag and id structure with each id being unique.

     Parameter  Description
  1  $a         Source parse tree
  2  $A         Target parse tree

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>Aaaaa
    <b b1="b1" b2="b2">Bbbbb
      <c c1="c1" />Ccccc
      <d d1="d1" >Ddddd
        <e  e1="e1" />
          Eeeee
        <f  f1="f1" />
          Fffff
      </d>
      Ggggg
    </b>
    Hhhhhh
  </a>
  END

    my $A = Data::Edit::Xml::new(<<END);
  <a>AaaAaaA
    <b b1="b1" b3="B3">BbbBbbB
      <c c1="C1" />Ccccc
      <d d2="D2" >DddDddD
        <e  e3="E3" />
          EeeEeeE
        <f  f1="F1" />
          FffFffF
      </d>
      GggGggG
    </b>
    Hhhhhh
  </a>
  END

    $a->numberTreesJustIds(q(a));

    $A->numberTreesJustIds(q(a));

    my $patches = $a->createPatch($A);

    $patches->install($a);

    ok !$a->diff  ($A);

    ok  $a->equals($A);

Data::Edit::Xml::Patch::install($$)

Replay a patch created by createPatch against a parse tree that has the same tag and id structure with each id being unique.

     Parameter  Description
  1  $patches   Patch
  2  $a         Parse tree

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>Aaaaa
    <b b1="b1" b2="b2">Bbbbb
      <c c1="c1" />Ccccc
      <d d1="d1" >Ddddd
        <e  e1="e1" />
          Eeeee
        <f  f1="f1" />
          Fffff
      </d>
      Ggggg
    </b>
    Hhhhhh
  </a>
  END

    my $A = Data::Edit::Xml::new(<<END);
  <a>AaaAaaA
    <b b1="b1" b3="B3">BbbBbbB
      <c c1="C1" />Ccccc
      <d d2="D2" >DddDddD
        <e  e3="E3" />
          EeeEeeE
        <f  f1="F1" />
          FffFffF
      </d>
      GggGggG
    </b>
    Hhhhhh
  </a>
  END

    $a->numberTreesJustIds(q(a));

    $A->numberTreesJustIds(q(a));

    my $patches = $a->createPatch($A);

    $patches->install($a);

    ok !$a->diff  ($A);

    ok  $a->equals($A);

Propogating

Propagate parent node attributes through a parse tree.

propagate($$@)

Propagate new attributes from nodes that match the specified tag to all their child nodes, then unwrap all the nodes that match the specified tag. Return the specified parse tree.

     Parameter  Description
  1  $tree      Parse tree
  2  $tag       Tag of nodes whose attributes are to be propagated
  3  @context   Optional context for parse tree

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b b="B">
      <b c="C">
        <c/>
        <b d="D">
          <d/>
          <b e="E">
            <e/>
          </b>
        </b>
      </b>
    </b>
  </a>
  END

    $a->propagate(q(b));

    ok -p $a eq <<END;
  <a>
    <c b="B" c="C"/>
    <d b="B" c="C" d="D"/>
    <e b="B" c="C" d="D" e="E"/>
  </a>
  END

Analyze and generate tables of contents.

tocNumbers($@)

Table of Contents number the nodes in a parse tree.

     Parameter  Description
  1  $node      Node
  2  @match     Optional list of tags to descend into else all tags will be descended into

Example:

    ok $a->prettyStringNumbered eq <<END;
  <a id="1">
    <b id="2">
      <A id="3"/>
      <B id="4"/>
    </b>
    <c id="5">
      <C id="6"/>
      <D id="7"/>
    </c>
  </a>
  END

      my $t = $a->tocNumbers();

      is_deeply {map {$_=>$t->{$_}->tag} keys %$t},

       {"1"  =>"b",

        "1 1"=>"A",

        "1 2"=>"B",

        "2"  =>"c",

        "2 1"=> "C",

        "2 2"=>"D"

       }

Labels

Label nodes so that they can be cross referenced and linked by Data::Edit::Xml::Lint

addLabels($@)

Add the named labels to the specified $node and return the number of labels added. Labels that are not defined will be ignored.

     Parameter  Description
  1  $node      Node in parse tree
  2  @labels    Names of labels to add.

Example:

    ok $x->stringReplacingIdsWithLabels eq '<a><b><c/></b></a>';

    my $b = $x->go(q(b));

    ok $b->countLabels == 0;

    $b->addLabels(1..2);

    $b->addLabels(3..4);

    ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c/></b></a>';

countLabels($)

Return the count of the number of labels at a node.

     Parameter  Description
  1  $node      Node in parse tree.

Example:

    ok $x->stringReplacingIdsWithLabels eq '<a><b><c/></b></a>';

    my $b = $x->go(q(b));

    ok $b->countLabels == 0;

    $b->addLabels(1..2);

    $b->addLabels(3..4);

    ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c/></b></a>';

    ok $b->countLabels == 4;

labelsInTree($)

Return a hash of all the labels in a tree

     Parameter  Description
  1  $tree      Parse tree.

Example:

    ok -p (new $A->stringExtendingIdsWithLabels) eq <<END;
  <a id="aa, a, a5">
    <b id="bb, b, b2">
      <c id="cc, c, c1"/>
    </b>
    <b id="B, b4">
      <c id="C, c3"/>
    </b>
  </a>
  END

    is_deeply [sort keys %{$A->labelsInTree}],

      ["B", "C", "a", "a5", "b", "b2", "b4", "c", "c1", "c3"];

getLabels($)

Return the names of all the labels set on a node.

     Parameter  Description
  1  $node      Node in parse tree.

Example:

    ok $x->stringReplacingIdsWithLabels eq '<a><b><c/></b></a>';

    my $b = $x->go(q(b));

    ok $b->countLabels == 0;

    $b->addLabels(1..2);

    $b->addLabels(3..4);

    ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c/></b></a>';

    is_deeply [1..4], [$b->getLabels];

deleteLabels($@)

Delete the specified labels in the specified $node or all labels if no labels have are specified and return that node.

     Parameter  Description
  1  $node      Node in parse tree
  2  @labels    Names of the labels to be deleted

Example:

    ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c id="1, 2, 3, 4"/></b></a>';

    $b->deleteLabels(1,4) for 1..2;

    ok $x->stringReplacingIdsWithLabels eq '<a><b id="2, 3"><c id="1, 2, 3, 4"/></b></a>';

copyLabels($$)

Copy all the labels from the source node to the target node and return the source node.

     Parameter  Description
  1  $source    Source node
  2  $target    Target node.

Example:

    ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c/></b></a>';

    $b->copyLabels($c) for 1..2;

    ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c id="1, 2, 3, 4"/></b></a>';

moveLabels($$)

Move all the labels from the source node to the target node and return the source node.

     Parameter  Description
  1  $source    Source node
  2  $target    Target node.

Example:

    ok $x->stringReplacingIdsWithLabels eq '<a><b id="2, 3"><c id="1, 2, 3, 4"/></b></a>';

    $b->moveLabels($c) for 1..2;

    ok $x->stringReplacingIdsWithLabels eq '<a><b><c id="1, 2, 3, 4"/></b></a>';

copyLabelsAndIdsInTree($$)

Copy all the labels and ids in the source parse tree to the matching nodes in the target parse tree. Nodes are matched via path. Return the number of labels and ids copied.

     Parameter  Description
  1  $source    Source node
  2  $target    Target node.

Example:

    ok -p (new $a->stringExtendingIdsWithLabels) eq <<END;
  <a id="a, a5">
    <b id="b, b2">
      <c id="c, c1"/>
    </b>
    <b id="B, b4">
      <c id="C, c3"/>
    </b>
  </a>
  END

    ok -p (new $A->stringExtendingIdsWithLabels) eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"/>
    </b>
    <b>
      <c/>
    </b>
  </a>
  END

    ok $a->copyLabelsAndIdsInTree($A) == 10;

    ok -p (new $A->stringExtendingIdsWithLabels) eq <<END;
  <a id="aa, a, a5">
    <b id="bb, b, b2">
      <c id="cc, c, c1"/>
    </b>
    <b id="B, b4">
      <c id="C, c3"/>
    </b>
  </a>
  END

Operators

Operator access to methods use the assign versions to avoid 'useless use of operator in void context' messages. Use the non assign versions to return the results of the underlying method call. Thus '/' returns the wrapping node, whilst '/=' does not. Assign operators always return their left hand side even though the corresponding method usually returns the modification on the right.

opString($$)

-B: bitsNodeTextBlank

-b: isAllBlankText

-c: context

-e: prettyStringEnd

-f: first node

-g: pathString

-l: last node

-M: number

-o: contentAsTags

-p: prettyString

-s: string

-S : stringNode

-T : isText

-t : tag

-u: id

-W: unWrap

-w: stringQuoted

-x: prettyStringDitaHeaders

-X: cut

-z: prettyStringNumbered.

     Parameter  Description
  1  $node      Node
  2  $op        Monadic operator.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b><c>ccc</c></b>
    <d><e>eee</e></d>
  </a>
  END

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    my ($c, $b, $e, $d) = $a->byList;

    ok $c->printNode eq q(c id="42" match="mm");

    ok -A $c eq q(c id="42" match="mm");

    ok -b $e;

    ok -c $e eq q(e d a);

    ok -f $b eq $c;

    ok -l $a eq $d;

    ok -O $a, q( b  d );

    ok -o $a, q(b d);

    ok -w $a eq q('<a><b><c id="42" match="mm"/></b><d><e/></d></a>');

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    ok -s $a eq '<a><b><c id="42" match="mm"/></b><d><e/></d></a>';

    ok -t $a eq 'a';

    $a->numberTree;

    ok -z $a eq <<END;
  <a id="1">
    <b id="2">
      <c id="42" match="mm"/>
    </b>
    <d id="4">
      <e id="5"/>
    </d>
  </a>
  END

   {my $a = Data::Edit::Xml::new(<<END);
  <concept/>
  END

    Data::Edit::Xml::ditaOrganization = q(ACT);

    ok $a->prettyStringDitaHeaders eq <<END;
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE concept PUBLIC "-//ACT//DTD DITA Concept//EN" "concept.dtd" []>
  <concept/>
  END

    ok -x $a eq <<END;
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE concept PUBLIC "-//ACT//DTD DITA Concept//EN" "concept.dtd" []>
  <concept/>
  END

opContents($)

@{} : nodes immediately below a node.

     Parameter  Description
  1  $node      Node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b><c>ccc</c></b>
    <d><e>eee</e></d>
  </a>
  END

    my ($b, $d) =  @$a;

    ok -c $b eq q(b a);

    my ($c)     =  @$b;

    ok -c $c eq q(c b a);

opAt($$)

<= : Check that a node is in the context specified by the referenced array of words.

     Parameter  Description
  1  $node      Node
  2  $context   Reference to array of words specifying the parents of the desired node.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    ok (($a >= [qw(d e)]) <= [qw(e d a)]);

opNew($$)

** : create a new node from the text on the right hand side: if the text contains a non word character \W the node will be create as text, else it will be created as a tag

     Parameter  Description
  1  $node      Node
  2  $text      Name node of node to create or text of new text element

Example:

   {my $a = Data::Edit::Xml::new("<a/>");

    my $b = $a ** q(b);

    ok -s $b eq "<b/>";

opPutFirst($$)

>> : put a node or string first under a node and return the new node.

     Parameter  Description
  1  $node      Node
  2  $text      Node or text to place first under the node.

Example:

    ok -p $a eq <<END;
  <a/>
  END

    my $f = $a >> qq(first);

    ok -p $a eq <<END;
  <a>
    <first/>
  </a>
  END

opPutFirstAssign($$)

>>= : put a node or string first under a node.

     Parameter  Description
  1  $node      Node
  2  $text      Node or text to place first under the node.

Example:

    ok -p $a eq <<END;
  <a/>
  END

    $a >>= qq(first);

    ok -p $a eq <<END;
  <a>
    <first/>
  </a>
  END

opPutLast($$)

<< : put a node or string last under a node and return the new node.

     Parameter  Description
  1  $node      Node
  2  $text      Node or text to place last under the node.

Example:

    ok -p $a eq <<END;
  <a>
    <first/>
  </a>
  END

    my $l = $a << qq(last);

    ok -p $a eq <<END;
  <a>
    <first/>
    <last/>
  </a>
  END

opPutLastAssign($$)

<<= : put a node or string last under a node.

     Parameter  Description
  1  $node      Node
  2  $text      Node or text to place last under the node.

Example:

    ok -p $a eq <<END;
  <a>
    <first/>
  </a>
  END

    $a <<= qq(last);

    ok -p $a eq <<END;
  <a>
    <first/>
    <last/>
  </a>
  END

opPutNext($$)

> + : put a node or string after the specified $node and return the new node.

     Parameter  Description
  1  $node      Node
  2  $text      Node or text to place after the first node.

Example:

    ok -p $a eq <<END;
  <a>
    <first/>
    <last/>
  </a>
  END

    $f += qq(next);

    ok -p $a eq <<END;
  <a>
    <first/>
    <next/>
    <last/>
  </a>
  END

opPutNextAssign($$)

+= : put a node or string after the specified $node.

     Parameter  Description
  1  $node      Node
  2  $text      Node or text to place after the first node.

Example:

    ok -p $a eq <<END;
  <a>
    <first/>
    <last/>
  </a>
  END

    my $f = -f $a;

    $f += qq(next);

    ok -p $a eq <<END;
  <a>
    <first/>
    <next/>
    <last/>
  </a>
  END

opPutPrev($$)

< - : put a node or string before the specified $node and return the new node.

     Parameter  Description
  1  $node      Node
  2  $text      Node or text to place before the first node.

Example:

    ok -p $a eq <<END;
  <a>
    <first/>
    <next/>
    <last/>
  </a>
  END

    $l -= qq(prev);

    ok -p $a eq <<END;
  <a>
    <first/>
    <next/>
    <prev/>
    <last/>
  </a>
  END

opPutPrevAssign($$)

-= : put a node or string before the specified $node,

     Parameter  Description
  1  $node      Node
  2  $text      Node or text to place before the first node.

Example:

    ok -p $a eq <<END;
  <a>
    <first/>
    <next/>
    <last/>
  </a>
  END

    my $l = -l $a;

    $l -= qq(prev);

    ok -p $a eq <<END;
  <a>
    <first/>
    <next/>
    <prev/>
    <last/>
  </a>
  END

opBy($$)

x= : Traverse a parse tree in post-order.

     Parameter  Description
  1  $node      Parse tree
  2  $code      Code to execute against each node.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

     {my $s; $a x= sub{$s .= -t $_}; ok $s eq "cbeda"

opGo($$)

>= : Search for a node via a specification provided as a reference to an array of words each number. Each word represents a tag name, each number the index of the previous tag or zero by default.

     Parameter  Description
  1  $node      Node
  2  $go        Reference to an array of search parameters.

Example:

    ok -p $a eq <<END;                                                            #tdown #tdownX
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    ok (($a >= [qw(d e)]) <= [qw(e d a)]);

opAttr($$)

% : Get the value of an attribute of the specified $node.

     Parameter  Description
  1  $node      Node
  2  $attr      Reference to an array of words and numbers specifying the node to search for.

Example:

   {my $a = Data::Edit::Xml::new('<a number="1"/>');

    ok $a %  qq(number) == 1;

opWrapWith($$)

/ : Wrap node with a tag, returning the wrapping node.

     Parameter  Description
  1  $node      Node
  2  $tag       Tag.

Example:

   {my $c = Data::Edit::Xml::new("<c/>");

    my $b = $c / qq(b);

    ok -s $b eq "<b><c/></b>";

    my $a = $b / qq(a);

    ok -s $a eq "<a><b><c/></b></a>";

opWrapContentWith($$)

* : Wrap content with a tag, returning the wrapping node.

     Parameter  Description
  1  $node      Node
  2  $tag       Tag.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
    </b>
  </a>
  END

    my ($c, $d, $b) = $a->byList;

    $b *= q(B);

    ok -p $a eq <<END;
  <a>
    <b>
      <B>
        <c/>
        <d/>
      </B>
    </b>
  </a>
  END

opCut($)

-- : Cut out a node.

     Parameter  Description
  1  $node      Node.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>
    <b><c/></b>
  </a>
  END

    my $b = $x >= qq(b);

     --$b;

    ok -s $x eq "<a/>";

    ok -s $b eq "<b><c/></b>";

opUnwrap($)

++ : Unwrap a node.

     Parameter  Description
  1  $node      Node.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
      <d/>
    </b>
  </a>
  END

    my ($c, $d, $b) = $a->byList;

    $b++;

    ok -p $a eq <<END;
  <a>
    <c/>
    <d/>
  </a>
  END

Statistics

Statistics describing the parse tree.

count($@)

Return the count of the number of instances of the specified tags under the specified $node, either by tag in array context or in total in scalar context.

     Parameter  Description
  1  $node      Node
  2  @names     Possible tags immediately under the node.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a>

  </a>
  END

    ok $x->count == 0;

countTags($)

Count the number of tags in a parse tree.

     Parameter  Description
  1  $node      Parse tree.

Example:

      ok -p $a eq <<END;
  <a id="aa">
    <b id="bb">
      <c id="cc"/>
    </b>
  </a>
  END

      ok $a->countTags == 3;

countTagNames($$)

Return a reference to a hash showing the number of instances of each tag on and below the specified $node.

     Parameter  Description
  1  $node      Node
  2  $count     Count of tags so far.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a A="A" B="B" C="C">
    <b  B="B" C="C">
      <c  C="C">
      </c>
      <c/>
    </b>
    <b  C="C">
      <c/>
    </b>
  </a>
  END

    is_deeply $x->countTagNames,  { a => 1, b => 2, c => 3 };

countAttrNames($$)

Return a reference to a hash showing the number of instances of each attribute on and below the specified $node.

     Parameter  Description
  1  $node      Node
  2  $count     Attribute count so far

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a A="A" B="B" C="C">
    <b  B="B" C="C">
      <c  C="C">
      </c>
      <c/>
    </b>
    <b  C="C">
      <c/>
    </b>
  </a>
  END

    is_deeply $x->countAttrNames, { A => 1, B => 2, C => 4 };

countAttrNamesOnTagExcluding($@)

Count the number of attributes owned by the specified $node that are not in the specified list.

     Parameter  Description
  1  $node      Node
  2  @attr      Attributes to ignore

Example:

   {my $a = Data::Edit::Xml::new(q(<a a="1" b="2" c="3" d="4" e="5"/>));

countAttrValues($$)

Return a reference to a hash showing the number of instances of each attribute value on and below the specified $node.

     Parameter  Description
  1  $node      Node
  2  $count     Count of attributes so far.

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <a A="A" B="B" C="C">
    <b  B="B" C="C">
      <c  C="C">
      </c>
      <c/>
    </b>
    <b  C="C">
      <c/>
    </b>
  </a>
  END

    is_deeply $x->countAttrValues, { A => 1, B => 2, C => 4 };

countOutputClasses($$)

Count instances of outputclass attributes

     Parameter  Description
  1  $node      Node
  2  $count     Count so far.

Example:

   {my $a = Data::Edit::Xml::newTree("a", id=>1, class=>2, href=>3, outputclass=>4);

    is_deeply { 4 => 1 }, $a->countOutputClasses;

changeReasonCommentSelectionSpecification()

Provide a specification to select change reason comments to be inserted as text into a parse tree. A specification can be either:

the name of a code to be accepted,
a regular expression which matches the codes to be accepted,
a hash whose keys are defined for the codes to be accepted or
undef (the default) to specify that no such comments should be accepted.

Example:

    changeReasonCommentSelectionSpecification = {ccc=>1, ddd=>1};

    changeReasonCommentSelectionSpecification = undef;

This is a static method and so should be invoked as:

  Data::Edit::Xml::changeReasonCommentSelectionSpecification

crc($$$)

Insert a comment consisting of a code and an optional reason as text into the parse tree to indicate the location of changes to the parse tree. As such comments tend to become very numerous, only comments whose codes matches the specification provided in changeReasonCommentSelectionSpecification are accepted for insertion. Subsequently these comments can be easily located using:

grep -nr "<!--code"

on the file containing a printed version of the parse tree. Please note that these comments will be removed if the output file is reparsed.

Returns the specified $node.

     Parameter  Description
  1  $node      Node being changed
  2  $code      Reason code
  3  $reason    Optional text description of change

Example:

   {my $a = Data::Edit::Xml::new("<a><b/></a>");

    my ($b) = $a->contents;

    changeReasonCommentSelectionSpecification = {ccc=>1, ddd=>1};

    $b->putFirst(my $c = $b->newTag(q(c)));

    $c->crc($_) for qw(aaa ccc);

    ok <<END eq -p $a;
  <a>
    <b><!--ccc-->
      <c/>
    </b>
  </a>
  END

    changeReasonCommentSelectionSpecification = undef;

    $c->putFirst(my $d = $c->newTag(q(d)));

    $d->crc($_) for qw(aaa ccc);

    ok <<END eq -p $a;
  <a>
    <b><!--ccc-->
      <c>
        <d/>
      </c>
    </b>
  </a>
  END

howFirst($)

Return the depth to which the specified $node is first else 0.

     Parameter  Description
  1  $node      Node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    ok $d->howFirst     == 4;

howLast($)

Return the depth to which the specified $node is last else 0.

     Parameter  Description
  1  $node      Node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    ok $f->howLast      == 3;

howOnlyChild($)

Return the depth to which the specified $node is an only child else 0.

     Parameter  Description
  1  $node      Node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    ok $d->howOnlyChild == 2;

howFar($$)

Return how far the first node is from the second node along a path through their common ancestor.

     Parameter  Description
  1  $first     First node
  2  $second    Second node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    is_deeply [$d->commonAdjacentAncestors($C)], [$b, $B];

    ok $d->howFar($d) == 0;

    ok $d->howFar($a) == 3;

    ok $b->howFar($B) == 1;

    ok $d->howFar($f) == 5;

    ok $d->howFar($C) == 4;

howFarAbove($$)

Return how far the first node is above the second node is or 0 if the first node is not strictly above the second node.

     Parameter  Description
  1  $above     First node above
  2  $below     Second node below

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    ok  $a->howFarAbove($d) == 3;

    ok !$d->howFarAbove($c);

howFarBelow($$)

Return how far the first node is below the second node is or 0 if the first node is not strictly below the second node.

     Parameter  Description
  1  $below     First node below
  2  $above     Second node above

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
    </b>
    <b>
      <c/>
    </b>
    <e>
      <f/>
    </e>
  </a>
  END

    my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;

    ok  $d->howFarBelow($a) == 3;

    ok !$c->howFarBelow($d);

Required clean up

Insert required clean up tags.

requiredCleanUp($$)

Replace a node with a required cleanup node around the text of the replaced node with special characters replaced by symbols.

Returns the specified $node.

     Parameter     Description
  1  $node         Node
  2  $outputclass  Optional outputclass attribute of required cleanup tag

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        ccc
      </c>
    </b>
  </a>
  END

    my ($b) = $a->contents;

    $b->requiredCleanUp(q(33));

    ok -p $a eq <<END;
  <a>
    <required-cleanup outputclass="33">&lt;b&gt;
    &lt;c&gt;
        ccc
      &lt;/c&gt;
  &lt;/b&gt;
  </required-cleanup>
  </a>
  END

replaceWithRequiredCleanUp($$)

Replace a node with a required cleanup message and return the new node

     Parameter  Description
  1  $node      Node to be replace
  2  $text      Clean up message

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
  </a>
  END

    my ($b) = $a->contents;

    $b->replaceWithRequiredCleanUp(q(bb));

    ok -p $a eq <<END;
  <a>
    <required-cleanup>bb</required-cleanup>
  </a>
  END

putFirstRequiredCleanUp($$)

Place a required cleanup tag first under a node and return the required clean up node.

     Parameter  Description
  1  $node      Node
  2  $text      Clean up message

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b/>
  </a>
  END

    $a->putFirstRequiredCleanUp(qq(1111
));

    ok -p $a eq <<END;
  <a>
    <required-cleanup>1111
  </required-cleanup>
    <b/>
  </a>
  END

putLastRequiredCleanUp($$)

Place a required cleanup tag last under a node and return the required clean up node.

     Parameter  Description
  1  $node      Node
  2  $text      Clean up message

Example:

    ok -p $a eq <<END;
  <a>
    <required-cleanup>1111
  </required-cleanup>
    <b/>
  </a>
  END

    $a->putLastRequiredCleanUp(qq(4444
));

    ok -p $a eq <<END;
  <a>
    <required-cleanup>1111
  </required-cleanup>
    <b/>
    <required-cleanup>4444
  </required-cleanup>
  </a>
  END

putNextRequiredCleanUp($$)

Place a required cleanup tag after a node.

     Parameter  Description
  1  $node      Node
  2  $text      Clean up message

Example:

    ok -p $a eq <<END;
  <a>
    <required-cleanup>1111
  </required-cleanup>
    <b/>
    <required-cleanup>4444
  </required-cleanup>
  </a>
  END

    $a->go(q(b))->putNextRequiredCleanUp(qq(3333
));

    ok -p $a eq <<END;
  <a>
    <required-cleanup>1111
  </required-cleanup>
    <b/>
    <required-cleanup>3333
  </required-cleanup>
    <required-cleanup>4444
  </required-cleanup>
  </a>
  END

putPrevRequiredCleanUp($$)

Place a required cleanup tag before a node.

     Parameter  Description
  1  $node      Node
  2  $text      Clean up message

Example:

    ok -p $a eq <<END;
  <a>
    <required-cleanup>1111
  </required-cleanup>
    <b/>
    <required-cleanup>3333
  </required-cleanup>
    <required-cleanup>4444
  </required-cleanup>
  </a>
  END

    $a->go(q(b))->putPrevRequiredCleanUp(qq(2222
));

    ok -p $a eq <<END;
  <a>
    <required-cleanup>1111
  </required-cleanup>
    <required-cleanup>2222
  </required-cleanup>
    <b/>
    <required-cleanup>3333
  </required-cleanup>
    <required-cleanup>4444
  </required-cleanup>
  </a>
  END

Conversions

Methods useful for conversions to and from word, html and Dita.

ditaListToSteps($@)

Change the specified $node to steps and its contents to cmd\step optionally only in the specified context.

     Parameter  Description
  1  $list      Node
  2  @context   Optional context

Example:

    ok -p $a eq <<END;
  <dita>
    <ol>
      <li>
        <p>aaa</p>
      </li>
      <li>
        <p>bbb</p>
      </li>
    </ol>
  </dita>
  END

    $a->first->ditaListToSteps;

    ok -p $a eq <<END;
  <dita>
    <steps>
      <step>
        <cmd>aaa</cmd>
      </step>
      <step>
        <cmd>bbb</cmd>
      </step>
    </steps>
  </dita>
  END

ditaListToStepsUnordered($@)

Change the specified $node to steps-unordered and its contents to cmd\step optionally only in the specified context.

     Parameter  Description
  1  $list      Node
  2  @context   Optional context

Example:

    ok -p $a eq <<END;
  <dita>
    <ol>
      <li>aaa</li>
      <li>bbb</li>
    </ol>
  </dita>
  END

    $a->first->ditaListToStepsUnordered;

    ok -p $a eq <<END;
  <dita>
    <steps-unordered>
      <step>
        <cmd>aaa</cmd>
      </step>
      <step>
        <cmd>bbb</cmd>
      </step>
    </steps-unordered>
  </dita>
  END

ditaListToSubSteps($@)

Change the specified $node to substeps and its contents to cmd\step optionally only in the specified context.

     Parameter  Description
  1  $list      Node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <dita>
    <ol>
      <li>aaa</li>
      <li>bbb</li>
    </ol>
  </dita>
  END

    $a->first->ditaListToSubSteps;

    ok -p $a eq <<END;
  <dita>
    <substeps>
      <substep>
        <cmd>aaa</cmd>
      </substep>
      <substep>
        <cmd>bbb</cmd>
      </substep>
    </substeps>
  </dita>
  END

ditaStepsToList($@)

Change the specified $node to ol and its cmd\step content to li optionally only in the specified context.

     Parameter  Description
  1  $steps     Node
  2  @context   Optional context

Example:

    ok -p $a eq <<END;
  <dita>
    <ol>
      <li>
        <p>aaa</p>
      </li>
      <li>
        <p>bbb</p>
      </li>
    </ol>
  </dita>
  END

    $a->first->ditaStepsToList;

    ok -p $a eq <<END;
  <dita>
    <ol>
      <li>aaa</li>
      <li>bbb</li>
    </ol>
  </dita>
  END

ditaMergeLists($@)

Merge the specified $node with the preceding or following list or steps or substeps if possible and return the specified $node regardless.

     Parameter  Description
  1  $node      Node
  2  @context   Optional context

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <li id="1"/>
    <ol/>
    <ol>
      <li id="2"/>
      <li id="3"/>
    </ol>
  </a>
  END

    $a x= sub{$_->ditaMergeLists};

    ok -p $a eq <<END;
  <a>
    <ol>
      <li id="1"/>
      <li id="2"/>
      <li id="3"/>
    </ol>
  </a>
  END

ditaMaximumNumberOfEntriesInARow($)

Return the maximum number of entries in the rows of the specified $table or undef if not a table.

     Parameter  Description
  1  $table     Table node

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <table>
    <tgroup>
      <tbody>
        <row><entry/></row>
        <row><entry/><entry/></row>
        <row><entry/><entry/><entry/></row>
        <row><entry/><entry/></row>
        <row/>
      </tbody>
    </tgroup>
  </table>
  END

    ok 3 == $a->ditaMaximumNumberOfEntriesInARow;
    $a->first->ditaAddColSpecToTgroup(3);

    ok -p $a eq <<END
  <table>
    <tgroup cols="3">
      <colspec colname="c1" colnum="1" colwidth="1*"/>
      <colspec colname="c2" colnum="2" colwidth="1*"/>
      <colspec colname="c3" colnum="3" colwidth="1*"/>
      <tbody>
        <row>
          <entry/>
        </row>
        <row>
          <entry/>
          <entry/>
        </row>
        <row>
          <entry/>
          <entry/>
          <entry/>
        </row>
        <row>
          <entry/>
          <entry/>
        </row>
        <row/>
      </tbody>
    </tgroup>
  </table>
  END
   }

ditaAddColSpecToTgroup($$)

Add the specified $number of column specification to a specified $tgroup which does not have any already.

     Parameter  Description
  1  $tgroup    Tgroup node
  2  $number    Number of colspecs to add

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <table>
    <tgroup>
      <tbody>
        <row><entry/></row>
        <row><entry/><entry/></row>
        <row><entry/><entry/><entry/></row>
        <row><entry/><entry/></row>
        <row/>
      </tbody>
    </tgroup>
  </table>
  END

    ok 3 == $a->ditaMaximumNumberOfEntriesInARow;
    $a->first->ditaAddColSpecToTgroup(3);

    ok -p $a eq <<END
  <table>
    <tgroup cols="3">
      <colspec colname="c1" colnum="1" colwidth="1*"/>
      <colspec colname="c2" colnum="2" colwidth="1*"/>
      <colspec colname="c3" colnum="3" colwidth="1*"/>
      <tbody>
        <row>
          <entry/>
        </row>
        <row>
          <entry/>
          <entry/>
        </row>
        <row>
          <entry/>
          <entry/>
          <entry/>
        </row>
        <row>
          <entry/>
          <entry/>
        </row>
        <row/>
      </tbody>
    </tgroup>
  </table>
  END
   }

ditaFixTableColSpec($)

Improve the specified $table by making obvious improvements.

     Parameter  Description
  1  $table     Table node

Example:

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <table>
    <tbody>
      <row><entry/></row>
      <row><entry/><entry/></row>
      <row><entry/><entry/><entry/></row>
      <row><entry/><entry/></row>
      <row>
        <entry>
          <table>
            <tbody>
              <row><entry/><entry/><entry/><entry/><entry/><entry/><entry/></row>
            </tbody>
          </table>
        </entry>
      </row>
   </tbody>
  </table>
  END

    $a->ditaFixTableColSpec;

    ok -p $a eq <<END
  <table>
    <tgroup cols="3">
      <colspec colname="c1" colnum="1" colwidth="1*"/>
      <colspec colname="c2" colnum="2" colwidth="1*"/>
      <colspec colname="c3" colnum="3" colwidth="1*"/>
      <tbody>
        <row>
          <entry/>
        </row>
        <row>
          <entry/>
          <entry/>
        </row>
        <row>
          <entry/>
          <entry/>
          <entry/>
        </row>
        <row>
          <entry/>
          <entry/>
        </row>
        <row>
          <entry>
            <table>
              <tbody>
                <row>
                  <entry/>
                  <entry/>
                  <entry/>
                  <entry/>
                  <entry/>
                  <entry/>
                  <entry/>
                </row>
              </tbody>
            </table>
          </entry>
        </row>
      </tbody>
    </tgroup>
  </table>
  END
   }

ditaObviousChanges($)

Make obvious changes to a parse tree to make it look more like Dita.

     Parameter  Description
  1  $node      Node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <dita>
    <ol>
      <li><para>aaa</para></li>
      <li><para>bbb</para></li>
    </ol>
  </dita>
  END

    $a->ditaObviousChanges;

    ok -p $a eq <<END;
  <dita>
    <ol>
      <li>
        <p>aaa</p>
      </li>
      <li>
        <p>bbb</p>
      </li>
    </ol>
  </dita>
  END

ditaOrganization()

Set the dita organization field in the xml headers, set by default to OASIS.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <concept/>
  END

    Data::Edit::Xml::ditaOrganization = q(ACT);

    ok $a->prettyStringDitaHeaders eq <<END;
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE concept PUBLIC "-//ACT//DTD DITA Concept//EN" "concept.dtd" []>
  <concept/>
  END

    ok -x $a eq <<END;
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE concept PUBLIC "-//ACT//DTD DITA Concept//EN" "concept.dtd" []>
  <concept/>
  END

ditaTopicHeaders($)

Add xml headers for the dita document type indicated by the specified parse tree

     Parameter  Description
  1  $node      Node in parse tree

Example:

    ok Data::Edit::Xml::new(q(<concept/>))->ditaTopicHeaders eq <<END;
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd" []>
  END

ditaPrettyPrintWithHeaders($)

Add xml headers for the dita document type indicated by the specified parse tree to a pretty print of the parse tree.

     Parameter  Description
  1  $node      Node in parse tree

htmlHeadersToSections($)

Position sections just before html header tags so that subsequently the document can be divided into sections.

     Parameter  Description
  1  $node      Parse tree

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <x>
  <h1>h1</h1>
    H1
  <h2>h2</h2>
    H2
  <h3>h3</h3>
    H3
  <h3>h3</h3>
    H3
  <h2>h2</h2>
    H2
  <h4>h4</h4>
    H4
  </x>
  END

  $x->htmlHeadersToSections;

    $x->divideDocumentIntoSections(sub

     {my ($topicref, $section) = @_;

      my $file = keys %file;

      $topicref->href = $file;

      $file{$file} = -p $section;

      $section->cut;

     });

    ok -p $x eq <<END;
  <x>
    <topicref href="0">
      <topicref href="1">
        <topicref href="2"/>
        <topicref href="3"/>
      </topicref>
      <topicref href="4">
        <topicref href="5"/>
      </topicref>
    </topicref>
  </x>
  END

    ok  nn(dump({map {$_=>nn($file{$_})} keys %file})) eq nn(dump(

     {"0" => "<section level=\"1\">N  <h1>h1</h1>NN  H1NN</section>N",

      "1" => "<section level=\"2\">N  <h2>h2</h2>NN  H2NN</section>N",

      "2" => "<section level=\"3\">N  <h3>h3</h3>NN  H3NN</section>N",

      "3" => "<section level=\"3\">N  <h3>h3</h3>NN  H3NN</section>N",

      "4" => "<section level=\"2\">N  <h2>h2</h2>NN  H2NN</section>N",

      "5" => "<section level=\"4\">N  <h4>h4</h4>NN  H4NN</section>N",

divideDocumentIntoSections($$)

Divide a parse tree into sections by moving non section tags into their corresponding section so that the section tags expand until they are contiguous. The sections are then cut out by applying the specified sub to each section tag in the parse tree. The specified sub will receive the containing topicref and the section to be cut out as parameters allowing a reference to the cut out section to be inserted into the topicref.

     Parameter  Description
  1  $node      Parse tree
  2  $cutSub    Cut out sub

Example:

   {my $x = Data::Edit::Xml::new(<<END);
  <x>
  <h1>h1</h1>
    H1
  <h2>h2</h2>
    H2
  <h3>h3</h3>
    H3
  <h3>h3</h3>
    H3
  <h2>h2</h2>
    H2
  <h4>h4</h4>
    H4
  </x>
  END

  $x->htmlHeadersToSections;

    $x->divideDocumentIntoSections(sub

     {my ($topicref, $section) = @_;

      my $file = keys %file;

      $topicref->href = $file;

      $file{$file} = -p $section;

      $section->cut;

     });

    ok -p $x eq <<END;
  <x>
    <topicref href="0">
      <topicref href="1">
        <topicref href="2"/>
        <topicref href="3"/>
      </topicref>
      <topicref href="4">
        <topicref href="5"/>
      </topicref>
    </topicref>
  </x>
  END

    ok  nn(dump({map {$_=>nn($file{$_})} keys %file})) eq nn(dump(

     {"0" => "<section level=\"1\">N  <h1>h1</h1>NN  H1NN</section>N",

      "1" => "<section level=\"2\">N  <h2>h2</h2>NN  H2NN</section>N",

      "2" => "<section level=\"3\">N  <h3>h3</h3>NN  H3NN</section>N",

      "3" => "<section level=\"3\">N  <h3>h3</h3>NN  H3NN</section>N",

      "4" => "<section level=\"2\">N  <h2>h2</h2>NN  H2NN</section>N",

      "5" => "<section level=\"4\">N  <h4>h4</h4>NN  H4NN</section>N",

ditaParagraphToNote($$)

Convert all nodes to <note> if the paragraph starts with 'Note:', optionally wrapping the content of the <note> with a

     Parameter                     Description
  1  $node                         Parse tree
  2  $wrapNoteContentWithParagaph  Wrap the <note> content with a <p> if true

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <p> Note: see over for details.</p>
  </a>
  END

    $a->ditaParagraphToNote(1);

    ok -p $a eq <<END;
  <a>
    <note>
      <p>See over for details.</p>
    </note>
  </a>
  END

wordStyles($)

Extract style information from a parse tree representing a word document.

     Parameter  Description
  1  $x         Parse tree

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
   <text:list-style style:name="aa">
     <text:list-level-style-bullet text:level="2"/>
   </text:list-style>
  </a>
  END

    my $styles = $a->wordStyles;

    is_deeply $styles, {bulletedList=>{aa=>{2=>1}}};

htmlTableToDita($)

Convert an html table to a Dita table.

     Parameter  Description
  1  $table     Html table node

Example:

   {my $a = Data::Edit::Xml::new(<<END);
   <table>
     <thead>
      <tr>
         <th>Month</th>
         <th>Savings</th>
         <th>Phone</th>
         <th>Comment</th>
      </tr>
     </thead>
     <tbody>
      <tr>
         <td>January</td>
         <td>100</td>
         <td>555-1212</td>
      </tr>
      <tr>
         <td>February</td>
         <td>80</td>
      </tr>
     </tbody>
  </table>
  END

    $a->htmlTableToDita;

    ok -p $a eq <<END;
  <table>
    <tgroup cols="4">
      <colspec colname="c1" colnum="1" colwidth="1*"/>
      <colspec colname="c2" colnum="2" colwidth="1*"/>
      <colspec colname="c3" colnum="3" colwidth="1*"/>
      <colspec colname="c4" colnum="4" colwidth="1*"/>
      <thead>
        <row>
          <entry>Month</entry>
          <entry>Savings</entry>
          <entry>Phone</entry>
          <entry>Comment</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry>January</entry>
          <entry>100</entry>
          <entry nameend="c4" namest="c3">555-1212</entry>
        </row>
        <row>
          <entry>February</entry>
          <entry nameend="c4" namest="c2">80</entry>
        </row>
      </tbody>
    </tgroup>
  </table>
  END

Debug

Debugging methods

printAttributes($)

Print the attributes of a node.

     Parameter  Description
  1  $node      Node whose attributes are to be printed.

Example:

   {my $x = Data::Edit::Xml::new(my $s = <<END);
  <a no="1" word="first"/>
  END

    ok $x->printAttributes eq qq( no="1" word="first");

printNode($)

Print the tag and attributes of a node.

     Parameter  Description
  1  $node      Node to be printed.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c id="42" match="mm"/>
    </b>
    <d>
      <e/>
    </d>
  </a>
  END

    ok $c->printNode eq q(c id="42" match="mm");

goFish($@)

A debug version of go that returns additional information explaining any failure to reach the node identified by the path.

Returns ([reachable tag...], failing tag, [possible tag...]) where:

reachable tag: the path elements successfully traversed;
failing tag: the failing element;
possible tag: the possibilities at the point where the path failed if it failed else undef.

Parameters:

     Parameter  Description
  1  $node      Node
  2  @path      Search specification.

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c>
        <d/>
      </c>
      <c/>
    </b>
    <b/>
  </a>
  END

      my ($good, $fail, $possible) = $a->goFish(qw(b c D));

      ok  $fail eq q(D);

      is_deeply $good,     [qw(b c)];

      is_deeply $possible, [q(d)];

Compression

Read and write files of compressed xml. These methods provide a compact, efficient way to store and retrieve parse trees to/from files.

writeCompressedFile($$)

Write the parse tree starting at $node as compressed xml to the specified $file. Use readCompressedFile to read the $file.

     Parameter  Description
  1  $node      Parse tree node
  2  $file      File to write to.

Example:

    my $a = Data::Edit::Xml::new(q(<a>).(q(<b>𝝱</b>)x1e3).q(</a>));

    my $file = $a->writeCompressedFile(q(zzz.xml.zip));

    my $A = readCompressedFile($file);

    ok $a->equals($A);

readCompressedFile($)

Read the specified $file containing compressed xml and return the root node. Use writeCompressedFile to write the $file.

     Parameter  Description
  1  $file      File to read.

Example:

    my $a = Data::Edit::Xml::new(q(<a>).(q(<b>𝝱</b>)x1e3).q(</a>));

    my $file = $a->writeCompressedFile(q(zzz.xml.zip));

    my $A = readCompressedFile($file);

    ok $a->equals($A);

This is a static method and so should be invoked as:

  Data::Edit::Xml::readCompressedFile

Autoload

Allow methods with constant parameters to be called as method_p1_p2...(variable parameters) whenever it is easier to type underscores than (qw()).

AUTOLOAD()

Allow methods with constant parameters to be called as method_p1_p2...(variable parameters) whenever it is easier to type underscores than (qw()).

Example:

   {my $a = Data::Edit::Xml::new(<<END);
  <a>
    <b>
      <c/>
    </b>
  </a>
  END

    my ($c, $b) = $a->byList;

    ok  $c->at_c_b_a;

    ok !$c->at_b;

    ok  -t $c->change_d_c_b eq q(d);

    ok !   $c->change_d_b;

  if (1)
   {my $a = Data::Edit::Xml::new(<<END);
  <a><b><c/><d/><e/><f/></b></a>
  END

    ok -t $a->first_b__first_c__next__next_e__next eq q(f);
    ok   !$a->first_b__first_c__next__next_f;
   }

Private Methods

tree($$)

Build a tree representation of the parsed XML which can be easily traversed to look for things.

     Parameter  Description
  1  $parent    The parent node
  2  $parse     The remaining parse

disconnectLeafNode($)

Remove a leaf node from the parse tree and make it into its own parse tree.

     Parameter  Description
  1  $node      Leaf node to disconnect.

reindexNode($)

Index the children of a node so that we can access them by tag and number.

     Parameter  Description
  1  $node      Node to index.

indexNode($)

Merge multiple text segments and set parent and parser after changes to a node

     Parameter  Description
  1  $node      Node to index.

normalizeWhiteSpace($)

Normalize white space, remove comments DOCTYPE and xml processors from a string

     Parameter  Description
  1  $string    String to normalize

This is a static method and so should be invoked as:

  Data::Edit::Xml::normalizeWhiteSpace

prettyStringEnd($)

Return a readable string representing a node of a parse tree and all the nodes below it as a here document

     Parameter  Description
  1  $node      Start node

byX2($$@)

Post-order traversal of a parse tree or sub tree calling the specified sub within eval{} at each node and returning the specified starting node. The sub is passed references to the current node and all of its ancestors. The value of the current node is also made available via $_.

     Parameter  Description
  1  $node      Starting node
  2  $sub       Sub to call
  3  @context   Accumulated context.

byX22($$@)

     Parameter  Description
  1  $node      Starting node
  2  $sub       Sub to call
  3  @context   Accumulated context.

downX2($$@)

Pre-order traversal of a parse tree or sub tree calling the specified sub within eval{} at each node and returning the specified starting node. The sub is passed references to the current node and all of its ancestors. The value of the current node is also made available via $_.

     Parameter  Description
  1  $node      Starting node
  2  $sub       Sub to call
  3  @context   Accumulated context.

downX22($$@)

Pre-order traversal down through a parse tree or sub tree calling the specified sub within eval{} at each node and returning the specified starting node. The sub is passed references to the current node and all of its ancestors. The value of the current node is also made available via $_.

     Parameter  Description
  1  $node      Starting node
  2  $sub       Sub to call for each sub node
  3  @context   Accumulated context.

atPositionMatch($$)

Confirm that a string matches a match expression.

     Parameter  Description
  1  $tag       Starting node
  2  $match     Ancestry.

numberNode($)

Ensure that the specified $node has a number.

     Parameter  Description
  1  $node      Node

createRequiredCleanUp($$)

Create a required clean up node

     Parameter  Description
  1  $node      Node
  2  $text      Clean up message

ditaMergeListsOnce($)

Merge the specified $node with the preceding or following list or steps or substeps if possible and return the specified $node regardless.

     Parameter  Description
  1  $node      Node

ditaAddPadEntriesToRows($$)

Adding padding entries to a table to make sure every row has the same number of entries

     Parameter  Description
  1  $table     Table node
  2  $nEntries  Number of entries

topicTypeAndBody($)

Topic type and corresponding body.

     Parameter  Description
  1  $type      Type from qw(bookmap concept reference task)

getSectionHeadingLevel($)

Get the heading level from a section tag.

     Parameter  Description
  1  $o         Node

printAttributesReplacingIdsWithLabels($)

Print the attributes of a node replacing the id with the labels.

     Parameter  Description
  1  $node      Node whose attributes are to be printed.

printAttributesExtendingIdsWithLabels($)

Print the attributes of a node extending the id with the labels.

     Parameter  Description
  1  $node      Node whose attributes are to be printed.

checkParentage($)

Check the parent pointers are correct in a parse tree.

     Parameter  Description
  1  $x         Parse tree.

checkParser($)

Check that every node has a parser.

     Parameter  Description
  1  $x         Parse tree.

nn($)

Replace new lines in a string with N to make testing easier.

     Parameter  Description
  1  $s         String.

Synonyms

firstLeaf is a synonym for downWhileFirst - Move down from the specified $node as long as each lower node is a first node.

lastLeaf is a synonym for downWhileLast - Move down from the specified $node as long as each lower node is a last node.

mnt is a synonym for matchesNextTags - Return the specified b<$node> if the siblings following the specified $node match the specified <@tags> else return undef.

mpt is a synonym for matchesPrevTags - Return the specified b<$node> if the siblings prior to the specified $node match the specified <@tags> else return undef.

oat is a synonym for overAllTags - Return the specified b<$node> if all of it's child nodes match the specified <@tags> else return undef.

oft is a synonym for overFirstTags - Return the specified b<$node> if the first of it's child nodes match the specified <@tags> else return undef.

olt is a synonym for overLastTags - Return the specified b<$node> if the last of it's child nodes match the specified <@tags> else return undef.

Index

1 above - Return the first node if the first node is above the second node optionally checking that the first node is in the specified context otherwise return undef

2 abovePath - Return the nodes along the path from the first node down to the second node when the first node is above the second node else return ().

3 addConditions - Add conditions to a node and return the node.

4 addFirst - Add a new node first below the specified $node and return the new node unless a node with that tag already exists in which case return the existing $node.

5 addFirstAsText - Add a new text node first below the specified $node and return the new node unless a text node already exists there and starts with the same text in which case return the existing $node.

6 addLabels - Add the named labels to the specified $node and return the number of labels added.

7 addLast - Add a new node last below the specified $node and return the new node unless a node with that tag already exists in which case return the existing $node.

8 addLastAsText - Add a new text node last below the specified $node and return the new node unless a text node already exists there and ends with the same text in which case return the existing $node.

9 addNext - Add a new node next to the specified $node and return the new node unless a node with that tag already exists in which case return the existing $node.

10 addNextAsText - Add a new text node after the specified $node and return the new node unless a text node already exists there and starts with the same text in which case return the existing $node.

11 addPrev - Add a new node before the specified $node and return the new node unless a node with that tag already exists in which case return the existing $node.

12 addPrevAsText - Add a new text node before the specified $node and return the new node unless a text node already exists there and ends with the same text in which case return the existing $node.

13 addSingleChild - Wrap the content of a specified $node in a new node with the specified $tag and optional %attribute unless the content is already wrapped in a single child with the specified $tag.

14 addWrapWith - Wrap the specified $node with the specified tag if the node is not already wrapped with such a tag and return the new node unless a node with that tag already exists in which case return the existing $node.

15 adjacent - Return the first node if it is adjacent to the second node else undef.

16 after - Return the first node if it occurs after the second node in the parse tree optionally checking that the first node is in the specified context or else undef if the node is above, below or before the target.

17 allConditions - Return the node if it has all of the specified conditions, else return undef

18 an - Return the next node if the specified $node has the specified tag and the next node is in the specified context.

19 ancestry - Return a list containing: (the specified $node, its parent, its parent's parent etc.

20 anyCondition - Return the node if it has any of the specified conditions, else return undef

21 ap - Return the previous node if the specified $node has the specified tag and the previous node is in the specified context.

22 apn - Return (previous node, next node) if the previous and current nodes have the specified tags and the next node is in the specified context else return ().

23 at - Confirm that the specified $node has the specified ancestry and return the specified $node if it does else undef.

24 atOrBelow - Confirm that the node or one of its ancestors has the specified context as recognized by at and return the first node that matches the context or undef if none do.

25 atPositionMatch - Confirm that a string matches a match expression.

26 attr - Return the value of an attribute of the current node as an lvalue sub.

27 attrCount - Return the number of attributes in the specified $node, optionally ignoring the specified names from the count.

28 attributes - The attributes of the specified $node, see also: "Attributes".

29 attrs - Return the values of the specified attributes of the current node as a list

30 audience - Attribute audience for a node as an lvalue sub.

31 AUTOLOAD - Allow methods with constant parameters to be called as method_p1_p2.

32 before - Return the first node if it occurs before the second node in the parse tree optionally checking that the first node is in the specified context or else undef if the node is above, below or before the target.

33 below - Return the first node if the first node is below the second node optionally checking that the first node is in the specified context otherwise return undef

34 belowPath - Return the nodes along the path from the first node up to the second node when the first node is below the second node else return ().

35 bitsNodeTextBlank - Return a bit string that shows if there are any non text nodes, text nodes or blank text nodes under a node.

36 breakIn - Concatenate the nodes following and preceding the start node, unwrapping nodes whose tag matches the start node and return the start node.

37 breakInBackwards - Concatenate the nodes preceding the start node, unwrapping nodes whose tag matches the start node and return the start node in the manner of breakIn.

38 breakInForwards - Concatenate the nodes following the start node, unwrapping nodes whose tag matches the start node and return the start node in the manner of breakIn.

39 breakOut - Lift child nodes with the specified tags under the specified parent node splitting the parent node into clones and return the cut out original node.

40 by - Post-order traversal of a parse tree or sub tree calling the specified sub at each node and returning the specified starting node.

41 byList - Return a list of all the nodes at and below a specified $node in pre-order or the empty list if the $node is not in the optional context.

42 byReverse - Reverse post-order traversal of a parse tree or sub tree calling the specified sub at each node and returning the specified starting $node.

43 byReverseList - Return a list of all the nodes at and below a specified $node in reverse preorder or the empty list if the specified $node is not in the optional context.

44 byReverseX - Reverse post-order traversal of a parse tree or sub tree below the specified $node calling the specified sub within eval{} at each node and returning the specified starting $node.

45 byX - Post-order traversal of a parse tree calling the specified sub at each node as long as this sub does not die.

46 byX2 - Post-order traversal of a parse tree or sub tree calling the specified sub within eval{} at each node and returning the specified starting node.

47 byX22 - Post-order traversal of a parse tree or sub tree calling the specified sub within eval{} at each node and returning the specified starting node.

48 c - Return an array of all the nodes with the specified tag below the specified $node.

49 cdata - The name of the tag to be used to represent text - this tag must not also be used as a command tag otherwise the parser will confess.

50 change - Change the name of the specified $node, optionally confirming that the $node is in a specified context and return the $node.

51 changeAttr - Change the name of an attribute in the specified $node unless it has already been set and return the node.

52 changeAttributeValue - Apply a sub to the value of an attribute of the specified $node.

53 changeAttrValue - Change the name and value of an attribute in the specified $node unless it has already been set and return the node.

54 changeReasonCommentSelectionSpecification - Provide a specification to select change reason comments to be inserted as text into a parse tree.

55 changeText - If the specified $node is a text node in the specified context then the specified sub is passed the text of the node in $_, any changes to which are recorded in the text of the $node.

56 checkParentage - Check the parent pointers are correct in a parse tree.

57 checkParser - Check that every node has a parser.

58 class - Attribute class for a node as an lvalue sub.

59 clone - Return a clone of the parse tree optionally checking that the starting node is in a specified context: the parse tree is cloned without converting it to string and reparsing it so this method will not renew any nodes added as text.

60 commonAdjacentAncestors - Given two nodes, find a pair of adjacent ancestral siblings if such a pair exists else return ().

61 commonAncestor - Find the most recent common ancestor of the specified nodes or undef if there is no common ancestor.

62 concatenate - Concatenate two successive nodes and return the target node.

63 concatenateSiblings - Concatenate preceding and following nodes as long as they have the same tag as the specified $node and return the specified $node.

64 condition - Return the node if it has the specified condition and is in the optional context, else return undef

65 conditions - Conditional strings attached to a node, see "Conditions".

66 containsSingleText - Return the single text element below the specified $node else return undef.

67 content - Content of command: the nodes immediately below the specified $node in the order in which they appeared in the source text, see also "Contents".

68 contentAfter - Return a list of all the sibling nodes following the specified $node or an empty list if the specified $node is last or not in the optional context.

69 contentAfterAsTags - Return a string containing the tags of all the sibling nodes following the specified $node separated by single spaces or the empty string if the node is empty or undef if the node does not match the optional context.

70 contentAfterAsTags2 - Return a string containing the tags of all the sibling nodes following the specified $node separated by two spaces with a single space preceding the first tag and a single space following the last tag or the empty string if the node is empty or undef if the node does not match the optional context.

71 contentAsTags - Return a string containing the tags of all the child nodes of the specified $node separated by single spaces or the empty string if the node is empty or undef if the node does not match the optional context.

72 contentAsTags2 - Return a string containing the tags of all the child nodes of the specified $node separated by two spaces with a single space preceding the first tag and a single space following the last tag or the empty string if the node is empty or undef if the node does not match the optional context.

73 contentBefore - Return a list of all the sibling nodes preceding the specified $node or an empty list if the specified $node is last or not in the optional context.

74 contentBeforeAsTags - Return a string containing the tags of all the sibling nodes preceding the specified $node separated by single spaces or the empty string if the node is empty or undef if the node does not match the optional context.

75 contentBeforeAsTags2 - Return a string containing the tags of all the sibling nodes preceding the specified $node separated by two spaces with a single space preceding the first tag and a single space following the last tag or the empty string if the node is empty or undef if the node does not match the optional context.

76 contents - Return a list of all the nodes contained by the specified $node or an empty list if the node is empty or not in the optional context.

77 context - Return a string containing the tag of the starting node and the tags of all its ancestors separated by single spaces.

78 copyAttrs - Copy all the attributes of the source node to the target node, or, just the named attributes if the optional list of attributes to copy is supplied, overwriting any existing attributes in the target node and return the source node.

79 copyLabels - Copy all the labels from the source node to the target node and return the source node.

80 copyLabelsAndIdsInTree - Copy all the labels and ids in the source parse tree to the matching nodes in the target parse tree.

81 copyNewAttrs - Copy all the attributes of the source node to the target node, or, just the named attributes if the optional list of attributes to copy is supplied, without overwriting any existing attributes in the target node and return the source node.

82 count - Return the count of the number of instances of the specified tags under the specified $node, either by tag in array context or in total in scalar context.

83 countAttrNames - Return a reference to a hash showing the number of instances of each attribute on and below the specified $node.

84 countAttrNamesOnTagExcluding - Count the number of attributes owned by the specified $node that are not in the specified list.

85 countAttrValues - Return a reference to a hash showing the number of instances of each attribute value on and below the specified $node.

86 countLabels - Return the count of the number of labels at a node.

87 countOutputClasses - Count instances of outputclass attributes

88 countTagNames - Return a reference to a hash showing the number of instances of each tag on and below the specified $node.

89 countTags - Count the number of tags in a parse tree.

90 crc - Insert a comment consisting of a code and an optional reason as text into the parse tree to indicate the location of changes to the parse tree.

91 createPatch - Create a patch that moves the source parse tree to the target parse tree node as long as they have the same tag and id structure with each id being unique.

92 createRequiredCleanUp - Create a required clean up node

93 cut - Cut out the specified $node so that it can be reinserted else where in the parse tree.

94 data - A hash added to the node for use by the programmer during transformations.

95 Data::Edit::Xml::Patch::install - Replay a patch created by createPatch against a parse tree that has the same tag and id structure with each id being unique.

96 deleteAttr - Delete the named attribute in the specified $node, optionally check its value first, return the node regardless.

97 deleteAttrs - Delete the specified attributes of the specified $node without checking their values and return the node.

98 deleteConditions - Delete conditions applied to a node and return the node.

99 deleteContent - Delete the content of the specified $node.

100 deleteLabels - Delete the specified labels in the specified $node or all labels if no labels have are specified and return that node.

101 depth - Returns the depth of the specified $node, the depth of a root node is zero.

102 diff - Return () if the dense string representations of the two nodes are equal, else up to the first N (default 16) characters of the common prefix before the point of divergence and the remainder of the string representation of each node from the point of divergence.

103 disconnectLeafNode - Remove a leaf node from the parse tree and make it into its own parse tree.

104 disordered - Return the first node that is out of the specified order when performing a pre-ordered traversal of the parse tree.

105 ditaAddColSpecToTgroup - Add the specified $number of column specification to a specified $tgroup which does not have any already.

106 ditaAddPadEntriesToRows - Adding padding entries to a table to make sure every row has the same number of entries

107 ditaFixTableColSpec - Improve the specified $table by making obvious improvements.

108 ditaListToSteps - Change the specified $node to steps and its contents to cmd\step optionally only in the specified context.

109 ditaListToStepsUnordered - Change the specified $node to steps-unordered and its contents to cmd\step optionally only in the specified context.

110 ditaListToSubSteps - Change the specified $node to substeps and its contents to cmd\step optionally only in the specified context.

111 ditaMaximumNumberOfEntriesInARow - Return the maximum number of entries in the rows of the specified $table or undef if not a table.

112 ditaMergeLists - Merge the specified $node with the preceding or following list or steps or substeps if possible and return the specified $node regardless.

113 ditaMergeListsOnce - Merge the specified $node with the preceding or following list or steps or substeps if possible and return the specified $node regardless.

114 ditaObviousChanges - Make obvious changes to a parse tree to make it look more like Dita.

115 ditaOrganization - Set the dita organization field in the xml headers, set by default to OASIS.

116 ditaParagraphToNote - Convert all nodes to <note> if the paragraph starts with 'Note:', optionally wrapping the content of the <note> with a

117 ditaPrettyPrintWithHeaders - Add xml headers for the dita document type indicated by the specified parse tree to a pretty print of the parse tree.

118 ditaStepsToList - Change the specified $node to ol and its cmd\step content to li optionally only in the specified context.

119 ditaTopicHeaders - Add xml headers for the dita document type indicated by the specified parse tree

120 divideDocumentIntoSections - Divide a parse tree into sections by moving non section tags into their corresponding section so that the section tags expand until they are contiguous.

121 down - Pre-order traversal down through a parse tree or sub tree calling the specified sub at each node and returning the specified starting node.

122 downReverse - Reverse pre-order traversal down through a parse tree or sub tree calling the specified sub at each node and returning the specified starting node.

123 downReverseX - Reverse pre-order traversal down through a parse tree or sub tree calling the specified sub within eval{} at each node and returning the specified starting node.

124 downWhileFirst - Move down from the specified $node as long as each lower node is a first node.

125 downWhileLast - Move down from the specified $node as long as each lower node is a last node.

126 downWhileSingleChild - Move down from the specified $node as long as it has a single child else return undef.

127 downX - Pre-order traversal of a parse tree calling the specified sub at each node as long as this sub does not die.

128 downX2 - Pre-order traversal of a parse tree or sub tree calling the specified sub within eval{} at each node and returning the specified starting node.

129 downX22 - Pre-order traversal down through a parse tree or sub tree calling the specified sub within eval{} at each node and returning the specified starting node.

130 equals - Return the first node if the two parse trees have identical representations via string, else undef.

131 equalsIgnoringAttributes - Return the first node if the two parse trees have identical representations via string if the specified attributes are ignored, else undef.

132 errorsFile - Error listing file.

133 expandIncludes - Expand the includes mentioned in a parse tree: any tag that ends in include is assumed to be an include directive.

134 findByForestNumber - Find the node with the specified forest number as made visible on the id attribute by prettyStringNumbered in the parse tree containing the specified $node and return the found node or undef if no such node exists.

135 findByNumber - Find the node with the specified number as made visible by prettyStringNumbered in the parse tree containing the specified $node and return the found node or undef if no such node exists.

136 findByNumbers - Find the nodes with the specified numbers as made visible by prettyStringNumbered in the parse tree containing the specified $node and return the found nodes in a list with undef for nodes that do not exist.

137 first - Return the first node below the specified $node optionally checking its context.

138 firstBy - Return a list of the first instance of each specified tag encountered in a post-order traversal from the specified $node or a hash of all first instances if no tags are specified.

139 firstContextOf - Return the first node encountered in the specified context in a depth first post-order traversal of the parse tree.

140 firstDown - Return a list of the first instance of each specified tag encountered in a pre-order traversal from the specified $node or a hash of all first instances if no tags are specified.

141 firstIn - Return the first child node matching one of the named tags under the specified parent node.

142 firstInIndex - Return the specified $node if it is first in its index and optionally at the specified context else undef

143 firstn - Return the $n'th first node below the specified $node optionally checking its context or undef if there is no such node.

144 firstNot - Return the first child node that does not match any of the named @tags under the specified parent $node.

145 firstOf - Return an array of the nodes that are continuously first under their specified parent node and that match the specified list of tags.

146 firstSibling - Return the first sibling of the specified $node in the optional context else undef

147 firstText - Return the first node if it is a text node otherwise undef

148 firstTextMatches - Return the first node under the specified $node if: it is a text mode; its text matches the specified regular expression; the specified $node is in the optional specified context.

149 firstUntil - Go first from the specified $node and continue deeper until a first child node matches the specified @context or return undef if there is no such node.

150 firstWhile - Go first from the specified $node and continue deeper as long as each first child node matches one of the specified @tags.

151 forestNumbers - Index to node by forest number as set by numberForest.

152 forestNumberTrees - Number the ids of the nodes in a parse tree in pre-order so they are numbered in the same sequence that they appear in the source.

153 from - Return a list consisting of the specified node and its following siblings optionally including only those nodes that match one of the tags in the specified list.

154 fromTo - Return a list of the nodes between the specified start and end nodes optionally including only those nodes that match one of the tags in the specified list.

155 getAttrs - Return a sorted list of all the attributes on the specified $node.

156 getLabels - Return the names of all the labels set on a node.

157 getSectionHeadingLevel - Get the heading level from a section tag.

158 go - Return the node reached from the specified $node via the specified path: (index position?)* where index is the tag of the next node to be chosen and position is the optional zero based position within the index of those tags under the current node.

159 goFish - A debug version of go that returns additional information explaining any failure to reach the node identified by the path.

160 guid - Attribute guid for a node as an lvalue sub.

161 howFar - Return how far the first node is from the second node along a path through their common ancestor.

162 howFarAbove - Return how far the first node is above the second node is or 0 if the first node is not strictly above the second node.

163 howFarBelow - Return how far the first node is below the second node is or 0 if the first node is not strictly below the second node.

164 howFirst - Return the depth to which the specified $node is first else 0.

165 howLast - Return the depth to which the specified $node is last else 0.

166 howOnlyChild - Return the depth to which the specified $node is an only child else 0.

167 href - Attribute href for a node as an lvalue sub.

168 htmlHeadersToSections - Position sections just before html header tags so that subsequently the document can be divided into sections.

169 htmlTableToDita - Convert an html table to a Dita table.

170 id - Attribute id for a node as an lvalue sub.

171 index - Return the index of the specified $node in its parent index.

172 indexes - Indexes to sub commands by tag in the order in which they appeared in the source text.

173 indexIds - Return a map of the ids at and below the specified $node.

174 indexNode - Merge multiple text segments and set parent and parser after changes to a node

175 input - Source of the parse if this is the parser root node.

176 inputFile - Source file of the parse if this is the parser root node.

177 inputString - Source string of the parse if this is the parser root node.

178 invert - Swap a parent and child node where the child is the only child of the parent and return the parent.

179 invertFirst - Swap a parent and child node where the child is the first child of the parent by placing the parent last in the child.

180 invertLast - Swap a parent and child node where the child is the last child of the parent by placing the parent first in the child.

181 isAllBlankText - Return the specified $node if the specified $node, optionally in the specified context, does not contain anything or if it does contain something it is all white space else return undef.

182 isBlankText - Return the specified $node if the specified $node is a text node, optionally in the specified context, and contains nothing other than white space else return undef.

183 isEmpty - Confirm that the specified $node is empty, that is: the specified $node has no content, not even a blank string of text.

184 isFirst - Return the specified $node if it is first under its parent and optionally has the specified context, else return undef

185 isFirstText - Return the specified $node if the specified $node is a text node, the first node under its parent and that the parent is optionally in the specified context, else return undef.

186 isFirstToDepth - Return the specified $node if it is first to the specified depth else return undef

187 isLast - Return the specified $node if it is last under its parent and optionally has the specified context, else return undef

188 isLastText - Return the specified $node if the specified $node is a text node, the last node under its parent and that the parent is optionally in the specified context, else return undef.

189 isLastToDepth - Return the specified $node if it is last to the specified depth else return undef

190 isOnlyChild - Return the specified $node if it is the only node under its parent ignoring any surrounding blank text.

191 isOnlyChildToDepth - Return the specified $node if it and its ancestors are only children to the specified depth else return undef.

192 isText - Return the specified $node if the specified $node is a text node, optionally in the specified context, else return undef.

193 labels - The labels attached to a node to provide addressability from other nodes, see: "Labels".

194 labelsInTree - Return a hash of all the labels in a tree

195 lang - Attribute lang for a node as an lvalue sub.

196 last - Return the last node below the specified $node optionally checking its context.

197 lastBy - Return a list of the last instance of each specified tag encountered in a post-order traversal from the specified $node or a hash of all last instances if no tags are specified.

198 lastContextOf - Return the last node encountered in the specified context in a depth first reverse pre-order traversal of the parse tree.

199 lastDown - Return a list of the last instance of each specified tag encountered in a pre-order traversal from the specified $node or a hash of all last instances if no tags are specified.

200 lastIn - Return the last child node matching one of the named tags under the specified parent node.

201 lastInIndex - Return the specified $node if it is last in its index and optionally at the specified context else undef

202 lastn - Return the $n'th last node below the specified $node optionally checking its context or undef if there is no such node.

203 lastNot - Return the last child node that does not match any of the named @tags under the specified parent $node.

204 lastOf - Return an array of the nodes that are continuously last under their specified parent node and that match the specified list of tags.

205 lastSibling - Return the last sibling of the specified $node in the optional context else undef

206 lastText - Return the last node if it is a text node otherwise undef

207 lastTextMatches - Return the last node under the specified $node if: it is a text mode; its text matches the specified regular expression; the specified $node is in the optional specified context.

208 lastUntil - Go last from the specified $node and continue deeper until a last child node matches the specified @context or return undef if there is no such node.

209 lastWhile - Go last from the specified $node and continue deeper as long as each last child node matches one of the specified @tags.

210 listConditions - Return a list of conditions applied to a node.

211 matchAfter - Confirm that the string representing the tags following the specified $node matches a regular expression where each pair of tags is separated by a single space.

212 matchAfter2 - Confirm that the string representing the tags following the specified $node matches a regular expression where each pair of tags have two spaces between them and the first tag is preceded by a single space and the last tag is followed by a single space.

213 matchBefore - Confirm that the string representing the tags preceding the specified $node matches a regular expression where each pair of tags is separated by a single space.

214 matchBefore2 - Confirm that the string representing the tags preceding the specified $node matches a regular expression where each pair of tags have two spaces between them and the first tag is preceded by a single space and the last tag is followed by a single space.

215 matchesNextTags - Return the specified b<$node> if the siblings following the specified $node match the specified <@tags> else return undef.

216 matchesPrevTags - Return the specified b<$node> if the siblings prior to the specified $node match the specified <@tags> else return undef.

217 matchesText - Returns an array of regular expression matches in the text of the specified $node if it is text node and it matches the specified regular expression and optionally has the specified context otherwise returns an empty array.

218 matchTree - Return a list of nodes that match the specified tree of match expressions, else () if one or more match expressions fail to match nodes in the tree below the specified start node.

219 mergeDuplicateChildWithParent - Merge a parent node with its only child if their tags are the same and their attributes do not collide other than possibly the id in which case the parent id is used.

220 moveAttrs - Move all the attributes of the source node to the target node, or, just the named attributes if the optional list of attributes to move is supplied, overwriting any existing attributes in the target node and return the source node.

221 moveLabels - Move all the labels from the source node to the target node and return the source node.

222 moveNewAttrs - Move all the attributes of the source node to the target node, or, just the named attributes if the optional list of attributes to copy is supplied, without overwriting any existing attributes in the target node and return the source node.

223 navtitle - Attribute navtitle for a node as an lvalue sub.

224 new - Create a new parse tree - call this method statically as in Data::Edit::Xml::new(file or string) to parse a file or string or with no parameters and then use "input", "inputFile", "inputString", "errorFile" to provide specific parameters for the parse, then call "parse" to perform the parse and return the parse tree.

225 newTag - Create a new non text node.

226 newText - Create a new text node.

227 newTree - Create a new tree.

228 next - Return the node next to the specified $node, optionally checking its context.

229 nextIn - Return the nearest sibling after the specified $node that matches one of the named tags or undef if there is no such sibling node.

230 nextn - Return the $n'th next node after the specified $node optionally checking its context or undef if there is no such node.

231 nextOn - Step forwards as far as possible from the specified $node while remaining on nodes with the specified tags.

232 nextText - Return the next node after the specified $node if it is a text node otherwise undef

233 nextTextMatches - Return the next node to the specified $node if: it is a text mode; its text matches the specified regular expression; the specified $node is in the optional specified context.

234 nextUntil - Go to the next sibling of the specified $node and continue forwards until the tag of a sibling node matches one of the specified @tags.

235 nextWhile - Go to the next sibling of the specified $node and continue forwards while the tag of each sibling node matches one of the specified @tags.

236 nn - Replace new lines in a string with N to make testing easier.

237 normalizeWhiteSpace - Normalize white space, remove comments DOCTYPE and xml processors from a string

238 not - Return the specified $node if it does not match any of the specified tags, else undef

239 number - Number of the specified $node, see findByNumber.

240 numbering - Last number used to number a node in this parse tree.

241 numberNode - Ensure that the specified $node has a number.

242 numbers - Nodes by number.

243 numberTree - Number the nodes in a parse tree in pre-order so they are numbered in the same sequence that they appear in the source.

244 numberTreesJustIds - Number the ids of the nodes in a parse tree in pre-order so they are numbered in the same sequence that they appear in the source.

245 opAt - <= : Check that a node is in the context specified by the referenced array of words.

246 opAttr - % : Get the value of an attribute of the specified $node.

247 opBy - x= : Traverse a parse tree in post-order.

248 opContents - @{} : nodes immediately below a node.

249 opCut - -- : Cut out a node.

250 opGo - >= : Search for a node via a specification provided as a reference to an array of words each number.

251 opNew - ** : create a new node from the text on the right hand side: if the text contains a non word character \W the node will be create as text, else it will be created as a tag

252 opPutFirst - >> : put a node or string first under a node and return the new node.

253 opPutFirstAssign - >>= : put a node or string first under a node.

254 opPutLast - << : put a node or string last under a node and return the new node.

255 opPutLastAssign - <<= : put a node or string last under a node.

256 opPutNext - > + : put a node or string after the specified $node and return the new node.

257 opPutNextAssign - += : put a node or string after the specified $node.

258 opPutPrev - < - : put a node or string before the specified $node and return the new node.

259 opPutPrevAssign - -= : put a node or string before the specified $node,

260 opString - -B: bitsNodeTextBlank

-b: isAllBlankText

-c: context

-e: prettyStringEnd

-f: first node

-g: pathString

-l: last node

-M: number

-o: contentAsTags

-p: prettyString

-s: string

-S : stringNode

-T : isText

-t : tag

-u: id

-W: unWrap

-w: stringQuoted

-x: prettyStringDitaHeaders

-X: cut

-z: prettyStringNumbered.

261 opUnwrap - ++ : Unwrap a node.

262 opWrapContentWith - * : Wrap content with a tag, returning the wrapping node.

263 opWrapWith - / : Wrap node with a tag, returning the wrapping node.

264 ordered - Return the first node if the specified nodes are all in order when performing a pre-ordered traversal of the parse tree else return undef.

265 otherprops - Attribute otherprops for a node as an lvalue sub.

266 outputclass - Attribute outputclass for a node as an lvalue sub.

267 over - Confirm that the string representing the tags at the level below the specified $node match a regular expression where each pair of tags is separated by a single space.

268 over2 - Confirm that the string representing the tags at the level below the specified $node match a regular expression where each pair of tags have two spaces between them and the first tag is preceded by a single space and the last tag is followed by a single space.

269 overAllTags - Return the specified b<$node> if all of it's child nodes match the specified <@tags> else return undef.

270 overFirstTags - Return the specified b<$node> if the first of it's child nodes match the specified <@tags> else return undef.

271 overLastTags - Return the specified b<$node> if the last of it's child nodes match the specified <@tags> else return undef.

272 parent - Parent node of the specified $node or undef if the parser root node.

273 parse - Parse input XML specified via: inputFile, input or inputString.

274 parser - Parser details: the root node of a tree is the parser node for that tree.

275 path - Return a list representing the path to a node from the root of the parse tree which can then be reused by go to retrieve the node as long as the structure of the parse tree has not changed along the path.

276 pathString - Return a string representing the path to the specified $node from the root of the parse tree.

277 position - Return the index of the specified $node in the content of the parent of the $node.

278 present - Return the count of the number of the specified tag types present immediately under a node or a hash {tag} = count for all the tags present under the node if no names are specified.

279 prettyString - Return a readable string representing a node of a parse tree and all the nodes below it.

280 prettyStringCDATA - Return a readable string representing a node of a parse tree and all the nodes below it with the text fields wrapped with <CDATA>.

281 prettyStringContent - Return a readable string representing all the nodes below a node of a parse tree.

282 prettyStringContentNumbered - Return a readable string representing all the nodes below a node of a parse tree with numbering added.

283 prettyStringDitaHeaders - Return a readable string representing the parse tree below the specified $node with appropriate headers as determined by ditaOrganization .

284 prettyStringEnd - Return a readable string representing a node of a parse tree and all the nodes below it as a here document

285 prettyStringNumbered - Return a readable string representing a node of a parse tree and all the nodes below it with a number attached to each tag.

286 prev - Return the node before the specified $node, optionally checking its context.

287 prevIn - Return the nearest sibling node before the specified $node which matches one of the named tags or undef if there is no such sibling node.

288 prevn - Return the $n'th previous node after the specified $node optionally checking its context or undef if there is no such node.

289 prevOn - Step backwards as far as possible while remaining on nodes with the specified tags.

290 prevText - Return the previous node if it is a text node otherwise undef

291 prevTextMatches - Return the previous node to the specified $node if: it is a text mode; its text matches the specified regular expression; the specified $node is in the optional specified context.

292 prevUntil - Go to the previous sibling of the specified $node and continue backwards until the tag of a sibling node matches one of the specified @tags.

293 prevWhile - Go to the previous sibling of the specified $node and continue backwards while the tag of each sibling node matches one of the specified @tags.

294 printAttributes - Print the attributes of a node.

295 printAttributesExtendingIdsWithLabels - Print the attributes of a node extending the id with the labels.

296 printAttributesReplacingIdsWithLabels - Print the attributes of a node replacing the id with the labels.

297 printNode - Print the tag and attributes of a node.

298 propagate - Propagate new attributes from nodes that match the specified tag to all their child nodes, then unwrap all the nodes that match the specified tag.

299 props - Attribute props for a node as an lvalue sub.

300 putFirst - Place a cut out or new node at the front of the content of the specified $node and return the new node.

301 putFirstAsText - Add a new text node first under a parent and return the new text node.

302 putFirstCut - Cut out the second node, place it first under the first node and return the second node.

303 putFirstRequiredCleanUp - Place a required cleanup tag first under a node and return the required clean up node.

304 putLast - Place a cut out or new node last in the content of the specified $node and return the new node.

305 putLastAsText - Add a new text node last under a parent and return the new text node.

306 putLastCut - Cut out the second node, place it last under the first node and return the second node.

307 putLastRequiredCleanUp - Place a required cleanup tag last under a node and return the required clean up node.

308 putNext - Place a cut out or new node just after the specified $node and return the new node.

309 putNextAsText - Add a new text node following the specified $node and return the new text node.

310 putNextCut - Cut out the second node, place it next after the first node and return the second node.

311 putNextRequiredCleanUp - Place a required cleanup tag after a node.

312 putPrev - Place a cut out or new node just before the specified $node and return the new node.

313 putPrevAsText - Add a new text node following the specified $node and return the new text node

314 putPrevCut - Cut out the second node, place it before the first node and return the second node.

315 putPrevRequiredCleanUp - Place a required cleanup tag before a node.

316 readCompressedFile - Read the specified $file containing compressed xml and return the root node.

317 reindexNode - Index the children of a node so that we can access them by tag and number.

318 renameAttr - Change the name of an attribute in the specified $node regardless of whether the new attribute already exists or not and return the node.

319 renameAttrValue - Change the name and value of an attribute in the specified $node regardless of whether the new attribute already exists or not and return the node.

320 renew - Returns a renewed copy of the parse tree, optionally checking that the starting node is in a specified context: use this method if you have added nodes via the "Put as text" methods and wish to traverse their parse tree.

321 replaceContentWith - Replace the content of a node with the specified nodes and return the replaced content

322 replaceContentWithMovedContent - Replace the content of a specified target node with the contents of the specified source nodes removing the content from each source node and return the target node.

323 replaceContentWithText - Replace the content of a node with the specified texts and return the replaced content

324 replaceSpecialChars - Replace < > " & with < > " & Larry Wall's excellent Xml parser unfortunately replaces < > " & etc.

325 replaceWith - Replace a node (and all its content) with a new node (and all its content) and return the new node.

326 replaceWithBlank - Replace a node (and all its content) with a new blank text node and return the new node.

327 replaceWithRequiredCleanUp - Replace a node with a required cleanup message and return the new node

328 replaceWithText - Replace a node (and all its content) with a new text node and return the new node.

329 requiredCleanUp - Replace a node with a required cleanup node around the text of the replaced node with special characters replaced by symbols.

330 restore - Return a parse tree from a copy saved in a file by save.

331 save - Save a copy of the parse tree to a file which can be restored and return the saved node.

332 set - Set the values of some attributes in a node and return the node.

333 setAttr - Set the values of some attributes in a node and return the node.

334 singleChild - Return the only child of the specified $node if the child is the only node under its parent ignoring any surrounding blank text and has the optional specified context, else return undef.

335 singleChildToDepth - Return the specified $node if it has single children to at least the specified depth else return undef.

336 string - Return a dense string representing a node of a parse tree and all the nodes below it.

337 stringContent - Return a string representing all the nodes below a node of a parse tree.

338 stringExtendingIdsWithLabels - Return a string representing the specified parse tree with the id attribute of each node extended by the Labels attached to each node.

339 stringNode - Return a string representing a node showing the attributes, labels and node number

340 stringQuoted - Return a quoted string representing a parse tree a node of a parse tree and all the nodes below it.

341 stringReplacingIdsWithLabels - Return a string representing the specified parse tree with the id attribute of each node set to the Labels attached to each node.

342 stringWithConditions - Return a string representing the specified $node of a parse tree and all the nodes below it subject to conditions to select or reject some nodes.

343 style - Attribute style for a node as an lvalue sub.

344 swap - Swap two nodes optionally checking that the first node is in the specified context and return the first node.

345 tag - Tag name for the specified $node, see also "Traversal" and "Navigation".

346 text - Text of the specified $node but only if it is a text node, i.

347 through - Traverse parse tree visiting each node twice calling the specified sub at each node and returning the specified starting node.

348 throughX - Traverse parse tree visiting each node twice calling the specified sub within eval{} at each node and returning the specified starting node.

349 to - Return a list of the sibling nodes preceding the specified node optionally including only those nodes that match one of the tags in the specified list.

350 tocNumbers - Table of Contents number the nodes in a parse tree.

351 topicTypeAndBody - Topic type and corresponding body.

352 tree - Build a tree representation of the parsed XML which can be easily traversed to look for things.

353 type - Attribute type for a node as an lvalue sub.

354 unwrap - Unwrap the specified $node by inserting its content into its parent at the point containing the specified $node and return the parent node.

355 unwrapContentsKeepingText - Unwrap all the non text nodes below the specified $node adding a leading and a trailing space to prevent unwrapped content from being elided and return the specified $node else undef if not in the optional context.

356 unwrapParentsWithSingleChild - Unwrap any immediate ancestors of the specified $node which have only a single child and return the specified $node regardless.

357 up - Return the parent of the current node optionally checking the context of the specified $node first or return undef if the specified $node is the root of the parse tree.

358 upn - Go up the specified number of levels from the specified $node and return the node reached or undef if there is no such node.

359 upThru - Go up the specified path from the specified $node returning the node at the top or undef if no such node exists.

360 upUntil - Return the nearest ancestral node to the specified $node that matches the specified @context or undef if there is no such node.

361 upUntilFirst - Move up from the specified $node until we reach the root or a first node.

362 upUntilIsOnlyChild - Move up from the specified $node until we reach the root or another only child.

363 upUntilLast - Move up from the specified $node until we reach the root or a last node.

364 upWhile - Go up one level from the specified $node and then continue up while each node matches on of the specified <@tags>.

365 upWhileFirst - Move up from the specified $node as long as each node is a first node or return undef if the specified $node is not a first node.

366 upWhileIsOnlyChild - Move up from the specified $node as long as each node is an only child or return undef if the specified $node is not an only child.

367 upWhileLast - Move up from the specified $node as long as each node is a last node or return undef if the specified $node is not a last node.

368 wordStyles - Extract style information from a parse tree representing a word document.

369 wrapContentWith - Wrap the content of the specified $node in a new node created from the specified <@tag> and %attributes: the specified $node then contains just the new node which, in turn, contains all the content of the specified $node.

370 wrapDown - Wrap the content of the specified $node in a sequence of new nodes forcing the original node up - deepening the parse tree - return the array of wrapping nodes.

371 wrapFrom - Wrap all the nodes from the $start node to the $end node with a new node created from the specified <@tag> and %attributes and return the new node.

372 wrapSiblingsAfter - If there are any siblings after the specified $node, wrap them with a new node created from the specified <@tag> and %attributes.

373 wrapSiblingsBefore - If there are any siblings before the specified $node, wrap them with a new node created from the specified <@tag> and %attributes.

374 wrapSiblingsBetween - If there are any siblings between the specified $nodes, wrap them with a new node created from the specified <@tag> and %attributes.

375 wrapTo - Wrap all the nodes from the $start node to the $end node with a new node created from the specified <@tag> and %attributes and return the new node.

376 wrapUp - Wrap the specified $node in a sequence of new nodes created from the specified @tags forcing the original node down - deepening the parse tree - return the array of wrapping nodes.

377 wrapWith - Wrap the specified $node in a new node created from the specified $tag and %attributes forcing the specified $node down - deepening the parse tree - return the new wrapping node.

378 writeCompressedFile - Write the parse tree starting at $node as compressed xml to the specified $file.

379 xmlHeader - Add the standard xml header to a string

Installation

This module is written in 100% Pure Perl and, thus, it is easy to read, comprehend, use, modify and install via cpan:

  sudo cpan install Data::Edit::Xml

Author

philiprbrenan@gmail.com

http://www.appaapps.com

Copyright

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

To install Data::Edit::Xml, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Data::Edit::Xml

CPAN shell

perl -MCPAN -e shell
install Data::Edit::Xml

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)