lib/Data/Edit/Xml.pm

filter: Statementstmt 90.0% 18 / 20 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 7 / 7 Podpod n/a totaltotal 92.5% 25 / 27 CC 1 SCAR 0.4
CC
1
Cov
90%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
↑ Summary
1 #!/usr/bin/perl -I/home/phil/perl/cpan/DitaValidate/lib/ -I/home/phil/perl/cpan/DataDFA/lib/ -I/home/phil/perl/cpan/DataNFA/lib/ -I/home/phil/perl/cpan/DataTableText/lib/
2 # Edit data held in the XML format.
3 # Philip R Brenan at gmail dot com, Appa Apps Ltd Inc, 2016-2019
4 #-------------------------------------------------------------------------------
5 # podDocumentation
6 # cd /home/phil/perl/cpan/DataEditXml/; perl Build.PL && perl Build test && sudo perl Build install
7 # perl -d:NYTProf -Ilib test.pl && nytprofhtml --open
8 # $source =~ s(\x{a0}) ( )gs; The no break space problem
9 # Do not line number if xtrf is already taken!
10 # Pretty print with line numbers so we can get out of adding line numbers to existing xml which is currently not reliable
11 # When deleting content should putFirstCut check that the cut node is not above the target node ?.
12 # add*asTree
13 # change wrap and other commands that use %attributes rather than @context to use @context
14 # swap c and cc
15 # root finds the root node possibly obviating the need for the parser attribute?
16 # Stop unwrap from confessing to being on the root node
17 # Parse DTDs so that we can separate a classification map from a conventional map
18 # #b means the method acts on one node and returns a string - its braceable
19  
20 package Data::Edit::Xml;
21 our $VERSION = 20201031;
22 1 ▶use v5.26;
Subroutine BEGIN: called CC=1 SCAR=0.0
23 1 ▶use warnings FATAL => qw(all);
Subroutine BEGIN: called CC=1 SCAR=0.0
24 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
25 1 ▶use Carp qw(confess cluck);
Subroutine BEGIN: called CC=1 SCAR=0.0
26 1 ▶use Data::Dump qw(dump);
Subroutine BEGIN: called CC=1 SCAR=0.0
27 1 ▶use Data::Table::Text qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
28 #se Dita::Validate;
29 0 ▶use XML::Parser; # https://metacpan.org/pod/XML::Parser
Subroutine BEGIN: called CC=1 SCAR=2.6
30 use Storable qw(dclone freeze retrieve store thaw);
31 use utf8;
32  
33 #D1 Construction # Create a parse tree, either by parsing a L<file or string|/file or string> B<or> L<node by node|/Node by Node> B<or> from another L<parse tree|/Parse tree>.
34  
35 #D2 File or String # Construct a parse tree from a file or a string.
36  
37 our $lastParseError; # The last parse error encountered
38  
39 sub new(;$@) #IS Create a new parse tree - call this method statically as in Data::Edit::Xml::new(file or string) to parse a file or string B<or> with no parameters and then use L</input>, L</inputFile>, L</inputString>, L</errorFile> to provide specific parameters for the parse, then call L</parse> to perform the parse and return the parse tree.
40 {my ($fileNameOrString, @options) = @_; # Optional file name or string from which to construct the parse tree, hash of other options.
41 shift @_ while @_ && ref($_[0]); # Remove any leading references to find the actual string or file to be parsed
42 my ($source, %options) = @_; # Assign parameters - the one higher up is for documentation only
43 checkKeys(\%options, # Check report options
44 {lineNumbers => <<'END',
45 Save the line number.column number at which tag starts and ends on
46 the xtrf attribute of each node if true.
47 END
48 input => <<'END',
49 Specifies the string or file name containing the source xml to be parsed if true
50 END
51 inputString => <<'END',
52 Specifies the string of xml to be parsed if true
53 END
54 inputFile => <<'END',
55 Specifies the name of the input file containing the source xml to be parsed if true.
56 END
57 errorsFile => <<'END',
58 Specifies the file to which any parse errors will be written to. By default this file is named: B<zzzParseErrors/out.data>.
59 END
60 });
61 if (@_)
62 {my $x = bless {input=>@_}; # Create L<XML> editor with a string or file
63 $x->parser = $x; # Parser root node
64 return $x->parse; # Parse
65 }
66 my $x = bless {}; # Create empty L<XML> editor
67 $x->parser = $x; # Parser root node
68 $x # Parser
69 }
70  
71 sub 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 L<confess>.
72 {'CDATA'
73 }
74  
75 sub reduceParseErroMessage($) #P Reduce the parse failure message to the bare essentials.
76 {my ($e) = @_; # Error message
77 if ($e =~ m((not well-formed.*?byte\s*\d+))is) {return $1}
78 $e # Return full message of it cannot be further reduced
79 }
80  
81 sub parse($) # Parse input L<XML> specified via: L<inputFile|/inputFile>, L<input|/input> or L<inputString|/inputString>.
82 {my ($parser) = @_; # Parser created by L</new>
83  
84 if (my $s = $parser->input) # Source to be parsed is a file or a string
85 {if ($s =~ /\n/s or !-e $s) # Parse as a string because it does not look like a file name
86 {$parser->inputString = $s;
87 }
88 else # Parse a file
89 {$parser->inputFile = $s;
90 $parser->inputString = readFile($s);
91 }
92 }
93 elsif (my $f = $parser->inputFile) # Source to be parsed is a file
94 {$parser->inputString = readFile($f);
95 }
96 elsif ($parser->inputString) {} # Source to be parsed is a string
97 else # Unknown string
98 {confess "Supply a string or file to be parsed";
99 }
100  
101 my $xmlParser = new XML::Parser(Style => 'Tree'); # Extend Larry Wall's excellent L<XML> parser
102 my $D = $parser->inputString; # String to be parsed
103 my $d = $parser->lineNumbers ? &addLineNumbers($D) : $D; # Add line numbers if requested
104 $d =~ s(&(?!(amp|gt|lt|quot|#x?\d+);)) (&amp;)gs; # Correct free floating ampersands
105  
106 my $x = eval {$xmlParser->parse($d)}; # Parse string
107 $lastParseError = reduceParseErroMessage($@); # Record any error
108  
109 if (!$x) # Error in parse: write a message to STDERR and to a file if possible
110 {my $f = $parser->inputFile ? "Source file is:\n". # Source details if a file
111 $parser->inputFile."\n" : '';
112 my $s = $lastParseError;
113 eval {confess "Parse failed at:\n"}; # Stack of parse failure
114 my $e = "$d\n$f\n$@\n$s\n"; # Error
115 # warn "Xml parse error: $e"; # Write a description of the error to STDERR before attempting to write to a file
116 my $badFile = $parser->errorsFile || # File name to write error analysis to
117 fullFileName(filePathExt(qw(zzzParseErrors out data)));
118 unlink $badFile if -e $badFile; # Remove existing errors file
119 writeFile($badFile, $e); # Write a description of the error to the errorsFile
120 confess "Xml parse error, see file:\n$badFile\n$s\n"; # Complain helpfully if parse failed
121 }
122  
123 $parser->tree($x); # Structure parse results as a tree
124  
125 if (my @c = @{$parser->content}) # Set additional attributes on root node
126 {confess "No XML" if !@c;
127 confess "More than one outer-most tag" if @c > 1;
128 my $c = $c[0];
129 $parser->tag = $c->tag;
130 $parser->attributes = $c->attributes;
131 $parser->content = $c->content;
132 $parser->parent = undef;
133 $parser->indexNode;
134 }
135  
136 $parser # Parse details
137 }
138  
139 sub tree($$) #P Build a tree representation of the parsed L<XML> which can be easily traversed to look for things.
140 {my ($parent, $parse) = @_; # The parent node, the remaining parse
141 while(@$parse)
142 {my $tag = shift @$parse; # Tag for node
143 my $node = bless {parser=>$parent->parser}; # New node
144 if ($tag eq cdata)
145 {confess cdata.' tag encountered'; # We use this tag for text and so it cannot be used as a user tag in the document
146 }
147 elsif ($tag eq '0') # Text
148 {my $s = shift @$parse;
149 if ($s !~ /\A\s*\Z/) # Ignore entirely blank strings
150 {$s = replaceSpecialChars($s); # Restore special characters in the text
151 $node->tag = cdata; # Save text. ASSUMPTION: CDATA is not used as a tag anywhere.
152 $node->text = $s;
153 push @{$parent->content}, $node; # Save on parents content list
154 }
155 }
156 else # Node
157 {my $children = shift @$parse;
158 my $attributes = shift @$children;
159 $node->tag = $tag; # Save tag
160 $_ = replaceSpecialChars($_) for values %$attributes; # Restore in text with L<XML> special characters
161 $node->attributes = $attributes; # Save attributes
162 push @{$parent->content}, $node; # Save on parents content list
163 $node->tree($children) if $children; # Add nodes below this node
164 }
165 }
166 $parent->indexNode; # Index this node
167 }
168  
169 sub addLineNumbers($) #P Add line numbers to the source
170 {my ($string) = @_; # Source string
171 my @s = split //, ($string =~ s(<!--linted:.*\Z) ()gsr); # Remove any trailing lint comments
172 my $state = 0; # 0 - outside any tag, 1 - inside a tag
173 my $Line = 1; # Current tag start position
174 my $Col = 0;
175 my $line = 1; # Current position
176 my $col = 0;
177 for my $i(keys @s) # Each input character
178 {my $c = $s[$i]; # current character
179 ++$col;
180 if ($c eq qq(\n)) # Line/column number
181 {++$line;
182 $col = 0;
183 }
184 elsif ($state == 0) # Looking for the start of a tag
185 {if ($c eq q(<) and ($s[$i+1]//'') =~ m(\A[^/?!]\Z)s) # Exclude non tags
186 {($Line, $Col) = ($line, $col); # Record start position
187 $state = 1; # Looking for end
188 }
189 }
190 elsif ($c eq q(>)) # At end of tag
191 {if ($state == 1) # Inside a tag
192 {my $m = join '', ' xtrf="', $Line, '.', $Col, ':', # Line number uses an increment
193 ($line == $Line ? q() : ($line-$Line).q(.)), $col, '"';
194 if (($s[$i-1]//'') ne q(/)) # Tag with content
195 {$s[$i] = $m.'>';
196 }
197 else # Tag with no content
198 {$s[$i-1] = $m.'/';
199 }
200 $state = 0; # Looking for the next tag
201 }
202 }
203 }
204 join '', @s # New source string
205 }
206  
207 #D2 Node by Node # Construct a parse tree node by node.
208  
209 sub newText($$) # Create a new text node.
210 {my (undef, $text) = @_; # Any reference to this package, content of new text node
211 my $node = bless {}; # New node
212 $node->parser = $node; # Root node of this parse
213 $node->tag = cdata; # Text node
214 $node->text = $text; # Content of node
215 $node # Return new non text node
216 }
217  
218 sub newTag($$%) # Create a new non text node.
219 {my (undef, $command, %attributes) = @_; # Any reference to this package, the tag for the node, attributes as a hash.
220 my $node = bless {}; # New node
221 $node->parser = $node; # Root node of this parse
222 $node->tag = $command; # Tag for node
223 $node->attributes = \%attributes; # Attributes for node
224 $node # Return new node
225 }
226  
227 sub newTree($%) # Create a new tree.
228 {my ($command, %attributes) = @_; # The name of the root node in the tree, attributes of the root node in the tree as a hash.
229 &newTag(undef, @_)
230 }
231  
232 sub dupTag($@) #C Create a new non text node by duplicating the tag of an existing node.
233 {my ($node, @context) = @_; # Node, optional context
234 return undef if @context and !$node->at(@context); # Not in specified context
235 my $new = bless {}; # New node
236 $new->parser = $node->parser; # Root node of this parse
237 $new->tag = $node->tag; # Tag for node
238 $new # Return new node
239 }
240  
241 sub disconnectLeafNode($) #P Remove a leaf node from the parse tree and make it into its own parse tree.
242 {my ($node) = @_; # Leaf node to disconnect.
243 $node->parent = undef; # No parent
244 $node->parser = $node; # Own parse tree
245 }
246  
247 sub reindexNode($) #P Index the children of a node so that we can access them by tag and number.
248 {my ($node) = @_; # Node to index.
249 delete $node->{indexes}; # Delete the indexes
250 for my $n($node->contents) # Index content
251 {push @{$node->indexes->{$n->tag}}, $n; # Indices to sub nodes
252 }
253 }
254  
255 sub indexNode($) #P Merge multiple text segments and set parent and parser after changes to a node
256 {my ($node) = @_; # Node to index.
257 return unless keys @{$node->{content}};
258 my @contents = @{$node->content}; # Contents of the node
259  
260 # eval {grep {$_->{tag} eq cdata} @contents};
261 # $@ and confess "$@\n";
262  
263 if ((grep {$_->{tag} eq cdata} @contents) > 1) # Make parsing easier for the user by concatenating successive text nodes - NB: this statement has been optimized
264 {my (@c, @t); # New content, pending intermediate texts list
265 for(@contents) # Each node under the current node
266 {if ($_->{tag} eq cdata) # Text node. NB: optimized
267 {push @t, $_; # Add the text node to pending intermediate texts list
268 }
269 elsif (@t == 1) # Non text element encountered with one pending intermediate text
270 {push @c, @t, $_; # Save the text node and the latest non text node
271 @t = (); # Empty pending intermediate texts list
272 }
273 elsif (@t > 1) # Non text element encountered with two or more pending intermediate texts
274 {my $t = shift @t; # Reuse the first text node
275 $t->text .= join '', map {$_->text} @t; # Concatenate the remaining text nodes
276 $_->disconnectLeafNode for @t; # Disconnect the remain text nodes as they are no longer needed
277 push @c, $t, $_; # Save the resulting text node and the latest non text node
278 @t = (); # Empty pending intermediate texts list
279 }
280 else {push @c, $_} # Non text node encountered without immediately preceding text
281 }
282  
283 if (@t == 0) {} # No action required if no pending text at the end
284 elsif (@t == 1) {push @c, @t} # Just one text node
285 else # More than one text node - remove leading and trailing blank text nodes
286 {my $t = shift @t; # Reuse the first text node
287 $t->text .= join '', map {$_->text} @t; # Concatenate the remaining text nodes
288 $_->disconnectLeafNode for @t; # Disconnect the remain text nodes as they are no longer needed
289 push @c, $t; # Save resulting text element
290 }
291  
292 @contents = @c; # The latest content of the node
293 $node->content = \@c; # Node contents with concatenated text elements
294 }
295  
296 my $parser = $node->parser; # Parser for this node
297 for(@contents) # Index content
298 {$_->{parent} = $node; # Point to parent
299 $_->{parser} = $parser; # Point to parser
300 }
301 }
302  
303 sub replaceSpecialChars($) #S Replace < > " & with &lt; &gt; &quot; &amp; Larry Wall's excellent L<Xml parser> unfortunately replaces &lt; &gt; &quot; &amp; 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.
304 {my ($string) = @_; # String to be edited.
305 $string =~ s/\&/&amp;/g; # At this point all & that prefix variables should have been expanded, so any that are left are are real &s which should be replaced with &amp;
306 $string =~ s/\</&lt;/gr =~ s/\>/&gt;/gr =~ s/\"/&quot;/gr # Replace the special characters that we can replace.
307 }
308  
309 sub undoSpecialChars($) #S Reverse the results of calling L<replaceSpecialChars|/replaceSpecialChars>.
310 {my ($string) = @_; # String to be edited.
311 $string =~ s/&amp;/\&/g; # At this point all & that prefix variables should have been expanded, so any that are left are are real &s which should be replaced with &amp;
312 $string =~ s/&lt;/\</gr =~ s/&gt;/\>/gr =~ s/&quot;/\"/gr # Replace the special characters that we can replace.
313 }
314  
315 #D2 Parse tree attributes # Attributes of a node in a parse tree. For instance the attributes associated with an L<XML> tag are held in the L<attributes|/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.
316  
317 genHash(__PACKAGE__, # L<XML> parser definition
318 content=>[], # Content of command: the nodes immediately below the specified B<$node> in the order in which they appeared in the source text, see also L</Contents>.
319 numbers=>[], # Nodes by number.
320 data=>{}, # 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 L<printed|/Print> methods and so can be used to add data to the L<parse|/parse> tree that will not be seen in any output L<XML> produced from the L<parse|/parse> tree.
321 attributes=>{}, # The attributes of the specified B<$node>, see also: L</Attributes>. The frequently used attributes: class, id, href, outputclass can be accessed by an L<lvalueMethod> method as in: $node->id = 'c1'.
322 conditions=>{}, # Conditional strings attached to a node, see L</Conditions>.
323 forestNumbers=>{}, # Index to node by forest number as set by L<numberForest|/numberForest>.
324 indexes=>{}, # Indexes to sub commands by tag in the order in which they appeared in the source text.
325 labels=>{}, # The labels attached to a node to provide addressability from other nodes, see: L</Labels>.
326 depthProfileLast=>undef, # The last known depth profile for this node as set by L<setDepthProfiles|/setDepthProfiles>.
327 errorsFile=>undef, # Error listing file. Use this parameter to explicitly set the name of the file that will be used to write any L<parse|/parse> errors to. By default this file is named: B<zzzParseErrors/out.data>.
328 inputFile=>undef, # Source file of the L<parse|/parse> if this is the L<parser|/parse> root node. Use this parameter to explicitly set the file to be L<parsed|/parse>.
329 input=>undef, # Source of the L<parse|/parse> if this is the L<parser|/parse> root node. Use this parameter to specify some input either as a string or as a file name for the L<parser|/parse> to convert into a L<parse|/parse> tree.
330 inputString=>undef, # Source string of the L<parse|/parse> if this is the L<parser|/parse> root node. Use this parameter to explicitly set the string to be L<parsed|/parse>.
331 lineNumbers=>undef, # If true then save the line number.column number at which tag starts and ends on the xtrf attribute of each node.
332 numbering=>undef, # Last number used to number a node in this L<parse|/parse> tree.
333 number=>undef, # Number of the specified B<$node>, see L<findByNumber|/findByNumber>.
334 parent=>undef, # Parent node of the specified B<$node> or B<undef> if the L<parser|/parse> root node. See also L</Traversal> and L</Navigation>. Consider as read only.
335 parser=>undef, # L<Parser|/parse> details: the root node of a tree is the L<parser|/parse> node for that tree. Consider as read only.
336 representationLast=>undef, # The last representation set for this node by one of: L<setRepresentationAsTagsAndText|/setRepresentationAsTagsAndText>.
337 tag=>undef, # Tag name for the specified B<$node>, see also L</Traversal> and L</Navigation>. Consider as read only.
338 text=>undef, # Text of the specified B<$node> but only if it is a text node otherwise B<undef>, i.e. the tag is cdata() <=> L</isText> is true.
339 );
340  
341 #D2 Parse tree # Construct a L<parse|/parse> tree from another L<parse|/parse> tree.
342  
343 sub renew($@) #C Returns a renewed copy of the L<parse|/parse> tree by first printing it and then re-parsing it, optionally checking that the starting node is in a specified context: use this method if you have added nodes via the L</"Put as text"> methods and wish to traverse their L<parse|/parse> tree.\mReturns the starting node of the new L<parse|/parse> tree or B<undef> if the optional context constraint was supplied but not satisfied.
344 {my ($node, @context) = @_; # Node to renew from, optional context
345 return undef if @context and !$node->at(@context); # Not in specified context
346 my $x = new($node->string); # Reconstruct parse tree from node
347 $x->inputFile = $node->root->inputFile; # Convey the input file name if present so that relative references can be resolved in the new parse tree
348 $x # Return new parse tree
349 }
350  
351 sub clone($) #C Return a clone of the entire L<parse|/parse> tree which is created using the fast L<Storable::dclone> method. The L<parse|/parse> tree is cloned without converting it to string and re-parsing it so this method will not L<renew|/renew> any nodes added L<as text|/Put as text>.\mReturns the starting node of the new L<parse|/parse> tree.
352 {my ($tree) = @_; # Parse tree
353 my $new = dclone($tree);
354 # $new->parent = undef;
355 $new->parser = $new;
356 $new->cut;
357 }
358  
359 sub equals($$) #Y Return the first node if the two L<parse|/parse> trees have identical representations via L<string|/string>, else B<undef>.
360 {my ($node1, $node2) = @_; # Parse tree 1, parse tree 2.
361 $node1->string eq $node2->string ? $node1 : undef # Test
362 }
363  
364 sub equalsIgnoringAttributes($$@) # Return the first node if the two L<parse|/parse> trees have identical representations via L<string|/string> if the specified attributes are ignored, else B<undef>.
365 {my ($node1, $node2, @attributes) = @_; # Parse tree 1, parse tree 2, attributes to ignore during comparison
366 my $p = $node1->clone; # Clone the parse trees so we can modify them
367 my $q = $node2->clone;
368 for my $x($p, $q) # Remove specified attributes from clones of parse trees
369 {$x->by(sub
370 {$_->deleteAttrs(@attributes);
371 })
372 }
373 $p->string eq $q->string ? $node1 : undef # Compare the reduced parse trees
374 }
375  
376 sub normalizeWhiteSpace($) #PS Normalize white space, remove comments DOCTYPE and L<XML> processors from a string
377 {my ($string) = @_; # String to normalize
378 $string =~ s(<\?.*?\?>) ( )gs; # Processors
379 $string =~ s(<!--.*?-->) ( )gs; # Comments
380 $string =~ s(<!DOCTYPE.+?>) ( )gs; # Doctype
381 $string =~ s(\s+) ( )gs; # White space
382 $string
383 }
384  
385 sub 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.
386 {my ($first, $second, $N) = @_; # First node, second node, maximum length of difference strings to return
387 $first = new($first) unless ref $first; # Auto vivify the first node if necessary
388 $second = new($second) unless ref $second; # Auto vivify the second node if necessary
389 $N //= 16;
390 my $a = normalizeWhiteSpace(-s $first); # Convert to normalized strings
391 my $b = normalizeWhiteSpace(-s $second);
392 return () if length($a) == length($b) and $a eq $b; # Equal strings
393  
394 my @a = split //, $a; # Split into characters
395 my @b = split //, $b;
396 my @c; # Common prefix
397 while(@a and @b and $a[0] eq $b[0]) # Remove equal prefix characters
398 {push @c, shift @a; shift @b; # Save common prefix
399 }
400  
401 $#a = $N-1 if $N and @a > $N; # Truncate remainder if necessary
402 $#b = $N-1 if $N and @b > $N;
403 if ($N) {shift @c while @c > $N}
404  
405 (join ('', @c), join('', @a), join('', @b)) # Return common prefix and diverging strings
406 }
407  
408 sub save($$) # Save a copy of the L<parse|/parse> tree to a file which can be L<restored|/restore> and return the saved node. This method uses L<Storable> which is fast but produces large files that do not compress well. Use L<writeCompressedFile|/writeCompressedFile> to produce smaller save files at the cost of more time.
409 {my ($node, $file) = @_; # Parse tree, file.
410 makePath($file);
411 store $node, $file;
412 $node
413 }
414  
415 sub restore($) #SY Return a L<parse|/parse> tree from a copy saved in a file by L<save|/save>.
416 {my ($file) = @_; # File
417 -e $file or confess "Cannot restore from a non existent file:\n$file";
418 retrieve $file
419 }
420  
421 sub expandIncludes($) #U Expand the includes mentioned in a L<parse|/parse> tree: any tag that ends in B<include> is assumed to be an include directive. The file to be included is named on the B<href> keyword. If the file to be included is a relative file name, i.e. it does not begin with B</> then this file is made absolute relative to the file from which this L<parse|/parse> tree was obtained.
422 {my ($x) = @_; # Parse tree
423 $x->by(sub # Look for include statements
424 {my ($o) = @_;
425 if ($o->at(qr(include\Z))) # Include statement
426 {my $href = $o->attr(q(href)); # Remove dots and slashes from front of file name
427 my $in = $x->inputFile;
428 my $file = absFromAbsPlusRel($in, $href);
429 my $i = eval{Data::Edit::Xml::new($file)}; # Parse the new source file
430  
431 if ($@) # Report any errors encountered in expansion
432 {confess "Failed to expand href $href in file $in\n$@";
433 }
434  
435 $i->expandIncludes; # Rescan for any internal includes
436 $o->replaceWith($i); # Replace include statement
437 }
438 });
439 }
440  
441 #D1 Print # Create a string representation of the L<parse|/parse> tree with optional selection of nodes via L<conditions|/Conditions>.\mNormally use the methods in L<Pretty|/Pretty> to format the L<XML> in a readable yet reparseable manner; use L<Dense|/Dense> string to format the L<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 L<file test operators|/opString> can also be conveniently used to print L<parse|/parse> trees in these formats.
442  
443 #D2 Pretty # Pretty print the L<parse|/parse> tree.
444  
445 sub prettyString($;$) #IU Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it. Or use L<-p|/opString> $node
446 {my ($node, $depth) = @_; # Start node, optional depth.
447 $depth //= 0; # Start depth if none supplied
448  
449 # return $node->text.($node->isLast ? q() : qq(\n)) if $node->isText; # Add a new line after contiguous blocks of text to offset next node
450  
451 if ($node->isText) # Text block
452 {my $t = $node->text =~ s( *\n) (\n)gsr; # Collapse spaces before new line
453 return $t if $node->isLast; # The following tag will deal with the new line
454 return $t.qq(\n) unless $t =~ m(\n\Z)s; # Separate from next tag with a new line
455 return $t; # Text already has a new line and so no additional separator required
456 }
457  
458 my $t = $node->tag; # Not text so it has a tag
459 my $content = $node->content; # Sub nodes
460 my $space = " "x($depth//0);
461 return $space.'<'.$t.$node->printAttributes.'/>'."\n" if !@$content; # No sub nodes
462  
463 my $s = $space.'<'.$t.$node->printAttributes.'>'. # Has sub nodes
464 ($node->first->isText ? '' : "\n"); # Continue text on the same line, otherwise place nodes on following lines
465 $s .= $_->prettyString($depth+1) for @$content; # Recurse to get the sub content
466 $s .= $node->last->isText ? ((grep{!$_->isText} @$content) # Continue text on the same line, otherwise place nodes on following lines
467 ? "\n$space": "") : $space;
468 my $r = $s . '</'.$t.'>'."\n"; # Closing tag
469 return $r if $depth; # Return from sub tree
470 $r =~ s(>\n( *[.,;:\)] *)) (>$1\n)gsr # Overall result moves some punctuation through one new line to be closer to its tag
471 =~ s(\n\s*\n) (\n)gsr # Remove blank lines
472 }
473  
474 sub prettyStringHtml2($$) #P Return a string of html representing a node of a L<parse|/parse> tree and all the nodes below it. Or use L<-p|/opString> $node
475 {my ($node, $depth) = @_; # Start node, optional depth.
476 $depth //= 0; # Start depth if none supplied
477  
478 if ($node->isText) # Text block
479 {my $t = # Wrap text in span on one line
480 qq(<span class="xmlText">)
481 .nws($node->text)
482 .qq(</span>);
483 return $t; # Text already has a new line and so no additional separator required
484 }
485  
486 my $t = qq(<span class="xmlTag">).$node->tag.q(</span>); # Not text so it has a tag
487 my $content = $node->content; # Sub nodes
488  
489 my $space = qq(<span class="xmlLineStartTag">) # Space before text
490 .("&nbsp;"x(4*($depth//0)))
491 .qq(</span>);
492  
493 return $space # No sub nodes
494 .q(<span class="xmlLt">&lt;</span>)
495 .$t
496 .$node->printAttributesHtml
497 .q(<span class="xmlSlashGt">/&gt;</span>)
498 ."\n" if !@$content;
499  
500 my $s = $space # Has sub nodes
501 .q(<span class="xmlLt">&lt;</span>)
502 .$t
503 .$node->printAttributesHtml
504 .q(<span class="xmlGt">&gt;</span>)
505 .($node->first->isText ? '' : "\n"); # Continue text on the same line, otherwise place nodes on following lines
506  
507 $s .= $_->prettyStringHtml2($depth+1) for @$content; # Recurse to get the sub content
508  
509 $s .= $node->last->isText ? ((grep{!$_->isText} @$content) # Continue text on the same line, otherwise place nodes on following lines
510 ? "\n$space": "") : $space;
511  
512 my $r = $s # Closing tag
513 .q(<span class="xmlLtSlash">&lt;/</span>)
514 .$t
515 .q(<span class="xmlGt">&gt;</span>)
516 ."\n";
517  
518 return $r if $depth; # Return from sub tree
519  
520 my $h = join "\n", map {qq(<div class="xmlLine">$_</div>)} split m/\n/, $r; # Wrap div around each line
521 qq($h\n)
522 }
523  
524 sub prettyStringHtml($@) # Return a string of L<html> representing a node of a L<parse|/parse> tree and all the nodes below it if the node is in the specified context.
525 {my ($node, @context) = @_; # Node, optional context
526 return undef if @context and !$node->at(@context); # Check optional context
527 prettyStringHtml2($node, 0); # Print as html
528 }
529  
530 sub prettyStringDitaHeaders($) #U Return a readable string representing the L<parse|/parse> tree below the specified B<$node> with appropriate headers. Or use L<-x|/opString> $node
531 {my ($node) = @_; # Start node
532 # cluck "Please use: ditaPrettyPrintWithHeaders...redirecting";
533 $node->ditaPrettyPrintWithHeaders
534 }
535  
536 sub prettyStringNumbered($;$) #U Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it with a L<number|/number> attached to each tag. The node numbers can then be used as described in L<Order|/Order> to monitor changes to the L<parse|/parse> tree.
537 {my ($node, $depth) = @_; # Start node, optional depth.
538 $depth //= 0; # Start depth if none supplied
539  
540 my $N = $node->number; # Node number if present
541  
542 if ($node->isText) # Text node
543 {my $n = $node->next;
544 my $s = !defined($n) || $n->isText ? '' : "\n"; # Add a new line after contiguous blocks of text to offset next node
545 return ($N ? "($N)" : '').$node->text.$s; # Number text
546 }
547  
548 my $t = $node->tag; # Number tag in a way which allows us to skip between start and end tags in L<Geany|http://www.geany.org> using the ctrl+up and ctrl+down arrows
549 my $i = $N && !defined($node->id) ? " id=\"$N\"" : ''; # Use id to hold tag
550 my $content = $node->content; # Sub nodes
551 my $space = " "x($depth//0);
552 return $space.'<'.$t.$i.$node->printAttributes.'/>'."\n" if !@$content; # No sub nodes
553  
554 my $s = $space.'<'.$t.$i.$node->printAttributes.'>'. # Has sub nodes
555 ($node->first->isText ? '' : "\n"); # Continue text on the same line, otherwise place nodes on following lines
556 $s .= $_->prettyStringNumbered($depth+1) for @$content; # Recurse to get the sub content
557 $s .= $node->last->isText ? ((grep{!$_->isText} @$content) # Continue text on the same line, otherwise place nodes on following lines
558 ? "\n$space": "") : $space;
559 my $r = $s . '</'.$t.'>'."\n"; # Closing tag
560 return $r if $depth; # Return from sub tree
561 $r =~ s(>\n( *[.,;:\)] *)) (>$1\n)gsr # Overall result moves some punctuation through one new line to be closer to its tag
562 }
563  
564 sub prettyStringCDATA($;$) #U Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it with the text fields wrapped with <CDATA>...</CDATA>.
565 {my ($node, $depth) = @_; # Start node, optional depth.
566 $depth //= 0; # Start depth if none supplied
567  
568 if ($node->isText) # Text node
569 {my $n = $node->next;
570 my $s = !defined($n) || $n->isText ? '' : "\n"; # Add a new line after contiguous blocks of text to offset next node
571 return '<'.cdata.'>'.$node->text.'</'.cdata.'>'.$s;
572 }
573  
574 my $t = $node->tag; # Not text so it has a tag
575 my $content = $node->content; # Sub nodes
576 my $space = " "x($depth//0);
577 return $space.'<'.$t.$node->printAttributes.'/>'."\n" if !@$content; # No sub nodes
578  
579 my $s = $space.'<'.$t.$node->printAttributes.'>'. # Has sub nodes
580 ($node->first->isText ? '' : "\n"); # Continue text on the same line, otherwise place nodes on following lines
581 $s .= $_->prettyStringCDATA($depth+2) for @$content; # Recurse to get the sub content
582 $s .= $node->last->isText ? ((grep{!$_->isText} @$content) # Continue text on the same line, otherwise place nodes on following lines
583 ? "\n$space": "") : $space;
584 my $r = $s . '</'.$t.'>'."\n"; # Closing tag
585 return $r if $depth; # Return from sub tree
586 $r =~ s(>\n( *[.,;:\)] *)) (>$1\n)gsr # Overall result moves some punctuation through one new line to be closer to its tag
587 }
588  
589 sub prettyStringEnd($) #PU Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it as a here document
590 {my ($node) = @_; # Start node
591 my $s = -p $node; # Pretty string representation
592 ' ok -p $x eq <<END;'. "\n".(-p $node). "\nEND" # Here document
593 }
594  
595 sub prettyStringContent($) #U Return a readable string representing all the nodes below a node of a L<parse|/parse> tree.
596 {my ($node) = @_; # Start node.
597 my $s = '';
598 $s .= $_->prettyString for $node->contents; # Recurse to get the sub content
599 $s
600 }
601  
602 sub prettyStringContentNumbered($) #U Return a readable string representing all the nodes below a node of a L<parse|/parse> tree with numbering added.
603 {my ($node) = @_; # Start node.
604 my $s = '';
605 $s .= $_->prettyStringNumbered for $node->contents; # Recurse to get the sub content
606 $s
607 }
608  
609 sub xmlHeader($) #S Add the standard L<XML> header to a string
610 {my ($string) = @_; # String to which a standard L<XML> header should be prefixed
611 <<END
612 <?xml version="1.0" encoding="UTF-8"?>
613 $string
614 END
615 }
616  
617 #D2 Html/Json # Represent the L<parse|/parse> tree using html or Json
618  
619 sub htmlTables($) # Return a string of html representing a L<parse|/parse> tree.
620 {my ($node) = @_; # Start node of parse tree
621  
622 my $bgColor = sub # Create a random background color
623 {join q(), q(bgcolor="#), (map {sprintf("%02x", $_)} @_), q(");
624 };
625  
626 my $idNumber = 0;
627 my $id = sub # Create the next id number
628 {++$idNumber
629 };
630  
631 my @actions = qw(dup rename cut paste unwrap wrap wrapContent);
632  
633 my @nodes;
634 my %count;
635 my @depth;
636 my @path;
637 my $height = 0;
638  
639 $node->down(sub # Map xml
640 {my ($n) = @_;
641 return if $n->isFirstText;
642 push @nodes, $n;
643 $count{$_}++ for @_;
644 push @path, join ' ', $n->path;
645 my $h = scalar @_;
646 push @depth, $h;
647 $height = max($height, $h);
648 });
649  
650 my @h = q(<html>); # Generated html
651  
652 push @h, qq(<table cellspacing="0" cellpadding="2">); # Create table
653 for my $i(keys @nodes)
654 {my $n = $nodes[$i];
655 my $tag = -t $n;
656 my $line = $i + 1;
657 my $rowspan = $count{$n};
658 my $colspan = $height-$depth[$i]+1;
659 my @color = map {int(rand()*255)} 1..3;
660 my $color = &$bgColor(map {127+$_/2} @color);
661 my $colorLight = &$bgColor(map {191+$_/4} @color);
662 my $click = join '',
663 q/onclick="mimClick(event)" path="/, $path[$i], q/"/;
664  
665 my ($i1, $i2, $i3, $i4, $i5, $i6, $i7) =
666 map
667 {qq( onmouseover="mimMouseOver(event)" onmouseout="mimMouseOut(event)").
668 qq( onkeydown="mimKeyDown(event)")
669 }
670 1..7;
671 push @h, qq(<tr><td $i1 $color $click align="right">$line</td>);
672 push @h, qq(<td $i2 $color $click rowspan="$rowspan" width="10px"></td>);
673 push @h, qq(<td $i3 $color $click colspan="$colspan" contentEditable="true">$tag</td>) if $colspan;
674  
675 if (my $t = $n->isText) # Text element
676 {push @h, qq(<td $i4 contenteditable="true" $colorLight>).$t->text.q(</td>);
677 }
678 elsif (my $T = $n->firstText) # Text element first below non text element
679 {push @h, qq(<td $i5 contenteditable="true" $colorLight>).$T->text.q(</td>);
680 }
681 elsif ($tag =~ m(\A(b|cmd|info|li|p)\Z)s)
682 {push @h, qq(<td $i6 contenteditable="true" $colorLight> </td>);
683 }
684 else
685 {push @h, qq(<td $i7></td>);
686 }
687 }
688 push @h, qq(</table>); # End of table
689  
690 push @h, <<END;
691 <script>
692  
693 function say() // Say strings
694 {console.log(Array.from(arguments).map(a=>a.toString()).join(''))
695 }
696  
697 var mimMouseOverLastColor;
698  
699 function mimMouseOver(event)
700 {const target = event.target;
701 mimMouseOverLastColor = target.style["background-color"];
702 target.style["background-color"] = "white";
703 }
704  
705 function mimMouseOut(event)
706 {const target = event.target;
707 target.style["background-color"] = mimMouseOverLastColor;
708 }
709  
710 function mimClick(event)
711 {console.log(event);
712 }
713  
714 function mimKeyDown(event)
715 {const target = event.target;
716 console.log(event.key+ " "+event.code);
717 event.preventDefault();
718  
719 if (event.code == "KeyD")
720 {alert("duplicate path "+target.getAttribute("path"));
721 }
722 else if (event.code == "KeyR")
723 {const response = prompt("Enter new name");
724 target.innerText = response;
725 }
726 else if (event.code == "KeyU")
727 {alert("unwrap path "+target.getAttribute("path"));
728 }
729 }
730  
731 </script>
732 </html>
733 END
734  
735 join '', map {qq($_\n)} @h
736 }
737  
738 sub jsonString2($) #P Return a Json representation of a parse tree
739 {my ($node) = @_; # Start node of parse tree
740  
741 my $n = {tag=>$node->tag, # New node
742 (keys(%{$node->attributes}) ? (attributes => $node->attributes) : ()),
743 ($node->isText ? (text => $node->text) : ())};
744  
745 for my $c($node->contents) # Add content, hoisting any initial text node to the text field.
746 {push @{$n->{contents}}, $c->jsonString2;
747 }
748  
749 $n
750 }
751  
752 sub jsonString($) #U Return a Json representation of a parse tree
753 {my ($node) = @_; # Start node of parse tree
754 encodeJson($node->jsonString2) =~ s(([\}\]],)) ($1\n)gsr; # Encode Perl to Json with some line breaks added.
755 }
756  
757 sub xmlToJson($;$) #S Return a Json string representing valid L<XML> contained in a file or string, optionally double escaping escape characters.
758 {my ($xml, $escape) = @_; # File name or string of valid html, double escape the escaped characters if true
759 ref($xml) and confess "Expected a string or a file name";
760 my $j = jsonString(new($xml)); # Json string
761 $j =~ s(\\) (\\\\)gs if $escape; # Escape if requested
762 $j
763 }
764  
765 sub jsonToXml2($) #P Convert a json string to an L<XML> parse tree
766 {my ($node) = @_; # Start node of parse tree
767 my $a = $$node{attributes}; # Attributes
768 my $n = bless {tag=>$$node{tag},(keys(%$a) ? (attributes => $a) : ())}; # Tag and attributes
769 $$n{text} = trim($$node{text}) if $$node{text}; # Avoid endless blank line expansion of text
770 push @{$$n{content}}, &jsonToXml2($_) for @{$$node{contents}}; # Add content
771 $n
772 }
773  
774 sub jsonToXml($) # Convert a json string representing an L<XML> parse tree into an L<XML> parse tree
775 {my ($json) = @_; # Json string
776 my $p = decodeJson($json); # Json represented as Perl
777 my $x = jsonToXml2($p); # Parse tree - enough to print
778 my $s = string($x); # Parse tree as string
779 new($s); # Recreate full parse tree from string
780 }
781  
782 #D2 Dense # Print the L<parse|/parse> tree densely for reuse by computers rather than humans.
783  
784 sub string($) #U Return a dense string representing a node of a L<parse|/parse> tree and all the nodes below it. Or use L<-s|/opString> B<$node>.
785 {my ($node) = @_; # Start node.
786 return $node->{text} if $node->{tag} eq cdata; # Text node
787 my $content = $node->content; # Sub nodes
788 my $attr = keys %{$node->{attributes}}; # Number of attributes
789  
790 return '<'.$node->{tag}. '/>'
791 if !@$content and !keys %{$node->{attributes}}; # No sub nodes or attributes
792  
793 return '<'.$node->{tag}.$node->printAttributes.'/>'
794 if !@$content; # No sub nodes
795  
796 join '', '<', $node->{tag}, $node->printAttributes, '>', # Has sub nodes
797 (map {$_->{tag} eq cdata ? $_->{text} : $_->string} @$content), # Recurse to get the sub content
798 '</', $node->{tag}, '>'
799 }
800  
801 sub stringAsMd5Sum($) #U Return the L<md5> of the dense L<string|/string> representing a node of a L<parse|/parse> tree minus its L<id> and all the nodes below it. Or use L<-g|/opString> B<$node>. The id of the top most node is not included in the md5sum to equate parse trees that would otherwise only differ by the arbitrary root node id value.
802 {my ($node) = @_; # Node.
803 $node->id = undef if my $i = $node->id; # Save id
804 my $md5 = stringMd5Sum($node->string); # Md5 sum of string content minus id. The various printing methods will of course all produce different md5 sums but the md5 sum is big enough to accommodate the variations without collisions.
805 $node->id = $i if $i; # Restore id if present
806 $md5 # Return md5 sum
807 }
808  
809 sub stringQuoted($) #U Return a quoted string representing a L<parse|/parse> tree a node of a L<parse|/parse> tree and all the nodes below it. Or use L<-o|/opString> B<$node>.
810 {my ($node) = @_; # Start node
811 "'".$node->string."'"
812 }
813  
814 sub stringReplacingIdsWithLabels($) # Return a string representing the specified L<parse|/parse> tree with the id attribute of each node set to the L<Labels|/Labels> attached to each node.
815 {my ($node) = @_; # Start node.
816 return $node->text if $node->isText; # Text node
817 my $t = $node->tag; # Not text so it has a tag
818 my $content = $node->content; # Sub nodes
819 return '<'.$t.$node->printAttributesReplacingIdsWithLabels.'/>' if !@$content;# No sub nodes
820  
821 my $s = '<'.$t.$node->printAttributesReplacingIdsWithLabels.'>'; # Has sub nodes
822 $s .= $_->stringReplacingIdsWithLabels for @$content; # Recurse to get the sub content
823 return $s.'</'.$t.'>';
824 }
825  
826 sub stringExtendingIdsWithLabels($) # Return a string representing the specified L<parse|/parse> tree with the id attribute of each node extended by the L<Labels|/Labels> attached to each node.
827 {my ($node) = @_; # Start node.
828 return $node->text if $node->isText; # Text node
829 my $t = $node->tag; # Not text so it has a tag
830 my $content = $node->content; # Sub nodes
831 return '<'.$t.$node->printAttributesExtendingIdsWithLabels.'/>' if !@$content;# No sub nodes
832  
833 my $s = '<'.$t.$node->printAttributesExtendingIdsWithLabels.'>'; # Has sub nodes
834 $s .= $_->stringExtendingIdsWithLabels for @$content; # Recurse to get the sub content
835 return $s.'</'.$t.'>';
836 }
837  
838 sub stringContent($) #U Return a string representing all the nodes below a node of a L<parse|/parse> tree.
839 {my ($node) = @_; # Start node.
840 my $s = '';
841 $s .= $_->string for $node->contents; # Recurse to get the sub content
842 $s
843 }
844  
845 sub stringContentOrText($) #U Return a string representing all the nodes below a node of a L<parse|/parse> tree or the text of the current node if it is a text node.
846 {my ($node) = @_; # Start node.
847 return $node->text if $node->isText;
848 stringContent($node);
849 }
850  
851 sub stringNode($) #U Return a string representing the specified B<$node> showing the attributes, labels and node number.
852 {my ($node) = @_; # Node.
853 my $s = '';
854  
855 if ($node->isText) # Text node
856 {$s = 'CDATA='.$node->text;
857 }
858 else # Non text node
859 {$s = $node->tag.$node->printAttributes;
860 }
861  
862 if (my $n = $node->number) # Node number if present
863 {$s .= "($n)"
864 }
865  
866 if (my @l = $node->getLabels) # Labels
867 {$s .= " ${_}:".$l[$_] for keys @l;
868 }
869  
870 $s
871 }
872  
873 sub stringTagsAndText($) #U Return a string showing just the tags and text at and below a specified B<$node>.
874 {my ($node) = @_; # Node.
875 my @s; # String or each node
876 for my $n($node->byList) # Each node
877 {push @s, $n->isText ? trim($n->text) : $n->tag; # Representation of node
878 }
879 return @s if wantarray; # Representations as array
880 join ' ', @s # Representation as string
881 }
882  
883 sub stringText($) #U Return a string showing just the text of the text nodes (separated by blanks) at and below a specified B<$node>.
884 {my ($node) = @_; # Node.
885 my @s; # String or each node
886 for my $n($node->byList) # Each node
887 {push @s, trim($n->text) if $n->isText; # Text of text nodes
888 }
889 return @s if wantarray; # Representations as array
890 join ' ', @s # Representation as string
891 }
892  
893 sub setRepresentationAsTagsAndText($) #U Sets the L<representationLast|/representationLast> for every node in the specified B<$tree> via L<stringTagsAndText|/stringTagsAndText>.
894 {my ($tree) = @_; # Tree of nodes.
895 $tree->by(sub # Each node
896 {$_->representationLast = $_->stringTagsAndText; # Set representationLast for each node
897 });
898 $tree
899 }
900  
901 sub setRepresentationAsText($) #U Sets the L<representationLast|/representationLast> for every node in the specified B<$tree> via L<stringText|/stringText>.
902 {my ($tree) = @_; # Tree of nodes.
903 $tree->by(sub # Each node
904 {$_->representationLast = $_->stringText; # Set representationLast for each node
905 });
906 $tree
907 }
908  
909 sub matchNodesByRepresentation($) #U Creates a hash of arrays of nodes that have the same representation in the specified B<$tree>. Set L<representation|/representationLast> for each node in the tree before calling this method.
910 {my ($tree) = @_; # Tree to examine
911 my %map; # Map of arrays of nodes that have the same representation.
912 for my $n($tree->byList) # Each node
913 {push @{$map{$n->representationLast}}, $n; # Classify node by representation
914 }
915 \%map # Return results
916 }
917  
918 #D2 Conditions # Print a subset of the L<parse|/parse> tree determined by the conditions attached to it.
919  
920 sub stringWithConditions($@) # Return a string representing the specified B<$node> of a L<parse|/parse> tree and all the nodes below it subject to conditions to select or reject some nodes.
921 {my ($node, @conditions) = @_; # Start node, conditions to be regarded as in effect.
922 return $node->text if $node->isText; # Text node
923 my %c = %{$node->conditions}; # Process conditions if any for this node
924 return '' if keys %c and @conditions and !grep {$c{$_}} @conditions; # Return if conditions are in effect and no conditions match
925 my $t = $node->tag; # Not text so it has a tag
926 my $content = $node->content; # Sub nodes
927  
928 my $s = ''; $s .= $_->stringWithConditions(@conditions) for @$content; # Recurse to get the sub content
929 return '<'.$t.$node->printAttributes.'/>' if !@$content or $s =~ /\A\s*\Z/; # No sub nodes or none selected
930 '<'.$t.$node->printAttributes.'>'.$s.'</'.$t.'>'; # Has sub nodes
931 }
932  
933 sub condition($$@) #CY Return the B<$node> if it has the specified B<$condition> and is in the optional B<@context>, else return B<undef>
934 {my ($node, $condition, @context) = @_; # Node, condition to check, optional context
935 return undef if @context and !$node->at(@context); # Check optional context
936 $node->conditions->{$condition} ? $node : undef # Return node if it has the specified condition, else B<undef>
937 }
938  
939 sub anyCondition($@) #Y Return the B<$node> if it has any of the specified B<@conditions>, else return B<undef>
940 {my ($node, @conditions) = @_; # Node, conditions to check
941 $node->conditions->{$_} ? return $node : undef for @conditions; # Return node if any of the specified conditions are present
942 undef # No conditions present
943 }
944  
945 sub allConditions($@) #Y Return the B<$node> if it has all of the specified B<@conditions>, else return B<undef>
946 {my ($node, @conditions) = @_; # Node, conditions to check
947 !$node->conditions->{$_} ? return undef : undef for @conditions; # Return node if any of the specified conditions are missing
948 $node # All conditions present
949 }
950  
951 sub addConditions($@) # Given a B<$node> add the specified B<@conditions> and return the node.
952 {my ($node, @conditions) = @_; # Node, conditions to add.
953 $node->conditions->{$_}++ for @conditions;
954 $node
955 }
956  
957 sub deleteConditions($@) # Given a B<$node> delete any B<@conditions> applied to the $node and return the $node.
958 {my ($node, @conditions) = @_; # Node, conditions to add.
959 delete $node->conditions->{$_} for @conditions;
960 $node
961 }
962  
963 sub listConditions($) # Return a list of conditions applied to a B<$node>.
964 {my ($node) = @_; # Node.
965 sort keys %{$node->conditions}
966 }
967  
968 #D1 Attributes # Get or set the attributes of nodes in the L<parse|/parse> tree. L<Well Known Attributes|/Well Known Attributes> can be set directly via L<lvalueMethod> B<sub>s. To set or get the values of other attributes use L<Get or Set Attributes|/Get or Set Attributes>. To delete or rename attributes see: L<Other Operations on Attributes|/Other Operations on Attributes>.
969  
970 #D2 Well Known Attributes # Get or set these node attributes via L<lvalueMethod> B<sub>s as in:\m $x->href = "#ref";
971  
972 if (0) {
973 genHash(__PACKAGE__, # Well known attributes useful in respect to L<XML> that conforms to the L<Dita> standard.
974 audience => undef, # Attribute B<audience> for a node as an L<lvalueMethod> B<sub>. Use B<audienceX()> to return B<q()> rather than B<undef>.
975 class => undef, # Attribute B<class> for a node as an L<lvalueMethod> B<sub>. Use B<classX()> to return B<q()> rather than B<undef>.
976 guid => undef, # Attribute B<guid> for a node as an L<lvalueMethod> B<sub>. Use B<guidX()> to return B<q()> rather than B<undef>.
977 href => undef, # Attribute B<href> for a node as an L<lvalueMethod> B<sub>. Use B<hrefX()> to return B<q()> rather than B<undef>.
978 id => undef, # Attribute B<id> for a node as an L<lvalueMethod> B<sub>. Use B<idX()> to return B<q()> rather than B<undef>.
979 lang => undef, # Attribute B<lang> for a node as an L<lvalueMethod> B<sub>. Use B<langX()> to return B<q()> rather than B<undef>.
980 navtitle => undef, # Attribute B<navtitle> for a node as an L<lvalueMethod> B<sub>. Use B<navtitleX()> to return B<q()> rather than B<undef>.
981 otherprops => undef, # Attribute B<otherprops> for a node as an L<lvalueMethod> B<sub>. Use B<otherpropsX()> to return B<q()> rather than B<undef>.
982 outputclass => undef, # Attribute B<outputclass> for a node as an L<lvalueMethod> B<sub>. Use B<outputclassX()> to return B<q()> rather than B<undef>.
983 props => undef, # Attribute B<props> for a node as an L<lvalueMethod> B<sub>. Use B<propsX()> to return B<q()> rather than B<undef>.
984 style => undef, # Attribute B<style> for a node as an L<lvalueMethod> B<sub>. Use B<styleX()> to return B<q()> rather than B<undef>.
985 type => undef, # Attribute B<type> for a node as an L<lvalueMethod> B<sub>. Use B<typeX()> to return B<q()> rather than B<undef>.
986 xtrc => undef, # Attribute B<xtrc> for a node as an L<lvalueMethod> B<sub>. Use B<classX()> to return B<q()> rather than B<undef>.
987 xtrf => undef, # Attribute B<xtrf> for a node as an L<lvalueMethod> B<sub>. Use B<classX()> to return B<q()> rather than B<undef>.
988 );
989 }
990  
991 BEGIN # The above documents the attributes created below using the L<attr|_/attr> method.
992 {for my $a(qw(audience class guid href id lang navtitle), # Return well known attributes as an assignable value
993 qw(otherprops outputclass props style type xtrf))
994 {eval 'sub '.$a. '($) :lvalue {&attr($_[0], q('.$a.'))}'.
995 'sub '.$a.'X($) {&attr($_[0], q('.$a.')) // q()}';
996 $@ and confess "Cannot create well known attribute $a\n$@";
997  
998 my $A = ucfirst $a;
999 for my $c(qw(at first next prev last)) # Commands to attach to attributes
1000 {my $cmd = 'sub '.$c.$A.'($)'.
1001 ' {my ($node, $attrValue, @context) = @_;'.
1002 ' my $A = $node->attr(q('.$a.'));'.
1003 ' return $node if $node->'.$c.'(@context) and $A and $A eq $attrValue;'.
1004 ' undef;}';
1005 eval $cmd;
1006 $@ and confess "Cannot create well known attribute $a\n$@";
1007 }
1008 }
1009 }
1010  
1011 #D2 Get or Set Attributes # Get or set the attributes of nodes.
1012 sub attr($$) :lvalue # Return the value of an attribute of the current node as an L<lvalueMethod> B<sub>.
1013 {my ($node, $attribute) = @_; # Node in parse tree, attribute name.
1014 $node->attributes->{$attribute}
1015 }
1016  
1017 sub attrX($$) #I Return the value of the specified B<$attribute> of the specified B<$node> or B<q()> if the B<$node> does not have such an attribute.
1018 {my ($node, $attribute) = @_; # Node in parse tree, attribute name.
1019 $node->attributes->{$attribute} // ''
1020 }
1021  
1022 sub set($%) #U Set the values of some attributes in a node and return the node. Identical in effect to L<setAttr|/setAttr>.
1023 {my ($node, %values) = @_; # Node in parse tree, (attribute name=>new value)*
1024 s/["<>]/ /gs for grep {$_} values %values; # We cannot have these characters in an attribute
1025 $node->attributes->{$_} = $values{$_} for keys %values; # Set attributes
1026 $node
1027 }
1028 #a deleteAttrs
1029 #b <b/>
1030 #c at b
1031 #c set id bb class cc href hh
1032 #d Set some attributes.
1033  
1034 sub addAttr($%) #U Check the specified B<$node> for the specified B<%attributes> and add any that are not already set. Returns the current node.
1035 {my ($node, %values) = @_; # Node in parse tree, (attribute name=>new value)*
1036 s/["<>]/ /gs for grep {$_} values %values; # We cannot have these characters in an attribute
1037 $node->attributes->{$_} //= $values{$_} for keys %values; # Set attributes
1038 $node
1039 }
1040  
1041 sub setAttr($%) #U Set the values of some attributes in a node and return the node. Identical in effect to L<set|/set>.
1042 {my ($node, %values) = @_; # Node in parse tree, (attribute name=>new value)*
1043 s/["<>]/ /gs for grep {$_} values %values; # We cannot have these characters in an attribute
1044 $node->attributes->{$_} = $values{$_} for keys %values; # Set attributes
1045 $node
1046 }
1047  
1048 #D2 Other Operations on Attributes # Perform operations other than get or set on the attributes of a node
1049 sub attrs($@) # Return the values of the specified attributes of the current node as a list
1050 {my ($node, @attributes) = @_; # Node in parse tree, attribute names.
1051 my @v;
1052 my $a = $node->attributes;
1053 push @v, $a->{$_} for @attributes;
1054 @v
1055 }
1056  
1057 sub attrCount($@) #U Return the number of attributes in the specified B<$node>, optionally ignoring the specified names from the count.
1058 {my ($node, @exclude) = @_; # Node in parse tree, optional attribute names to exclude from the count.
1059 my $a = $node->attributes; # Attributes
1060 return scalar grep {defined $a->{$_}} keys %$a if @exclude == 0; # Count all attributes
1061 my %e = map{$_=>1} @exclude; # Hash of attributes to be excluded
1062 scalar grep {defined $a->{$_} and !$e{$_}} keys %$a; # Count attributes that are not excluded
1063 }
1064  
1065 sub getAttrs($) # Return a sorted list of all the attributes on the specified B<$node>.
1066 {my ($node) = @_; # Node in parse tree.
1067 my $a = $node->attributes; # Attributes
1068 grep {defined $a->{$_}} sort keys %$a # Attributes
1069 }
1070  
1071 sub deleteAttr($$;$) #U Delete the named attribute in the specified B<$node>, optionally check its value first, returning the value of the attribute or B<undef> if the attribute does not exist on this node.
1072 {my ($node, $attr, $value) = @_; # Node, attribute name, optional attribute value to check first.
1073 @_ > 3 and confess
1074 "A maximum of three parameters are allowed or try deleteAttrs"; # Deflect to deleteAttrs if too many parameters
1075 my $a = $node->attributes; # Attributes hash
1076 if (@_ == 3)
1077 {if (defined($a->{$attr}) and $a->{$attr} eq $value) # Delete user key if it has the right value
1078 {delete $a->{$attr}; return $value; # Delete user key if it has the right value
1079 }
1080 return undef; # Attribute has wrong value so return undef
1081 }
1082 else
1083 {return delete $a->{$attr}; # Delete user key unconditionally
1084 }
1085 }
1086 #a
1087 #b <b class="help"/><b class="ref"/>
1088 #c deleteAttr class help
1089 #d Delete an attribute if has a specific value.
1090  
1091 sub deleteAttrs($@) #U Delete the specified attributes of the specified B<$node> without checking their values and return the node.
1092 {my ($node, @attrs) = @_; # Node, Names of the attributes to delete
1093 my $a = $node->attributes; # Attributes hash
1094 delete $a->{$_} for @attrs;
1095 $node
1096 }
1097 #a deleteAttr
1098 #b <b id="b"/><c id="c" class="c" href="c"/>
1099 #c at c
1100 #c deleteAttrs id class
1101 #d Delete the named attributes.
1102 sub deleteAttrsInTree($@) #U Delete the specified attributes of the specified B<$node> and all the nodes under it and return the specified B<$node>.
1103 {my ($node, @attrs) = @_; # Node, Names of the attributes to delete
1104 $node->by(sub # Traverse the parse tree
1105 {my ($o) = @_;
1106 my $a = $o->attributes; # Attributes hash
1107 delete $a->{$_} for @attrs; # Delete the specified attributes
1108 });
1109 $node
1110 }
1111  
1112 sub attrsNone($@) #CU Check that the specified B<$node> has no attributes. Return the specified $node if no attributes were found else B<undef>. Invented by MfM.
1113 {my ($node, @context) = @_; # Node, optional context
1114 return undef if @context and !$node->at(@context); # Check optional context
1115 my $a = $node->attributes; # Attributes hash
1116 keys(%$a) ? undef : $node # Fail if there are attributes
1117 }
1118 #a attrs
1119 #b <b/><c id="cc"/>
1120 #c attrsNone b a
1121 #c set id had_no_attributes
1122 #d Continue if there are no attributes present.
1123  
1124 sub deleteAttrValueAtInTree($$$@) #C Delete all instances of the specified B<$attribute> with the specified B<$value> in the specified B<@context> in the specified B<$tree> and return the modified B<$tree>. An undefined B<$value> will cause the attribute to be deleted without first confirming its value. An empty context will remove the attribute from every node in the B<$tree>.
1125 {my ($tree, $attribute, $value, @context) = @_; # Tree, attribute name, attribute value or B<undef> for all values, optional context
1126 $tree->by(sub # Traverse the parse tree
1127 {my ($o) = @_;
1128 return if @context and !$o->at(@context); # Not in specified context
1129 $o->deleteAttr($attribute, $value); # Delete the named attribute if its value matches
1130 });
1131 $tree # Return the modified parse tree
1132 }
1133  
1134 sub renameAttr($$$@) #CU Rename attribute B<$old> to B<$new> in the specified B<$node> with optional context B<@context> regardless of whether attribute B<$new> already exists or not and return the B<$node>. To prevent inadvertent changes to an existing attribute use L<changeAttr|/changeAttr>.
1135 {my ($node, $old, $new, @context) = @_; # Node, existing attribute name, new attribute name, optional context.
1136 return undef if @context and !$node->at(@context); # Check optional context
1137 my $a = $node->attributes; # Attributes hash
1138 if (defined($a->{$old})) # Check old attribute exists
1139 {my $value = $a->{$old}; # Existing value
1140 $a->{$new} = $value; # Change the attribute name
1141 delete $a->{$old};
1142 }
1143 $node
1144 }
1145 #a attrs set deleteAttrs
1146 #b <b class="bb"/>
1147 #c renameAttr class href
1148 #d Rename an attribute.
1149  
1150 sub renameAttrXtr($@) #CU Rename the attributes B<@attr> as far as possible to xtrc or xtrf. Returns an array of the attributes that could not be so renamed.
1151 {my ($node, @attr) = @_; # Node, attributes to rename if they exist
1152 my $a = $node->attributes; # Attributes hash
1153 my @a; # Attributes unable to rename
1154 for my $attr(@attr) # Each attribute to rename
1155 {next unless defined $a->{$attr}; # Requested attribute not present
1156 if (!defined($a->{xtrc})) # xtrc
1157 {$a->{xtrc} = delete $a->{$attr};
1158 }
1159 elsif (!defined($a->{xtrf})) # xtrf
1160 {$a->{xtrf} = delete $a->{$attr};
1161 }
1162 else # Cannot rename
1163 {push @a, $attr;
1164 }
1165 }
1166 @a # Unrenameable attributes
1167 }
1168  
1169 sub changeAttr($$$@) #CU Rename attribute B<$old> to B<$new> in the specified B<$node> with optional context B<@context> unless attribute B<$new> is already set and return the B<$node>. To make changes regardless of whether the new attribute already exists use L<renameAttr|/renameAttr>.
1170 {my ($node, $old, $new, @context) = @_; # Node, existing attribute name, new attribute name, optional context.
1171 return undef if @context and !$node->at(@context); # Check optional context
1172 exists $node->attributes->{$new} ? $node : $node->renameAttr($old, $new) # Check old attribute exists
1173 }
1174  
1175 sub changeOrDeleteAttr($$$@) #CU Rename attribute B<$old> to B<$new> in the specified B<$node> in the optional B<@context> unless attribute B<$new> is already set in which case delete attribute B<$old>. Return B<$node> regardless of what action was taken. To make changes regardless of whether the new attribute already exists use L<renameAttr|/renameAttr>.
1176 {my ($node, $old, $new, @context) = @_; # Node, existing attribute name, new attribute name, optional context.
1177 return undef if @context and !$node->at(@context); # Check optional context
1178 exists $node->attributes->{$new} ? $node->deleteAttr($old) : # Delete or rename attribute
1179 $node->renameAttr($old, $new)
1180 }
1181  
1182 sub renameAttrValue($$$$$@) #CU Rename attribute B<$old> to B<$new> with new value B<$newValue> in the specified B<$node> in the optional B<@context> regardless of whether attribute B<$new> already exists or not as long as the attribute B<$old> has the value B<$oldValue>. Return the B<$node> regardless of what changes were made. To prevent inadvertent changes to existing attributes use L<changeAttrValue|/changeAttrValue>.
1183 {my ($node, $old, $oldValue, $new, $newValue, @context) = @_; # Node, existing attribute name, existing attribute value, new attribute name, new attribute value, optional context.
1184 return undef if @context and !$node->at(@context); # Check optional context
1185 my $a = $node->attributes; # Attributes hash
1186 if (defined($a->{$old}) and $a->{$old} eq $oldValue) # Check old attribute exists and has the specified value
1187 {$a->{$new} = $newValue; # Change the attribute name
1188 delete $a->{$old};
1189 }
1190 $node
1191 }
1192  
1193 sub changeAttrValue($$$$$@) #CU Rename attribute B<$old> to B<$new> with new value B<$newValue> on the specified B<$node> in the optional B<@context> unless attribute B<$new> is already set or the value of the B<$old> attribute is not B<$oldValue>. Return the B<$node> regardless of what changes were made. To make changes regardless of whether the new attribute already exists use L<renameAttrValue|/renameAttrValue>.
1194 {my ($node, $old, $oldValue, $new, $newValue, @context) = @_; # Node, existing attribute name, existing attribute value, new attribute name, new attribute value, optional context.
1195 return undef if @context and !$node->at(@context); # Check optional context
1196 exists $node->attributes->{$new} ? $node : # Check old attribute exists
1197 $node->renameAttrValue($old, $oldValue, $new, $newValue)
1198 }
1199  
1200 sub changeAttributeValue($$$@) #CU Apply a sub to the value of an attribute of the specified B<$node>. The value to be changed is supplied and returned in: L<$_>.
1201 {my ($node, $attribute, $sub, @context) = @_; # Node, attribute name, change sub, optional context.
1202 return () if @context and !$node->at(@context); # Check optional context
1203 return unless local $_ = $node->attr($attribute); # Check that the attribute has a value we can change
1204 &$sub; # Change the attribute
1205 $node->set($attribute, $_) # Update the attribute's value
1206 }
1207  
1208 sub changeOrDeleteAttrValue($$$$$@) #CU Rename attribute B<$old> to B<$new> with new value B<$newValue> on the specified B<$node> in the optional B<@context> unless attribute B<$new> is already set or the value of the B<$old> attribute is not B<$oldValue> in which cases the B<$old> attribute is deleted. Return the B<$node> regardless of any changes made. To make changes regardless of whether the new attribute already exists use L<renameAttrValue|/renameAttrValue>.
1209 {my ($node, $old, $oldValue, $new, $newValue, @context) = @_; # Node, existing attribute name, existing attribute value, new attribute name, new attribute value, optional context.
1210 return undef if @context and !$node->at(@context); # Check optional context
1211 exists $node->attributes->{$new} ? $node->deleteAttr($old) : # Check old attribute exists
1212 $node->renameAttrValue($old, $oldValue, $new, $newValue)
1213 }
1214  
1215 sub 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.
1216 {my ($source, $target, @attr) = @_; # Source node, target node, optional list of attributes to copy
1217 my $s = $source->attributes; # Source attributes hash
1218 my $t = $target->attributes; # Target attributes hash
1219 if (@attr) # Named attributes
1220 {$t->{$_} = $s->{$_} for @attr; # Transfer each named attribute
1221 }
1222 else # All attributes
1223 {$t->{$_} = $s->{$_} for sort keys %$s; # Transfer each source attribute
1224 }
1225 $source # Return source node
1226 }
1227  
1228 sub copyAttrsFromParent($@) #U Copy all the attributes from the parent (if there is one) of the current B<$node> to $node or just the named B<@attributes> and return $node. If $node is the top of the parse tree then return B<undef> as it does not have a parent.
1229 {my ($node, @attr) = @_; # Node, attributes to copy from parent
1230 return undef unless my $parent = $node->parent;
1231 my $s = $parent->attributes; # Source attributes hash
1232 my $t = $node->attributes; # Target attributes hash
1233 if (@attr) # Named attributes
1234 {$t->{$_} = $s->{$_} for @attr; # Transfer each named attribute
1235 }
1236 else # All attributes
1237 {$t->{$_} = $s->{$_} for sort keys %$s; # Transfer all attributes from parent
1238 }
1239 $node # Return node
1240 }
1241  
1242 sub copyAttrsToParent($@) #U Copy all the attributes of the specified B<$node> to its parent (if there is one) or just the named B<@attributes> and return $node. If $node is the top of the parse tree then return B<undef> as it does not have a parent.
1243 {my ($node, @attr) = @_; # Node, attributes to copy from parent
1244 return undef unless my $parent = $node->parent;
1245 my $s = $node->attributes; # Source attributes hash
1246 my $t = $parent->attributes; # Target attributes hash
1247 if (@attr) # Named attributes
1248 {$t->{$_} = $s->{$_} for @attr; # Transfer each named attribute
1249 }
1250 else # All attributes
1251 {$t->{$_} = $s->{$_} for sort keys %$s; # Transfer all attributes from parent
1252 }
1253 $node # Return node
1254 }
1255  
1256 sub 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.
1257 {my ($source, $target, @attr) = @_; # Source node, target node, optional list of attributes to copy
1258 my $s = $source->attributes; # Source attributes hash
1259 my $t = $target->attributes; # Target attributes hash
1260 if (@attr) # Named attributes
1261 {$t->{$_} = $s->{$_} for grep {!exists $t->{$_}} @attr; # Transfer each named attribute not already present in the target
1262 }
1263 else # All attributes
1264 {$t->{$_} = $s->{$_} for grep {!exists $t->{$_}} sort keys %$s; # Transfer each source attribute not already present in the target
1265 }
1266 $source # Return source node
1267 }
1268  
1269 sub 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.
1270 {my ($source, $target, @attr) = @_; # Source node, target node, attributes to move
1271 my $s = $source->attributes; # Source attributes hash
1272 my $t = $target->attributes; # Target attributes hash
1273 if (@attr) # Named attributes
1274 {$t->{$_} = delete $s->{$_} for @attr; # Transfer each named attribute and delete from the source node
1275 }
1276 else # All attributes
1277 {$t->{$_} = delete $s->{$_} for sort keys %$s; # Transfer each source attribute and delete from source node
1278 }
1279 $source # Return source node
1280 }
1281  
1282 sub 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.
1283 {my ($source, $target, @attr) = @_; # Source node, target node, optional list of attributes to move
1284 my $s = $source->attributes; # Source attributes hash
1285 my $t = $target->attributes; # Target attributes hash
1286 if (@attr) # Named attributes
1287 {$t->{$_} = delete $s->{$_} for grep {!exists $t->{$_}} @attr; # Transfer each named attribute and delete it from the source node as long as it does not already exist in the target
1288 }
1289 else # All attributes
1290 {$t->{$_} = delete $s->{$_} for grep {!exists $t->{$_}} sort keys %$s; # Transfer every attribute and delete it from the source node as long as it does not already exist in the target
1291 }
1292 $source # Return source node
1293 }
1294  
1295 #D1 Traversal # Traverse the L<parse|/parse> tree in various orders applying a B<sub> to each node.
1296  
1297 #D2 Post-order # This order allows you to edit children before their parents.
1298  
1299 sub by2($$@) #P Post-order traversal of a L<parse|/parse> tree
1300 {my ($node, $sub, @context) = @_; # Starting node, sub to call for each sub node, accumulated context.
1301 $_->by2($sub, $node, @context) for $node->contents; # Recurse to process sub nodes in deeper context
1302 &$sub(local $_ = $node, @context); # Process specified node last
1303 $node
1304 }
1305  
1306 sub By22($$) #P Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. A reference to the current node is also made available via L<$_>. This is equivalent to the L<x=|/opBy> operator.
1307 {my ($node, $sub) = @_; # Starting node, sub to call for each sub node
1308 $node->by2($sub); # Recurse through nodes
1309 $node
1310 }
1311  
1312 # Doubles performance of by! IT is tempting to think that removing all the parameters would speed things up a lot - it does not as most parse trees are not very deep.
1313  
1314 sub by($$) #I Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. A reference to the current node is also made available via L<$_>. This is equivalent to the L<x=|/opBy> operator.
1315 {my ($node, $sub) = @_; # Starting node, sub to call for each sub node
1316  
1317 my $by; $by = sub # Recurse to process sub nodes in deeper context
1318 {$_ = $_[0]; # Save active node in $_
1319 if (my $c = $_->{content}) # Contents reference
1320 {my @c = @$c; # For some reason we cannot place this directly in a for loop reliably
1321 for(@c) # Each node under the current node
1322 {if (my $d = $_->{content}) # Contents reference
1323 {my @d = @$d; # Content
1324 my $D = $_; # Save $_ so we can use it in the following loop
1325 for(@d) # Each node under the current node
1326 {if (my $e = $_->{content}) # Contents reference
1327 {my @e = @$e; # For some reason we cannot place this directly in a for loop reliably
1328 my $E = $_; # Save $_ so we can use it in the following loop
1329 for(@e) # Each node under the current node
1330 {if (my $f = $_->{content}) # Contents reference
1331 {my @f = @$f; # Content
1332 my $F = $_; # Save $_ so we can use it in the following loop
1333 for(@f) # Each node under the current node
1334 {if (my $g = $_->{content}) # Contents reference
1335 {my @g = @$g; # Content
1336 my $G = $_; # Save $_ so we can use it in the following loop
1337 for(@g) # Each node under the current node
1338 {if (my $h = $_->{content}) # Contents reference
1339 {my @h = @$h; # Content
1340 my $H = $_; # Save $_ so we can use it in the following loop
1341 for(@h) # Each node under the current node
1342 {if (my $i = $_->{content}) # Contents reference
1343 {my @i = @$i; # Content
1344 my $I = $_; # Save $_ so we can use it in the following loop
1345 for(@i) # Each node under the current node
1346 {if (my $j = $_->{content}) # Contents reference
1347 {my @j = @$j; # Content
1348 my $J = $_; # Save $_ so we can use it in the following loop
1349 for(@j) { # Each node under the current node
1350 &$by($_, $J, $I, $H, $G, $F, $E, $D, @_); # Recurse
1351 }
1352 }
1353 &$sub($_, $I, $H, $G, $F, $E, $D, @_); # Process current node in post order
1354 }
1355 }
1356 &$sub($_, $H, $G, $F, $E, $D, @_); # Process current node in post order
1357 }
1358 }
1359 &$sub($_, $G, $F, $E, $D, @_); # Process current node in post order
1360 }
1361 }
1362 &$sub($_, $F, $E, $D, @_); # Process current node in post order
1363 }
1364 }
1365 &$sub($_, $E, $D, @_); # Process current node in post order
1366 }
1367 }
1368 &$sub($_, $D, @_); # Process current node in post order
1369 }
1370 }
1371 &$sub($_, @_); # Process current node in post order
1372 }
1373 }
1374 &$sub(@_); # Process current node in post order
1375 };
1376  
1377 &$by($node); # Recurse through nodes
1378  
1379 $node
1380 }
1381  
1382 sub byX($$) #C Post-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die>. The traversal is halted if the called sub does L<die> on any call with the reason in L<?@|http://perldoc.perl.org/perlvar.html#Error-Variables> The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry> up to the node on which this sub was called. A reference to the current node is also made available via L<$_>.\mReturns the start node regardless of the outcome of calling B<sub>.
1383 {my ($node, $sub) = @_; # Start node, sub to call
1384 eval {$node->byX2($sub)}; # Trap any errors that occur
1385 $node
1386 }
1387  
1388 sub byX2($$@) #P Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval>B<{}> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
1389 {my ($node, $sub, @context) = @_; # Starting node, sub to call, accumulated context.
1390 $_->byX2($sub, $node, @context) for $node->contents; # Recurse to process sub nodes in deeper context
1391 &$sub(local $_ = $node, @context); # Process specified node last
1392 }
1393  
1394 sub byX22($$@) #P Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval>B<{}> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
1395 {my ($node, $sub, @context) = @_; # Starting node, sub to call, accumulated context.
1396 $_->byX($sub, $node, @context) for $node->contents; # Recurse to process sub nodes in deeper context
1397 eval {&$sub(local $_ = $node, @context)}; # Process specified node last
1398 $node
1399 }
1400  
1401 sub byList($@) #C Return a list of all the nodes at and below a specified B<$node> in post-order or the empty list if the B<$node> is not in the optional B<@context>.
1402 {my ($node, @context) = @_; # Starting node, optional context
1403 return () if @context and !$node->at(@context); # Check optional context
1404 my @n; # Nodes under specified node
1405 $node->by(sub{push @n, $_}); # Retrieve nodes in post-order
1406 @n # Return list of nodes
1407 }
1408  
1409 sub byReverse($$@) # Reverse post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting B<$node>. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
1410 {my ($node, $sub, @context) = @_; # Starting node, sub to call for each sub node, accumulated context.
1411 $_->byReverse($sub, $node, @context) for reverse $node->contents; # Recurse to process sub nodes in deeper context
1412 &$sub(local $_ = $node, @context); # Process specified node last
1413 $node
1414 }
1415  
1416 sub byReverseX($$@) # Reverse post-order traversal of a L<parse|/parse> tree or sub tree below the specified B<$node> calling the specified B<sub> within L<eval>B<{}> at each node and returning the specified starting B<$node>. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
1417 {my ($node, $sub, @context) = @_; # Starting node, sub to call for each sub node, accumulated context.
1418 $_->byReverseX($sub, $node, @context) for reverse $node->contents; # Recurse to process sub nodes in deeper context
1419 &$sub(local $_ = $node, @context); # Process specified node last
1420 $node
1421 }
1422  
1423 sub byReverseList($@) #C Return a list of all the nodes at and below a specified B<$node> in reverse preorder or the empty list if the specified B<$node> is not in the optional B<@context>.
1424 {my ($node, @context) = @_; # Starting node, optional context
1425 return () if @context and !$node->at(@context); # Check optional context
1426 my @n; # Nodes
1427 $node->byReverse(sub{push @n, $_}); # Retrieve nodes in reverse post-order
1428 @n # Return list of nodes
1429 }
1430  
1431 #D2 Pre-order # This order allows you to edit children after their parents
1432  
1433 sub down($$@) # Pre-order traversal down through a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
1434 {my ($node, $sub, @context) = @_; # Starting node, sub to call for each sub node, accumulated context.
1435 &$sub(local $_ = $node, @context); # Process specified node first
1436 $_->down($sub, $node, @context) for $node->contents; # Recurse to process sub nodes in deeper context
1437 $node
1438 }
1439  
1440 sub downX($$) # Pre-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die>. The traversal is halted for the entire L<parse|/parse> tree if the called sub does L<die> with the reason returned in L<?@|http://perldoc.perl.org/perlvar.html#Error-Variables>. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry> up to the node on which this sub was called. A reference to the current node is also made available via L<$_>.\mReturns the start node regardless of the outcome of calling B<sub>.
1441 {my ($node, $sub) = @_; # Start node, sub to call
1442 eval {$node->downX2($sub)}; # Trap any errors that occur
1443 $node
1444 }
1445  
1446 sub downX2($$@) #P Pre-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval>B<{}> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
1447 {my ($node, $sub, @context) = @_; # Starting node, sub to call, accumulated context.
1448 &$sub(local $_ = $node, @context); # Process specified node last
1449 $_->downX2($sub, $node, @context) for $node->contents; # Recurse to process sub nodes in deeper context
1450 }
1451  
1452 sub downToDie($$) # Pre-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die>. The traversal of the current sub tree is halted and continue with the next sibling or parent if the called sub does L<die>. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry> up to the node on which this sub was called. A reference to the current node is also made available via L<$_>.\mReturns the start node regardless of the outcome of calling B<sub>.
1453 {my ($node, $sub) = @_; # Start node, sub to call
1454 $node->downToDie2($sub);
1455 $node
1456 }
1457  
1458 sub downToDie2($$@) #P Pre-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die>. The traversal of the current sub tree is halted and continue with the next sibling or parent if the called sub does L<die>. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry> up to the node on which this sub was called. A reference to the current node is also made available via L<$_>.\mReturns the start node regardless of the outcome of calling B<sub>.
1459 {my ($node, $sub, @context) = @_; # Starting node, sub to call, accumulated context.
1460 eval {&$sub(local $_ = $node, @context)}; # Process specified node last
1461 unless($@) # Skip sub tree if sub died while processing parent
1462 {$_->downToDie2($sub, $node, @context) for $node->contents; # Recurse to process sub nodes in deeper context
1463 }
1464 }
1465  
1466 sub downList($@) #C Return a list of all the nodes at and below a specified B<$node> in pre-order or the empty list if the B<$node> is not in the optional B<@context>.
1467 {my ($node, @context) = @_; # Starting node, optional context
1468 return () if @context and !$node->at(@context); # Check optional context
1469 my @n; # Nodes under specified node
1470 $node->down(sub{push @n, $_}); # Retrieve nodes in pre-order
1471 @n # Return list of nodes
1472 }
1473  
1474 sub downReverse($$@) # Reverse pre-order traversal down through a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
1475 {my ($node, $sub, @context) = @_; # Starting node, sub to call for each sub node, accumulated context.
1476 &$sub(local $_ = $node, @context); # Process specified node first
1477 $_->downReverse($sub, $node, @context) for reverse $node->contents; # Recurse to process sub nodes in deeper context
1478 $node
1479 }
1480  
1481 sub downReverseX($$@) # Reverse pre-order traversal down through a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval>B<{}> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
1482 {my ($node, $sub, @context) = @_; # Starting node, sub to call for each sub node, accumulated context.
1483 &$sub(local $_ = $node, @context); # Process specified node first
1484 $_->downReverseX($sub, $node, @context) for reverse $node->contents; # Recurse to process sub nodes in deeper context
1485 $node
1486 }
1487  
1488 sub downReverseList($@) #C Return a list of all the nodes at and below a specified B<$node> in reverse pre-order or the empty list if the B<$node> is not in the optional B<@context>.
1489 {my ($node, @context) = @_; # Starting node, optional context
1490 return () if @context and !$node->at(@context); # Check optional context
1491 my @n; # Nodes under specified node
1492 $node->downReverse(sub{push @n, $_}); # Retrieve nodes in reverse pre-order
1493 @n # Return list of nodes
1494 }
1495  
1496 #D2 Pre and Post order # Visit the parent first, then the children, then the parent again.
1497  
1498 sub through($$$@) # Traverse L<parse|/parse> tree visiting each node twice calling the specified sub B<$before> as we go down past the node and sub B<$after> as we go up past the node, finally return the specified starting node. The subs B<$before, $after> are passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
1499 {my ($node, $before, $after, @context) = @_; # Starting node, sub to call when we meet a node, sub to call we leave a node, accumulated context.
1500 &$before(local $_ = $node, @context) if $before; # Process specified node first with before()
1501 $_->through($before, $after, $node, @context) for $node->contents; # Recurse to process sub nodes in deeper context
1502 &$after(local $_ = $node, @context) if $after; # Process specified node last with after()
1503 $node
1504 }
1505  
1506 sub throughX($$$@) # Identical to L<through|/through> except the B<$before, $after> subs are called in an L<eval> block to prevent L<die> terminating the traversal of the full tree.
1507 {my ($node, $before, $after, @context) = @_; # Starting node, sub to call when we meet a node, sub to call we leave a node, accumulated context.
1508 &$before(local $_ = $node, @context); # Process specified node first with before()
1509 $_->throughX($before, $after, $node, @context) for $node->contents; # Recurse to process sub nodes in deeper context
1510 &$after(local $_ = $node, @context); # Process specified node last with after()
1511 $node
1512 }
1513  
1514 #D2 Range # Ranges of nodes
1515  
1516 sub 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.
1517 {my ($start, @match) = @_; # Start node, optional list of tags to match
1518 my $p = $start->parent; # Parent node
1519 confess "No parent" unless $p; # Not possible on a root node
1520 my @c = $p->contents; # Content
1521 shift @c while @c and $c[ 0] != $start; # Position on start node
1522 if (@match) # Select matching nodes if requested
1523 {my %m = map {$_=>1} @match;
1524 return grep {$m{$_->tag}} @c;
1525 }
1526 @c # Elements in the specified range
1527 }
1528  
1529 sub 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.
1530 {my ($end, @match) = @_; # End node, optional list of tags to match
1531 my $q = $end->parent; # Parent node
1532 confess "No parent" unless $q; # Not possible on a root node
1533 my @c = $q->contents; # Content
1534 pop @c while @c and $c[-1] != $end; # Position on end
1535 if (@match) # Select matching nodes if requested
1536 {my %m = map {$_=>1} @match;
1537 return grep {$m{$_->tag}} @c;
1538 }
1539 @c # Elements in the specified range
1540 }
1541  
1542 sub 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.
1543 {my ($start, $end, @match) = @_; # Start node, end node, optional list of tags to match
1544 my $p = $start->parent; # Parent node
1545 confess "No parent" unless $p; # Not possible on a root node
1546 my $q = $end->parent; # Parent node
1547 confess "No parent" unless $q; # Not possible on a root node
1548 confess "Not siblings" unless $p == $q; # Not possible unless the two nodes are siblings under the same parent
1549 my @c = $p->contents; # Content
1550 shift @c while @c and $c[ 0] != $start; # Position on start node
1551 pop @c while @c and $c[-1] != $end; # Position on end
1552 if (@match) # Select matching nodes if requested
1553 {my %m = map {$_=>1} @match;
1554 return grep {$m{$_->tag}} @c;
1555 }
1556 @c # Elements in the specified range
1557 }
1558  
1559 #D1 Location # Locate the line numbers and columns of a specified node and write that information as a L<Oxygen Message|/https://www.oxygenxml.com/doc/versions/20.1/ug-author/topics/linked-output-messages-of-external-engine.html>.
1560  
1561 sub parseLineLocation($) #PS Parse a line location
1562 {my ($loc) = @_; # Location
1563 my ($l, $c, $L, $C) = split m/[.:]/, $loc; # Position of node in source
1564  
1565 for my $n($l, $c, $L) # Check that some-one else is not using xtrf for some other reason
1566 {return () unless $n and $n =~ m(\A\d+\Z)s;
1567 }
1568 return () if $L and $L !~ m(\A\d+\Z)s;
1569  
1570 unless(defined $C) # Same line
1571 {$C = $L;
1572 $L = 0;
1573 }
1574 $L += $l; # Final line
1575  
1576 ($l, $c, $L, $C) # Return parsed line location
1577 }
1578  
1579 sub lineLocation($) #U Return the line number.column location of this tag in its source file or string if the source was parsed with the L<line number|/lineNumber> option on.
1580 {my ($node) = @_; # Node
1581 my $loc = $node->attr(q(xtrf)); # Location of node in source
1582 return q() unless $loc; # No location specified
1583 my @c = my ($l, $c, $L, $C) = parseLineLocation $loc; # Position of node in source
1584 for(@c)
1585 {return q() unless defined $_;
1586 }
1587 if ($l eq $L) # All on one line
1588 {return qq(on line $l from $c to $C) # Single line
1589 }
1590 qq(from line $l at $c to line $L at $C) # Spans two or more lines
1591 }
1592  
1593 sub location($;$) #U Return the line number.column plus file location of this tag in its source file or string if the source was parsed with the L<line number|/lineNumber> option on.
1594 {my ($node, $file) = @_; # Node, optionally the location of the source.
1595 my $lmsg = $node->lineLocation(); # Line location
1596 $lmsg = q( ).$lmsg if $lmsg;
1597 my $parser = $node->parser; # Parser associated with this node
1598 my $fmsg = sub # Description of the containing file
1599 {return qq( in file: ).$file if $file; # In the specified file
1600 return qq( in file: ).$parser->inputFile if $parser->inputFile; # Position of node in source
1601 q() # Unknown location
1602 }->();
1603 $lmsg.$fmsg # Return location
1604 }
1605  
1606 sub closestLocation($) #U Return the nearest node with line number.column information
1607 {my ($node) = @_; # Node
1608 return $node if $node->attr(q(xtrf)); # Node has a location so return it.
1609 my $best; # Best location so far
1610 if ($node->parser->lineNumbers) # Search through tree for closest node if line numbering is in effect
1611 {my $before = 1; # Best node before (after) the specified node
1612 for my $p($node->parser->downList) # Preorder traversal
1613 {if ($before or !$best) # Before or at the node
1614 {$best = $p if $p->attr(q(xtrf));
1615 }
1616 $before = 0 if $p == $node and $before; # Pass the node
1617 }
1618 }
1619 $best # Return best node if known
1620 }
1621  
1622 sub approxLocation($;$) #U Return the line number.column location of the node nearest to this node in the source file if the source was parsed with the L<line number|/lineNumber> option on.
1623 {my ($node, $file) = @_; # Node, optionally the location of the source.
1624 return location(@_) if $node->attr(q(xtrf)); # Node has a location so return it.
1625  
1626 my $best = $node->closestLocation; # Search through tree for closest node if line numbering is in effect
1627 return location($best, $file) if $best; # Nearby node has a location so return it.
1628 my $f = $file // $node->parser->inputFile; # Parser input file if known
1629 return qq( in file: ).$f if $f; # Position of node in source
1630 q() # Unknown location
1631 }
1632  
1633 sub formatOxygenMessage($$$@) #U Write an error message in Oxygen format
1634 {my ($node, $level, $url, @message) = @_; # Node, error level [F|E|W], explanatory Url, message text
1635 my ($line, $col, $Line, $Col) = sub # Position in Oxygen format
1636 {my $best = $node->closestLocation; # Closest node with line number information
1637 return parseLineLocation $best->xtrfX if $best; # Return numbers
1638 (1,1,0,0)
1639 }->();
1640 my $m = nws(join '', @message);
1641 my $u = $url ? qq( $url) : q();
1642 <<END; # To get this message to Oxygen simply write on STDOUT or STDERR
1643 Type: $level
1644 Line: $line
1645 Column: $col
1646 EndLine: $Line
1647 EndColumn: $Col
1648 AdditionalInfoURL:$u
1649 Description: $m
1650 END
1651 }
1652  
1653 #D1 Position # Confirm that the position L<navigated|/Navigation> to is the expected position.
1654  
1655 sub atPositionMatch($$) #P Confirm that a string matches a match expression.
1656 {my ($tag, $match) = @_; # Starting node, ancestry.
1657 return 1 unless $match; # Undefined match means anything matches
1658 return $tag eq $match unless ref $match; # Match scalar
1659 return $tag =~ m($match)s if ref($match) =~ m(regexp)i; # Match regular expression
1660 return $$match{$tag} if ref($match) =~ m(hash)i; # Match hash key
1661 if (ref($match) =~ m(array)i) # Match array
1662 {my %m = map {$_=>1} @$tag;
1663 return $m{$tag}
1664 }
1665 confess "Unknown match type"; # Do not know how to match
1666 }
1667  
1668 sub at($@) #CIYU Confirm that the specified B<$node> has the specified L<ancestry|/ancestry>. Ancestry is specified by providing the expected tags that the B<$node>'s parent, the parent's parent etc. must match at each level. If B<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 B<undef>.
1669 {my ($node, @context) = @_; # Node, ancestry.
1670 for(my $x = shift @_; $x; $x = $x->parent) # Up through parents
1671 {return $node unless @_; # OK if no more required context
1672 next if atPositionMatch(-t $x, shift @_); # Match tag against context
1673 return undef # Error if required does not match actual
1674 }
1675 !@_ ? $node : undef # Top of the tree is OK as long as there is no more required context
1676 }
1677 #b <b/>
1678 #b <c/>
1679 #c at b
1680 #c set id idb href bbb
1681 #d Continue if we are in the specified context.
1682  
1683 sub atText($$@) #CU Confirm that we are on a text node whose text value matches a regular expression in the optional B<@context>. Return the specified B<$node> on success else B<undef>.
1684 {my ($node, $re, @context) = @_; # Text node, regular expression to match, context
1685 return undef if !$node->isText(@context); # Not a text node in the specified context
1686 $node->text =~ m($re) ? $node : undef # Success if the text matches
1687 }
1688 #b <b>bb</b><c>cc</c>
1689 #c atText cc c
1690 #c up
1691 #c set id CC
1692 #d Continue if we are on a text node whose value matches a regular expression
1693  
1694 sub atStringContentMatches($$@) #CU Confirm that we are on a B<$node> whose contents, represented as a string, matches the specified regular expression B<$re> in the optional B<@context>. Return the specified B<$node> on success else B<undef>.
1695 {my ($node, $re, @context) = @_; # Text node, regular expression to match, context
1696 return undef if @context and !$node->at(@context); # Check optional context
1697 $node->stringContent =~ m($re) ? $node : undef # Success if the content, as a string, matches the re
1698 }
1699 #b <b><c>cc</c><d>dd</d></b>
1700 #c atStringContentMatches qr(dd)
1701 #c set id yes
1702 #d Continue if we are on a node whose content represented as a string matches a regular expression
1703  
1704 sub atTop($) #U Return the current node if it is the root == top of a parse tree else return B<undef>.
1705 {my ($node) = @_; # Node
1706 return $node unless $node->parent; # Has no parent so must be at the top
1707 undef # Has a parent and so is not at the top
1708 }
1709 #a at
1710 #b <b/>
1711 #c atTop
1712 #c set id top
1713 #d Continue if we are at the top.
1714  
1715 sub attrAt($$@) #CU Return the specified B<$node> if it has the specified B<$attribute> and the $node is in the optional B<@context> else return B<undef>.
1716 {my ($node, $attribute, @context) = @_; # Starting node, attribute, context
1717 return undef if @context and !$node->at(@context); # Not in specified context
1718 defined($node->attributes->{$attribute}) ? $node : undef # Node has attribute
1719 }
1720 #a set
1721 #b <b id='b'/><b id='bb'/>
1722 #c attrValueAt id bb
1723 #c set class here
1724 #d Continue if an attribute has a specific value.
1725  
1726 sub attrValueAt($$$@) #CU Return the specified B<$node> if it has the specified B<$attribute> with the specified B<$value> and the $node is in the optional B<@context> else return B<undef>.
1727 {my ($node, $attribute, $value, @context) = @_; # Starting node, attribute, wanted value of attribute, context
1728 return undef if @context and !$node->at(@context); # Not in specified context
1729 my $v = $node->attributes->{$attribute}; # Actual value of attribute
1730 if (defined($value) and defined($v)) # Compare attribute actual and wanted values
1731 {if (my $r = ref($value)) # Compare with a reference
1732 {if ($r =~ m(regExp)is) # Regular expression
1733 {return $v =~ m($value) ? $node : undef;
1734 }
1735 elsif ($r =~ m(Hash)is) # Key of a hash
1736 {return $$value{$v} ? $node : undef;
1737 }
1738 confess "Attribute value check expressed via unknown reference type"; # Unknown matching method
1739 }
1740 else # Match on value
1741 {return $value eq $v ? $node : undef;
1742 }
1743 }
1744 undef # One of actual and wanted values was B<undef> so return B<undef>.
1745 }
1746 #a set
1747 #b <b id='b'/><b id='bb'/>
1748 #c attrValueAt id bb
1749 #c set class here
1750 #d Continue if an attribute has a specific value.
1751  
1752 sub not($@) #U Return the specified B<$node> if it does not match any of the specified tags, else B<undef>
1753 {my ($node, @tags) = @_; # Node, tags not to match
1754 my %tags = map {$_=>1} @tags; # Tags not to match
1755 return $node unless $tags{$node->tag}; # Ok if node does not have one of the specified tags
1756 undef # Matched one of the tags that it should not match
1757 }
1758  
1759 sub atOrBelow($@) #CYU Confirm that the node or one of its ancestors has the specified context as recognized by L<at|/at> and return the first node that matches the context or B<undef> if none do.
1760 {my ($start, @context) = @_; # Starting node, ancestry.
1761 for(my $x = $start; $x; $x = $x->parent) # Up through parents
1762 {return $x if $x->at(@context); # Return this node if the context matches
1763 }
1764 undef # No node that matches the context
1765 }
1766  
1767 sub adjacent($$) # Return the first node if it is adjacent to the second node else B<undef>.
1768 {my ($first, $second) = @_; # First node, second node
1769 my ($n, $p) = ($first->next, $first->prev); # Nodes adjacent to the first node
1770 return $first if $n && $n == $second or $p && $p == $second; # Adjacent nodes
1771 undef
1772 }
1773  
1774 sub ancestry($) #U Return a list containing: (the specified B<$node>, its parent, its parent's parent etc..). Or use L<upn|/upn> to go up the specified number of levels.
1775 {my ($node) = @_; # Starting node.
1776 my @a;
1777 for(my $x = $node; $x; $x = $x->parent) # Up through parents
1778 {push @a, $x;
1779 }
1780 @a # Return ancestry
1781 }
1782  
1783 sub context($) #bU Return a string containing the tag of the starting node and the tags of all its ancestors separated by single spaces.
1784 {my ($node) = @_; # Starting node.
1785 my @a; # Ancestors
1786 for(my $p = $node; $p; $p = $p->parent)
1787 {push @a, $p->tag;
1788 @a < 100 or confess "Overly deep tree!";
1789 }
1790 join ' ', @a
1791 }
1792 #a
1793 #b <b> <c> <d context/> </c> </b>
1794 #c
1795 #d Get the context of node <b>d</b> by typing <b>context</b> or <b>gc</b> against its closing bracket and pressing <b>Save</b>.
1796 BEGIN {*gc = *context}
1797  
1798 sub containsSingleText($@) #CU Return the single text element below the specified B<$node> else return B<undef>.
1799 {my ($node, @context) = @_; # Node, optional context
1800 return undef if @context and !$node->at(@context); # Not in specified context
1801 my $t = $node->hasSingleChild; # Child element
1802 $t ? $t->isText : $t # Child element must be text
1803 }
1804  
1805 sub depth($) #U Returns the depth of the specified B<$node>, the depth of a root node is zero.
1806 {my ($node) = @_; # Node.
1807 my $a = 0;
1808 for(my $x = $node->parent; $x; $x = $x->parent) {++$a} # Up through parents
1809 $a # Return depth
1810 }
1811  
1812 sub depthProfile($) #U Returns the depth profile of the tree rooted at the specified B<$node>.
1813 {my ($node) = @_; # Node.
1814 my @d; # Depth profile as an array
1815 $node->by(sub # Each node
1816 {push @d, scalar @_; # Depth of node
1817 });
1818 return @d if wantarray; # Depth profile as an array
1819 join ' ', @d # Depth profile as a string
1820 }
1821  
1822 sub setDepthProfile($) #U Sets the L<depthProfile|/depthProfile> for every node in the specified B<$tree>. The last set L<depthProfile|/depthProfile> for a specific node can be retrieved from L<depthProfileLast|/depthProfileLast>.
1823 {my ($tree) = @_; # Tree of nodes.
1824 $tree->by(sub # Each node
1825 {$_->depthProfileLast = $_->depthProfile; # Set depth profile for node.
1826 });
1827 $tree
1828 }
1829  
1830 sub height($) #U Returns the height of the tree rooted at the specified B<$node>.
1831 {my ($node) = @_; # Node.
1832 my $h = 0; # Height of tree so far
1833 $node->by(sub # Each node
1834 {$h = scalar(@_) if scalar(@_) > $h; # Highest height so far
1835 });
1836 $h # Return height
1837 }
1838  
1839 sub isFirst($@) #BCYU Return the specified B<$node> if it is first under its parent and optionally has the specified context, else return B<undef>
1840 {my ($node, @context) = @_; # Node, optional context
1841 return undef if @context and !$node->at(@context); # Not in specified context
1842 my $parent = $node->parent; # Parent
1843 return $node unless defined($parent); # The top most node is always first
1844 $node == $parent->first ? $node : undef # First under parent
1845 }
1846 #a isLast
1847 #b <b/><c><d/></c><e/>
1848 #c isFirst
1849 #c set id first
1850 #d Continue if we are at a first child.
1851  
1852 sub isNotFirst($@) #CU Return the specified B<$node> if it is not first under its parent and optionally has the specified context, else return B<undef>
1853 {my ($node, @context) = @_; # Node, optional context
1854 return undef if @context and !$node->at(@context); # Not in specified context
1855 my $parent = $node->parent; # Parent
1856 return undef unless defined($parent); # The top most node is always first
1857 $node != $parent->first ? $node : undef # Not first under parent
1858 }
1859 #a isNotFirst
1860 #b <b/><c><d/></c><e/>
1861 #c isNotFirst
1862 #c set id notFirst
1863 #d Continue if we are not at a first child.
1864  
1865 sub isFirstN($$@) #CU Return the first B<$N> nodes as an array if the first B<$N> tags of the parent of B<$node> finish at the specified B<$node> and have the specified tags in the sequence specified by B<@context>. If B<@context> contains more then B<$N> entries, the remainder are checked as the context of the parent of B<$node>. Returns an array of nodes found or an empty array if the specified B<$node> does not match these conditions.
1866 {my ($node, $N, @context) = @_; # Node, number of tags to be first, first tags and optional context
1867 return () unless my $parent = $node->parent; # Must have a parent
1868 @context >= $N or confess "Not enough context"; # Must have enough tags to match N
1869 my @tags; push @tags, shift @context for 1..$N; # Separate context into first n tags and parent context
1870 return () if @context and !$parent->at(@context); # Not in specified context
1871 my @nodes = $parent->contents; # Parent content
1872 pop @nodes while @nodes and $nodes[-1] != $node; # Remove following nodes
1873 return () unless @nodes == $N; # Nodes are not first
1874 for(1..$N) # Confirm tags match
1875 {next if $nodes[-$_]->tag eq $tags[-$_]; # Confirm tag matches
1876 return () # Return empty list as tags failed to match
1877 }
1878 @nodes # Return matching nodes on success
1879 }
1880  
1881 sub isFirstToDepth($$@) #CU Return the specified B<$node> if it is first to the specified depth else return B<undef>
1882 {my ($node, $depth, @context) = @_; # Node, depth, optional context
1883 return undef if @context and !$node->at(@context); # Not in specified context
1884 my $p = $node; # Start
1885 for(1..$depth-1) # Check each ancestor is first to the specified depth but one
1886 {return undef unless $p->isFirst and $p = $p->parent; # Check node is first and that we can move up
1887 }
1888 $p->isFirst # Confirm that the last ancestor so reached is a first node
1889 }
1890  
1891 sub firstIs($@) #CU Return the specified B<$node> if it has one or more child nodes and the first child node has the specified B<@context> otherwise B<undef>.
1892 {my ($node, @context) = @_; # Node, optional context
1893 return undef unless my $first = $node->first; # Must have a first child
1894 return undef if @context and !$first->at(@context); # First child must match any supplied context
1895 $node # Success
1896 }
1897 #a firstIs
1898 #b <b><c><d/><e/></c></b>
1899 #c firstIs d
1900 #c set id yes
1901 #d Continue if there is a first child with the specified context
1902  
1903 sub isLast($@) #BCYU Return the specified B<$node> if it is last under its parent and optionally has the specified context, else return B<undef>
1904 {my ($node, @context) = @_; # Node, optional context
1905 return undef if @context and !$node->at(@context); # Not in specified context
1906 my $parent = $node->parent; # Parent
1907 return $node unless defined($parent); # The top most node is always last
1908 $node == $parent->last ? $node : undef # Last under parent
1909 }
1910 #a isFirst
1911 #b <b/><c><d/></c><e/>
1912 #c isLast
1913 #c set id last
1914 #d Continue if we are at a last child.
1915  
1916 sub isNotLast($@) #CU Return the specified B<$node> if it is not last under its parent and optionally has the specified context, else return B<undef>
1917 {my ($node, @context) = @_; # Node, optional context
1918 return undef if @context and !$node->at(@context); # Not in specified context
1919 my $parent = $node->parent; # Parent
1920 return undef unless defined($parent); # The top most node is always last
1921 $node != $parent->last ? $node : undef # Not last under parent
1922 }
1923 #a isLast isNotFirst
1924 #b <b/><c><d/></c><e/>
1925 #c isNotLast
1926 #c set id notLast
1927 #d Continue if we are not at a last child.
1928  
1929 sub isLastN($$@) #CU Return the last B<$N> nodes as an array if the last B<$N> tags of the parent of B<$node> start at the specified B<$node> and have the specified tags in the sequence specified by B<@context>. If B<@context> contains more then B<$N> entries, the remainder are checked as the context of the parent of B<$node>. Returns an array of nodes found or an empty array if the specified B<$node> does not match these conditions.
1930 {my ($node, $N, @context) = @_; # Node, number of tags to be last, last tags and optional context
1931 return () unless my $parent = $node->parent; # Must have a parent
1932 @context >= $N or confess "Not enough context"; # Must have enough tags to match N
1933 my @tags; push @tags, shift @context for 1..$N; # Separate context into last n tags and parent context
1934 return () if @context and !$parent->at(@context); # Not in specified context
1935 my @nodes = $parent->contents; # Parent content
1936 shift @nodes while @nodes and $nodes[0] != $node; # Remove preceding nodes
1937 return () unless @nodes == $N; # Nodes are not last
1938 for(1..$N) # Confirm tags match
1939 {next if $nodes[-$_]->tag eq $tags[-$_]; # Confirm tag matches
1940 return () # Return empty list as tags failed to match
1941 }
1942 @nodes # Return matching nodes on success
1943 }
1944  
1945 sub isLastToDepth($$@) #CU Return the specified B<$node> if it is last to the specified depth else return B<undef>
1946 {my ($node, $depth, @context) = @_; # Node, depth, optional context
1947 return undef if @context and !$node->at(@context); # Not in specified context
1948 my $p = $node; # Start
1949 for(1..$depth-1) # Check each ancestor is last to the specified depth but one
1950 {return undef unless $p->isLast and $p = $p->parent; # Check node is last and that we can move up
1951 }
1952 $p->isLast ? $node : undef # Confirm that the last ancestor so reached is a last node
1953 }
1954  
1955 sub lastIs($@) #CU Return the specified B<$node> if it has one or more child nodes and the last child node has the specified B<@context> otherwise B<undef>.
1956 {my ($node, @context) = @_; # Node, optional context
1957 return undef unless my $last = $node->last; # Must have a last child
1958 return undef if @context and !$last->at(@context); # Last child must match any supplied context
1959 $node # Success
1960 }
1961 #a lastIs
1962 #b <b><c><d/><e/></c></b>
1963 #c lastIs e
1964 #c set id yes
1965 #d Continue if there is a last child with the specified context
1966  
1967 sub nextIs($@) #CU Return the specified B<$node> if there is a following node with the specified B<@context>. Returns B<undef> if the $node is last.
1968 {my ($node, @context) = @_; # Node, optional context
1969 return undef unless my $next = $node->next; # Must have a following node
1970 return undef if @context and !$next->at(@context); # Following node must match any supplied context
1971 $node # Success
1972 }
1973 #a nextIs
1974 #b <b/><c/><d/><e/>
1975 #c nextIs d
1976 #c set id yes
1977 #d Continue if the following node has the expected context
1978  
1979 sub nextN($$@) #CU Return B<$N> nodes as an array starting at B<$node> inclusive if they match the first B<$N> tags of B<@context>. If B<@context> contains more then B<$N> entries, the remainder are checked as the context of the parent of B<$node>. Returns an array of nodes found or an empty array if the specified B<$node> does not match these conditions.
1980 {my ($node, $N, @context) = @_; # Node, number of tags to be last, last tags and optional context
1981 return () unless my $parent = $node->parent; # Must have a parent
1982 @context >= $N or confess "Not enough context"; # Must have enough tags to match N
1983 my @tags; push @tags, shift @context for 1..$N; # Separate context into last n tags and parent context
1984 return () if @context and !$parent->at(@context); # Not in specified context
1985 my @nodes = $parent->contents; # Parent content
1986 shift @nodes while @nodes and $nodes[0] != $node; # Remove preceding nodes
1987 return () unless @nodes >= $N; # Enough nodes to match
1988 pop @nodes while @nodes and @nodes > $N; # Nodes requested
1989 for(1..$N) # Confirm tags match
1990 {next if $nodes[-$_]->tag eq $tags[-$_]; # Confirm tag matches
1991 return () # Return empty list as tags failed to match
1992 }
1993 @nodes # Return matching nodes on success
1994 }
1995  
1996 sub prevIs($@) #CU Return the specified B<$node> if there is a previous node with the specified B<@context>. Returns B<undef> if the $node is first.
1997 {my ($node, @context) = @_; # Node, optional context
1998 return undef unless my $prev = $node->prev; # Must have a previous node
1999 return undef if @context and !$prev->at(@context); # Previous node must match any supplied context
2000 $node # Success
2001 }
2002 #a prevIs
2003 #b <b/><c/><d/><e/>
2004 #c prevIs c
2005 #c set id yes
2006 #d Continue if the previous node has the expected context
2007  
2008 sub prevN($$@) #CU Return B<$N> nodes as an array ending at B<$node> inclusive if they match the first B<$N> tags of B<@context>. If B<@context> contains more then B<$N> entries, the remainder are checked as the context of the parent of B<$node>. Returns an array of nodes found or an empty array if the specified B<$node> does not match these conditions.
2009 {my ($node, $N, @context) = @_; # Node, number of tags to be first, first tags and optional context
2010 return () unless my $parent = $node->parent; # Must have a parent
2011 @context >= $N or confess "Not enough context"; # Must have enough tags to match N
2012 my @tags; push @tags, shift @context for 1..$N; # Separate context into first n tags and parent context
2013 return () if @context and !$parent->at(@context); # Not in specified context
2014 my @nodes = $parent->contents; # Parent content
2015 pop @nodes while @nodes and $nodes[-1] != $node; # Remove following nodes
2016 return () unless @nodes >= $N; # Nodes are not first
2017 shift @nodes while @nodes and @nodes > $N; # Nodes requested
2018 for(1..$N) # Confirm tags match
2019 {next if $nodes[-$_]->tag eq $tags[-$_]; # Confirm tag matches
2020 return () # Return empty list as tags failed to match
2021 }
2022 @nodes # Return matching nodes on success
2023 }
2024  
2025 sub isOnlyChild($@) #CYU Return the specified B<$node> if it is the only node under its parent ignoring any surrounding blank text.
2026 {my ($node, @context) = @_; # Node, optional context
2027 return undef if @context and !$node->at(@context); # Not in specified context
2028 my $parent = $node->parent; # Find parent
2029 return $node unless $parent; # The root node is an only child
2030 my @c = $parent->contents; # Contents of parent
2031 return $node if @c == 1; # Only child if only one child
2032 shift @c while @c and $c[ 0]->isBlankText; # Ignore leading blank text
2033 pop @c while @c and $c[-1]->isBlankText; # Ignore trailing blank text
2034 return $node if @c == 1; # Only child if only one child after leading and trailing blank text has been ignored
2035 undef # Not the only child
2036 }
2037 #a isOnlyChild
2038 #b <b><c/></b><d><e/><e/></d>
2039 #c isOnlyChild
2040 #c set id onlyChild
2041 #d Continue if we are at an only child.
2042  
2043 sub isOnlyChildToDepth($$@) #CU Return the specified B<$node> if it and its ancestors are L<only children|/isOnlyChild> to the specified depth else return B<undef>. L<isOnlyChildToDepth(1)|/isOnlyChildToDepth> is the same as L<isOnlychild|/isOnlyChild>
2044 {my ($node, $depth, @context) = @_; # Node, depth to which each parent node must also be an only child, optional context
2045 return undef if @context and !$node->at(@context); # Not in specified context
2046 my $p = $node; # Walk up through ancestors
2047 for(1..$depth-1) # Walk up through ancestors to the specified depth but one
2048 {return undef unless $p->isOnlyChild and $p = $p->parent; # Confirm we are an only child and can move up one more level
2049 }
2050 $p->isOnlyChild; # Confirm that we are still on an only child
2051 }
2052  
2053 sub isOnlyChildN($$@) #CU Return the specified B<$node> if it is an only child of B<$depth> ancestors with L<only children|/hasSingleChild> in the optional B<@context> else return B<undef>. L<isOnlyChildN(1)|/isOnlyChildN> is the same as L<isOnlychild|/isOnlyChild>.
2054 {my ($node, $depth, @context) = @_; # Node, depth to which each parent node must also be an only child, optional context
2055 return undef if @context and !$node->at(@context); # Not in specified context
2056 my $p = $node; # Walk up through ancestors
2057 for(1..$depth-1) # Walk up through ancestors to the specified depth but one
2058 {return undef unless $p->isOnlyChild and $p = $p->parent; # Confirm we are an only child and can move up one more level
2059 }
2060 $p->isOnlyChild ? $node : undef # Confirm that we are still on an only child
2061 }
2062  
2063 sub isOnlyChildText($@) #CU Return the specified B<$node> if it is a text node and it is an only child else and its parent is in the specified optional context else return B<undef>.
2064 {my ($node, @context) = @_; # Node, optional context
2065 if (my $parent = $node->parent) # Parent required
2066 {return undef if @context and !$parent->at(@context); # Not in specified context
2067 return $node if $node->isText and $node->isOnlyChild; # Confirm that the node is a text node and an only child
2068 }
2069 undef # No parent so cannot be an only child
2070 }
2071  
2072 sub hasSingleChild($@) #CYU Return the only child of the specified B<$node> if the child is the only node under its parent ignoring any surrounding blank text and has the optional specified context, else return B<undef>.
2073 {my ($node, @context) = @_; # Node, optional context
2074 return undef unless my $child = $node->first(@context); # A possible child node
2075 return undef unless $child->isOnlyChild; # Not an only child
2076 $child # Return the only child
2077 }
2078 #a hasSingleChild
2079 #b <b><c/></b><d><e/><e/></d>
2080 #c hasSingleChild
2081 #c set id hasSingleChild
2082 #d Continue if we have a single child.
2083  
2084 sub hasSingleChildText($@) #CU Return the only child of the specified B<$node> if the child is a text node and the child is the only node under its parent ignoring any surrounding blank text and the child has the optional specified context, else return B<undef>.
2085 {my ($node, @context) = @_; # Node, optional context
2086 return undef unless my $child = $node->hasSingleChild(@context); # A possible single child node
2087 return undef unless $child->isText; # Not a text node
2088 $child # Return the only text child
2089 }
2090  
2091 sub hasSingleChildToDepth($$@) #CU Return the descendant of the specified B<$node> if it has single children to the specified depth in the specified optional B<@context> else return B<undef>. L<hasSingleChildToDepth(0)|/hasSingleChildToDepth> is equivalent to L<hasSingleChild|/hasSingleChild>.
2092 {my ($node, $depth, @context) = @_; # Node, depth, optional context
2093 return $node->isOnlyChild if $depth < 1; # Validate depth
2094 my $c = 0; # Depth count
2095 my $p; # Current position
2096 for
2097 ($p = $node->first; # Descend firstly
2098 $p and $p->isOnlyChild and ++$c < $depth;
2099 $p = $p->first)
2100 {}
2101 $p ? $p->isOnlyChild(@context) : $p # Check the context of the descendant single child
2102 }
2103  
2104 sub isEmpty($@) #CYU Confirm that the specified B<$node> is empty, that is: the specified B<$node> has no content, not even a blank string of text. To test for blank nodes, see L<isAllBlankText|/isAllBlankText>.
2105 {my ($node, @context) = @_; # Node, optional context
2106 return undef if @context and !$node->at(@context); # Not in specified context
2107 !$node->first ? $node : undef # If it has no first descendant it must be empty
2108 }
2109 #a cutIfEmpty
2110 #b <b><c/></b>
2111 #c isEmpty
2112 #c set id empty
2113 #d Continue if we have no children.
2114  
2115 sub hasContent($@) #CYU Confirm that the specified B<$node> has content. Return the specified node if it has content else return B<undef> if it does not.
2116 {my ($node, @context) = @_; # Node, optional context
2117 return undef if @context and !$node->at(@context); # Not in specified context
2118 $node->first ? $node : undef # If it has a first descendant it has content
2119 }
2120 #a hasContent
2121 #b <b><c/></b>
2122 #c hasContent
2123 #c set id yes
2124 #d Continue if we have children.
2125  
2126 sub over($$@) #CYU Confirm that the string representing the tags at the level below the specified B<$node> match a regular expression where each pair of tags is separated by a single space. Use L<contentAsTags|/contentAsTags> to visualize the tags at the next level.
2127 {my ($node, $re, @context) = @_; # Node, regular expression, optional context.
2128 return undef if @context and !$node->at(@context); # Not in specified context
2129 $node->contentAsTags =~ m/$re/ ? $node : undef
2130 }
2131  
2132 sub over2($$@) #CYU Confirm that the string representing the tags at the level below the specified B<$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 L<contentAsTags2|/contentAsTags2> to visualize the tags at the next level.
2133 {my ($node, $re, @context) = @_; # Node, regular expression, optional context.
2134 return undef if @context and !$node->at(@context); # Not in specified context
2135 $node->contentAsTags2 =~ m/$re/ ? $node : undef
2136 }
2137 #a over
2138 #b <b><c/><c/></b><b><c/></b>
2139 #c over2 \A(\sc\s){2}\Z
2140 #c set id over2
2141 #d Continue if our children's tag match a regular expression.
2142  
2143 sub overAllTags($@) #U Return the specified b<$node> if all of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
2144 {my ($node, @tags) = @_; # Node, tags.
2145 my @c = $node->contents; # Node contents
2146 while(@tags and @c) # Match node contents against tags
2147 {return undef unless atPositionMatch(-t shift @c, shift @tags); # Continue unless we fail to match
2148 }
2149 return $node if @c == 0 and @tags == 0; # Child nodes and tags matched exactly
2150 undef # Wrong number of tags
2151 }
2152  
2153 BEGIN{*oat=*overAllTags}
2154  
2155 sub overFirstTags($@) #U Return the specified b<$node> if the first of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
2156 {my ($node, @tags) = @_; # Node, tags.
2157 my @c = $node->contents; # Node contents
2158 while(@tags and @c) # Match node contents against tags
2159 {return undef unless atPositionMatch(-t shift @c, shift @tags); # Continue unless we fail to match
2160 }
2161 return $node if @c >= 0 and @tags == 0; # The first child nodes match the specified tags
2162 undef # Wrong number of tags
2163 }
2164  
2165 BEGIN{*oft=*overFirstTags}
2166  
2167 sub overLastTags($@) #U Return the specified b<$node> if the last of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
2168 {my ($node, @tags) = @_; # Node, tags.
2169 my @c = $node->contents; # Node contents
2170 while(@tags and @c) # Match node contents against tags
2171 {return undef unless atPositionMatch(-t pop @c, pop @tags); # Continue unless we fail to match
2172 }
2173 return $node if @c >= 0 and @tags == 0; # The last child nodes match the specified tags
2174 undef # Wrong number of tags
2175 }
2176  
2177 BEGIN{*olt=*overLastTags}
2178  
2179 sub matchAfter($$@) #CY Confirm that the string representing the tags following the specified B<$node> matches a regular expression where each pair of tags is separated by a single space. Use L<contentAfterAsTags|/contentAfterAsTags> to visualize these tags.
2180 {my ($node, $re, @context) = @_; # Node, regular expression, optional context.
2181 return undef if @context and !$node->at(@context); # Not in specified context
2182 $node->contentAfterAsTags =~ m/$re/ ? $node : undef
2183 }
2184  
2185 sub matchAfter2($$@) #CY Confirm that the string representing the tags following the specified B<$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 L<contentAfterAsTags2|/contentAfterAsTags2> to visualize these tags.
2186 {my ($node, $re, @context) = @_; # Node, regular expression, optional context.
2187 return undef if @context and !$node->at(@context); # Not in specified context
2188 $node->contentAfterAsTags2 =~ m/$re/ ? $node : undef
2189 }
2190  
2191 sub matchBefore($$@) #CY Confirm that the string representing the tags preceding the specified B<$node> matches a regular expression where each pair of tags is separated by a single space. Use L<contentBeforeAsTags|/contentBeforeAsTags> to visualize these tags.
2192 {my ($node, $re, @context) = @_; # Node, regular expression, optional context.
2193 return undef if @context and !$node->at(@context); # Not in specified context
2194 $node->contentBeforeAsTags =~ m/$re/ ? $node : undef
2195 }
2196  
2197 sub matchBefore2($$@) #CY Confirm that the string representing the tags preceding the specified B<$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 L<contentBeforeAsTags2|/contentBeforeAsTags2> to visualize these tags.
2198 {my ($node, $re, @context) = @_; # Node, regular expression, optional context.
2199 return undef if @context and !$node->at(@context); # Not in specified context
2200 $node->contentBeforeAsTags2 =~ m/$re/ ? $node : undef
2201 }
2202  
2203 sub parentage($) #U Return a reference to an array of the nodes along the path from the root to the specified B<$Node> inclusive.
2204 {my ($node) = @_; # Node.
2205 my @p; # Path
2206 for(my $p = $node; $p; $p = $p->parent) # Go up
2207 {push @p, $p; # Save position
2208 }
2209 [reverse @p] # Return path from root
2210 }
2211  
2212 BEGIN{*p=*parentage}
2213  
2214 sub path($) #U Return a list of strings representing the path to a node from the root of the parse tree which can then be reused by L<go|/go> to retrieve the node as long as the structure of the L<parse|/parse> tree has not changed along the path.
2215 {my ($node) = @_; # Node.
2216 my @p; # Path
2217 for(my $p = $node; $p and $p->parent; $p = $p->parent) # Go up
2218 {my $i = $p->index; # Position in parent index
2219 push @p, $i if $i; # Save position unless default
2220 push @p, $p->tag; # Save index
2221 }
2222 reverse @p # Return path from root
2223 }
2224  
2225 sub pathString($) #bU Return a string representing the L<path|/path> to the specified B<$node> from the root of the parse tree.
2226 {my ($node) = @_; # Node.
2227 join ' ', path($node) # String representation
2228 }
2229  
2230 #D2 Match # Locate adjacent nodes that match horizontally and vertically
2231  
2232 sub an($$@) #CU Return the next node if the specified B<$node> has the tag specified by B<$current> and the next node is in the specified B<@context>.
2233 {my ($node, $current, @context) = @_; # Node, tag node must match, optional context of the next node.
2234 return undef unless $node->at($current); # Check node has the right tag
2235 $node->next(@context) # Next node if it matches the context else B<undef>
2236 }
2237  
2238 sub ap($$@) #CU Return the previous node if the specified B<$node> has the tag specified by B<$current> and the previous node is in the specified B<@context>.
2239 {my ($node, $current, @context) = @_; # Node, tag node must match, optional context of the previous node.
2240 return undef unless $node->at($current); # Check node has the right tag
2241 $node->prev(@context) # Previous node if it matches the context else B<undef>
2242 }
2243  
2244 sub apn($$$@) #KU Return (previous node, next node) if the B<$previous> and B<$current> nodes have the specified tags and the next node is in the specified B<@context> else return B<()>. The specified B<@context> must have at least one element otherwise B<()> is returned.
2245 {my ($node, $prev, $current, @context) = @_; # Current node, tag for the previous node, tag for specified node, context for the next node.
2246 return () if !@context or !$node->at($current) or # Check context
2247 $node->isLast or $node->isFirst; # Check existence of surrounding nodes
2248 my $p = $node->prev($prev); # Previous node
2249 my $n = $node->next(@context); # Next node
2250 return ($p, $n) if $p and $n; # Successful match
2251 () # Match failed
2252 }
2253  
2254 sub matchesFirst($@) #U Return the specified B<$node> if its children L<match|/atPositionMatch> the specified <@sequence> forwards from the first child else return B<undef>.
2255 {my ($node, @sequence) = @_; # Node, sequence.
2256 my @c = $node->contents; # Child nodes
2257 while(@sequence and @c) # Match node contents against tags
2258 {return undef unless atPositionMatch(-t shift @c, shift @sequence); # Continue unless we fail to match
2259 }
2260 return $node unless @sequence; # The following nodes match the specified tags
2261 undef # Wrong number of tags
2262 }
2263  
2264 sub matchesLast($@) #U Return the specified B<$node> if its children L<match|/atPositionMatch> the specified <@sequence> backwards from the last child else return B<undef>.
2265 {my ($node, @sequence) = @_; # Node, sequence.
2266 my @c = reverse $node->contents; # Child nodes
2267 while(@sequence and @c) # Match node contents against tags
2268 {return undef unless atPositionMatch(-t shift @c, shift @sequence); # Continue unless we fail to match
2269 }
2270 return $node unless @sequence; # The following nodes match the specified tags
2271 undef # Wrong number of tags
2272 }
2273  
2274 sub matchesNext($@) #U Return the specified B<$node> if its following siblings L<match|/atPositionMatch> the specified <@sequence> else return B<undef>.
2275 {my ($node, @sequence) = @_; # Node, sequence.
2276 my @c = $node->contentAfter; # Following node
2277 while(@sequence and @c) # Match node contents against tags
2278 {return undef unless atPositionMatch(-t shift @c, shift @sequence); # Continue unless we fail to match
2279 }
2280 return $node unless @sequence; # The following nodes match the specified tags
2281 undef # Wrong number of tags
2282 }
2283  
2284 sub matchesPrev($@) #U Return the specified B<$node> if the siblings before $node L<match|/atPositionMatch> the specified <@sequence> with the first element of @sequence nearest to $node and the last element furthest else return B<undef>.
2285 {my ($node, @sequence) = @_; # Node, sequence.
2286 my @c = reverse $node->contentBefore; # Prior nodes
2287 while(@sequence and @c) # Match node contents against tags
2288 {return undef unless atPositionMatch(-t shift @c, shift @sequence); # Continue unless we fail to match
2289 }
2290 return $node unless @sequence; # The prior nodes match the specified tags
2291 undef # Wrong number of tags
2292 }
2293  
2294 #D2 Child of, Parent of, Sibling of # Nodes that are directly above, below or adjacent to another node.
2295  
2296 sub parentOf($$@) #C Returns the specified B<$parent> node if it is the parent of the specified B<$child> node and the B<$parent> node is in the specified optional context.
2297 {my ($parent, $child, @context) = @_; # Parent, child, optional context
2298 return undef if @context and !$parent->at(@context); # Check context
2299 return $parent if $child->parent == $parent; # Check child has the parent as its parent
2300 undef # Wrong parent
2301 }
2302  
2303 sub childOf($$@) #C Returns the specified B<$child> node if it is a child of the specified B<$parent> node and the B<$child> node is in the specified optional context.
2304 {my ($child, $parent, @context) = @_; # Child, parent, optional context
2305 return undef if @context and !$child->at(@context); # Check context
2306 return $child if $child->parent == $parent; # Check child has the parent as its parent
2307 undef # Wrong parent
2308 }
2309  
2310 sub succeedingSiblingOf($$@) #C Returns the specified B<$child> node if it has the same parent as B<$sibling> and occurs after B<$sibling> and has the optionally specified context else returns B<undef>.
2311 {my ($child, $sibling, @context) = @_; # Child, sibling thought to occur before child, optional context
2312 return undef if @context and !child->at(@context); # Check context
2313 return undef unless $child->parent == $sibling->parent; # Check child has the parent as its prior sibling
2314 $child->after($sibling); # Check child occurs after prior sibling
2315 }
2316  
2317 sub precedingSiblingOf($$@) #C Returns the specified B<$child> node if it has the same parent as B<$sibling> and occurs before B<$sibling> and has the optionally specified context else returns B<undef>.
2318 {my ($child, $sibling, @context) = @_; # Child, sibling thought to occur after child, optional context
2319 return undef if @context and !child->at(@context); # Check context
2320 return undef unless $child->parent == $sibling->parent; # Check child has the parent as its prior sibling
2321 $child->before($sibling); # Check child occurs after prior sibling
2322 }
2323  
2324 #D1 Navigation # Move around in the L<parse|/parse> tree.
2325  
2326 sub go($@) #IYU Return the node reached from the specified B<$node> via the specified L<path|/path>: (index positionB<?>)B<*> 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. B<*> can be used as the last position to retrieve all nodes with the final tag.
2327 {my ($node, @path) = @_; # Node, search specification.
2328 my $p = $node; # Current node
2329 while(@path) # Position specification
2330 {my $i = shift @path; # Index name
2331 return undef unless $p; # There is no node of the named type under this node
2332 reindexNode($p); # Create index for this node
2333 my $q = $p->indexes->{$i}; # Index
2334 return undef unless defined $q; # Complain if no such index
2335 if (@path) # Position within index
2336 {if ($path[0] =~ /\A([-+]?\d+)\Z/) # Numeric position in index from start
2337 {shift @path;
2338 $p = $q->[$1]
2339 }
2340 elsif (@path == 1 and $path[0] =~ /\A\*\Z/) # Final index wanted
2341 {return @$q;
2342 }
2343 else {$p = $q->[0]} # Step into first sub node by default
2344 }
2345 else {$p = $q->[0]} # Step into first sub node by default on last step
2346 }
2347 $p
2348 }
2349 #a up
2350 #b <b><c/><c><d/><d/><d/><d/></c><c/></b>
2351 #c go c 1 d 2
2352 #c set id arrived_here
2353 #d Follow a path from the current node.
2354 sub c($$) #U Return an array of all the nodes with the specified tag below the specified B<$node>.
2355 {my ($node, $tag) = @_; # Node, tag.
2356 reindexNode($node); # Create index for this node
2357 my $c = $node->indexes->{$tag}; # Index for specified tags
2358 $c ? @$c : () # Contents as an array
2359 }
2360  
2361 sub cText($) #U Return an array of all the text nodes immediately below the specified B<$node>.
2362 {my ($node) = @_; # Node.
2363 reindexNode($node); # Create index for this node
2364 $node->c(cdata); # Index for text data
2365 }
2366  
2367 sub findById($$) #U Find a node in the parse tree under the specified B<$node> with the specified B<$id>.
2368 {my ($node, $id) = @_; # Parse tree, id desired.
2369 my $i; # Node found
2370 eval {$node->by(sub # Look for an instance of such a node
2371 {if ($_->idX eq $id) {$i = $_; die} # Found the node - die to stop the search from going further
2372 })};
2373 $i # Node found if any
2374 }
2375  
2376 sub matchesNode($$@) # Return the B<$first> node if it matches the B<$second> node's tag and the specified B<@attributes> else return B<undef>.
2377 {my ($first, $second, @attributes) = @_; # First node, second node, attributes to match on
2378 return undef unless -t $first eq -t $second; # Check tags match
2379 my $f = $first->attributes; # Attributes for first node
2380 my $s = $second->attributes; # Attributes for second node
2381 for my $a(@attributes)
2382 {return undef unless defined($f->{$a}) and defined($s->{$a}) and
2383 $f->{$a} eq $s->{$a};
2384 }
2385 $first # Nodes match on specified attributes
2386 }
2387  
2388 sub matchesSubTree($$@) # Return the B<$first> node if it L<matches|/matchesNode> the B<$second> node and the nodes under the first node match the corresponding nodes under the second node, else return B<undef>.
2389 {my ($first, $second, @attributes) = @_; # First node, second node, attributes to match on
2390 return undef unless &matchesNode(@_); # Check nodes match
2391 my @f = @$first; # Children for first node
2392 my @s = @$second; # Children for second node
2393 return undef unless @f == @s; # Wrong number of children
2394 while(@f) # Match each child
2395 {return undef unless (shift @f)->matchesNode(shift @s, @attributes); # Children match
2396 }
2397 $first # Sub trees match
2398 }
2399  
2400 sub findMatchingSubTrees($$@) # Find nodes in the parse tree whose sub tree matches the specified B<$subTree> excluding any of the specified B<$attributes>.
2401 {my ($node, $subTree, @attributes) = @_; # Parse tree, parse tree to match, attributes to match on
2402 my @i; # Node found
2403 my $t = -t $subTree; # Quick reject
2404 $node->by(sub # Each node in the tree
2405 {return unless -t $_ eq $t; # Quick reject
2406 push @i, $_ if $_->matchesSubTree($subTree, @attributes); # Found a matching sub tree
2407 });
2408 @i # Node found if any
2409 }
2410  
2411 #D2 First # Find nodes that are first amongst their siblings.
2412  
2413 sub first($@) #BCYU Return the first node below the specified B<$node> optionally checking the first node's context. See L<addFirst|/addFirst> to ensure that an expected node is in position.
2414 {my ($node, @context) = @_; # Node, optional context.
2415 return $node->content->[0] unless @context; # Return first node if no context specified
2416 my ($c) = $node->contents; # First node
2417 $c ? $c->at(@context) : undef; # Return first node if in specified context
2418 }
2419 #a
2420 #b <b><c/></b><b><d/></b>
2421 #c at b
2422 #c first c
2423 #c set id firstChild
2424 #d Go to our first child optionally checking its context.
2425  
2426 sub firstn($$@) #CU Return the B<$n>'th first node below the specified B<$node> optionally checking its context or B<undef> if there is no such node. B<firstn(1)> is identical in effect to L<first|/first>.
2427 {my ($node, $N, @context) = @_; # Node, number of times to go first, optional context.
2428 return undef if @context and !$node->at(@context); # Check the context if supplied
2429 for(1..$N) # Go first the specified number of times
2430 {$node = $node->first; # Go first
2431 last unless $node; # Cannot go further
2432 }
2433 $node
2434 }
2435  
2436 sub firstText($@) #CU Return the first node under the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
2437 {my ($node, @context) = @_; # Node, optional context.
2438 return undef if @context and !$node->at(@context); # Check the context if supplied
2439 my $l = &first($node); # First node
2440 $l ? $l->isText : undef # Test whether the first node exists and is a text node
2441 }
2442  
2443 sub firstTextMatches($$@) #CU Return the first node under the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context. Else return B<undef>.
2444 {my ($node, $match, @context) = @_; # Node, regular expression the text must match, optional context of specified node.
2445 return undef if @context and !$node->at(@context); # Check context
2446 if (my $t = $node->firstText) # First node is text
2447 {return $t->matchesText($match); # First text node matches the specified regular expression
2448 }
2449 undef # First node is not text or does not match the specified regular expression
2450 }
2451  
2452 sub firstBy($@) #U Return a list of the first instance of each specified tag encountered in a post-order traversal from the specified B<$node> or a hash of all first instances if no tags are specified.
2453 {my ($node, @tags) = @_; # Node, tags to search for.
2454 my %tags; # Tags found first
2455 $node->byReverse(sub {$tags{$_->tag} = $_}); # Save first instance of each node
2456 return %tags unless @tags; # Return hash of all tags encountered first unless @tags filter was specified
2457 map {$tags{$_}} @tags; # Nodes in the requested order
2458 }
2459  
2460 sub firstDown($@) #U Return a list of the first instance of each specified tag encountered in a pre-order traversal from the specified B<$node> or a hash of all first instances if no tags are specified.
2461 {my ($node, @tags) = @_; # Node, tags to search for.
2462 my %tags; # Tags found first
2463 $node->downReverse(sub {$tags{$_->tag} = $_}); # Save first instance of each node
2464 return %tags unless @tags; # Return hash of all tags encountered first unless @tags filter was specified
2465 map {$tags{$_}} @tags; # Nodes in the requested order
2466 }
2467  
2468 sub firstIn($@) #YU Return the first child node matching one of the named tags under the specified parent node.
2469 {my ($node, @tags) = @_; # Parent node, child tags to search for.
2470 my %tags = map {$_=>1} @tags; # Hashify tags
2471 for($node->contents) # Search forwards through contents
2472 {return $_ if $tags{$_->tag}; # Find first tag with the specified name
2473 }
2474 return undef # No such node
2475 }
2476  
2477 sub firstNot($@) #U Return the first child node that does not match any of the named B<@tags> under the specified parent B<$node>. Return B<undef> if there is no such child node.
2478 {my ($node, @tags) = @_; # Parent node, child tags to avoid.
2479 my %tags = map {$_=>1} @tags; # Hashify tags
2480 for($node->contents) # Search forwards through contents
2481 {return $_ unless $tags{$_->tag}; # Find first tag that fails to match
2482 }
2483 return undef # No such node
2484 }
2485  
2486 sub firstInIndex($@) #CYU Return the specified B<$node> if it is first in its index and optionally L<at|/at> the specified context else B<undef>
2487 {my ($node, @context) = @_; # Node, optional context.
2488 return undef if @context and !$node->at(@context); # Check the context if supplied
2489 my $parent = $node->parent; # Parent
2490 return undef unless $parent; # The root node is not first in anything
2491 my @c = $parent->c($node->tag); # Index containing node
2492 @c && $c[0] == $node ? $node : undef # First in index ?
2493 }
2494  
2495 sub firstOf($@) #U Return an array of the nodes that are continuously first under their specified parent node and that match the specified list of tags.
2496 {my ($node, @tags) = @_; # Node, tags to search for.
2497 my %tags = map {$_=>1} @tags; # Hashify tags
2498 my @l; # Matching last nodes
2499 for($node->contents) # Search through contents
2500 {return @l unless $tags{$_->tag}; # Nonmatching tag
2501 push @l, $_; # Save continuously matching tag in correct order
2502 }
2503 return @l # All tags match
2504 }
2505  
2506 sub firstWhile($@) #U Go first from the specified B<$node> and continue deeper firstly as long as each first child node matches one of the specified B<@tags>. Return the deepest such node encountered or else return B<undef> if no such node is encountered.
2507 {my ($node, @tags) = @_; # Node, tags to search for.
2508 my %tags = map {$_=>1} @tags; # Hashify tags
2509 my $p; # Current position
2510 for(my $f = $node->first; $f and $tags{-t $f}; $f = $f->first) {$p = $f} # Go ever firstly
2511 $p
2512 }
2513  
2514 sub firstUntil($@) #CU Go first from the specified B<$node> and continue deeper firstly until a first child node matches the specified B<@context> or return B<undef> if there is no such node. Return the first child of the specified B<$node> if no B<@context> is specified.
2515 {my ($node, @context) = @_; # Node, context to search for.
2516 for(my $p = $node->first; $p; $p = $p->first) # Check each first child node below the B<$node>
2517 {return $p if $p->at(@context); # Return the node if it matches the specified context
2518 }
2519 undef
2520 }
2521  
2522 sub firstUntilText($@) #CU Go first from the specified B<$node> and continue deeper firstly until a text node is encountered whose parent matches the specified B<@context> or return B<undef> if there is no such node.
2523 {my ($node, @context) = @_; # Node, context to search for.
2524 for(my $p = $node->first; $p; $p = $p->first) # Check each first child node below the B<$node>
2525 {return $p if $p->isText and $p->parent->at(@context); # Return the node if it is text and its parent matches the specified context
2526 }
2527 undef
2528 }
2529  
2530 sub firstContextOf($@) #CYU Return the first node encountered in the specified context in a depth first post-order traversal of the L<parse|/parse> tree.
2531 {my ($node, @context) = @_; # Node, array of tags specifying context.
2532 my $x; # Found node if found
2533 eval # Trap the die which signals success
2534 {$node->by(sub # Traverse L<parse|/parse> tree in depth first order
2535 {my ($o) = @_;
2536 if ($o->at(@context)) # Does this node match the supplied context?
2537 {$x = $o; # Success
2538 die "success!"; # Halt the search
2539 }
2540 });
2541 };
2542 confess $@ if $@ and $@ !~ /success!/; # Report any suppressed error messages at this point
2543 $x # Return node found if we are still alive
2544 }
2545  
2546 sub firstSibling($@) #CYU Return the first sibling of the specified B<$node> in the optional B<@context> else B<undef>
2547 {my ($node, @context) = @_; # Node, array of tags specifying context.
2548 return undef if @context and !$node->at(@context); # Not in specified context
2549 my $p = $node->parent; # Parent node
2550 $p->first # Return first sibling
2551 }
2552  
2553 #D2 Last # Find nodes that are last amongst their siblings.
2554  
2555 sub last($@) #BCYU Return the last node below the specified B<$node> optionally checking the last node's context. See L<addLast|/addLast> to ensure that an expected node is in position.
2556 {my ($node, @context) = @_; # Node, optional context.
2557 return $node->content->[-1] unless @context; # Return last node if no context specified
2558 my ($c) = reverse $node->contents; # Last node
2559 $c ? $c->at(@context) : undef; # Return last node if in specified context
2560 }
2561 #a
2562 #b <b><c/><d/></b><b><c/></b>
2563 #c at b
2564 #c last d
2565 #c set id lastChild
2566 #d Go to our last child optionally checking its context.
2567  
2568 sub lastn($$@) #CU Return the B<$n>'th last node below the specified B<$node> optionally checking its context or B<undef> if there is no such node. B<lastn(1)> is identical in effect to L<last|/last>.
2569 {my ($node, $N, @context) = @_; # Node, number of times to go last, optional context.
2570 return undef if @context and !$node->at(@context); # Check the context if supplied
2571 for(1..$N) # Go last the specified number of times
2572 {$node = $node->last; # Go last
2573 last unless $node; # Cannot go further
2574 }
2575 $node
2576 }
2577  
2578 sub lastText($@) #CU Return the last node under the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
2579 {my ($node, @context) = @_; # Node, optional context.
2580 return undef if @context and !$node->at(@context); # Check the context if supplied
2581 my $l = &last($node); # Last node
2582 $l ? $l->isText : undef # Test whether the first node exists and is a text node
2583 }
2584  
2585 sub lastTextMatches($$@) #CU Return the last node under the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context. Else return B<undef>.
2586 {my ($node, $match, @context) = @_; # Node, regular expression the text must match, optional context of specified node.
2587 return undef if @context and !$node->at(@context); # Check context
2588 if (my $t = $node->lastText) # Last node is text
2589 {return $t->matchesText($match); # Last text node matches the specified regular expression
2590 }
2591 undef # Last node is not text or does not match the specified regular expression
2592 }
2593  
2594 sub lastBy($@) #U Return a list of the last instance of each specified tag encountered in a post-order traversal from the specified B<$node> or a hash of all last instances if no tags are specified.
2595 {my ($node, @tags) = @_; # Node, tags to search for.
2596 my %tags; # Tags found first
2597 $node->by(sub {$tags{$_->tag} = $_}); # Save last instance of each node
2598 return %tags unless @tags; # Return hash of all tags encountered last unless @tags filter was specified
2599 map {$tags{$_}} @tags; # Nodes in the requested order
2600 }
2601  
2602 sub lastDown($@) #U Return a list of the last instance of each specified tag encountered in a pre-order traversal from the specified B<$node> or a hash of all last instances if no tags are specified.
2603 {my ($node, @tags) = @_; # Node, tags to search for.
2604 my %tags; # Tags found first
2605 $node->down(sub {$tags{$_->tag} = $_}); # Save last instance of each node
2606 return %tags unless @tags; # Return hash of all tags encountered last unless @tags filter was specified
2607 map {$tags{$_}} @tags; # Nodes in the requested order
2608 }
2609  
2610 sub lastIn($@) #YU Return the last child node matching one of the named tags under the specified parent node.
2611 {my ($node, @tags) = @_; # Parent node, child tags to search for.
2612 my %tags = map {$_=>1} @tags; # Hashify tags
2613 for(reverse $node->contents) # Search backwards through contents
2614 {return $_ if $tags{$_->tag}; # Find last tag with the specified name
2615 }
2616 return undef # No such node
2617 }
2618  
2619 sub lastNot($@) #U Return the last child node that does not match any of the named B<@tags> under the specified parent B<$node>. Return B<undef> if there is no such child node.
2620 {my ($node, @tags) = @_; # Parent node, child tags to avoid.
2621 my %tags = map {$_=>1} @tags; # Hashify tags
2622 for(reverse $node->contents) # Search backwards through contents
2623 {return $_ unless $tags{$_->tag}; # Find last tag that fails to match
2624 }
2625 return undef # No such node
2626 }
2627  
2628 sub lastOf($@) #U Return an array of the nodes that are continuously last under their specified parent node and that match the specified list of tags.
2629 {my ($node, @tags) = @_; # Node, tags to search for.
2630 my %tags = map {$_=>1} @tags; # Hashify tags
2631 my @l; # Matching last nodes
2632 for(reverse $node->contents) # Search backwards through contents
2633 {return @l unless $tags{$_->tag}; # Nonmatching tag
2634 unshift @l, $_; # Save continuously matching tag in correct order
2635 }
2636 return
2637 @l # All tags match
2638 }
2639  
2640 sub lastInIndex($@) #CYU Return the specified B<$node> if it is last in its index and optionally L<at|/at> the specified context else B<undef>
2641 {my ($node, @context) = @_; # Node, optional context.
2642 return undef if @context and !$node->at(@context); # Check the context if supplied
2643 my $parent = $node->parent; # Parent
2644 return undef unless $parent; # The root node is not first in anything
2645 my @c = $parent->c($node->tag); # Index containing node
2646 @c && $c[-1] == $node ? $node : undef # Last in index ?
2647 }
2648  
2649 sub lastContextOf($@) #CYU Return the last node encountered in the specified context in a depth first reverse pre-order traversal of the L<parse|/parse> tree.
2650 {my ($node, @context) = @_; # Node, array of tags specifying context.
2651 my $x; # Found node if found
2652 eval # Trap the die which signals success
2653 {$node->downReverse(sub # Traverse L<parse|/parse> tree in depth first order
2654 {my ($o) = @_;
2655 if ($o->at(@context)) # Does this node match the supplied context?
2656 {$x = $o; # Success
2657 die "success!"; # Halt the search
2658 }
2659 });
2660 };
2661 confess $@ if $@ and $@ !~ /success!/; # Report any suppressed error messages at this point
2662 $x # Return node found if we are still alive
2663 }
2664  
2665 sub lastSibling($@) #CYU Return the last sibling of the specified B<$node> in the optional B<@context> else B<undef>
2666 {my ($node, @context) = @_; # Node, array of tags specifying context.
2667 return undef if @context and !$node->at(@context); # Not in specified context
2668 my $p = $node->parent; # Parent node
2669 $p->last # Return last sibling
2670 }
2671  
2672 sub lastWhile($@) #U Go last from the specified B<$node> and continue deeper lastly as long as each last child node matches one of the specified B<@tags>. Return the deepest such node encountered or else return B<undef> if no such node is encountered.
2673 {my ($node, @tags) = @_; # Node, tags to search for.
2674 my %tags = map {$_=>1} @tags; # Hashify tags
2675 my $p; # Current position
2676 for(my $l = $node->last; $l and $tags{-t $l}; $l = $l->first) {$p = $l} # Go ever lastly
2677 $p
2678 }
2679  
2680 sub lastUntil($@) #CU Go last from the specified B<$node> and continue deeper lastly until a last child node matches the specified B<@context> or return B<undef> if there is no such node. Return the last child of the specified B<$node> if no B<@context> is specified.
2681 {my ($node, @context) = @_; # Node, context to search for.
2682 for(my $p = $node->last; $p; $p = $p->last) # Check each last child node below the B<$node>
2683 {return $p if $p->at(@context); # Return the node if it matches the specified context
2684 }
2685 undef
2686 }
2687  
2688 sub lastUntilText($@) #CU Go last from the specified B<$node> and continue deeper lastly until a last child text node matches the specified B<@context> or return B<undef> if there is no such node.
2689 {my ($node, @context) = @_; # Node, context to search for.
2690 for(my $p = $node->last; $p; $p = $p->last) # Check each last child node below the B<$node>
2691 {return $p if $p->isText and $p->parent->at(@context); # Return the node if it matches the specified context
2692 }
2693 undef
2694 }
2695  
2696 #D2 Next # Find sibling nodes after the specified B<$node>.
2697  
2698 sub next($@) #BCYU Return the node next to the specified B<$node>, optionally checking the next node's context. See L<addNext|/addNext> to ensure that an expected node is in position.
2699 {my ($node, @context) = @_; # Node, optional context.
2700 return undef if $node->isLast; # No node follows the last node at a level or the top most node
2701 my @c = $node->parent->contents; # Content array of parent
2702 while(@c) # Test until no more nodes left to test
2703 {my $c = shift @c; # Each node
2704 if ($c == $node) # Current node
2705 {my $n = shift @c; # Next node
2706 return undef if @context and !$n->at(@context); # Next node is not in specified context
2707 return $n; # Found node
2708 }
2709 }
2710 confess "Node not found in parent"; # Something wrong with parent/child relationship
2711 }
2712 #a isFirst
2713 #b <b/><c/><b/><d/>
2714 #c at b
2715 #c next c
2716 #c set id c_after_b
2717 #d Go to the next sibling optionally checking its context.
2718  
2719 sub nextn($$@) #CU Return the B<$n>'th next node after the specified B<$node> optionally checking its context or B<undef> if there is no such node. B<nextn(1)> is identical in effect to L<next|/next>.
2720 {my ($node, $N, @context) = @_; # Node, number of times to go next, optional context.
2721 return undef if @context and !$node->at(@context); # Check the context if supplied
2722 for(1..$N) # Go next the specified number of times
2723 {$node = $node->next; # Go next
2724 last unless $node; # Cannot go further
2725 }
2726 $node
2727 }
2728  
2729 sub nextText($@) #CU Return the node after the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
2730 {my ($node, @context) = @_; # Node, optional context.
2731 return undef if @context and !$node->at(@context); # Check the context if supplied
2732 my $l = &next($node); # Next node
2733 $l ? $l->isText : undef # Test whether the first node exists and is a text node
2734 }
2735  
2736 sub nextTextMatches($$@) #CU Return the next node to the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context. Else return B<undef>.
2737 {my ($node, $match, @context) = @_; # Node, regular expression the text must match, optional context of specified node.
2738 return undef if @context and !$node->at(@context); # Check context
2739 if (my $t = $node->nextText) # Next node is text
2740 {return $t->matchesText($match); # Next text node matches the specified regular expression
2741 }
2742 undef # Next node is not text or does not match the specified regular expression
2743 }
2744  
2745 sub nextIn($@) #YU Return the nearest sibling after the specified B<$node> that matches one of the named tags or B<undef> if there is no such sibling node.
2746 {my ($node, @tags) = @_; # Node, tags to search for.
2747 my %tags = map {$_=>1} @tags; # Hashify tags
2748 my $parent = $node->parent; # Parent node
2749 return undef unless $parent; # No nodes follow the root node
2750 my @c = $parent->contents; # Search forwards through contents
2751 shift @c while @c and $c[0] != $node; # Move up to starting node
2752 shift @c; # Move over starting node
2753 for(@c) # Each subsequent node
2754 {return $_ if $tags{$_->tag}; # Find first tag with the specified name in the remaining nodes
2755 }
2756 return undef # No such node
2757 }
2758  
2759 sub nextOn($@) #U Step forwards as far as possible from the specified B<$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.
2760 {my ($node, @tags) = @_; # Start node, tags identifying nodes that can be step on to context.
2761 return wantarray ? ($node) : $node if $node->isLast; # Easy case
2762 my $parent = $node->parent; # Parent node
2763 confess "No parent" unless $parent; # Not possible on a root node
2764 my @c = $parent->contents; # Content
2765 shift @c while @c and $c[0] != $node; # Position on current node
2766 confess "Node not found in parent" unless @c; # Something wrong with parent/child relationship
2767 my %tags = map {$_=>1} @tags; # Hashify tags of acceptable commands
2768 if (wantarray) # Return node and following matching nodes if array wanted
2769 {my @a = (shift @c);
2770 push @a, shift @c while @c and $tags{$c[0]->tag}; # Proceed forwards staying on acceptable tags
2771 @a # Current node and matching following nodes
2772 }
2773 else
2774 {shift @c while @c > 1 and $tags{$c[1]->tag}; # Proceed forwards but staying on acceptable tags
2775 return $c[0] # Current node or last acceptable tag reached while staying on acceptable tags
2776 }
2777 }
2778  
2779 sub nextWhile($@) #U Go to the next sibling of the specified B<$node> and continue forwards while the tag of each sibling node matches one of the specified B<@tags>. Return the first sibling node that does not match else B<undef> if there is no such sibling.
2780 {my ($node, @tags) = @_; # Node, child tags to avoid.
2781 my %tags = map {$_=>1} @tags; # Hashify tags
2782 for($node->contentAfter) # Search forwards through siblings
2783 {return $_ unless $tags{$_->tag}; # Find first tag that fails to match
2784 }
2785 return undef # No such node
2786 }
2787  
2788 sub nextUntil($@) #U Go to the next sibling of the specified B<$node> and continue forwards until the tag of a sibling node matches one of the specified B<@tags>. Return the matching sibling node else B<undef> if there is no such sibling node.
2789 {my ($node, @tags) = @_; # Node, tags to look for.
2790 my %tags = map {$_=>1} @tags; # Hashify tags
2791 for($node->contentAfter) # Search forwards through following siblings
2792 {return $_ if $tags{$_->tag}; # Find next node that matches on of the supplied tags
2793 }
2794 undef # No such node
2795 }
2796  
2797 #D2 Prev # Find sibling nodes before the specified B<$node>.
2798  
2799 sub prev($@) #BCYU Return the node before the specified B<$node>, optionally checking the previous node's context. See L<addLast|/addLast> to ensure that an expected node is in position.
2800 {my ($node, @context) = @_; # Node, optional context.
2801 return undef if $node->isFirst; # No node follows the last node at a level or the top most node
2802 my @c = $node->parent->contents; # Content array of parent
2803 while(@c) # Test until no more nodes left to test
2804 {my $c = pop @c; # Each node
2805 if ($c == $node) # Current node
2806 {my $n = pop @c; # Prior node
2807 return undef if @context and !$n->at(@context); # Prior node is not in specified context
2808 return $n; # Found node
2809 }
2810 }
2811 confess "Node not found in parent"; # Something wrong with parent/child relationship
2812 }
2813 #a
2814 #b <b/><c/><b/><d/>
2815 #c at d
2816 #c prev b
2817 #c set id b_before_d
2818 #d Go to the previous sibling optionally checking its context.
2819  
2820 sub prevText($@) #CU Return the node before the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
2821 {my ($node, @context) = @_; # Node, optional context.
2822 return undef if @context and !$node->at(@context); # Check the context if supplied
2823 my $l = &prev($node); # Previous node
2824 $l ? $l->isText : undef # Test whether the first node exists and is a text node
2825 }
2826  
2827 sub prevn($$@) #CU Return the B<$n>'th previous node after the specified B<$node> optionally checking its context or B<undef> if there is no such node. B<prevn(1)> is identical in effect to L<prev|/prev>.
2828 {my ($node, $N, @context) = @_; # Node, number of times to go prev, optional context.
2829 return undef if @context and !$node->at(@context); # Check the context if supplied
2830 for(1..$N) # Go previous the specified number of times
2831 {$node = $node->prev; # Go previous
2832 return undef unless $node; # Cannot go further
2833 }
2834 $node
2835 }
2836 #a
2837 #b <b/><c/><d/><e/>
2838 #c last
2839 #c prevn 2
2840 #c set id yes
2841 #d Go backwards
2842  
2843 sub prevTextMatches($$@) #CU Return the previous node to the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context. Else return B<undef>.
2844 {my ($node, $match, @context) = @_; # Node, regular expression the text must match, optional context of specified node.
2845 return undef if @context and !$node->at(@context); # Check context
2846 if (my $t = $node->prevText) # Previous node is text
2847 {return $t->matchesText($match); # Previous text node matches the specified regular expression
2848 }
2849 undef # Previous node is not text or does not match the specified regular expression
2850 }
2851  
2852 sub prevIn($@) #YU Return the nearest sibling node before the specified B<$node> which matches one of the named tags or B<undef> if there is no such sibling node.
2853 {my ($node, @tags) = @_; # Node, tags to search for.
2854 my %tags = map {$_=>1} @tags; # Hashify tags
2855 my $parent = $node->parent; # Parent node
2856 return undef unless $parent; # No nodes follow the root node
2857 my @c = reverse $parent->contents; # Reverse through contents
2858 shift @c while @c and $c[0] != $node; # Move down to starting node
2859 shift @c; # Move over starting node
2860 for(@c) # Each subsequent node
2861 {return $_ if $tags{$_->tag}; # Find first tag with the specified name in the remaining nodes
2862 }
2863 return undef # No such node
2864 }
2865  
2866 sub prevOn($@) #U 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.
2867 {my ($node, @tags) = @_; # Start node, tags identifying nodes that can be step on to context.
2868 return wantarray ? ($node) : $node if $node->isFirst; # Easy case
2869 my $parent = $node->parent; # Parent node
2870 confess "No parent" unless $parent; # Not possible on a root node
2871 my @c = reverse $parent->contents; # Content backwards
2872 shift @c while @c and $c[0] != $node; # Position on current node
2873 confess "Node not found in parent" unless @c; # Something wrong with parent/child relationship
2874 my %tags = map {$_=>1} @tags; # Hashify tags of acceptable commands
2875 if (wantarray) # Return node and following matching nodes if array wanted
2876 {my @a = (shift @c);
2877 push @a, shift @c while @c and $tags{$c[0]->tag}; # Proceed forwards staying on acceptable tags
2878 @a # Current node and matching following nodes
2879 }
2880 else
2881 {shift @c while @c > 1 and $tags{$c[1]->tag}; # Proceed forwards but staying on acceptable tags
2882 return $c[0] # Current node or last acceptable tag reached while staying on acceptable tags
2883 }
2884 }
2885  
2886 sub prevWhile($@) #U Go to the previous sibling of the specified B<$node> and continue backwards while the tag of each sibling node matches one of the specified B<@tags>. Return the first sibling node that does not match else B<undef> if there is no such sibling.
2887 {my ($node, @tags) = @_; # Parent node, child tags to avoid.
2888 my %tags = map {$_=>1} @tags; # Hashify tags
2889 for(reverse $node->contentBefore) # Search backwards through siblings
2890 {return $_ unless $tags{$_->tag}; # Find first tag that fails to match
2891 }
2892 return undef # No such node
2893 }
2894  
2895 sub prevUntil($@) #U Go to the previous sibling of the specified B<$node> and continue backwards until the tag of a sibling node matches one of the specified B<@tags>. Return the matching sibling node else B<undef> if there is no such sibling node.
2896 {my ($node, @tags) = @_; # Node, tags to look for.
2897 my %tags = map {$_=>1} @tags; # Hashify tags
2898 for($node->contentBefore) # Search forwards through following siblings
2899 {return $_ if $tags{$_->tag}; # Find next node that matches on of the supplied tags
2900 }
2901 undef # No such node
2902 }
2903  
2904 #D2 Up # Methods for moving up the L<parse|/parse> tree from a node.
2905  
2906 sub top($@) #CYU Return the top of the parse tree containing the current B<$node> after optionally checking that the $node is in the optional B<@context>.
2907 {my ($node, @context) = @_; # Start node, optional context
2908 return undef if @context and !$node->at(@context); # Check the context if supplied
2909 for (my $p = $node;; $p = $p->parent) # Walk up the parse tree
2910 {return $p unless $p->parent; # Continue up the parse tree unless we are at the top - if not, let us hope that Zorn's lemma applies soon rather than later
2911 }
2912 }
2913  
2914 BEGIN {*root = *top}
2915  
2916 #a
2917 #b <b><c/></b>
2918 #c top
2919 #c set id top
2920 #d Go to the top of the parse tree.
2921  
2922 sub up($@) #CYU Return the parent of the current node optionally checking the parent node's context or return B<undef> if the specified B<$node> is the root of the L<parse|/parse> tree. See L<addWrapWith|/addWrapWith> to ensure that an expected node is in position.
2923 {my ($node, @context) = @_; # Start node, optional context of parent.
2924 return $node->parent unless @context; # Parent with no context check
2925 my $p = $node->parent;
2926 $p->at(@context) ? $p : undef; # Check context of parent
2927 }
2928 #a
2929 #b <b><c/></b>
2930 #c at c
2931 #c up
2932 #c set id above_c
2933 #d Go up one level.
2934  
2935 sub upn($$@) #CU Go up the specified number of levels from the specified B<$node> and return the node reached optionally checking the parent node's context or B<undef> if there is no such node.L<upn(1)|/up> is identical in effect to L<up|/up>. Or use L<ancestry|/ancestry> to get the path back to the root node.
2936 {my ($node, $levels, @context) = @_; # Start node, number of levels to go up, optional context.
2937 for(my $c = 0; $node and $c < $levels; $node = $node->parent, ++$c) {} # Number of levels move up
2938 return $node unless @context; # Return node reached unless context check required
2939 $node ? $node->at(@context) : undef; # Check context
2940 }
2941  
2942 sub upWhile($@) #YU Go up one level from the specified B<$node> and then continue up while each node matches on of the specified <@tags>. Return the last matching node or B<undef> if no node matched any of the specified B<@tags>.
2943 {my ($node, @tags) = @_; # Start node, tags to match
2944 my %tags = map {$_=>1} @tags; # Hashify tags
2945 my $lastMatch; # Last good match
2946 for(my $p = $node->parent; $p; $p = $p->parent) # Go up
2947 {last unless $tags{-t $p}; # Found an ancestor that does not match
2948 $lastMatch = $p;
2949 }
2950 $lastMatch # Last good match
2951 }
2952  
2953 sub upWhileFirst($@) #CU Move up from the specified B<$node> as long as each node is a first node or return B<undef> if the specified B<$node> is not a first node.
2954 {my ($node, @context) = @_; # Start node, optional context
2955 return undef if @context && !$node->at(@context) or !$node->isFirst; # Check the context if supplied and that the node is first
2956 my $lastMatch = $node; # First node
2957 for(my $p = $node->parent; $p; $p = $p->parent) # Go up
2958 {return $lastMatch unless $p->isFirst; # Return last node which was first
2959 $lastMatch = $p # Update last matching position
2960 }
2961 $lastMatch # Root node matches
2962 }
2963  
2964 sub upWhileLast($@) #CU Move up from the specified B<$node> as long as each node is a last node or return B<undef> if the specified B<$node> is not a last node.
2965 {my ($node, @context) = @_; # Start node, optional context
2966 return undef if @context && !$node->at(@context) or !$node->isLast; # Check the context if supplied and that the node is last
2967 my $lastMatch = $node; # Last node
2968 for(my $p = $node->parent; $p; $p = $p->parent) # Go up
2969 {return $lastMatch unless $p->isLast; # Return last node which was last
2970 $lastMatch = $p # Update last matching position
2971 }
2972 $lastMatch # Root node matches
2973 }
2974  
2975 sub upWhileIsOnlyChild($@) #CU Move up from the specified B<$node> as long as each node is an only child or return B<undef> if the specified B<$node> is not an only child.
2976 {my ($node, @context) = @_; # Start node, optional context
2977 return undef if @context && !$node->at(@context) or !$node->isOnlyChild; # Check the context if supplied and that the node is an only child
2978 my $lastMatch = $node; # Last node
2979 for(my $p = $node->parent; $p; $p = $p->parent) # Go up
2980 {return $lastMatch unless $p->isOnlyChild; # Return last node which was an only child
2981 $lastMatch = $p # Update last matching position
2982 }
2983 $lastMatch # Root node matches
2984 }
2985  
2986 sub upUntil($@) #CYU Find the first node going up from B<$node> that matches the specified B<@context>. The first such node will be the specified $node if no @context is specified or the specified $node matches the specified @context>.
2987 {my ($node, @context) = @_; # Start node, context.
2988 for(my $p = $node; $p; $p = $p->parent) # Go up
2989 {return $p if $p->at(@context); # Return node which satisfies the condition
2990 }
2991 return undef # Not found
2992 }
2993 #a upUntil
2994 #b <b><c><d/></c></b>
2995 #c at d
2996 #c upUntil c b
2997 #c set id up
2998 #d Go up while we are not in the specified context
2999  
3000 sub upUntilFirst($@) #CU Move up from the specified B<$node> until we reach the root or a first node.
3001 {my ($node, @context) = @_; # Start node, optional context
3002 return undef if @context and !$node->at(@context); # Check the context if supplied
3003 for(my $p = $node; $p; $p = $p->parent) # Go up
3004 {return $p if $p->isFirst; # Return first first node
3005 }
3006 undef # This should not happen
3007 }
3008  
3009 sub upUntilLast($@) #CU Move up from the specified B<$node> until we reach the root or a last node.
3010 {my ($node, @context) = @_; # Start node, optional context
3011 return undef if @context and !$node->at(@context); # Check the context if supplied
3012 for(my $p = $node; $p; $p = $p->parent) # Go up
3013 {return $p if $p->isLast; # Return first last node
3014 }
3015 undef # This should not happen
3016 }
3017  
3018 sub upUntilIsOnlyChild($@) #CU Move up from the specified B<$node> until we reach the root or another only child.
3019 {my ($node, @context) = @_; # Start node, optional context
3020 return undef if @context and !$node->at(@context); # Check the context if supplied and that the node is an only child
3021 for(my $p = $node; $p; $p = $p->parent) # Go up
3022 {return $p if $p->isOnlyChild; # Return last node which was an only child
3023 }
3024 undef # This should not happen
3025 }
3026  
3027 sub upThru($@) #YU Go up the specified path from the specified B<$node> returning the node at the top or B<undef> if no such node exists.
3028 {my ($node, @tags) = @_; # Start node, tags identifying path.
3029 while(@tags) # Go up through the tags
3030 {$node = $node->parent; # Go up on level
3031 return undef unless $node and $node->at(shift @tags); # Failed to match next tag
3032 }
3033 $node # Reached the top of the path
3034 }
3035  
3036 #D2 down # Methods for moving down through the L<parse|/parse> tree from a node.
3037  
3038 sub downWhileFirst($@) #CU Move down from the specified B<$node> as long as each lower node is a first node.
3039 {my ($node, @context) = @_; # Start node, optional context
3040 return undef if @context and !$node->at(@context); # Check the context if supplied
3041 for(my $p = $node->first; $p; $p = $p->first) # Go down firstly
3042 {return $p unless $p->first; # Return node unless there is another one below it
3043 }
3044 $node->isFirst # Leaf node
3045 }
3046  
3047 BEGIN{*firstLeaf=*downWhileFirst}
3048  
3049 sub downWhileLast($@) #CU Move down from the specified B<$node> as long as each lower node is a last node.
3050 {my ($node, @context) = @_; # Start node, optional context
3051 return undef if @context and !$node->at(@context); # Check the context if supplied
3052 for(my $p = $node->last; $p; $p = $p->last) # Go down lastly
3053 {return $p unless $p->last; # Return node unless there is another one below it
3054 }
3055 $node->isLast # Leaf node
3056 }
3057  
3058 BEGIN{*lastLeaf=*downWhileLast}
3059  
3060 sub downWhileHasSingleChild($@) #CU Move down from the specified B<$node> as long as it has a single child else return undef.
3061 {my ($node, @context) = @_; # Start node, optional context
3062 return undef if @context and !$node->at(@context); # Check the context if supplied
3063 my $q;
3064 for(my $p = $node; $p; $q = $p, $p = $p->first)
3065 {last unless $p->hasSingleChild;
3066 }
3067 $q
3068 }
3069  
3070 #D1 Editing # Edit the data in the L<parse|/parse> tree and change the structure of the L<parse|/parse> tree by L<wrapping and unwrapping|/Wrap and unwrap> nodes, by L<replacing|/Replace> nodes, by L<cutting and pasting|/Cut and Put> nodes, by L<concatenating|/Fusion> nodes, by L<splitting|/Fission> nodes, by adding new L<text|/Put as text> nodes or L<swapping|/swap> nodes.
3071  
3072 sub change($$@) #CIYU Change the name of the specified B<$node>, optionally confirming that the B<$node> is in a specified context and return the B<$node>.
3073 {my ($node, $name, @context) = @_; # Node, new name, optional context.
3074 return undef if @context and !$node->at(@context); # Not in specified context
3075 $node->tag = $name; # Change name
3076 if (my $parent = $node->parent) {$parent->indexNode} # Reindex parent
3077 $node
3078 }
3079 #a
3080 #b <b/>
3081 #c change c b a
3082 #d Change a tag.
3083 BEGIN{*cc=*change}
3084  
3085 sub changeKids($$@) #CU Change the names of all the immediate children of the specified B<$node>, if they match the optional B<@context>, to the specified B<$tag> and return the B<$node>.
3086 {my ($node, $name, @context) = @_; # Node, new name, optional context.
3087 if (!@context) # No context - change all immediate children
3088 {$_->tag = $name for $node->contents; # Change each node regardless
3089 }
3090 else # Check context of each child before changing name
3091 {for my $c($node->contents) # Each immediate child
3092 {$c->tag = $name if $c->at(@context); # Change node if in specified context
3093 }
3094 }
3095 $node->indexNode; # Reindex node
3096 $node # Return node
3097 }
3098  
3099 BEGIN{*ck=*change}
3100  
3101 sub changeText($$$$@) #CU Change the content of the specified text B<$node> that matches a regular expression B<$rf> presented as a string to a string B<$rt> in the optional B<@context> and return the specified $node else return B<undef>. For a more efficient non unitary method see L<editText>.
3102 {my ($node, $rf, $rt, $flags, @context) = @_; # Text node, from re, to string, re flags, optional context
3103 confess "Parameter 2 should be a string" if ref($rf); # Check usage
3104 return undef unless $node->isText(@context); # Check that this is a text node in the specified context.
3105 my $t = $node->text; # Text to change
3106 my $c = qq(\$t =~ s($rf) ($rt)$flags); # Create regular expression
3107 my $r = eval qq(\$t =~ s($rf) ($rt)$flags); # Evaluate regular expression
3108 confess "$@\n" if $@; # Confess to failures
3109 $node->text = $t; # Update text
3110 $r ? $node : undef # Return node on success or undef on fail
3111 }
3112 #a editText
3113 #b <b>ababa</b>
3114 #c changeText b(.)b $1C$1 s
3115 #d Change text using a regular expression, target string and flags.
3116  
3117 sub changeTextToSpace($$@) #CU Change each instance of the content of the specified text B<$node> that matches a regular expression B<$re> to one space and return the specified $node else return B<undef>.
3118 {my ($node, $re, @context) = @_; # Text node, regular expression, optional context
3119 return undef unless $node->isText(@context); # Check that this is a text node in the specified context.
3120 $node->text =~ s($re) ( )gs ? $node : undef # Change text to spaces
3121 }
3122 #a
3123 #b <b>ababa</b>
3124 #c changeTextToSpace b
3125 #d Change text to space using a regular expression.
3126  
3127 sub dupPutNext($@) #CU Duplicate the specified B<$tree> in the optional B<@context>, place the new tree next after $tree and return the root of the new tree on success else B<undef>.
3128 {my ($tree, @context) = @_; # Node, optional context.
3129 return undef if @context and !$tree->at(@context); # Not in specified context
3130 putNext($tree, clone($tree)); # Place new node and return it
3131 }
3132  
3133 BEGIN{*r=*dupPutNext} # As used in editWithPerl
3134  
3135 sub dupPutPrev($@) #CU Duplicate the specified B<$tree> in the optional B<@context>, place the new tree before $tree and return the root of the new tree on success else B<undef>.
3136 {my ($tree, @context) = @_; # Node, optional context.
3137 return undef if @context and !$tree->at(@context); # Not in specified context
3138 putPrev($tree, clone($tree)); # Place new node and return it
3139 }
3140  
3141 sub dupPutNextN($$@) #CU Duplicate the specified B<$tree> B<$N> times in the optional B<@context>, placing each copy after $tree and return the last new node created on success else B<undef>.
3142 {my ($node, $N, @context) = @_; # Node, number of duplications, optional context.
3143 return undef if @context and !$node->at(@context); # Not in specified context
3144 return undef unless my $parent = $node->parent; # Cannot duplicate the root node
3145 my $r = $node->renew; # Make a copy of the node and its descendants
3146 my $f = freeze($r); # Freeze parse tree restricted to node and its contents
3147 my $c = $parent->content; # Content array of parent
3148 my $i = $node->position; # Position in content array
3149 my @n = map {my $r = thaw($f); $r->parent = $parent; $r} 1..$N; # New nodes after original node - copy on write might be useful
3150 splice(@$c, $i+1, 0, @n); # Insert new nodes after original node
3151 $parent->indexNode; # Rebuild indices for parent
3152 }
3153  
3154 BEGIN{*rN=*dupPutNextN}
3155  
3156 our $selectionStart; # Selection starts here
3157 our $selectionEnd; # Selection ends here
3158  
3159 sub setSelectionStart($@) #CU Set the selection to start at the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>..
3160 {my ($node, @context) = @_; # Node, optional context.
3161 return undef if @context and !$node->at(@context); # Not in specified context
3162 $selectionStart = $node; # Start selection
3163 }
3164  
3165 BEGIN{*ss=*setSelectionStart}
3166  
3167 sub setSelectionEnd($@) #CU Set the selection to end at the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>..
3168 {my ($node, @context) = @_; # Node, optional context.
3169 return undef if @context and !$node->at(@context); # Not in specified context
3170 $selectionEnd = $node; # End selection
3171 }
3172  
3173 BEGIN{*se=*setSelectionEnd}
3174  
3175 sub moveSelectionFirst($@) #CU Move the current selection (if there is one) so that it is first under the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
3176 {my ($node, @context) = @_; # Node, optional context.
3177 return undef if @context and !$node->at(@context); # Not in specified context
3178 return undef unless $selectionStart || $selectionEnd; # No selection
3179 my $s = $selectionStart || $selectionEnd; # Selection start
3180 my $e = $selectionEnd || $selectionStart; # Selection end
3181 $s->moveBlockFirst($e, $node); # Move selection
3182 $s->putFirstAsComment(q(start)); # Show selection start
3183 $e->putLastAsComment(q(end)); # Show selection end
3184 $node; # Success
3185 }
3186  
3187 BEGIN{*mf=*moveSelectionFirst}
3188  
3189 sub moveSelectionAfter($@) #CU Move the current selection (if there is one) after the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
3190 {my ($node, @context) = @_; # Node, optional context.
3191 return undef if @context and !$node->at(@context); # Not in specified context
3192 return undef unless $selectionStart || $selectionEnd; # No selection
3193 my $s = $selectionStart || $selectionEnd; # Selection start
3194 my $e = $selectionEnd || $selectionStart; # Selection end
3195 $s->moveBlockAfter($e, $node); # Move selection
3196 $node; # Success
3197 }
3198  
3199 BEGIN{*ma=*moveSelectionAfter}
3200  
3201 sub moveSelectionBefore($@) #CU Move the current selection (if there is one) before the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
3202 {my ($node, @context) = @_; # Node, optional context.
3203 return undef if @context and !$node->at(@context); # Not in specified context
3204 return undef unless $selectionStart || $selectionEnd; # No selection
3205 my $s = $selectionStart || $selectionEnd; # Selection start
3206 my $e = $selectionEnd || $selectionStart; # Selection end
3207 $s->moveBlockBefore($e, $node); # Move selection
3208 $node; # Success
3209 }
3210  
3211 BEGIN{*mb=*moveSelectionBefore}
3212  
3213 sub moveSelectionLast($@) #CU Move the current selection (if there is one) so that it is last under the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
3214 {my ($node, @context) = @_; # Node, optional context.
3215 return undef if @context and !$node->at(@context); # Not in specified context
3216 return undef unless $selectionStart || $selectionEnd; # No selection
3217 my $s = $selectionStart || $selectionEnd; # Selection start
3218 my $e = $selectionEnd || $selectionStart; # Selection end
3219 $s->moveBlockLast($e, $node); # Move selection
3220 $node; # Success
3221 }
3222  
3223 BEGIN{*ml=*moveSelectionLast}
3224  
3225 #D2 Cut and Put # Cut and paste nodes in the L<parse|/parse> tree.
3226  
3227 sub cut($@) #CUI Cut out and return the specified B<$node> so that it can be reinserted else where in the L<parse|/parse> tree.
3228 {my ($node, @context) = @_; # Node to cut out, optional context
3229 return undef if @context and !$node->at(@context); # Not in specified context
3230 my $parent = $node->parent; # Parent node
3231 # confess "Already cut out" unless $parent; # We have to let thing be cut out more than once or supply an isCutOut() method
3232 return $node unless $parent; # Uppermost node is already cut out
3233 my $c = $parent->content; # Content array of parent
3234 my $i = $node->position; # Position in content array
3235 splice(@$c, $i, 1); # Remove node
3236 $parent->indexNode; # Rebuild indices
3237 $node->disconnectLeafNode; # Disconnect node no longer in L<parse|/parse> tree
3238 $node # Return node
3239 }
3240 #a unwrap
3241 #b <b>C</b>
3242 #c cut b
3243 #d Delete a node and all its contents.
3244  
3245 BEGIN{*x=*cut}
3246  
3247 our @saveLastCutOut; # Save the last node cut out on the cut out stack
3248  
3249 sub cutFirst($@) #CU Cut out the first node below the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack. Return $node on success else return B<undef>. The cut out node can be reinserted using one of the putCutOut(First|Last|Next|Prev) methods.
3250 {my ($node, @context) = @_; # Node, optional context
3251 return undef unless my $first = $node->first; # First child node must exist
3252 return undef if @context and !$first->at(@context); # First child node not in specified context
3253 push @saveLastCutOut, $first->cut; # Cut out node saving it on the cut out stack
3254 $node # Return current node
3255 }
3256  
3257 sub putCutOutFirst($@) #CU Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it first under the specified B<$node> if $node is in the optional B<@context>. Return $node on success else return B<undef>.
3258 {my ($node, @context) = @_; # Node, optional context
3259 return undef if @context and !$node->at(@context); # Node not in specified context
3260 return undef unless my $cut = pop @saveLastCutOut; # Last cut out node
3261 $node->putFirst($cut); # Insert cut out node
3262 $node # Return current node
3263 }
3264  
3265 sub cutLast($@) #CU Cut out the last node below the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack. Return $node on success else return B<undef>. The cut out node can be reinserted using one of the putCutOut(First|Last|Next|Prev) methods.
3266 {my ($node, @context) = @_; # Node, optional context
3267 return undef unless my $last = $node->last; # Last child node must exist
3268 return undef if @context and !$last->at(@context); # Last child node not in specified context
3269 push @saveLastCutOut, $last->cut; # Cut out node saving it on the cut out stack
3270 $node # Return current node
3271 }
3272  
3273 sub putCutOutLast($@) #CU Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it last under the specified B<$node> if $node is in the optional B<@context>. Return $node on success else return B<undef>.
3274 {my ($node, @context) = @_; # Node, optional context
3275 return undef if @context and !$node->at(@context); # Node not in specified context
3276 return undef unless my $cut = pop @saveLastCutOut; # Last cut out node
3277 $node->putLast($cut); # Insert cut out node
3278 $node # Return current node
3279 }
3280  
3281 sub cutNext($@) #CU Cut out the next node beyond the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack. Return the current node on success else return B<undef>. The cut out node can be reinserted using one of the putCutOut(First|Last|Next|Prev) methods.
3282 {my ($node, @context) = @_; # Node, optional context
3283 return undef unless my $next = $node->next; # Next node must exist
3284 return undef if @context and !$next->at(@context); # Not in specified context
3285 push @saveLastCutOut, $next->cut; # Cut out node saving it on the cut out stack
3286 $node # Return current node
3287 }
3288 #a cut
3289 #b <b/><c/><d/>
3290 #c first
3291 #c cutNext c a
3292 #c next d
3293 #c putCutOutNext
3294 #d Cut out the next node and reinsert it
3295  
3296 sub putCutOutNext($@) #CU Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it next after the specified B<$node> if $node is in the optional B<@context>. Return $node on success else return B<undef>.
3297 {my ($node, @context) = @_; # Node, optional context
3298 return undef if @context and !$node->at(@context); # Node not in specified context
3299 return undef unless my $cut = pop @saveLastCutOut; # Last cut out node
3300 $node->putNext($cut); # Insert cut out node
3301 $node # Return current node
3302 }
3303  
3304 sub cutPrev($@) #CU Cut out the previous node before the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack. Return the current node on success else return B<undef>. The cut out node can be reinserted using one of the putCutOut(First|Last|Next|Prev) methods.
3305 {my ($node, @context) = @_; # Node, optional context
3306 return undef unless my $prev = $node->prev; # Previous node must exist
3307 return undef if @context and !$prev->at(@context); # Not in specified context
3308 push @saveLastCutOut, $prev->cut; # Cut out node saving it on the cut out stack
3309 $node # Return current node
3310 }
3311 #a cut
3312 #b <b/><c/><d/>
3313 #c last
3314 #c cutPrev c a
3315 #c prev b
3316 #c putCutOutPrev
3317 #d Cut out the previous node and reinsert it
3318  
3319 sub putCutOutPrev($@) #CU Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it before the specified B<$node> if $node is in the optional B<@context>. Return $node on success else return B<undef>.
3320 {my ($node, @context) = @_; # Node, optional context
3321 return undef if @context and !$node->at(@context); # Node not in specified context
3322 return undef unless my $cut = pop @saveLastCutOut; # Last cut out node
3323 $node->putPrev($cut); # Insert cut out node
3324 $node # Return current node
3325 }
3326  
3327 sub cutIfEmpty($@) #CU Cut out and return the specified B<$node> so that it can be reinserted else where in the L<parse|/parse> tree if it is empty.
3328 {my ($node, @context) = @_; # Node to cut out, optional context
3329 return undef if @context and !$node->at(@context); # Not in specified context
3330 return $node->cut if $node->isAllBlankText; # Cut node if it has no content or all blank content
3331 undef # Cannot cut out node
3332 }
3333 #a cut unwrap
3334 #b <b/><c/><b/><d>text</d>
3335 #c cutIfEmpty
3336 #d Remove a node if it is empty.
3337  
3338 sub deleteContent($@) #CU Delete the content of the specified B<$node>.
3339 {my ($node, @context) = @_; # Node, optional context
3340 return undef if @context and !$node->at(@context); # Not in specified context
3341 my @c = $node->contents; # Content
3342 $_->parent = undef for @c; # Remove parent link from each child
3343 $node->content = []; # Delete content
3344 $node # Return node
3345 }
3346  
3347 sub putFirst($$@) #C Place a L<cut out|/cut> or L<new|/new> node at the front of the content of the specified B<$node> and return the new node. See L<putFirstCut|/putFirstCut> to cut and put first in one operation. See L<addFirst|/addFirst> to perform this operation conditionally.
3348 {my ($old, $new, @context) = @_; # Original node, new node, optional context.
3349 return undef if @context and !$old->at(@context); # Not in specified context
3350 $new->parent and confess "Please cut out the node before moving it"; # The node must have be cut out first
3351 $new->parser == $new and $old->parser == $new and # Prevent a root node from being inserted into a sub tree
3352 confess "Recursive insertion attempted";
3353 $new->parser = $old->parser; # Assign the new node to the old parser
3354 unshift @{$old->content}, $new; # Content array of original node
3355 $old->indexNode; # Rebuild indices for node
3356 $new # Return the new node
3357 }
3358  
3359 sub putFirstCut($$@) #C Cut out the B<$second> node, place it first under the B<$first> node and return the B<$second> node.
3360 {my ($first, $second, @context) = @_; # First node, second node, optional context.
3361 $first->putFirst($second->cut, @context) # Place second node relative to the first node if in the specified context and return the second node.
3362 }
3363  
3364 sub putLast($$@) #CI Place a L<cut out|/cut> or L<new|/new> node last in the content of the specified B<$node> and return the new node. See L<putLastCut|/putLastCut> to cut and put last in one operation. See L<addLast|/addLast> to perform this operation conditionally.
3365 {my ($old, $new, @context) = @_; # Original node, new node, optional context.
3366 return undef if @context and !$old->at(@context); # Not in specified context
3367 $new->parent and confess "Please cut out the node before moving it"; # The node must have be cut out first
3368 $new->parser == $new and $old->parser == $new and # Prevent a root node from being inserted into a sub tree
3369 confess "Recursive insertion attempted";
3370 $new->parser = $old->parser; # Assign the new node to the old parser
3371 push @{$old->content}, $new; # Content array of original node
3372 $old->indexNode; # Rebuild indices for node
3373 $new # Return the new node
3374 }
3375  
3376 sub putLastCut($$@) #C Cut out the B<$second> node, place it last under the B<$first> node and return the B<$second> node.
3377 {my ($first, $second, @context) = @_; # First node, second node, optional context.
3378 $first->putLast($second->cut, @context) # Place second node relative to the first node if in the specified context and return the second node.
3379 }
3380  
3381 sub putNext($$@) #C Place a L<cut out|/cut> or L<new|/new> node just after the specified B<$node> and return the new node. See L<putNextCut|/putNextCut> to cut and put next in one operation. See L<addNext|/addNext> to perform this operation conditionally.
3382 {my ($old, $new, @context) = @_; # Original node, new node, optional context.
3383 return undef if @context and !$old->at(@context); # Not in specified context
3384 return undef unless my $parent = $old->parent; # Parent node
3385 $parent or confess "Cannot place a node after the outermost node"; # The originating node must have a parent
3386 $new->parent and confess "Please cut out the node before moving it"; # The node must have be cut out first
3387 $new->parser == $new and $old->parser == $new and # Prevent a root node from being inserted into a sub tree
3388 confess "Recursive insertion attempted";
3389 $new->parser = $old->parser; # Assign the new node to the old parser
3390 my $c = $parent->content; # Content array of parent
3391 my $i = $old->position; # Position in content array
3392 splice(@$c, $i+1, 0, $new); # Insert new node after original node
3393 $new->parent = $parent; # Return node
3394 $parent->indexNode; # Rebuild indices for parent
3395 $new # Return the new node
3396 }
3397  
3398 sub putNextCut($$@) #C Cut out the B<$second> node, place it after the B<$first> node and return the B<$second> node.
3399 {my ($first, $second, @context) = @_; # First node, second node, optional context.
3400 $first->putNext($second->cut, @context) # Place second node relative to the first node if in the specified context and return the second node.
3401 }
3402  
3403 sub putPrev($$@) #C Place a L<cut out|/cut> or L<new|/new> node just before the specified B<$node> and return the new node. See L<putPrevCut|/putPrevCut> to cut and put previous in one operation. See L<addPrev|/addPrev> to perform this operation conditionally.
3404 {my ($old, $new, @context) = @_; # Original node, new node, optional context.
3405 return undef if @context and !$old->at(@context); # Not in specified context
3406 return undef unless my $parent = $old->parent; # Parent node
3407 $parent or confess "Cannot place a node before the outermost node"; # The originating node must have a parent
3408 $new->parent and confess "Please cut out the node before moving it"; # The node must have be cut out first
3409 $new->parser == $new and $old->parser == $new and # Prevent a root node from being inserted into a sub tree
3410 confess "Recursive insertion attempted";
3411 $new->parser = $old->parser; # Assign the new node to the old parser
3412 my $c = $parent->content; # Content array of parent
3413 my $i = $old->position; # Position in content array
3414 splice(@$c, $i, 0, $new); # Insert new node before original node
3415 $new->parent = $parent; # Return node
3416 $parent->indexNode; # Rebuild indices for parent
3417 $new # Return the new node
3418 }
3419  
3420 sub putPrevCut($$@) #C Cut out the B<$second> node, place it before the B<$first> node and return the B<$second> node.
3421 {my ($first, $second, @context) = @_; # First node, second node, optional context.
3422 $first->putPrev($second->cut, @context) # Place second node relative to the first node if in the specified context and return the second node.
3423 }
3424  
3425 #D2 Put Siblings or Contents # Move a node and its siblings up and down the parse tree.
3426  
3427 sub putSiblingsFirst($@) #CU Move the siblings preceding the specified B<$node> in the optional B<@context> down one level and place them first under the specified B<$node> preceding any existing content. Return the specified B<$node>.
3428 {my ($node, @context) = @_; # Node whose start should be moved, optional context of node.
3429 return undef if @context and !$node->at(@context); # Not in specified context
3430 for my $n(reverse $node->contentBefore) # Each node preceding the specified node
3431 {$node->putFirstCut($n); # Place node first
3432 }
3433 $node # Success
3434 }
3435  
3436 sub putSiblingsLast($@) #CU Move the siblings following the specified B<$node> in the optional B<@context> down one level so that they are last under the specified B<$node> following any existing content. Return the specified B<$node>.
3437 {my ($node, @context) = @_; # Node whose start should be moved, optional context of node.
3438 return undef if @context and !$node->at(@context); # Not in specified context
3439 for my $n($node->contentAfter) # Each node following the specified node
3440 {$node->putLastCut($n); # Place node last
3441 }
3442 $node # Success
3443 }
3444  
3445 sub putSiblingsAfterParent($@) #CU Move the specified B<$node> and its following siblings up one level and place them after the parent of the specified B<$node> if the specified B<$node> is in the optional B<@context>. Return the specified B<$node> if the move was made successfully, else confess that the specified move is not possible.
3446 {my ($node, @context) = @_; # Node whose start should be moved, optional context of node.
3447 return undef if @context and !$node->at(@context); # Not in specified context
3448 confess "Cannot put after root of parse tree" unless my $p = $node->parent; # Fail on root node
3449 for my $n(reverse @$p) # Each node from last to first under parent
3450 {$p->putNextCut($n); # Place node after parent
3451 last if $node == $n; # Stop when we reach the specified node
3452 }
3453 $node # Success
3454 }
3455  
3456 sub putSiblingsBeforeParent($@) #CU Move the specified B<$node> and its preceding siblings up one level and place them before the parent of the specified B<$node> if the specified B<$node> is in the optional B<@context>. Return the specified B<$node> if the move was made successfully, else confess that the specified move is not possible.
3457 {my ($node, @context) = @_; # Node whose start should be moved, optional context of node.
3458 return undef if @context and !$node->at(@context); # Not in specified context
3459 confess "Cannot put before root of parse tree" unless my $p = $node->parent; # Fail on root node
3460 for my $n($p->contents) # Each node from last to first under parent
3461 {$p->putPrevCut($n); # Place node after parent
3462 last if $node == $n; # Stop when we reach the specified node
3463 }
3464 $node # Success
3465 }
3466  
3467 sub putContentAfter($@) #CU Move the content of the specified B<$node> and place it after that node if that node is in the optional B<@context>. Return the specified B<$node> or confess if the move is not possible.
3468 {my ($node, @context) = @_; # Node whose start should be moved, optional context of node.
3469 return undef if @context and !$node->at(@context); # Not in specified context
3470 confess "Cannot put content after root of parse tree" unless $node->parent; # Fail on root node
3471 for my $n(reverse @$node) # Each content node from last to first
3472 {$node->putNextCut($n); # Move contained node after parent
3473 }
3474 $node # Success
3475 }
3476  
3477 sub putContentBefore($@) #CU Move the content of the specified B<$node> and place it before that node if that node is in the optional B<@context>. Return the specified B<$node> or confess if the move is not possible.
3478 {my ($node, @context) = @_; # Node whose start should be moved, optional context of node.
3479 return undef if @context and !$node->at(@context); # Not in specified context
3480 confess "Cannot put content before root of parse tree" unless $node->parent; # Fail on root node
3481 for my $n(my @c = @$node) # Each content node from first to last
3482 {$node->putPrevCut($n); # Move contained node before parent
3483 }
3484 $node # Success
3485 }
3486  
3487 #D2 Move # Move nodes around in the L<parse|/parse> tree by cutting and pasting them.
3488  
3489 sub moveFirst($@) #CU Move the specified node so that is is the first sibling under its parent. Returns the specified $node on success otherwise B<undef>.
3490 {my ($node, @context) = @_; # Node to be moved, optional context of node.
3491 return undef if @context and !$node->at(@context); # Not in specified context
3492 return $node if $node->isFirst; # Node is already in position
3493 return undef unless my $parent = $node->parent; # Parent node
3494 $parent->putFirstCut($node); # Move node
3495 $node # Success
3496 }
3497  
3498 sub moveLast($@) #CU Move the specified node so that is is the last sibling under its parent. Returns the specified $node on success otherwise B<undef>.
3499 {my ($node, @context) = @_; # Node to be moved, optional context of node.
3500 return undef if @context and !$node->at(@context); # Not in specified context
3501 return $node if $node->isLast; # Node is already in position
3502 return undef unless my $parent = $node->parent; # Parent node
3503 $parent->putLastCut($node); # Move node
3504 $node # Success
3505 }
3506  
3507 sub moveStartFirst($@) #CU Move the start of a B<$node> to contain all of its preceding siblings as children. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3508 {my ($node, @context) = @_; # Node whose start should be moved, optional context of node.
3509 return undef if @context and !$node->at(@context); # Not in specified context
3510  
3511 if ($node->isFirst) # Node is already in position
3512 {return $node;
3513 }
3514 for my $p(reverse $node->contentBefore) # Each node before the start tag
3515 {$node->putFirstCut($p); # Move node
3516 }
3517 $node # Success
3518 }
3519  
3520 sub moveStartAfter($$@) #C Move the start end of a B<$node> to just after the specified B<$target> node assuming that the B<$target> node is either a preceding sibling or a child of B<$node>. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3521 {my ($node, $to, @context) = @_; # Node whose start should be moved, target node, optional context of node.
3522 return undef if @context and !$node->at(@context); # Not in specified context
3523  
3524 if ($node->prev && $node->prev == $to) # Node is already in position
3525 {return $node;
3526 }
3527 elsif ($to->precedingSiblingOf($node)) # Target is outside and before node, so move start up to it
3528 {for my $p(reverse $node->contentBefore) # Each node before the start node up to the target
3529 {last if $p == $to; # Reached target
3530 $node->putFirstCut($p); # Move node
3531 }
3532 return $node; # Success
3533 }
3534 elsif ($to->parent and $to->parent == $node) # Contained by node
3535 {for my $p((reverse $to->contentBefore), $to) # Nodes from target
3536 {$node->putPrevCut($p); # Move node
3537 }
3538 return $node; # Success
3539 }
3540 confess "To node is not a child or preceding sibling of node"; # Cannot do the requested operation
3541 }
3542  
3543 sub moveStartBefore($$@) #C Move the start of a B<$node> to just before the specified B<$target> node assuming that the B<$target> node is either a preceding sibling or a child of B<$node>. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3544 {my ($node, $to, @context) = @_; # Node whose start should be moved, target node, optional context of node.
3545 return undef if @context and !$node->at(@context); # Not in specified context
3546  
3547 if ($node->first && $node->first == $to) # Node is already in position
3548 {return $node;
3549 }
3550 elsif ($to->precedingSiblingOf($node)) # Target is outside and before node, so move start up to it
3551 {for my $p(reverse $node->contentBefore) # Each node after the end tag up to the target
3552 {$node->putFirstCut($p); # Move node
3553 last if $p == $to; # Reached target
3554 }
3555 return $node; # Success
3556 }
3557 elsif ($to->parent and $to->parent == $node) # Contained by node
3558 {for my $p($to->contentBefore) # Nodes from target
3559 {$node->putPrevCut($p); # Move node
3560 }
3561 return $node; # Success
3562 }
3563 confess "To node is not a child or preceding sibling of node"; # Cannot do the requested operation
3564 }
3565  
3566 sub moveEndLast($@) #CU Move the end of a B<$node> to contain all of its following siblings as children. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3567 {my ($node, @context) = @_; # Node whose end should be moved, optional context of node.
3568 return undef if @context and !$node->at(@context); # Not in specified context
3569  
3570 if ($node->isLast) # Node is already in position
3571 {return $node;
3572 }
3573 for my $p($node->contentAfter) # Each node after the end tag
3574 {$node->putLastCut($p); # Move node
3575 }
3576 return $node; # Success
3577 }
3578  
3579 sub moveEndAfter($$@) #CI Move the end of a B<$node> to just after the specified B<$target> node assuming that the B<$target> node is either a subsequent sibling or a child of B<$node>. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3580 {my ($node, $to, @context) = @_; # Node whose end should be moved, target node, optional context of node.
3581 return undef if @context and !$node->at(@context); # Not in specified context
3582  
3583 if ($node->last && $node->last == $to) # Node is already in position
3584 {return $node;
3585 }
3586 elsif ($to->succeedingSiblingOf($node)) # Target is outside and beyond node, so move end down to it
3587 {for my $p($node->contentAfter) # Each node after the end node up to the target
3588 {$node->putLastCut($p); # Move node
3589 last if $p == $to; # Reached target
3590 }
3591 return $node; # Success
3592 }
3593 elsif ($to->parent and $to->parent == $node) # Contained by node
3594 {for my $p(reverse $to->contentAfter) # Nodes from target
3595 {$node->putNextCut($p); # Move node
3596 }
3597 return $node; # Success
3598 }
3599 confess "To node is not a child or succeeding sibling of node"; # Cannot do the requested operation
3600 }
3601  
3602 sub moveEndBefore($$@) #C Move the end of a B<$node> to just before the specified B<$target> node assuming that the B<$target> node is either a subsequent sibling or a child of B<$node>. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3603 {my ($node, $to, @context) = @_; # Node whose end should be moved, target node, optional context of node.
3604 return undef if @context and !$node->at(@context); # Not in specified context
3605  
3606 if ($node->next && $node->next == $to) # Node is already in position
3607 {return $node;
3608 }
3609 elsif ($to->succeedingSiblingOf($node)) # Target is outside and beyond node, so move end down to it
3610 {for my $p($node->contentAfter) # Each node after the end tag up to the target
3611 {last if $p == $to; # Reached target
3612 $node->putLastCut($p); # Move node
3613 }
3614 return $node; # Success
3615 }
3616 elsif ($to->parent and $to->parent == $node) # Contained by node
3617 {for my $p((reverse $to->contentAfter), $to) # Nodes from target
3618 {$node->putNextCut($p); # Move node
3619 }
3620 return $node; # Success
3621 }
3622 confess "To is not a child or succeeding sibling of node"; # Cannot do the requested operation
3623 }
3624  
3625 # Move a single node # Move a single node into a new position close to its current position.
3626  
3627 sub putNextFirstCut($@) #CU Move the specified B<$node> so it is first in the next node with the optional context. Return $node on success else return B<undef> on failure.
3628 {my ($node, @context) = @_; # Node, context
3629 return undef unless my $next = $node->next; # The next node
3630 return undef if @context and !$next->at(@context); # Not in specified context
3631 $next->putFirstCut($node); # Move node into position
3632 }
3633  
3634 sub putNextFirstCut2($@) #CU Move the specified B<$node> so it is first in the first node with the specified optional B<@context> of the next node. Return $node on success else return B<undef> on failure.
3635 {my ($node, @context) = @_; # Node, context
3636 return undef unless my $next = $node->next; # The next node
3637 return undef unless my $first = $next->first; # The First node under the next node
3638 return undef if @context and !$first->at(@context); # Not in specified context
3639 $first->putFirstCut($node); # Move node into position
3640 }
3641  
3642 sub putPrevLastCut($@) #CU Move the specified B<$node> so it is last in the preceding node with the optional context. Return $node on success else return B<undef> on failure.
3643 {my ($node, @context) = @_; # Node, context
3644 return undef unless my $prev = $node->prev; # The previous node
3645 return undef if @context and !$prev->at(@context); # Not in specified context
3646 $prev->putLastCut($node); # Move node into position
3647 }
3648 #a
3649 #b <b/><c/>
3650 #c putPrevLastCut b
3651 #d Put last in the previous node.
3652 sub putPrevLastCut2($@) #CU Move the specified B<$node> so it is last in the last node with the specified optional context of the preceding node. Return the specified $node on success else return B<undef> on failure.
3653 {my ($node, @context) = @_; # Node, context
3654 return undef unless my $prev = $node->prev; # The previous node
3655 return undef unless my $last = $prev->last; # The last node under the previous node
3656 return undef if @context and !$last->at(@context); # Not in specified context
3657 $last->putLastCut($node); # Move node into position
3658 }
3659  
3660 sub putUpNextCut($@) #CU Move the specified B<$node>, in the optional B<@context>, which must be last under its parent, so that it is next after its parent. Return $node on success else return B<undef> on failure.
3661 {my ($node, @context) = @_; # Node, context
3662 return undef if @context and !$node->at(@context); # Not in specified context
3663 return undef unless $node->isLast; # The node must be last
3664 return undef unless my $parent = $node->parent; # The parent node
3665 $parent->putNextCut($node); # Move node into position
3666 }
3667 #a putPrevLastCut
3668 #b <b><c/></b>
3669 #c putUpNextCut c
3670 #d Cut out a last child and place it after its parent.
3671  
3672 sub putUpNextCut2($@) #CU Move the specified B<$node>, in the optional B<@context>, if $node is last after its parent which must also be last under its parent, so that $node is next after its grandparent. Return $node on success else return B<undef> on failure.
3673 {my ($node, @context) = @_; # Node, context
3674 return undef if @context and !$node->at(@context); # Not in specified context
3675 return undef unless $node->isLast; # The node must be last
3676 return undef unless my $parent = $node->parent; # Not in specified context
3677 return undef unless $parent->isLast; # The parent must also be last
3678 return undef unless my $qarent = $parent->parent; # The parent parent node
3679 $qarent->putNextCut($node); # Move node into position
3680 }
3681  
3682 sub putUpPrevCut($@) #CU Move the specified B<$node> in the optional B<@context>, if $node is first under its parent, so that it is prior to its parent. Return $node on success else return B<undef> on failure.
3683 {my ($node, @context) = @_; # Node, context
3684 return undef if @context and !$node->at(@context); # Not in specified context
3685 return undef unless $node->isFirst; # The node must be last
3686 return undef unless my $parent = $node->parent; # The parent node
3687 $parent->putPrevCut($node); # Move node into position
3688 }
3689  
3690 sub putUpPrevCut2($@) #CU Move the specified B<$node>, in the optional B<@context>, if $node is first under its parent which must also be first under its parent, so that $node is prior to its grandparent. Return the specified B<$node> on success else return B<undef> on failure.
3691 {my ($node, @context) = @_; # Node, context
3692 return undef if @context and !$node->at(@context); # Not in specified context
3693 return undef unless $node->isFirst; # The node must be first
3694 return undef unless my $parent = $node->parent; # Not in specified context
3695 return undef unless $parent->isFirst; # The parent must also be first
3696 return undef unless my $qarent = $parent->parent; # The parent parent node
3697 $qarent->putPrevCut($node); # Move node into position
3698 }
3699  
3700 # Move a block # Move a block of siblings to a new position
3701  
3702 sub moveBlockFirst($$$@) #C Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> first under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3703 {my ($start, $end, $parent, @context) = @_; # First sibling, last sibling, parent to move first under, optional context
3704 return undef if @context and !$start->at(@context); # Not in specified context
3705 my $w = $start->wrapTo($end, q(grab)); # Grab the nodes in the block
3706 $parent->putFirstCut($w); # Move block
3707 $w->unwrap; # Unwrap block in new position
3708 $start # Success
3709 }
3710  
3711 sub moveBlockLast($$$@) #C Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> last under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3712 {my ($start, $end, $parent, @context) = @_; # First sibling, last sibling, parent to move last under, optional context
3713 return undef if @context and !$start->at(@context); # Not in specified context
3714 my $w = $start->wrapTo($end, q(grab)); # Grab the nodes in the block
3715 $parent->putLastCut($w); # Move block
3716 $w->unwrap; # Unwrap block in new position
3717 $start # Success
3718 }
3719  
3720 sub moveBlockAfter($$$@) #C Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> after the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3721 {my ($start, $end, $after, @context) = @_; # First sibling, last sibling, node to move after, optional context
3722 return undef if @context and !$start->at(@context); # Not in specified context
3723 my $w = $start->wrapTo($end, q(grab)); # Grab the nodes in the block
3724 $after->putNextCut($w); # Move block
3725 $w->unwrap; # Unwrap block in new position
3726 $start # Success
3727 }
3728  
3729 sub moveBlockBefore($$$@) #C Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> before the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3730 {my ($start, $end, $before, @context) = @_; # First sibling, last sibling, node to move before, optional context
3731 return undef if @context and !$start->at(@context); # Not in specified context
3732 my $w = $start->wrapTo($end, q(grab)); # Grab the nodes in the block
3733 $before->putPrevCut($w); # Move block
3734 $w->unwrap; # Unwrap block in new position
3735 $start # Success
3736 }
3737  
3738 sub moveBlockToLastFirst($$@) #C Move the siblings starting with B<$start> in the optional context first under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3739 {my ($start, $parent, @context) = @_; # Start sibling, parent to move first under, optional context
3740 return undef if @context and !$start->at(@context); # Not in specified context
3741 my $w = $start->wrapToLast(q(grab)); # Grab the nodes in the block
3742 $parent->putFirstCut($w); # Move block
3743 $w->unwrap; # Unwrap block in new position
3744 $start # Success
3745 }
3746  
3747 sub moveBlockToLastLast($$@) #C Move the block of siblings starting with B<$start> in the optional context last under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3748 {my ($start, $parent, @context) = @_; # First sibling, parent to move last under, optional context
3749 return undef if @context and !$start->at(@context); # Not in specified context
3750 my $w = $start->wrapToLast(q(grab)); # Grab the nodes in the block
3751 $parent->putLastCut($w); # Move block
3752 $w->unwrap; # Unwrap block in new position
3753 $start # Success
3754 }
3755  
3756 sub moveBlockToLastAfter($$@) #C Move the block of siblings starting with B<$start> in the optional context after the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3757 {my ($start, $after, @context) = @_; # First sibling, node to move after, optional context
3758 return undef if @context and !$start->at(@context); # Not in specified context
3759 my $w = $start->wrapToLast(q(grab)); # Grab the nodes in the block
3760 $after->putNextCut($w); # Move block
3761 $w->unwrap; # Unwrap block in new position
3762 $start # Success
3763 }
3764  
3765 sub moveBlockToLastBefore($$@) #C Move the block of siblings starting with B<$start> in the optional context before the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3766 {my ($start, $before, @context) = @_; # First sibling, node to move before, optional context
3767 return undef if @context and !$start->at(@context); # Not in specified context
3768 my $w = $start->wrapToLast(q(grab)); # Grab the nodes in the block
3769 $before->putPrevCut($w); # Move block
3770 $w->unwrap; # Unwrap block in new position
3771 $start # Success
3772 }
3773  
3774 sub moveBlockFromFirstFirst($$@) #C Move the siblings starting with B<$start> in the optional context first under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3775 {my ($start, $parent, @context) = @_; # Start sibling, parent to move first under, optional context
3776 return undef if @context and !$start->at(@context); # Not in specified context
3777 my $w = $start->wrapFromFirst(q(grab)); # Grab the nodes in the block
3778 $parent->putFirstCut($w); # Move block
3779 $w->unwrap; # Unwrap block in new position
3780 $start # Success
3781 }
3782  
3783 sub moveBlockFromFirstLast($$@) #C Move the block of siblings starting with B<$start> in the optional context last under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3784 {my ($start, $parent, @context) = @_; # First sibling, parent to move last under, optional context
3785 return undef if @context and !$start->at(@context); # Not in specified context
3786 my $w = $start->wrapFromFirst(q(grab)); # Grab the nodes in the block
3787 $parent->putLastCut($w); # Move block
3788 $w->unwrap; # Unwrap block in new position
3789 $start # Success
3790 }
3791  
3792 sub moveBlockFromFirstAfter($$@) #C Move the block of siblings starting with B<$start> in the optional context after the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3793 {my ($start, $after, @context) = @_; # First sibling, node to move after, optional context
3794 return undef if @context and !$start->at(@context); # Not in specified context
3795 my $w = $start->wrapFromFirst(q(grab)); # Grab the nodes in the block
3796 $after->putNextCut($w); # Move block
3797 $w->unwrap; # Unwrap block in new position
3798 $start # Success
3799 }
3800  
3801 sub moveBlockFromFirstBefore($$@) #C Move the block of siblings starting with B<$start> in the optional context before the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
3802 {my ($start, $before, @context) = @_; # First sibling, node to move before, optional context
3803 return undef if @context and !$start->at(@context); # Not in specified context
3804 my $w = $start->wrapFromFirst(q(grab)); # Grab the nodes in the block
3805 $before->putPrevCut($w); # Move block
3806 $w->unwrap; # Unwrap block in new position
3807 $start # Success
3808 }
3809  
3810 #D2 Add selectively # Add new nodes unless they already exist.
3811  
3812 sub addFirst($$@) #CU Add a new node L<first|/first> below the specified B<$node> with the specified B<$tag> unless a node with that tag already exists in that position. Return the new node if it was created unless return the pre-existing node.
3813 {my ($node, $tag, @context) = @_; # Node, tag of new node, optional context
3814 return undef if @context and !$node->at(@context); # Not in specified context
3815 if (my $f = $node->first) # Existing first node
3816 {return $f if $f->tag eq $tag; # Return existing first node with matching tag
3817 }
3818 $node->putFirst($node->newTag($tag)) # Create a new node, place it first below the specified node and return the new node.
3819 }
3820  
3821 #a
3822 #b <b/>
3823 #c addFirst c b
3824 #d Add a first child if needed.
3825  
3826 sub addNext($$@) #CU Add a new node L<next|/next> the specified B<$node> and return the new node unless a node with that tag already exists in which case return the existing B<$node>.
3827 {my ($node, $tag, @context) = @_; # Node, tag of new node, optional context
3828 return undef if @context and !$node->at(@context); # Not in specified context
3829 if (my $n = $node->next) # Existing next node
3830 {return $n if $n->tag eq $tag; # Return existing next node with matching tag
3831 }
3832 $node->putNext($node->newTag($tag)) # Create a new node, place it next to the specified node and return the new node.
3833 }
3834  
3835 #a addFirst
3836 #b <b/>
3837 #c addNext c b
3838 #d Add a next child if needed.
3839  
3840 sub addPrev($$@) #CU Add a new node L<before|/prev> the specified B<$node> with the specified B<$tag> unless a node with that tag already exists in that position. Return the new node if it was created unless return the pre-existing node.
3841 {my ($node, $tag, @context) = @_; # Node, tag of new node, optional context
3842 return undef if @context and !$node->at(@context); # Not in specified context
3843 if (my $p = $node->prev) # Existing previous node
3844 {return $p if $p->tag eq $tag; # Return existing previous node with matching tag
3845 }
3846 $node->putPrev($node->newTag($tag)) # Create a new node, place it before the specified node and return the new node.
3847 }
3848  
3849 sub addLast($$@) #CU Add a new node L<last|/last> below the specified B<$node> with the specified B<$tag> unless a node with that tag already exists in that position. Return the new node if it was created unless return the pre-existing node..
3850 {my ($node, $tag, @context) = @_; # Node, tag of new node, optional context
3851 return undef if @context and !$node->at(@context); # Not in specified context
3852 if (my $l = $node->last) # Existing last node
3853 {return $l if $l->tag eq $tag; # Return existing first node with matching tag
3854 }
3855 $node->putLast($node->newTag($tag)) # Create a new node, place it last below the specified node and return the new node.
3856 }
3857  
3858 sub addWrapWith($$@) #CU L<Wrap|/wrap> the specified B<$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 B<$node>.
3859 {my ($node, $tag, @context) = @_; # Node, tag of new node, optional context
3860 return undef if @context and !$node->at(@context); # Not in specified context
3861 if (my $l = $node->parent) # Existing wrapping node
3862 {return $l if $l->tag eq $tag; # Return existing first node with matching tag
3863 }
3864 $node->wrapWith($tag) # Wrap with the specified node
3865 }
3866  
3867 sub addSingleChild($$@) #CU Wrap the content of a specified B<$node> in a new node with the specified B<$tag> unless the content is already wrapped in a single child with the specified B<$tag>.
3868 {my ($node, $tag, @context) = @_; # Node, tag of new node, optional context
3869 return undef if @context and !$node->at(@context); # Not in specified context
3870 if (my $c = $node->hasSingleChild) # Return the existing child if it is an only child and has the right tag
3871 {return $c if -t $c eq $tag;
3872 }
3873 &wrapContentWith(@_); # Normal wrap content with new node
3874 }
3875  
3876 #D2 Add text selectively # Add new text unless it already exists.
3877  
3878 sub addFirstAsText($$@) #CU Add a new text node first below the specified B<$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 B<$node>.
3879 {my ($node, $text, @context) = @_; # Node, text, optional context
3880 return undef if @context and !$node->at(@context); # Not in specified context
3881 if (my $f = $node->first) # Existing first node
3882 {return $f if $f->isText and $f->text =~ m(\A$text); # Return existing first node if is a text node with the same starting text
3883 }
3884 $node->putFirstAsText($text) # Create a new text node, place it first below the specified node and return the new text node.
3885 }
3886  
3887 sub addNextAsText($$@) #CU Add a new text node after the specified B<$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 B<$node>.
3888 {my ($node, $text, @context) = @_; # Node, text, optional context
3889 return undef if @context and !$node->at(@context); # Not in specified context
3890 if (my $n = $node->next) # Existing next node
3891 {return $n if $n->isText and $n->text =~ m(\A$text); # Return existing next node if is a text node with the same starting text
3892 }
3893 $node->putNextAsText($text) # Create a new text node, place it after the specified node and return the new text node.
3894 }
3895  
3896 sub addPrevAsText($$@) #CU Add a new text node before the specified B<$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 B<$node>.
3897 {my ($node, $text, @context) = @_; # Node, text, optional context
3898 return undef if @context and !$node->at(@context); # Not in specified context
3899 if (my $p = $node->prev) # Existing previous node
3900 {return $p if $p->isText and $p->text =~ m($text\Z); # Return existing previous node if is a text node with the same ending text
3901 }
3902 $node->putPrevAsText($text) # Create a new text node, place it before the specified node and return the new text node.
3903 }
3904  
3905 sub addLastAsText($$@) #CU Add a new text node last below the specified B<$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 B<$node>.
3906 {my ($node, $text, @context) = @_; # Node, text, optional context
3907 return undef if @context and !$node->at(@context); # Not in specified context
3908 if (my $l = $node->last) # Existing last node
3909 {return $l if $l->isText and $l->text =~ m($text\Z); # Return existing last node if is a text node with the same ending text
3910 }
3911 $node->putLastAsText($text) # Create a new text node, place it last below the specified node and return the new text node.
3912 }
3913  
3914 sub joinWithText($$$@) #CU Insert some text between the children of the current B<$node> as specified by B<$text> between all the children of the current $node as long as they all have a tag of B<$over>. Return the current $node on success or B<undef> on failure.
3915 {my ($node, $text, $over, @context) = @_; # Node, text, child tag, optional context
3916 return undef if @context and !$node->at(@context); # Not in specified context
3917 if ($node->over2(qr(\A(\s$over\s){2,}\Z))) # Check tags of children
3918 {my @c = @$node; # Children of node
3919 pop @c; # Insert between children
3920 $_->putNextAsText($text) for @c; # Insertion text offset from existing children
3921 return $node; # Success
3922 }
3923 undef # Not all children have required tag
3924 }
3925 #a
3926 #b <b/><b/><b/><b/>
3927 #c joinWithText plus b a
3928 #d Insert text between each child.
3929  
3930 #D2 Fission # Split the parent L<before|/splitBefore> or L<after|/splitAfter> the specified sibling.
3931  
3932 sub splitBefore($@) #CU Split the parent node into two identical nodes except all the siblings before the specified B<$node> are retained by the existing parent while any following siblings become siblings of the new parent node which is placed after the existing parent. The new parent is returned.
3933 {my ($node, @context) = @_; # Node to split before, optional context
3934 return undef if @context and !$node->at(@context); # Not in specified context
3935 my $p = $node->parent; # Parent
3936 $p or confess "Cannot split before the root node"; # Complain if we try to split before the root node
3937 my @c = ($node, $node->contentAfter); # Content of new node
3938 my $q = $p->dupTag; # New node
3939 $q->putFirstCut($_) for reverse @c; # Move each node after to new parent avoiding text eliding which will occur if the preceding element is text and one of the siblings is also a text segment
3940 $p->putNext($q); # Place new node after parent
3941 }
3942  
3943 sub splitAfter($@) #CU Split the parent node into two identical nodes except all the siblings after the specified B<$node> are retained by the existing parent while any preceding siblings become siblings of the new parent node which is placed before the existing parent. The new parent is returned
3944 {my ($node, @context) = @_; # Node to split before, optional context
3945 return undef if @context and !$node->at(@context); # Not in specified context
3946 my $p = $node->parent; # Parent
3947 $p or confess "Cannot split before the root node"; # Complain if we try to split before the root node
3948 my @c = ($node->contentBefore, $node); # Content of new node
3949 my $q = $p->dupTag; # New node
3950 $q->putLastCut($_) for @c; # Move each node before to new parent
3951 $p->putPrev($q); # Place new node before parent
3952 }
3953  
3954 #D2 Fusion # Join consecutive nodes
3955  
3956 sub concatenate($$@) #C Concatenate two successive nodes and return the B<$target> node.
3957 {my ($target, $source, @context) = @_; # Target node to replace, node to concatenate, optional context of $target
3958 return undef if @context and !$target->at(@context); # Not in specified context
3959 $source->parser or confess "Cannot concatenate the root node"; # Complain if we try and concatenate the root
3960 if ($source = $target->next)
3961 {$target->content = [$target->contents, $source->contents]; # Concatenate (target, source) to target
3962 }
3963 elsif ($source = $target->prev)
3964 {$target->content = [$source->contents, $target->contents]; # Concatenate (source, target) to target
3965 }
3966 else
3967 {confess "Cannot concatenate non consecutive nodes"; # Complain if the nodes are not adjacent
3968 }
3969 $source->content = []; # Concatenate
3970 $target->indexNode; # Index target node
3971 $source->indexNode; # Index source node
3972 $source->cut;
3973 $target # Return new node
3974 }
3975  
3976 sub concatenateSiblings($@) #CU Concatenate the nodes that precede and follow the specified B<$node> in the optional B<@context> as long as they have the same tag as the specified B<$node> and return the specified B<$node>.
3977 {my ($node, @context) = @_; # Concatenate around this node, optional context.
3978 return undef if @context and !$node->at(@context); # Not in specified context
3979 my $t = $node->tag; # The tag to match
3980 while(my $p = $node->prev)
3981 {last unless $p->tag eq $t; # Stop when the siblings no longer match
3982 $node->concatenate($p)
3983 }
3984 while(my $n = $node->next)
3985 {last unless $n->tag eq $t; # Stop when the siblings no longer match
3986 $node->concatenate($n) if $n->tag eq $t
3987 }
3988 $node # Return concatenating node
3989 }
3990  
3991 sub mergeDuplicateChildWithParent($@) #CU 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.
3992 {my ($parent, @context) = @_; # Parent this node, optional context.
3993 return undef if @context and !$parent->at(@context); # Not in specified context
3994 return undef unless my $child = $parent->hasSingleChild; # Not an only child
3995 return undef unless $child->tag eq $parent->tag; # Tags differ
3996 my %c = %{$child->attributes}; # Child attributes
3997 my %p = %{$parent->attributes}; # Parent attributes
3998 $p{id} = $c{id} unless $p{id}; # Transfer child id unless parent already has one
3999 delete $c{id}; # Remove child id
4000 for(sort keys %c) # Remaining attributes
4001 {return undef if $p{$_} and $p{$_} ne $c{$_}; # Attributes collide
4002 $p{$_} = $c{$_}; # Transfer non colliding attribute
4003 }
4004 $parent->attributes = \%p; # Transfer the attributes en masses as none of them collide
4005 $child->copyLabels($parent); # Copy child labels to parent
4006 $child->unwrap; # Unwrap child
4007 $parent # Return original node
4008 }
4009  
4010 #D2 Put as text # Add text to the L<parse|/parse> tree.
4011  
4012 sub putFirstAsText($$@) #CU Add a new text node first under a parent and return the new text node.
4013 {my ($node, $text, @context) = @_; # The parent node, the string to be added which might contain unparsed Xml as well as text, optional context.
4014 return undef if @context and !$node->at(@context); # Not in specified context
4015 $node->putFirst(my $t = $node->newText($text)); # Add new text node
4016 $t # Return new node
4017 }
4018  
4019 sub putTextFirst($@) #U Given a B<$node> place some B<@text> first under the $node and return the new text node else return B<undef> if this is not possible.
4020 {my ($node, @text) = @_; # The parent node, the text to be added
4021 $node->putFirst(my $t = $node->newText(join ' ', @text)); # Add new text node
4022 $t # Return new node
4023 }
4024 #a
4025 #b <b><c/></b>
4026 #c at b
4027 #c putTextFirst I shall count the seconds
4028 #d Put some text first under the current node.
4029 sub putLastAsText($$@) #CU Add a new text node last under a parent and return the new text node.
4030 {my ($node, $text, @context) = @_; # The parent node, the string to be added which might contain unparsed Xml as well as text, optional context.
4031 return undef if @context and !$node->at(@context); # Not in specified context
4032 $node->putLast(my $t = $node->newText($text)); # Add new text node
4033 $t # Return new node
4034 }
4035  
4036 sub putTextLast($@) #U Given a B<$node> place some B<@text> last under the $node and return the new text node else return B<undef> if this is not possible.
4037 {my ($node, @text) = @_; # The parent node, the text to be added
4038 $node->putLast(my $t = $node->newText(join ' ', @text)); # Add new text node
4039 $t # Return new node
4040 }
4041 #a
4042 #b <b><c/></b>
4043 #c at b
4044 #c putTextLast Each second will be an hour
4045 #d Put some text last under the current node.
4046  
4047 sub putNextAsText($$@) #CU Add a new text node following the specified B<$node> and return the new text node.
4048 {my ($node, $text, @context) = @_; # The parent node, the string to be added which might contain unparsed Xml as well as text, optional context.
4049 return undef if @context and !$node->at(@context); # Not in specified context
4050 $node->putNext(my $t = $node->newText($text)); # Add new text node
4051 $t # Return new node
4052 }
4053  
4054 sub putTextNext($@) #U Given a B<$node> place some B<@text> next to the $node and return the new text node else return B<undef> if this is not possible.
4055 {my ($node, @text) = @_; # The parent node, the text to be added
4056 $node->putNext(my $t = $node->newText(join ' ', @text)); # Add new text node
4057 $t # Return new node
4058 }
4059  
4060 sub putPrevAsText($$@) #CU Add a new text node following the specified B<$node> and return the new text node
4061 {my ($node, $text, @context) = @_; # The parent node, the string to be added which might contain unparsed Xml as well as text, optional context.
4062 return undef if @context and !$node->at(@context); # Not in specified context
4063 $node->putPrev(my $t = $node->newText($text)); # Add new text node
4064 $t # Return new node
4065 }
4066  
4067 sub putTextPrev($@) #U Given a B<$node> place some B<@text> prior to the $node and return the new text node else return B<undef> if this is not possible.
4068 {my ($node, @text) = @_; # The parent node, the text to be added
4069 $node->putPrev(my $t = $node->newText(join ' ', @text)); # Add new text node
4070 $t # Return new node
4071 }
4072  
4073 #D2 Put as tree # Add parsed text to the L<parse|/parse> tree.
4074  
4075 sub putFirstAsTree($$@) #C Put parsed text first under the specified B<$node> parent and return a reference to the parsed tree. Confess if the text cannot be parsed successfully.
4076 {my ($node, $text, @context) = @_; # The parent node, the string to be parsed and added, context
4077 return undef if @context and !$node->at(@context); # Not in specified context
4078 $node->putFirst(new($text)) # Add new parse tree first
4079 }
4080  
4081 sub putLastAsTree($$@) #C Put parsed text last under the specified B<$node> parent and return a reference to the parsed tree. Confess if the text cannot be parsed successfully.
4082 {my ($node, $text, @context) = @_; # The parent node, the string to be parsed and added, context
4083 return undef if @context and !$node->at(@context); # Not in specified context
4084 $node->putLast(new($text)) # Add new parse tree last
4085 }
4086  
4087 sub putNextAsTree($$@) #C Put parsed text after the specified B<$node> parent and return a reference to the parsed tree. Confess if the text cannot be parsed successfully.
4088 {my ($node, $text, @context) = @_; # The parent node, the string to be parsed and added, context
4089 return undef if @context and !$node->at(@context); # Not in specified context
4090 $node->putNext(new($text)) # Add new parse tree
4091 }
4092  
4093 sub putPrevAsTree($$@) #C Put parsed text before the specified B<$parent> parent and return a reference to the parsed tree. Confess if the text cannot be parsed successfully.
4094 {my ($node, $text, @context) = @_; # The parent node, the string to be parsed and added, context
4095 return undef if @context and !$node->at(@context); # Not in specified context
4096 $node->putPrev(new($text)) # Add new parse tree
4097 }
4098  
4099 #D2 Put as comment # Add some comments to the parse tree relative to the specified B<$node> in the optional B<$context> and return the specified B<$node>.
4100  
4101 sub putFirstAsComment($$@) #CU Put a comment first under the specified B<$node> and return the specified B<$node>.
4102 {my ($node, $text, @context) = @_; # Parent node, comment, context
4103 return undef if @context and !$node->at(@context); # Not in specified context
4104 $node->putFirstAsText(qq(<!-- $text -->)); # Put comment first
4105 }
4106  
4107 sub putLastAsComment($$@) #CU Put a comment last under the specified B<$node> and return the specified B<$node>.
4108 {my ($node, $text, @context) = @_; # Parent node, comment, context
4109 return undef if @context and !$node->at(@context); # Not in specified context
4110 $node->putLastAsText(qq(<!-- $text -->)); # Put comment last
4111 }
4112  
4113 sub putNextAsComment($$@) #CU Put a comment after the specified B<$node> and return the specified B<$node>
4114 {my ($node, $text, @context) = @_; # Node, comment, context
4115 return undef if @context and !$node->at(@context); # Not in specified context
4116 $node->putNextAsText(qq(<!-- $text -->)); # Put comment as next node
4117 }
4118  
4119 sub putPrevAsComment($$@) #CU Put a comment before the specified B<$parent> parent and return the specified B<$node>
4120 {my ($node, $text, @context) = @_; # Node, comment, context
4121 return undef if @context and !$node->at(@context); # Not in specified context
4122 $node->putPrevAsText(qq(<!-- $text -->)); # Put comment as previous node
4123 }
4124  
4125 #D2 Break in and out # Break nodes out of nodes or push them back
4126  
4127 sub breakIn($@) #CU 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 L<breakInBackwards|/breakInBackwards>, to concatenate only the following nodes, use L<breakInForwards|/breakInForwards>.
4128 {my ($start, @context) = @_; # The start node, optional context.
4129 return undef if @context and !$start->at(@context); # Not in specified context
4130 $start->breakInBackwards; # The nodes before the start node
4131 $start->breakInForwards # The nodes following the start node
4132 }
4133  
4134 sub breakInForwards($@) #CU Concatenate the nodes following the start node, unwrapping nodes whose tag matches the start node and return the start node in the manner of L<breakIn|/breakIn>.
4135 {my ($start, @context) = @_; # The start node, optional context..
4136 return undef if @context and !$start->at(@context); # Not in specified context
4137 my $tag = $start->tag; # The start node tag
4138 for my $item($start->contentAfter) # Each item following the start node
4139 {$start->putLast($item->cut); # Concatenate item
4140 if ($item->tag eq $tag) # Unwrap items with the same tag as the start node
4141 {$item->unwrap; # Start a new clone of the parent
4142 }
4143 }
4144 $start # Return the start node
4145 }
4146  
4147 sub breakInBackwards($@) #CU Concatenate the nodes preceding the start node, unwrapping nodes whose tag matches the start node and return the start node in the manner of L<breakIn|/breakIn>.
4148 {my ($start, @context) = @_; # The start node, optional context..
4149 return undef if @context and !$start->at(@context); # Not in specified context
4150 my $tag = $start->tag; # The start node tag
4151 for my $item(reverse $start->contentBefore) # Each item preceding the start node reversing from the start node
4152 {$start->putFirst($item->cut); # Concatenate item
4153 if ($item->tag eq $tag) # Unwrap items with the same tag as the start node
4154 {$item->unwrap; # Start a new clone of the parent
4155 }
4156 }
4157 $start # Return the start node
4158 }
4159  
4160 sub breakOut($@) #U 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.
4161 {my ($parent, @tags) = @_; # The parent node, the tags of the modes to be broken out.
4162 my %tags = map {$_=>1} @tags; # Tags to break out
4163 my %attributes = %{$parent->attributes}; # Attributes of parent
4164 my $parentTag = $parent->tag; # The tag of the parent
4165 my $p; # Clone of parent currently being built
4166 for my $item($parent->contents) # Each item
4167 {if ($tags{$item->tag}) # Item to break out
4168 {$parent->putPrev($item->cut); # Position item broken out
4169 $p = undef; # Start a new clone of the parent
4170 }
4171 else # Item to remain in situ
4172 {if (!defined($p)) # Create a new parent clone
4173 {$parent->putPrev($p = $parent->newTag($parent->tag, %attributes)); # Position new parent clone
4174 }
4175 $p->putLast($item->cut); # Move current item into parent clone
4176 }
4177 }
4178 $parent->cut # Remove the original copy of the parent from which the clones were made
4179 }
4180  
4181 sub breakOutChild($@) #CU Lift the specified B<$node> up one level splitting its parent. Return the specified B<$node> on success or B<undef> if the operation is not possible.
4182 {my ($node, @context) = @_; # Node to break out, optional context
4183 return undef if @context and !$node->at(@context); # Not in specified context
4184 my $parent = $node->parent; # Parent node
4185 return undef unless $parent; # Cannot break out the root node
4186 my $grandParent = $parent->parent; # Parent of parent node
4187 return undef unless $grandParent; # Cannot break out of the root node
4188 my %attributes = %{$parent->attributes}; # Attributes of parent
4189 my $parentTag = $parent->tag; # The tag of the parent
4190 my $prevParent = $parent->putPrev($parent->newTag($parent->tag, %attributes));# Position new parent clone
4191 my $p; # Clone of parent currently being built
4192 for my $item($node->contentBefore) # Each preceding sibling
4193 {$prevParent->putLast($item->cut); # Reposition preceding sibling
4194 }
4195 $parent->putPrev($node->cut); # Reposition child
4196 $node # Return broken out node
4197 }
4198  
4199 #D2 Split and Zip # Move a node up the parse tree by splitting its parent nodes
4200  
4201 sub splitParentAfter($@) #CU Finish and restart the parent of the specified B<$node> just after the specified B<$node> and return the newly created parent node on success or B<undef> on failure.
4202 {my ($node, @context) = @_; # The splitting node, optional context.
4203 return undef if @context and !$node->at(@context); # Not in specified context
4204 return undef unless my $p = $node->parent; # Parent to split
4205 my @c = $p->contents; # Siblings to keep
4206 my @C; # Siblings to reparent
4207 unshift @C, pop @c while @c && $c[-1] != $node; # Nodes to keep as is
4208 $p->content = [@c]; # Content for existing tag
4209 my $P = $p->dupTag; # Duplicate a node
4210 $p->putNext($P); # Insert new node
4211 $P->content = [@C]; # Content for new tag
4212 $_->indexNode for $p, $P; # Reindex parent nodes
4213 $P
4214 }
4215  
4216 BEGIN{*spa=*splitParentAfter}
4217  
4218 sub splitParentBefore($@) #CU Finish and restart the parent of the specified B<$node> just before the specified B<$node> and return the newly created parent node on success or B<undef> on failure.
4219 {my ($node, @context) = @_; # The splitting node, optional context.
4220 return undef if @context and !$node->at(@context); # Not in specified context
4221 return undef unless my $p = $node->parent; # Parent to split
4222 my @C = $p->contents; # Siblings to keep
4223 my @c; # Siblings to reparent
4224 push @C, shift @c while @c && $c[-1] != $node; # Nodes to keep as is
4225 $p->content = [@c]; # Content for existing tag
4226 my $P = $p->dupTag; # Duplicate a node
4227 $p->putPrev($P); # Insert new node
4228 $P->content = [@C]; # Content for new tag
4229 $_->indexNode for $p, $P; # Reindex parent nodes
4230 $P
4231 }
4232  
4233 BEGIN{*spb=*splitParentBefore}
4234  
4235 sub splitTo($$@) #C Lift the specified B<$node> up until it splits the specified B<$parent> node. Return the specified B<$node> on success or B<undef> if the operation is not possible.
4236 {my ($node, $parent, @context) = @_; # Node to break out, ancestral node to split, optional context
4237 return undef if @context and !$node->at(@context); # Not in specified context
4238 return undef if $node == $parent; # Not breakable
4239 return undef unless $node->parent; # The node has to have a parent to split
4240 return undef unless $parent->parent; # The parent will have to have a parent as well if the parent is to be splittable.
4241 my @p = $node->belowPath($parent); # Path to parent
4242 return undef unless @p; # No path to parent
4243 $node->breakOutChild for 1..@p; # Break up along the path
4244 return $node; # Return child in new position
4245 }
4246  
4247 sub adoptChild($$@) #C Lift the specified B<$child> node up until it is an immediate child of the specified B<$parent> node by splitting any intervening nodes. Return the specified B<$child> node on success or B<undef> if the operation is not possible.
4248 {my ($parent, $child, @context) = @_; # Adopting parent node, child node to adopt, optional context of child
4249 return undef if @context and !$child->at(@context); # Child not in specified context
4250 return undef if $child == $parent; # Cannot adopt oneself
4251 return undef unless $child->parent; # Cannot adopt the root
4252 my @p = $child->belowPath($parent); # Path to parent
4253 return undef unless @p; # No path to parent
4254 pop @p; # Split up to the parent but not the parent
4255 $child->breakOutChild for 1..@p; # Break up along the path
4256 return $child; # Return child in new position
4257 }
4258  
4259 sub zipDownOnce($@) #CU Push a node down one level by making it a child of a node formed by merging the preceding and following siblings if they have the same tag.
4260 {my ($node, @context) = @_; # Node, optional context
4261 return undef if @context and !$node->at(@context); # Node not in specified context
4262 my $n = $node->next; # Next siblings
4263 my $p = $node->prev; # Previous sibling
4264 return undef unless $n and $p and $n->tag eq $p->tag; # Next and previous siblings must have same tag
4265 $p->putLastCut($_) for $node, @{$n->content}; # Extend previous sibling
4266 $n->cut; # Remove next sibling
4267 $node # Return node in new position
4268 }
4269  
4270 sub zipDown($@) #CU Push a node down as many levels as possible by making it a child of a node formed by merging the preceding and following siblings if they have the same tag.
4271 {my ($node, @context) = @_; # Node, optional context
4272 return undef if @context and !$node->at(@context); # Node not in specified context
4273 undef while $node->zipDownOnce; # Zip down for as long as possible
4274 $node # Return node in new position
4275 }
4276  
4277 sub splitAndWrapFromStart($$$@) #CU Split the child nodes of B<$parent> on the child nodes with a tag of B<$split> wrapping the splitting node and all preceding nodes from the previous splitting node or the start with the specified B<$wrap>ping node with optional B<%attributes>. Returns an array of the wrapping nodes created.
4278 {my ($parent, $split, $wrap, %attributes) = @_; # Parent node, tag of splitting nodes, tag for wrapping node, attributes for wrapping nodes
4279 my @s = $parent->c($split); # Splitting nodes
4280 my @w; # Wrapping nodes
4281 for my $i(reverse keys @s) # Each splitting node
4282 {my $s = $s[$i];
4283 if ($i) # From previous split
4284 {push @w, $s[$i-1]->next->wrapTo($s, $wrap, %attributes); # Save wrapping node
4285 }
4286 else # From start
4287 {push @w, $s->wrapFromFirst($wrap, %attributes); # Save wrapping node
4288 }
4289 }
4290 @w
4291 }
4292  
4293 sub splitAndWrapToEnd($$$@) #CU Split the sequence of child nodes under the specified B<$parent> node on those child nodes whose tag value is B<$split> wrapping the splitting node and all following nodes up until the next splitting node or the end of the sequence with newly created nodes whose tag is B<$wrap> with optional attributes B<%attributes>. Returns an array of the wrapping nodes so created.
4294 {my ($parent, $split, $wrap, %attributes) = @_; # Parent node, tag of splitting nodes, tag for wrapping node, attributes for wrapping nodes
4295 my @s = $parent->c($split); # Splitting nodes
4296 my @w; # Wrapping nodes
4297 for my $i(keys @s) # Each splitting node
4298 {my $s = $s[$i];
4299 if ($i != $#s) # More splits to come
4300 {push @w, $s->wrapTo($s[$i+1]->prev, $wrap, %attributes); # Save wrapping node
4301 }
4302 else # Last splitting node
4303 {push @w, $s->wrapToLast($wrap, %attributes); # Save wrapping node
4304 }
4305 }
4306 @w
4307 }
4308  
4309 #D2 Replace # Replace nodes in the L<parse|/parse> tree with nodes or text
4310  
4311 sub replaceWith($$@) #C Replace a node (and all its content) with a L<new node|/newTag> (and all its content) and return the new node. If the node to be replaced is the root of the L<parse|/parse> tree then no action is taken other then returning the new node.
4312 {my ($old, $new, @context) = @_; # Old node, new node, optional context..
4313 return undef if @context and !$old->at(@context); # Not in specified context
4314 $new->parent and confess "Please cut out the node before moving it"; # The node must have be cut out first
4315 $new->parser == $new and $old->parser == $new and # Prevent a root node from being inserted into a sub tree
4316 confess "Recursive replacement attempted";
4317  
4318 if (my $parent = $old->parent) # Parent node of old node
4319 {my $c = $parent->content; # Content array of parent
4320 if (defined(my $i = $old->position)) # Position of old node in content array of parent
4321 {splice(@$c, $i, 1, $new); # Replace old node with new node
4322 $old->parent = undef; # Cut out node
4323 $parent->indexNode; # Rebuild indices for parent
4324 return $new; # Return new node
4325 }
4326 confess "Should not happen";
4327 }
4328 else # Replacing the root - merge the new node rather than replacing it so that we do not loose addressability to the old tree
4329 {$old->tag = $new->tag;
4330 $old->content = $new->content;
4331 $old->attributes = $new->attributes;
4332 return $old;
4333 }
4334 }
4335  
4336 sub replaceWithText($$@) #CU Replace a node (and all its content) with a new text node and return the new node.
4337 {my ($old, $text, @context) = @_; # Old node, text of new node, optional context.
4338 return undef if @context and !$old->at(@context); # Not in specified context
4339 my $n = $old->replaceWith($old->newText($text)); # Create a new text node, replace the old node and return the result
4340 $n
4341 }
4342  
4343 sub replaceWithBlank($@) #CU Replace a node (and all its content) with a new blank text node and return the new node.
4344 {my ($old, @context) = @_; # Old node, optional context.
4345 return undef if @context and !$old->at(@context); # Not in specified context
4346 my $n = $old->replaceWithText(' '); # Create a new text node, replace the old node with a new blank text node and return the result
4347 $n
4348 }
4349  
4350 sub 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.
4351 {my ($node, @nodes) = @_; # Target node, source nodes
4352 my @content; # Target content array
4353 for my $source(@nodes) # Each source node
4354 {push @content, $source->contents; # Build target content array
4355 $source->content = undef; # Move content
4356 $source->indexNode; # Rebuild indices
4357 }
4358 $node->content = [@content]; # Insert new content
4359 $node->indexNode; # Rebuild indices
4360 $node # Return target node
4361 }
4362  
4363 sub replaceContentWith($@) # Replace the content of a node with the specified nodes and return the replaced content
4364 {my ($node, @content) = @_; # Node whose content is to be replaced, new content
4365 my @c = $node->contents; # Content
4366 $node->content = [@content]; # Insert new content
4367 $node->indexNode; # Rebuild indices
4368 @c # Return old content
4369 }
4370  
4371 sub replaceContentWithText($@) #U Replace the content of a node with the specified texts and return the replaced content
4372 {my ($node, @text) = @_; # Node whose content is to be replaced, texts to form new content
4373 my @c = $node->contents; # Content
4374 $node->content = [map {$node->newText($_)} @text]; # Insert new content
4375 $node->indexNode; # Rebuild indices
4376 @c # Return old content
4377 }
4378  
4379 #D2 Swap # Swap nodes both singly and in blocks
4380  
4381 sub invert($@) #CU Swap a parent and child node where the child is the only child of the parent and return the parent.
4382 {my ($parent, @context) = @_; # Parent, context
4383 return undef unless my $child = $parent->hasSingleChild(@context); # Single child
4384 my $grandParent = $parent->parent; # Grandparent
4385 $grandParent or confess "Cannot invert the outer most node"; # Cannot invert root
4386 $parent->unwrap; # Unwrap parent
4387 my $content = $child->content; # Child content
4388 $child->content = [$parent]; # Place parent under child
4389 $parent->content = $content; # Place child content under parent
4390 $child->parent = $grandParent; # Grand parent
4391 $parent->parent = $child; # Parent
4392 $_->indexNode for $child, $parent, $grandParent; # Index modified nodes
4393 $parent # Return parent
4394 }
4395  
4396 sub invertFirst($@) #CU 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.
4397 {my ($parent, @context) = @_; # Parent, context
4398 return undef if @context and !$parent->at(@context); # Not in specified context
4399 return undef unless my $child = $parent->first; # First child
4400 my $grandParent = $parent->parent; # Grandparent
4401 $grandParent or confess "Cannot invertFirst the outer most node"; # Cannot invert root
4402 my $i = $parent->index; # Position of parent in grandparent
4403 $parent->cut; # Cut out parent
4404 $child->cut; # Cut out child
4405 $child->putLast($parent); # Put parent last under child
4406 $grandParent->content->[$i] = $child; # Put child in position in grandparent
4407 $_->indexNode for $child, $parent, $grandParent; # Index modified nodes
4408 $child->parent = $grandParent; # Grand parent
4409 $parent # Return parent
4410 }
4411  
4412 sub invertLast($@) #CU 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.
4413 {my ($parent, @context) = @_; # Parent, context
4414 return undef if @context and !$parent->at(@context); # Not in specified context
4415 return undef unless my $child = $parent->last; # Last child
4416 my $grandParent = $parent->parent; # Grandparent
4417 $grandParent or confess "Cannot invert the outer most node"; # Cannot invert root
4418 my $i = $parent->index; # Position of parent in grandparent
4419 $parent->cut; # Cut out parent
4420 $child->cut; # Cut out child
4421 $child->putFirst($parent); # Put parent last under child
4422 $grandParent->content->[$i] = $child; # Put child in position in grandparent
4423 $child->parent = $grandParent; # Grand parent
4424 $_->indexNode for $child, $parent, $grandParent; # Index modified nodes
4425 $parent # Return parent
4426 }
4427  
4428 sub swap($$@) #C Swap two nodes optionally checking that the first node is in the specified context and return the first node.
4429 {my ($first, $second, @context) = @_; # First node, second node, optional context
4430 return undef if @context and !$first->at(@context); # First node not in specified context
4431 confess "First node is above second node" if $first->above($second); # Check that the first node is not above the second node otherwise the result of the swap would not be a tree
4432 confess "First node is below second node" if $first->below($second); # Check that the first node is not above the second node otherwise the result of the swap would not be a tree
4433 return $first if $first == $second; # Do nothing if the first node is the second node
4434 my $f = $first ->wrapWith(q(temp)); # Wrap first node for transfer
4435 my $s = $second->wrapWith(q(temp)); # Wrap second node for transfer
4436 $f->putLast($second->cut); # Transfer second node
4437 $s->putLast($first ->cut); # Transfer first node
4438 $_->unwrap for $f, $s; # Remove wrapping
4439 $first # Return first node
4440 }
4441  
4442 sub swapFirstSibling($@) #CU Swap B<$node> with its first sibling node and return B<$node>.
4443 {my ($node, @context) = @_; # Node, optional context
4444 return undef if @context and !$node->at(@context); # Node not in specified context
4445 return undef unless my $parent = $node->parent; # Cannot swap root node
4446 my ($f1, $f2) = @$parent; # First two nodes
4447 return $node if $node == $f1; # Already the first node
4448 $node->putNextCut($f1); # Move first node into position
4449 return $node if $node == $f2; # Was second, now first
4450 $parent->putFirstCut($node); # Move node first
4451 }
4452  
4453 BEGIN{*sfs=*swapFirstSibling}
4454  
4455 sub swapNext($@) #CU Swap B<$node> with its following node if $B<$node> matches the first element of the specified context and the next node matches the rest. Return the node that originally followed B<$node> on success or B<undef> on failure.
4456 {my ($node, @context) = @_; # Node, optional context
4457 my $next = $node->next; # Next node
4458 return undef unless $next; # No following node so no swap possible
4459 if (@context) # Check supplied context
4460 {my ($c, $d, @c) = @context;
4461 return undef unless $node->at($c, @c); # Node not in context
4462 return undef unless !$d or $next->at($d, @c); # Following node not in context
4463 }
4464 $next->putNextCut($node); # Swap nodes
4465 $next # Return other node
4466 }
4467  
4468 BEGIN{*sn=*swapNext}
4469  
4470 sub swapPrev($@) #CU Swap B<$node> with its preceding node if $B<$node> matches the first element of the specified context and the previous node matches the rest. Return the node that originally followed B<$node> on success or B<undef> on failure.
4471 {my ($node, @context) = @_; # Node, optional context
4472 my $prev = $node->prev; # Previous node
4473 return undef unless $prev; # No previous node so no swap possible
4474 if (@context) # Check supplied context
4475 {my ($c, $d, @c) = @context;
4476 return undef unless $node->at($c, @c); # Node not in context
4477 return undef unless !$d or $prev->at($d, @c); # Following node not in context
4478 }
4479 $prev->putPrevCut($node); # Swap nodes
4480 $prev # Return other node
4481 }
4482  
4483 BEGIN{*sp=*swapPrev}
4484  
4485 sub swapLastSibling($@) #CU Swap B<$node> with its last sibling node and return B<$node>.
4486 {my ($node, @context) = @_; # Node, optional context
4487 return undef if @context and !$node->at(@context); # Node not in specified context
4488 return undef unless my $parent = $node->parent; # Cannot swap root node
4489 my ($l1, $l2) = reverse @$parent; # Last two nodes
4490 return $node if $node == $l1; # Already the last node
4491 $node->putPrevCut($l1); # Move last node into position
4492 return $node if $node == $l2; # Was second last, now last
4493 $parent->putLastCut($node); # Move node last
4494 }
4495  
4496 BEGIN{*sls=*swapLastSibling}
4497  
4498 sub swapTags($$@) #C Swap the tags of two nodes optionally checking that the first node is in the specified context and return (B<$first>, B<$second>) nodes.
4499 {my ($first, $second, @context) = @_; # First node, second node, optional context
4500 return undef if @context and !$first->at(@context); # First node not in specified context
4501 my ($t, $T) = ($first->tag, $second->tag); # Tags
4502 $first ->change($T);
4503 $second->change($t);
4504 ($first, $second) # Return nodes
4505 }
4506  
4507 sub swapTagWithParent($@) #CU Swap the tags of the specified B<$node> and its parent optionally checking that the B<$node> is in the specified context and return (parent of B<$node>, B<$node>) or () if there is no such parent node.
4508 {my ($node, @context) = @_; # Node, optional context
4509 return () if @context and !$node->at(@context); # Node not in specified context
4510 return () unless my $p = $node->parent; # No parent for node to swap with
4511 $p->swapTags($node) # Swap tags
4512 }
4513  
4514 sub reorder($$$@) #CU If the current B<$node> has a context of (B<$first>, @context) and the preceding node has a context of (B<$second>, B<@context>), then swap the current node with the previous node.Return the current node regardless
4515 {my ($node, $first, $second, @context) = @_; # Node, first tag, second tag, optional context
4516 return undef unless $node->at($first, @context); # Node not in specified context
4517 return undef unless my $prev = $node->prev; # No previous node
4518 return undef unless $prev->at($second, @context); # Previous node not in specified context
4519 $node->putNextCut($prev); # Reorder nodes
4520 $node # Return the current node
4521 }
4522 #a
4523 #b <c/><b/>
4524 #c reorder b c
4525 #d Reorder two adjacent nodes if they are out of order.
4526  
4527 #D2 Wrap and unwrap # Wrap and unwrap nodes to alter the depth of the L<parse|/parse> tree
4528 #D3 Wrap # Wrap nodes to deepen the L<parse|/parse> tree
4529  
4530 sub wrapWith($$@) #IU Wrap the specified B<$node> in a new node created from the specified B<$tag> in the optional B<@context> forcing the specified $node down to deepen the L<parse|/parse> tree - return the new wrapping node or B<undef> if this is not possible. See L<addWrapWith|/addWrapWith> to perform this operation conditionally.
4531 {my ($node, $tag, @context) = @_; # Node, tag for the new node or tag, optional context
4532 return undef if @context and !$node->at(@context); # Node not in specified context
4533 my $new = newTag(undef, $tag); # Create wrapping node
4534 if (my $par = $node->parent) # Parent node exists
4535 {my $c = $par->content; # Content array of parent
4536 my $i = $node->position; # Position in content array
4537 splice(@$c, $i, 1, $new); # Replace node
4538 $new->parser = $node->parser; # Assign the new node to the old parser
4539 $node->parent = $new; # Set parent of original node as wrapping node
4540 $new->parent = $par; # Set parent of wrapping node
4541 $new->content = [$node]; # Create content for wrapping node
4542 $par->indexNode; # Rebuild indices for parent
4543 }
4544 else # At the top - no parent
4545 {$new->parser = $new; # Assign the new node to the old parser
4546 $node->by(sub{$_->parser = $new}); # Set parser node so ditaTopicHeaders works - not entirely satisfactory but then w have to assume that the parser node is important enough to maintain.
4547 $new->content = [$node]; # Create content for wrapping node
4548 $node->parent = $new; # Set parent of original node as wrapping node
4549 $new->parent = undef; # Set parent of wrapping node - there is none
4550 }
4551 $new->indexNode; # Create index for wrapping node
4552 $new # Return wrapping node
4553 }
4554 #a unwrap addWrapWith
4555 #b <c/>
4556 #c wrapWith b c
4557 #d Wrap a child with a new parent.
4558  
4559 sub wrapWithDup($@) #U Wrap the specified B<$node> in a new node with the same tag as $node in the optional B<@context> making $node an L<only child|/isOnlyChild> of the new node. Return the new wrapping node or B<undef> if this is not possible.
4560 {my ($node, @context) = @_; # Node, optional context
4561 $node->wrapWith($node->tag, @context);
4562 }
4563  
4564 sub wrapUp($@) #U Wrap the specified B<$node> in a sequence of new nodes created from the specified B<@tags> forcing the original node down - deepening the L<parse|/parse> tree - return the array of wrapping nodes if want array else the last wrapping node.
4565 {my ($node, @tags) = @_; # Node to wrap, tags to wrap the node with - with the uppermost tag rightmost.
4566 my @n = map {$node = $node->wrapWith($_)} @tags; # Wrap up
4567 wantarray ? @n : @n ? $n[-1] : undef;
4568 }
4569  
4570 sub wrapWithN($$@) #CU Wrap this B<$node> with the first B<$N> elements of B<@context>. If B<@context> contains more then B<$N> entries, the remainder are checked as the context of B<$node>. Returns the upper most wrapping node or B<undef> if the specified B<$node> does not match these conditions.
4571 {my ($node, $N, @context) = @_; # Node, number of tags wrapping tags, tags and optional context
4572 @context >= $N or confess "Not enough context"; # Must have at least enough tags to match N e
4573 my @tags; push @tags, shift @context for 1..$N; # Separate context into wrapping tags and context
4574 return undef if @context and !$node->at(@context); # Not in specified context
4575 for my $tag(@tags) # Wrap with each wrapping tag
4576 {$node = $node->wrapWith($tag); # Wrap
4577 }
4578 $node # Return last wrapping node
4579 }
4580  
4581 sub wrapWithAll($@) #CU Wrap this B<$node> wrapped with the specified B<@tags> and return the last wrapping node.
4582 {my ($node, @tags) = @_; # Node, tags
4583 for my $tag(@tags) # Wrap with each wrapping tag
4584 {$node = $node->wrapWith($tag); # Wrap
4585 }
4586 $node # Return last wrapping node
4587 }
4588  
4589 BEGIN{*ww=*wrapWithAll}
4590  
4591 sub wrapDown($@) #U Wrap the content of the specified B<$node> in a sequence of new nodes forcing the original node up - deepening the L<parse|/parse> tree - return the array of wrapping nodes if want array else the last wrapping node.
4592 {my ($node, @tags) = @_; # Node to wrap, tags to wrap the node with - with the uppermost tag rightmost.
4593 my @n = map {$node = $node->wrapContentWith($_)} @tags; # Wrap down
4594 wantarray ? @n : @n ? $n[-1] : undef;
4595 }
4596  
4597 sub wrapContentWith($$@) #U Wrap the content of the specified B<$node> in a new node created from the specified B<$tag> and B<%attributes>: the specified B<$node> then contains just the new node which, in turn, contains all the content of the specified B<$node>.\mReturns the new wrapping node.
4598 {my ($old, $tag, %attributes) = @_; # Node, tag for new node, attributes for new node.
4599 my $new = newTag(undef, $tag, %attributes); # Create wrapping node
4600 $new->parser = $old->parser; # Assign the new node to the old parser
4601 $new->content = $old->content; # Transfer content
4602 $old->content = [$new]; # Insert new node
4603 $new->indexNode; # Create indices for new node
4604 $old->indexNode; # Rebuild indices for old mode
4605 $new # Return new node
4606 }
4607  
4608 BEGIN{*wcw=*wrapContentWith}
4609  
4610 sub wrapContentWithDup($@) #U Wrap the content if the specified B<$node> in a new node with the same tag as $node in the optional B<@context> making the new node an L<only child|/isOnlyChild> of $node. Return the new wrapping node or B<undef> if this is not possible.
4611 {my ($node, @context) = @_; # Node, optional context
4612 $node->wrapContentWith($node->tag, @context);
4613 }
4614  
4615 sub wrapSiblingsBefore($$@) #U If there are any siblings before the specified B<$node>, wrap them with a new node created from the specified B<$tag> and B<%attributes> and return the newly created node.\mReturns B<undef> if the specified B<$node> is the first node under its parent.
4616 {my ($node, $tag, %attributes) = @_; # Node to wrap before, tag for new node, attributes for new node.
4617 my $first = $node->firstSibling; # First sibling
4618 return undef if $node == $first; # We are the first sibling so no wrapping is possible
4619 $first->wrapTo($node->prev, $tag, %attributes); # Wrap the preceding nodes
4620 }
4621  
4622 sub wrapFromFirst($$@) #U Wrap this B<$node> and any preceding siblings with a new node created from the specified B<$tag> and B<%attributes> and return the wrapping node.
4623 {my ($node, $tag, %attributes) = @_; # Node to wrap before, tag for new node, attributes for new node.
4624 $node->firstSibling->wrapTo($node, $tag, %attributes); # Wrap this node and any preceding nodes
4625 }
4626  
4627 sub wrapFromFirstOrLastIn($$@) #U Wrap inclusively from the first sibling node to the specified B<$node> or from the last prior sibling node whose tag matches one of the tags in B<@targets> to the specified B<$node> using B<$tag> as the tag of the wrapping node and return the wrapping node.
4628 {my ($node, $tag, @targets) = @_; # Node at which to start to wrap, wrapping tag, tags at which to end the wrap.
4629 my $target = $node->prevIn(@targets) // $node->firstSibling; # Target node
4630 $node->wrapFrom($target, $tag); # Wrap from the target node to the specified node inclusively
4631 }
4632  
4633 sub wrapFirstN($$$@) #U Wrap the first B<$N> nodes under this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
4634 {my ($node, $N, $tag, @context) = @_; # Node, number of nodes to wrap, wrapping tag, optional context
4635 return () if @context and !$node->at(@context); # Node not in specified context
4636 my @c = $node->contents; # Content
4637 pop @c while @c and @c > $N; # Remove excess content
4638 return undef unless @c == $N; # Check we have enough nodes to wrap
4639 $c[0]->wrapTo($c[-1], $tag); # Wrap the first $N nodes and return the wrapping node
4640 }
4641  
4642 sub wrapSiblingsBetween($$$@) # If there are any siblings between the specified B<$node>s, wrap them with a new node created from the specified B<$tag> and B<%attributes>. Return the wrapping node else B<undef> if there are no nodes to wrap.
4643 {my ($first, $last, $tag, %attributes) = @_; # First sibling, last sibling, tag for new node, attributes for new node.
4644 my $parent = $first->parent; # Check parentage
4645 $parent or confess "Cannot wrap between siblings using the root node";
4646 $parent == $last->parent or confess "Not siblings";
4647  
4648 my ($i, $j) = map {$_->position} my ($f, $l) = ($first, $last); # Get the node indexes so we can order them
4649 return $f->next->wrapWith( $tag, %attributes) if $i == $j - 2; # One intervening node
4650 return $l->next->wrapWith( $tag, %attributes) if $j == $i - 2;
4651 return $f->next->wrapTo ($l->prev, $tag, %attributes) if $i < $j - 2; # Several intervening nodes
4652 return $l->next->wrapTo ($f->prev, $tag, %attributes) if $j < $i - 2;
4653 undef # No intervening nodes
4654 }
4655  
4656 sub wrapSiblingsAfter($$@) #U If there are any siblings after the specified B<$node>, wrap them with a new node created from the specified B<$tag> and B<%attributes> and return the newly created node.\mReturns B<undef> if the specified B<$node> is the last node under its parent.
4657 {my ($node, $tag, %attributes) = @_; # Node to wrap before, tag for new node, attributes for new node.
4658 my $last = $node->lastSibling; # Last sibling
4659 return undef if $node == $last; # We are the last sibling so no wrapping is possible
4660 $node->next->wrapTo($last, $tag, %attributes); # Wrap the following nodes
4661 }
4662  
4663 sub wrapNext($$@) #U Wrap this B<$node> and the following sibling with a new node created from the specified B<$tag>. If the optional context is specified then it should match the first node, next node and the context of the parent of the B<$node> as far as it is specified. Return the new node created or B<undef> on failure.
4664 {my ($node, $tag, @context) = @_; # Node to wrap before, tag for new node, context.
4665 return undef unless my $next = $node->next; # Next node
4666 return undef unless my $parent = $node->parent; # Parent node
4667 return undef if @context and $node->tag ne shift @context; # Node context
4668 return undef if @context and $next->tag ne shift @context; # Next node context
4669 return undef if @context and $parent->tag ne shift @context; # Parent context
4670 $node->wrapTo($next, $tag); # Wrap this node and the next node
4671 }
4672  
4673 sub wrapNextN($$$@) #U Wrap this B<$node>and the next B<$N>-1 nodes following this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
4674 {my ($node, $N, $tag, @context) = @_; # Node, number of nodes to wrap, wrapping tag, optional context
4675 return () if @context and !$node->at(@context); # Node not in specified context
4676 my @c = ($node, $node->contentAfter); # Content after node
4677 pop @c while @c and @c > $N; # Remove excess content
4678 return undef unless @c == $N; # Check we have enough nodes to wrap
4679 $c[0]->wrapTo($c[-1], $tag); # Wrap the next $N nodes and return the wrapping node
4680 }
4681  
4682 sub wrapPrev($$@) #U Wrap this B<$node> and the preceding sibling with a new node created from the specified B<$tag>. If the optional context is specified then it should match the first node, previous node and the context of the parent of the B<$node> as far as it is specified. Return the new node created or B<undef> on failure.
4683 {my ($node, $tag, @context) = @_; # Node to wrap before, tag for new node, context.
4684 return undef unless my $prev = $node->prev; # Next node
4685 return undef unless my $parent = $node->parent; # Parent node
4686 return undef if @context and $node->tag ne shift @context; # Node context
4687 return undef if @context and $prev->tag ne shift @context; # Next node context
4688 return undef if @context and $parent->tag ne shift @context; # Parent context
4689 $prev->wrapTo($node, $tag); # Wrap this node and the previous node
4690 }
4691  
4692 sub wrapPrevN($$$@) #U Wrap this B<$node>and the previous B<$N>-1 nodes following this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
4693 {my ($node, $N, $tag, @context) = @_; # Node, number of nodes to wrap, wrapping tag, optional context
4694 return () if @context and !$node->at(@context); # Node not in specified context
4695 my @c = ($node->contentBefore, $node); # Content after node
4696 shift @c while @c and @c > $N; # Remove excess content
4697 return undef unless @c == $N; # Check we have enough nodes to wrap
4698 $c[0]->wrapTo($c[-1], $tag); # Wrap the Prev $N nodes and return the wrapping node
4699 }
4700  
4701 sub wrapToLast($$@) #U Wrap this B<$node> and any following siblings with a new node created from the specified B<$tag> and B<%attributes> and return the wrapping node.
4702 {my ($node, $tag, %attributes) = @_; # Node to wrap before, tag for new node, attributes for new node.
4703 $node->wrapTo($node->lastSibling, $tag, %attributes); # Wrap this node and any preceding nodes
4704 }
4705  
4706 sub wrapToLastOrFirstIn($$@) #U Wrap this B<$node> and any following siblings, up to and including the first sibling that matches one of the specified B<@find> nodes or all following siblings if no such match occurs, with a new node created from the specified B<$tag> and return the new wrapping node.
4707 {my ($node, $tag, @targets) = @_; # Node at which to start to wrap, wrapping tag, tags at which to end the wrap.
4708 my $target = $node->nextIn(@targets) // $node->lastSibling; # Target node
4709 $node->wrapTo($target, $tag); # Wrap this node up to and including the target
4710 }
4711  
4712 sub wrapLastN($$$@) #U Wrap the last B<$N> nodes under this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
4713 {my ($node, $N, $tag, @context) = @_; # Node, number of nodes to wrap, wrapping tag, optional context
4714 return () if @context and !$node->at(@context); # Node not in specified context
4715 my @c = $node->contents; # Content
4716 shift @c while @c and @c > $N; # Remove excess content
4717 return undef unless @c == $N; # Check we have enough nodes to wrap
4718 $c[0]->wrapTo($c[-1], $tag); # Wrap the Last $N nodes and return the wrapping node
4719 }
4720  
4721 sub wrapTo($$$@) #Y Wrap all the nodes from the B<$start> node to the B<$end> node inclusive with a new node created from the specified B<$tag> and B<%attributes> and return the new node.\mReturn B<undef> if the B<$start> and B<$end> nodes are not siblings - they must have the same parent for this method to work.
4722 {my ($start, $end, $tag, %attributes) = @_; # Start node, end node, tag for the wrapping node, attributes for the wrapping node
4723 @_ >= 3 or confess "At least three parameters required"; # The tag of the new node must be supplied!
4724 my $parent = $start->parent; # Parent
4725 confess "Start node has no parent" unless $parent; # Not possible unless the start node has a parent
4726 confess "End node has a different parent" unless $parent == $end->parent; # Not possible unless the start and end nodes have the same parent
4727 my $s = $start->position; # Start position
4728 my $e = $end->position; # End position
4729 confess "End node precedes start node" if $e < $s; # End must not precede start node
4730 $start->putPrev(my $new = $start->newTag($tag, %attributes)); # Create and insert wrapping node
4731 my @c = $parent->contents; # Content of parent
4732 $_ < @c ? $new->putLast($c[$_]->cut) : undef for $s+1..$e+1; # Move the nodes from start to end into the new node remembering that the new node has already been inserted
4733 $new # Return new node
4734 }
4735  
4736 sub wrapFrom($$$%) #Y Wrap all the nodes from the B<$start> node to the B<$end> node with a new node created from the specified B<$tag> and B<%attributes> and return the new node. Return B<undef> if the B<$start> and B<$end> nodes are not siblings - they must have the same parent for this method to work.
4737 {my ($end, $start, $tag, %attributes) = @_; # End node, start node, tag for the wrapping node, attributes for the wrapping node
4738 $start->wrapTo($end, $tag, %attributes); # Invert and wrapTo
4739 }
4740  
4741 #D3 Unwrap # Unwrap nodes to reduce the depth of the L<parse|/parse> tree
4742  
4743 sub unwrap($@) #CIYU Unwrap the specified B<$node> if in the optional B<@context> by replacing the node with its contents. Returns the parent node on success, otherwise B<undef> if an attempt is made to unwrap a text node or the root node.
4744 {my ($node, @context) = @_; # Node to unwrap, optional context.
4745 return undef if @context && !$node->at(@context) or $node->isText; # Not in specified context or a text node
4746 my $parent = $node->parent; # Parent node
4747 # $parent or confess "Cannot unwrap the outer most node"; # Root nodes cannot be unwrapped
4748 return undef unless $parent; # Root nodes cannot be unwrapped
4749 if ($node->isEmpty) # Empty nodes can just be cut out
4750 {$node->cut;
4751 }
4752 else
4753 {my $p = $parent->content; # Content array of parent
4754 my $n = $node->content; # Content array of node
4755 my $i = $node->position; # Position of node in parent
4756 splice(@$p, $i, 1, @$n); # Replace node with its content
4757 $parent->indexNode; # Rebuild indices for parent
4758 $node->disconnectLeafNode; # Disconnect node from parse tree
4759 }
4760 $parent # Return the parent node
4761 }
4762 #b <b id="b">C</b>
4763 #c unwrap b
4764 #d Delete a node retaining its content.
4765  
4766 BEGIN{*u=*unwrap}
4767  
4768 sub unwrapParentOfOnlyChild($@) #CU Unwrap the parent of the specified B<$node> in the optional B<@context> when the B<$node> is the only child of its parent. Return the specified B<$node> regardless unless the node is not in the optional context in which case return B<undef>.
4769 {my ($node, @context) = @_; # Node, optional context
4770 if ($node->isOnlyChild(@context)) # Only child of parent
4771 {$node->parent->unwrap; # Unwrap parent
4772 return $node; # Success
4773 }
4774 undef # Not in specified context
4775 }
4776  
4777 sub unwrapOnlyChild($@) #CU Unwrap the specified B<$node> in the optional B<@context> when the B<$node> is the only child of its parent. Return the specified B<$node> regardless unless the node is not in the optional context in which case return B<undef>.
4778 {my ($node, @context) = @_; # Node, optional context
4779 if ($node->isOnlyChild(@context)) # Only child of parent
4780 {$node->unwrap; # Unwrap parent
4781 return $node; # Success
4782 }
4783 undef # Not in specified context
4784 }
4785  
4786 sub unwrapParentsWithSingleChild($@) #CU Unwrap any immediate ancestors of the specified B<$node> in the optional B<@context> which have only a single child and return the specified B<$node> regardless unless the node is not in the optional context in which case return B<undef>.
4787 {my ($node, @context) = @_; # Node, optional context
4788 return undef if @context && !$node->at(@context) or $node->isText; # Not in specified context or a text node
4789 my @p; # Parents with single child
4790 for(my $p = $node->parent; $p; $p = $p->parent) # Check each parent
4791 {$node->isOnlyChild and $p->parent ? push @p, $p : last # Locate parents with single child
4792 }
4793 $_->unwrap for @p; # Unwrap parents with single child
4794 $node # Return node
4795 }
4796  
4797 sub unwrapContentsKeepingText($@) #CYU Unwrap all the non text nodes below the specified B<$node> adding a leading and a trailing space to prevent unwrapped content from being elided and return the specified B<$node> else B<undef> if not in the optional B<@context>.
4798 {my ($node, @context) = @_; # Node to unwrap, optional context.
4799 return undef if @context and !$node->at(@context); # Not in specified context
4800 $node->by(sub
4801 {if (!$_->isText and $_ != $node) # Keep interior text nodes
4802 {$_->putPrevAsText(" "); # Separate from preceding content
4803 $_->putNextAsText(" "); # Separate from following content
4804 $node->addLabels($_->id) if $_->id; # Transfer any id as a label to the specified B<$node>
4805 $_->copyLabels($node); # Transfer any labels to the specified node
4806 $_->unwrap; # Unwrap non text tag
4807 }
4808 });
4809 $node # Return the node to show success
4810 }
4811  
4812 sub wrapRuns($$@) #CU Wrap consecutive runs of children under the specified parent B<$node> that are not already wrapped with B<$wrap>. Returns an array of any wrapping nodes created. Returns () if the specified B<$node> is not in the optional B<@context>.
4813 {my ($node, $wrap, @context) = @_; # Node to unwrap, tag of wrapping node, optional context.
4814 return () if @context and !$node->at(@context); # Not in specified context
4815 my @wrap; # Wrapping nodes created
4816 my @c = @$node; # Children
4817 my $w; # The latest wrapping node
4818 for my $child(@c) # Each child node
4819 {if ($child->tag eq $wrap) # Wrapped nodes
4820 {$w = undef; # NO wrapper required
4821 }
4822 else # A child that should be wrapped
4823 {unless($w) # No current wrapper
4824 {$child->putPrev($w = $node->newTag($wrap)); # Add a wrapper
4825 push @wrap, $w; # Add a start node unless we are already have a node of the right type
4826 }
4827 $w->putLast($child->cut); # Put unwrapped child in last wrapper created
4828 }
4829 }
4830 @wrap # Return array of new wrapping nodes
4831 }
4832  
4833 #D1 Contents # The children of each node.
4834  
4835 sub contents($@) #K Return a list of all the nodes contained by the specified B<$node> or an empty list if the node is empty or not in the optional B<@context>.
4836 {my ($node, @context) = @_; # Node, optional context.
4837 return () if @context and !$node->at(@context); # Optionally check the context
4838 my $c = $node->content; # Contents reference
4839 $c ? @$c : () # Contents as a list
4840 }
4841  
4842 sub contentAfter($@) #KU Return a list of all the sibling nodes following the specified B<$node> or an empty list if the specified B<$node> is last or not in the optional B<@context>.
4843 {my ($node, @context) = @_; # Node, optional context.
4844 return () if @context and !$node->at(@context); # Optionally check the context
4845 my $parent = $node->parent; # Parent
4846 return () if !$parent; # The uppermost node has no content beyond it
4847 my @c = $parent->contents; # Contents of parent
4848 while(@c) # Test until no more nodes left to test
4849 {my $c = shift @c; # Position of current node
4850 return @c if $c == $node # Nodes beyond this node if it is the searched for node
4851 }
4852 confess "Node not found in parent"; # Something wrong with parent/child relationship
4853 }
4854  
4855 BEGIN{*ca=*contentAfter}
4856  
4857 sub contentBefore($@) #KU Return a list of all the sibling nodes preceding the specified B<$node> (in the normal sibling order) or an empty list if the specified B<$node> is last or not in the optional B<@context>.
4858 {my ($node, @context) = @_; # Node, optional context.
4859 return () if @context and !$node->at(@context); # Optionally check the context
4860 my $parent = $node->parent; # Parent
4861 return () if !$parent; # The uppermost node has no content beyond it
4862 my @c = $parent->contents; # Contents of parent
4863 while(@c) # Test until no more nodes left to test
4864 {my $c = pop @c; # Position of current node
4865 return @c if $c == $node # Nodes beyond this node if it is the searched for node
4866 }
4867 confess "Node not found in parent"; # Something wrong with parent/child relationship
4868 }
4869  
4870 BEGIN{*cb=*contentBefore}
4871  
4872 sub contentAsTags($@) #KYU Return a string containing the tags of all the child nodes of the specified B<$node> separated by single spaces or the empty string if the node is empty or B<undef> if the node does not match the optional context. Use L<over|/over> to test the sequence of tags with a regular expression.
4873 {my ($node, @context) = @_; # Node, optional context.
4874 return undef if @context and !$node->at(@context); # Optionally check the context
4875 join ' ', map {$_->tag} $node->contents
4876 }
4877  
4878 sub contentAsTags2($@) #KYU Return a string containing the tags of all the child nodes of the specified B<$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 B<undef> if the node does not match the optional context. Use L<over2|/over2> to test the sequence of tags with a regular expression. Use L<over2|/over2> to test the sequence of tags with a regular expression.
4879 {my ($node, @context) = @_; # Node, optional context.
4880 return undef if @context and !$node->at(@context); # Optionally check the context
4881 join '', map {' '.$_->tag.' '} $node->contents
4882 }
4883  
4884 sub contentAfterAsTags($@) #KU Return a string containing the tags of all the sibling nodes following the specified B<$node> separated by single spaces or the empty string if the node is empty or B<undef> if the node does not match the optional context. Use L<matchAfter|/matchAfter> to test the sequence of tags with a regular expression.
4885 {my ($node, @context) = @_; # Node, optional context.
4886 return undef if @context and !$node->at(@context); # Optionally check the context
4887 join ' ', map {$_->tag} $node->contentAfter
4888 }
4889  
4890 sub contentAfterAsTags2($@) #KU Return a string containing the tags of all the sibling nodes following the specified B<$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 B<undef> if the node does not match the optional context. Use L<matchAfter2|/matchAfter2> to test the sequence of tags with a regular expression.
4891 {my ($node, @context) = @_; # Node, optional context.
4892 return undef if @context and !$node->at(@context); # Optionally check the context
4893 join '', map {' '.$_->tag.' '} $node->contentAfter
4894 }
4895  
4896 sub contentBeforeAsTags($@) #KU Return a string containing the tags of all the sibling nodes preceding the specified B<$node> separated by single spaces or the empty string if the node is empty or B<undef> if the node does not match the optional context. Use L<matchBefore|/matchBefore> to test the sequence of tags with a regular expression.
4897 {my ($node, @context) = @_; # Node, optional context.
4898 return undef if @context and !$node->at(@context); # Optionally check the context
4899 join ' ', map {$_->tag} $node->contentBefore
4900 }
4901  
4902 sub contentBeforeAsTags2($@) #KU Return a string containing the tags of all the sibling nodes preceding the specified B<$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 B<undef> if the node does not match the optional context. Use L<matchBefore2|/matchBefore2> to test the sequence of tags with a regular expression.
4903 {my ($node, @context) = @_; # Node, optional context.
4904 return undef if @context and !$node->at(@context); # Optionally check the context
4905 join '', map {' '.$_->tag.' '} $node->contentBefore
4906 }
4907  
4908 sub position($) #U Return the index of the specified B<$node> in the content of the parent of the B<$node>.
4909 {my ($node) = @_; # Node.
4910 my @c = $node->parent->contents; # Each node in parent content
4911 for(keys @c) # Test each node
4912 {return $_ if $c[$_] == $node; # Return index position of node which counts from zero
4913 }
4914 confess "Node not found in parent"; # Something wrong with parent/child relationship
4915 }
4916  
4917 sub index($) #U Return the index of the specified B<$node> in its parent index. Use L<position|/position> to find the position of a node under its parent.
4918 {my ($node) = @_; # Node.
4919 my $p = $node->parent; # Parent
4920 $p or confess "Cannot find index of root node"; # Complain if we try to find the index of the root node
4921 if (my @c = $p->c($node->tag)) # Each node in parent index
4922 {for(keys @c) # Test each node
4923 {return $_ if $c[$_] == $node; # Return index position of node which counts from zero
4924 }
4925 }
4926 confess "Node not found in parent"; # Something wrong with parent/child relationship
4927 }
4928  
4929 sub present($@) #U 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.
4930 {my ($node, @names) = @_; # Node, possible tags immediately under the node.
4931 reindexNode($node); # Create index for this node
4932 my %i = %{$node->indexes}; # Index of child nodes
4933 return map {$_=>scalar @{$i{$_}}} keys %i unless @names; # Hash of all names
4934 grep {$i{$_}} @names # Count of tag types present
4935 }
4936  
4937 sub editText($@) :lvalue #C Return the text of a text B<$node> as an lvalue string reference that can be modified by a regular expression, else as a reference to a dummy string that will be ignored. For a unitary version of this method see: L<changeText>
4938 {my ($node, @context) = @_; # Node to test, optional context
4939 my $dummy = ""; # An empty string reference
4940 return $dummy if @context and !$node->at(@context); # Not in specified context
4941 return $node->text if $node->isText; # Return reference to text if on a text node
4942 $dummy # Nor on a text node
4943 }
4944  
4945 sub isText($@) #UCY Return the specified B<$node> if the specified B<$node> is a text node, optionally in the specified context, else return B<undef>.
4946 {my ($node, @context) = @_; # Node to test, optional context
4947 if (@context) # Optionally check context
4948 {my $p = $node->parent; # Parent
4949 return undef if !$p or !$p->at(@context); # Parent must match context
4950 }
4951 $node->tag eq cdata ? $node : undef
4952 }
4953  
4954 sub isFirstText($@) #UCY Return the specified B<$node> if the specified B<$node> is a text node, the first node under its parent and that the parent is optionally in the specified context, else return B<undef>.
4955 {my ($node, @context) = @_; # Node to test, optional context for parent
4956 return undef unless $node->isText(@context) and $node->isFirst; # Check that this node is a text node, that it is first, and, optionally check context of parent
4957 $node # Return the node as it passes all tests
4958 }
4959  
4960 sub isLastText($@) #UCY Return the specified B<$node> if the specified B<$node> is a text node, the last node under its parent and that the parent is optionally in the specified context, else return B<undef>.
4961 {my ($node, @context) = @_; # Node to test, optional context for parent
4962 return undef unless $node->isText(@context) and $node->isLast; # Check that this node is a text node, that it is last, and, optionally check context of parent
4963 $node # Return the node as it passes all tests
4964 }
4965  
4966 sub matchTree($@) #UC Return a list of nodes that match the specified tree of match expressions, else B<()> 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 [].
4967 {my ($node, @match) = @_; # Node to start matching from, tree of match expressions.
4968 my ($tag, @S) = @match; # Tag we must match, sub tag specifications
4969 my @nodes; # Matching nodes
4970 return () unless atPositionMatch(-t $node, $tag); # Match tag of node
4971 push @nodes, $node; # The current node matches so save it
4972 if (my @s = map{ref($_) ? $_ : [$_]} @S) # Wrap sub tags that are not references with [] so that the caller does not have to because it is a bit tedious wrapping each word in quotes and [] brackets.
4973 {my @c = $node->contents; # Contents of node
4974 return () unless @s <= @c; # Confirm that there is a node to match against for each match expression
4975 for my $c(@c) # Confirm each sub tag matches its sub tag expression
4976 {push @nodes, my @m = $c->matchTree(@{shift @s}); # Save sub match
4977 return () unless @m; # No sub match so return an empty list
4978 }
4979 }
4980 @nodes # The nodes that matched each match expression
4981 }
4982  
4983 sub matchesText($$@) #UC Returns an array of regular expression matches in the text of the specified B<$node> if it is text node and it matches the specified regular expression and optionally has the specified context otherwise returns an empty array.
4984 {my ($node, $re, @context) = @_; # Node to test, regular expression, optional context
4985 return () unless $node->isText(@context); # Check that this is a text node
4986 $node->text =~ m($re); # Return array of matches - do not add 'g' as a modifier to the regular expression as the pos() feature of Perl regular expressions will then cause matches to fail that otherwise would not.
4987 }
4988  
4989 sub isBlankText($@) #UCY Return the specified B<$node> if the specified B<$node> is a text node, optionally in the specified context, and contains nothing other than white space else return B<undef>. See also: L<isAllBlankText|/isAllBlankText>
4990 {my ($node, @context) = @_; # Node to test, optional context
4991 return undef if @context and !$node->at(@context); # Optionally check context
4992 $node->isText && $node->text =~ /\A\s*\Z/s ? $node : undef
4993 }
4994  
4995 sub isAllBlankText($@) #UCY Return the specified B<$node> if the specified B<$node>, optionally in the specified context, does not contain anything or if it does contain something it is all white space else return B<undef>. See also: L<bitsNodeTextBlank|/bitsNodeTextBlank>
4996 {my ($node, @context) = @_; # Node to test, optional context
4997 return undef if @context and !$node->at(@context); # Optionally check context
4998 if ($node->isText) # If this is a text node test the text of the node
4999 {return $node->text =~ m(\A\s*\Z)s ? $node : undef;
5000 }
5001 my @c = $node->contents;
5002 return $node if @c == 0; # No content
5003 return undef if @c > 1; # Content other than text (adjacent text elements are merged so there can only be one)
5004 $node->stringContent =~ m(\A\s*\Z)s ? $node : undef
5005 }
5006  
5007 sub isOnlyChildBlankText($@) #UC Return the specified B<$node> if it is a blank text node and an only child else return B<undef>.
5008 {my ($node, @context) = @_; # Node to test, optional context
5009 return undef unless &isOnlyChildText(@_); # Confirm that this is an only text child
5010 $node->text =~ m(\A\s*\Z)s; # All blank
5011 }
5012  
5013 sub bitsNodeTextBlank($) #U 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.
5014 {my ($node) = @_; # Node to test.
5015 my ($n, $t, $b) = (0,0,0); # Non text, text, blank text count
5016 my @c = $node->contents; # Contents of node
5017 return '' unless @c; # Return empty string if no children
5018  
5019 for(@c) # Contents of node
5020 {if ($_->isText) # Text node
5021 {++$t;
5022 ++$b if $_->isBlankText; # Blank text node
5023 }
5024 else # Non text node
5025 {++$n;
5026 }
5027 }
5028 join '', map {$_ ? 1 : 0} ($n, $t, $b); # Multiple content so there must be some tags present because L<indexNode|/indexNode> concatenates contiguous text
5029 }
5030  
5031 #D1 Number # Number the nodes of a parse tree so that they can be easily retrieved by number - either by a person reading the source L<XML> or programmatically.
5032  
5033 sub findByNumber($$) #UY Find the node with the specified number as made visible by L<prettyStringNumbered|/prettyStringNumbered> in the L<parse|/parse> tree containing the specified B<$node> and return the found node or B<undef> if no such node exists.
5034 {my ($node, $number) = @_; # Node in the parse tree to search, number of the node required.
5035 $node->parser->numbers->[$number]
5036 }
5037  
5038 sub findByNumbers($@) #U Find the nodes with the specified numbers as made visible by L<prettyStringNumbered|/prettyStringNumbered> in the L<parse|/parse> tree containing the specified B<$node> and return the found nodes in a list with B<undef> for nodes that do not exist.
5039 {my ($node, @numbers) = @_; # Node in the parse tree to search, numbers of the nodes required.
5040 map {$node->findByNumber($_)} @numbers # Node corresponding to each number
5041 }
5042  
5043 sub numberNode($) #UP Ensure that the specified B<$node> has a number.
5044 {my ($node) = @_; # Node
5045 my $n = $node->number = ++($node->parser->numbering); # Number node
5046 $node->parser->numbers->[$n] = $node # Index the nodes in a parse tree
5047 }
5048  
5049 sub numberTree($) #U Number the nodes in a L<parse|/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 L<prettyStringNumbered|/prettyStringNumbered>. Nodes can be found using L<findByNumber|/findByNumber>. This method differs from L<forestNumberTrees|/forestNumberTrees> in that avoids overwriting the B<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 L<prettyStringNumbered|/prettyStringNumbered>.
5050 {my ($node) = @_; # Node
5051 my $parser = $node->parser; # Top of tree
5052 my $n = 0; # Node number
5053 $parser->down(sub {$parser->numbers->[$_->number = ++$n] = $_}); # Number the nodes in a parse tree in pre-order so they are numbered in the same sequence that they appear in the source
5054 }
5055  
5056 sub indexIds($) #U Return a map of the ids at and below the specified B<$node>.
5057 {my ($node) = @_; # Node
5058 my %ids; # Id map
5059 $node->by(sub # Map the nodes
5060 {if (my $id = $_->id) # Ignore text nodes and nodes that already have an id
5061 {$ids{$id} and confess "Duplicate id $id"; # Confess to duplicate id under the specified node
5062 $ids{$id} = $_; # Index node by id
5063 }
5064 });
5065 \%ids # Return the index
5066 }
5067  
5068 sub numberTreesJustIds($$) #U Number the ids of the nodes in a L<parse|/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 L<prettyStringNumbered()|/prettyStringNumbered>. This method differs from L<numberTree|/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 specified L<parse|/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 L<findByNumber|/findByNumber>. Returns the specified B<$node>.
5069 {my ($node, $prefix) = @_; # Node, prefix for each id at and under the specified B<$node>
5070 my $parser = $node->parser; # Root node
5071 my $n = 0; # Node number
5072 $node->down(sub # Number the nodes in the parse tree in pre-order so they are numbered in the same sequence that they appear in the source. Add the prefix to each node number.
5073 {if (!$_->isText and !$_->id) # Ignore text nodes and nodes that already have an id
5074 {$_->id = $prefix.++$n; # Set id with prefix
5075 }
5076 }) if $prefix;
5077 $node->down(sub # Number the nodes in the parse tree in pre-order so they are numbered in the same sequence that they appear in the source. Add the prefix to each node number.
5078 {if (!$_->isText and !$_->id) # Ignore text nodes and nodes that already have an id
5079 {$_->id = ++$n; # Set id without prefix
5080 }
5081 }) unless $prefix;
5082 $node # Return the specified node
5083 }
5084  
5085 #D1 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 L<XML> or programmatically.
5086  
5087 sub forestNumberTrees($$) #U Number the ids of the nodes in a L<parse|/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 L<prettyString|/prettyString>. This method differs from L<numberTree|/numberTree> in that only non text nodes are numbered and nodes with existing B<id=> attributes have the value of their B<id=> attribute transferred to a L<label|/Labels>. 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 L<parse|/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 L<findByForestNumber|/findByForestNumber>. Returns the specified B<$node>.
5088 {my ($node, $prefix) = @_; # Node in parse tree to be numbered, tree number
5089 my $parser = $node->parser; # Root node
5090 defined($prefix) or confess "prefix required"; # Typically the prefix separates parallel processes and so it is a good idea to have one
5091 $prefix =~ m(\A\d+\Z)s or confess "prefix must be an integer \\d+"; # Insist on a numeric prefix
5092 $parser->down(sub # Number the nodes in the parse tree in pre-order so they are numbered in the same sequence that they appear in the source
5093 {if (!$_->isText) # Number non text nodes
5094 {$_->addLabels($_->id) if $_->id; # Make any existing id a label
5095 my $n = $prefix.q(_).(scalar(keys %{$parser->forestNumbers}) + 1); # Id number
5096 $_->id = $n; # Set id
5097 $parser->forestNumbers->{$n} = $_; # Index node
5098 }
5099 });
5100 $node # Return the specified node
5101 }
5102  
5103 sub findByForestNumber($$$) #U Find the node with the specified L<forest number|/forestNumberTrees> as made visible on the id attribute by L<prettyStringNumbered|/prettyStringNumbered> in the L<parse|/parse> tree containing the specified B<$node> and return the found node or B<undef> if no such node exists.
5104 {my ($node, $tree, $id) = @_; # Node in the parse tree to search, forest number, id number of the node required.
5105 $node->parser->forestNumbers->{$tree.q(_).$id}
5106 }
5107  
5108 #D1 Order # Check the order and relative position of nodes in a parse tree.
5109  
5110 sub above($$@) #CY 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 B<undef>
5111 {my ($first, $second, @context) = @_; # First node, second node, optional context
5112 return undef if @context and !$first->at(@context); # Not in specified context
5113 return undef if $first == $second; # A node cannot be above itself
5114 my @f = $first ->ancestry;
5115 my @s = $second->ancestry;
5116 pop @f, pop @s while @f and @s and $f[-1] == $s[-1]; # Find first different ancestor
5117 !@f ? $first : undef # Node is above target if its ancestors are all ancestors of target
5118 }
5119  
5120 sub 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 B<()>.
5121 {my ($first, $second) = @_; # First node, second node
5122 return ($first) if $first == $second; # A node cannot be above itself
5123 my @f = $first ->ancestry;
5124 my @s = $second->ancestry;
5125 pop @f, pop @s while @f and @s and $f[-1] == $s[-1]; # Find first different ancestor
5126 !@f ? ($first, reverse @s) : () # Node is above target if its ancestors are all ancestors of target
5127 }
5128  
5129 sub below($$@) #CY 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 B<undef>
5130 {my ($first, $second, @context) = @_; # First node, second node, optional context
5131 $second->above($first, @context); # The second node is above the first node if the first node is below the second node
5132 }
5133  
5134 sub 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 B<()>.
5135 {my ($first, $second) = @_; # First node, second node
5136 reverse $second->abovePath($first)
5137 }
5138  
5139 sub after($$@) #CY Return the first node if it occurs after the second node in the L<parse|/parse> tree optionally checking that the first node is in the specified context or else B<undef> if the node is L<above|/above>, L<below|/below> or L<before|/before> the target.
5140 {my ($first, $second, @context) = @_; # First node, second node, optional context
5141 return undef if @context and !$first->at(@context); # First node not in specified context
5142 my @n = $first ->ancestry;
5143 my @t = $second->ancestry;
5144 pop @n, pop @t while @n and @t and $n[-1] == $t[-1]; # Find first different ancestor
5145 return undef unless @n and @t; # Undef if we cannot decide
5146 $n[-1]->position > $t[-1]->position # Node relative to target at first common ancestor
5147 }
5148  
5149 sub before($$@) #CY Return the first node if it occurs before the second node in the L<parse|/parse> tree optionally checking that the first node is in the specified context or else B<undef> if the node is L<above|/above>, L<below|/below> or L<before|/before> the target.
5150 {my ($first, $second, @context) = @_; # First node, second node, optional context
5151 $second->after($first, @context); # The first node is before the second node if the second node is after the first node
5152 }
5153  
5154 sub disordered($@) # Return the first node that is out of the specified order when performing a pre-ordered traversal of the L<parse|/parse> tree.
5155 {my ($node, @nodes) = @_; # Node, following nodes.
5156 my $c = $node; # Node we are currently checking for
5157 $node->parser->down(sub {$c = shift @nodes while $c and $_ == $c}); # Preorder traversal from root looking for each specified node
5158 $c # Disordered if we could not find this node
5159 }
5160  
5161 sub commonAncestor($@) #Y Find the most recent common ancestor of the specified nodes or B<undef> if there is no common ancestor.
5162 {my ($node, @nodes) = @_; # Node, @nodes
5163 return $node unless @nodes; # A single node is it its own common ancestor
5164 my @n = $node->ancestry; # The common ancestor so far
5165 for(@nodes) # Each node
5166 {my @t = $_->ancestry; # Ancestry of latest node
5167 my @c; # Common ancestors
5168 while(@n and @t and $n[-1] == $t[-1]) # Find common ancestors
5169 {push @c, pop @n; pop @t; # Save common ancestor
5170 }
5171 return undef unless @c; # No common ancestors
5172 @n = reverse @c; # Update common ancestry so far
5173 }
5174 $n[0] # Most recent common ancestor
5175 }
5176  
5177 sub commonAdjacentAncestors($$) # Given two nodes, find a pair of adjacent ancestral siblings if such a pair exists else return B<()>.
5178 {my ($first, $second) = @_; # First node, second node
5179 my @f = $first->ancestry; # Ancestors of the first node
5180 my @s = $second->ancestry; # Ancestors of the second node
5181 while(@f and @s and $f[-1] == $s[-1]) # Remove common ancestors
5182 {pop @f; pop @s;
5183 }
5184 return () unless @f and @s; # No common ancestors
5185 my ($f, $s) = ($f[-1], $s[-1]); # Possible common pair of ancestral siblings
5186 return ($f, $s) if $f->adjacent($s); # Return first diverging siblings if they exist
5187 () # No such pair exists
5188 }
5189  
5190 sub ordered($@) #Y Return the first node if the specified nodes are all in order when performing a pre-ordered traversal of the L<parse|/parse> tree else return B<undef>.
5191 {my ($node, @nodes) = @_; # Node, following nodes.
5192 &disordered(@_) ? undef : $node
5193 }
5194  
5195 #D1 Patching # Analyze two similar L<parse|/parse> trees and create a patch that transforms the first L<parse|/parse> tree into the second as long as each tree has the same tag and id structure with each id being unique.
5196  
5197 sub createPatch($$) # Create a patch that moves the source L<parse|/parse> tree to the target L<parse|/parse> tree node as long as they have the same tag and id structure with each id being unique.
5198 {my ($a, $A) = @_; # Source parse tree, target parse tree
5199 my @patches;
5200 my $I = $A->indexIds;
5201 $a->by(sub
5202 {my ($o) = @_;
5203 return unless my $id = $o->id;
5204 if (my $O = $I->{$id})
5205 {for my $a($o->getAttrs)
5206 {my ($v, $V)= ($o->attr($a), $O->attr($a)); # Values
5207 if (defined($V) and $v ne $V)
5208 {push @patches, [q(changeValue), $id, $a, $v, $V] # Set attribute
5209 }
5210 elsif (!defined($V))
5211 {push @patches, [q(deleteAttr), $id, $a, $v] # Set attribute
5212 }
5213 }
5214 for my $A($O->getAttrs)
5215 {next if $o->attr($A);
5216 push @patches, [q(createAttr), $id, $A, $O->attr($A)]; # Set attribute
5217 }
5218  
5219 if (my $f = $o->first) # First following text
5220 {if ($f->isText)
5221 {if (my $F = $O->first)
5222 {if ($F->isText)
5223 {if ($f->text ne $F->text)
5224 {push @patches, [q(firstText), $id, $f->text, $F->text];
5225 }
5226 }
5227 else
5228 {confess "Text expected first after node $id:\n".$f->text;
5229 }
5230 }
5231 else
5232 {confess "Node expected first after node $id:\n".$f->text;
5233 }
5234 }
5235 }
5236  
5237 if (my $n = $o->next) # Following text
5238 {if ($n->isText)
5239 {if (my $N = $O->next)
5240 {if ($N->isText)
5241 {if ($n->text ne $N->text)
5242 {push @patches, [q(nextText), $id, $n->text, $N->text];
5243 }
5244 }
5245 else
5246 {confess "Text expected after node $id:\n".$n->text;
5247 }
5248 }
5249 else
5250 {confess "Node expected after node $id:\n".$n->text;
5251 }
5252 }
5253 }
5254  
5255 if (my $p = $o->prev) # Preceding text
5256 {if ($p->isText)
5257 {if (my $P = $O->prev)
5258 {if ($P->isText)
5259 {if ($p->text ne $P->text)
5260 {push @patches, [q(prevText), $id, $p->text, $P->text];
5261 }
5262 }
5263 else
5264 {confess "Text expected before node $id:\n".$p->text;
5265 }
5266 }
5267 else
5268 {confess "Node expected before node $id:\n".$p->text;
5269 }
5270 }
5271 }
5272  
5273 if (my $l = $o->last) # Last preceding text
5274 {if ($l->isText)
5275 {if (my $L = $O->last)
5276 {if ($L->isText)
5277 {if ($l->text ne $L->text)
5278 {push @patches, [q(lastText), $id, $l->text, $L->text];
5279 }
5280 }
5281 else
5282 {confess "Text expected last before node $id:\n".$l->text;
5283 }
5284 }
5285 else
5286 {confess "Node expected last before node $id:\n".$l->text;
5287 }
5288 }
5289 }
5290 }
5291 else
5292 {confess "No matching id for $id";
5293 }
5294 });
5295 bless [@patches], q(Data::Edit::Xml::Patch); # Return patch
5296 }
5297  
5298 sub Data::Edit::Xml::Patch::install($$) # Replay a patch created by L<createPatch|/createPatch> against a L<parse|/parse> tree that has the same tag and id structure with each id being unique.
5299 {my ($patches, $a) = @_; # Patch, parse tree
5300 my $i = $a->indexIds;
5301 for my $patch(@$patches)
5302 {my ($c, $id) = @$patch;
5303 my $o = $i->{$id} or confess "No node with id $id";
5304 if ($c eq q(changeValue))
5305 {my (undef, undef, $a, $v, $V) = @$patch;
5306 $o->attr($a) eq $v or confess "Expected $a=$v but got $a=".$o->attr($a);
5307 $o->setAttr($a, $V);
5308 }
5309 elsif ($c eq q(deleteAttr))
5310 {my (undef, undef, $a, $v) = @$patch;
5311 $o->attr($a) eq $v or confess "Expected $a=$v but got $a=".$o->attr($a);
5312 $o->deleteAttr($a);
5313 }
5314 elsif ($c eq q(createAttr))
5315 {my (undef, undef, $a, $v) = @$patch;
5316 $o->setAttr($a, $v);
5317 }
5318 else
5319 {my (undef, undef, $t, $T) = @$patch;
5320 my $update = sub
5321 {my ($o, $pos) = @_;
5322 $o or confess "Node expected $pos node $id";
5323 my $s = $o->text;
5324 $s or confess "Text node expected $pos node $id";
5325 $s eq $t or $s eq $T or confess "Text expected $pos node $id should be:\n$s";
5326 $o->text = $T unless $s eq $T;
5327 };
5328 if ($c eq q(firstText)) {$update->($o->first, q(first after))}
5329 elsif ($c eq q(nextText)) {$update->($o->next, q(after))}
5330 elsif ($c eq q(prevText)) {$update->($o->prev, q(before))}
5331 elsif ($c eq q(lastText)) {$update->($o->last, q(last before))}
5332 else {confess "Unknown command $c"}
5333 }
5334 }
5335 }
5336  
5337 #D1 Propogating # Propagate parent node attributes through a parse tree.
5338  
5339 sub propagate($$@) #UC Propagate L<new attributes|/copyNewAttrs> from nodes that match the specified tag to all their child nodes, then L<unwrap|/unwrap> all the nodes that match the specified tag. Return the specified parse tree.
5340 {my ($tree, $tag, @context) = @_; # Parse tree, tag of nodes whose attributes are to be propagated, optional context for parse tree
5341 return undef if @context and !$tree->at(@context); # Not in specified context
5342 $tree->by(sub # Copy new attributes from each matching parent for each node in the parse tree
5343 {my ($node, @parents) = @_; # Node, parents
5344 for my $parent(@parents) # For each parent of the node being visited
5345 {$parent->copyNewAttrs($node) if -t $parent eq $tag; # Copy the new attributes of a parent with the specified tag
5346 }
5347 });
5348 $tree->by(sub # Unwrap nodes with the specified tag unless they are the starting node
5349 {my ($node) = @_; # Node
5350 $node->unwrap if $node != $tree and -t $node eq $tag; # Unwrap the node if it matches the specified tag
5351 });
5352 $tree # Return the parse tree
5353 }
5354  
5355 #D1 Table of Contents # Analyze and generate tables of contents.
5356  
5357 sub tocNumbers($@) #U Table of Contents number the nodes in a L<parse|/parse> tree.
5358 {my ($node, @match) = @_; # Node, optional list of tags to descend into else all tags will be descended into
5359 my $toc = {};
5360 my $match = @match ? {map{$_=>1} @match} : undef; # Tags to match or none
5361 my @context;
5362  
5363 my $tree; $tree = sub # Number the nodes below the current node
5364 {my ($node) = @_;
5365 my $n = 0;
5366 for($node->contents) # Each node below the current node
5367 {next if $match and !$match->{$_->tag}; # Skip non matching nodes
5368 push @context, ++$n; # New scope
5369 $toc->{"@context"} = $_; # Toc number for tag
5370 &$tree($_); # Number sub tree
5371 pop @context; # End scope
5372 }
5373 };
5374  
5375 &$tree($node); # Descend through the tree numbering matching nodes
5376 $toc # Return {toc number} = <tag>
5377 }
5378  
5379 #D1 Labels # Label nodes so that they can be cross referenced and linked by L<Data::Edit::Xml::Lint>
5380  
5381 sub addLabels($@) #U Add the named labels to the specified B<$node> and return the number of labels added. Labels that are not L<defined|https://perldoc.perl.org/functions/defined.html> will be ignored.
5382 {my ($node, @labels) = @_; # Node in parse tree, names of labels to add.
5383 my $l = $node->labels; # Labels on node
5384 my $n = keys %$l; # Count the number of labels at the start
5385 $l->{$_}++ for grep {trim($_)} @labels; # Labels must be defined to be added. Remove leading and trailing white space to prevent Data::Edit::Xml::Lint complaining about it: justified by the assumption that it is a data entry error.
5386 keys(%$l) - $n # Number of labels added
5387 }
5388  
5389 sub countLabels($) #U Return the count of the number of labels at a node.
5390 {my ($node) = @_; # Node in parse tree.
5391 scalar keys %{$node->labels} # Count of labels
5392 }
5393  
5394 sub labelsInTree($) #U Return a hash of all the labels in a tree
5395 {my ($tree) = @_; # Parse tree.
5396 my %labels; # Labels found
5397 $tree->by(sub # Labels for each node in the parse tree
5398 {for($_->getLabels) # Each label
5399 {$labels{$_}++
5400 }
5401 });
5402 \%labels # Hash of labels in the tree
5403 }
5404  
5405 sub getLabels($) #U Return the names of all the labels set on a node.
5406 {my ($node) = @_; # Node in parse tree.
5407 sort keys %{$node->labels}
5408 }
5409  
5410 sub deleteLabels($@) #U Delete the specified labels in the specified B<$node> or all labels if no labels have are specified and return that node.
5411 {my ($node, @labels) = @_; # Node in parse tree, names of the labels to be deleted
5412 my $n = keys %{$node->{labels}}; # Number of labels at start
5413 $node->{labels} = {} unless @labels; # Delete all the labels if no labels supplied
5414 delete @{$node->{labels}}{@labels}; # Delete specified labels
5415 $n - keys %{$node->{labels}} # Number of labels deleted
5416 }
5417  
5418 sub copyLabels($$) # Copy all the labels from the source node to the target node and return the source node.
5419 {my ($source, $target) = @_; # Source node, target node.
5420 $target->addLabels($source->getLabels); # Copy all the labels from the source to the target
5421 }
5422  
5423 sub moveLabels($$) # Move all the labels from the source node to the target node and return the source node.
5424 {my ($source, $target) = @_; # Source node, target node.
5425 $target->addLabels($source->getLabels); # Copy all the labels from the source to the target
5426 $source->deleteLabels; # Delete all the labels from the source
5427 }
5428  
5429 sub 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 L<path|/path>. Return the number of labels and ids copied.
5430 {my ($source, $target) = @_; # Source node, target node.
5431 my $n = 0; # Count modifications
5432 $target->by(sub # Scan the target
5433 {my ($o) = @_;
5434 my @p = $o->path; # Matching node in source
5435 if (my $q = $source->go(@p))
5436 {$n += $q->copyLabels($o) + $o->addLabels($q->id); # Copy labels and id from source to target
5437 }
5438 });
5439 $n # Number of labels added
5440 }
5441  
5442 sub giveEveryIdAGuid($$) #U Give a guid to every node in the specified B<$tree> that has an id attribute, saving any existing id attribute as a label, and return the count of the number of such replacements made.
5443 {my ($tree, $genGuid) = @_; # Tree, a sub that accepts a number and a node and returns a new Guid each time it is called
5444 my $n = 0; # count the number of ids replaced with guids
5445 $tree->by(sub # Scan the tree
5446 {my ($o) = @_;
5447 if (my $i = $o->id) # Ignore this node unless it has an id
5448 {if ($i !~ m(\AGUID)is) # Ignore this node if it already has a guid
5449 {$o->addLabels($i); # Make the current id into a label.
5450 $o->id = $genGuid->(++$n, $o); # Replace the existing id with the next guid
5451 }
5452 }
5453 });
5454 $n # Number of ids replaced with guids
5455 }
5456  
5457 sub createGuidId($@) #CU Create an id for the specified B<$node> in the optional B<@context> from the md5Sum of its content moving any existing id to the labels associated with the B<$node> and return the existing B<$node>.
5458 {my ($node, @context) = @_; # Node, optional context
5459 return undef if @context and !$node->at(@context); # Not in specified context
5460 if (my $i = $node->id) # Save any current id if any
5461 {$node->addLabels($i); # Save id as a label
5462 }
5463 $node->id = guidFromMd5 $node->stringAsMd5Sum; # Guid from MD5 of content
5464 $node # Return existing node
5465 }
5466 #a
5467 #b <b><c/></b>
5468 #c createGuidId b
5469 #d Use the content of the current node to create a globally unique id for this node.
5470  
5471 #D1 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.
5472  
5473 use overload
5474 '=' => sub{$_[0]},
5475 '**' => \&opNew,
5476 '-X' => \&opString,
5477 '@{}' => \&opContents,
5478 '<=' => \&opAt,
5479 '>>' => \&opPutFirst,
5480 '>>=' => \&opPutFirstAssign,
5481 '<<' => \&opPutLast,
5482 '<<=' => \&opPutLastAssign,
5483 '>' => \&opPutNext,
5484 '+=' => \&opPutNextAssign,
5485 '+' => \&opPutNext,
5486 '<' => \&opPutPrev,
5487 '-=' => \&opPutPrevAssign,
5488 '-' => \&opPutPrev,
5489 'x=' => \&opBy,
5490 'x' => \&opBy,
5491 '>=' => \&opGo,
5492 '*' => \&opWrapContentWith, # doc
5493 '*=' => \&opWrapContentWith,
5494 '/' => \&opWrapWith,
5495 '/=' => \&opWrapWith,
5496 '%' => \&opAttr,
5497 '--' => \&opCut, # Better using -X
5498 '++' => \&opUnwrap, # doc # Better using -u
5499 "fallback" => 1;
5500  
5501 sub opString($$) # -A: L<printNode|/printNode>\m-B: L<bitsNodeTextBlank|/bitsNodeTextBlank>\m-b: L<isAllBlankText|/isAllBlankText>\m-C: L<stringContent|/stringContent>\m-c: L<context|/context>\m-d: L<depth|/depth>\m-e: L<prettyStringEnd|/prettyStringEnd>\m-f: L<first node|/first>\m-g: L<createGuidId|/createGuidId>\m-k: L<createGuidId|/createGuidId>\m-l: L<last node|/last>\m-M: L<stringAsMd5Sum|/stringAsMd5Sum>\m-O: L<contentAsTags2|/contentAsTags2>\m-o: L<contentAsTags|/contentAsTags>\m-p: L<prettyString|/prettyString>\m-R: L<requiredCleanup|/requiredCleanup>\m-r: L<stringTagsAndText|/stringTagsAndText>\m-S: L<printStack|/printStack>\m-s: L<string|/string>\m-T: L<isText|/isText>\m-t: L<tag|/tag>\m-u: L<unwrap|/unwrap>\m-W: L<id|/id>\m-w: L<stringQuoted|/stringQuoted>\m-X: L<prettyStringDitaHeaders|/prettyStringDitaHeaders>\m-x: L<cut|/cut>\m-z: L<prettyStringNumbered|/prettyStringNumbered>.
5502 {my ($node, $op) = @_; # Node, monadic operator.
5503 $op or confess;
5504 return $node->printNode if $op eq 'A';
5505 return $node->bitsNodeTextBlank if $op eq 'B'; # Not much use
5506 return $node->isAllBlankText if $op eq 'b';
5507 return $node->stringContent if $op eq 'C';
5508 return $node->context if $op eq 'c';
5509 return $node->depth if $op eq 'd'; # Not much use
5510 return $node->prettyStringEnd if $op eq 'e'; # Not much use
5511 return $node->first if $op eq 'f'; # Not much use
5512 return $node->createGuidId if $op eq 'g';
5513 return $node->createGuidId if $op eq 'k'; # Not in use
5514 return $node->last if $op eq 'l'; # Not much use
5515 return $node->stringAsMd5Sum if $op eq 'M';
5516 return $node->contentAsTags2 if $op eq 'O';
5517 return $node->contentAsTags if $op eq 'o';
5518 return $node->prettyString if $op eq 'p';
5519 return $node->requiredCleanUp if $op eq 'R'; # Not much use
5520 return $node->stringTagsAndText if $op eq 'r'; # Not much use
5521 return $node->printStack if $op eq 'S';
5522 return $node->string if $op eq 's';
5523 return $node->isText if $op eq 'T';
5524 return $node->tag if $op eq 't';
5525 return $node->unwrap if $op eq 'u';
5526 return $node->id if $op eq 'W'; # Not much use
5527 return $node->stringQuoted if $op eq 'w'; # Not much use
5528 return $node->prettyStringDitaHeaders if $op eq 'X';
5529 return $node->cut if $op eq 'x';
5530 return $node->prettyStringNumbered if $op eq 'z'; # Not much use
5531 confess "Unknown operator: $op";
5532 }
5533  
5534 sub opContents($) # @{} : nodes immediately below a node.
5535 {my ($node) = @_; # Node.
5536 $node->content
5537 }
5538  
5539 sub opAt($$) # <= : Check that a node is in the context specified by the referenced array of words.
5540 {my ($node, $context) = @_; # Node, reference to array of words specifying the parents of the desired node.
5541 ref($context) =~ m/array/is or
5542 confess "Array of words required to specify the context";
5543 $node->at(@$context);
5544 }
5545  
5546 sub 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
5547 {my ($node, $text) = @_; # Node, name node of node to create or text of new text element
5548 return $text if ref($text) eq __PACKAGE__; # The right hand side is already a node
5549 return $node->newTag($text) unless $text =~ m/\W/s; # Create a new node as tag
5550 $node->newText($text) # Create a new node as text if nothing lse worked
5551 }
5552  
5553 sub opPutFirst($$) # >> : put a node or string first under a node and return the new node.
5554 {my ($node, $text) = @_; # Node, node or text to place first under the node.
5555 $node->putFirst(my $new = opNew($node, $text));
5556 $new
5557 }
5558  
5559 sub opPutFirstAssign($$) # >>= : put a node or string first under a node.
5560 {my ($node, $text) = @_; # Node, node or text to place first under the node.
5561 opPutFirst($node, $text);
5562 $node
5563 }
5564  
5565 sub opPutLast($$) # << : put a node or string last under a node and return the new node.
5566 {my ($node, $text) = @_; # Node, node or text to place last under the node.
5567 $node->putLast(my $new = opNew($node, $text));
5568 $new
5569 }
5570  
5571 sub opPutLastAssign($$) # <<= : put a node or string last under a node.
5572 {my ($node, $text) = @_; # Node, node or text to place last under the node.
5573 opPutLast($node, $text);
5574 $node
5575 }
5576  
5577 sub opPutNext($$) # > + : put a node or string after the specified B<$node> and return the new node.
5578 {my ($node, $text) = @_; # Node, node or text to place after the first node.
5579 $node->putNext(my $new = opNew($node, $text));
5580 $new
5581 }
5582  
5583 sub opPutNextAssign($$) # += : put a node or string after the specified B<$node>.
5584 {my ($node, $text) = @_; # Node, node or text to place after the first node.
5585 opPutNext($node, $text);
5586 $node
5587 }
5588  
5589 sub opPutPrev($$) # < - : put a node or string before the specified B<$node> and return the new node.
5590 {my ($node, $text) = @_; # Node, node or text to place before the first node.
5591 $node->putPrev(my $new = opNew($node, $text));
5592 $new
5593 }
5594  
5595 sub opPutPrevAssign($$) # -= : put a node or string before the specified B<$node>,
5596 {my ($node, $text) = @_; # Node, node or text to place before the first node.
5597 opPutPrev($node, $text);
5598 $node
5599 }
5600  
5601 sub opBy($$) # x= : Traverse a L<parse|/parse> tree in post-order.
5602 {my ($node, $code) = @_; # Parse tree, code to execute against each node.
5603 ref($code) =~ m/code/is or
5604 confess "sub reference required on right hand side";
5605 $node->by($code);
5606 }
5607  
5608 sub 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.
5609 {my ($node, $go) = @_; # Node, reference to an array of search parameters.
5610 return $node->go(@$go) if ref($go);
5611 $node->go($go)
5612 }
5613  
5614 sub opAttr($$) # % : Get the value of an attribute of the specified B<$node>.
5615 {my ($node, $attr) = @_; # Node, reference to an array of words and numbers specifying the node to search for.
5616 return map {$node->attr($_)} @$attr if ref($attr);
5617 $node->attr($attr)
5618 }
5619  
5620 sub opWrapWith($$) # / : Wrap node with a tag, returning the wrapping node.
5621 {my ($node, $tag) = @_; # Node, tag.
5622 return $node->wrapUp(@$tag) if ref($tag);
5623 $node->wrapWith($tag)
5624 }
5625  
5626 sub opWrapContentWith($$) # * : Wrap content with a tag, returning the wrapping node.
5627 {my ($node, $tag) = @_; # Node, tag.
5628 return $node->wrapDown(@$tag) if ref($tag);
5629 $node->wrapContentWith($tag)
5630 }
5631  
5632 sub opCut($) # -- : Cut out a node.
5633 {my ($node) = @_; # Node.
5634 $node->cut
5635 }
5636  
5637 sub opUnwrap($) # ++ : Unwrap a node.
5638 {my ($node) = @_; # Node.
5639 $node->unwrap
5640 }
5641  
5642 #D1 Reuse # Identify common components that can be reused
5643  
5644 sub subMd5Tree($) # Return the L<md5> of the L<stringContent> of the parse tree.
5645 {my ($node) = @_; # Node
5646 if (my $s = $node->stringContent) # Md5 of something with content
5647 {return (stringMd5Sum($s), $s);
5648 }
5649 () # A text element must be wrapped in an non text element - to get the md5 sum of a text element call via the wrapping node - otherwise we get duplicates.
5650 }
5651  
5652 sub subMd5($%) # Return a hash {L<md5> of parse tree}{string representation of sub tree}++ to locate common parse trees under B<$node> that could be included via a conref. L<Md5>s are only calculated for nodes whose tags match the keys of the B<$tags> hash that have truthful values. The attributes of the root node of each sub tree are ignored in the computation as they can be supplied by the conreffing element.
5653 {my ($node, %tags) = @_; # Node, hash of acceptable tags.
5654  
5655 my %hash; # Hash of md5 sums to content
5656  
5657 my $M; $M = sub($) # Md5 sum of current parse tree
5658 {my ($p) = @_; # Node
5659 my $tag = -t $p;
5660 if ($tags{$tag}) # Tag matches
5661 {if (my ($m, $s) = $p->subMd5Tree) # Md5 of something with content
5662 {$hash{$tag}{$m}{$s}++;
5663 }
5664 }
5665  
5666 if (my @c = $p->contents) # Each sub tree
5667 {$M->($_) for @c;
5668 }
5669 };
5670  
5671 $M->($node); # Start at current node
5672 return \%hash; # Resulting hash
5673 }
5674  
5675 #D1 Statistics # Statistics describing the L<parse|/parse> tree.
5676  
5677 sub count($@) #U Return the count of the number of instances of the specified tags under the specified B<$node>, either by tag in array context or in total in scalar context.
5678 {my ($node, @names) = @_; # Node, possible tags immediately under the node.
5679 if (wantarray) # In array context return the count for each tag specified
5680 {my @c; # Count for the corresponding tag
5681 reindexNode($node); # Create index for this node
5682 my %i = %{$node->indexes}; # Index of child nodes
5683 for(@names)
5684 {if (my $i = $i{$_}) {push @c, scalar(@$i)} else {push @c, 0}; # Save corresponding count
5685 }
5686 return @c; # Return count for each tag specified
5687 }
5688 else # In scalar context count the total number of instances of the named tags
5689 {if (@names)
5690 {my $c = 0; # Tag count
5691 reindexNode($node); # Create index for this node
5692 my %i = %{$node->indexes}; # Index of child nodes
5693 for(@names)
5694 {if (my $i = $i{$_}) {$c += scalar(@$i)}
5695 }
5696 return $c;
5697 }
5698 else # In scalar context, with no tags specified, return the number of nodes under the specified B<$node>
5699 {my @c = $node->contents;
5700 return scalar(@c); # Count of all tags including CDATA
5701 }
5702 }
5703 confess "This should not happen"
5704 }
5705  
5706 sub countTags($) #U Count the number of tags in a L<parse|/parse> tree.
5707 {my ($node) = @_; # Parse tree.
5708 my $n = 0;
5709 $node->by(sub{++$n}); # Count tags including CDATA
5710 $n # Number of tags encountered
5711 }
5712  
5713 sub countTagNames2($$) #P Return a reference to a hash showing the number of instances of each tag on and below the specified B<$node>.
5714 {my ($node, $count) = @_; # Node, count of tags so far.
5715 $$count{$node->tag}++; # Add current tag
5716 $_->countTagNames2($count) for $node->contents; # Each contained node
5717 }
5718  
5719 sub countTagNames($@) #U Return a reference to a hash showing the number of instances of each tag on and below the specified B<$node> excluding any tags named in B<@exclude>.
5720 {my ($node, @exclude) = @_; # Node, tags to exclude from the count
5721 my $count = {}; # Counts
5722 $node->countTagNames2($count); # Count includes this node
5723 delete $$count{$_} for @exclude; # Delete excluded nodes
5724 $count # Count
5725 }
5726  
5727 sub countNonEmptyTags2($$) #P Count the instances of non empty tags on and below the specified B<$node>.
5728 {my ($node, $count) = @_; # Node, count of tags so far.
5729 $$count{$node->tag}++ unless $node->isAllBlankText; # Add current tag
5730 $_->countNonEmptyTags2($count) for $node->contents; # Each contained node
5731 }
5732  
5733 sub countNonEmptyTags($@) #U Return a reference to a hash showing the number of instances of each non empty tag on and below the specified B<$node> excluding any tags named in B<@exclude>.
5734 {my ($node, @exclude) = @_; # Node, tags to exclude from the count
5735 my $count = {}; # Counts
5736 $node->countNonEmptyTags2($count); # Count includes this node
5737 delete $$count{$_} for @exclude; # Delete excluded nodes
5738 $count # Count
5739 }
5740  
5741 sub countTexts2($$) #P Count the instances of non empty texts on and below the specified B<$node>.
5742 {my ($node, $count) = @_; # Node, texts so far
5743 if ($node->isText) # Check we are on a text node
5744 {$$count{$node->text}++; # Add current text
5745 }
5746 else # Not on a text node
5747 {$_->countTexts2($count) for $node->contents; # Each contained node
5748 }
5749 }
5750  
5751 sub countTexts($) #U Return a reference to a hash showing the incidence of texts on and below the specified B<$node>.
5752 {my ($node) = @_; # Node
5753 my $count = {}; # Counts
5754 $node->countTexts2($count); # Count includes this node
5755 $count # Count
5756 }
5757  
5758 sub countWords($) #UP Count instances of words in texts
5759 {my ($node) = @_; # Node
5760 my $c = countTexts($node); # Gather text
5761 my %w; # Words
5762 for my $t(keys %$c) # Each text
5763 {$w{$_}++ for split /[.,;]?\s+/, $t; # Count words in each text
5764 }
5765 \%w # Return words
5766 }
5767  
5768 sub countAttrNames($;$) #U Return a reference to a hash showing the number of instances of each attribute on and below the specified B<$node>.
5769 {my ($node, $count) = @_; # Node, attribute count so far
5770 $count //= {}; # Counts
5771 $$count{$_}++ for $node->getAttrs; # Attributes from current tag
5772 $_->countAttrNames($count) for $node->contents; # Each contained node
5773 $count # Count
5774 }
5775  
5776 sub countAttrNamesOnTagExcluding($@) #U Count the number of attributes owned by the specified B<$node> that are not in the specified list.
5777 {my ($node, @attr) = @_; # Node, attributes to ignore
5778 my %attr = map{$_=>1} @attr; # Set of attributes to ignore
5779 my $count; # Count
5780 $count++ for grep {!$attr{$_}} $node->getAttrs; # Attributes from current tag
5781 $count # Count
5782 }
5783  
5784 sub countAttrValues($;$) #U Return a reference to a hash showing the number of instances of each attribute value on and below the specified B<$node>.
5785 {my ($node, $count) = @_; # Node, count of attributes so far.
5786 $count //= {}; # Counts
5787 $count->{$node->attr($_)}++ for $node->getAttrs; # Attribute values from current tag
5788 $_->countAttrValues($count) for $node->contents; # Each contained node
5789 $count # Count
5790 }
5791  
5792 sub countAttrNamesAndValues($;$) #U Return a reference to a hash showing the number of instances of each attribute name and value on and below the specified B<$node>.
5793 {my ($node, $count) = @_; # Node, count of attributes so far.
5794 $count //= {}; # Counts
5795 $count->{$_}{$node->attr($_)}++ for $node->getAttrs; # Attribute names and values from current tag
5796 $_->countAttrNamesAndValues($count) for $node->contents; # Each contained node
5797 $count # Count
5798 }
5799  
5800 sub countOutputClasses($$) #U Count instances of outputclass attributes
5801 {my ($node, $count) = @_; # Node, count so far.
5802 $count //= {}; # Counts
5803 my $a = $node->attr(qw(outputclass)); # Outputclass attribute
5804 $$count{$a}++ if $a ; # Add current output class
5805 &countOutputClasses($_, $count) for $node->contents; # Each contained node
5806 $count # Count
5807 }
5808  
5809 sub countReport($@) #U Count tags, attributes, words below the specified node
5810 {my ($node, @context) = @_; # Node to count from, optional context
5811 return undef if @context and !$node->at(@context); # Optionally check context
5812 my $c = $node->countTagNames; # Count tag types
5813 formatTable([sort {$$a[1] cmp $$b[1]} map {[$$c{$_}, $_]} sort keys %$c],
5814 [qw(Tag Count)]);
5815 }
5816  
5817 BEGIN{*cr=*countReport}
5818  
5819 sub changeReasonCommentSelectionSpecification :lvalue #S Provide a specification to select L<change reason comments|/crc> to be inserted as text into a L<parse|/parse> tree. A specification can be either:\m=over\m=item the name of a code to be accepted,\m=item a regular expression which matches the codes to be accepted,\m=item a hash whose keys are defined for the codes to be accepted or\m=item B<undef> (the default) to specify that no such comments should be accepted.\m=back
5820 {CORE::state $r;
5821 $r
5822 }
5823  
5824 sub crc($$;$) # Insert a comment consisting of a code and an optional reason as text into the L<parse|/parse> tree to indicate the location of changes to the L<parse|/parse> tree. As such comments tend to become very numerous, only comments whose codes matches the specification provided in L<changeReasonCommentSelectionSpecification|/changeReasonCommentSelectionSpecification> are accepted for insertion. Subsequently these comments can be easily located using:\mB<grep -nr "<!-->I<code>B<">\mon the file containing a printed version of the L<parse|/parse> tree. Please note that these comments will be removed if the output file is reparsed.\mReturns the specified B<$node>.
5825 {my ($node, $code, $reason) = @_; # Node being changed, reason code, optional text description of change
5826 if (sub # Whether to make a change entry in the L<parse|/parse> tree
5827 {my $s = changeReasonCommentSelectionSpecification; # Change selection specification
5828 return undef unless $s; # Do not record change reasons unless a change selection has been supplied
5829 my $r = ref $s; # Change selection has been supplied
5830 return 1 if $r and $r =~ m(Regexp) and $code =~ m($s); # Requested change matches the supplied regular expression
5831 return 1 if $r and $r =~ m(HASH) and $s->{$code}; # Requested change is a key in the supplied hash
5832 return 1 if $s and $s eq $code; # Requested change equal to the supplied name
5833 undef # No match so do not crate a change entry in the L<parse|/parse> tree
5834 }->())
5835 {my $message = $reason ? "<!--$code - $reason -->" : "<!--$code-->"; # Insert message either eliding it with existing text or creating a new text node
5836 if ($node->isText) # If we are on a text node we can simply add the comment at the front
5837 {$node->text = $message.$node->text;
5838 }
5839 else
5840 {my $P = $node->prev; # At the end of a previous text node?
5841 if ($P and $P->isText)
5842 {$P->text = $node->text.$message;
5843 }
5844 else
5845 {my $N = $node->next; # At the start of a following text node?
5846 if ($N and $N->isText)
5847 {$N->text = $message.$node->text;
5848 }
5849 elsif ($node->parent) # Not a text node, no text node on either side, not the root
5850 {$node->putPrevAsText($message);
5851 }
5852 elsif (my $f = $node->first) # Root node but not text
5853 {if ($f->isText) # At front of first text node
5854 {$f->text = $message.$node->text;
5855 }
5856 else # No first node or first node is not text, place first
5857 {$node->putFirstAsText($message);
5858 }
5859 }
5860 }
5861 }
5862 }
5863 $node
5864 }
5865  
5866 sub howFirst($) #U Return the depth to which the specified B<$node> is L<first|/isFirst> else B<0>.
5867 {my ($node) = @_; # Node
5868 my $i = 0; # Count first depth
5869 for(my $p = $node; $p; $p = $p->parent) # Go up
5870 {last unless $p->isFirst; # Go up while first
5871 ++$i;
5872 }
5873 $i
5874 }
5875  
5876 sub howLast($) #U Return the depth to which the specified B<$node> is L<last|/isLast> else B<0>.
5877 {my ($node) = @_; # Node
5878 my $i = 0; # Count last depth
5879 for(my $p = $node; $p; $p = $p->parent) # Go up
5880 {last unless $p->isLast; # Go up while last
5881 ++$i;
5882 }
5883 $i
5884 }
5885  
5886 sub howOnlyChild($) #U Return the depth to which the specified B<$node> is an L<only child|/isOnlyChild> else B<0>.
5887 {my ($node) = @_; # Node
5888 my $i = 0; # Count only child depth
5889 for(my $p = $node; $p; $p = $p->parent) # Go up
5890 {last unless $p->isOnlyChild; # Go up while only child
5891 ++$i;
5892 }
5893 $i
5894 }
5895  
5896 sub howFar($$) #U Return how far the first node is from the second node along a path through their common ancestor.
5897 {my ($first, $second) = @_; # First node, second node
5898 my $p = $first->commonAncestor($second); # Find their common ancestor
5899 return 0 if $first == $second; # Same node
5900 return 1 if $first->adjacent($second); # Adjacent nodes
5901 $p->howFarAbove($first) + $p->howFarAbove($second) - # Sum of the paths to their common ancestor plus any adjustment
5902 ($first->commonAdjacentAncestors($second) ? 1 : 0); # If the nodes share a pair of common ancestral siblings the path is one step shorter
5903 }
5904  
5905 sub howFarAbove($$) #U Return how far the first node is L<above|/above> the second node is or B<0> if the first node is not strictly L<above|/above> the second node.
5906 {my ($above, $below) = @_; # First node above, second node below
5907 for(my ($i, $p) = (1, $below->parent); $p; $p = $p->parent, ++$i) # Go up from below to above
5908 {return $i if $above == $p; # Return the height if we have reached the node above
5909 }
5910 0
5911 }
5912  
5913 sub howFarBelow($$) #U Return how far the first node is L<below|/below> the second node is or B<0> if the first node is not strictly L<below|/below> the second node.
5914 {my ($below, $above) = @_; # First node below, second node above
5915 $above->howFarAbove($below) # Use howFarABove with arguments inverted
5916 }
5917  
5918 #D1 Required clean up # Insert required clean up tags.
5919  
5920 sub createRequiredCleanUp($@) #P Create a required clean up $node with the specified B<@text>
5921 {my ($node, @text) = @_; # Node, clean up messages
5922 my $text = join ' ', @text; # Combined text
5923 my $r = $node->newTag(q(required-cleanup)); # Create required clean up node
5924 $r->putFirstAsText($text); # Add text
5925 $r # Return required clean up node
5926 }
5927  
5928 sub requiredCleanUp($;$) #U Replace a B<$node> with a required cleanup node with special characters replaced by symbols and with the optional B<$outputclass>.\mReturns the specified B<$node>.
5929 {my ($node, $outputclass) = @_; # Node, optional outputclass attribute of required cleanup tag
5930 my $text = replaceSpecialChars($node->prettyString); # Replace xml chars with symbols
5931 my $r = $node->createRequiredCleanUp($text); # Create required clean up node
5932 $r->outputclass = $outputclass if $outputclass; # Add outputclass if supplied
5933 $node->replaceWith($r); # Replace current node
5934 $r # Return required clean up node
5935 }
5936  
5937 sub replaceWithRequiredCleanUp($@) #U Replace a B<$node> with required cleanup B<@text> and return the new node
5938 {my ($node, @text) = @_; # Node to be replace, clean up message
5939 my $text = join ' ', @text; # Combined text
5940 my $r = $node->createRequiredCleanUp($text); # Create required clean up node
5941 $node->replaceWith($r);
5942 $r
5943 }
5944  
5945 sub putFirstRequiredCleanUp($@) #U Place a required cleanup first under a specified B<$node> using the specified B<@text> and return the required clean up node.
5946 {my ($node, @text) = @_; # Node, clean up message
5947 my $text = join ' ', @text; # Combined text
5948 my $r = $node->createRequiredCleanUp($text); # Create required clean up node
5949 $node->putFirst($r); # Insert required clean up node
5950 $r # Return required clean up node
5951 }
5952  
5953 sub putLastRequiredCleanUp($@) #U Place a required cleanup last under a specified B<$node> using the specified B<@text> and return the required clean up node.
5954 {my ($node, @text) = @_; # Node, clean up message
5955 my $text = join ' ', @text; # Combined text
5956 my $r = $node->createRequiredCleanUp($text); # Create required clean up node
5957 $node->putLast($r); # Insert required clean up node
5958 $r # Return required clean up node
5959 }
5960  
5961 sub putNextRequiredCleanUp($@) #IU Place a required cleanup next after a specified B<$node> using the specified B<@text> and return the required clean up node.
5962 {my ($node, @text) = @_; # Node, clean up message
5963 my $text = join ' ', @text; # Combined text
5964 if ($node->parent) # Place after non root node
5965 {my $r = $node->createRequiredCleanUp($text); # Create required clean up node
5966 $node->putNext($r); # Insert required clean up node
5967 return $r; # Return required clean up node
5968 }
5969 else # Place last under a root node
5970 {return $node->putLastRequiredCleanUp($text);
5971 }
5972 }
5973 #a putFirstRequiredCleanUp
5974 #b <b><c/></b>
5975 #c at c b
5976 #c putNextRequiredCleanUp remove tag c
5977 #d Create a required cleanup tag with the specified text and put it next.
5978  
5979 sub putPrevRequiredCleanUp($$) #U Place a required cleanup before a specified B<$node> using the specified B<@text> and return the required clean up node.
5980 {my ($node, $text) = @_; # Node, clean up message
5981 if ($node->parent) # Place before non root node
5982 {my $r = $node->createRequiredCleanUp($text); # Create required clean up node
5983 $node->putPrev($r); # Insert required clean up node
5984 return $r; # Return required clean up node
5985 }
5986 else # Place first under a root node
5987 {return $node->putFirstRequiredCleanUp($text);
5988 }
5989 }
5990  
5991 #D1 Conversions # Methods useful for conversions from word, L<html> and L<Dita> to L<Dita>.
5992  
5993 #D2 Dita Conversions # Methods useful for enhancing L<Dita>.
5994  
5995 sub ditaGetConRef($$;$$) #S Get the value of a B<conref> attribute given a valid L<Dita> B<$ref> reference found in the file named B<$sourceFile>. Optionally, if the regular expression B<$matchContext> is supplied then nodes whose context (single blank separated) tags match this regular expression will be considered first as a target of the conref, if such a search fails then any unique node with the matching id will be the considered next as a possible target unless the optional B<$matchContextOnly> parameter is true. Note: all the conrefs in the included content will also be expanded creating the possibility of endless circular expansions.
5996 {my ($ref, $sourceFile, $matchContext, $matchContextOnly) = @_; # Dita ref value of conref, source file containing conref, optional regular expression of acceptable context, confine search to acceptable context.
5997 my ($rf, $rt, $ri) = parseDitaRef($ref, $sourceFile); # Parse the reference
5998 # -e $rf or confess "No such file:\n$rf\n"; # Confess if the target file does not exist
5999 return undef unless $rf and -e $rf; # Insist that the file be present
6000  
6001 my $x = eval {new($rf)}; # Parse target file
6002 return undef unless $x; # Any errors will show up in the Lint reports
6003  
6004 if ($ri) # Id present - we want part of the target
6005 {if ($matchContext) # Matching requested
6006 {my $tree; # Parse tree representing conreffed content
6007 $x->by(sub # Scan parse tree for id
6008 {my ($o) = @_; # Each node
6009 if ($o->idX eq $ri and $o->context =~ m($matchContext)) # Node with matching id and matching tag if tag matching requested
6010 {my $r = $o->ditaExpandAllConRefs($rf); # Expand any conrefs referenced by the conref
6011 $tree = $r && $o != $r ? $r->cut : $o->cut; # Parse tree representing conref
6012 }
6013 });
6014  
6015 return $tree if $tree; # Take last matching id if any
6016 }
6017  
6018 return undef if $matchContextOnly; # Broader search not allowed
6019  
6020 my $tree; # Broaden the search if the target has not been found so far and a broader search is permissible.
6021 $x->by(sub # Scan parse tree for id
6022 {my ($o) = @_; # Each node
6023 if ($o->idX eq $ri) # Node with matching id and matching tag if tag matching requested
6024 {my $r = $o->ditaExpandAllConRefs($rf); # Expand any conrefs referenced by the conref
6025 $tree = $r && $o != $r ? $r->cut : $o->cut; # Parse tree representing conref
6026 }
6027 });
6028  
6029 return $tree; # Conreffed content or fail
6030 }
6031 else # No id specified so include the entire topic
6032 {$x->by(sub # Scan the new content for conrefs to expand - let us hope that there is an end to their conref chain else we will hit the call depth limit
6033 {my ($o) = @_; # Each node
6034 $o->ditaExpandAllConRefs($rf); # Expand any conrefs in the content referenced by the conref
6035 });
6036  
6037 $x
6038 } # Id missing, we want the entire target
6039 # cluck "No such id in file: $ref\n$rf\n" unless @c; # No such id
6040 # cluck "Too many possibilities for in file: $ref\n$rf\n".dump(\@c)."\n" if @c; # Too many possibilities
6041 }
6042  
6043 sub ditaReplaceConref($$) # Replace a conref on the specified B<$node> in the specified source file B<$sourceFile> with the parse tree of the referenced content. Returns the referenced content. Confesses if there is no conref to replace on $node.
6044 {my ($node, $sourceFile) = @_; # Node with conref attribute, source file containing the node.
6045 my $c = $node->attr(q(conref)); # Conref attribute
6046 $c or confess "No conref attribute: ".-A $node; # Check there is a conref
6047 if (my $v = ditaGetConRef($c, $sourceFile)) # Parse tree
6048 {if (my $id = $node->id) # The node has an id which should be retained
6049 {my $r = $node->replaceWith($v);
6050 $r->id = $id;
6051 return $r;
6052 }
6053 else # The node does not have an id
6054 {return $node->replaceWith($v);
6055 }
6056 }
6057 undef
6058 }
6059  
6060 sub ditaReplaceAnyConref($@) #U Replace a conref with the referenced content if we are in the optional context and the target of the conref can be located. Returns true regardless of any processing performed to allow L<PCD> processing to continue.
6061 {my ($node, @context) = @_; # Node with conref attribute, optional context.
6062 return undef if @context and !$node->at(@context); # Not in specified context
6063 return $node unless my $c = $node->attr(q(conref)); # Continue if there is no conref attribute
6064 if (my $inputFile = $node->root->inputFile) # Input file
6065 {if (my $v = ditaGetConRef($c, $inputFile)) # Locate conref
6066 {if (my $id = $node->id) # The node has an id which should be retained
6067 {my $r = $node->replaceWith($v); # Replace current node with referenced node and return new node
6068 $r->id = $id;
6069 return $r;
6070 }
6071 else # No id to retain on node
6072 {return $node->replaceWith($v); # Replace current node with referenced node and return new node
6073 }
6074 }
6075 }
6076 undef # Unable to replace conref
6077 }
6078  
6079 sub ditaReplaceAnyConrefIdeallyWithMatchingTag($@) #U Replace a conref with the referenced content if we are in the optional context and the target of the conref can be located. If multiple possible targets exists, priority will be given to any that match the tag of $node. Returns the root of the parse tree containing the new content or B<undef> if no new content was located.
6080 {my ($node, @context) = @_; # Node with conref attribute, optional context.
6081 return undef if @context and !$node->at(@context); # Not in specified context
6082 return $node unless my $c = $node->attr(q(conref)); # Continue if there is no conref attribute
6083 if (my $inputFile = $node->root->inputFile) # Input file
6084 {my $tag = quotemeta $node->tag; # Tag of conreffing node
6085 if (my $v = ditaGetConRef($c, $inputFile, qr(\A$tag(\s|\Z)))) # Locate conref with, ideally, the target node having the same tag as the source node
6086 {if (my $id = $node->id) # The node has an id which should be retained
6087 {my $r = $node->replaceWith($v); # Replace current node with referenced node and return new node
6088 $r->id = $id;
6089 return $r;
6090 }
6091 else # No id to retain on node
6092 {return $node->replaceWith($v); # Replace current node with referenced node and return new node
6093 }
6094 }
6095 }
6096 undef # Unable to replace conref
6097 }
6098  
6099 sub ditaReplaceAnyConrefInContext($$@) #U Replace a conref with the referenced content if we are in the optional context and the target of the conref can be located and the L<context> of the target node matches the regular expression B<$context>. Returns the root of the parse tree containing the new content or B<undef> if no new content was located.
6100 {my ($node, $context, @context) = @_; # Node with conref attribute, tags to match, optional context.
6101 return undef if @context and !$node->at(@context); # Not in specified context
6102 return $node unless my $c = $node->attr(q(conref)); # Continue if there is no conref attribute
6103 if (my $inputFile = $node->root->inputFile) # Input file
6104 {if (my $v = ditaGetConRef($c, $inputFile, $context, 1)) # Locate conref requiring that the target node match the specified regular expression
6105 {if (my $id = $node->id) # The node has an id which should be retained
6106 {my $r = $node->replaceWith($v); # Replace current node with referenced node and return new node
6107 $r->id = $id;
6108 return $r;
6109 }
6110 else # No id to retain on node
6111 {return $node->replaceWith($v); # Replace current node with referenced node and return new node
6112 }
6113 }
6114 }
6115 undef # Unable to replace conref
6116 }
6117  
6118 sub ditaExpandAllConRefs($$) #U Expand all the conrefs in the specified B<$parseTree> relative to the specified B<$sourceFile>.
6119 {my ($tree, $sourceFile) = @_; # Parse tree, Source file we are expanding in
6120  
6121 $tree->by(sub # Search parse tree for conrefs to expand
6122 {my ($o) = @_;
6123 if ($o->attr_conref) # Located a conref
6124 {my $id = $o->id;
6125 my $r = $o->ditaReplaceConref($sourceFile); # Expand conref
6126 $r->id = $id if $r && defined $id;
6127 if ($o == $tree) # Expanded
6128 {$tree = $r;
6129 }
6130 }
6131 });
6132  
6133 $tree
6134 }
6135  
6136 sub ditaAbsoluteHref($$) # Return the absolute value of the href of a specified B<$node> relative to the specified B<$sourceFile> or B<undef> if the node has no B<href> attribute.
6137 {my ($node, $sourceFile) = @_; # Node containing href, source file
6138 if (my $h = $node->href) # Node has href
6139 {return absFromAbsPlusRel($sourceFile, $h);
6140 }
6141 undef # No href
6142 }
6143  
6144 sub ditaListToChoices($@) #UC Change the specified B<$list> to B<choices>.
6145 {my ($list, @context) = @_; # Node, optional context
6146 $list->tag =~ m(\A(ol|sl|ul)\Z)s or confess "Not a list"; # Not a list
6147 return undef if @context and !$list->at(@context); # Not in specified context
6148 for my $li($list->c_li) # All li
6149 {$li->change(q(choice)); # Change li to choice
6150 }
6151 $list->change(q(choices)) ; # Change tag of node to choices
6152 }
6153  
6154 sub ditaListToSteps($@) #UC Change the specified B<$node> to B<steps> and its contents to B<cmd\step> optionally only in the specified context.
6155 {my ($list, @context) = @_; # Node, optional context
6156 return undef if @context and !$list->at(@context); # Not in specified context
6157 for(@$list) # Each li
6158 {$_->change(qw( cmd))->wrapWith(q(step)); # li -> cmd\step
6159 $_->unwrap(qw(p cmd)) for @$_; # Unwrap any contained p
6160 }
6161 $list->change(q(steps));
6162 }
6163  
6164 sub ditaListToStepsUnordered($@) #UC Change the specified B<$node> to B<steps-unordered> and its contents to B<cmd\step> optionally only in the specified context.
6165 {my ($list, @context) = @_; # Node, optional context
6166 my $steps = $list->ditaListToSteps(@context); # Change to steps
6167 $steps->change(q(steps-unordered)) if $steps; # Change to steps unordered
6168 $steps
6169 }
6170  
6171 sub ditaListToSubSteps($@) #UC Change the specified B<$node> to B<substeps> and its contents to B<cmd\step> optionally only in the specified context.
6172 {my ($list, @context) = @_; # Node, optional context
6173 return undef if @context and !$list->at(@context); # Not in specified context
6174 for(@$list) # Each li
6175 {$_->change(qw( cmd))->wrapWith(q(substep)); # li -> cmd\step
6176 $_->unwrap(qw(p cmd)) for @$_; # Unwrap any contained p
6177 }
6178 $list->change(q(substeps));
6179 }
6180  
6181 sub ditaStepsToList($$@) #UC Change the specified B<$node> to a node with name B<$tag> or to B<ol> if B<$tag> is not supplied and its B<cmd\step> content to B<li> to create a list optionally only in the specified context.
6182 {my ($steps, $tag, @context) = @_; # Node, new tag if not ol, optional context
6183 return undef if @context and !$steps->at(@context); # Not in specified context
6184  
6185 for(@$steps) # Content
6186 {$_->change(q(li)); # Change content to li
6187 $_->unwrap for $_->c_cmd; # Unwrap cmd
6188 }
6189 $steps->change($tag//q(ol)); # Change tag of node to ol unless an alternative has been supplied
6190 }
6191  
6192 sub ditaStepsToChoices($@) #UC Change the specified B<$node> to B<choices>.
6193 {my ($steps, @context) = @_; # Node, optional context
6194 return undef if @context and !$steps->at(@context); # Not in specified context
6195 for my $step(@$steps) # Steps
6196 {$step->change(q(choice)); # Change step to choice
6197 for my $o(@$step)
6198 {my $t = $o->tag;
6199 if ($t =~ m(\Acmd\Z)s)
6200 {$o->change(q(p));
6201 }
6202 elsif ($t =~ m(\A(stepresult|stepxmp)\Z)s)
6203 {$o->unwrap;
6204 }
6205 }
6206 }
6207 $steps->change(q(choices)) ; # Change tag of node to choices
6208 }
6209  
6210 sub ditaConvertSubStepsToSteps($@) #UC Change the B<$substeps> to B<steps> and return the B<steps> on success or B<undef> on failure.
6211 {my ($substeps, @context) = @_; # Substeps, optional context
6212 $substeps->at_substeps or confess "Not on substeps"; # Not on substeps
6213 return undef if @context and !$substeps->at(@context); # Not in specified context
6214 for my $s(@$substeps) # Substeps
6215 {$s->change_step; # Change substep to step
6216 }
6217 $substeps->change_steps; # Change to steps
6218 }
6219  
6220 sub ditaListToTable($@) #UC Convert a list to a table in situ - as designed by MiM.
6221 {my ($node, @context) = @_; # List node, optional context
6222 return undef if @context and !$node->at(@context); # Not in specified context
6223  
6224 my $cols = 0; # Number of columns
6225 for my $l($node->c_li)
6226 {my $n = $l->c_p;
6227 $cols = max($cols, $n);
6228 }
6229  
6230 my $table = $node->change_table; # Table structure
6231 my $tgroup = $table->wrapContentWith_tgroup->set(cols=>$cols);
6232 my $tbody = $tgroup->wrapContentWith_tbody;
6233 my $headEntries = q(<entry/>) x $cols;
6234 $tgroup->putFirst(Data::Edit::Xml::new(<<END));
6235 <thead>
6236 <row>
6237 $headEntries
6238 </row>
6239 </thead>
6240 END
6241  
6242 for my $i(reverse 1..$cols) # Add colspec
6243 {$tgroup->putFirst($node->newTag
6244 (qw(colspec colwidth 1*), colname=>q(c).$i, colnum=>$i));
6245 }
6246  
6247 for my $l($tbody->c_li) # Convert li to row and the p to entry
6248 {$l->change_row;
6249 for my $p($l->c_p)
6250 {$p->change_entry
6251 }
6252 }
6253  
6254 $node # Table thus constructed
6255 }
6256  
6257 sub ditaMergeLists($@) #UC Merge the specified B<$node> with the preceding or following list or steps or substeps if possible and return the specified B<$node> regardless.
6258 {my ($node, @context) = @_; # Node, optional context
6259 return undef if @context and !$node->at(@context); # Not in specified context
6260 $node->ditaMergeListsOnce for 1..2 # Do the merge twice to pick up all the stragglers
6261 }
6262  
6263 sub ditaMergeListsOnce($) #UP Merge the specified B<$node> with the preceding or following list or steps or substeps if possible and return the specified B<$node> regardless.
6264 {my ($node) = @_; # Node
6265 if ($node->at(qr(\A(ol|ul|steps|substeps)\Z))) # Lists
6266 {if (my $p = $node->prev(-t $node)) # Merge two lists or steps or substeps
6267 {$p->putLast($node->cut);
6268 $node->unwrap;
6269 }
6270 elsif ($node->at(qr(\A(ol|sl|ul)))) # List with preceding or following list elements
6271 {if (my $p = $node->prev(q(li)))
6272 {$node->putFirst($p->cut);
6273 }
6274 elsif (my $n = $node->next(q(li)))
6275 {$node->putLast($n->cut);
6276 }
6277 }
6278 elsif ($node->at(q(steps))) # Steps with preceding or following step
6279 {if (my $p = $node->prev(qr(step|stepsection)))
6280 {$node->putFirst($p->cut);
6281 }
6282 elsif (my $n = $node->next(q(step)))
6283 {$node->putLast($n->cut);
6284 }
6285 }
6286 elsif ($node->at(q(substeps))) # Substeps with preceding or following steps
6287 {if (my $p = $node->prev(q(substep)))
6288 {$node->putFirst($p->cut);
6289 }
6290 elsif (my $n = $node->next(q(substep)))
6291 {$node->putLast($n->cut);
6292 }
6293 }
6294 elsif ($node->at(q(step)) and !$node->up(q(steps))) # Step not in steps
6295 {$node->wrapWith(q(steps));
6296 }
6297 elsif ($node->at(q(substep)) and !$node->up(q(substeps))) # Substep not in substeps
6298 {$node->wrapWith(q(steps));
6299 }
6300 elsif ($node->at(q(li)) and !$node->up(qr(\A(ol|sl|ul)\Z))) # Li not in list
6301 {$node->wrapWith(q(ol));
6302 }
6303 elsif ($node->at(q(cmd)) and $node->up(q(steps))) # Cmd under steps
6304 {$node->wrapWith(q(step));
6305 }
6306 elsif ($node->at(q(cmd)) and $node->up(q(substeps))) # Cmd under substeps
6307 {$node->wrapWith(q(substep));
6308 }
6309 elsif ($node->not(q(li)) and $node->up(qr(\A(ol|sl|ul)\Z))) # Something under a list which is not an li
6310 {$node->wrapWith(q(li));
6311 }
6312 elsif ($node->not(qw(step stepsection)) and $node->up(q(steps))) # Something under steps which is not a step or stepsection
6313 {if (my $p = $node->prev(q(stepsection)))
6314 {$p->putLast($node->cut);
6315 }
6316 else
6317 {$node->wrapWith(q(stepsection));
6318 }
6319 }
6320 }
6321 elsif ($node->at(q(li))) # Free floating list element
6322 {if (my $p = $node->parent)
6323 {if ($p->not(qw(ol sl ul)))
6324 {sub
6325 {if (my $prev = $node->prev)
6326 {if ($prev->at(qr(\A(ol|sl|ul)\Z)))
6327 {$prev->putLastCut($node);
6328 return;
6329 }
6330 }
6331  
6332 if (my $next = $node->next)
6333 {if ($next->at(qr(\A(ol|sl|ul)\Z)))
6334 {$next->putFirstCut($node);
6335 return;
6336 }
6337 }
6338 $node->wrapWith(q(ol));
6339 }->();
6340 }
6341 }
6342 }
6343  
6344 $node # Return the specified B<$node>
6345 }
6346  
6347 sub mergeLikeElements($@) #UC Merge two of the same elements into one, retaining the order of any children. Return the original B<$node> if the request succeeds, else return B<undef>.
6348 {my ($node, @context) = @_; # Node, optional context
6349 if (my $a = $node->mergeLikePrev(@context))
6350 {return $a;
6351 }
6352 if (my $b = $node->mergeLikeNext(@context))
6353 {return $b;
6354 }
6355 undef;
6356 }
6357  
6358 sub mergeLikeNext($@) #UC Merge a B<$node> in an optional context with the next node if the two have the same tag by placing the next node first in the current B<$node> and unwrapping the next node. Return B<undef> if the request fails else the current B<$node>. Identical to L<mergeLikeElements|/mergeLikeElements>
6359 {my ($node, @context) = @_; # Node, optional context
6360 return undef if @context and !$node->at(@context); # Not in specified context
6361 if (my $next = $node->next(@context ? ($context[0]) : (-t $node))) # Check following node has the same context as far as it is known
6362 {my $t = $node->lastText && $next->firstText; # Check whether we will be merging two text items
6363 $node->putLastCut($next);
6364 $next->putPrevAsText(q( )) if $t; # Separate the two nodes with some white space if they contain just text
6365 $next->unwrap;
6366 return $node;
6367 }
6368 undef
6369 }
6370  
6371 BEGIN{*mln=*mergeLikeNext}
6372  
6373 sub mergeLikePrev($@) #UC Merge a B<$node> in an optional context with the previous node if the two have the same tag by placing the previous node first in the current B<$node> and unwrapping the previous node. Return B<undef> if the request fails else return the specified B<$node>.
6374 {my ($node, @context) = @_; # Node, optional context
6375 return undef if @context and !$node->at(@context); # Not in specified context
6376 if (my $prev = $node->prev(@context ? ($context[0]) : (-t $node))) # Check following node has the same context as far as it is known
6377 {my $t = $node->firstText && $prev->lastText; # Check whether we will be merging two text items
6378 $node->putFirstCut($prev);
6379 $prev->putNextAsText(q( )) if $t; # Separate the two nodes with some white space if they contain just text
6380 $prev->unwrap;
6381 return $node;
6382 }
6383 undef
6384 }
6385  
6386 #b <b id="1">bbbb</b><b id="2">BBBB</b>
6387 #c mergeLikePrev b
6388 #d Merge the current node into the previous node if it has the same tag name.
6389  
6390 BEGIN{*mlp=*mergeLikePrev}
6391  
6392 sub mergeOnlyChildLikeNext($@) #UC Merge a B<$node> if it is the only child of its parent with a preceding node of the same name that is also the only child of its parent and return the specified B<$node> or B<undef> if the request fails.
6393 {my ($node, @context) = @_; # Node, optional context
6394 return undef if @context and !$node->at(@context); # Not in specified context
6395 return undef unless $node->isOnlyChild; # Node is an only child
6396 return undef unless my $parent = $node->parent; # Parent node
6397 return undef unless my $Parent = $parent->next(-t $parent); # Prior parent
6398 return undef unless $Parent->hasSingleChild(-t $node); # Prior single child
6399 mergeLikeNext($_) for $parent, $node; # Merge
6400 $node # Original node with content merged in
6401 }
6402  
6403 BEGIN{*mocln=*mergeOnlyChildLikeNext}
6404  
6405 sub mergeOnlyChildLikePrev($@) #UC Merge a B<$node> if it is the only child of its parent with a preceding node of the same name that is also the only child of its parent and return the specified B<$node> or B<undef> if the request fails.
6406 {my ($node, @context) = @_; # Node, optional context
6407 return undef if @context and !$node->at(@context); # Not in specified context
6408 return undef unless $node->isOnlyChild; # Node is an only child
6409 return undef unless my $parent = $node->parent; # Parent node
6410 return undef unless my $Parent = $parent->prev(-t $parent); # Prior parent
6411 return undef unless $Parent->hasSingleChild(-t $node); # Prior single child
6412 mergeLikePrev($_) for $parent, $node; # Merge
6413 $node # Original node with content merged in
6414 }
6415  
6416 BEGIN{*moclp=*mergeOnlyChildLikePrev}
6417  
6418 sub mergeOnlyChildLikePrevLast($@) #UC Merge a B<$node> if it is the only child of its parent with a preceding node with the same tag that is the last child of its parent and return the previous B<$node> or B<undef> if the request fails.
6419 {my ($node, @context) = @_; # Node, optional context
6420 return undef if @context and !$node->at(@context); # Not in specified context
6421 return undef unless $node->isOnlyChild; # Node is an only child
6422 return undef unless my $parent = $node->parent; # Parent node
6423 return undef unless my $Parent = $parent->prev(-t $parent); # Prior parent
6424 return undef unless my $cousin = $Parent->last(-t $node); # Prior matching last child
6425 mergeLikeNext($_) for $Parent, $cousin; # Merge
6426 $cousin # Original node with content merged in
6427 }
6428  
6429 sub ditaMaximumNumberOfEntriesInATGroupRow($) #U Return the maximum number of entries in the rows of the specified B<$table> or B<undef> if not a table.
6430 {my ($tgroup) = @_; # TGroup node
6431 $tgroup->at_tgroup or confess "Not a tgroup node: ".$tgroup->tag; # Confirm we are on a tgroup
6432 my $N = 0; # Maximum number of entries in a row
6433 $tgroup->by(sub # Traverse tgroup
6434 {if (my ($r, $hb, $g) = @_)
6435 {if ($r->at_row_thead_tgroup or $r->at_row_tbody_tgroup) # Check this row is in the current table
6436 {if ($g == $tgroup)
6437 {$N = max($N, $r->ditaNumberOfColumnsInRow); # Maximum number of entries in a row so far
6438 }
6439 }
6440 }
6441 });
6442  
6443 $N
6444 }
6445  
6446 sub ditaNumberOfColumnsInRow($) #UP Return estimate of the number of columns in a row
6447 {my ($row) = @_; # Row
6448 my @e = $row->c_entry;
6449 my $spans = 0; # Number of additional spanned columns
6450 for my $e(@e) # Number of pad entries in this row
6451 {if (my $a = $e->attr_namest) # Span start
6452 {if (my $b = $e->attr_nameend) # Span end
6453 {s(\A\D+) ()gs for $a, $b; # Remove non digits from front of column name on the assumptions (as is so often the case) that the column names are numbered sequentially.
6454 $spans += ($b||0) - ($a||0); # Additional columns
6455 }
6456 }
6457 }
6458  
6459 $spans + @e
6460 }
6461  
6462 sub ditaTGroupStatistics($) #U Return statistics about the rows in a given table
6463 {my ($tgroup) = @_; # Table group node
6464 $tgroup->at_tgroup or confess "Not a tgroup node: ".$tgroup->tag; # Confirm we are on a tgroup
6465  
6466 my $maxHeadMinusPadding; # Maximum number of entries in a head row after an padding entries have been removed
6467 my $maxHead; # Maximum number of entries in a head row regardless of padding rows
6468 my $minHead; # Minimum number of entries in a head row regardless of padding rows
6469 my $maxBodyMinusPadding; # Maximum number of entries in a body row after an padding entries have been removed
6470 my $maxBody; # Maximum number of entries in a body row regardless of padding rows
6471 my $minBody; # Minimum number of entries in a body row regardless of padding rows
6472 my $colSpec = 0; # Colspec
6473 my $rows = 0; # Number of rows in table = head and body combined rows
6474  
6475 $tgroup->by(sub # Traverse table group
6476 {if (my ($r, $h, $g) = @_)
6477 {if ($r->at_row_thead_tgroup and $g == $tgroup) # Heading row in current table group
6478 {if (my @n = $r->c_entry) # Entries in this heading row
6479 {my $n = $r->ditaNumberOfColumnsInRow; # Number of entries in a heading row so far
6480 $maxHead = max($maxHead//0, $n); # Maximum number of entries in a heading row so far
6481 $minHead = min($minHead//$n, $n); # Maximum number of entries in a heading row so far
6482 while(@n) # Remove padding entries
6483 {if ($n[-1]->isAllBlankText) {pop @n; next}
6484 last;
6485 }
6486 $maxHeadMinusPadding = max($maxHeadMinusPadding//0, $n); # Maximum number of non padding entries in a heading row so far
6487 }
6488 ++$rows;
6489 }
6490 elsif ($r->at_row_tbody_tgroup and $g == $tgroup) # Body row in current table group
6491 {if (my @n = $r->c_entry) # Entries in this body row
6492 {my $n = $r->ditaNumberOfColumnsInRow; # Number of entries in a body row so far
6493 $maxBody = max($maxBody//0, $n); # Maximum number of entries in a body row so far
6494 $minBody = min($minBody//$n, $n); # Maximum number of entries in a body row so far
6495 while(@n) # Remove padding entries
6496 {if ($n[-1]->isAllBlankText) {pop @n; next}
6497 last;
6498 }
6499 $maxBodyMinusPadding = max($maxBodyMinusPadding//0, $n); # Maximum number of non padding entries in a body row so far
6500 }
6501 ++$rows;
6502 }
6503 elsif ($r->at_colspec_tgroup and $h == $tgroup) # Colspec
6504 {++$colSpec;
6505 }
6506 }
6507 });
6508  
6509 genHash(q(Data::Edit::Xml::Table::Statistics), # Statistics about a table
6510 colsAttribute => $tgroup->attr_cols, # Column attribute
6511 maxHeadMinusPadding => $maxHeadMinusPadding, # Maximum number of entries in a head row after an padding entries have been removed
6512 maxHead => $maxHead, # Maximum number of entries in a head row regardless of padding rows
6513 minHead => $minHead, # Maximum number of entries in a head row regardless of padding rows
6514 maxBodyMinusPadding => $maxBodyMinusPadding, # Maximum number of entries in a body row after an padding entries have been removed
6515 maxBody => $maxBody, # Maximum number of entries in a body row regardless of padding rows
6516 minBody => $minBody, # Maximum number of entries in a body row regardless of padding rows
6517 colSpec => $colSpec, # Number of colspec entries
6518 rows => $rows, # Number of rows
6519 );
6520 }
6521  
6522 sub ditaAddPadEntriesToTGroupRows($$) #UP Adding padding entries to a tgroup to make sure every row has the same number of entries
6523 {my ($tgroup, $nEntries) = @_; # TGroup node, number of entries
6524 $tgroup->at_tgroup or confess "Not a tgroup node: ".$tgroup->tag; # Confirm we are on a tgroup
6525 $tgroup->by(sub # Traverse tgroup
6526 {if (my ($r, $hb, $g) = @_)
6527 {if ($r->at_row_thead_tgroup || $r->at_row_tbody_tgroup and $g == $tgroup) # Check this row is in the current tgroup
6528 {my $cols = $r->ditaNumberOfColumnsInRow; # Number of columns
6529 for($cols..$nEntries-1) # Number of pad entries required in this row
6530 {$r->putLast($r->newTag(q(entry))); # Add new padding entry
6531 }
6532 }
6533 }
6534 });
6535 }
6536  
6537 sub ditaAddColSpecToTGroup($$) #U Add the specified B<$number> of column specification to a specified B<$tgroup> which does not have any already.
6538 {my ($tgroup, $number) = @_; # Tgroup node, number of colspecs to add
6539 $tgroup->at_tgroup or confess "Not a tgroup node: ".$tgroup->tag; # Confirm we are on a tgroup node
6540 $tgroup->set(cols=>$number); # Set cols attribute
6541 my @c = $tgroup->c_colspec; # Existing colspecs
6542 $_->unwrap for @c; # Remove existing colspecs
6543 for my $col(reverse 1..$number) # Add colspecs
6544 {$tgroup->putFirst($tgroup->newTag(q(colspec), # Colspec
6545 colname=>"c$col", colnum=>"$col", colwidth=>"1*"));
6546 }
6547 }
6548  
6549 sub ditaFixTGroupColSpec($) #U Fix the colspec attribute and colspec nodes of the specified B<$tgroup>.
6550 {my ($tgroup) = @_; # Tgroup node
6551 $tgroup->at_tgroup or confess "Not a tgroup node: ".$tgroup->tag; # Check we are on a tgroup
6552 my $N = $tgroup->ditaMaximumNumberOfEntriesInATGroupRow; # Maximum number of entries in a row
6553 $tgroup->ditaAddColSpecToTGroup($N); # Add colspecs
6554 }
6555  
6556 sub ditaRemoveTGroupTrailingEmptyEntries($) #U Remove empty trailing entry
6557 {my ($tgroup) = @_; # Table node
6558 $tgroup->at_tgroup or confess "Not a tgroup node: ".$tgroup->tag; # Confirm we are on a tgroup node
6559 {for my $hb($tgroup->c_thead, $tgroup->c_tbody) # THead and TBody in TGroup
6560 {for my $r($hb->c_row) # Rows in THead and TBody
6561 {my @e = $r->c_entry; # Entries in Row
6562 while(@e) # Each entry
6563 {if ($e[-1]->isAllBlankText) # Trailing blank entry
6564 {$e[-1]->cut; # Remove trailing blank entry
6565 pop @e; # Remove entry
6566 next; # Next trailing entry
6567 }
6568 last; # Not blank
6569 }
6570 }
6571 }
6572 }
6573 }
6574  
6575 sub fixTGroup($) #UC Fix the specified B<$tgroup> so that each row has the same number of entries with this number reflected in the tgroup.cols= attribute and colspec nodes.
6576 {my ($tgroup) = @_; # TGroup node
6577 $tgroup->at_tgroup or confess "Not a tgroup node: ".$tgroup->tag; # Check we are on a tgroup
6578  
6579 $tgroup->by(sub
6580 {my ($o, $p) = @_; # Misplaced rows
6581 if ($o->at_row_tgroup)
6582 {if ($p == $tgroup)
6583 {my $b = $o->wrapWith_tbody;
6584 $b->mergeLikePrev;
6585 }
6586 }
6587 });
6588  
6589 my $stats = $tgroup->ditaTGroupStatistics; # Statistics for tgroup
6590 my $cols = $stats->colsAttribute;
6591 my $maxCols = max($stats->maxHead//0, $stats->maxBody//0);
6592 my $maxColsMP = max($stats->maxHeadMinusPadding//0,
6593 $stats->maxBodyMinusPadding//0);
6594 if (($stats->maxHead//0) == $maxCols and # The right combination
6595 ($stats->minHead//0) == $maxCols and
6596 ($stats->maxBody//0) == $maxCols and
6597 ($stats->minBody//0) == $maxCols and
6598 $stats->colSpec == $maxCols)
6599 {if (!$cols or $cols != $maxCols) # Cols wrong but everything else ok
6600 {$tgroup->ditaAddColSpecToTGroup($maxCols);
6601 }
6602 }
6603 else # Repad columns
6604 {$tgroup->ditaRemoveTGroupTrailingEmptyEntries;
6605 $tgroup->ditaAddPadEntriesToTGroupRows($maxColsMP);
6606 $tgroup->ditaAddColSpecToTGroup($maxColsMP);
6607 }
6608 $tgroup->ditaFixTGroupColSpec;
6609 }
6610  
6611 sub fixTable($) #U Fix the specified B<$table> so that each row has the same number of entries with this number reflected in the tgroup.cols= attribute and colspec nodes.
6612 {my ($table) = @_; # Table node
6613 $table->at_table or confess "Not a table node: ".$table->tag; # Check we are on a table
6614  
6615 if ($table->isAllBlankText) # Add the text of a minimal table declaration if the table is blank
6616 {$table->putFirstAsTree(<<END);
6617 <tgroup cols="1">
6618 <tbody>
6619 <row><entry/></row>
6620 </tbody>
6621 </tgroup>
6622 END
6623 }
6624 else # Try to fix a non blank table
6625 {for my $g($table->c_tgroup) # Each tgroup
6626 {$g->fixTGroup;
6627 }
6628 # if (!$table->go_title) # Add previous p as title if no title present and the p does not have prohibited items in it
6629 # {if (my $p = $table->prev_p) # Holding off on this addition as it destroys some existing conversions
6630 # {my $c = $p->countTagNames;
6631 # if (!$$c{xref})
6632 # {$table->putFirstCut($p->change_title);
6633 # }
6634 # }
6635 # }
6636 }
6637 $table
6638 }
6639  
6640 sub fixEntryColSpan($) #U Fix the colspan on an entry assumed to be under row, tbody, tgroup with @cols and colspecs' set
6641 {my ($entry) = @_; # Entry
6642 $entry->at_entry_row_tbody_tgroup or confess "Not a usable entry node"; # Check we are on an entry of the right kind
6643  
6644 my $colspan = $entry->attr_colspan; # colspan
6645 return $entry unless $colspan;
6646 $colspan =~ m(\A\d+\Z)s or confess "Unexpected colspan value $colspan";
6647  
6648 my (undef, $row, $tbody, $tgroup) = $entry->ancestry; # cols
6649 my $cols = $tgroup->attr_cols or
6650 confess "No \@cols on tgroup ". (-A $tgroup). "\n";
6651  
6652 my @cols = grep {defined $_} map {$_->attr_colname} $tgroup->c_colspec; # colspec
6653 @cols == $cols or confess "cols/colspec mismatch ".(-p $tgroup). "\n";
6654 $colspan > 0 and $colspan <= $cols or
6655 confess "Colspan $colspan out of range $cols";
6656 my %cols = map {$cols[$_]=>$_} keys @cols;
6657  
6658 $entry->deleteAttr_colspan;
6659 return $entry if $cols == 1 or $colspan == 1; # Degenerate cases
6660  
6661 if ($entry->isOnlyChild)
6662 {$entry->set(namest=>$cols[0], nameend=>$cols[-1]);
6663 }
6664 elsif ($entry->isFirst) # Easy case`
6665 {$entry->set(namest=>$cols[0], nameend=>$cols[$colspan-1]);
6666 }
6667 elsif ($entry->isLast) # Easy case
6668 {$entry->set(namest=>$cols[-$colspan], nameend=>$cols[-1]);
6669 }
6670 else # Normal case
6671 {sub
6672 {my @c = $entry->contentBefore;
6673 for my $e(@c)
6674 {if (my $end = $e->attr_nameend)
6675 {if (my $c = $cols{$end})
6676 {$entry->set(namest=>$cols[$c+1], nameend=>$cols[$c+$colspan]);
6677 return;
6678 }
6679 }
6680 }
6681 my $c = @c;
6682 $entry->set(namest=>$cols[$c], nameend=>$cols[$c+$colspan-1]);
6683 }->();
6684 }
6685 }
6686  
6687 sub fixEntryRowSpan($) #U Fix the rowspan on an entry
6688 {my ($entry) = @_; # Entry
6689 $entry->at_entry or confess "Not an entry node"; # Check we are on entry
6690  
6691 my $rowspan = $entry->attr_rowspan; # rowspan
6692 return $entry unless $rowspan;
6693  
6694 $rowspan =~ m(\A\d+\Z)s or confess "Unexpected rowspan $rowspan value";
6695 $rowspan > 0 or confess "Rowspan $rowspan out of range";
6696 $entry->set(morerows=>$rowspan-1);
6697 $entry->deleteAttr_rowspan;
6698 $entry
6699 }
6700  
6701 sub ditaConvertDlToUl($) #U Convert a L<Dita> B<$dl> to a B<ul> if each B<dlentry> has only B<dt> or B<dl> elements but not both. Return B<undef> if such a conversion is not possible else return the new B<ul> node.
6702 {my ($dl) = @_; # Dl
6703 return undef unless $dl->at_dl; # Check start tag
6704  
6705 my @e; my @l;
6706 for my $e($dl->c_dlentry) # Each dlentry
6707 {my @t = $e->c_dt; # dt elements
6708 my @d = $e->c_dd; # dd elements
6709 return undef if @d and @t; # Mixed entry suppresses the conversion
6710 push @e, $e; # Unwrap thee elements later
6711 push @l, @t, @d; # Convert these elements to li
6712 }
6713  
6714 $_->unwrap for @e; # Unwrap dlentry
6715 $_->change_li for @l; # Change dt/dd to li
6716 $dl->change_ul; # Change dl to ul and return
6717 }
6718  
6719 sub ditaConvertOlToSubSteps($@) #U Convert a L<Dita> B<$ul> to B<substeps> else B<undef> if this is not possible.
6720 {my ($ol, @context) = @_; # Ul, context
6721 return undef if !$ol->at(q(ol), @context); # Not in specified context
6722  
6723 for my $e($ol->c_li) # Each li
6724 {$e->change_cmd__wrapWith_substep; # Change li to cmd\substep
6725 }
6726  
6727 $ol->change_substeps; # Change ol to substeps
6728 }
6729  
6730 sub ditaConvertUlToSubSteps($@) #U Convert a L<Dita> B<$ol> to B<substeps> else B<undef> if this is not possible.
6731 {my ($ul, @context) = @_; # Ul, context
6732 return undef if !$ul->at(q(ul), @context); # Not in specified context
6733  
6734 for my $e($ul->c_li) # Each li
6735 {$e->change_cmd__wrapWith_substep; # Change li to cmd\substep
6736 }
6737  
6738 $ul->change_substeps; # Change ul to substeps
6739 }
6740  
6741 sub ditaConvertFromHtmlDl($) #U Convert a B<Html> B<$dl> to a L<Dita> B<dl> or return B<undef> if this is not possible.
6742 {my ($dl) = @_; # Dl
6743 return undef unless $dl->at_dl; # Check start tag
6744  
6745 my $t; # Last entry
6746 for my $e(reverse @$dl) # Each dt/dd
6747 {if ($e->at_dt) # dt
6748 {if ($t) # Wrap to last entry with dlentry
6749 {$t = $e->wrapTo($t->prev, q(dlentry));
6750 }
6751 else # Wrap to end with dlentry
6752 {$t = $e->wrapToLast(q(dlentry));
6753 }
6754 }
6755 }
6756 $dl
6757 }
6758  
6759 sub ditaConvertSimpleTableToTable($) #U Convert a L<Dita> B<simpletable> to a B<table>.
6760 {my ($simpleTable) = @_; # Simple table
6761 $simpleTable->at_simpletable or confess "Not on a simple table"; # Not a simpletable
6762  
6763 $simpleTable->by(sub # Traverse table making changes
6764 {if (my ($s) = @_)
6765 {if ($s->at_simpletable) # Simple table
6766 {$s->change_table; # Change to table
6767 my $g = $s->wrapContentWith_tgroup; # Wrap content with tgroup
6768 my $b = $g->wrapContentWith_tbody; # Wrap content with tbody
6769 if (my $h = $b->go_thead) # Move thead out of tbody
6770 {$b->putPrevCut($h);
6771 }
6772 $s->fixTable; # Fix remaining problems
6773 $s->deleteAttr_relcolwidth;
6774 }
6775 elsif ($s->at_sthead) # thead
6776 {$s->change_thead;
6777 $s->wrapContentWith_row;
6778 }
6779 elsif ($s->at_stentry) # entry
6780 {$s->change_entry;
6781 }
6782 elsif ($s->at_strow) # row
6783 {$s->change_row;
6784 }
6785 }
6786 });
6787  
6788 $simpleTable # Simple table is now a normal table
6789 }
6790  
6791 sub ditaCouldConvertConceptToTask($) #U Check whether a concept could be converted to a task
6792 {my ($concept) = @_; # Concept to check
6793 return () unless $concept->at_concept; # Not a concept
6794 my $body = $concept->go_conbody; # No conbody
6795 return () unless $body;
6796 $body->c_ol; # Ol to break on
6797 }
6798  
6799 sub ditaConvertConceptToTask($@) #U Convert a Dita B<concept> to a B<task> by representing B<ol> as B<steps>. Return B<undef> if the conversion is not possible because there are no B<ol> else return the specified B<$concept> as as B<task>.
6800 {my ($node, @context) = @_; # Node, optional context
6801  
6802 return undef if @context and !$node->at(@context); # Node not in specified context
6803 return undef unless my $concept = $node->upUntil_concept;
6804  
6805 my @ol = $concept->ditaCouldConvertConceptToTask; # Breaking ol
6806 return undef unless @ol;
6807  
6808 my $body = $concept->go_conbody; # Conbody guaranteed by prior check
6809 if (my $p = $ol[0]->prev) # Items before first ol become context
6810 {$p->wrapFromFirst_context;
6811 }
6812 else
6813 {$body->putFirst($body->newTag_context);
6814 }
6815  
6816 for my $i(grep {$_ > 0} keys @ol) # Items between ol become stepsection
6817 {my $o = $ol[$i];
6818 my $O = $ol[$i-1];
6819 if ($o != $O)
6820 {$O->wrapSiblingsBetween($o, q(stepsection));
6821 }
6822 }
6823  
6824 if (my $p = $ol[-1]->next) # Items after last ol become results
6825 {$p->wrapToLast_result;
6826 }
6827 else
6828 {$body->putLast($body->newTag_result);
6829 }
6830  
6831 $ol[0]->wrapTo($ol[-1], q(steps)); # Range of ol becomes steps
6832  
6833 for my $ol(@ol) # Each ol becomes steps
6834 {for my $li($ol->c_li)
6835 {my @note;
6836 while(my $first = $li->first(qr(\A(fig|image|note)\Z)))
6837 {push @note, $first->cut;
6838 }
6839  
6840 if (my $first = $li->first) # Change something to cmd
6841 {if ($first->isText)
6842 {$first->wrapWith_cmd;
6843 }
6844 else
6845 {$first->change_cmd;
6846 }
6847 }
6848 if (my $first = $li->first) # Remainder after cmd becomes info
6849 {if (my $last = $li->last)
6850 {if ($first != $last)
6851 {if (my $next = $first->next)
6852 {$next->wrapTo($last, q(info));
6853 }
6854 }
6855 }
6856 }
6857  
6858 if (my $cmd = $li->first_cmd) # Ameliorate any trailing items in cmd by putting them first in context
6859 {while(my $last = $cmd->last(qr(\A(fig|image|note)\Z)))
6860 {my $info = $li->addLast_info;
6861 $info->putFirstCut($last);
6862 }
6863 if ($cmd->over2(qr(\A( li )+\Z))) # Li in cmd to substeps
6864 {my $choices = $cmd->wrapContentWith_ol->ditaListToChoices;
6865 $cmd->putNextCut($choices);
6866 $cmd->putFirstAsText(q(Choose one of the following:));
6867 }
6868 }
6869  
6870 if (@note) # Preceding notes, images, figures
6871 {for my $n(reverse @note)
6872 {$li->putFirst($n);
6873 if (!$n->at_note)
6874 {$n->wrapWith_note;
6875 }
6876 }
6877 }
6878  
6879 $li->change_step; # li to step
6880 if (!$li->go_cmd) # Make sure there is a command for the step
6881 {if (my $n = $li->go_note)
6882 {$n->putNextAsTree(q(<cmd/>));
6883 }
6884 else
6885 {$li->putFirstAsTree(q(<cmd/>));
6886 }
6887 }
6888 }
6889 $ol->unwrap;
6890 }
6891  
6892 $concept->change_task;
6893 $body ->change_taskbody;
6894  
6895 $concept->go_taskbody_result__hasSingleChild_section__unwrap__change_example; # Unwrap section only child of result and make result into an example
6896 $concept->go_taskbody_result__hasSingleChild_example__parent__unwrap; # Unwrap result around example
6897  
6898 $concept
6899 }
6900  
6901 BEGIN{*ct=*ditaConvertConceptToTask}
6902  
6903 sub ditaConvertReferenceToConcept($) #U Convert a Dita B<reference> to a B<concept> by unwrapping sections. Return B<undef> if the conversion is not possible because there are no B<ol> else return the specified B<$reference> as as B<concept>.
6904 {my ($reference) = @_; # Reference
6905 $reference->at_reference or confess "Not a reference"; # Check we are on reference
6906  
6907 my $body = $reference->go_refbody;
6908 $body or confess "No refbody under reference";
6909  
6910 $reference->change_concept; # Change topic to concept
6911 $body ->change_conbody;
6912  
6913 $reference->by(sub # Unwrap sections
6914 {$_->unwrap_section;
6915 });
6916  
6917 $reference # Return reference as a concept
6918 }
6919  
6920 sub ditaConvertReferenceToTask($) #U Convert a Dita B<reference> to a B<task> in situ by representing B<ol> as B<steps>. Return B<undef> if the conversion is not possible because there are no such B<ol> else return the specified B<$reference> as as B<task>.
6921 {my ($reference) = @_; # Reference
6922 $reference->at_reference or confess "Not a reference"; # Check we are on reference
6923  
6924 my $body = $reference->go_refbody;
6925 $body or confess "No refbody under reference";
6926  
6927 # my $ol; # Check that the necessary ol is present
6928 # $body->by(sub
6929 # {my ($o) = @_;
6930 # if ($o->at_ol_section_refbody)
6931 # {++$ol;
6932 # }
6933 # });
6934 # return undef unless $ol;
6935  
6936 if (my $concept = $reference->ditaConvertReferenceToConcept)
6937 {return $concept->ditaConvertConceptToTask;
6938 }
6939 confess "Unable to convert reference to task";
6940 }
6941  
6942 sub ditaConvertConceptToReference($) #U Convert a Dita B<concept> to a B<reference>. Return B<undef> if the conversion is not possible else return the specified B<$concept> as as B<reference>.
6943 {my ($concept) = @_; # Concept
6944 $concept->at_concept or confess "Not a concept"; # Check we are on concept
6945  
6946 my $body = $concept->go_conbody;
6947 $body or confess "No conbody under concept";
6948  
6949 if (my @s = $body->c_section) # Sections in concept
6950 {if (my $p = $s[0]->prev)
6951 {$body->wrapContentWith_section->moveEndAfter($p);
6952 }
6953 if (my $n = $s[-1]->next)
6954 {$body->wrapContentWith_section->moveStartBefore($n);
6955 }
6956 }
6957 else
6958 {$body->wrapContentWith_section;
6959 }
6960  
6961 $concept->change_reference;
6962 $body ->change_refbody;
6963  
6964 # if (!$concept->id)
6965 # {$concept->createGuidId;
6966 # }
6967  
6968 $concept
6969 }
6970  
6971 sub ditaConvertTopicToTask($) #U Convert a topic that is not already a task into a task
6972 {my ($x) = @_; # Topic parse tree
6973  
6974 if ($x->at_concept) # Convert concept
6975 {$x->ditaConvertConceptToTask;
6976 }
6977 elsif ($x->at_reference) # Convert reference
6978 {$x->ditaConvertReferenceToTask;
6979 }
6980  
6981 $x->at_task # Succeeded if we now have a task
6982 }
6983  
6984 sub ditaConvertSectionToConcept($) #U Convert a Dita B<$section> to a B<concept>. Return B<undef> if the conversion is not possible else return the specified B<$section> as as B<concept>.
6985 {my ($section) = @_; # Section
6986 $section->at_section or confess "Not a section, its a ",-t $section; # Check we are on a section
6987  
6988 my $title = $section->first_title; # Locate any existing title
6989  
6990 my $concept = $section->change_concept; # Change section to concept
6991 $concept->wrapContentWith_conbody;
6992  
6993 if ($title) # Move title into position
6994 {$concept->putFirstCut($title);
6995 }
6996 else
6997 {$concept->putFirst($concept->newTag_title);
6998 }
6999  
7000 $concept->createGuidId unless $concept->id; # Create an id for the topic
7001  
7002 $concept # Return concept
7003 }
7004  
7005 BEGIN{*sc=*ditaConvertSectionToConcept}
7006  
7007 sub ditaConvertConceptToSection($) #U Convert a Dita B<concept> to a B<$section> . Return B<undef> if the conversion is not possible else return the specified B<$section> as as B<concept>.
7008 {my ($concept) = @_; # Section
7009 $concept->at_concept or confess "Not a concept, its a ",-t $concept; # Check we are on a concept
7010  
7011 if (my $conbody = $concept->go_conbody) # Unwrap conbody
7012 {$conbody->unwrap;
7013 }
7014  
7015 if (my $title = $concept->first_title) # Remove any existing blank title
7016 {if ($title->isAllBlankText)
7017 {$title->cut;
7018 }
7019 }
7020  
7021 my $section = $concept->change_section; # Change concept to section
7022  
7023 $section # Return section
7024 }
7025  
7026 BEGIN{*cs=*ditaConvertConceptToSection}
7027  
7028 sub ditaConvertSectionToReference($) #U Convert a Dita B<$section> to a B<reference>. Return B<undef> if the conversion is not possible else return the specified B<$section> as as B<reference>.
7029 {my ($section) = @_; # Section
7030 if (my $c = $section->ditaConvertSectionToConcept) # First convert section to concept
7031 {return $c->ditaConvertConceptToReference; # Second convert concept to reference
7032 }
7033 undef # Conversion not possible
7034 }
7035  
7036 sub ditaConvertSectionToTask($) #U Convert a Dita B<$section> to a B<task>. Return B<undef> if the conversion is not possible else return the specified B<$section> as as B<task>.
7037 {my ($section) = @_; # Section
7038 if (my $c = $section->ditaConvertSectionToConcept) # First convert section to concept
7039 {return $c->ditaConvertConceptToTask; # Second convert concept to task
7040 }
7041 undef # Conversion not possible
7042 }
7043  
7044 sub ditaObviousChanges($) #U Make obvious changes to a L<parse|/parse> tree to make it look more like L<Dita>.
7045 {my ($node) = @_; # Node
7046  
7047 $node->by(sub # Do the obvious conversions
7048 {my ($o) = @_;
7049  
7050 my %change = # Tags that should be changed
7051 (a => q(xref),
7052 book => q(bookmap),
7053 code => q(codeph),
7054 command => q(codeph), # Needs approval from Micalea
7055 emphasis => q(b),
7056 figure => q(fig),
7057 guibutton => q(uicontrol),
7058 guilabel => q(uicontrol),
7059 guimenu => q(uicontrol),
7060 itemizedlist => q(ul), # PS2-570
7061 link => q(xref),
7062 listitem => q(li),
7063 menuchoice => q(uicontrol),
7064 orderedlist => q(ol),
7065 para => q(p),
7066 quote => q(q),
7067 replaceable => q(varname),
7068 span => q(div), # Span to div at 2019.05.19 18:59:50
7069 subscript => q(sub),
7070 variablelist => q(dl),
7071 varlistentry => q(dlentry),
7072 );
7073  
7074 my %deleteAttributesDependingOnValue = # Attributes that should be deleted if they have specified values
7075 (b=>[[qw(role bold)], [qw(role underline)]],
7076 );
7077  
7078 my @deleteAttributesUnconditionally = # Attributes that should be deleted unconditionally from all tags that have them
7079 # qw(version xml:id xmlns xmlns:xi xmlns:xl xmlns:d);
7080 qw(xml:id xmlns xmlns:xi xmlns:xl xmlns:d);
7081  
7082 my %renameAttributes = # Attributes that should be renamed
7083 (xref => [[qw(linkend href)], [qw(xrefstyle outputclass)]], # 2018.06.14 added xrefstyle->outputclass
7084 fig => [[qw(role outputclass)], [qw(xml:id id)]],
7085 example => [[qw(role outputclass)]],
7086 imagedata => [[qw(contentwidth scale)], [qw(fileref href)]],
7087 image => [[qw(src href)]], # Image source at 2019.05.19 19:04:50
7088 );
7089  
7090 for my $old(sort keys %change) # Perform requested tag changes
7091 {$o->change($change{$old}) if $o->at($old);
7092 }
7093  
7094 for my $tag(sort keys %deleteAttributesDependingOnValue) # Delete specified attributes if they have the right values
7095 {if ($o->at($tag))
7096 {$o->deleteAttr(@$_) for @{$deleteAttributesDependingOnValue{$tag}};
7097 }
7098 }
7099  
7100 $o->deleteAttrs(@deleteAttributesUnconditionally); # Delete attributes unconditionally from all tags that have them
7101  
7102 for my $tag(sort keys %renameAttributes) # Rename specified attributes
7103 {if ($o->at($tag))
7104 {$o->renameAttr(@$_) for @{$renameAttributes{$tag}};
7105 }
7106 }
7107 });
7108  
7109 $node->addFirst(q(title)) if $node->at(qr(\A(concept|reference|task)\Z)); # Make sure we have a title
7110 $node
7111 }
7112  
7113 sub ditaXrefs($) #U Make obvious changes to all the B<xref>s found in a L<parse|/parse> tree to make them more useful in L<Dita>.
7114 {my ($x) = @_; # Parse tree
7115  
7116 $x->by(sub # NEX116 at 2018.12.28 01:10:40
7117 {my ($r, $b) = @_;
7118 if ($r->at_xref)
7119 {if (my $h = $r->href)
7120 {if ($h =~ m(\Ahttps?://|\Awww\.|\.com\Z|\.net\Z|\.org\Z)s)
7121 {$r->set(scope=>q(external), format=>q(html));
7122 }
7123 }
7124 if ($b and my $tag = -t $b) # Wrap the xref with a p if immediately under a body
7125 {if ($tag =~ m(body\Z)s)
7126 {$r->wrapWith_p;
7127 }
7128 }
7129 }
7130 });
7131 }
7132  
7133 sub ditaSampleConcept(%) #S Sample concept
7134 {my (@options) = @_; # Options for concept
7135 shift @options while @options && ref $options[0]; # Remove any leading references to find the actual string or file to be parsed
7136  
7137 my %options = @options;
7138 checkKeys(\%options, # Check options
7139 {title =>q(Title of the concept),
7140 metadata =>q(Metadata of the concept ),
7141 body =>q(Body of the concept ),
7142 });
7143  
7144 my $title = $options{title} // "Title unknown - please provide one using the title keyword";
7145 my $prolog = $options{prolog} // q();
7146 my $body = $options{body} // "<p>Please provide the body of this concept using the body keyword</p>";
7147  
7148 my $metadata = sub
7149 {my $m = $options{metadata};
7150 return '' unless $m;
7151 qq(<prolog><metadata>$m</metadata></prolog>\n)
7152 }->();
7153  
7154 my $concept = new(<<END);
7155 <concept>
7156 <title id="title">$title</title>
7157 $metadata
7158 <conbody>$body</conbody>
7159 </concept>
7160 END
7161  
7162 $concept->createGuidId;
7163 $concept
7164 }
7165  
7166 sub ditaSampleTask(%) #S Sample task
7167 {my (@options) = @_; # Options for task
7168 shift @options while @options && ref $options[0]; # Remove any leading references to find the actual string or file to be parsed
7169 my %options = @options;
7170 checkKeys(\%options, # Check options
7171 {title =>q(Title of the task),
7172 });
7173  
7174 my $title = $options{title} // "Title unknown";
7175 my $task = new(<<END);
7176 <task>
7177 <title id="title">$title</title>
7178 <taskbody>
7179 <context/>
7180 <steps/>
7181 <result/>
7182 </taskbody>
7183 </task>
7184 END
7185 $task->createGuidId;
7186 $task
7187 }
7188  
7189 sub ditaSampleBookMap(%) #S Sample bookmap
7190 {my (@options) = @_; # Options for bookmap
7191  
7192 shift @options while @options && ref $options[0]; # Remove any leading references to find the actual string or file to be parsed
7193 my %options = @options;
7194 checkKeys(\%options, # Check bookmap options
7195 {appendices=>q(Appendices),
7196 author =>q(Author of the document),
7197 chapters =>q(Chapter and topicrefs),
7198 metadata =>q(Meta data),
7199 notices =>q(Name of file containing notices),
7200 title =>q(Title of the document),
7201 year =>q(Copyright year),
7202 });
7203  
7204 my $author = sub # Author
7205 {my $a = $options{author};
7206 return qq(<author>$a</author>) if $a;
7207 q(<author/>)
7208 }->();
7209  
7210 my $title = sub # Title
7211 {my $t = $options{title};
7212 return qq(<mainbooktitle>$t</mainbooktitle>) if $t;
7213 q(<mainbooktitle/>)
7214 }->();
7215  
7216 my $year = sub # Year
7217 {my $y = $options{year};
7218 return qq(<year>$y</year>) if $y;
7219 q(<year/>)
7220 }->();
7221  
7222 my $chapters = sub
7223 {my $c = $options{chapters};
7224 return '' unless $c;
7225 return -p $c if ref($c);
7226 $c
7227 }->();
7228  
7229 my $appendices = sub
7230 {my $c = $options{appendices};
7231 return '' unless $c;
7232 return -p $c if ref($c);
7233 $c
7234 }->();
7235  
7236 my $notices = sub
7237 {my $n = $options{notices};
7238 # return ' <notices/>' unless $n;
7239 return ' <notices/>' unless $n;
7240 qq(<notices href="$n" navtitle="Notices"/>)
7241 }->();
7242  
7243 my $metadata = sub
7244 {my $m = $options{metadata};
7245 return '' unless $m;
7246 qq(<metadata>$m</metadata>\n)
7247 }->();
7248  
7249 my $bookMap = new(<<END); # Sample bookmap
7250 <bookmap>
7251 <booktitle>
7252 $title
7253 </booktitle>
7254 <bookmeta>
7255 <shortdesc/>
7256 $author
7257 <source/>
7258 $metadata
7259 <category/>
7260 <keywords>
7261 <keyword/>
7262 </keywords>
7263 <prodinfo>
7264 <prodname product=""/>
7265 <vrmlist>
7266 <vrm version=""/>
7267 </vrmlist>
7268 <prognum/>
7269 <brand/>
7270 </prodinfo>
7271 <bookchangehistory>
7272 <approved>
7273 <revisionid/>
7274 </approved>
7275 </bookchangehistory>
7276 <bookrights>
7277 <copyrfirst>
7278 $year
7279 </copyrfirst>
7280 <bookowner/>
7281 </bookrights>
7282 </bookmeta>
7283 <frontmatter>
7284 $notices
7285 <booklists>
7286 <toc/>
7287 </booklists>
7288 <preface/>
7289 </frontmatter>
7290 $chapters
7291 <appendices>
7292 $appendices
7293 </appendices>
7294 <reltable>
7295 <relheader>
7296 <relcolspec/>
7297 <relcolspec/>
7298 </relheader>
7299 <relrow>
7300 <relcell/>
7301 <relcell/>
7302 </relrow>
7303 <relrow>
7304 <relcell/>
7305 <relcell/>
7306 </relrow>
7307 </reltable>
7308 </bookmap>
7309 END
7310 $bookMap->createGuidId; # Id for bookmap
7311 $bookMap
7312 }
7313  
7314 sub isADitaMap($) #U Return the specified B<$node> if this node is a L<Dita> map else return B<undef>
7315 {my ($node) = @_; # Node to test
7316 $node->tag =~ m(map\Z) ? $node : undef # Map
7317 }
7318  
7319 sub topicTypeAndBody($) #P Topic type and corresponding body.
7320 {my ($type) = @_; # Type from qw(bookmap concept reference task)
7321 return qw(bookmap BookMap) if $type =~ /\Abookmap/i;
7322 return qw(concept Concept conbody) if $type =~ /\Aconcept/i;
7323 return qw(glossentry Glossary glossentry) if $type =~ /\Aglossentry/i;
7324 return qw(map Map) if $type =~ /\Amap/i;
7325 return (q(map), q(Subject Scheme Map)) if $type =~ /\AsubjectScheme/i;
7326 return qw(reference Reference refbody) if $type =~ /\Areference/i;
7327 return qw(task Task taskbody) if $type =~ /\Atask/i;
7328 return qw(topic Topic body) if $type =~ /\Atopic/i;
7329 return qw(unknown Unknown unknown);
7330 confess "Unknown document type: $type\n";
7331 }
7332  
7333 sub ditaRoot($) #U Return the specified B<$node> if it a L<Dita> root node else return B<undef>.
7334 {my ($node) = @_; # Node to check
7335 return $node if $node->tag =~
7336 m(\A(bookmap|concept|glossentry|map|subjectScheme|reference|task|topic)\Z)s;
7337 }
7338  
7339 sub ditaTopicHeaders($;$) #U Add L<XML> headers for the dita document type indicated by the specified L<parse|/parse> tree
7340 {my ($node, $String) = @_; # Node in parse tree, suffix string
7341 my $string = $String // q();
7342 my $parse = $node->parser;
7343 my $t = $parse->tag;
7344 my ($n, $N) = topicTypeAndBody $t;
7345 my $r = xmlHeader(<<END) =~ s(\s*\Z) (\n)sr;
7346 <!DOCTYPE $t PUBLIC "-//OASIS//DTD DITA $N//EN" "$n.dtd" []>
7347 $string
7348 END
7349 $r
7350 }
7351  
7352 sub ditaPrettyPrintWithHeaders($) #U Add L<XML> headers for the dita document type indicated by the specified L<parse|/parse> tree to a pretty print of the parse tree.
7353 {my ($node) = @_; # Node in parse tree
7354 my $s = -p $node;
7355  
7356 if ($node->isADitaMap and $s =~ m(<topicsubject)i) # An exception to the general rule
7357 {return xmlHeader <<END.$s
7358 <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Classification Map//EN" "classifyMap.dtd">
7359 END
7360 }
7361  
7362 $node->ditaTopicHeaders($s);
7363 }
7364  
7365 #sub ditaFindFirstFailure($@) #U Return the first node that fails to conform to the L<Dita> standard starting at the specified B<$node>. Return B<undef> if no failing node was found.
7366 # {my ($node, @context) = @_; # Node, optional context
7367 # return undef if @context and !$node->at(@context); # Not in specified context
7368 #
7369 # my $r = Dita::Validate::firstFailure($node); # Validate node along path from parent
7370 # return $r if $r; # Specified node is invalid
7371 # for my $n($node->contents) # Check children
7372 # {my $r = Dita::Validate::firstFailure($n); # Validate child
7373 # return $r if $r; # Return invalid child node
7374 # }
7375 # undef # No failing node found
7376 # }
7377 ###a
7378 ###b <concept><title/><conbody><p/><q/></conbody></concept>
7379 ###c atTop
7380 ###c ditaFindFirstFailure
7381 ###c set id failed
7382 ###d Find the first failing node
7383  
7384 sub ditaCutTopicmetaFromAClassificationMap($@) #U Remove a topicmeta node from a classification map. Dita::Validate was built from conventional maps and so does not recognize all the situations where topicmeta is invalid in a classification map
7385 {my ($node, @context) = @_; # Node, optional context
7386 return undef if @context and !$node->at(@context); # Not in specified context
7387  
7388 if (@context and $context[0]=~ m(topicmeta)i) # Pending DTD parsing we have to do this manually
7389 {if ($node->isAllBlankText and !$node->isFirst and !$node->prev_title)
7390 {$node->unwrap;
7391 }
7392 return $node;
7393 }
7394 undef
7395 }
7396  
7397 #sub ditaCutIfEmptyAndFirstFailingChild($@) #U Remove this node if is in the specified optional context, empty and the first child under its parent which fails to conform to the L<Dita> standard. Return $node if the node is valid else B<undef>.
7398 # {my ($node, @context) = @_; # Node, optional context
7399 # return undef if @context and !$node->at(@context); # Not in specified context
7400 #
7401 # my $r = Dita::Validate::validateChild($node); # Validate node along path from parent
7402 # if ($r == 0) { return undef} # Not a Dita node
7403 # elsif ($r == 1) { return undef} # Not reachable
7404 # elsif ($r == 2) {$node->cutIfEmpty; return undef} # Reachable but in error: cut if empty, stop the PCD
7405 # else { return $node} # Reachable and valid
7406 # }
7407 ##a
7408 ##b <concept><title/><p/></concept>
7409 ##c ditaCutIfEmptyAndFirstFailingChild p
7410 ##d Remove first empty child that fails to conform to Dita.
7411  
7412 sub ditaAddTopicReport($$) # Place a report into a dita topic using required clean up
7413 {my ($tree, $report) = @_; # Topic, report
7414 $tree->downToDie(sub
7415 {my ($o) = @_;
7416 if ($o->at_conbody)
7417 {$o->putFirstRequiredCleanUp($report);
7418 die;
7419 }
7420 elsif ($o->at_refbody)
7421 {my $c = $o->addFirst_section;
7422 $c->putFirstRequiredCleanUp($report);
7423 die;
7424 }
7425 elsif ($o->at_taskbody)
7426 {my $c = $o->addFirst_context;
7427 $c->putFirstRequiredCleanUp($report);
7428 die;
7429 }
7430 });
7431 }
7432  
7433 our $defaultBrowser; # Name of default browser executable
7434 our $defaultEditorHelp = # Editor help Url
7435 q(https://philiprbrenan.github.io/data_edit_xml_edit_commands.html);
7436  
7437 sub help($) #U Get help for a node and the editor
7438 {my ($node) = @_; # Node
7439 my $t = -t $node; # Node in question
7440 my $l = substr($t, 0, 1); # Index page
7441 my $u = qq(http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/contentmodels/cmlt${l}.html#cmlt${l}__$t);
7442 return $u unless $defaultBrowser; # Return the url unless we have a default browser
7443 qx($defaultBrowser $u & $defaultBrowser $defaultEditorHelp &) # Display url in default browser
7444 }
7445  
7446 BEGIN{*h=*help}
7447  
7448 #D2 Html and word conversions # Methods useful for converting Word and L<Html> to L<Dita>
7449  
7450 sub htmlHeadersToSections($) #U Position sections just before html header tags so that subsequently the document can be divided into L<sections|/divideDocumentIntoSections>.
7451 {my ($tree) = @_; # Parse tree
7452  
7453 $tree->by(sub # Move each section definition upwards so that its parent is another section. Intervening container tags such as <div> or <span> should have been unwrapped by this point as they might move the section further back than is desired.
7454 {my ($o) = @_;
7455 if ($o->tag =~ m(\Ah(\d)\Z)i)
7456 {my $level = $1;
7457 $o->putPrev($o->newTag(q(section), level=>$level));
7458 }
7459 });
7460 }
7461  
7462 sub getSectionHeadingLevel($) #UP Get the heading level from a section tag.
7463 {my ($o) = @_; # Node
7464 return undef unless $o->at(qq(section));
7465 $o->attr(qq(level))
7466 }
7467  
7468 sub unwrapSingleParentsOfSection($) #UP Unwrap single parents of section: in word documents the header is often buried in a list to gain a section number - here we remove these unnecessary items
7469 {my ($tree) = @_; # Parse tree
7470  
7471 $tree->by(sub
7472 {my ($o) = @_;
7473 if ($o->at(qq(section)))
7474 {$o->unwrapParentsWithSingleChild;
7475 }
7476 });
7477 }
7478  
7479 sub extendSectionToNextSection($) #UP Extend a section tag until it meets the next section tag
7480 {my ($tree) = @_; # Parse tree
7481  
7482 $tree->by(sub # Place each non heading node in its corresponding heading node
7483 {my ($o) = @_;
7484 if (my $h = getSectionHeadingLevel($o))
7485 {while(my $n = $o->next)
7486 {last if getSectionHeadingLevel($n);
7487 $n->cut;
7488 $o->putLast($n);
7489 }
7490 }
7491 });
7492 }
7493  
7494 sub structureAdjacentSectionsByLevel($) #UP Structure adjacent sections by level
7495 {my ($tree) = @_; # Parse tree
7496  
7497 $tree->by(sub # Place each sub section in its containing section
7498 {my ($o) = @_;
7499 if (my $h = getSectionHeadingLevel($o))
7500 {while(my $n = $o->next)
7501 {my $i = getSectionHeadingLevel($n);
7502 last if !defined($i) or $i <= $h;
7503 $o->putLast($n->cut);
7504 }
7505 }
7506 });
7507 }
7508  
7509 sub divideDocumentIntoSections($$) # Divide a L<parse|/parse> tree into sections by moving non B<section> tags into their corresponding B<section> so that the B<section> tags expand until they are contiguous. The sections are then cut out by applying the specified sub to each B<section> tag in the L<parse|/parse> tree. The specified sub will receive the containing B<topicref> and the B<section> to be cut out as parameters allowing a reference to the cut out section to be inserted into the B<topicref>.
7510 {my ($node, $cutSub) = @_; # Parse tree, cut out sub
7511  
7512 $node->unwrapSingleParentsOfSection; # In word documents the header is often buried in a list to gain a section number - here we remove these unnecessary items
7513 $node->extendSectionToNextSection; # Place each non heading node in its corresponding heading node
7514 $node->structureAdjacentSectionsByLevel; # Place each sub section in its containing section
7515  
7516 $node->by(sub # Wrap each section in topicrefs
7517 {my ($o) = @_;
7518 if ($o->at(qq(section)))
7519 {my $t = $o->wrapWith(q(topicref)); # Topic ref
7520 $t->putLast($_->cut) for $o->c(q(topicref)); # Move topics out of section into containing topic
7521 };
7522 });
7523  
7524 $node->by(sub # Cut out each section
7525 {my ($o, $p) = @_;
7526 if ($o->at(qq(section)))
7527 {$p->at(q(topicref)) or confess "Section not in topicref";
7528 $cutSub->($p, $o);
7529 }
7530 });
7531 }
7532  
7533 sub divideHtmlDocumentIntoSections($) #U Divide a L<parse|/parse> tree representing an html document into sections based on the heading tags.
7534 {my ($tree) = @_; # Parse tree
7535 $tree->htmlHeadersToSections;
7536 $tree->extendSectionToNextSection; # Place each non heading node in its corresponding heading node
7537 $tree->structureAdjacentSectionsByLevel; # Place each sub section in its containing section
7538 $tree->by(sub{$_->change(q(title), qr(\Ah\d\Z)i)}); # Move each section definition upwards so that its parent is another section. Intervening container tags such as <div> or <span> should have been unwrapped by this point as they might move the section further back than is desired.
7539 $tree->by(sub{$_->renameAttr_level_outputclass if $_->at_section}); # Change level to outputclass
7540 }
7541  
7542 sub ditaParagraphToNote($;$) #U Convert all <p> nodes to <note> if the paragraph starts with 'Note:', optionally wrapping the content of the <note> with a <p>
7543 {my ($node, $wrapNoteContentWithParagaph) = @_; # Parse tree, wrap the <note> content with a <p> if true
7544 my $count = 0; # Count the number of changes
7545 $node->by(sub # Each node
7546 {my ($o, $p) = @_; # Text, p
7547 if ($o->isText_p) # Text under p
7548 {if ($o->text =~ m(\A\s*(Attention|Caution|Danger|Fastpath|Important|Notices?|Notes?|Remember|Restriction|Tip|Trouble|Warning)\s*:?\s*)i) # Note
7549 {my $note = $1;
7550 $p->change(q(note)); # Change to note
7551 $p->wrapContentWith(q(p)) if $wrapNoteContentWithParagaph; # Wrap content if required
7552 $o->text =~ s(\A\s*$note\s*:?\s*) ()i; # Remove note text
7553 $o->text = ucfirst($o->text); # Uppercase leading character
7554 $note =~ s(s\Z) ()gs; # Remove optional trailing s
7555 $p->set(type=>lc $note) unless $note =~ m(\Anote\Z)is; # Set type
7556 ++$count;
7557 }
7558 }
7559 });
7560 $count
7561 }
7562  
7563 sub wordStyles($) #U Extract style information from a parse tree representing a word document.
7564 {my ($x) = @_; # Parse tree
7565 my $styles; # Styles encountered
7566 $x->by(sub # Each node
7567 {my ($o, $p) = @_;
7568 if ($o->at(qw(text:list-level-style-bullet text:list-style))) # Bulleted lists
7569 {my ($level, $name) = ($o->attr(q(text:level)), $p->attr(q(style:name)));
7570 if ($level and $name)
7571 {$styles->{bulletedList}{$name}{$level}++;
7572 }
7573 }
7574 });
7575 $styles # Return styles encountered
7576 }
7577  
7578 sub htmlTableToDita($) #U Convert an L<html table> to a L<Dita> table.
7579 {my ($table) = @_; # Html table node
7580  
7581 $table->wrapContentWith(q(tgroup)); # tgroup
7582 my %transforms = # Obvious transformations
7583 (td=>q(entry),
7584 th=>q(entry),
7585 tr=>q(row),
7586 );
7587  
7588 $table->by(sub
7589 {if (my $c = $transforms{-t $_}) {$_->change($c)}
7590 });
7591  
7592 my $N = 0; # Number of columns in widest row
7593 $table->by(sub
7594 {my ($r, undef, $group, $Table) = @_;
7595 if ($r->at(qw(row), undef, qw(tgroup table)) and $Table == $table) # In this table, not in an embedded sub table
7596 {my $n = $r->c(q(entry));
7597 $N = $n if $n > $N;
7598 }
7599 });
7600  
7601 $table->by(sub # Fix colspecs
7602 {my ($group, $Table) = @_;
7603 if ($group->at(qw(tgroup table)) and $Table == $table) # In this table, not in an embedded sub table
7604 {$group->setAttr (q(cols), $N);
7605 $_->unwrap for $group->c(q(colspec));
7606 $group->putFirst($group->newTag # Insert colspecs
7607 (qw(colspec colname), qq(c$_), q(colnum), $_, qw(colwidth 1*)))
7608 for reverse 1..$N;
7609 }
7610 });
7611  
7612 $table->by(sub # Span last element of each row to fill row
7613 {my ($r, undef, $group, $Table) = @_;
7614 if ($r->at(qw(row), undef, qw(tgroup table)) and $Table == $table)
7615 {my @e = $r->c(q(entry));
7616 my $n = @e;
7617 $e[-1]->setAttr(namest=>qq(c$n), nameend=>qq(c$N)) if @e < $N;
7618 }
7619 });
7620 }
7621  
7622 sub ditaSyntaxDiagramFromDocBookCmdSynopsis($) #U Convert doc book cmdsynopsis to Dita syntax diagram
7623 {package ditaSyntaxDiagramFromDocBookCmdSynopsis; # Allows us to package the entire conversion as one method
7624 use Carp;
7625 my ($x) = @_; # Parse tree
7626  
7627 sub command {q(command)} # Constants encountered
7628 sub ellipsis {q(<sep>&#x2026;</sep>)}
7629 sub importance{q(importance)}
7630 sub opt {q(opt)}
7631 sub optional {q(optional)}
7632 sub plain {q(plain)}
7633 sub rep {q(rep)}
7634 sub req {q(req)}
7635 sub repeat {q(repeat)}
7636 sub required {q(required)}
7637  
7638 sub ditaOptional($) # Return the specified B<$node> if it is optional else return B<undef>.
7639 {my ($node) = @_; # Node to test
7640 return $node if $node->attrX_importance eq optional;
7641 undef
7642 }
7643  
7644 sub ditaNonOptionalGroupSeq($) # Return the specified B<$node> if it is group sequence but not optional else return B<undef>.
7645 {my ($node) = @_; # Node to test
7646 return $node if $node->at_groupseq and !ditaOptional($node);
7647 undef
7648 }
7649  
7650 sub ditaOptionalGroupChoice($) # Return the specified B<$node> if it is a group choice and optional else return B<undef>.
7651 {my ($node) = @_; # Node to test
7652 return $node if $node->at_groupchoice and ditaOptional($node);
7653 undef
7654 }
7655  
7656 sub ditaRepeated($) # Return the specified B<$node> if it is repeated else return B<undef>.
7657 {my ($node) = @_; # Node to test
7658 if (my $s = $node->last_seq)
7659 {if ($s->string eq ellipsis)
7660 {return $node;
7661 }
7662 }
7663 undef
7664 }
7665  
7666 sub docBookChoiceAttribute($) # Return the value of the B<choice> attribute of the B<arg> or B<group> specified by B<$node> if we are on a B<arg> or B<group> node else confess.
7667 {my ($node) = @_; # Node to test
7668 $node->at_arg || $node->at_group or
7669 confess "Not an arg or group node".-A $node;
7670 $node->attrX_choice
7671 }
7672  
7673 $x->by(sub
7674 {my ($o, $p) = @_;
7675  
7676 if ($o->at_cmdsynopsis) # cmdsynopsis
7677 {$o->change_syntaxdiagram__wrapContentWith_groupseq;
7678 $o->renameAttr(qw(xml:id id));
7679 }
7680  
7681 if ($o->at_command) # command
7682 {$o->change_kwd;
7683 $o->outputclass = command;
7684 }
7685  
7686 $o->change_var_replaceable; # replaceable
7687  
7688 if ($o->isText_arg) # Text under arg becomes kwd
7689 {$o->wrapWith_kwd
7690 }
7691  
7692 if ($o->at_arg) # arg
7693 {my $c = docBookChoiceAttribute($o);
7694  
7695 if (!$c or $c eq opt) # Choice
7696 {$o->set(importance=>optional);
7697 $o->change_groupseq;
7698 }
7699 elsif ($c eq plain)
7700 {$o->change_groupseq;
7701 }
7702 elsif ($c eq q(req))
7703 {$o->change_groupchoice;
7704 }
7705 else
7706 {confess "Unprogrammed arg choice=$c\n";
7707 }
7708  
7709 if (my $r = $o->attr_rep) # Repetition
7710 {if ($r eq repeat)
7711 {$o->putLastAsTree(ellipsis);
7712 $o->wrapContentWith_groupseq unless $o->at_groupseq; # PS2-658 - wrap the repeated sequence unless it is already wrapped
7713 }
7714 }
7715  
7716 $o->deleteAttrs_choice_rep; # Attributes processed
7717 }
7718  
7719  
7720 # Brackets are used to distinguish between optional, required, or plain arguments. Usually square brackets are placed around optional arguments, [-f | -g], and curly brackets are placed around required arguments, {-f | -g}. Plain arguments are required, but are not decorated with brackets.
7721  
7722 if ($o->at_group) # group
7723 {my $c = docBookChoiceAttribute($o);
7724  
7725 if (!$c or $c eq opt) # Choice
7726 {$o->set(importance=>optional);
7727 $o->change_groupchoice;
7728 }
7729 elsif ($c eq plain)
7730 {$o->change_groupseq;
7731 }
7732 elsif ($c eq req)
7733 {$o->change_groupchoice;
7734 }
7735 else
7736 {confess "Unprogrammed group choice=$c\n";
7737 }
7738  
7739 if (my $r = $o->attr_rep) # Repetition
7740 {if ($r eq repeat)
7741 {$o->putLastAsTree(ellipsis);
7742 $o->wrapContentWith_groupseq unless $o->at_groupseq; # PS2-658 - wrap the repeated sequence unless it is already wrapped
7743 }
7744 }
7745  
7746 $o->deleteAttrs_choice_rep; # Attributes processed
7747 }
7748 });
7749  
7750 for(1..9) # Flatten the syntax diagram where possible
7751 {my $w = 0;
7752  
7753 $x->by(sub # Consolidate groups with only one item in them
7754 {my ($k, $g) = @_;
7755 if ($k->isOnlyChild(qr(\A(kwd|var)\Z), qr(\A(groupseq|groupchoice)\Z)))
7756 {$g->unwrap; ++$w;
7757 if (ditaOptional($g)) # If group is optional then the child must be optional
7758 {$k->set(importance=>optional);
7759 }
7760 }
7761 });
7762  
7763 $x->by(sub # group sequence single child of group choice importance=optional goes to group sequence importance=optional
7764 {my ($s, $c) = @_;
7765 if ($s->isOnlyChild_groupseq_groupchoice)
7766 {if (ditaOptional($c))
7767 {if (!ditaRepeated($s))
7768 {$c->unwrap; ++$w;
7769 $s->set(importance=>optional); # The wrapping choice forces this seq to be optional
7770 }
7771 }
7772 }
7773 });
7774  
7775 $x->by(sub # A non optional group sequence under a non optional group sequence can be unwrapped
7776 {my ($s, $t) = @_;
7777 if ($s->at_groupseq_groupseq)
7778 {if (ditaNonOptionalGroupSeq($s))
7779 {if (ditaNonOptionalGroupSeq($t))
7780 {if (!ditaRepeated($s))
7781 {$s->unwrap; ++$w;
7782 }
7783 }
7784 }
7785 }
7786 });
7787  
7788 $x->by(sub # An only child group choice under a non optional group sequence: unwrap the group sequence as unnecessary
7789 {my ($c, $s) = @_;
7790 if ($c->isOnlyChild_groupchoice_groupseq)
7791 {if (ditaNonOptionalGroupSeq($s))
7792 {$s->unwrap; ++$w;
7793 }
7794 }
7795 });
7796  
7797 $x->by(sub # An only child group choice under a non optional group sequence: unwrap the group sequence as unnecessary
7798 {my ($c, $d) = @_;
7799 if ($c->isOnlyChild_groupchoice_groupchoice)
7800 {if ($c->attrX_importance eq $d->attrX_importance)
7801 {$c->unwrap; ++$w;
7802 }
7803 elsif (ditaOptionalGroupChoice($c))
7804 {$d->unwrap; ++$w;
7805 }
7806 elsif (ditaOptionalGroupChoice($d))
7807 {$c->unwrap; ++$w;
7808 }
7809 }
7810 });
7811  
7812 $x->by(sub # group sequence importance=optional under group choice importance=optional: remove importance from group sequence as it is redundant and leads to over bracketing
7813 {my ($s, $c) = @_;
7814 if ($c and $c->at_groupchoice)
7815 {if (ditaOptional($c) and ditaOptional($s))
7816 {$s->deleteAttrs_importance;
7817 }
7818 }
7819 });
7820  
7821 $x->by(sub # importance=required always produces the same results as importance=>undef in the html5 transformation so we assume that it can be safely removed
7822 {my ($o) = @_;
7823 if ($o->attrX_importance eq required)
7824 {$o->deleteAttr_importance;
7825 }
7826 });
7827  
7828 last unless $w;
7829 }
7830  
7831 $x
7832 } # ditaSyntaxDiagramFromDocBookCmdSynopsis
7833  
7834 sub ditaSyntaxDiagramToBasicRepresentation($) #U Convert Dita syntax diagrams into Micaela's Basic Version.
7835 {my ($x) = @_; # Parse tree
7836  
7837 $x->down(sub
7838 {my ($o, $p) = @_;
7839  
7840 my $i = $o->attrX_importance; # Add brackets
7841 if ($o->at_groupchoice) # Group choice has brackets and separators
7842 {if ($i eq q(optional))
7843 {$o->putPrevAsText(q( [));
7844 $o->putNextAsText(q(] ));
7845 }
7846 else
7847 {$o->putPrevAsText(q( {));
7848 $o->putNextAsText(q(} ));
7849 }
7850 my ($c, @c) = @$o;
7851 $_->putPrevAsText(q( | )) for @c;
7852 }
7853 elsif ($i eq q(optional)) # Non group choice just has square brackets
7854 {$o->putPrevAsText(q( [));
7855 $o->putNextAsText(q(] ));
7856 }
7857  
7858 if ($o->at_syntaxdiagram) # Map tags
7859 {$o->change_p;
7860 $o->outputclass = q(syntaxdiagram);
7861 }
7862 elsif ($o->at_kwd and $o->outputclassX eq q(command))
7863 {$o->change_cmdname;
7864 }
7865 elsif ($o->at_kwd)
7866 {$o->change_codeph;
7867 }
7868 elsif ($o->at_var)
7869 {$o->change_userinput;
7870 }
7871 elsif ($o->at_sep)
7872 {$o->change_codeph;
7873 }
7874 elsif ($o->at_groupseq or $o->at_groupchoice)
7875 {$o->unwrap;
7876 }
7877  
7878 $o->deleteAttrs_outputclass_importance;
7879  
7880 });
7881  
7882 } # ditaSyntaxDiagramToBasicRepresentation
7883  
7884 sub ditaUnderPNotConbody #P Return a hash of items that L<Dita> permits under B<p> but not directly under B<conbody>
7885 {{
7886 "abbreviated-form" => 1,
7887 "apiname" => 1,
7888 "b" => 1,
7889 "boolean" => 1,
7890 "CDATA" => 1,
7891 "cite" => 1,
7892 "cmdname" => 1,
7893 "codeph" => 1,
7894 "equation-inline" => 1,
7895 "filepath" => 1,
7896 "fn" => 1,
7897 "i" => 1,
7898 "indexterm" => 1,
7899 "indextermref" => 1,
7900 "keyword" => 1,
7901 "line-through" => 1,
7902 "markupname" => 1,
7903 "menucascade" => 1,
7904 "msgnum" => 1,
7905 "msgph" => 1,
7906 "numcharref" => 1,
7907 "option" => 1,
7908 "overline" => 1,
7909 "parameterentity" => 1,
7910 "parmname" => 1,
7911 "ph" => 1,
7912 "q" => 1,
7913 "state" => 1,
7914 "sub" => 1,
7915 "sup" => 1,
7916 "synph" => 1,
7917 "systemoutput" => 1,
7918 "term" => 1,
7919 "text" => 1,
7920 "textentity" => 1,
7921 "tm" => 1,
7922 "tt" => 1,
7923 "u" => 1,
7924 "uicontrol" => 1,
7925 "userinput" => 1,
7926 "varname" => 1,
7927 "wintitle" => 1,
7928 "xmlatt" => 1,
7929 "xmlelement" => 1,
7930 "xmlnsname" => 1,
7931 "xmlpi" => 1,
7932 "xref" => 1,
7933 }} # ditaUnderPNotConbody
7934  
7935 sub ditaWrapWithPUnderConbody($) #U Wrap items immediately under L<DITA> B<conbody> with B<p> or merge with any previous B<p> if the item in question does not fit under B<conbody> but does fit under B<p>. Return the current node if it is B<conbody> else return B<undef>.
7936 {my ($conbody) = @_; # Section
7937 $conbody->at_conbody or confess "Not a conbody, its a ". -t $conbody; # Check we are on a conbody
7938 my $fit = ditaUnderPNotConbody; # Tags that need to be wrapped with B<p> if they occur directly under B<conbody>.
7939 my $p; # Last p encountered
7940 my @c = @$conbody; # Each direct child of conbody
7941 for my $c(@c) # Each direct child of conbody
7942 {if ($$fit{-t $c}) # Better as a p
7943 {if ($p) # Prior tag is p
7944 {$p->putLastCut($c); # Merge
7945 }
7946 else # Start new p
7947 {$p = $c->wrapWith_p; # Wrap with p and make new p
7948 }
7949 }
7950 elsif ($c->at_p) # Tag is p - so make it the last p
7951 {$p = $c; # P tag becomes last p
7952 }
7953 else # Not on a p and not better wrapped in p
7954 {$p = undef; # New p required
7955 }
7956 }
7957 }
7958  
7959 #D1 PCD # Please Change Dita Language Features
7960  
7961 our %savedNodes; #E Hash of saved nodes
7962  
7963 sub putNodeAs($$@) #CU Return the specified B<$node> after saving it under the specified B<$name> if we are in the optional B<@context>.
7964 {my ($node, $name, @context) = @_; # Node, save name, optional context
7965 return $node if @context and !$node->at(@context); # Not in specified context
7966 $savedNodes{$name} = $node; # Save a reference to the node under the specified name and return the current node
7967 }
7968  
7969 BEGIN{*put=*putNodeAs}
7970  
7971 sub getNodeAs($$@) #CU Return the specified B<$node> unless it is possible to return the node saved with L<putNodeAs> under the specified B<name> and we are optionally in the specified B<@context>.
7972 {my ($node, $name, @context) = @_; # Default node, name of saved node, optional context
7973 return $node if @context and !$node->at(@context); # Not in specified context
7974 $savedNodes{$name} // $node; # Return saved node defaulting to current node
7975 }
7976  
7977 BEGIN{*get=*getNodeAs}
7978  
7979 sub reportNodeAttributes($$@) #CU Print the attributes of the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
7980 {my ($node, $label, @context) = @_; # Node node, label, optional context
7981 return '' if @context and !$node->at(@context); # Not in specified context
7982 join ' ', $label, $node->printAttributes; # Print label and attributes
7983 }
7984  
7985 BEGIN{*rna=*reportNodeAttributes}
7986  
7987 sub reportNodeContext($$@) #CU Print the context of the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
7988 {my ($node, $label, @context) = @_; # Node node, label, optional context
7989 return '' if @context and !$node->at(@context); # Not in specified context
7990 join ' ', $label, $node->context; # Print label and context
7991 }
7992  
7993 BEGIN{*rnc=*reportNodeContext}
7994  
7995 sub reportNode($$@) #CU Print the parse tree starting at the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
7996 {my ($node, $label, @context) = @_; # Node node, label, optional context
7997 return '' if @context and !$node->at(@context); # Not in specified context
7998 join '', $label, "\n", $node->prettyString; # Print label and parse tree
7999 }
8000  
8001 BEGIN{*rn=*reportNode}
8002  
8003 #D1 Debug # Debugging methods
8004  
8005 sub sss($@) #U Put, after the current B<$node>, the specified B<@text> and return the current $node.
8006 {my ($node, @text) = @_; # Node, text
8007 my $text = join ' ', @text; # Text to insert
8008 $node->putNextAsText($text); # Insert text after current node
8009 $node
8010 }
8011 #a
8012 #b <b><c><d/></c></b>
8013 #c at d c
8014 #c sss we reached here
8015 #d Say something special so we can see where we were.
8016  
8017 sub printAttributes($) #U Print the attributes of a node.
8018 {my ($node) = @_; # Node whose attributes are to be printed.
8019 return q() unless keys %{$node->attributes}; # No attributes
8020  
8021 my %a = %{$node->attributes}; # Attributes
8022 my $s = '';
8023 for(sort keys %a) # Each attribute
8024 {next unless defined(my $v = $a{$_});
8025 $s .= $_.'="'.$v.'" '; # Attributes enclosed in "" in alphabetical order
8026 }
8027 chop($s);
8028 length($s) ? ' '.$s : '';
8029 }
8030  
8031 sub printAttributesHtml($) #U Print the attributes of a node as html.
8032 {my ($node) = @_; # Node whose attributes are to be printed.
8033 return q() unless keys %{$node->attributes}; # No attributes
8034  
8035 my %a = %{$node->attributes}; # Attributes
8036 my $s = '';
8037 for(sort keys %a) # Each attribute
8038 {next unless defined(my $v = $a{$_}); # Attributes enclosed in "" in alphabetical order
8039 $s .= qq(<span class="xmlAttr">$_</span>).
8040 qq(<span class="xmlEquals">=</span>).
8041 qq(<span class="xmlValue">"$v"</span> );
8042 }
8043 chop($s);
8044 length($s) ? ' '.$s : '';
8045 }
8046  
8047 sub printStack($@) #UC Print the attributes of a node and each of its parents
8048 {my ($node, @context) = @_; # Node whose attributes are to be printed, optional context.
8049 return undef if @context and !$node->at(@context); # Not in specified context
8050  
8051 my @s; # Resulting text
8052 my @p = reverse $node->ancestry; # Each ancestor
8053 for my $i(keys @p) # Print and indent
8054 {my $p = $p[$i];
8055 push @s, q( )x$i.$p->printNode; # Print node with indentation
8056 }
8057 join "\n", @s, ''; # Return ancestry
8058 }
8059  
8060 sub printNode($@) #UC Print the tag and attributes of a node.
8061 {my ($node, @context) = @_; # Node whose attributes are to be printed, optional context.
8062 return undef if @context and !$node->at(@context); # Not in specified context
8063 my %a = %{$node->attributes}; # Attributes
8064 my $t = $node->tag; # Tag
8065 my $s = ''; # Attributes string
8066 for(sort keys %a) # Each attribute
8067 {next unless defined(my $v = $a{$_}); # Each defined attribute
8068 $s .= qq( ${_}="$v"); # Attributes enclosed in "" in alphabetical order
8069 }
8070 qq($t$s) # Result
8071 }
8072  
8073 sub printNodeAsSingleton($@) #UC Print the tag and attributes of a node as if it were a single node regardless of any child nodes it might have
8074 {my ($node, @context) = @_; # Node whose attributes are to be printed, optional context.
8075 return undef if @context and !$node->at(@context); # Not in specified context
8076 q(<).printNode($node).q(/>);
8077 }
8078  
8079 sub printAttributesReplacingIdsWithLabels($) #UP Print the attributes of a node replacing the id with the labels.
8080 {my ($node) = @_; # Node whose attributes are to be printed.
8081 my %a = %{$node->attributes}; # Clone attributes
8082 my %l = %{$node->labels}; # Clone labels
8083 delete $a{id}; # Delete id
8084 $a{id} = join ', ', sort keys %l if keys %l; # Replace id with labels in cloned attributes
8085 defined($a{$_}) ? undef : delete $a{$_} for keys %a; # Remove undefined attributes
8086 return '' unless keys %a; # No attributes
8087 my $s = ' '; $s .= $_.'="'.$a{$_}.'" ' for sort keys %a; chop($s); # Attributes enclosed in "" in alphabetical order
8088 $s
8089 }
8090  
8091 sub printAttributesExtendingIdsWithLabels($) #UP Print the attributes of a node extending the id with the labels.
8092 {my ($node) = @_; # Node whose attributes are to be printed.
8093 my %a = %{$node->attributes}; # Clone attributes
8094 my %l = %{$node->labels}; # Clone labels
8095 my $i = $a{id} ? $a{id}.q(, ) : q(); # Format id
8096 $a{id} = join '', $i, join ', ', sort keys %l if keys %l; # Extend id with labels in cloned attributes
8097 defined($a{$_}) ? undef : delete $a{$_} for keys %a; # Remove undefined attributes
8098 return '' unless keys %a; # No attributes
8099 my $s = ' '; $s .= $_.'="'.$a{$_}.'" ' for sort keys %a; chop($s); # Attributes enclosed in "" in alphabetical order
8100 $s
8101 }
8102  
8103 sub checkParentage($) #UP Check the parent pointers are correct in a L<parse|/parse> tree.
8104 {my ($x) = @_; # Parse tree.
8105 $x->by(sub
8106 {my ($o) = @_;
8107 for($o->contents)
8108 {my $p = $_->parent;
8109 $p == $o or confess "No parent: ". $_->tag;
8110 $p and $p == $o or confess "Wrong parent: ".$o->tag. ", ". $_->tag;
8111 }
8112 });
8113 }
8114  
8115 sub checkParser($) #UP Check that every node has a L<parse|/parse>r.
8116 {my ($x) = @_; # Parse tree.
8117 $x->by(sub
8118 {$_->parser or confess "No parser for ". $_->tag;
8119 $_->parser == $x or confess "Wrong parser for ". $_->tag;
8120 })
8121 }
8122  
8123 sub goFish($@) #U A debug version of L<go|/go> that returns additional information explaining any failure to reach the node identified by the L<path|/path>.\mReturns ([B<reachable tag>...], B<failing tag>, [B<possible tag>...]) where:\m=over\m=item B<reachable tag>\mthe path elements successfully traversed;\m=item B<failing tag>\mthe failing element;\m=item B<possible tag>\mthe possibilities at the point where the path failed if it failed else B<undef>.\m=back\mParameters:
8124 {my ($node, @path) = @_; # Node, search specification.
8125 my $p = $node; # Current node
8126 my @p; # Elements of the path successfully processed
8127 while(@path) # Position specification
8128 {my $i = shift @path; # Index name
8129 return ([@p], $i, [sort keys %{$p->indexes}]) unless $p; # There is no node of the named type under this node
8130 reindexNode($p); # Create index for this node
8131 my $q = $p->indexes->{$i}; # Index
8132 return ([@p], $i, [sort keys %{$p->indexes}]) unless defined $q; # Complain if no such index
8133 push @p, $i;
8134 if (@path) # Position within index
8135 {if ($path[0] =~ /\A([-+]?\d+)\Z/) # Numeric position in index from start
8136 {my $n = shift @path; # Next path item
8137 my $N = scalar(@$q); # Dimension of index
8138 return ([@p], $n, [0..$N]) unless defined($p = $q->[$n]); # Complain if no such index
8139 push @p, $n; # Save successfully processed index
8140 }
8141 elsif (@path == 1 and $path[0] =~ /\A\*\Z/) # Final index wanted
8142 {return [@p];
8143 }
8144 else {$p = $q->[0]} # Step into first sub node by default
8145 }
8146 else {$p = $q->[0]} # Step into first sub node by default on last step
8147 }
8148 [@p] # Success!
8149 }
8150  
8151 sub nn($) #P Replace new lines in a string with N to make testing easier.
8152 {my ($s) = @_; # String.
8153 $s =~ s/\n/N/gsr
8154 }
8155  
8156 #D1 Validation # Validate Xml
8157  
8158 sub checkAllPaths($) #S Create a representation of all the paths permitted in a block of L<xml>. The syntax of each line is a word representing an L<xml> tag followed by one of: tag B<1 * + ? -> with B<1> being the default and meaning that exactly one instance of this tag is required under its parent, B<*> meaning that zero or more such tags are permitted under its parent, B<+> meaning that one or more such tags are required under its parent, B<?> meaning that no more than one such tag is permitted under its parent, B<-> meaning that this is a leaf tag that can be missing or present just once under its parent. The remaining words on the line being treated as a comment describing the purpose of the tag. Tags that are not marked with B<-> are required to have either text under them if they are leaf tags. Tags marked with B<-> are boolean leafs and may not have any text or child tags under them. The children of a tag are listed on following lines with exactly two more spaces of indentation. This enables the validation of a block of non recursive L<xml> without having to resort to writing a complex L<DTD>.
8159 {my ($valid) = @_; # Path descriptions
8160 my %valid; # Perl representation of validating string
8161 my @stack; # Tag stack
8162 my @lines = split m/\n/, $valid; # Split into lines
8163  
8164 for my $i(keys @lines) # Each line
8165 {my $line = $lines[$i] =~ s(\s*#.*\Z) ()r; # Remove trailing comments
8166 next unless $line =~ m(\S); # Ignore blank lines
8167  
8168 my sub error(@) # Write an error message
8169 {confess join ' ', @_, 'on line:', $i + 1, "\n";
8170 };
8171  
8172 my $tag = $line =~ s(\A\s*) ()r; # Check indentation carefully as it shows the desired structure
8173 my $indent = length($line) - length($tag);
8174 $indent % 2 and error "Indentation is not even";
8175 my $indent2 = $indent / 2;
8176 $i == 0 and $indent != 0 and error "Indent is not zero";
8177 @stack+1 < $indent2 and error "Too much indentation";
8178  
8179 while(@stack) # Reduce the stack to the current level
8180 {if (@stack > $indent2)
8181 {pop @stack;
8182 next;
8183 }
8184 last;
8185 }
8186  
8187 my ($tagName, @words) = split m/\s+/, $tag; # Save tag on the tag stack
8188 push @stack, $tagName;
8189  
8190 my $count = sub # The count indicator optionally follows the tag
8191 {return 1 unless @words; # The default is just one and it is required
8192 my $c = shift @words;
8193 return $c if $c =~ m(\A[-1+*?]\Z)i; # Valid operators
8194 1
8195 }->();
8196  
8197 if (@stack > 1) # Element description
8198 {$valid{join ' ', @stack[1..$#stack]} =
8199 [$count, my $comment = join ' ', @words];
8200 }
8201 }
8202  
8203 my ($root) = @stack; # The root tag
8204  
8205 for my $a(sort keys %valid) # Create get methods
8206 {for my $b(sort keys %valid)
8207 {my $c = $valid{$b}[0]; # Count field
8208 my @b = split m/\s+/, $b;
8209 my $m = pop @b;
8210 if ($a eq join " ", @b or !@b) # Has children
8211 {my @m = ($root, @b);
8212 if (!isSubInPackage((join '::', @m), $m))
8213 {my $d = $c eq q(*) || $c eq q(+) ? q([]) : q/q()/; # Default return value
8214  
8215 my $s = join ' ', qq(sub), (join '::', @m, $m), qq({\$_[0]{$m} // $d});
8216 eval $s;
8217 if ($@)
8218 {confess join '', "Unable to create method: ",$a, q(::).qq($m\n$@\n);
8219 }
8220 }
8221 if (@b and $valid{$a}[0] eq q(-)) # Check that tags marked as boolean leaves do not have any children
8222 {confess <<END;
8223 Path: '$a' has been marked with '-' making it a boolean leaf yet it has
8224 a child: '$b' '$a'
8225 END
8226 }
8227 }
8228 }
8229 }
8230  
8231 \%valid
8232 } # checkAllPaths
8233  
8234 sub xmlToPerl($$) #S Parse some L<xml>, validate using a description recognized by L<checkAllPaths> and return the corresponding L<Perl> structure. Valid fields in the returned structure can be referenced via methods with the same names as their corresponding L<xml> tags. Tags marked with B<*> or B<+> in the description processed by L<checkAllPaths> result in arrays of children, whilst tags marked with B<1> or B<?> can be referenced directly.
8235 {my ($xml, $valid) = @_; # Xml represented as a string, Xml validating represented as a string
8236  
8237 my $xmlTree = Data::Edit::Xml::new($xml); # Xml parse tree
8238 my $validator = checkAllPaths($valid); # Create a validating string to check all the paths in the xml description of the system
8239 my $perl; # Perl representation of the Xml
8240  
8241 $xmlTree->by(sub # Traverse xml to build Perl data structure
8242 {my ($o) = @_;
8243 return if $o == $xmlTree;
8244  
8245 my @path = reverse @_; # Node path from root downwards
8246 shift @path; # Remove root tag as it is boiler plate
8247 pop @path if $o->isText; # Remove CDATA
8248 my $p = join ' ', map {-t $_} @path; # Tag path
8249  
8250 if (my $valid = $$validator{$p}[0]) # Details of this path
8251 {my @keys; # Path as text
8252 for my $path(@path) # Describe path
8253 {my $t = -t $path;
8254 if ($path != $xmlTree)
8255 {my $i = $path->index;
8256 push @keys, qq({$t}[$i]);
8257 }
8258 }
8259 if ($o->isText) # Text field
8260 {my $s = join "", q($$perl), @keys, q( = ), dump trim $o->text; # Load Perl data structure
8261 eval $s;
8262 $@ and confess "$@\n";
8263 }
8264 else # Check that a tag has content unless it is a boolean leaf
8265 {if ($o->isEmpty) # Tag has no content
8266 {if ($valid eq q(-))
8267 {my $s = join "", q($$perl), @keys, q( = 1); # Show leaf tag present
8268 eval $s;
8269 $@ and confess "$@\n";
8270 }
8271 else
8272 {confess join " ", "Tag has no content on path(zero based):",
8273 $o->pathString, "\n";
8274 }
8275 }
8276 else # Tag has content
8277 {if ($valid eq q(-))
8278 {confess join " ", "Leaf boolean has content on path(zero based):",
8279 $o->pathString, "\n";
8280 }
8281 }
8282 }
8283  
8284 if (1) # Bless parents so we can write $a->b rather than $a->{b} and get an error if we choose an invalid field.
8285 {pop @keys; pop @path;
8286 my @p = map{$_->tag} @path;
8287 my $k = join '', @keys;
8288 my $p = join '::', $xmlTree->tag, @p;
8289 my $s = @keys ? qq(bless \$\$perl$k, "$p") : qq(bless \$perl$k, "$p");
8290 eval $s;
8291 $@ and confess "$@\n";
8292 }
8293 }
8294 elsif ($p)
8295 {confess join ' ',
8296 "No description in validator for path:", $o->pathString, "\n";
8297 }
8298 else
8299 {my $j = -p $o;
8300 confess "Junk: $j\n";
8301 }
8302 });
8303  
8304 for my $v(sort keys %$validator) # Validate presence of required elements by checking the application of each rule which requires at least one sub element
8305 {my ($count) = $$validator{$v}->@*; # Count specification from this validation specification
8306 next unless $count =~ m(\A[1+]\Z)i; # We are only interested in required elements
8307 my @path = split m/\s+/, $v; # Path to this rule
8308 my $parent = join ' ', reverse $xmlTree->tag, @path[0..@path-2]; # Path to parent of this rule
8309  
8310 $xmlTree->by(sub # Traverse xml to build Perl data structure
8311 {my ($o) = @_;
8312 if ($parent eq $o->context) # Point in the xml parse tree that matches the parent rule
8313 {my $child = $path[-1];
8314 my @c = $o->c($child);
8315 if (@c < 1)
8316 {say STDERR -p $o;
8317 confess join " ", "$child required under", $o->context, "\n";
8318 }
8319 }
8320 });
8321 }
8322  
8323 my $sublimate; $sublimate = sub # Replace arrays with direct references where possible
8324 {my ($data, @path) = @_; # Data point, path to data point
8325  
8326 for my $k(sort keys %$data)
8327 {push @path, $k;
8328 for my $d($$data{$k}->@*) # Sublimate lower trees
8329 {$sublimate->($d, @path) if ref $d;
8330 if (my $valid = $$validator{join ' ', @path})
8331 {if ($$valid[0] =~ m(\A[-1?]\Z)i and $$data{$k}->@* <= 1)
8332 {$$data{$k} = $$data{$k}[0];
8333 }
8334 }
8335 }
8336 pop @path;
8337 }
8338 };
8339  
8340 &$sublimate($perl); # Replace arrays with direct references where possible
8341  
8342 $perl
8343 } # xmlToPerl
8344  
8345 #D1 Documentation # Update documentation describing this module
8346  
8347 sub extractDocumentationFlags($$) #P Generate documentation for a method with a user flag.
8348 {my ($flags, $method) = @_; # Flags, method name.
8349 my $b = "${method}NonBlank"; # Not blank method name - used for a small number of navigation methods
8350 my $x = "${method}NonBlankX"; # Not blank, die on B<undef> method name
8351 my $m = $method; # Second action method
8352 $m =~ s/\Afirst/next/gs;
8353 $m =~ s/\Alast/prev/gs;
8354 my @doc; my @code;
8355  
8356 if ($flags =~ m/C/is) # Context flag for a method that returns a single node or B<undef> if in the wrong context
8357 {push @doc, <<'END' if $flags =~ m/C/s;
8358 Use the optional B<@context> parameter to test the context of the specified
8359 B<$node> as understood by method L<at|/at>. If the context is supplied and
8360 B<$node> is not in this context then this method returns B<undef> immediately.
8361 END
8362 push @doc, <<'END' if $flags =~ m/c/s;
8363 Use the required B<$tag> parameter to specify the expected tag on the specified
8364 B<$node> using a single match expression as understood by method L<at|/at>. Use
8365 the optional B<@context> parameter to test the context as understood by method
8366 L<at|/at> of the parent node of the specified B<$node>. If either test fails
8367 this method returns B<undef> immediately.
8368 END
8369 }
8370 if ($flags =~ m/K/s) # Context flag for a method that returns an array of nodes or the empty array if in the wrong context
8371 {push @doc, <<'END';
8372 Use the B<@context> parameter to test the context of the specified
8373 B<$node> as understood by method L<at|/at>. If a context is supplied and
8374 B<$node> is not in this context then this method returns an empty list B<()>
8375 immediately.
8376 END
8377 }
8378  
8379 if ($flags =~ m/B/s) # Skip blank text
8380 {push @doc, <<END;
8381 Use B<$b> to skip a (rare) initial blank text CDATA. Use B<$x> to die rather
8382 then receive a returned B<undef> or false result.
8383 END
8384 push @code, <<END;
8385 sub $b
8386 {my \$r = &$method(\$_[0]);
8387 return undef unless \$r;
8388 if (\$r->isBlankText)
8389 {shift \@_;
8390 return &$m(\$r, \@_)
8391 }
8392 else
8393 {return &$m(\@_);
8394 }
8395 }
8396  
8397 sub $x
8398 {my \$r = &$b(\@_);
8399 die '$method' unless defined(\$r);
8400 \$r
8401 }
8402 END
8403 }
8404  
8405 [join("\n", @doc), join("\n", @code), $flags =~ m/B/ ? [$b, $x] : ()]
8406 }
8407  
8408 sub writeContentToGitHub($$) #P Upload the contents of a string to a file on github
8409 {my ($file, $content) = @_; # File on github, file contents
8410 my $g = <<'END'; # I am the only person who does this so there is no point in adding GitHub::Crud to the prerequisites list
8411 use GitHub::Crud;
8412 my $target = writeFile(undef, $content);
8413 GitHub::Crud::writeFileFromFileUsingSavedToken
8414 (q(philiprbrenan), q(philiprbrenan.github.io), $file, $target);
8415 GitHub::Crud::writeFileFromFileUsingSavedToken
8416 (q(ryffine), q(ryffine.github.io), $file, $target);
8417 END
8418  
8419 my $r = eval $g;
8420 confess "$@" if $@;
8421 $r
8422 }
8423  
8424 sub writeFileToGitHub($$) #P Upload the contents of the specified local file to a file on github
8425 {my ($file, $localFile) = @_; # File name on github, local file name
8426 my $g = <<'END'; # I am the only person who does this so there is no point in adding GitHub::Crud to the prerequisites list
8427 use GitHub::Crud;
8428 GitHub::Crud::writeFileFromFileUsingSavedToken
8429 (q(philiprbrenan), q(philiprbrenan.github.io), $file, $localFile);
8430 GitHub::Crud::writeFileFromFileUsingSavedToken
8431 (q(ryffine), q(ryffine.github.io), $file, $localFile);
8432 END
8433  
8434 my $r = eval $g;
8435 confess "$@" if $@;
8436 $r
8437 }
8438  
8439 sub processModuleDescription($) #P Process module description to write a description of editing Xml to GitHub
8440 {my ($d) = @_; # Module description
8441  
8442 my $b = q(<b>);
8443 my $bb = q(</b>);
8444 my $th = q(<th align="left">);
8445  
8446 my @h = (<<END); # Editor commands description
8447 <!DOCTYPE html>
8448 <html>
8449 <head>
8450 <meta charset="utf-8"/>
8451 <title></title>
8452 <style>
8453 .l0 {
8454 background-color: #f0fff0
8455 }
8456 .l1 {
8457 background-color: #fff0ff
8458 }
8459 </style>
8460 </head>
8461 <body>
8462  
8463 <div style="width: 80em">
8464  
8465 <h1>Methods in Data::Edit::Xml that can be used to Edit Dita</h1>
8466 END
8467  
8468 my $methods = sub # Format methods either the immediately useful ones or all of them
8469 {my ($isUseful) = @_; # Immediately useful methods
8470  
8471 return unless my $M = $d->{methods}; # Method descriptions
8472  
8473 push my @h, (<<END); # Table header
8474 <table border="0" cellpadding="20">
8475 <tr>${th}Line${th}Method long name${th}aka${th}Parameter${th}Description
8476 END
8477  
8478 my $line = 0; # Method number
8479  
8480 for my $method(sort keys %$M)
8481 {my $m = $$M{$method};
8482 next if $isUseful and !$m->{isUseful}; # Only immediately useful methods requested
8483 next unless $m->{unitary}; # Only unitary methods can be used in the editor or the pcd language
8484  
8485 my $name = $m->{name};
8486 my $synonym = sub
8487 {return q() unless my $S = $m->{synonyms};
8488 my ($s) = sort keys %$S;
8489 return $s;
8490 }->();
8491  
8492 my $c = $m->{comment}; # Format the comment so that it breaks
8493 $c = formatString($c, 80);
8494  
8495 my $p = $m->{parameters};
8496 shift @$p; # We are unitary so this is feasible
8497 ++$line;
8498  
8499 my $class = q(class="l).($line % 2).q("); # Row color
8500  
8501 push @h, qq(<tr $class><td>$line<td>$name<td><b>$synonym</b><td><td>$c\n);
8502 if (@$p)
8503 {for my $p(@$p)
8504 {my ($parm, $desc) = @$p;
8505 push @h, qq(<tr $class><td><td><td><td>$parm<td>$desc\n);
8506 }
8507 }
8508 }
8509  
8510 push @h, (<<END);
8511 </table>
8512 END
8513 @h
8514 };
8515  
8516 push @h, <<END, &$methods(1), <<END2, &$methods(0);
8517 <h2>Immediately useful methods</h2>
8518 <p>The following methods are frequently use to make simple changes:
8519 END
8520 <h2>All methods</h2>
8521 <p>Here is a listing of all methods currently available:
8522 END2
8523  
8524 my $dts = dateTimeStamp;
8525 push @h, <<END;
8526  
8527 <h1>Editing Dita using Geany or PCD</h1>
8528  
8529 <p>L[dex] is a Perl extension module that can help you edit L[Dita] either
8530 interactively using L[Geany] or in batch using L[PCD] files.
8531  
8532 <h2>Configuring Geany to Edit Dita and PCD</h2>
8533  
8534 <p>Please obtain a version of L[Ubuntu] and follow the instructions at
8535 L[pcdInstall].
8536  
8537 <h2>Editing Dita interactively with Geany</h2>
8538  
8539 <p>You can use many of the methods found in L[dex] one at a time directly from
8540 the L[Geany] editor when it has been configured for L[Dita] editing. The
8541 methods executed are recorded in log visible in another L[Geany] tab so that
8542 they can be edited directly into a program that is being developed to use
8543 L[dex] directly from L[Perl] or from L[pcd].
8544  
8545 <p>The table below lists the methods that can be used in L[Geany]. Simply type
8546 the method name and any parameters up against a closing $b&gt;$bb or
8547 $b&gt;$bb as shown on line $b 13 $bb like this:
8548  
8549 <p><img src="/images/mlp_start.png"/>
8550  
8551 <p>and press $b shift+Enter $bb to merge the two lists:
8552  
8553 <p><img src="/images/mlp_finish.png"/>
8554  
8555  
8556 <h2>Editing Dita in batch using PCD</h2>
8557  
8558 <p>L[PCD] files contain a list of L[dex] commands, one per line, that are applied
8559 to each node of each of the parse trees produced by parsing all of the L[DITA]
8560 files found in the same directory tree as the L[PCD] file.
8561  
8562 <p><a href="https://github.com/philiprbrenan/pleaseChangeDita">This
8563 repository</a> contains two L[DITA] l[concept]s and one L[PCD] file. The L[PCD]
8564 file unwraps a <b>b</b> tag found under another <b>b</b> tag.
8565  
8566 <p>There are four types of line in a L[PCD] file:
8567  
8568 <p><pre>
8569 1
8570 2 # Comment
8571 3 Unwrap b under b and delete empty paragraphs
8572 4 unwrap b b
8573 5 cutIfEmpty p
8574 </pre></p>
8575  
8576 <table cellpadding="20" border="0">
8577 <tr><th>Line<th>Name<th>Description
8578  
8579 <tr><td>1<td>Blank lines <td>Blank lines are ignored
8580  
8581 <tr><td>2<td>Comment lines <td>If the first non space character is <b>#</b>
8582 then this is a comment line and it is ignored.
8583  
8584 <tr><td>3<td>Description lines<td>If the first character is not a space it is a
8585 description line whose purpose is to communicate with other humans what the
8586 following commands aim to do.
8587  
8588 <tr><td>4<td>Command lines <td>If the first character is a space then the
8589 rest of the line is command line: a method name chosen from L[dex] followed by
8590 any parameters separated from each other by one or more spaces.
8591  
8592 </table>
8593  
8594 <p>Each L[PCD] file can contain zero or more description lines. Each description
8595 line can be followed by zero or more command lines called a "block of command
8596 lines" or "block" for short. L[PCD] executes each block against each node in
8597 each of the parse trees constructed by parsing all of the L[DITA] files found
8598 in the same folder as the L[PCD] files. Execution of the block continues line
8599 by line until the end of the block or the L[dex] method fails. If the block
8600 completes successfully, the description line for that block is printed out to
8601 show that it "fired".
8602  
8603 <p>L[Geany] on L[Ubuntu] has been configured as an L[IDE] to make editing both
8604 L[PCD] and test L[DITA] files a pleasant experience with all the usual
8605 facilities provided by such an L[IDE] such as help choosing command names,
8606 testing the syntax of L[PCD] files once they are written, then executing
8607 them against L[DITA] files and showing the execution results.</p>
8608  
8609 <p>You can also place l[PCD] files into the same L[S3] Bucket or L[github] repo
8610 as your L[dita] files and then process them in bulk with L[ssxr].
8611 <p>Updated: $dts
8612 </div>
8613 </body>
8614 </html>
8615 END
8616  
8617 my $h2 = join "\n", @h; # Html
8618 my $h1 = expandWellKnownUrlsInHtmlFormat ($h2);
8619 my $h = expandWellKnownUrlsInHtmlFromPerl($h1);
8620 $h =~ s(([LB]) (<) ([^>]*) (>)) ($1&lt;$3&gt;)xgs; # Fix angle brackets
8621  
8622 if (1) # Simplified documentation
8623 {my @l = readFile($INC{"Data/Edit/Xml.pm"});
8624  
8625 my $method; my @also; my @before; my @code;
8626 for my $l(@l)
8627 {if ($l =~ m(\Asub\s*(\w+))) # Method for which there is simplified documentation
8628 {$method = $1;
8629 @before = (); @code = ();
8630 }
8631 if ($l =~ m(\A#a\s*(.*?)\s*\Z)) #a see also
8632 {push @also, split /\s+/, $1;
8633 }
8634 if ($l =~ m(\A#b\s*(.*?)\s*\Z)) #b before file with the root unwrapped
8635 {push @before, $1;
8636 }
8637 if ($l =~ m(\A#c\s*(.*?)\s*\Z)) #c Example pcd
8638 {push @code, $1;
8639 }
8640 if ($l =~ m(\A#d\s*(.*?)\s*\Z)) #d Simplified documentation
8641 {$d->{methods}{$method}{example} =
8642 genHash(q(Data::Edit::Xml::Example), # Description of a pcd method
8643 method => $method, # Method
8644 also => [@also], # See also
8645 before => [@before], # Before file content minus root tag which will be added as <a>
8646 code => [@code], # Pcd code
8647 doc => $1, # One line summary
8648 );
8649 }
8650 }
8651 }
8652 ####TEST####
8653 # writeContentToGitHub(q(data_edit_xml_edit_commands.html), $h);
8654 # writeFileToGitHub(q(images/mlp_start.png), q(/home/phil/r/oxygenWorkshop/doc/selfServiceXref/images/4/s011256.png));
8655 # writeFileToGitHub(q(images/mlp_finish.png), q(/home/phil/r/oxygenWorkshop/doc/selfServiceXref/images/4/s011321.png));
8656 } # processModuleDescription
8657  
8658 #D1 Compression # Read and write files of compressed xml. These methods provide a compact, efficient way to store and retrieve parse trees to/from files.
8659  
8660 sub writeCompressedFile($$) #U Write the parse tree starting at B<$node> as compressed L<XML> to the specified B<$file>. Use L<readCompressedFile|/readCompressedFile> to read the B<$file>.
8661 {my ($node, $file) = @_; # Parse tree node, file to write to.
8662 makePath($file);
8663 open my $F, "| gzip>$file" or # Compress via gzip
8664 confess "Cannot open file for write because:\n$file\n$!\n";
8665 binmode($F, ":utf8"); # Input to gzip encoded as utf8
8666 print {$F} -s $node;
8667 close ($F);
8668 -e $file or confess "Failed to write to file:\n$file\n";
8669 $file
8670 }
8671  
8672 sub readCompressedFile($) #S Read the specified B<$file> containing compressed L<XML> and return the root node. Use L<writeCompressedFile|/writeCompressedFile> to write the B<$file>.
8673 {my ($file) = @_; # File to read.
8674 defined($file) or
8675 confess "Cannot read undefined file\n";
8676 $file =~ m(\n) and
8677 confess "File name contains a new line:\n=$file=\n";
8678 -e $file or
8679 confess "Cannot read file because it does not exist, file:\n$file\n";
8680 open(my $F, "gunzip < $file|") or # Unzip input file
8681 confess "Cannot open file for input, file:\n$file\n$!\n$?\n";
8682 local $/ = undef;
8683 my $string = <$F>;
8684 new($string) # Reparse resulting string to recover parse tree
8685 }
8686  
8687 #D1 Autoload # Allow methods with constant parameters to be called as B<method_p1_p2>...(variable parameters) whenever it is easier to type underscores than (qw()).
8688  
8689 sub DESTROY {} # TO avoid seeing it in AUTOLOAD
8690  
8691 our $AUTOLOAD; # The method to be autoloaded appears here
8692  
8693 sub AUTOLOAD # Allow methods with constant parameters to be called as B<method_p1_p2>...(variable parameters) whenever it is easier to type underscores than (qw()).
8694 {#return if $AUTOLOAD =~ m(Destroy)is; # Perl internal
8695 my $q = shift; # Object package
8696 if ($AUTOLOAD =~ m(__)s) # Chain of calls separated by q(__)
8697 {no strict q(refs); # So we can call a sub by name
8698 my @calls = split /__/, $AUTOLOAD; # Calls in chain
8699 for my $call(@calls) # Each call in chain
8700 {my ($p, @p) = split /_/, $call; # Call, parameters for call
8701 confess "No such method : $p" unless $q->can($p); # Check that the method name is valid
8702 $q = $p->($q, @p); # Make call
8703 # return undef unless $q; # Abort chain of calls if any call returns undef
8704 return undef unless defined $q; # Abort chain of calls if any call returns undef
8705 }
8706 return $q; # Return result of chain
8707 }
8708 else # Optimized single call
8709 {my ($p, @p) = split /_/, $AUTOLOAD; # Break out parameters
8710 confess "No such method : $p" unless $q->can($p); # Check that the method name is valid
8711 unshift @_, $q, @p; # Insert static parameters into parameter list
8712 goto &$p; # Call desired routine
8713 }
8714 }
8715  
8716 #D0
8717  
8718 #-------------------------------------------------------------------------------
8719 # Export - eeee
8720 #-------------------------------------------------------------------------------
8721  
8722 use Exporter qw(import);
8723  
8724 use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
8725  
8726 # containingFolder
8727  
8728 @ISA = qw(Exporter);
8729 @EXPORT = qw(formatTable);
8730 @EXPORT_OK = qw(
8731 $defaultBrowser
8732 $defaultEditorHelp
8733 $lastParseError
8734 %savedNodes
8735 @saveLastCutOut
8736 $selectionEnd
8737 $selectionStart
8738 );
8739 %EXPORT_TAGS = (all=>[@EXPORT, @EXPORT_OK]);
8740  
8741 # podDocumentation
8742  
8743 #Install If you receive the message:\m Expat.xs:12:19: fatal error: expat.h: No such file or directory\mduring installation, install libexpat1-dev:\m sudo apt install libexpat1-dev
8744  
8745 =pod
8746  
8747 =encoding utf-8
8748  
8749 =head1 Name
8750  
8751 Data::Edit::Xml - Edit data held in the XML format.
8752  
8753 =head1 Synopsis
8754  
8755 Create a L<new|/new> XML parse tree:
8756  
8757 my $a = Data::Edit::Xml::new q(<a><b><c/></b><d><c/></d></a>);
8758  
8759 use:
8760  
8761 say STDERR -p $a;
8762  
8763 to L<print|/print>:
8764  
8765 <a>
8766 <b>
8767 <c/>
8768 </b>
8769 <d>
8770 <c/>
8771 </d>
8772 </a>
8773  
8774 L<Cut|/cut> out B<c> under B<b> but not under B<d> in the created tree
8775 by L<traversing|/Traversal> in post-order L<applying|/by> a B<sub> to each node
8776 to L<cut|/cut> out B<c> when we are L<at|/at> B<c> under B<b> under B<a>.
8777  
8778 $a -> by(sub {$_ -> cut_c_b_a});
8779  
8780 Or if you know when you are going:
8781  
8782 $a -> go_b_c__cut;
8783  
8784 To get:
8785  
8786 <a>
8787 <b/>
8788 <d>
8789 <c/>
8790 </d>
8791 </a>
8792  
8793 =head2 Bullets to unordered list
8794  
8795 To transform a series of bullets into an unordered list, parse the input XML:
8796  
8797 my $a = Data::Edit::Xml::new(<<END);
8798 <a>
8799 <p>• Minimum 1 number</p>
8800 <p>• No leading, trailing, or embedded spaces</p>
8801 <p>• Not case-sensitive</p>
8802 </a>
8803 END
8804  
8805 Traverse the resulting parse tree, removing bullets and leading white space,
8806 changing B<p> to B<li> and B<a> to B<ul>:
8807  
8808 $a->change_ul->by(sub
8809 {$_->up__change_li if $_->text_p and $_->text =~ s/\A•\s*//s
8810 });
8811  
8812 Print to get:
8813  
8814 ok -p $a eq <<END;
8815 <ul>
8816 <li>Minimum 1 number</li>
8817 <li>No leading, trailing, or embedded spaces</li>
8818 <li>Not case-sensitive</li>
8819 </ul>
8820 END
8821  
8822 =head2 XSLT Transformation Example from Wikipedia
8823  
8824 Given sample data for an B<XSLT> transformation from
8825 L<Wikipedia|https://en.wikipedia.org/w/index.php?title=XSLT#Example_1_(transforming_XML_to_XML)>
8826  
8827 my $x = Data::Edit::Xml::new(<<END);
8828 <persons>
8829 <person username="JS1"><name>John</name><surname>Smith</surname></person>
8830 <person username="MI1"><name>Morka</name><surname>Ismincius</surname></person>
8831 </persons>
8832 END
8833  
8834 We can transform it by the rather shorter:
8835  
8836 $x->by(sub
8837 {$_->unwrap_name;
8838 $_->cut_surname;
8839 $_->change_name_person__change_root_persons;
8840 });
8841  
8842 To get:
8843  
8844 ok -p $x eq <<END;
8845 <persons>
8846 <name username="JS1">John</name>
8847 <name username="MI1">Morka</name>
8848 </persons>
8849 END
8850  
8851 =head2 Convert ol to steps
8852  
8853 Given an ordered list:
8854  
8855 my $a = Data::Edit::Xml::new(<<END);
8856 <ol>
8857 <li>A</li>
8858 <li>B</li>
8859 <li>C</li>
8860 </ol>
8861 END
8862  
8863 A single call transforms the ordered list:
8864  
8865 $a->ditaConvertOlToSubSteps;
8866  
8867 to L<Dita> steps:
8868  
8869 ok -p $a eq <<END;
8870 <substeps>
8871 <substep>
8872 <cmd>A</cmd>
8873 </substep>
8874 <substep>
8875 <cmd>B</cmd>
8876 </substep>
8877 <substep>
8878 <cmd>C</cmd>
8879 </substep>
8880 </substeps>
8881 END
8882  
8883 =head1 Description
8884  
8885 Edit data held in the XML format.
8886  
8887  
8888 Version 20201031.
8889  
8890  
8891 The following sections describe the methods in each functional area of this
8892 module. For an alphabetic listing of all methods by name see L<Index|/Index>.
8893  
8894  
8895  
8896 =head1 Immediately useful methods
8897  
8898 These methods are the ones most likely to be of immediate use to anyone using
8899 this module for the first time:
8900  
8901  
8902 L<at($node, @context)|/at($node, @context)>
8903  
8904 Confirm that the specified B<$node> has the specified L<ancestry|/ancestry>. Ancestry is specified by providing the expected tags that the B<$node>'s parent, the parent's parent etc. must match at each level. If B<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 B<undef>.
8905  
8906 L<attrX($node, $attribute)|/attrX($node, $attribute)>
8907  
8908 Return the value of the specified B<$attribute> of the specified B<$node> or B<q()> if the B<$node> does not have such an attribute.
8909  
8910 L<by($node, $sub)|/by($node, $sub)>
8911  
8912 Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. A reference to the current node is also made available via L<$_>. This is equivalent to the L<x=|/opBy> operator.
8913  
8914 L<change($node, $name, @context)|/change($node, $name, @context)>
8915  
8916 Change the name of the specified B<$node>, optionally confirming that the B<$node> is in a specified context and return the B<$node>.
8917  
8918 L<cut($node, @context)|/cut($node, @context)>
8919  
8920 Cut out and return the specified B<$node> so that it can be reinserted else where in the L<parse|/parse> tree.
8921  
8922 L<go($node, @path)|/go($node, @path)>
8923  
8924 Return the node reached from the specified B<$node> via the specified L<path|/path>: (index positionB<?>)B<*> 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. B<*> can be used as the last position to retrieve all nodes with the final tag.
8925  
8926 L<moveEndAfter($node, $to, @context)|/moveEndAfter($node, $to, @context)>
8927  
8928 Move the end of a B<$node> to just after the specified B<$target> node assuming that the B<$target> node is either a subsequent sibling or a child of B<$node>. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
8929  
8930 L<new($fileNameOrString, @options)|/new($fileNameOrString, @options)>
8931  
8932 Create a new parse tree - call this method statically as in Data::Edit::Xml::new(file or string) to parse a file or string B<or> with no parameters and then use L</input>, L</inputFile>, L</inputString>, L</errorFile> to provide specific parameters for the parse, then call L</parse> to perform the parse and return the parse tree.
8933  
8934 L<prettyString($node, $depth)|/prettyString($node, $depth)>
8935  
8936 Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it. Or use L<-p|/opString> $node
8937  
8938 L<putLast($old, $new, @context)|/putLast($old, $new, @context)>
8939  
8940 Place a L<cut out|/cut> or L<new|/new> node last in the content of the specified B<$node> and return the new node. See L<putLastCut|/putLastCut> to cut and put last in one operation. See L<addLast|/addLast> to perform this operation conditionally.
8941  
8942 L<putNextRequiredCleanUp($node, @text)|/putNextRequiredCleanUp($node, @text)>
8943  
8944 Place a required cleanup next after a specified B<$node> using the specified B<@text> and return the required clean up node.
8945  
8946 L<unwrap($node, @context)|/unwrap($node, @context)>
8947  
8948 Unwrap the specified B<$node> if in the optional B<@context> by replacing the node with its contents. Returns the parent node on success, otherwise B<undef> if an attempt is made to unwrap a text node or the root node.
8949  
8950 L<wrapWith($node, $tag, @context)|/wrapWith($node, $tag, @context)>
8951  
8952 Wrap the specified B<$node> in a new node created from the specified B<$tag> in the optional B<@context> forcing the specified $node down to deepen the L<parse|/parse> tree - return the new wrapping node or B<undef> if this is not possible. See L<addWrapWith|/addWrapWith> to perform this operation conditionally.
8953  
8954  
8955  
8956  
8957 =head1 Construction
8958  
8959 Create a parse tree, either by parsing a L<file or string|/file or string> B<or> L<node by node|/Node by Node> B<or> from another L<parse tree|/Parse tree>.
8960  
8961 =head2 File or String
8962  
8963 Construct a parse tree from a file or a string.
8964  
8965 =head3 new($fileNameOrString, @options)
8966  
8967 Create a new parse tree - call this method statically as in Data::Edit::Xml::new(file or string) to parse a file or string B<or> with no parameters and then use L</input>, L</inputFile>, L</inputString>, L</errorFile> to provide specific parameters for the parse, then call L</parse> to perform the parse and return the parse tree.
8968  
8969 Parameter Description
8970 1 $fileNameOrString Optional file name or string from which to construct the parse tree
8971 2 @options Hash of other options.
8972  
8973 B<Example:>
8974  
8975  
8976  
8977 my $a = Data::Edit::Xml::new(<<END); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
8978  
8979 <a>
8980 <b>
8981 <c id="42" match="mm"/>
8982 </b>
8983 <d>
8984 <e/>
8985 </d>
8986 </a>
8987 END
8988  
8989 ok -p $a eq <<END;
8990 <a>
8991 <b>
8992 <c id="42" match="mm"/>
8993 </b>
8994 <d>
8995 <e/>
8996 </d>
8997 </a>
8998 END
8999  
9000  
9001 This is a static method and so should either be imported or invoked as:
9002  
9003 Data::Edit::Xml::new
9004  
9005  
9006 =head3 cdata()
9007  
9008 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 L<confess|http://perldoc.perl.org/Carp.html#SYNOPSIS/>.
9009  
9010  
9011 B<Example:>
9012  
9013  
9014  
9015 ok Data::Edit::Xml::cdata eq q(CDATA); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9016  
9017  
9018  
9019 =head3 parse($parser)
9020  
9021 Parse input L<Xml|https://en.wikipedia.org/wiki/XML> specified via: L<inputFile|/inputFile>, L<input|/input> or L<inputString|/inputString>.
9022  
9023 Parameter Description
9024 1 $parser Parser created by L</new>
9025  
9026 B<Example:>
9027  
9028  
9029 my $x = Data::Edit::Xml::new;
9030  
9031 $x->inputString = <<END;
9032 <a id="aa"><b id="bb"><c id="cc"/></b></a>
9033 END
9034  
9035  
9036 $x->parse; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9037  
9038  
9039 ok -p $x eq <<END;
9040 <a id="aa">
9041 <b id="bb">
9042 <c id="cc"/>
9043 </b>
9044 </a>
9045 END
9046  
9047  
9048 =head2 Node by Node
9049  
9050 Construct a parse tree node by node.
9051  
9052 =head3 newText(undef, $text)
9053  
9054 Create a new text node.
9055  
9056 Parameter Description
9057 1 undef Any reference to this package
9058 2 $text Content of new text node
9059  
9060 B<Example:>
9061  
9062  
9063 ok -p $x eq <<END;
9064 <a class="aa" id="1">
9065 <b class="bb" id="2"/>
9066 </a>
9067 END
9068  
9069  
9070 $x->putLast($x->newText("t")); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9071  
9072  
9073 ok -p $x eq <<END;
9074 <a class="aa" id="1">
9075 <b class="bb" id="2"/>
9076 t
9077 </a>
9078 END
9079  
9080  
9081 =head3 newTag(undef, $command, %attributes)
9082  
9083 Create a new non text node.
9084  
9085 Parameter Description
9086 1 undef Any reference to this package
9087 2 $command The tag for the node
9088 3 %attributes Attributes as a hash.
9089  
9090 B<Example:>
9091  
9092  
9093 my $x = Data::Edit::Xml::newTree("a", id=>1, class=>"aa");
9094  
9095  
9096 $x->putLast($x->newTag("b", id=>2, class=>"bb")); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9097  
9098  
9099 ok -p $x eq <<END;
9100 <a class="aa" id="1">
9101 <b class="bb" id="2"/>
9102 </a>
9103 END
9104  
9105  
9106 =head3 newTree($command, %attributes)
9107  
9108 Create a new tree.
9109  
9110 Parameter Description
9111 1 $command The name of the root node in the tree
9112 2 %attributes Attributes of the root node in the tree as a hash.
9113  
9114 B<Example:>
9115  
9116  
9117  
9118 my $x = Data::Edit::Xml::newTree("a", id=>1, class=>"aa"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9119  
9120  
9121 ok -s $x eq '<a class="aa" id="1"/>';
9122  
9123  
9124 =head3 dupTag($node, @context)
9125  
9126 Create a new non text node by duplicating the tag of an existing node.
9127  
9128 Parameter Description
9129 1 $node Node
9130 2 @context Optional context
9131  
9132 Use the optional B<@context> parameter to test the context of the specified
9133 B<$node> as understood by method L<at|/at>. If the context is supplied and
9134 B<$node> is not in this context then this method returns B<undef> immediately.
9135  
9136  
9137  
9138 B<Example:>
9139  
9140  
9141 my $a = Data::Edit::Xml::new(<<END);
9142 <a>
9143 <b><c/></b>
9144 </a>
9145 END
9146  
9147 my $d = $a->go_b__dupTag;
9148 ok -p $d eq <<END;
9149 <b/>
9150 END
9151  
9152  
9153 =head3 replaceSpecialChars($string)
9154  
9155 Replace < > " & with &lt; &gt; &quot; &amp; Larry Wall's excellent L<Xml parser> unfortunately replaces &lt; &gt; &quot; &amp; 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.
9156  
9157 Parameter Description
9158 1 $string String to be edited.
9159  
9160 B<Example:>
9161  
9162  
9163  
9164 ok Data::Edit::Xml::replaceSpecialChars(q(<">)) eq q(&lt;&quot;&gt;); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9165  
9166  
9167  
9168 This is a static method and so should either be imported or invoked as:
9169  
9170 Data::Edit::Xml::replaceSpecialChars
9171  
9172  
9173 =head3 undoSpecialChars($string)
9174  
9175 Reverse the results of calling L<replaceSpecialChars|/replaceSpecialChars>.
9176  
9177 Parameter Description
9178 1 $string String to be edited.
9179  
9180 B<Example:>
9181  
9182  
9183  
9184 ok Data::Edit::Xml::undoSpecialChars(q(&lt;&quot;&gt;)) eq q(<">); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9185  
9186  
9187  
9188 This is a static method and so should either be imported or invoked as:
9189  
9190 Data::Edit::Xml::undoSpecialChars
9191  
9192  
9193 =head2 Parse tree attributes
9194  
9195 Attributes of a node in a parse tree. For instance the attributes associated with an L<Xml|https://en.wikipedia.org/wiki/XML> tag are held in the L<attributes|/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.
9196  
9197 =head2 Parse tree
9198  
9199 Construct a L<parse|/parse> tree from another L<parse|/parse> tree.
9200  
9201 =head3 renew($node, @context)
9202  
9203 Returns a renewed copy of the L<parse|/parse> tree by first printing it and then reparsing it, optionally checking that the starting node is in a specified context: use this method if you have added nodes via the L</"Put as text"> methods and wish to traverse their L<parse|/parse> tree.
9204  
9205 Returns the starting node of the new L<parse|/parse> tree or B<undef> if the optional context constraint was supplied but not satisfied.
9206  
9207 Parameter Description
9208 1 $node Node to renew from
9209 2 @context Optional context
9210  
9211 Use the optional B<@context> parameter to test the context of the specified
9212 B<$node> as understood by method L<at|/at>. If the context is supplied and
9213 B<$node> is not in this context then this method returns B<undef> immediately.
9214  
9215  
9216  
9217 B<Example:>
9218  
9219  
9220 my $a = Data::Edit::Xml::new("<a/>", inputFile=>q(aaa.xml));
9221 $a->putFirstAsText(qq(<b/>));
9222 ok !$a->go(q(b));
9223  
9224 my $A = $a->renew; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9225  
9226 ok -t $A->go(q(b)) eq q(b);
9227 ok $A->root->inputFile eq $a->root->inputFile;
9228  
9229  
9230 =head3 clone($tree)
9231  
9232 Return a clone of the entire L<parse|/parse> tree which is created using the fast L<Storable::dclone> method. The L<parse|/parse> tree is cloned without converting it to string and reparsing it so this method will not L<renew|/renew> any nodes added L<as text|/Put as text>.
9233  
9234 Returns the starting node of the new L<parse|/parse> tree.
9235  
9236 Parameter Description
9237 1 $tree Parse tree
9238  
9239 Use the optional B<@context> parameter to test the context of the specified
9240 B<$node> as understood by method L<at|/at>. If the context is supplied and
9241 B<$node> is not in this context then this method returns B<undef> immediately.
9242  
9243  
9244  
9245 B<Example:>
9246  
9247  
9248 {my $a = Data::Edit::Xml::new("<a> </a>");
9249  
9250  
9251 my $A = $a->clone; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9252  
9253  
9254 ok -s $A eq q(<a/>);
9255  
9256 ok $a->equals($A);
9257  
9258 {my $x = Data::Edit::Xml::new(<<END);
9259 <x>
9260 <a>aaa
9261 <b>bbb</b>
9262 ccc
9263 <d>ddd</d>
9264 eee
9265 </a>
9266 </x>
9267 END
9268  
9269  
9270 my $y = $x->clone; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9271  
9272  
9273 ok !$x->diff($y);
9274  
9275  
9276 =head3 equals($node1, $node2)
9277  
9278 Return the first node if the two L<parse|/parse> trees have identical representations via L<string|/string>, else B<undef>.
9279  
9280 Parameter Description
9281 1 $node1 Parse tree 1
9282 2 $node2 Parse tree 2.
9283  
9284 B<Example:>
9285  
9286  
9287 {my $a = Data::Edit::Xml::new("<a> </a>");
9288  
9289 my $A = $a->clone;
9290  
9291 ok -s $A eq q(<a/>);
9292  
9293  
9294 ok $a->equals($A); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9295  
9296  
9297  
9298 =head3 equalsIgnoringAttributes($node1, $node2, @attributes)
9299  
9300 Return the first node if the two L<parse|/parse> trees have identical representations via L<string|/string> if the specified attributes are ignored, else B<undef>.
9301  
9302 Parameter Description
9303 1 $node1 Parse tree 1
9304 2 $node2 Parse tree 2
9305 3 @attributes Attributes to ignore during comparison
9306  
9307 B<Example:>
9308  
9309  
9310 {my $a = Data::Edit::Xml::new(<<END);
9311 <a>
9312 <b id="1" outputclass="1" name="b">
9313 <c id="2" outputclass="2" name="c"/>
9314 </b>
9315 </a>
9316 END
9317  
9318 my $A = Data::Edit::Xml::new(<<END);
9319 <a>
9320 <b id="11" outputclass="11" name="b">
9321 <c id="22" outputclass="22" name="c"/>
9322 </b>
9323 </a>
9324 END
9325  
9326 ok !$a->equals($A);
9327  
9328  
9329 ok !$a->equalsIgnoringAttributes($A, qw(id)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9330  
9331  
9332  
9333 ok $a->equalsIgnoringAttributes($A, qw(id outputclass)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9334  
9335  
9336  
9337 =head3 diff($first, $second, $N)
9338  
9339 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.
9340  
9341 Parameter Description
9342 1 $first First node
9343 2 $second Second node
9344 3 $N Maximum length of difference strings to return
9345  
9346 B<Example:>
9347  
9348  
9349 {my $x = Data::Edit::Xml::new(<<END);
9350 <x>
9351 <a>aaa
9352 <b>bbb</b>
9353 ccc
9354 <d>ddd</d>
9355 eee
9356 </a>
9357 </x>
9358 END
9359  
9360  
9361 ok !$x->diff($x); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9362  
9363  
9364 my $y = $x->clone;
9365  
9366  
9367 ok !$x->diff($y); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9368  
9369  
9370 $y->first->putLast($x->newTag(q(f)));
9371  
9372 ok nws(<<END) eq nws(-p $y);
9373 <x>
9374 <a>aaa
9375 <b>bbb</b>
9376 ccc
9377 <d>ddd</d>
9378 eee
9379 <f/>
9380 </a>
9381 </x>
9382 END
9383  
9384  
9385 is_deeply [$x->diff($y)], ["<d>ddd</d> eee <", "/a></x>", "f/></a></x>"]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9386  
9387  
9388  
9389 is_deeply [diff(-p $x, $y)], ["<d>ddd</d> eee <", "/a></x>", "f/></a></x>"]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9390  
9391  
9392  
9393 is_deeply [$x->diff(-p $y)], ["<d>ddd</d> eee <", "/a></x>", "f/></a></x>"]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9394  
9395  
9396 my $X = writeFile(undef, -p $x);
9397  
9398 my $Y = writeFile(undef, -p $y);
9399  
9400  
9401 is_deeply [diff($X, $Y)], ["<d>ddd</d> eee <", "/a></x>", "f/></a></x>"]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9402  
9403  
9404  
9405 =head3 save($node, $file)
9406  
9407 Save a copy of the L<parse|/parse> tree to a file which can be L<restored|/restore> and return the saved node. This method uses L<Storable|https://metacpan.org/pod/Storable> which is fast but produces large files that do not compress well. Use L<writeCompressedFile|/writeCompressedFile> to produce smaller save files at the cost of more time.
9408  
9409 Parameter Description
9410 1 $node Parse tree
9411 2 $file File.
9412  
9413 B<Example:>
9414  
9415  
9416  
9417 $y->save($f); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9418  
9419  
9420 my $Y = Data::Edit::Xml::restore($f);
9421  
9422 ok $Y->equals($y);
9423  
9424  
9425 =head3 restore($file)
9426  
9427 Return a L<parse|/parse> tree from a copy saved in a file by L<save|/save>.
9428  
9429 Parameter Description
9430 1 $file File
9431  
9432 B<Example:>
9433  
9434  
9435 $y->save($f);
9436  
9437  
9438 my $Y = Data::Edit::Xml::restore($f); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9439  
9440  
9441 ok $Y->equals($y);
9442  
9443  
9444 This is a static method and so should either be imported or invoked as:
9445  
9446 Data::Edit::Xml::restore
9447  
9448  
9449 =head3 expandIncludes($x)
9450  
9451 Expand the includes mentioned in a L<parse|/parse> tree: any tag that ends in B<include> is assumed to be an include directive. The file to be included is named on the B<href> keyword. If the file to be included is a relative file name, i.e. it does not begin with B</> then this file is made absolute relative to the file from which this L<parse|/parse> tree was obtained.
9452  
9453 Parameter Description
9454 1 $x Parse tree
9455  
9456 B<Example:>
9457  
9458  
9459 my @files =
9460  
9461 (owf("in1/a.xml", q(<a id="a"><include href="../in2/b.xml"/></a>)),
9462  
9463 owf("in2/b.xml", q(<b id="b"><include href="c.xml"/></b>)),
9464  
9465 owf("in2/c.xml", q(<c id="c"/>)));
9466  
9467 my $x = Data::Edit::Xml::new(fpf(currentDirectory, $files[0]));
9468  
9469  
9470 $x->expandIncludes; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9471  
9472  
9473 ok <<END eq -p $x;
9474 <a id="a">
9475 <b id="b">
9476 <c id="c"/>
9477 </b>
9478 </a>
9479 END
9480  
9481  
9482 =head1 Print
9483  
9484 Create a string representation of the L<parse|/parse> tree with optional selection of nodes via L<conditions|/Conditions>.
9485  
9486 Normally use the methods in L<Pretty|/Pretty> to format the L<Xml|https://en.wikipedia.org/wiki/XML> in a readable yet reparseable manner; use L<Dense|/Dense> string to format the L<Xml|https://en.wikipedia.org/wiki/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 L<file test operators|/opString> can also be conveniently used to print L<parse|/parse> trees in these formats.
9487  
9488 =head2 Pretty
9489  
9490 Pretty print the L<parse|/parse> tree.
9491  
9492 =head3 prettyString($node, $depth)
9493  
9494 Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it. Or use L<-p|/opString> $node
9495  
9496 Parameter Description
9497 1 $node Start node
9498 2 $depth Optional depth.
9499  
9500 B<Example:>
9501  
9502  
9503 {my $s = <<END;
9504 <a>
9505 <b>
9506 <A/>
9507 <B/>
9508 </b>
9509 <c>
9510 <C/>
9511 <D/>
9512 </c>
9513 </a>
9514 END
9515  
9516 my $a = Data::Edit::Xml::new($s);
9517  
9518  
9519 ok $s eq $a->prettyString; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9520  
9521  
9522 ok $s eq -p $a;
9523  
9524 {my $a = Data::Edit::Xml::new(<<END);
9525 <a>
9526 <b>bbb</b>.
9527 <c>ccc</c>.
9528 </a>
9529 END
9530  
9531  
9532 =head3 prettyStringHtml($node, @context)
9533  
9534 Return a string of L<HTML|https://en.wikipedia.org/wiki/HTML> representing a node of a L<parse|/parse> tree and all the nodes below it if the node is in the specified context.
9535  
9536 Parameter Description
9537 1 $node Node
9538 2 @context Optional context
9539  
9540 B<Example:>
9541  
9542  
9543 my $a = Data::Edit::Xml::new(<<END);
9544 <a id="1">
9545 <b id="2" b="B">
9546 <c/>
9547 </b>
9548 <d id="3" d="D">
9549 Some text
9550 </d>
9551 </a>
9552 END
9553  
9554  
9555 ok $a->prettyStringHtml eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9556  
9557 <div class="xmlLine"><span class="xmlLineStartTag"></span><span class="xmlLt">&lt;</span><span class="xmlTag">a</span> <span class="xmlAttr">id</span><span class="xmlEquals">=</span><span class="xmlValue">"1"</span><span class="xmlGt">&gt;</span></div>
9558 <div class="xmlLine"><span class="xmlLineStartTag">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xmlLt">&lt;</span><span class="xmlTag">b</span> <span class="xmlAttr">b</span><span class="xmlEquals">=</span><span class="xmlValue">"B"</span> <span class="xmlAttr">id</span><span class="xmlEquals">=</span><span class="xmlValue">"2"</span><span class="xmlGt">&gt;</span></div>
9559 <div class="xmlLine"><span class="xmlLineStartTag">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xmlLt">&lt;</span><span class="xmlTag">c</span><span class="xmlSlashGt">/&gt;</span></div>
9560 <div class="xmlLine"><span class="xmlLineStartTag">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xmlLtSlash">&lt;/</span><span class="xmlTag">b</span><span class="xmlGt">&gt;</span></div>
9561 <div class="xmlLine"><span class="xmlLineStartTag">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xmlLt">&lt;</span><span class="xmlTag">d</span> <span class="xmlAttr">d</span><span class="xmlEquals">=</span><span class="xmlValue">"D"</span> <span class="xmlAttr">id</span><span class="xmlEquals">=</span><span class="xmlValue">"3"</span><span class="xmlGt">&gt;</span><span class="xmlText">Some text</span><span class="xmlLtSlash">&lt;/</span><span class="xmlTag">d</span><span class="xmlGt">&gt;</span></div>
9562 <div class="xmlLine"><span class="xmlLineStartTag"></span><span class="xmlLtSlash">&lt;/</span><span class="xmlTag">a</span><span class="xmlGt">&gt;</span></div>
9563 END
9564  
9565  
9566 =head3 prettyStringDitaHeaders($node)
9567  
9568 Return a readable string representing the L<parse|/parse> tree below the specified B<$node> with appropriate headers. Or use L<-x|/opString> $node
9569  
9570 Parameter Description
9571 1 $node Start node
9572  
9573 B<Example:>
9574  
9575  
9576 if (1)
9577 {my $a = Data::Edit::Xml::new(<<END);
9578 <concept/>
9579 END
9580  
9581 ok $a->ditaPrettyPrintWithHeaders eq <<END;
9582 <?xml version="1.0" encoding="UTF-8"?>
9583 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd" []>
9584 <concept/>
9585 END
9586  
9587 }
9588  
9589  
9590 =head3 prettyStringNumbered($node, $depth)
9591  
9592 Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it with a L<number|/number> attached to each tag. The node numbers can then be used as described in L<Order|/Order> to monitor changes to the L<parse|/parse> tree.
9593  
9594 Parameter Description
9595 1 $node Start node
9596 2 $depth Optional depth.
9597  
9598 B<Example:>
9599  
9600  
9601 {my $s = <<END;
9602 <a>
9603 <b>
9604 <A/>
9605 <B/>
9606 </b>
9607 <c>
9608 <C/>
9609 <D/>
9610 </c>
9611 </a>
9612 END
9613  
9614 $a->numberTree;
9615  
9616  
9617 ok $a->prettyStringNumbered eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9618  
9619 <a id="1">
9620 <b id="2">
9621 <A id="3"/>
9622 <B id="4"/>
9623 </b>
9624 <c id="5">
9625 <C id="6"/>
9626 <D id="7"/>
9627 </c>
9628 </a>
9629 END
9630  
9631  
9632 =head3 prettyStringCDATA($node, $depth)
9633  
9634 Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it with the text fields wrapped with <CDATA>...</CDATA>.
9635  
9636 Parameter Description
9637 1 $node Start node
9638 2 $depth Optional depth.
9639  
9640 B<Example:>
9641  
9642  
9643 my $a = Data::Edit::Xml::new("<a><b>A</b></a>");
9644  
9645 my $b = $a->first;
9646  
9647 $b->first->replaceWithBlank;
9648  
9649  
9650 ok $a->prettyStringCDATA eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9651  
9652 <a>
9653 <b><CDATA> </CDATA></b>
9654 </a>
9655 END
9656  
9657  
9658 =head3 prettyStringContent($node)
9659  
9660 Return a readable string representing all the nodes below a node of a L<parse|/parse> tree.
9661  
9662 Parameter Description
9663 1 $node Start node.
9664  
9665 B<Example:>
9666  
9667  
9668 {my $s = <<END;
9669 <a>
9670 <b>
9671 <A/>
9672 <B/>
9673 </b>
9674 <c>
9675 <C/>
9676 <D/>
9677 </c>
9678 </a>
9679 END
9680  
9681  
9682 ok $a->prettyStringContent eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9683  
9684 <b>
9685 <A/>
9686 <B/>
9687 </b>
9688 <c>
9689 <C/>
9690 <D/>
9691 </c>
9692 END
9693  
9694  
9695 =head3 prettyStringContentNumbered($node)
9696  
9697 Return a readable string representing all the nodes below a node of a L<parse|/parse> tree with numbering added.
9698  
9699 Parameter Description
9700 1 $node Start node.
9701  
9702 B<Example:>
9703  
9704  
9705 {my $s = <<END;
9706 <a>
9707 <b>
9708 <c/>
9709 </b>
9710 </a>
9711 END
9712  
9713 my $a = Data::Edit::Xml::new($s);
9714  
9715 $a->numberTree;
9716  
9717  
9718 ok $a->prettyStringContentNumbered eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9719  
9720 <b id="2">
9721 <c id="3"/>
9722 </b>
9723 END
9724  
9725  
9726 ok $a->go(qw(b))->prettyStringContentNumbered eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9727  
9728 <c id="3"/>
9729 END
9730  
9731  
9732 =head3 xmlHeader($string)
9733  
9734 Add the standard L<Xml|https://en.wikipedia.org/wiki/XML> header to a string
9735  
9736 Parameter Description
9737 1 $string String to which a standard L<Xml|https://en.wikipedia.org/wiki/XML> header should be prefixed
9738  
9739 B<Example:>
9740  
9741  
9742  
9743 ok xmlHeader("<a/>") eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9744  
9745 <?xml version="1.0" encoding="UTF-8"?>
9746 <a/>
9747 END
9748  
9749  
9750 This is a static method and so should either be imported or invoked as:
9751  
9752 Data::Edit::Xml::xmlHeader
9753  
9754  
9755 =head2 Html/Json
9756  
9757 Represent the L<parse|/parse> tree using html or Json
9758  
9759 =head3 htmlTables($node)
9760  
9761 Return a string of html representing a L<parse|/parse> tree.
9762  
9763 Parameter Description
9764 1 $node Start node of parse tree
9765  
9766 B<Example:>
9767  
9768  
9769 my $a = Data::Edit::Xml::new(<<END);
9770 <task id="t1">
9771 <title>Title Text</title>
9772 <taskbody>
9773 <context>To add a new configuration:</context>
9774 <steps>
9775 <step><cmd>Click<b>Next</b>to go to the next page</cmd></step>
9776 <step><cmd>On the Ports page, complete the following fields</cmd></step>
9777 <step><cmd>Click to exit without saving</cmd></step>
9778 </steps>
9779 <result>
9780 <p>good!</p>
9781 </result>
9782 </taskbody>
9783 </task>
9784 END
9785  
9786  
9787 ok stringMd5Sum($a->htmlTables =~ s(#\w+) ()gsr) eq q(1e8555c2ea191a54361cbd8cc5baa94b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9788  
9789 ok stringMd5Sum($a->jsonString) eq q(3afa81dc2b2a249834fbac53a1ebd5f1);
9790  
9791  
9792 =head3 jsonString($node)
9793  
9794 Return a Json representation of a parse tree
9795  
9796 Parameter Description
9797 1 $node Start node of parse tree
9798  
9799 B<Example:>
9800  
9801  
9802 my $a = Data::Edit::Xml::new(<<END);
9803 <task id="t1">
9804 <title>Title Text</title>
9805 <taskbody>
9806 <context>To add a new configuration:</context>
9807 <steps>
9808 <step><cmd>Click<b>Next</b>to go to the next page</cmd></step>
9809 <step><cmd>On the Ports page, complete the following fields</cmd></step>
9810 <step><cmd>Click to exit without saving</cmd></step>
9811 </steps>
9812 <result>
9813 <p>good!</p>
9814 </result>
9815 </taskbody>
9816 </task>
9817 END
9818  
9819 ok stringMd5Sum($a->htmlTables =~ s(#\w+) ()gsr) eq q(1e8555c2ea191a54361cbd8cc5baa94b);
9820  
9821 ok stringMd5Sum($a->jsonString) eq q(3afa81dc2b2a249834fbac53a1ebd5f1); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9822  
9823  
9824  
9825 =head3 xmlToJson($xml, $escape)
9826  
9827 Return a Json string representing valid L<Xml|https://en.wikipedia.org/wiki/XML> contained in a file or string, optionally double escaping escape characters.
9828  
9829 Parameter Description
9830 1 $xml File name or string of valid html
9831 2 $escape Double escape the escaped characters if true
9832  
9833 B<Example:>
9834  
9835  
9836 my $x = <<END;
9837 <a a="1">t1
9838 <b b="2" c="3"/>
9839 t2
9840 </a>
9841 END
9842  
9843  
9844 ok xmlToJson($x) eq <<'END'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9845  
9846 {
9847 "attributes" : {
9848 "a" : "1"
9849 },
9850  
9851 "contents" : [
9852 {
9853 "tag" : "CDATA",
9854 "text" : "t1
9855 "
9856 },
9857  
9858 {
9859 "attributes" : {
9860 "b" : "2",
9861 "c" : "3"
9862 },
9863  
9864 "tag" : "b"
9865 },
9866  
9867 {
9868 "tag" : "CDATA",
9869 "text" : "
9870 t2
9871 "
9872 }
9873 ],
9874  
9875 "tag" : "a"
9876 }
9877 END
9878  
9879  
9880 ok xmlToJson($x, 1) eq <<'END'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9881  
9882 {
9883 "attributes" : {
9884 "a" : "1"
9885 },
9886  
9887 "contents" : [
9888 {
9889 "tag" : "CDATA",
9890 "text" : "t1\
9891 "
9892 },
9893  
9894 {
9895 "attributes" : {
9896 "b" : "2",
9897 "c" : "3"
9898 },
9899  
9900 "tag" : "b"
9901 },
9902  
9903 {
9904 "tag" : "CDATA",
9905 "text" : "\
9906 t2\
9907 "
9908 }
9909 ],
9910  
9911 "tag" : "a"
9912 }
9913 END
9914  
9915  
9916 This is a static method and so should either be imported or invoked as:
9917  
9918 Data::Edit::Xml::xmlToJson
9919  
9920  
9921 =head3 jsonToXml($json)
9922  
9923 Convert a json string representing an L<Xml|https://en.wikipedia.org/wiki/XML> parse tree into an L<Xml|https://en.wikipedia.org/wiki/XML> parse tree
9924  
9925 Parameter Description
9926 1 $json Json string
9927  
9928 B<Example:>
9929  
9930  
9931 my $a = Data::Edit::Xml::new(<<END);
9932 <a id="a">
9933 <b id="b" out="out">b1
9934 <c id="c"/>
9935 b2
9936 <d id="d"/>
9937 b3
9938 </b>
9939 </a>
9940 END
9941  
9942 my $json = $a->jsonString;
9943 ok stringMd5Sum($json) eq q(5bb9140c7076978dfd5f600d68a82164);
9944  
9945 ok -p jsonToXml ($json) eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
9946  
9947 <a id="a">
9948 <b id="b" out="out">b1
9949 <c id="c"/>
9950 b2
9951 <d id="d"/>
9952 b3
9953 </b>
9954 </a>
9955 END
9956  
9957  
9958 =head2 Dense
9959  
9960 Print the L<parse|/parse> tree densely for reuse by computers rather than humans.
9961  
9962 =head3 string($node)
9963  
9964 Return a dense string representing a node of a L<parse|/parse> tree and all the nodes below it. Or use L<-s|/opString> B<$node>.
9965  
9966 Parameter Description
9967 1 $node Start node.
9968  
9969 B<Example:>
9970  
9971  
9972 ok -p $a eq <<END;
9973 <a>
9974 <b>
9975 <c id="42" match="mm"/>
9976 </b>
9977 <d>
9978 <e/>
9979 </d>
9980 </a>
9981 END
9982  
9983 ok -s $a eq '<a><b><c id="42" match="mm"/></b><d><e/></d></a>';
9984  
9985  
9986 =head3 stringAsMd5Sum($node)
9987  
9988 Return the L<md5 sum|https://en.wikipedia.org/wiki/MD5> of the dense L<string|/string> representing a node of a L<parse|/parse> tree minus its L<id> and all the nodes below it. Or use L<-g|/opString> B<$node>. The id of the top most node is not included in the md5sum to equate parse trees that would otherwise only differ by the arbitrary root node id value.
9989  
9990 Parameter Description
9991 1 $node Node.
9992  
9993 B<Example:>
9994  
9995  
9996 my $a = Data::Edit::Xml::new(<<END);
9997 <a>
9998 <b>
9999 c
10000 </b>
10001 </a>
10002 END
10003  
10004  
10005 ok $a->stringAsMd5Sum eq q(390bf05d8f5671cc6a4771834840d695); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10006  
10007 ok ((-k $a)->id eq q(GUID-390bf05d-8f56-71cc-6a47-71834840d695));
10008 ok $a->id ne (-k $a->first)->id;
10009  
10010  
10011 =head3 stringQuoted($node)
10012  
10013 Return a quoted string representing a L<parse|/parse> tree a node of a L<parse|/parse> tree and all the nodes below it. Or use L<-o|/opString> B<$node>.
10014  
10015 Parameter Description
10016 1 $node Start node
10017  
10018 B<Example:>
10019  
10020  
10021 {my $s = <<END;
10022 <a>
10023 <b>
10024 <A/>
10025 <B/>
10026 </b>
10027 <c>
10028 <C/>
10029 <D/>
10030 </c>
10031 </a>
10032 END
10033  
10034  
10035 ok $a->stringQuoted eq q('<a><b><A/><B/></b><c><C/><D/></c></a>'); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10036  
10037  
10038  
10039 =head3 stringReplacingIdsWithLabels($node)
10040  
10041 Return a string representing the specified L<parse|/parse> tree with the id attribute of each node set to the L<Labels|/Labels> attached to each node.
10042  
10043 Parameter Description
10044 1 $node Start node.
10045  
10046 B<Example:>
10047  
10048  
10049  
10050 ok $x->stringReplacingIdsWithLabels eq '<a><b><c/></b></a>'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10051  
10052  
10053 $b->addLabels(1..4);
10054  
10055 $c->addLabels(5..8);
10056  
10057  
10058 ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c id="5, 6, 7, 8"/></b></a>'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10059  
10060  
10061  
10062 my $s = $x->stringReplacingIdsWithLabels; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10063  
10064  
10065 ok $s eq '<a><b id="1, 2, 3, 4"><c id="5, 6, 7, 8"/></b></a>';
10066  
10067  
10068 =head3 stringExtendingIdsWithLabels($node)
10069  
10070 Return a string representing the specified L<parse|/parse> tree with the id attribute of each node extended by the L<Labels|/Labels> attached to each node.
10071  
10072 Parameter Description
10073 1 $node Start node.
10074  
10075 B<Example:>
10076  
10077  
10078 {my $a = Data::Edit::Xml::new(<<END);
10079 <a id="a">
10080 <b id="b">
10081 <c id="c"/>
10082 </b>
10083 <b id="B">
10084 <c id="C"/>
10085 </b>
10086 </a>
10087 END
10088  
10089 my $N = 0; $a->by(sub{$_->addLabels((-t $_).++$N)});
10090  
10091  
10092 ok -p (new $a->stringExtendingIdsWithLabels) eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10093  
10094 <a id="a, a5">
10095 <b id="b, b2">
10096 <c id="c, c1"/>
10097 </b>
10098 <b id="B, b4">
10099 <c id="C, c3"/>
10100 </b>
10101 </a>
10102 END
10103  
10104  
10105 =head3 stringContent($node)
10106  
10107 Return a string representing all the nodes below a node of a L<parse|/parse> tree.
10108  
10109 Parameter Description
10110 1 $node Start node.
10111  
10112 B<Example:>
10113  
10114  
10115 {my $s = <<END;
10116 <a>
10117 <b>
10118 <A/>
10119 <B/>
10120 </b>
10121 <c>
10122 <C/>
10123 <D/>
10124 </c>
10125 </a>
10126 END
10127  
10128  
10129 ok $a->stringContent eq "<b><A/><B/></b><c><C/><D/></c>"; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10130  
10131  
10132  
10133 =head3 stringContentOrText($node)
10134  
10135 Return a string representing all the nodes below a node of a L<parse|/parse> tree or the text of the current node if it is a text node.
10136  
10137 Parameter Description
10138 1 $node Start node.
10139  
10140 B<Example:>
10141  
10142  
10143 my $a = Data::Edit::Xml::new(<<END);
10144 <a>AAAA</a>
10145 END
10146  
10147 ok $a->stringContent eq q(AAAA);
10148  
10149 ok $a->stringContentOrText eq q(AAAA); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10150  
10151 ok $a->first__stringContent eq q();
10152 ok $a->first__stringContentOrText eq q(AAAA);
10153  
10154  
10155 =head3 stringNode($node)
10156  
10157 Return a string representing the specified B<$node> showing the attributes, labels and node number.
10158  
10159 Parameter Description
10160 1 $node Node.
10161  
10162 B<Example:>
10163  
10164  
10165 ok $x->stringReplacingIdsWithLabels eq '<a><b><c/></b></a>';
10166  
10167 my $b = $x->go(q(b));
10168  
10169 $b->addLabels(1..2);
10170  
10171 $b->addLabels(3..4);
10172  
10173 ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c/></b></a>';
10174  
10175 $b->numberTree;
10176  
10177  
10178 ok $b->stringNode eq "b(2) 0:1 1:2 2:3 3:4"; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10179  
10180  
10181  
10182 =head3 stringTagsAndText($node)
10183  
10184 Return a string showing just the tags and text at and below a specified B<$node>.
10185  
10186 Parameter Description
10187 1 $node Node.
10188  
10189 B<Example:>
10190  
10191  
10192 if (1)
10193 {my $a = Data::Edit::Xml::new(<<END);
10194 <a>
10195 <b>
10196 <c>cc
10197 <d/>
10198 dd
10199 </c>
10200 </b>
10201 <B>
10202 <c>cc
10203 <d/>
10204 dd
10205 </c>
10206 </B>
10207 </a>
10208 END
10209  
10210 my $b = $a->first_b; my $B = $a->last_B;
10211 my $c = $b->first_c; my $C = $B->first_c;
10212 my $d = $c->first_d; my $D = $C->first_d;
10213  
10214 $a->setDepthProfile;
10215  
10216 ok $b->depthProfileLast eq q(3 3 3 2 1);
10217 ok $b->depthProfileLast eq $B->depthProfileLast;
10218  
10219 # Represent using tags and text
10220 $a->setRepresentationAsTagsAndText;
10221  
10222 is_deeply [$b->stringTagsAndText], [qw(cc d dd c b)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10223  
10224  
10225 is_deeply [$B->stringTagsAndText], [qw(cc d dd c B)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10226  
10227 ok $b->representationLast eq qq(cc d dd c b);
10228 ok $B->representationLast eq qq(cc d dd c B);
10229 ok $c->representationLast eq qq(cc d dd c);
10230 ok $C->representationLast eq qq(cc d dd c);
10231 ok dump($b->representationLast) ne dump($B->representationLast);
10232 is_deeply $c->representationLast,
10233 $C->representationLast;
10234  
10235 my $m = $a->matchNodesByRepresentation;
10236  
10237 my $bb = $b->representationLast;
10238 is_deeply $m->{$bb}, [$b];
10239  
10240 my $cc = $c->representationLast;
10241 is_deeply $m->{$cc}, [$c, $C];
10242  
10243 # Represent using just text
10244 $a->setRepresentationAsText;
10245 is_deeply [$b->stringText], [qw(cc dd)];
10246 is_deeply [$B->stringText], [qw(cc dd)];
10247 ok $b->representationLast eq qq(cc dd);
10248 ok $B->representationLast eq qq(cc dd);
10249 is_deeply $b->representationLast,
10250 $B->representationLast;
10251 is_deeply $c->representationLast,
10252 $C->representationLast;
10253  
10254 my $M = $a->matchNodesByRepresentation;
10255 my $BB = $b->representationLast;
10256 is_deeply $M->{$BB}, [$c, $b, $C, $B];
10257  
10258 my $CC = $c->representationLast;
10259 is_deeply $M->{$BB}, [$c, $b, $C, $B];
10260  
10261 ok $b->representationLast eq $c->representationLast;
10262 }
10263  
10264 if (1)
10265 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
10266 ok $a->first->isOnlyChildText;
10267 }
10268  
10269  
10270 =head3 stringText($node)
10271  
10272 Return a string showing just the text of the text nodes (separated by blanks) at and below a specified B<$node>.
10273  
10274 Parameter Description
10275 1 $node Node.
10276  
10277 B<Example:>
10278  
10279  
10280 if (1)
10281 {my $a = Data::Edit::Xml::new(<<END);
10282 <a>
10283 <b>
10284 <c>cc
10285 <d/>
10286 dd
10287 </c>
10288 </b>
10289 <B>
10290 <c>cc
10291 <d/>
10292 dd
10293 </c>
10294 </B>
10295 </a>
10296 END
10297  
10298 my $b = $a->first_b; my $B = $a->last_B;
10299 my $c = $b->first_c; my $C = $B->first_c;
10300 my $d = $c->first_d; my $D = $C->first_d;
10301  
10302 $a->setDepthProfile;
10303  
10304 ok $b->depthProfileLast eq q(3 3 3 2 1);
10305 ok $b->depthProfileLast eq $B->depthProfileLast;
10306  
10307 # Represent using tags and text
10308 $a->setRepresentationAsTagsAndText;
10309 is_deeply [$b->stringTagsAndText], [qw(cc d dd c b)];
10310 is_deeply [$B->stringTagsAndText], [qw(cc d dd c B)];
10311 ok $b->representationLast eq qq(cc d dd c b);
10312 ok $B->representationLast eq qq(cc d dd c B);
10313 ok $c->representationLast eq qq(cc d dd c);
10314 ok $C->representationLast eq qq(cc d dd c);
10315 ok dump($b->representationLast) ne dump($B->representationLast);
10316 is_deeply $c->representationLast,
10317 $C->representationLast;
10318  
10319 my $m = $a->matchNodesByRepresentation;
10320  
10321 my $bb = $b->representationLast;
10322 is_deeply $m->{$bb}, [$b];
10323  
10324 my $cc = $c->representationLast;
10325 is_deeply $m->{$cc}, [$c, $C];
10326  
10327 # Represent using just text
10328 $a->setRepresentationAsText;
10329  
10330 is_deeply [$b->stringText], [qw(cc dd)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10331  
10332  
10333 is_deeply [$B->stringText], [qw(cc dd)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10334  
10335 ok $b->representationLast eq qq(cc dd);
10336 ok $B->representationLast eq qq(cc dd);
10337 is_deeply $b->representationLast,
10338 $B->representationLast;
10339 is_deeply $c->representationLast,
10340 $C->representationLast;
10341  
10342 my $M = $a->matchNodesByRepresentation;
10343 my $BB = $b->representationLast;
10344 is_deeply $M->{$BB}, [$c, $b, $C, $B];
10345  
10346 my $CC = $c->representationLast;
10347 is_deeply $M->{$BB}, [$c, $b, $C, $B];
10348  
10349 ok $b->representationLast eq $c->representationLast;
10350 }
10351  
10352 if (1)
10353 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
10354 ok $a->first->isOnlyChildText;
10355 }
10356  
10357  
10358 =head3 setRepresentationAsTagsAndText($tree)
10359  
10360 Sets the L<representationLast|/representationLast> for every node in the specified B<$tree> via L<stringTagsAndText|/stringTagsAndText>.
10361  
10362 Parameter Description
10363 1 $tree Tree of nodes.
10364  
10365 B<Example:>
10366  
10367  
10368 if (1)
10369 {my $a = Data::Edit::Xml::new(<<END);
10370 <a>
10371 <b>
10372 <c>cc
10373 <d/>
10374 dd
10375 </c>
10376 </b>
10377 <B>
10378 <c>cc
10379 <d/>
10380 dd
10381 </c>
10382 </B>
10383 </a>
10384 END
10385  
10386 my $b = $a->first_b; my $B = $a->last_B;
10387 my $c = $b->first_c; my $C = $B->first_c;
10388 my $d = $c->first_d; my $D = $C->first_d;
10389  
10390 $a->setDepthProfile;
10391  
10392 ok $b->depthProfileLast eq q(3 3 3 2 1);
10393 ok $b->depthProfileLast eq $B->depthProfileLast;
10394  
10395 # Represent using tags and text
10396  
10397 $a->setRepresentationAsTagsAndText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10398  
10399 is_deeply [$b->stringTagsAndText], [qw(cc d dd c b)];
10400 is_deeply [$B->stringTagsAndText], [qw(cc d dd c B)];
10401 ok $b->representationLast eq qq(cc d dd c b);
10402 ok $B->representationLast eq qq(cc d dd c B);
10403 ok $c->representationLast eq qq(cc d dd c);
10404 ok $C->representationLast eq qq(cc d dd c);
10405 ok dump($b->representationLast) ne dump($B->representationLast);
10406 is_deeply $c->representationLast,
10407 $C->representationLast;
10408  
10409 my $m = $a->matchNodesByRepresentation;
10410  
10411 my $bb = $b->representationLast;
10412 is_deeply $m->{$bb}, [$b];
10413  
10414 my $cc = $c->representationLast;
10415 is_deeply $m->{$cc}, [$c, $C];
10416  
10417 # Represent using just text
10418 $a->setRepresentationAsText;
10419 is_deeply [$b->stringText], [qw(cc dd)];
10420 is_deeply [$B->stringText], [qw(cc dd)];
10421 ok $b->representationLast eq qq(cc dd);
10422 ok $B->representationLast eq qq(cc dd);
10423 is_deeply $b->representationLast,
10424 $B->representationLast;
10425 is_deeply $c->representationLast,
10426 $C->representationLast;
10427  
10428 my $M = $a->matchNodesByRepresentation;
10429 my $BB = $b->representationLast;
10430 is_deeply $M->{$BB}, [$c, $b, $C, $B];
10431  
10432 my $CC = $c->representationLast;
10433 is_deeply $M->{$BB}, [$c, $b, $C, $B];
10434  
10435 ok $b->representationLast eq $c->representationLast;
10436 }
10437  
10438 if (1)
10439 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
10440 ok $a->first->isOnlyChildText;
10441 }
10442  
10443  
10444 =head3 setRepresentationAsText($tree)
10445  
10446 Sets the L<representationLast|/representationLast> for every node in the specified B<$tree> via L<stringText|/stringText>.
10447  
10448 Parameter Description
10449 1 $tree Tree of nodes.
10450  
10451 B<Example:>
10452  
10453  
10454 if (1)
10455 {my $a = Data::Edit::Xml::new(<<END);
10456 <a>
10457 <b>
10458 <c>cc
10459 <d/>
10460 dd
10461 </c>
10462 </b>
10463 <B>
10464 <c>cc
10465 <d/>
10466 dd
10467 </c>
10468 </B>
10469 </a>
10470 END
10471  
10472 my $b = $a->first_b; my $B = $a->last_B;
10473 my $c = $b->first_c; my $C = $B->first_c;
10474 my $d = $c->first_d; my $D = $C->first_d;
10475  
10476 $a->setDepthProfile;
10477  
10478 ok $b->depthProfileLast eq q(3 3 3 2 1);
10479 ok $b->depthProfileLast eq $B->depthProfileLast;
10480  
10481 # Represent using tags and text
10482 $a->setRepresentationAsTagsAndText;
10483 is_deeply [$b->stringTagsAndText], [qw(cc d dd c b)];
10484 is_deeply [$B->stringTagsAndText], [qw(cc d dd c B)];
10485 ok $b->representationLast eq qq(cc d dd c b);
10486 ok $B->representationLast eq qq(cc d dd c B);
10487 ok $c->representationLast eq qq(cc d dd c);
10488 ok $C->representationLast eq qq(cc d dd c);
10489 ok dump($b->representationLast) ne dump($B->representationLast);
10490 is_deeply $c->representationLast,
10491 $C->representationLast;
10492  
10493 my $m = $a->matchNodesByRepresentation;
10494  
10495 my $bb = $b->representationLast;
10496 is_deeply $m->{$bb}, [$b];
10497  
10498 my $cc = $c->representationLast;
10499 is_deeply $m->{$cc}, [$c, $C];
10500  
10501 # Represent using just text
10502  
10503 $a->setRepresentationAsText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10504  
10505 is_deeply [$b->stringText], [qw(cc dd)];
10506 is_deeply [$B->stringText], [qw(cc dd)];
10507 ok $b->representationLast eq qq(cc dd);
10508 ok $B->representationLast eq qq(cc dd);
10509 is_deeply $b->representationLast,
10510 $B->representationLast;
10511 is_deeply $c->representationLast,
10512 $C->representationLast;
10513  
10514 my $M = $a->matchNodesByRepresentation;
10515 my $BB = $b->representationLast;
10516 is_deeply $M->{$BB}, [$c, $b, $C, $B];
10517  
10518 my $CC = $c->representationLast;
10519 is_deeply $M->{$BB}, [$c, $b, $C, $B];
10520  
10521 ok $b->representationLast eq $c->representationLast;
10522 }
10523  
10524 if (1)
10525 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
10526 ok $a->first->isOnlyChildText;
10527 }
10528  
10529  
10530 =head3 matchNodesByRepresentation($tree)
10531  
10532 Creates a hash of arrays of nodes that have the same representation in the specified B<$tree>. Set L<representation|/representationLast> for each node in the tree before calling this method.
10533  
10534 Parameter Description
10535 1 $tree Tree to examine
10536  
10537 B<Example:>
10538  
10539  
10540 if (1)
10541 {my $a = Data::Edit::Xml::new(<<END);
10542 <a>
10543 <b>
10544 <c>cc
10545 <d/>
10546 dd
10547 </c>
10548 </b>
10549 <B>
10550 <c>cc
10551 <d/>
10552 dd
10553 </c>
10554 </B>
10555 </a>
10556 END
10557  
10558 my $b = $a->first_b; my $B = $a->last_B;
10559 my $c = $b->first_c; my $C = $B->first_c;
10560 my $d = $c->first_d; my $D = $C->first_d;
10561  
10562 $a->setDepthProfile;
10563  
10564 ok $b->depthProfileLast eq q(3 3 3 2 1);
10565 ok $b->depthProfileLast eq $B->depthProfileLast;
10566  
10567 # Represent using tags and text
10568 $a->setRepresentationAsTagsAndText;
10569 is_deeply [$b->stringTagsAndText], [qw(cc d dd c b)];
10570 is_deeply [$B->stringTagsAndText], [qw(cc d dd c B)];
10571 ok $b->representationLast eq qq(cc d dd c b);
10572 ok $B->representationLast eq qq(cc d dd c B);
10573 ok $c->representationLast eq qq(cc d dd c);
10574 ok $C->representationLast eq qq(cc d dd c);
10575 ok dump($b->representationLast) ne dump($B->representationLast);
10576 is_deeply $c->representationLast,
10577 $C->representationLast;
10578  
10579  
10580 my $m = $a->matchNodesByRepresentation; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10581  
10582  
10583 my $bb = $b->representationLast;
10584 is_deeply $m->{$bb}, [$b];
10585  
10586 my $cc = $c->representationLast;
10587 is_deeply $m->{$cc}, [$c, $C];
10588  
10589 # Represent using just text
10590 $a->setRepresentationAsText;
10591 is_deeply [$b->stringText], [qw(cc dd)];
10592 is_deeply [$B->stringText], [qw(cc dd)];
10593 ok $b->representationLast eq qq(cc dd);
10594 ok $B->representationLast eq qq(cc dd);
10595 is_deeply $b->representationLast,
10596 $B->representationLast;
10597 is_deeply $c->representationLast,
10598 $C->representationLast;
10599  
10600  
10601 my $M = $a->matchNodesByRepresentation; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10602  
10603 my $BB = $b->representationLast;
10604 is_deeply $M->{$BB}, [$c, $b, $C, $B];
10605  
10606 my $CC = $c->representationLast;
10607 is_deeply $M->{$BB}, [$c, $b, $C, $B];
10608  
10609 ok $b->representationLast eq $c->representationLast;
10610 }
10611  
10612 if (1)
10613 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
10614 ok $a->first->isOnlyChildText;
10615 }
10616  
10617  
10618 =head2 Conditions
10619  
10620 Print a subset of the L<parse|/parse> tree determined by the conditions attached to it.
10621  
10622 =head3 stringWithConditions($node, @conditions)
10623  
10624 Return a string representing the specified B<$node> of a L<parse|/parse> tree and all the nodes below it subject to conditions to select or reject some nodes.
10625  
10626 Parameter Description
10627 1 $node Start node
10628 2 @conditions Conditions to be regarded as in effect.
10629  
10630 B<Example:>
10631  
10632  
10633 my $a = Data::Edit::Xml::new(<<END);
10634 <a>
10635 <b>
10636 <c/>
10637 <d/>
10638 </b>
10639 </a>
10640 END
10641  
10642 my $b = $a >= 'b';
10643  
10644 my ($c, $d) = $b->contents;
10645  
10646 $b->addConditions(qw(bb BB));
10647  
10648 $c->addConditions(qw(cc CC));
10649  
10650  
10651 ok $a->stringWithConditions eq '<a><b><c/><d/></b></a>'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10652  
10653  
10654  
10655 ok $a->stringWithConditions(qw(bb)) eq '<a><b><d/></b></a>'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10656  
10657  
10658  
10659 ok $a->stringWithConditions(qw(cc)) eq '<a/>'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10660  
10661  
10662  
10663 =head3 condition($node, $condition, @context)
10664  
10665 Return the B<$node> if it has the specified B<$condition> and is in the optional B<@context>, else return B<undef>
10666  
10667 Parameter Description
10668 1 $node Node
10669 2 $condition Condition to check
10670 3 @context Optional context
10671  
10672 Use the optional B<@context> parameter to test the context of the specified
10673 B<$node> as understood by method L<at|/at>. If the context is supplied and
10674 B<$node> is not in this context then this method returns B<undef> immediately.
10675  
10676  
10677  
10678 B<Example:>
10679  
10680  
10681 $b->addConditions(qw(bb BB));
10682  
10683 $c->addConditions(qw(cc CC));
10684  
10685  
10686 ok $c->condition(q(cc)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10687  
10688  
10689  
10690 ok !$c->condition(q(dd)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10691  
10692  
10693  
10694 ok $c->condition(q(cc), qw(c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10695  
10696  
10697  
10698 =head3 anyCondition($node, @conditions)
10699  
10700 Return the B<$node> if it has any of the specified B<@conditions>, else return B<undef>
10701  
10702 Parameter Description
10703 1 $node Node
10704 2 @conditions Conditions to check
10705  
10706 B<Example:>
10707  
10708  
10709 $b->addConditions(qw(bb BB));
10710  
10711 $c->addConditions(qw(cc CC));
10712  
10713  
10714 ok $b->anyCondition(qw(bb cc)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10715  
10716  
10717  
10718 ok !$b->anyCondition(qw(cc CC)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10719  
10720  
10721  
10722 =head3 allConditions($node, @conditions)
10723  
10724 Return the B<$node> if it has all of the specified B<@conditions>, else return B<undef>
10725  
10726 Parameter Description
10727 1 $node Node
10728 2 @conditions Conditions to check
10729  
10730 B<Example:>
10731  
10732  
10733 $b->addConditions(qw(bb BB));
10734  
10735 $c->addConditions(qw(cc CC));
10736  
10737  
10738 ok $b->allConditions(qw(bb BB)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10739  
10740  
10741  
10742 ok !$b->allConditions(qw(bb cc)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10743  
10744  
10745  
10746 =head3 addConditions($node, @conditions)
10747  
10748 Given a B<$node> add the specified B<@conditions> and return the node.
10749  
10750 Parameter Description
10751 1 $node Node
10752 2 @conditions Conditions to add.
10753  
10754 B<Example:>
10755  
10756  
10757  
10758 $b->addConditions(qw(bb BB)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10759  
10760  
10761 ok join(' ', $b->listConditions) eq 'BB bb';
10762  
10763  
10764 =head3 deleteConditions($node, @conditions)
10765  
10766 Given a B<$node> delete any B<@conditions> applied to the $node and return the $node.
10767  
10768 Parameter Description
10769 1 $node Node
10770 2 @conditions Conditions to add.
10771  
10772 B<Example:>
10773  
10774  
10775 ok join(' ', $b->listConditions) eq 'BB bb';
10776  
10777  
10778 $b->deleteConditions(qw(BB)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10779  
10780  
10781 ok join(' ', $b->listConditions) eq 'bb';
10782  
10783  
10784 =head3 listConditions($node)
10785  
10786 Return a list of conditions applied to a B<$node>.
10787  
10788 Parameter Description
10789 1 $node Node.
10790  
10791 B<Example:>
10792  
10793  
10794 $b->addConditions(qw(bb BB));
10795  
10796  
10797 ok join(' ', $b->listConditions) eq 'BB bb'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10798  
10799  
10800  
10801 =head1 Attributes
10802  
10803 Get or set the attributes of nodes in the L<parse|/parse> tree. L<Well Known Attributes|/Well Known Attributes> can be set directly via L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>s. To set or get the values of other attributes use L<Get or Set Attributes|/Get or Set Attributes>. To delete or rename attributes see: L<Other Operations on Attributes|/Other Operations on Attributes>.
10804  
10805 =head2 Well Known Attributes
10806  
10807 Get or set these node attributes via L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>s as in:
10808  
10809 $x->href = "#ref";
10810  
10811 =head2 Get or Set Attributes
10812  
10813 Get or set the attributes of nodes.
10814  
10815 =head3 attr($node, $attribute)
10816  
10817 Return the value of an attribute of the current node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>.
10818  
10819 Parameter Description
10820 1 $node Node in parse tree
10821 2 $attribute Attribute name.
10822  
10823 B<Example:>
10824  
10825  
10826 my $x = Data::Edit::Xml::new(my $s = <<END);
10827 <a number="1"/>
10828 END
10829  
10830  
10831 ok $x->attr(qq(number)) == 1; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10832  
10833  
10834  
10835 $x->attr(qq(number)) = 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10836  
10837  
10838  
10839 ok $x->attr(qq(number)) == 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10840  
10841  
10842 ok -s $x eq '<a number="2"/>';
10843  
10844  
10845 =head3 attrX($node, $attribute)
10846  
10847 Return the value of the specified B<$attribute> of the specified B<$node> or B<q()> if the B<$node> does not have such an attribute.
10848  
10849 Parameter Description
10850 1 $node Node in parse tree
10851 2 $attribute Attribute name.
10852  
10853 B<Example:>
10854  
10855  
10856 if (1)
10857 {my $a = Data::Edit::Xml::new(q(<a><b name="bb"/></a>));
10858  
10859 my $b = $a->first;
10860 ok $b->attrX_name eq q(bb);
10861 ok !$b->attrX_bbb;
10862 }
10863  
10864  
10865 =head3 set($node, %values)
10866  
10867 Set the values of some attributes in a node and return the node. Identical in effect to L<setAttr|/setAttr>.
10868  
10869 Parameter Description
10870 1 $node Node in parse tree
10871 2 %values (attribute name=>new value)*
10872  
10873 B<Example:>
10874  
10875  
10876 ok q(<a a="1" b="1" id="aa"/>) eq -s $a;
10877  
10878  
10879 $a->set(a=>11, b=>undef, c=>3, d=>4, e=>5); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10880  
10881  
10882 }
10883  
10884  
10885 =head3 addAttr($node, %values)
10886  
10887 Check the specified B<$node> for the specified B<%attributes> and add any that are not already set. Returns the current node.
10888  
10889 Parameter Description
10890 1 $node Node in parse tree
10891 2 %values (attribute name=>new value)*
10892  
10893 B<Example:>
10894  
10895  
10896 my $a = Data::Edit::Xml::new(q(<a id="a"/>));
10897  
10898  
10899 $a->addAttr(id=>"b", class=>"c"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10900  
10901  
10902 ok -p $a eq qq(<a class="c" id="a"/>
10903 );
10904  
10905  
10906 =head3 setAttr($node, %values)
10907  
10908 Set the values of some attributes in a node and return the node. Identical in effect to L<set|/set>.
10909  
10910 Parameter Description
10911 1 $node Node in parse tree
10912 2 %values (attribute name=>new value)*
10913  
10914 B<Example:>
10915  
10916  
10917 ok -s $x eq '<a number="2"/>';
10918  
10919  
10920 $x->setAttr(first=>1, second=>2, last=>undef); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10921  
10922  
10923 ok -s $x eq '<a first="1" number="2" second="2"/>';
10924  
10925  
10926 =head2 Other Operations on Attributes
10927  
10928 Perform operations other than get or set on the attributes of a node
10929  
10930 =head3 attrs($node, @attributes)
10931  
10932 Return the values of the specified attributes of the current node as a list
10933  
10934 Parameter Description
10935 1 $node Node in parse tree
10936 2 @attributes Attribute names.
10937  
10938 B<Example:>
10939  
10940  
10941 ok -s $x eq '<a first="1" number="2" second="2"/>';
10942  
10943  
10944 is_deeply [$x->attrs(qw(third second first ))], [undef, 2, 1]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10945  
10946  
10947  
10948 =head3 attrCount($node, @exclude)
10949  
10950 Return the number of attributes in the specified B<$node>, optionally ignoring the specified names from the count.
10951  
10952 Parameter Description
10953 1 $node Node in parse tree
10954 2 @exclude Optional attribute names to exclude from the count.
10955  
10956 B<Example:>
10957  
10958  
10959 ok -s $x eq '<a first="1" number="2" second="2"/>';
10960  
10961  
10962 ok $x->attrCount == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10963  
10964  
10965  
10966 ok $x->attrCount(qw(first second third)) == 1; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10967  
10968  
10969  
10970 =head3 getAttrs($node)
10971  
10972 Return a sorted list of all the attributes on the specified B<$node>.
10973  
10974 Parameter Description
10975 1 $node Node in parse tree.
10976  
10977 B<Example:>
10978  
10979  
10980 ok -s $x eq '<a first="1" number="2" second="2"/>';
10981  
10982  
10983 is_deeply [$x->getAttrs], [qw(first number second)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
10984  
10985  
10986  
10987 =head3 deleteAttr($node, $attr, $value)
10988  
10989 Delete the named attribute in the specified B<$node>, optionally check its value first, returning the value of the attribute or B<undef> if the attribute does not exist on this node.
10990  
10991 Parameter Description
10992 1 $node Node
10993 2 $attr Attribute name
10994 3 $value Optional attribute value to check first.
10995  
10996 B<Example:>
10997  
10998  
10999 ok -s $x eq '<a delete="me" number="2"/>';
11000  
11001  
11002 $x->deleteAttr(qq(delete)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11003  
11004  
11005 ok -s $x eq '<a number="2"/>';
11006  
11007  
11008 =head3 deleteAttrs($node, @attrs)
11009  
11010 Delete the specified attributes of the specified B<$node> without checking their values and return the node.
11011  
11012 Parameter Description
11013 1 $node Node
11014 2 @attrs Names of the attributes to delete
11015  
11016 B<Example:>
11017  
11018  
11019 ok -s $x eq '<a first="1" number="2" second="2"/>';
11020  
11021  
11022 $x->deleteAttrs(qw(first second third number)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11023  
11024  
11025 ok -s $x eq '<a/>';
11026  
11027  
11028 =head3 deleteAttrsInTree($node, @attrs)
11029  
11030 Delete the specified attributes of the specified B<$node> and all the nodes under it and return the specified B<$node>.
11031  
11032 Parameter Description
11033 1 $node Node
11034 2 @attrs Names of the attributes to delete
11035  
11036 B<Example:>
11037  
11038  
11039 ok -p $a eq <<END;
11040 <a class="2" id="0">
11041 <b class="1" id="1">
11042 <c class="0" id="0">
11043 <d class="1" id="1"/>
11044 <e class="2" id="0"/>
11045 <e class="0" id="1"/>
11046 <f class="1" id="0"/>
11047 <f class="2" id="1"/>
11048 </c>
11049 </b>
11050 </a>
11051 END
11052  
11053 $a->deleteAttrsInTree_class;
11054  
11055 ok -p $a eq <<END
11056 <a id="0">
11057 <b id="1">
11058 <c id="0">
11059 <d id="1"/>
11060 <e id="0"/>
11061 <e id="1"/>
11062 <f id="0"/>
11063 <f id="1"/>
11064 </c>
11065 </b>
11066 </a>
11067 END
11068  
11069  
11070 =head3 attrsNone($node, @context)
11071  
11072 Check that the specified B<$node> has no attributes. Return the specified $node if no attributes were found else B<undef>. Invented by MfM.
11073  
11074 Parameter Description
11075 1 $node Node
11076 2 @context Optional context
11077  
11078 Use the optional B<@context> parameter to test the context of the specified
11079 B<$node> as understood by method L<at|/at>. If the context is supplied and
11080 B<$node> is not in this context then this method returns B<undef> immediately.
11081  
11082  
11083  
11084 B<Example:>
11085  
11086  
11087 my $a = Data::Edit::Xml::new(q(<a><b/><c id="cc"/></a>));
11088 ok $a->first__attrsNone;
11089 ok !$a->last__attrsNone;
11090  
11091  
11092 =head3 deleteAttrValueAtInTree($tree, $attribute, $value, @context)
11093  
11094 Delete all instances of the specified B<$attribute> with the specified B<$value> in the specified B<@context> in the specified B<$tree> and return the modified B<$tree>. An undefined B<$value> will cause the attribute to be deleted without first confirming its value. An empty context will remove the attribute from every node in the B<$tree>.
11095  
11096 Parameter Description
11097 1 $tree Tree
11098 2 $attribute Attribute name
11099 3 $value Attribute value or B<undef> for all values
11100 4 @context Optional context
11101  
11102 Use the optional B<@context> parameter to test the context of the specified
11103 B<$node> as understood by method L<at|/at>. If the context is supplied and
11104 B<$node> is not in this context then this method returns B<undef> immediately.
11105  
11106  
11107  
11108 B<Example:>
11109  
11110  
11111 my $a = Data::Edit::Xml::new(<<END);
11112 <a>
11113 <b>
11114 <c id="c"/>
11115 <c id="d"/>
11116 </b>
11117 <d>
11118 <c id="c"/>
11119 <c id="d"/>
11120 </d>
11121 </a>
11122 END
11123  
11124 $a->deleteAttrValueAtInTree_id_c_c_b;
11125 ok -p $a eq <<END;
11126 <a>
11127 <b>
11128 <c/>
11129 <c id="d"/>
11130 </b>
11131 <d>
11132 <c id="c"/>
11133 <c id="d"/>
11134 </d>
11135 </a>
11136 END
11137  
11138  
11139 =head3 renameAttr($node, $old, $new, @context)
11140  
11141 Rename attribute B<$old> to B<$new> in the specified B<$node> with optional context B<@context> regardless of whether attribute B<$new> already exists or not and return the B<$node>. To prevent inadvertent changes to an existing attribute use L<changeAttr|/changeAttr>.
11142  
11143 Parameter Description
11144 1 $node Node
11145 2 $old Existing attribute name
11146 3 $new New attribute name
11147 4 @context Optional context.
11148  
11149 Use the optional B<@context> parameter to test the context of the specified
11150 B<$node> as understood by method L<at|/at>. If the context is supplied and
11151 B<$node> is not in this context then this method returns B<undef> immediately.
11152  
11153  
11154  
11155 B<Example:>
11156  
11157  
11158 ok $x->printAttributes eq qq( no="1" word="first");
11159  
11160  
11161 $x->renameAttr(qw(no number)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11162  
11163  
11164 ok $x->printAttributes eq qq( number="1" word="first");
11165  
11166  
11167 =head3 renameAttrXtr($node, @attr)
11168  
11169 Rename the attributes B<@attr> as far as possible to xtrc or xtrf. Returns an array of the attributes that could not be so renamed.
11170  
11171 Parameter Description
11172 1 $node Node
11173 2 @attr Attributes to rename if they exist
11174  
11175 Use the optional B<@context> parameter to test the context of the specified
11176 B<$node> as understood by method L<at|/at>. If the context is supplied and
11177 B<$node> is not in this context then this method returns B<undef> immediately.
11178  
11179  
11180  
11181 B<Example:>
11182  
11183  
11184 my $a = Data::Edit::Xml::new(q(<a a="1" b="2" c="3" d="4"/>));
11185 my @a = $a->renameAttrXtr_a_b_c;
11186 ok -A $a eq q(a c="3" d="4" xtrc="1" xtrf="2");
11187 is_deeply [@a], [qw(c)];
11188  
11189 my $b = Data::Edit::Xml::new(q(<b a="1" b="2" c="3" d="4" xtrf="5"/>));
11190 my @b = $b->renameAttrXtr_a_b_c;
11191 ok -A $b eq q(b b="2" c="3" d="4" xtrc="1" xtrf="5");
11192 is_deeply [@b], [qw(b c)];
11193  
11194  
11195 =head3 changeAttr($node, $old, $new, @context)
11196  
11197 Rename attribute B<$old> to B<$new> in the specified B<$node> with optional context B<@context> unless attribute B<$new> is already set and return the B<$node>. To make changes regardless of whether the new attribute already exists use L<renameAttr|/renameAttr>.
11198  
11199 Parameter Description
11200 1 $node Node
11201 2 $old Existing attribute name
11202 3 $new New attribute name
11203 4 @context Optional context.
11204  
11205 Use the optional B<@context> parameter to test the context of the specified
11206 B<$node> as understood by method L<at|/at>. If the context is supplied and
11207 B<$node> is not in this context then this method returns B<undef> immediately.
11208  
11209  
11210  
11211 B<Example:>
11212  
11213  
11214 ok $x->printAttributes eq qq( number="1" word="first");
11215  
11216  
11217 $x->changeAttr(qw(number word)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11218  
11219  
11220 ok $x->printAttributes eq qq( number="1" word="first");
11221  
11222  
11223 =head3 changeOrDeleteAttr($node, $old, $new, @context)
11224  
11225 Rename attribute B<$old> to B<$new> in the specified B<$node> in the optional B<@context> unless attribute B<$new> is already set in which case delete attribute B<$old>. Return B<$node> regardless of what action was taken. To make changes regardless of whether the new attribute already exists use L<renameAttr|/renameAttr>.
11226  
11227 Parameter Description
11228 1 $node Node
11229 2 $old Existing attribute name
11230 3 $new New attribute name
11231 4 @context Optional context.
11232  
11233 Use the optional B<@context> parameter to test the context of the specified
11234 B<$node> as understood by method L<at|/at>. If the context is supplied and
11235 B<$node> is not in this context then this method returns B<undef> immediately.
11236  
11237  
11238  
11239 B<Example:>
11240  
11241  
11242 my $a = Data::Edit::Xml::new(<<END);
11243 <a a="1"/>
11244 END
11245  
11246 $a->changeOrDeleteAttr_a_b;
11247  
11248 ok -p $a eq <<END;
11249 <a b="1"/>
11250 END
11251  
11252 my $a = Data::Edit::Xml::new(<<END);
11253 <a a="1" b="2"/>
11254 END
11255  
11256 $a->changeOrDeleteAttr_a_b;
11257  
11258 ok -p $a eq <<END;
11259 <a b="2"/>
11260 END
11261  
11262  
11263 =head3 renameAttrValue($node, $old, $oldValue, $new, $newValue, @context)
11264  
11265 Rename attribute B<$old> to B<$new> with new value B<$newValue> in the specified B<$node> in the optional B<@context> regardless of whether attribute B<$new> already exists or not as long as the attribute B<$old> has the value B<$oldValue>. Return the B<$node> regardless of what changes were made. To prevent inadvertent changes to existing attributes use L<changeAttrValue|/changeAttrValue>.
11266  
11267 Parameter Description
11268 1 $node Node
11269 2 $old Existing attribute name
11270 3 $oldValue Existing attribute value
11271 4 $new New attribute name
11272 5 $newValue New attribute value
11273 6 @context Optional context.
11274  
11275 Use the optional B<@context> parameter to test the context of the specified
11276 B<$node> as understood by method L<at|/at>. If the context is supplied and
11277 B<$node> is not in this context then this method returns B<undef> immediately.
11278  
11279  
11280  
11281 B<Example:>
11282  
11283  
11284 ok $x->printAttributes eq qq( number="1" word="first");
11285  
11286  
11287 $x->renameAttrValue(qw(number 1 numeral I)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11288  
11289  
11290 ok $x->printAttributes eq qq( numeral="I" word="first");
11291  
11292  
11293 =head3 changeAttrValue($node, $old, $oldValue, $new, $newValue, @context)
11294  
11295 Rename attribute B<$old> to B<$new> with new value B<$newValue> on the specified B<$node> in the optional B<@context> unless attribute B<$new> is already set or the value of the B<$old> attribute is not B<$oldValue>. Return the B<$node> regardless of what changes were made. To make changes regardless of whether the new attribute already exists use L<renameAttrValue|/renameAttrValue>.
11296  
11297 Parameter Description
11298 1 $node Node
11299 2 $old Existing attribute name
11300 3 $oldValue Existing attribute value
11301 4 $new New attribute name
11302 5 $newValue New attribute value
11303 6 @context Optional context.
11304  
11305 Use the optional B<@context> parameter to test the context of the specified
11306 B<$node> as understood by method L<at|/at>. If the context is supplied and
11307 B<$node> is not in this context then this method returns B<undef> immediately.
11308  
11309  
11310  
11311 B<Example:>
11312  
11313  
11314 ok $x->printAttributes eq qq( numeral="I" word="first");
11315  
11316  
11317 $x->changeAttrValue(qw(word second greek mono)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11318  
11319  
11320 ok $x->printAttributes eq qq( numeral="I" word="first");
11321  
11322  
11323 $x->changeAttrValue(qw(word first greek mono)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11324  
11325  
11326 ok $x->printAttributes eq qq( greek="mono" numeral="I");
11327  
11328  
11329 =head3 changeAttributeValue($node, $attribute, $sub, @context)
11330  
11331 Apply a sub to the value of an attribute of the specified B<$node>. The value to be changed is supplied and returned in: L<$_>.
11332  
11333 Parameter Description
11334 1 $node Node
11335 2 $attribute Attribute name
11336 3 $sub Change sub
11337 4 @context Optional context.
11338  
11339 Use the optional B<@context> parameter to test the context of the specified
11340 B<$node> as understood by method L<at|/at>. If the context is supplied and
11341 B<$node> is not in this context then this method returns B<undef> immediately.
11342  
11343  
11344  
11345 B<Example:>
11346  
11347  
11348 {my $a = Data::Edit::Xml::new(<<END);
11349 <a aa="abc"/>
11350 END
11351  
11352  
11353 $a->changeAttributeValue(q(aa), sub{s(b) (B)}); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11354  
11355  
11356 ok -p $a eq <<END;
11357 <a aa="aBc"/>
11358 END
11359  
11360  
11361 =head3 changeOrDeleteAttrValue($node, $old, $oldValue, $new, $newValue, @context)
11362  
11363 Rename attribute B<$old> to B<$new> with new value B<$newValue> on the specified B<$node> in the optional B<@context> unless attribute B<$new> is already set or the value of the B<$old> attribute is not B<$oldValue> in which cases the B<$old> attribute is deleted. Return the B<$node> regardless of any changes made. To make changes regardless of whether the new attribute already exists use L<renameAttrValue|/renameAttrValue>.
11364  
11365 Parameter Description
11366 1 $node Node
11367 2 $old Existing attribute name
11368 3 $oldValue Existing attribute value
11369 4 $new New attribute name
11370 5 $newValue New attribute value
11371 6 @context Optional context.
11372  
11373 Use the optional B<@context> parameter to test the context of the specified
11374 B<$node> as understood by method L<at|/at>. If the context is supplied and
11375 B<$node> is not in this context then this method returns B<undef> immediately.
11376  
11377  
11378  
11379 B<Example:>
11380  
11381  
11382 my $a = Data::Edit::Xml::new(<<END);
11383 <a a="1"/>
11384 END
11385  
11386 $a->changeOrDeleteAttrValue_a_0_b_1;
11387  
11388 ok -p $a eq <<END;
11389 <a a="1"/>
11390 END
11391  
11392 $a->changeOrDeleteAttrValue_a_1_b_3;
11393  
11394 ok -p $a eq <<END;
11395 <a b="3"/>
11396 END
11397  
11398 my $a = Data::Edit::Xml::new(<<END);
11399 <a a="1" b="2"/>
11400 END
11401  
11402 $a->changeOrDeleteAttrValue_a_0_b_2;
11403 ok -p $a eq <<END;
11404 <a b="2"/>
11405 END
11406  
11407 my $a = Data::Edit::Xml::new(<<END);
11408 <a a="1"/>
11409 END
11410  
11411 $a->changeOrDeleteAttrValue_a_1_b_3;
11412  
11413 ok -p $a eq <<END;
11414 <a b="3"/>
11415 END
11416  
11417  
11418 =head3 copyAttrs($source, $target, @attr)
11419  
11420 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.
11421  
11422 Parameter Description
11423 1 $source Source node
11424 2 $target Target node
11425 3 @attr Optional list of attributes to copy
11426  
11427 B<Example:>
11428  
11429  
11430 {my $x = Data::Edit::Xml::new(<<END);
11431 <x>
11432 <a a="1" b="2"/>
11433 <b b="3" c="4"/>
11434 <c/>
11435 </x>
11436 END
11437  
11438 my ($a, $b, $c) = $x->contents;
11439  
11440  
11441 $a->copyAttrs($b, qw(aa bb)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11442  
11443  
11444 ok <<END eq -p $x;
11445 <x>
11446 <a a="1" b="2"/>
11447 <b b="3" c="4"/>
11448 <c/>
11449 </x>
11450 END
11451  
11452  
11453 $a->copyAttrs($b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11454  
11455  
11456 ok <<END eq -p $x;
11457 <x>
11458 <a a="1" b="2"/>
11459 <b a="1" b="2" c="4"/>
11460 <c/>
11461 </x>
11462 END
11463  
11464  
11465 =head3 copyAttrsFromParent($node, @attr)
11466  
11467 Copy all the attributes from the parent (if there is one) of the current B<$node> to $node or just the named B<@attributes> and return $node. If $node is the top of the parse tree then return B<undef> as it does not have a parent.
11468  
11469 Parameter Description
11470 1 $node Node
11471 2 @attr Attributes to copy from parent
11472  
11473 B<Example:>
11474  
11475  
11476 my $a = Data::Edit::Xml::new(<<END);
11477 <a id="a" a="a">
11478 <b id="b" b="b"/>
11479 </a>
11480 END
11481 my $b = $a->first;
11482 $b->copyAttrsFromParent_id;
11483 ok <<END eq -p $a;
11484 <a a="a" id="a">
11485 <b b="b" id="a"/>
11486 </a>
11487 END
11488  
11489  
11490 $b->copyAttrsFromParent; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11491  
11492  
11493 ok <<END eq -p $a;
11494 <a a="a" id="a">
11495 <b a="a" b="b" id="a"/>
11496 </a>
11497 END
11498  
11499  
11500 =head3 copyAttrsToParent($node, @attr)
11501  
11502 Copy all the attributes of the specified B<$node> to its parent (if there is one) or just the named B<@attributes> and return $node. If $node is the top of the parse tree then return B<undef> as it does not have a parent.
11503  
11504 Parameter Description
11505 1 $node Node
11506 2 @attr Attributes to copy from parent
11507  
11508 B<Example:>
11509  
11510  
11511 my $a = Data::Edit::Xml::new(<<END);
11512 <a a="a">
11513 <b id="b" b="b"/>
11514 </a>
11515 END
11516 my $b = $a->first;
11517 $b->copyAttrsToParent_id;
11518 ok <<END eq -p $a;
11519 <a a="a" id="b">
11520 <b b="b" id="b"/>
11521 </a>
11522 END
11523  
11524  
11525 $b->copyAttrsToParent; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11526  
11527  
11528 ok <<END eq -p $a;
11529 <a a="a" b="b" id="b">
11530 <b b="b" id="b"/>
11531 </a>
11532 END
11533  
11534  
11535 =head3 copyNewAttrs($source, $target, @attr)
11536  
11537 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.
11538  
11539 Parameter Description
11540 1 $source Source node
11541 2 $target Target node
11542 3 @attr Optional list of attributes to copy
11543  
11544 B<Example:>
11545  
11546  
11547 {my $x = Data::Edit::Xml::new(<<END);
11548 <x>
11549 <a a="1" b="2"/>
11550 <b b="3" c="4"/>
11551 <c/>
11552 </x>
11553 END
11554  
11555 my ($a, $b, $c) = $x->contents;
11556  
11557  
11558 $a->copyNewAttrs($b, qw(aa bb)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11559  
11560  
11561 ok <<END eq -p $x;
11562 <x>
11563 <a a="1" b="2"/>
11564 <b b="3" c="4"/>
11565 <c/>
11566 </x>
11567 END
11568  
11569  
11570 $a->copyNewAttrs($b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11571  
11572  
11573 ok <<END eq -p $x;
11574 <x>
11575 <a a="1" b="2"/>
11576 <b a="1" b="3" c="4"/>
11577 <c/>
11578 </x>
11579 END
11580  
11581  
11582 =head3 moveAttrs($source, $target, @attr)
11583  
11584 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.
11585  
11586 Parameter Description
11587 1 $source Source node
11588 2 $target Target node
11589 3 @attr Attributes to move
11590  
11591 B<Example:>
11592  
11593  
11594 {my $x = Data::Edit::Xml::new(<<END);
11595 <x>
11596 <a a="1" b="2"/>
11597 <b b="3" c="4"/>
11598 <c/>
11599 </x>
11600 END
11601  
11602 my ($a, $b, $c) = $x->contents;
11603  
11604  
11605 $a->moveAttrs($c, qw(aa bb)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11606  
11607  
11608 ok <<END eq -p $x;
11609 <x>
11610 <a a="1" b="2"/>
11611 <b a="1" b="2" c="4"/>
11612 <c/>
11613 </x>
11614 END
11615  
11616  
11617 $b->moveAttrs($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11618  
11619  
11620 ok <<END eq -p $x;
11621 <x>
11622 <a a="1" b="2"/>
11623 <b/>
11624 <c a="1" b="2" c="4"/>
11625 </x>
11626 END
11627  
11628  
11629 =head3 moveNewAttrs($source, $target, @attr)
11630  
11631 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.
11632  
11633 Parameter Description
11634 1 $source Source node
11635 2 $target Target node
11636 3 @attr Optional list of attributes to move
11637  
11638 B<Example:>
11639  
11640  
11641 {my $x = Data::Edit::Xml::new(<<END);
11642 <x>
11643 <a a="1" b="2"/>
11644 <b b="3" c="4"/>
11645 <c/>
11646 </x>
11647 END
11648  
11649 my ($a, $b, $c) = $x->contents;
11650  
11651  
11652 $b->moveNewAttrs($c, qw(aa bb)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11653  
11654  
11655 ok <<END eq -p $x;
11656 <x>
11657 <a a="1" b="2"/>
11658 <b a="1" b="3" c="4"/>
11659 <c/>
11660 </x>
11661 END
11662  
11663  
11664 $b->moveNewAttrs($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11665  
11666  
11667 ok <<END eq -p $x;
11668 <x>
11669 <a a="1" b="2"/>
11670 <b/>
11671 <c a="1" b="3" c="4"/>
11672 </x>
11673 END
11674  
11675 ok <<END eq -p $x;
11676 <x>
11677 <c a="1" b="3" c="4"/>
11678 <b/>
11679 <a a="1" b="2"/>
11680 </x>
11681 END
11682  
11683  
11684 =head1 Traversal
11685  
11686 Traverse the L<parse|/parse> tree in various orders applying a B<sub> to each node.
11687  
11688 =head2 Post-order
11689  
11690 This order allows you to edit children before their parents.
11691  
11692 =head3 by($node, $sub)
11693  
11694 Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. A reference to the current node is also made available via L<$_>. This is equivalent to the L<x=|/opBy> operator.
11695  
11696 Parameter Description
11697 1 $node Starting node
11698 2 $sub Sub to call for each sub node
11699  
11700 B<Example:>
11701  
11702  
11703 ok -p $a eq <<END;
11704 <a>
11705 <b>
11706 <c id="42" match="mm"/>
11707 </b>
11708 <d>
11709 <e/>
11710 </d>
11711 </a>
11712 END
11713  
11714  
11715 {my $s; $a->by(sub{$s .= $_->tag}); ok $s eq "cbeda" # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11716  
11717  
11718  
11719 =head3 byX($node, $sub)
11720  
11721 Post-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die|http://perldoc.perl.org/functions/die.html>. The traversal is halted if the called sub does L<die|http://perldoc.perl.org/functions/die.html> on any call with the reason in L<?@|http://perldoc.perl.org/perlvar.html#Error-Variables> The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry> up to the node on which this sub was called. A reference to the current node is also made available via L<$_>.
11722  
11723 Returns the start node regardless of the outcome of calling B<sub>.
11724  
11725 Parameter Description
11726 1 $node Start node
11727 2 $sub Sub to call
11728  
11729 Use the optional B<@context> parameter to test the context of the specified
11730 B<$node> as understood by method L<at|/at>. If the context is supplied and
11731 B<$node> is not in this context then this method returns B<undef> immediately.
11732  
11733  
11734  
11735 B<Example:>
11736  
11737  
11738 ok -p $a eq <<END;
11739 <a>
11740 <b>
11741 <c id="42" match="mm"/>
11742 </b>
11743 <d>
11744 <e/>
11745 </d>
11746 </a>
11747 END
11748  
11749  
11750 {my $s; $a->byX(sub{$s .= $_->tag}); ok $s eq "cbeda" # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11751  
11752  
11753  
11754 sub byX($$) # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11755  
11756 {my ($node, $sub) = @_; # Start node, sub to call
11757 eval {$node->byX2($sub)}; # Trap any errors that occur
11758 $node
11759 }
11760  
11761  
11762 =head3 byList($node, @context)
11763  
11764 Return a list of all the nodes at and below a specified B<$node> in post-order or the empty list if the B<$node> is not in the optional B<@context>.
11765  
11766 Parameter Description
11767 1 $node Starting node
11768 2 @context Optional context
11769  
11770 Use the optional B<@context> parameter to test the context of the specified
11771 B<$node> as understood by method L<at|/at>. If the context is supplied and
11772 B<$node> is not in this context then this method returns B<undef> immediately.
11773  
11774  
11775  
11776 B<Example:>
11777  
11778  
11779 my $a = Data::Edit::Xml::new(<<END);
11780 <a>
11781 <b>
11782 <c id="42" match="mm"/>
11783 </b>
11784 <d>
11785 <e/>
11786 </d>
11787 </a>
11788 END
11789  
11790 ok -c $e eq q(e d a);
11791  
11792 my $a = Data::Edit::Xml::new(<<END);
11793 <a>
11794 <b>
11795 <c/>
11796 <d/>
11797 </b>
11798 <e/>
11799 <f>
11800 <g/>
11801 <h/>
11802 </f>
11803 </a>
11804 END
11805  
11806  
11807 ok q(c d b e g h f a) eq join ' ', map{-t $_} $a->byList; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11808  
11809 ok q(h g f e d c b a) eq join ' ', map{-t $_} $a->byReverseList;
11810 ok q(a b c d e f g h) eq join ' ', map{-t $_} $a->downList;
11811 ok q(a f h g e b d c) eq join ' ', map{-t $_} $a->downReverseList;
11812  
11813  
11814 =head3 byReverse($node, $sub, @context)
11815  
11816 Reverse post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting B<$node>. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
11817  
11818 Parameter Description
11819 1 $node Starting node
11820 2 $sub Sub to call for each sub node
11821 3 @context Accumulated context.
11822  
11823 B<Example:>
11824  
11825  
11826 ok -p $a eq <<END;
11827 <a>
11828 <b>
11829 <c id="42" match="mm"/>
11830 </b>
11831 <d>
11832 <e/>
11833 </d>
11834 </a>
11835 END
11836  
11837  
11838 {my $s; $a->byReverse(sub{$s .= $_->tag}); ok $s eq "edcba" # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11839  
11840  
11841  
11842 =head3 byReverseX($node, $sub, @context)
11843  
11844 Reverse post-order traversal of a L<parse|/parse> tree or sub tree below the specified B<$node> calling the specified B<sub> within L<eval|http://perldoc.perl.org/functions/eval.html>B<{}> at each node and returning the specified starting B<$node>. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
11845  
11846 Parameter Description
11847 1 $node Starting node
11848 2 $sub Sub to call for each sub node
11849 3 @context Accumulated context.
11850  
11851 B<Example:>
11852  
11853  
11854 ok -p $a eq <<END;
11855 <a>
11856 <b>
11857 <c id="42" match="mm"/>
11858 </b>
11859 <d>
11860 <e/>
11861 </d>
11862 </a>
11863 END
11864  
11865 {my $s; $a->byReverse(sub{$s .= $_->tag}); ok $s eq "edcba"
11866  
11867  
11868 =head3 byReverseList($node, @context)
11869  
11870 Return a list of all the nodes at and below a specified B<$node> in reverse preorder or the empty list if the specified B<$node> is not in the optional B<@context>.
11871  
11872 Parameter Description
11873 1 $node Starting node
11874 2 @context Optional context
11875  
11876 Use the optional B<@context> parameter to test the context of the specified
11877 B<$node> as understood by method L<at|/at>. If the context is supplied and
11878 B<$node> is not in this context then this method returns B<undef> immediately.
11879  
11880  
11881  
11882 B<Example:>
11883  
11884  
11885 my $a = Data::Edit::Xml::new(<<END);
11886 <a>
11887 <b>
11888 <c id="42" match="mm"/>
11889 </b>
11890 <d>
11891 <e/>
11892 </d>
11893 </a>
11894 END
11895  
11896  
11897 my ($E, $D, $C, $B) = $a->byReverseList; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11898  
11899  
11900 ok -A $C eq q(c id="42" match="mm");
11901  
11902 my $a = Data::Edit::Xml::new(<<END);
11903 <a>
11904 <b>
11905 <c/>
11906 <d/>
11907 </b>
11908 <e/>
11909 <f>
11910 <g/>
11911 <h/>
11912 </f>
11913 </a>
11914 END
11915  
11916 ok q(c d b e g h f a) eq join ' ', map{-t $_} $a->byList;
11917  
11918 ok q(h g f e d c b a) eq join ' ', map{-t $_} $a->byReverseList; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11919  
11920 ok q(a b c d e f g h) eq join ' ', map{-t $_} $a->downList;
11921 ok q(a f h g e b d c) eq join ' ', map{-t $_} $a->downReverseList;
11922  
11923  
11924 =head2 Pre-order
11925  
11926 This order allows you to edit children after their parents
11927  
11928 =head3 down($node, $sub, @context)
11929  
11930 Pre-order traversal down through a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
11931  
11932 Parameter Description
11933 1 $node Starting node
11934 2 $sub Sub to call for each sub node
11935 3 @context Accumulated context.
11936  
11937 B<Example:>
11938  
11939  
11940  
11941 {my $s; $a->down(sub{$s .= $_->tag}); ok $s eq "abcde" # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11942  
11943  
11944  
11945 =head3 downX($node, $sub)
11946  
11947 Pre-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die|http://perldoc.perl.org/functions/die.html>. The traversal is halted for the entire L<parse|/parse> tree if the called sub does L<die|http://perldoc.perl.org/functions/die.html> with the reason returned in L<?@|http://perldoc.perl.org/perlvar.html#Error-Variables>. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry> up to the node on which this sub was called. A reference to the current node is also made available via L<$_>.
11948  
11949 Returns the start node regardless of the outcome of calling B<sub>.
11950  
11951 Parameter Description
11952 1 $node Start node
11953 2 $sub Sub to call
11954  
11955 B<Example:>
11956  
11957  
11958 {my $s; $a->down(sub{$s .= $_->tag}); ok $s eq "abcde"
11959  
11960  
11961 sub downX($$) # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11962  
11963 {my ($node, $sub) = @_; # Start node, sub to call
11964 eval {$node->downX2($sub)}; # Trap any errors that occur
11965 $node
11966 }
11967  
11968  
11969 =head3 downToDie($node, $sub)
11970  
11971 Pre-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die|http://perldoc.perl.org/functions/die.html>. The traversal of the current sub tree is halted and continue with the next sibling or parent if the called sub does L<die|http://perldoc.perl.org/functions/die.html>. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry> up to the node on which this sub was called. A reference to the current node is also made available via L<$_>.
11972  
11973 Returns the start node regardless of the outcome of calling B<sub>.
11974  
11975 Parameter Description
11976 1 $node Start node
11977 2 $sub Sub to call
11978  
11979 B<Example:>
11980  
11981  
11982  
11983 my $a = Data::Edit::Xml::new(<<END);
11984 <a>
11985 <b>
11986 <c/>
11987 </b>
11988 <d>
11989 <e/>
11990 </d>
11991 </a>
11992 END
11993  
11994 my @a;
11995  
11996 $a->downToDie(sub # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
11997  
11998 {confess if -t $_ eq q(b);
11999 push @a, -t $_;
12000 });
12001  
12002 is_deeply [@a], [qw(a d e)];
12003  
12004 my @b;
12005  
12006 $a->downToDie(sub # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12007  
12008 {confess if -t $_ eq q(c);
12009 push @b, -t $_;
12010 });
12011  
12012 is_deeply [@b], [qw(a b d e)];
12013  
12014  
12015 =head3 downList($node, @context)
12016  
12017 Return a list of all the nodes at and below a specified B<$node> in pre-order or the empty list if the B<$node> is not in the optional B<@context>.
12018  
12019 Parameter Description
12020 1 $node Starting node
12021 2 @context Optional context
12022  
12023 Use the optional B<@context> parameter to test the context of the specified
12024 B<$node> as understood by method L<at|/at>. If the context is supplied and
12025 B<$node> is not in this context then this method returns B<undef> immediately.
12026  
12027  
12028  
12029 B<Example:>
12030  
12031  
12032 my $a = Data::Edit::Xml::new(<<END);
12033 <a>
12034 <b>
12035 <c/>
12036 <d/>
12037 </b>
12038 <e/>
12039 <f>
12040 <g/>
12041 <h/>
12042 </f>
12043 </a>
12044 END
12045  
12046 ok q(c d b e g h f a) eq join ' ', map{-t $_} $a->byList;
12047 ok q(h g f e d c b a) eq join ' ', map{-t $_} $a->byReverseList;
12048  
12049 ok q(a b c d e f g h) eq join ' ', map{-t $_} $a->downList; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12050  
12051 ok q(a f h g e b d c) eq join ' ', map{-t $_} $a->downReverseList;
12052  
12053  
12054 =head3 downReverse($node, $sub, @context)
12055  
12056 Reverse pre-order traversal down through a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
12057  
12058 Parameter Description
12059 1 $node Starting node
12060 2 $sub Sub to call for each sub node
12061 3 @context Accumulated context.
12062  
12063 B<Example:>
12064  
12065  
12066 ok -p $a eq <<END;
12067 <a>
12068 <b>
12069 <c id="42" match="mm"/>
12070 </b>
12071 <d>
12072 <e/>
12073 </d>
12074 </a>
12075 END
12076  
12077  
12078 {my $s; $a->downReverse(sub{$s .= $_->tag}); ok $s eq "adebc" # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12079  
12080  
12081  
12082 =head3 downReverseX($node, $sub, @context)
12083  
12084 Reverse pre-order traversal down through a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval|http://perldoc.perl.org/functions/eval.html>B<{}> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
12085  
12086 Parameter Description
12087 1 $node Starting node
12088 2 $sub Sub to call for each sub node
12089 3 @context Accumulated context.
12090  
12091 B<Example:>
12092  
12093  
12094 ok -p $a eq <<END;
12095 <a>
12096 <b>
12097 <c id="42" match="mm"/>
12098 </b>
12099 <d>
12100 <e/>
12101 </d>
12102 </a>
12103 END
12104  
12105 {my $s; $a->downReverse(sub{$s .= $_->tag}); ok $s eq "adebc"
12106  
12107  
12108 =head3 downReverseList($node, @context)
12109  
12110 Return a list of all the nodes at and below a specified B<$node> in reverse pre-order or the empty list if the B<$node> is not in the optional B<@context>.
12111  
12112 Parameter Description
12113 1 $node Starting node
12114 2 @context Optional context
12115  
12116 Use the optional B<@context> parameter to test the context of the specified
12117 B<$node> as understood by method L<at|/at>. If the context is supplied and
12118 B<$node> is not in this context then this method returns B<undef> immediately.
12119  
12120  
12121  
12122 B<Example:>
12123  
12124  
12125 my $a = Data::Edit::Xml::new(<<END);
12126 <a>
12127 <b>
12128 <c/>
12129 <d/>
12130 </b>
12131 <e/>
12132 <f>
12133 <g/>
12134 <h/>
12135 </f>
12136 </a>
12137 END
12138  
12139 ok q(c d b e g h f a) eq join ' ', map{-t $_} $a->byList;
12140 ok q(h g f e d c b a) eq join ' ', map{-t $_} $a->byReverseList;
12141 ok q(a b c d e f g h) eq join ' ', map{-t $_} $a->downList;
12142  
12143 ok q(a f h g e b d c) eq join ' ', map{-t $_} $a->downReverseList; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12144  
12145  
12146  
12147 =head2 Pre and Post order
12148  
12149 Visit the parent first, then the children, then the parent again.
12150  
12151 =head3 through($node, $before, $after, @context)
12152  
12153 Traverse L<parse|/parse> tree visiting each node twice calling the specified sub B<$before> as we go down past the node and sub B<$after> as we go up past the node, finally return the specified starting node. The subs B<$before, $after> are passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
12154  
12155 Parameter Description
12156 1 $node Starting node
12157 2 $before Sub to call when we meet a node
12158 3 $after Sub to call we leave a node
12159 4 @context Accumulated context.
12160  
12161 B<Example:>
12162  
12163  
12164  
12165 {my $s; my $n = sub{$s .= $_->tag}; $a->through($n, $n); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12166  
12167  
12168 ok $s eq "abccbdeeda"
12169  
12170  
12171 =head3 throughX($node, $before, $after, @context)
12172  
12173 Identical to L<through|/through> except the B<$before, $after> subs are called in an L<eval|http://perldoc.perl.org/functions/eval.html> block to prevent L<die|http://perldoc.perl.org/functions/die.html> terminating the traversal of the full tree.
12174  
12175 Parameter Description
12176 1 $node Starting node
12177 2 $before Sub to call when we meet a node
12178 3 $after Sub to call we leave a node
12179 4 @context Accumulated context.
12180  
12181 B<Example:>
12182  
12183  
12184 {my $s; my $n = sub{$s .= $_->tag}; $a->through($n, $n);
12185  
12186 ok $s eq "abccbdeeda"
12187  
12188  
12189 =head2 Range
12190  
12191 Ranges of nodes
12192  
12193 =head3 from($start, @match)
12194  
12195 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.
12196  
12197 Parameter Description
12198 1 $start Start node
12199 2 @match Optional list of tags to match
12200  
12201 B<Example:>
12202  
12203  
12204 ok -z $a eq <<END;
12205 <a id="1">
12206 <b id="2">
12207 <c id="3">
12208 <e id="4"/>
12209 </c>
12210 <d id="5">
12211 <e id="6"/>
12212 </d>
12213 <c id="7">
12214 <d id="8">
12215 <e id="9"/>
12216 </d>
12217 </c>
12218 <d id="10">
12219 <e id="11"/>
12220 </d>
12221 <c id="12">
12222 <d id="13">
12223 <e id="14"/>
12224 </d>
12225 </c>
12226 </b>
12227 </a>
12228 END
12229  
12230 {my ($d, $c, $D) = $a->findByNumbers(5, 7, 10);
12231  
12232  
12233 my @f = $d->from; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12234  
12235  
12236 ok @f == 4;
12237  
12238 ok $d == $f[0];
12239  
12240  
12241 my @F = $d->from(qw(c)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12242  
12243  
12244 ok @F == 2;
12245  
12246 ok $F[1]->number == 12;
12247  
12248 ok $D == $t[-1];
12249  
12250  
12251 =head3 to($end, @match)
12252  
12253 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.
12254  
12255 Parameter Description
12256 1 $end End node
12257 2 @match Optional list of tags to match
12258  
12259 B<Example:>
12260  
12261  
12262 ok -z $a eq <<END;
12263 <a id="1">
12264 <b id="2">
12265 <c id="3">
12266 <e id="4"/>
12267 </c>
12268 <d id="5">
12269 <e id="6"/>
12270 </d>
12271 <c id="7">
12272 <d id="8">
12273 <e id="9"/>
12274 </d>
12275 </c>
12276 <d id="10">
12277 <e id="11"/>
12278 </d>
12279 <c id="12">
12280 <d id="13">
12281 <e id="14"/>
12282 </d>
12283 </c>
12284 </b>
12285 </a>
12286 END
12287  
12288 {my ($d, $c, $D) = $a->findByNumbers(5, 7, 10);
12289  
12290  
12291 my @t = $D->to; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12292  
12293  
12294 ok @t == 4;
12295  
12296  
12297 my @T = $D->to(qw(c)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12298  
12299  
12300 ok @T == 2;
12301  
12302 ok $T[1]->number == 7;
12303  
12304  
12305 =head3 fromTo($start, $end, @match)
12306  
12307 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.
12308  
12309 Parameter Description
12310 1 $start Start node
12311 2 $end End node
12312 3 @match Optional list of tags to match
12313  
12314 B<Example:>
12315  
12316  
12317 ok -z $a eq <<END;
12318 <a id="1">
12319 <b id="2">
12320 <c id="3">
12321 <e id="4"/>
12322 </c>
12323 <d id="5">
12324 <e id="6"/>
12325 </d>
12326 <c id="7">
12327 <d id="8">
12328 <e id="9"/>
12329 </d>
12330 </c>
12331 <d id="10">
12332 <e id="11"/>
12333 </d>
12334 <c id="12">
12335 <d id="13">
12336 <e id="14"/>
12337 </d>
12338 </c>
12339 </b>
12340 </a>
12341 END
12342  
12343 {my ($d, $c, $D) = $a->findByNumbers(5, 7, 10);
12344  
12345  
12346 my @r = $d->fromTo($D); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12347  
12348  
12349 ok @r == 3;
12350  
12351  
12352 my @R = $d->fromTo($D, qw(c)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12353  
12354  
12355 ok @R == 1;
12356  
12357 ok $R[0]->number == 7;
12358  
12359  
12360 ok !$D->fromTo($d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12361  
12362  
12363  
12364 ok 1 == $d->fromTo($d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12365  
12366  
12367  
12368 =head1 Location
12369  
12370 Locate the line numbers and columns of a specified node and write that information as a L<Oxygen Message|/https://www.oxygenxml.com/doc/versions/20.1/ug-author/topics/linked-output-messages-of-external-engine.html>.
12371  
12372 =head2 lineLocation($node)
12373  
12374 Return the line number.column location of this tag in its source file or string if the source was parsed with the L<line number|/lineNumber> option on.
12375  
12376 Parameter Description
12377 1 $node Node
12378  
12379 B<Example:>
12380  
12381  
12382 my $a = Data::Edit::Xml::new(<<END, lineNumbers=>1, inputFile=>q(aaa.xml));
12383 <?xml version="1.0" encoding="UTF-8"?>
12384 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
12385 <test id="t1">
12386 <title>Test_</title>
12387 <testbody>
12388 <setup>
12389 <p>Place the boiling water and fresh tea in the pot.</p>
12390 </setup>
12391 <checks>
12392 <p>Make sure the pot is on an insulated surface.</p>
12393 </checks>
12394 <run>
12395 <p>Stir with a spoon then let brew for 5 minutes.</p>
12396 </run>
12397 <results>
12398 <p>Pour the tea into a cup.</p>
12399 </results>
12400 <outcome>
12401 <p>An enjoyable cup of tea.</p>
12402 </outcome>
12403 </testbody>
12404 </test>
12405 END
12406  
12407 ok -p $a eq <<END;
12408 <test id="t1" xtrf="3.1:14">
12409 <title xtrf="4.2:8">Test_</title>
12410 <testbody xtrf="5.3:12">
12411 <setup xtrf="6.5:11">
12412 <p xtrf="7.7:9">Place the boiling water and fresh tea in the pot.</p>
12413 </setup>
12414 <checks xtrf="9.5:12">
12415 <p xtrf="10.7:9">Make sure the pot is on an insulated surface.</p>
12416 </checks>
12417 <run xtrf="12.5:9">
12418 <p xtrf="13.7:9">Stir with a spoon then let brew for 5 minutes.</p>
12419 </run>
12420 <results xtrf="15.5:13">
12421 <p xtrf="16.7:9">Pour the tea into a cup.</p>
12422 </results>
12423 <outcome xtrf="18.5:13">
12424 <p xtrf="19.7:9">An enjoyable cup of tea.</p>
12425 </outcome>
12426 </testbody>
12427 </test>
12428 END
12429  
12430 ok $a->go_testbody_run_p__location eq q( on line 13 from 7 to 9 in file: aaa.xml);
12431  
12432 my $p = $a->go_testbody_run_p;
12433 $p->putNext(my $q = $p->newTag_hello);
12434  
12435 ok $p->lineLocation eq q(on line 13 from 7 to 9); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12436  
12437  
12438 ok $q->location eq q( in file: aaa.xml);
12439 ok $q->closestLocation == $p;
12440 ok $q->approxLocation eq q( on line 13 from 7 to 9 in file: aaa.xml);
12441  
12442 ok $q->formatOxygenMessage(q(E), q(), q(Hello detected)) eq <<END;
12443 Type: E
12444 Line: 13
12445 Column: 7
12446 EndLine: 13
12447 EndColumn: 9
12448 AdditionalInfoURL:
12449 Description: Hello detected
12450 END
12451  
12452  
12453 =head2 location($node, $file)
12454  
12455 Return the line number.column plus file location of this tag in its source file or string if the source was parsed with the L<line number|/lineNumber> option on.
12456  
12457 Parameter Description
12458 1 $node Node
12459 2 $file Optionally the location of the source.
12460  
12461 B<Example:>
12462  
12463  
12464 my $a = Data::Edit::Xml::new(<<END, lineNumbers=>1, inputFile=>q(aaa.xml));
12465 <?xml version="1.0" encoding="UTF-8"?>
12466 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
12467 <test id="t1">
12468 <title>Test_</title>
12469 <testbody>
12470 <setup>
12471 <p>Place the boiling water and fresh tea in the pot.</p>
12472 </setup>
12473 <checks>
12474 <p>Make sure the pot is on an insulated surface.</p>
12475 </checks>
12476 <run>
12477 <p>Stir with a spoon then let brew for 5 minutes.</p>
12478 </run>
12479 <results>
12480 <p>Pour the tea into a cup.</p>
12481 </results>
12482 <outcome>
12483 <p>An enjoyable cup of tea.</p>
12484 </outcome>
12485 </testbody>
12486 </test>
12487 END
12488  
12489 ok -p $a eq <<END;
12490 <test id="t1" xtrf="3.1:14">
12491 <title xtrf="4.2:8">Test_</title>
12492 <testbody xtrf="5.3:12">
12493 <setup xtrf="6.5:11">
12494 <p xtrf="7.7:9">Place the boiling water and fresh tea in the pot.</p>
12495 </setup>
12496 <checks xtrf="9.5:12">
12497 <p xtrf="10.7:9">Make sure the pot is on an insulated surface.</p>
12498 </checks>
12499 <run xtrf="12.5:9">
12500 <p xtrf="13.7:9">Stir with a spoon then let brew for 5 minutes.</p>
12501 </run>
12502 <results xtrf="15.5:13">
12503 <p xtrf="16.7:9">Pour the tea into a cup.</p>
12504 </results>
12505 <outcome xtrf="18.5:13">
12506 <p xtrf="19.7:9">An enjoyable cup of tea.</p>
12507 </outcome>
12508 </testbody>
12509 </test>
12510 END
12511  
12512 ok $a->go_testbody_run_p__location eq q( on line 13 from 7 to 9 in file: aaa.xml);
12513  
12514 my $p = $a->go_testbody_run_p;
12515 $p->putNext(my $q = $p->newTag_hello);
12516 ok $p->lineLocation eq q(on line 13 from 7 to 9);
12517  
12518  
12519 ok $q->location eq q( in file: aaa.xml); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12520  
12521 ok $q->closestLocation == $p;
12522 ok $q->approxLocation eq q( on line 13 from 7 to 9 in file: aaa.xml);
12523  
12524 ok $q->formatOxygenMessage(q(E), q(), q(Hello detected)) eq <<END;
12525 Type: E
12526 Line: 13
12527 Column: 7
12528 EndLine: 13
12529 EndColumn: 9
12530 AdditionalInfoURL:
12531 Description: Hello detected
12532 END
12533  
12534  
12535 =head2 closestLocation($node)
12536  
12537 Return the nearest node with line number.column information
12538  
12539 Parameter Description
12540 1 $node Node
12541  
12542 B<Example:>
12543  
12544  
12545 my $a = Data::Edit::Xml::new(<<END, lineNumbers=>1, inputFile=>q(aaa.xml));
12546 <?xml version="1.0" encoding="UTF-8"?>
12547 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
12548 <test id="t1">
12549 <title>Test_</title>
12550 <testbody>
12551 <setup>
12552 <p>Place the boiling water and fresh tea in the pot.</p>
12553 </setup>
12554 <checks>
12555 <p>Make sure the pot is on an insulated surface.</p>
12556 </checks>
12557 <run>
12558 <p>Stir with a spoon then let brew for 5 minutes.</p>
12559 </run>
12560 <results>
12561 <p>Pour the tea into a cup.</p>
12562 </results>
12563 <outcome>
12564 <p>An enjoyable cup of tea.</p>
12565 </outcome>
12566 </testbody>
12567 </test>
12568 END
12569  
12570 ok -p $a eq <<END;
12571 <test id="t1" xtrf="3.1:14">
12572 <title xtrf="4.2:8">Test_</title>
12573 <testbody xtrf="5.3:12">
12574 <setup xtrf="6.5:11">
12575 <p xtrf="7.7:9">Place the boiling water and fresh tea in the pot.</p>
12576 </setup>
12577 <checks xtrf="9.5:12">
12578 <p xtrf="10.7:9">Make sure the pot is on an insulated surface.</p>
12579 </checks>
12580 <run xtrf="12.5:9">
12581 <p xtrf="13.7:9">Stir with a spoon then let brew for 5 minutes.</p>
12582 </run>
12583 <results xtrf="15.5:13">
12584 <p xtrf="16.7:9">Pour the tea into a cup.</p>
12585 </results>
12586 <outcome xtrf="18.5:13">
12587 <p xtrf="19.7:9">An enjoyable cup of tea.</p>
12588 </outcome>
12589 </testbody>
12590 </test>
12591 END
12592  
12593 ok $a->go_testbody_run_p__location eq q( on line 13 from 7 to 9 in file: aaa.xml);
12594  
12595 my $p = $a->go_testbody_run_p;
12596 $p->putNext(my $q = $p->newTag_hello);
12597 ok $p->lineLocation eq q(on line 13 from 7 to 9);
12598  
12599 ok $q->location eq q( in file: aaa.xml);
12600  
12601 ok $q->closestLocation == $p; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12602  
12603 ok $q->approxLocation eq q( on line 13 from 7 to 9 in file: aaa.xml);
12604  
12605 ok $q->formatOxygenMessage(q(E), q(), q(Hello detected)) eq <<END;
12606 Type: E
12607 Line: 13
12608 Column: 7
12609 EndLine: 13
12610 EndColumn: 9
12611 AdditionalInfoURL:
12612 Description: Hello detected
12613 END
12614  
12615  
12616 =head2 approxLocation($node, $file)
12617  
12618 Return the line number.column location of the node nearest to this node in the source file if the source was parsed with the L<line number|/lineNumber> option on.
12619  
12620 Parameter Description
12621 1 $node Node
12622 2 $file Optionally the location of the source.
12623  
12624 B<Example:>
12625  
12626  
12627 my $a = Data::Edit::Xml::new(<<END, lineNumbers=>1, inputFile=>q(aaa.xml));
12628 <?xml version="1.0" encoding="UTF-8"?>
12629 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
12630 <test id="t1">
12631 <title>Test_</title>
12632 <testbody>
12633 <setup>
12634 <p>Place the boiling water and fresh tea in the pot.</p>
12635 </setup>
12636 <checks>
12637 <p>Make sure the pot is on an insulated surface.</p>
12638 </checks>
12639 <run>
12640 <p>Stir with a spoon then let brew for 5 minutes.</p>
12641 </run>
12642 <results>
12643 <p>Pour the tea into a cup.</p>
12644 </results>
12645 <outcome>
12646 <p>An enjoyable cup of tea.</p>
12647 </outcome>
12648 </testbody>
12649 </test>
12650 END
12651  
12652 ok -p $a eq <<END;
12653 <test id="t1" xtrf="3.1:14">
12654 <title xtrf="4.2:8">Test_</title>
12655 <testbody xtrf="5.3:12">
12656 <setup xtrf="6.5:11">
12657 <p xtrf="7.7:9">Place the boiling water and fresh tea in the pot.</p>
12658 </setup>
12659 <checks xtrf="9.5:12">
12660 <p xtrf="10.7:9">Make sure the pot is on an insulated surface.</p>
12661 </checks>
12662 <run xtrf="12.5:9">
12663 <p xtrf="13.7:9">Stir with a spoon then let brew for 5 minutes.</p>
12664 </run>
12665 <results xtrf="15.5:13">
12666 <p xtrf="16.7:9">Pour the tea into a cup.</p>
12667 </results>
12668 <outcome xtrf="18.5:13">
12669 <p xtrf="19.7:9">An enjoyable cup of tea.</p>
12670 </outcome>
12671 </testbody>
12672 </test>
12673 END
12674  
12675 ok $a->go_testbody_run_p__location eq q( on line 13 from 7 to 9 in file: aaa.xml);
12676  
12677 my $p = $a->go_testbody_run_p;
12678 $p->putNext(my $q = $p->newTag_hello);
12679 ok $p->lineLocation eq q(on line 13 from 7 to 9);
12680  
12681 ok $q->location eq q( in file: aaa.xml);
12682 ok $q->closestLocation == $p;
12683  
12684 ok $q->approxLocation eq q( on line 13 from 7 to 9 in file: aaa.xml); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12685  
12686  
12687 ok $q->formatOxygenMessage(q(E), q(), q(Hello detected)) eq <<END;
12688 Type: E
12689 Line: 13
12690 Column: 7
12691 EndLine: 13
12692 EndColumn: 9
12693 AdditionalInfoURL:
12694 Description: Hello detected
12695 END
12696  
12697  
12698 =head2 formatOxygenMessage($node, $level, $url, @message)
12699  
12700 Write an error message in Oxygen format
12701  
12702 Parameter Description
12703 1 $node Node
12704 2 $level Error level [F|E|W]
12705 3 $url Explanatory Url
12706 4 @message Message text
12707  
12708 B<Example:>
12709  
12710  
12711 my $a = Data::Edit::Xml::new(<<END, lineNumbers=>1, inputFile=>q(aaa.xml));
12712 <?xml version="1.0" encoding="UTF-8"?>
12713 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
12714 <test id="t1">
12715 <title>Test_</title>
12716 <testbody>
12717 <setup>
12718 <p>Place the boiling water and fresh tea in the pot.</p>
12719 </setup>
12720 <checks>
12721 <p>Make sure the pot is on an insulated surface.</p>
12722 </checks>
12723 <run>
12724 <p>Stir with a spoon then let brew for 5 minutes.</p>
12725 </run>
12726 <results>
12727 <p>Pour the tea into a cup.</p>
12728 </results>
12729 <outcome>
12730 <p>An enjoyable cup of tea.</p>
12731 </outcome>
12732 </testbody>
12733 </test>
12734 END
12735  
12736 ok -p $a eq <<END;
12737 <test id="t1" xtrf="3.1:14">
12738 <title xtrf="4.2:8">Test_</title>
12739 <testbody xtrf="5.3:12">
12740 <setup xtrf="6.5:11">
12741 <p xtrf="7.7:9">Place the boiling water and fresh tea in the pot.</p>
12742 </setup>
12743 <checks xtrf="9.5:12">
12744 <p xtrf="10.7:9">Make sure the pot is on an insulated surface.</p>
12745 </checks>
12746 <run xtrf="12.5:9">
12747 <p xtrf="13.7:9">Stir with a spoon then let brew for 5 minutes.</p>
12748 </run>
12749 <results xtrf="15.5:13">
12750 <p xtrf="16.7:9">Pour the tea into a cup.</p>
12751 </results>
12752 <outcome xtrf="18.5:13">
12753 <p xtrf="19.7:9">An enjoyable cup of tea.</p>
12754 </outcome>
12755 </testbody>
12756 </test>
12757 END
12758  
12759 ok $a->go_testbody_run_p__location eq q( on line 13 from 7 to 9 in file: aaa.xml);
12760  
12761 my $p = $a->go_testbody_run_p;
12762 $p->putNext(my $q = $p->newTag_hello);
12763 ok $p->lineLocation eq q(on line 13 from 7 to 9);
12764  
12765 ok $q->location eq q( in file: aaa.xml);
12766 ok $q->closestLocation == $p;
12767 ok $q->approxLocation eq q( on line 13 from 7 to 9 in file: aaa.xml);
12768  
12769  
12770 ok $q->formatOxygenMessage(q(E), q(), q(Hello detected)) eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12771  
12772 Type: E
12773 Line: 13
12774 Column: 7
12775 EndLine: 13
12776 EndColumn: 9
12777 AdditionalInfoURL:
12778 Description: Hello detected
12779 END
12780  
12781  
12782 =head1 Position
12783  
12784 Confirm that the position L<navigated|/Navigation> to is the expected position.
12785  
12786 =head2 at($node, @context)
12787  
12788 Confirm that the specified B<$node> has the specified L<ancestry|/ancestry>. Ancestry is specified by providing the expected tags that the B<$node>'s parent, the parent's parent etc. must match at each level. If B<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 B<undef>.
12789  
12790 Parameter Description
12791 1 $node Node
12792 2 @context Ancestry.
12793  
12794 Use the optional B<@context> parameter to test the context of the specified
12795 B<$node> as understood by method L<at|/at>. If the context is supplied and
12796 B<$node> is not in this context then this method returns B<undef> immediately.
12797  
12798  
12799  
12800 B<Example:>
12801  
12802  
12803 {my $a = Data::Edit::Xml::new(<<END);
12804 <a>
12805 <b>
12806 <c> <d/> </c>
12807 <c> <e/> </c>
12808 <c> <f/> </c>
12809 </b>
12810 </a>
12811 END
12812  
12813  
12814 ok $a->go(qw(b c -1 f))->at(qw(f c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12815  
12816  
12817  
12818 ok $a->go(qw(b c 1 e))->at(undef, qr(c|d), undef, qq(a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12819  
12820  
12821 ok $d->context eq q(d c b a);
12822  
12823  
12824 ok $d->at(qw(d c b), undef); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12825  
12826  
12827  
12828 ok !$d->at(qw(d c b), undef, undef); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12829  
12830  
12831  
12832 ok !$d->at(qw(d e b)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12833  
12834  
12835  
12836 =head2 atText($node, $re, @context)
12837  
12838 Confirm that we are on a text node whose text value matches a regular expression in the optional B<@context>. Return the specified B<$node> on success else B<undef>.
12839  
12840 Parameter Description
12841 1 $node Text node
12842 2 $re Regular expression to match
12843 3 @context Context
12844  
12845 Use the optional B<@context> parameter to test the context of the specified
12846 B<$node> as understood by method L<at|/at>. If the context is supplied and
12847 B<$node> is not in this context then this method returns B<undef> immediately.
12848  
12849  
12850  
12851 B<Example:>
12852  
12853  
12854 my $a = Data::Edit::Xml::new(<<END);
12855 <a>abcdcba</a>
12856 END
12857  
12858  
12859 =head2 atStringContentMatches($node, $re, @context)
12860  
12861 Confirm that we are on a B<$node> whose contents, represented as a string, matches the specified regular expression B<$re> in the optional B<@context>. Return the specified B<$node> on success else B<undef>.
12862  
12863 Parameter Description
12864 1 $node Text node
12865 2 $re Regular expression to match
12866 3 @context Context
12867  
12868 Use the optional B<@context> parameter to test the context of the specified
12869 B<$node> as understood by method L<at|/at>. If the context is supplied and
12870 B<$node> is not in this context then this method returns B<undef> immediately.
12871  
12872  
12873  
12874 B<Example:>
12875  
12876  
12877 my $a = Data::Edit::Xml::new(<<END);
12878 <a>
12879 <b>
12880 <c>cc</c>
12881 <d>dd</d>
12882 </b>
12883 </a>
12884 END
12885  
12886 $a->by(sub
12887 {my ($o) = @_;
12888 if (!$o->atStringContentMatches_dd)
12889 {$o->id = "no";
12890 }
12891 });
12892  
12893 ok -p $a eq <<END;
12894 <a>
12895 <b>
12896 <c id="no">cc</c>
12897 <d>dd</d>
12898 </b>
12899 </a>
12900 END
12901  
12902  
12903 =head2 atTop($node)
12904  
12905 Return the current node if it is the root == top of a parse tree else return B<undef>.
12906  
12907 Parameter Description
12908 1 $node Node
12909  
12910 B<Example:>
12911  
12912  
12913 my $a = Data::Edit::Xml::new(<<END);
12914 <a><b/></a>
12915 END
12916  
12917  
12918 ok $a->atTop; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
12919  
12920 ok !$a->first__atTop;
12921  
12922  
12923 =head2 attrAt($node, $attribute, @context)
12924  
12925 Return the specified B<$node> if it has the specified B<$attribute> and the $node is in the optional B<@context> else return B<undef>.
12926  
12927 Parameter Description
12928 1 $node Starting node
12929 2 $attribute Attribute
12930 3 @context Context
12931  
12932 Use the optional B<@context> parameter to test the context of the specified
12933 B<$node> as understood by method L<at|/at>. If the context is supplied and
12934 B<$node> is not in this context then this method returns B<undef> immediately.
12935  
12936  
12937  
12938 B<Example:>
12939  
12940  
12941 if (1)
12942 {my $a = Data::Edit::Xml::new(q(<a><b c="C"/></a>));
12943 my $b = $a->first;
12944 ok !$a->attrAt_id;
12945 ok $b->attrAt_c_b_a;
12946 ok !$b->attrAt_b_b_a;
12947 ok !$b->attrValueAt_c_C_c_a;
12948 ok $b->attrValueAt_c_C_b_a;
12949 }
12950  
12951  
12952 =head2 attrValueAt($node, $attribute, $value, @context)
12953  
12954 Return the specified B<$node> if it has the specified B<$attribute> with the specified B<$value> and the $node is in the optional B<@context> else return B<undef>.
12955  
12956 Parameter Description
12957 1 $node Starting node
12958 2 $attribute Attribute
12959 3 $value Wanted value of attribute
12960 4 @context Context
12961  
12962 Use the optional B<@context> parameter to test the context of the specified
12963 B<$node> as understood by method L<at|/at>. If the context is supplied and
12964 B<$node> is not in this context then this method returns B<undef> immediately.
12965  
12966  
12967  
12968 B<Example:>
12969  
12970  
12971 if (1)
12972 {my $a = Data::Edit::Xml::new(q(<a><b c="C"/></a>));
12973 my $b = $a->first;
12974 ok !$a->attrAt_id;
12975 ok $b->attrAt_c_b_a;
12976 ok !$b->attrAt_b_b_a;
12977 ok !$b->attrValueAt_c_C_c_a;
12978 ok $b->attrValueAt_c_C_b_a;
12979 }
12980  
12981  
12982 =head2 not($node, @tags)
12983  
12984 Return the specified B<$node> if it does not match any of the specified tags, else B<undef>
12985  
12986 Parameter Description
12987 1 $node Node
12988 2 @tags Tags not to match
12989  
12990 B<Example:>
12991  
12992  
12993 {my $a = Data::Edit::Xml::new(<<END);
12994 <a>
12995 <b/>
12996 </a>
12997 END
12998  
12999 ok $a->first->not_a_c;
13000  
13001  
13002 =head2 atOrBelow($start, @context)
13003  
13004 Confirm that the node or one of its ancestors has the specified context as recognized by L<at|/at> and return the first node that matches the context or B<undef> if none do.
13005  
13006 Parameter Description
13007 1 $start Starting node
13008 2 @context Ancestry.
13009  
13010 Use the optional B<@context> parameter to test the context of the specified
13011 B<$node> as understood by method L<at|/at>. If the context is supplied and
13012 B<$node> is not in this context then this method returns B<undef> immediately.
13013  
13014  
13015  
13016 B<Example:>
13017  
13018  
13019 ok $d->context eq q(d c b a);
13020  
13021  
13022 ok $d->atOrBelow(qw(d c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13023  
13024  
13025  
13026 ok $d->atOrBelow(qw( c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13027  
13028  
13029  
13030 ok $d->atOrBelow(qw( b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13031  
13032  
13033  
13034 ok !$d->atOrBelow(qw( c a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13035  
13036  
13037  
13038 =head2 adjacent($first, $second)
13039  
13040 Return the first node if it is adjacent to the second node else B<undef>.
13041  
13042 Parameter Description
13043 1 $first First node
13044 2 $second Second node
13045  
13046 B<Example:>
13047  
13048  
13049 {my $a = Data::Edit::Xml::new(<<END);
13050 <a>
13051 <b>
13052 <c>
13053 <d/>
13054 </c>
13055 </b>
13056 <b>
13057 <c/>
13058 </b>
13059 <e>
13060 <f/>
13061 </e>
13062 </a>
13063 END
13064  
13065 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
13066  
13067  
13068 ok !$a->adjacent($B); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13069  
13070  
13071  
13072 ok $b->adjacent($B); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13073  
13074  
13075  
13076 =head2 ancestry($node)
13077  
13078 Return a list containing: (the specified B<$node>, its parent, its parent's parent etc..). Or use L<upn|/upn> to go up the specified number of levels.
13079  
13080 Parameter Description
13081 1 $node Starting node.
13082  
13083 B<Example:>
13084  
13085  
13086 $a->numberTree;
13087  
13088 ok $a->prettyStringNumbered eq <<END;
13089 <a id="1">
13090 <b id="2">
13091 <A id="3"/>
13092 <B id="4"/>
13093 </b>
13094 <c id="5">
13095 <C id="6"/>
13096 <D id="7"/>
13097 </c>
13098 </a>
13099 END
13100  
13101  
13102 is_deeply [map {-t $_} $a->findByNumber(7)->ancestry], [qw(D c a)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13103  
13104  
13105  
13106 =head2 context($node)
13107  
13108 Return a string containing the tag of the starting node and the tags of all its ancestors separated by single spaces.
13109  
13110 Parameter Description
13111 1 $node Starting node.
13112  
13113 B<Example:>
13114  
13115  
13116 ok -p $a eq <<END;
13117 <a>
13118 <b>
13119 <c id="42" match="mm"/>
13120 </b>
13121 <d>
13122 <e/>
13123 </d>
13124 </a>
13125 END
13126  
13127  
13128 ok $a->go(qw(d e))->context eq 'e d a'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13129  
13130  
13131  
13132 =head2 containsSingleText($node, @context)
13133  
13134 Return the single text element below the specified B<$node> else return B<undef>.
13135  
13136 Parameter Description
13137 1 $node Node
13138 2 @context Optional context
13139  
13140 Use the optional B<@context> parameter to test the context of the specified
13141 B<$node> as understood by method L<at|/at>. If the context is supplied and
13142 B<$node> is not in this context then this method returns B<undef> immediately.
13143  
13144  
13145  
13146 B<Example:>
13147  
13148  
13149 {my $a = Data::Edit::Xml::new("<a><b>bb</b><c>cc<d/>ee</c></a>");
13150  
13151  
13152 ok $a->go(q(b))->containsSingleText->text eq q(bb); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13153  
13154  
13155  
13156 ok !$a->go(q(c))->containsSingleText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13157  
13158  
13159  
13160 =head2 depth($node)
13161  
13162 Returns the depth of the specified B<$node>, the depth of a root node is zero.
13163  
13164 Parameter Description
13165 1 $node Node.
13166  
13167 B<Example:>
13168  
13169  
13170 ok -z $a eq <<END;
13171 <a id="1">
13172 <b id="2">
13173 <c id="3">
13174 <e id="4"/>
13175 </c>
13176 <d id="5">
13177 <e id="6"/>
13178 </d>
13179 <c id="7">
13180 <d id="8">
13181 <e id="9"/>
13182 </d>
13183 </c>
13184 <d id="10">
13185 <e id="11"/>
13186 </d>
13187 <c id="12">
13188 <d id="13">
13189 <e id="14"/>
13190 </d>
13191 </c>
13192 </b>
13193 </a>
13194 END
13195  
13196  
13197 ok 0 == $a->depth; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13198  
13199  
13200  
13201 ok 4 == $a->findByNumber(14)->depth; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13202  
13203  
13204 if (1)
13205 {my $a = Data::Edit::Xml::new(q(<a><b><c><d/></c><e/></b></a>));
13206  
13207 ok -p $a eq <<END;
13208 <a>
13209 <b>
13210 <c>
13211 <d/>
13212 </c>
13213 <e/>
13214 </b>
13215 </a>
13216 END
13217  
13218 my ($d, $c, $e, $b) = $a->byList;
13219 ok $a->height == 4;
13220  
13221 ok $a->depth == 0; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13222  
13223  
13224 ok $c->depth == 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13225  
13226 ok $c->height == 2;
13227  
13228 ok $e->depth == 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13229  
13230 ok $e->height == 1;
13231  
13232 is_deeply [$a->depthProfile], [qw(4 3 3 2 1)];
13233 }
13234  
13235 if (1)
13236 {my $a = Data::Edit::Xml::new(<<END);
13237 <a>
13238 <b>
13239 <c>cc
13240 <d/>
13241 dd
13242 </c>
13243 </b>
13244 <B>
13245 <c>cc
13246 <d/>
13247 dd
13248 </c>
13249 </B>
13250 </a>
13251 END
13252  
13253 my $b = $a->first_b; my $B = $a->last_B;
13254 my $c = $b->first_c; my $C = $B->first_c;
13255 my $d = $c->first_d; my $D = $C->first_d;
13256  
13257 $a->setDepthProfile;
13258  
13259 ok $b->depthProfileLast eq q(3 3 3 2 1);
13260 ok $b->depthProfileLast eq $B->depthProfileLast;
13261  
13262 # Represent using tags and text
13263 $a->setRepresentationAsTagsAndText;
13264 is_deeply [$b->stringTagsAndText], [qw(cc d dd c b)];
13265 is_deeply [$B->stringTagsAndText], [qw(cc d dd c B)];
13266 ok $b->representationLast eq qq(cc d dd c b);
13267 ok $B->representationLast eq qq(cc d dd c B);
13268 ok $c->representationLast eq qq(cc d dd c);
13269 ok $C->representationLast eq qq(cc d dd c);
13270 ok dump($b->representationLast) ne dump($B->representationLast);
13271 is_deeply $c->representationLast,
13272 $C->representationLast;
13273  
13274 my $m = $a->matchNodesByRepresentation;
13275  
13276 my $bb = $b->representationLast;
13277 is_deeply $m->{$bb}, [$b];
13278  
13279 my $cc = $c->representationLast;
13280 is_deeply $m->{$cc}, [$c, $C];
13281  
13282 # Represent using just text
13283 $a->setRepresentationAsText;
13284 is_deeply [$b->stringText], [qw(cc dd)];
13285 is_deeply [$B->stringText], [qw(cc dd)];
13286 ok $b->representationLast eq qq(cc dd);
13287 ok $B->representationLast eq qq(cc dd);
13288 is_deeply $b->representationLast,
13289 $B->representationLast;
13290 is_deeply $c->representationLast,
13291 $C->representationLast;
13292  
13293 my $M = $a->matchNodesByRepresentation;
13294 my $BB = $b->representationLast;
13295 is_deeply $M->{$BB}, [$c, $b, $C, $B];
13296  
13297 my $CC = $c->representationLast;
13298 is_deeply $M->{$BB}, [$c, $b, $C, $B];
13299  
13300 ok $b->representationLast eq $c->representationLast;
13301 }
13302  
13303 if (1)
13304 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
13305 ok $a->first->isOnlyChildText;
13306 }
13307  
13308  
13309 =head2 depthProfile($node)
13310  
13311 Returns the depth profile of the tree rooted at the specified B<$node>.
13312  
13313 Parameter Description
13314 1 $node Node.
13315  
13316 B<Example:>
13317  
13318  
13319 if (1)
13320 {my $a = Data::Edit::Xml::new(q(<a><b><c><d/></c><e/></b></a>));
13321  
13322 ok -p $a eq <<END;
13323 <a>
13324 <b>
13325 <c>
13326 <d/>
13327 </c>
13328 <e/>
13329 </b>
13330 </a>
13331 END
13332  
13333 my ($d, $c, $e, $b) = $a->byList;
13334 ok $a->height == 4;
13335 ok $a->depth == 0;
13336 ok $c->depth == 2;
13337 ok $c->height == 2;
13338 ok $e->depth == 2;
13339 ok $e->height == 1;
13340  
13341  
13342 is_deeply [$a->depthProfile], [qw(4 3 3 2 1)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13343  
13344 }
13345  
13346 if (1)
13347 {my $a = Data::Edit::Xml::new(<<END);
13348 <a>
13349 <b>
13350 <c>cc
13351 <d/>
13352 dd
13353 </c>
13354 </b>
13355 <B>
13356 <c>cc
13357 <d/>
13358 dd
13359 </c>
13360 </B>
13361 </a>
13362 END
13363  
13364 my $b = $a->first_b; my $B = $a->last_B;
13365 my $c = $b->first_c; my $C = $B->first_c;
13366 my $d = $c->first_d; my $D = $C->first_d;
13367  
13368 $a->setDepthProfile;
13369  
13370 ok $b->depthProfileLast eq q(3 3 3 2 1);
13371 ok $b->depthProfileLast eq $B->depthProfileLast;
13372  
13373 # Represent using tags and text
13374 $a->setRepresentationAsTagsAndText;
13375 is_deeply [$b->stringTagsAndText], [qw(cc d dd c b)];
13376 is_deeply [$B->stringTagsAndText], [qw(cc d dd c B)];
13377 ok $b->representationLast eq qq(cc d dd c b);
13378 ok $B->representationLast eq qq(cc d dd c B);
13379 ok $c->representationLast eq qq(cc d dd c);
13380 ok $C->representationLast eq qq(cc d dd c);
13381 ok dump($b->representationLast) ne dump($B->representationLast);
13382 is_deeply $c->representationLast,
13383 $C->representationLast;
13384  
13385 my $m = $a->matchNodesByRepresentation;
13386  
13387 my $bb = $b->representationLast;
13388 is_deeply $m->{$bb}, [$b];
13389  
13390 my $cc = $c->representationLast;
13391 is_deeply $m->{$cc}, [$c, $C];
13392  
13393 # Represent using just text
13394 $a->setRepresentationAsText;
13395 is_deeply [$b->stringText], [qw(cc dd)];
13396 is_deeply [$B->stringText], [qw(cc dd)];
13397 ok $b->representationLast eq qq(cc dd);
13398 ok $B->representationLast eq qq(cc dd);
13399 is_deeply $b->representationLast,
13400 $B->representationLast;
13401 is_deeply $c->representationLast,
13402 $C->representationLast;
13403  
13404 my $M = $a->matchNodesByRepresentation;
13405 my $BB = $b->representationLast;
13406 is_deeply $M->{$BB}, [$c, $b, $C, $B];
13407  
13408 my $CC = $c->representationLast;
13409 is_deeply $M->{$BB}, [$c, $b, $C, $B];
13410  
13411 ok $b->representationLast eq $c->representationLast;
13412 }
13413  
13414 if (1)
13415 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
13416 ok $a->first->isOnlyChildText;
13417 }
13418  
13419  
13420 =head2 setDepthProfile($tree)
13421  
13422 Sets the L<depthProfile|/depthProfile> for every node in the specified B<$tree>. The last set L<depthProfile|/depthProfile> for a specific niode can be retrieved from L<depthProfileLast|/depthProfileLast>.
13423  
13424 Parameter Description
13425 1 $tree Tree of nodes.
13426  
13427 B<Example:>
13428  
13429  
13430 if (1)
13431 {my $a = Data::Edit::Xml::new(<<END);
13432 <a>
13433 <b>
13434 <c>cc
13435 <d/>
13436 dd
13437 </c>
13438 </b>
13439 <B>
13440 <c>cc
13441 <d/>
13442 dd
13443 </c>
13444 </B>
13445 </a>
13446 END
13447  
13448 my $b = $a->first_b; my $B = $a->last_B;
13449 my $c = $b->first_c; my $C = $B->first_c;
13450 my $d = $c->first_d; my $D = $C->first_d;
13451  
13452  
13453 $a->setDepthProfile; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13454  
13455  
13456 ok $b->depthProfileLast eq q(3 3 3 2 1);
13457 ok $b->depthProfileLast eq $B->depthProfileLast;
13458  
13459 # Represent using tags and text
13460 $a->setRepresentationAsTagsAndText;
13461 is_deeply [$b->stringTagsAndText], [qw(cc d dd c b)];
13462 is_deeply [$B->stringTagsAndText], [qw(cc d dd c B)];
13463 ok $b->representationLast eq qq(cc d dd c b);
13464 ok $B->representationLast eq qq(cc d dd c B);
13465 ok $c->representationLast eq qq(cc d dd c);
13466 ok $C->representationLast eq qq(cc d dd c);
13467 ok dump($b->representationLast) ne dump($B->representationLast);
13468 is_deeply $c->representationLast,
13469 $C->representationLast;
13470  
13471 my $m = $a->matchNodesByRepresentation;
13472  
13473 my $bb = $b->representationLast;
13474 is_deeply $m->{$bb}, [$b];
13475  
13476 my $cc = $c->representationLast;
13477 is_deeply $m->{$cc}, [$c, $C];
13478  
13479 # Represent using just text
13480 $a->setRepresentationAsText;
13481 is_deeply [$b->stringText], [qw(cc dd)];
13482 is_deeply [$B->stringText], [qw(cc dd)];
13483 ok $b->representationLast eq qq(cc dd);
13484 ok $B->representationLast eq qq(cc dd);
13485 is_deeply $b->representationLast,
13486 $B->representationLast;
13487 is_deeply $c->representationLast,
13488 $C->representationLast;
13489  
13490 my $M = $a->matchNodesByRepresentation;
13491 my $BB = $b->representationLast;
13492 is_deeply $M->{$BB}, [$c, $b, $C, $B];
13493  
13494 my $CC = $c->representationLast;
13495 is_deeply $M->{$BB}, [$c, $b, $C, $B];
13496  
13497 ok $b->representationLast eq $c->representationLast;
13498 }
13499  
13500 if (1)
13501 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
13502 ok $a->first->isOnlyChildText;
13503 }
13504  
13505  
13506 =head2 height($node)
13507  
13508 Returns the height of the tree rooted at the specified B<$node>.
13509  
13510 Parameter Description
13511 1 $node Node.
13512  
13513 B<Example:>
13514  
13515  
13516 if (1)
13517 {my $a = Data::Edit::Xml::new(q(<a><b><c><d/></c><e/></b></a>));
13518  
13519 ok -p $a eq <<END;
13520 <a>
13521 <b>
13522 <c>
13523 <d/>
13524 </c>
13525 <e/>
13526 </b>
13527 </a>
13528 END
13529  
13530 my ($d, $c, $e, $b) = $a->byList;
13531  
13532 ok $a->height == 4; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13533  
13534 ok $a->depth == 0;
13535 ok $c->depth == 2;
13536  
13537 ok $c->height == 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13538  
13539 ok $e->depth == 2;
13540  
13541 ok $e->height == 1; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13542  
13543  
13544 is_deeply [$a->depthProfile], [qw(4 3 3 2 1)];
13545 }
13546  
13547 if (1)
13548 {my $a = Data::Edit::Xml::new(<<END);
13549 <a>
13550 <b>
13551 <c>cc
13552 <d/>
13553 dd
13554 </c>
13555 </b>
13556 <B>
13557 <c>cc
13558 <d/>
13559 dd
13560 </c>
13561 </B>
13562 </a>
13563 END
13564  
13565 my $b = $a->first_b; my $B = $a->last_B;
13566 my $c = $b->first_c; my $C = $B->first_c;
13567 my $d = $c->first_d; my $D = $C->first_d;
13568  
13569 $a->setDepthProfile;
13570  
13571 ok $b->depthProfileLast eq q(3 3 3 2 1);
13572 ok $b->depthProfileLast eq $B->depthProfileLast;
13573  
13574 # Represent using tags and text
13575 $a->setRepresentationAsTagsAndText;
13576 is_deeply [$b->stringTagsAndText], [qw(cc d dd c b)];
13577 is_deeply [$B->stringTagsAndText], [qw(cc d dd c B)];
13578 ok $b->representationLast eq qq(cc d dd c b);
13579 ok $B->representationLast eq qq(cc d dd c B);
13580 ok $c->representationLast eq qq(cc d dd c);
13581 ok $C->representationLast eq qq(cc d dd c);
13582 ok dump($b->representationLast) ne dump($B->representationLast);
13583 is_deeply $c->representationLast,
13584 $C->representationLast;
13585  
13586 my $m = $a->matchNodesByRepresentation;
13587  
13588 my $bb = $b->representationLast;
13589 is_deeply $m->{$bb}, [$b];
13590  
13591 my $cc = $c->representationLast;
13592 is_deeply $m->{$cc}, [$c, $C];
13593  
13594 # Represent using just text
13595 $a->setRepresentationAsText;
13596 is_deeply [$b->stringText], [qw(cc dd)];
13597 is_deeply [$B->stringText], [qw(cc dd)];
13598 ok $b->representationLast eq qq(cc dd);
13599 ok $B->representationLast eq qq(cc dd);
13600 is_deeply $b->representationLast,
13601 $B->representationLast;
13602 is_deeply $c->representationLast,
13603 $C->representationLast;
13604  
13605 my $M = $a->matchNodesByRepresentation;
13606 my $BB = $b->representationLast;
13607 is_deeply $M->{$BB}, [$c, $b, $C, $B];
13608  
13609 my $CC = $c->representationLast;
13610 is_deeply $M->{$BB}, [$c, $b, $C, $B];
13611  
13612 ok $b->representationLast eq $c->representationLast;
13613 }
13614  
13615 if (1)
13616 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
13617 ok $a->first->isOnlyChildText;
13618 }
13619  
13620  
13621 =head2 isFirst($node, @context)
13622  
13623 Return the specified B<$node> if it is first under its parent and optionally has the specified context, else return B<undef>
13624  
13625 Parameter Description
13626 1 $node Node
13627 2 @context Optional context
13628  
13629 Use the optional B<@context> parameter to test the context of the specified
13630 B<$node> as understood by method L<at|/at>. If the context is supplied and
13631 B<$node> is not in this context then this method returns B<undef> immediately.
13632  
13633 Use B<isFirstNonBlank> to skip a (rare) initial blank text CDATA. Use B<isFirstNonBlankX> to die rather
13634 then receive a returned B<undef> or false result.
13635  
13636  
13637  
13638 B<Example:>
13639  
13640  
13641 ok -p $a eq <<END;
13642 <a>
13643 <b>
13644 <c id="42" match="mm"/>
13645 </b>
13646 <d>
13647 <e/>
13648 </d>
13649 </a>
13650 END
13651  
13652  
13653 ok $a->go(q(b))->isFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13654  
13655  
13656 {my $a = Data::Edit::Xml::new(<<END);
13657 <a>
13658 <b>
13659 <c>
13660 <d/>
13661 </c>
13662 </b>
13663 <b>
13664 <c/>
13665 </b>
13666 <e>
13667 <f/>
13668 </e>
13669 </a>
13670 END
13671  
13672 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
13673  
13674  
13675 ok $a->isFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13676  
13677  
13678  
13679 =head2 isNotFirst($node, @context)
13680  
13681 Return the specified B<$node> if it is not first under its parent and optionally has the specified context, else return B<undef>
13682  
13683 Parameter Description
13684 1 $node Node
13685 2 @context Optional context
13686  
13687 Use the optional B<@context> parameter to test the context of the specified
13688 B<$node> as understood by method L<at|/at>. If the context is supplied and
13689 B<$node> is not in this context then this method returns B<undef> immediately.
13690  
13691  
13692  
13693 B<Example:>
13694  
13695  
13696 my $a = Data::Edit::Xml::new(<<END);
13697 <a><b/><c/><d/></a>
13698 END
13699  
13700 my ($b, $c, $d) = $a->byList;
13701  
13702 ok $c->isNotFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13703  
13704 ok $b->isNotLast;
13705  
13706  
13707 =head2 isFirstN($node, $N, @context)
13708  
13709 Return the first B<$N> nodes as an array if the first B<$N> tags of the parent of B<$node> finish at the specified B<$node> and have the specified tags in the sequence specified by B<@context>. If B<@context> contains more then B<$N> entries, the remainder are checked as the context of the parent of B<$node>. Returns an array of nodes found or an empty array if the specified B<$node> does not match these conditions.
13710  
13711 Parameter Description
13712 1 $node Node
13713 2 $N Number of tags to be first
13714 3 @context First tags and optional context
13715  
13716 Use the optional B<@context> parameter to test the context of the specified
13717 B<$node> as understood by method L<at|/at>. If the context is supplied and
13718 B<$node> is not in this context then this method returns B<undef> immediately.
13719  
13720  
13721  
13722 B<Example:>
13723  
13724  
13725 my $x = Data::Edit::Xml::new(<<END);
13726 <x>
13727 <a/>
13728 <b/>
13729 <c/>
13730 <d/>
13731 <e/>
13732 </x>
13733 END
13734  
13735 my ($a, $b, $c, $d, $e) = $x->byList;
13736  
13737 is_deeply [$b->isFirstN_2_a_b_x], [$a, $b];
13738 ok !$b->isFirstN_2_b_x;
13739  
13740 is_deeply [$d->isLastN_2_d_e_x], [$d, $e];
13741 ok !$d->isLastN_2_d_x;
13742  
13743 is_deeply [$b->nextN_3_b_c_d], [$b, $c, $d];
13744 is_deeply [$d->prevN_3_b_c_d], [$b, $c, $d];
13745  
13746  
13747 =head2 isFirstToDepth($node, $depth, @context)
13748  
13749 Return the specified B<$node> if it is first to the specified depth else return B<undef>
13750  
13751 Parameter Description
13752 1 $node Node
13753 2 $depth Depth
13754 3 @context Optional context
13755  
13756 Use the optional B<@context> parameter to test the context of the specified
13757 B<$node> as understood by method L<at|/at>. If the context is supplied and
13758 B<$node> is not in this context then this method returns B<undef> immediately.
13759  
13760  
13761  
13762 B<Example:>
13763  
13764  
13765 {my $a = Data::Edit::Xml::new(<<END);
13766 <a>
13767 <b>
13768 <c>
13769 <d/>
13770 </c>
13771 </b>
13772 <e>
13773 <f/>
13774 </e>
13775 </a>
13776 END
13777  
13778 my ($d, $c, $b, $f, $e) = $a->byList;
13779  
13780  
13781 ok $d->isFirstToDepth(4); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13782  
13783  
13784  
13785 ok !$f->isFirstToDepth(2); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13786  
13787  
13788  
13789 ok $f->isFirstToDepth(1); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13790  
13791  
13792  
13793 ok !$f->isFirstToDepth(3); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13794  
13795  
13796  
13797 =head2 firstIs($node, @context)
13798  
13799 Return the specified B<$node> if it has one or more child nodes and the first child node has the specified B<@context> otherwise B<undef>.
13800  
13801 Parameter Description
13802 1 $node Node
13803 2 @context Optional context
13804  
13805 Use the optional B<@context> parameter to test the context of the specified
13806 B<$node> as understood by method L<at|/at>. If the context is supplied and
13807 B<$node> is not in this context then this method returns B<undef> immediately.
13808  
13809  
13810  
13811 B<Example:>
13812  
13813  
13814 my $a = Data::Edit::Xml::new(<<END);
13815 <a>
13816 <b/><c/><d/><e/>
13817 </a>
13818 END
13819  
13820 ok $a->go_c__nextIs_d;
13821 ok !$a->go_c__nextIs_c;
13822 ok $a->go_c__prevIs_b;
13823 ok !$a->go_c__prevIs_e;
13824  
13825 ok $a->firstIs_b;
13826 ok !$a->firstIs_c;
13827  
13828 ok $a->lastIs_e;
13829 ok !$a->lastIs_d;
13830  
13831  
13832 =head2 isLast($node, @context)
13833  
13834 Return the specified B<$node> if it is last under its parent and optionally has the specified context, else return B<undef>
13835  
13836 Parameter Description
13837 1 $node Node
13838 2 @context Optional context
13839  
13840 Use the optional B<@context> parameter to test the context of the specified
13841 B<$node> as understood by method L<at|/at>. If the context is supplied and
13842 B<$node> is not in this context then this method returns B<undef> immediately.
13843  
13844 Use B<isLastNonBlank> to skip a (rare) initial blank text CDATA. Use B<isLastNonBlankX> to die rather
13845 then receive a returned B<undef> or false result.
13846  
13847  
13848  
13849 B<Example:>
13850  
13851  
13852 ok -p $a eq <<END;
13853 <a>
13854 <b>
13855 <c id="42" match="mm"/>
13856 </b>
13857 <d>
13858 <e/>
13859 </d>
13860 </a>
13861 END
13862  
13863  
13864 ok $a->go(q(d))->isLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13865  
13866  
13867 {my $a = Data::Edit::Xml::new(<<END);
13868 <a>
13869 <b>
13870 <c>
13871 <d/>
13872 </c>
13873 </b>
13874 <b>
13875 <c/>
13876 </b>
13877 <e>
13878 <f/>
13879 </e>
13880 </a>
13881 END
13882  
13883 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
13884  
13885  
13886 ok $a->isLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13887  
13888  
13889  
13890 =head2 isNotLast($node, @context)
13891  
13892 Return the specified B<$node> if it is not last under its parent and optionally has the specified context, else return B<undef>
13893  
13894 Parameter Description
13895 1 $node Node
13896 2 @context Optional context
13897  
13898 Use the optional B<@context> parameter to test the context of the specified
13899 B<$node> as understood by method L<at|/at>. If the context is supplied and
13900 B<$node> is not in this context then this method returns B<undef> immediately.
13901  
13902  
13903  
13904 B<Example:>
13905  
13906  
13907 my $a = Data::Edit::Xml::new(<<END);
13908 <a><b/><c/><d/></a>
13909 END
13910  
13911 my ($b, $c, $d) = $a->byList;
13912 ok $c->isNotFirst;
13913  
13914 ok $b->isNotLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13915  
13916  
13917  
13918 =head2 isLastN($node, $N, @context)
13919  
13920 Return the last B<$N> nodes as an array if the last B<$N> tags of the parent of B<$node> start at the specified B<$node> and have the specified tags in the sequence specified by B<@context>. If B<@context> contains more then B<$N> entries, the remainder are checked as the context of the parent of B<$node>. Returns an array of nodes found or an empty array if the specified B<$node> does not match these conditions.
13921  
13922 Parameter Description
13923 1 $node Node
13924 2 $N Number of tags to be last
13925 3 @context Last tags and optional context
13926  
13927 Use the optional B<@context> parameter to test the context of the specified
13928 B<$node> as understood by method L<at|/at>. If the context is supplied and
13929 B<$node> is not in this context then this method returns B<undef> immediately.
13930  
13931  
13932  
13933 B<Example:>
13934  
13935  
13936 my $x = Data::Edit::Xml::new(<<END);
13937 <x>
13938 <a/>
13939 <b/>
13940 <c/>
13941 <d/>
13942 <e/>
13943 </x>
13944 END
13945  
13946 my ($a, $b, $c, $d, $e) = $x->byList;
13947  
13948 is_deeply [$b->isFirstN_2_a_b_x], [$a, $b];
13949 ok !$b->isFirstN_2_b_x;
13950  
13951 is_deeply [$d->isLastN_2_d_e_x], [$d, $e];
13952 ok !$d->isLastN_2_d_x;
13953  
13954 is_deeply [$b->nextN_3_b_c_d], [$b, $c, $d];
13955 is_deeply [$d->prevN_3_b_c_d], [$b, $c, $d];
13956  
13957  
13958 =head2 isLastToDepth($node, $depth, @context)
13959  
13960 Return the specified B<$node> if it is last to the specified depth else return B<undef>
13961  
13962 Parameter Description
13963 1 $node Node
13964 2 $depth Depth
13965 3 @context Optional context
13966  
13967 Use the optional B<@context> parameter to test the context of the specified
13968 B<$node> as understood by method L<at|/at>. If the context is supplied and
13969 B<$node> is not in this context then this method returns B<undef> immediately.
13970  
13971  
13972  
13973 B<Example:>
13974  
13975  
13976 {my $a = Data::Edit::Xml::new(<<END);
13977 <a>
13978 <b>
13979 <c>
13980 <d/>
13981 </c>
13982 </b>
13983 <e>
13984 <f/>
13985 </e>
13986 </a>
13987 END
13988  
13989 my ($d, $c, $b, $f, $e) = $a->byList;
13990  
13991  
13992 ok $c->isLastToDepth(1); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13993  
13994  
13995  
13996 ok !$c->isLastToDepth(3); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
13997  
13998  
13999  
14000 ok $d->isLastToDepth(2); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14001  
14002  
14003  
14004 ok !$d->isLastToDepth(4); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14005  
14006  
14007  
14008 =head2 lastIs($node, @context)
14009  
14010 Return the specified B<$node> if it has one or more child nodes and the last child node has the specified B<@context> otherwise B<undef>.
14011  
14012 Parameter Description
14013 1 $node Node
14014 2 @context Optional context
14015  
14016 Use the optional B<@context> parameter to test the context of the specified
14017 B<$node> as understood by method L<at|/at>. If the context is supplied and
14018 B<$node> is not in this context then this method returns B<undef> immediately.
14019  
14020  
14021  
14022 B<Example:>
14023  
14024  
14025 my $a = Data::Edit::Xml::new(<<END);
14026 <a>
14027 <b/><c/><d/><e/>
14028 </a>
14029 END
14030  
14031 ok $a->go_c__nextIs_d;
14032 ok !$a->go_c__nextIs_c;
14033 ok $a->go_c__prevIs_b;
14034 ok !$a->go_c__prevIs_e;
14035  
14036 ok $a->firstIs_b;
14037 ok !$a->firstIs_c;
14038  
14039 ok $a->lastIs_e;
14040 ok !$a->lastIs_d;
14041  
14042  
14043 =head2 nextIs($node, @context)
14044  
14045 Return the specified B<$node> if there is a following node with the specified B<@context>. Returns B<undef> if the $node is last.
14046  
14047 Parameter Description
14048 1 $node Node
14049 2 @context Optional context
14050  
14051 Use the optional B<@context> parameter to test the context of the specified
14052 B<$node> as understood by method L<at|/at>. If the context is supplied and
14053 B<$node> is not in this context then this method returns B<undef> immediately.
14054  
14055  
14056  
14057 B<Example:>
14058  
14059  
14060 my $a = Data::Edit::Xml::new(<<END);
14061 <a>
14062 <b/><c/><d/><e/>
14063 </a>
14064 END
14065  
14066 ok $a->go_c__nextIs_d;
14067 ok !$a->go_c__nextIs_c;
14068 ok $a->go_c__prevIs_b;
14069 ok !$a->go_c__prevIs_e;
14070  
14071 ok $a->firstIs_b;
14072 ok !$a->firstIs_c;
14073  
14074 ok $a->lastIs_e;
14075 ok !$a->lastIs_d;
14076  
14077  
14078 =head2 nextN($node, $N, @context)
14079  
14080 Return B<$N> nodes as an array starting at B<$node> inclusive if they match the first B<$N> tags of B<@context>. If B<@context> contains more then B<$N> entries, the remainder are checked as the context of the parent of B<$node>. Returns an array of nodes found or an empty array if the specified B<$node> does not match these conditions.
14081  
14082 Parameter Description
14083 1 $node Node
14084 2 $N Number of tags to be last
14085 3 @context Last tags and optional context
14086  
14087 Use the optional B<@context> parameter to test the context of the specified
14088 B<$node> as understood by method L<at|/at>. If the context is supplied and
14089 B<$node> is not in this context then this method returns B<undef> immediately.
14090  
14091  
14092  
14093 B<Example:>
14094  
14095  
14096 my $x = Data::Edit::Xml::new(<<END);
14097 <x>
14098 <a/>
14099 <b/>
14100 <c/>
14101 <d/>
14102 <e/>
14103 </x>
14104 END
14105  
14106 my ($a, $b, $c, $d, $e) = $x->byList;
14107  
14108 is_deeply [$b->isFirstN_2_a_b_x], [$a, $b];
14109 ok !$b->isFirstN_2_b_x;
14110  
14111 is_deeply [$d->isLastN_2_d_e_x], [$d, $e];
14112 ok !$d->isLastN_2_d_x;
14113  
14114 is_deeply [$b->nextN_3_b_c_d], [$b, $c, $d];
14115 is_deeply [$d->prevN_3_b_c_d], [$b, $c, $d];
14116  
14117  
14118 =head2 prevIs($node, @context)
14119  
14120 Return the specified B<$node> if there is a previous node with the specified B<@context>. Returns B<undef> if the $node is first.
14121  
14122 Parameter Description
14123 1 $node Node
14124 2 @context Optional context
14125  
14126 Use the optional B<@context> parameter to test the context of the specified
14127 B<$node> as understood by method L<at|/at>. If the context is supplied and
14128 B<$node> is not in this context then this method returns B<undef> immediately.
14129  
14130  
14131  
14132 B<Example:>
14133  
14134  
14135 my $a = Data::Edit::Xml::new(<<END);
14136 <a>
14137 <b/><c/><d/><e/>
14138 </a>
14139 END
14140  
14141 ok $a->go_c__nextIs_d;
14142 ok !$a->go_c__nextIs_c;
14143 ok $a->go_c__prevIs_b;
14144 ok !$a->go_c__prevIs_e;
14145  
14146 ok $a->firstIs_b;
14147 ok !$a->firstIs_c;
14148  
14149 ok $a->lastIs_e;
14150 ok !$a->lastIs_d;
14151  
14152  
14153 =head2 prevN($node, $N, @context)
14154  
14155 Return B<$N> nodes as an array ending at B<$node> inclusive if they match the first B<$N> tags of B<@context>. If B<@context> contains more then B<$N> entries, the remainder are checked as the context of the parent of B<$node>. Returns an array of nodes found or an empty array if the specified B<$node> does not match these conditions.
14156  
14157 Parameter Description
14158 1 $node Node
14159 2 $N Number of tags to be first
14160 3 @context First tags and optional context
14161  
14162 Use the optional B<@context> parameter to test the context of the specified
14163 B<$node> as understood by method L<at|/at>. If the context is supplied and
14164 B<$node> is not in this context then this method returns B<undef> immediately.
14165  
14166  
14167  
14168 B<Example:>
14169  
14170  
14171 my $x = Data::Edit::Xml::new(<<END);
14172 <x>
14173 <a/>
14174 <b/>
14175 <c/>
14176 <d/>
14177 <e/>
14178 </x>
14179 END
14180  
14181 my ($a, $b, $c, $d, $e) = $x->byList;
14182  
14183 is_deeply [$b->isFirstN_2_a_b_x], [$a, $b];
14184 ok !$b->isFirstN_2_b_x;
14185  
14186 is_deeply [$d->isLastN_2_d_e_x], [$d, $e];
14187 ok !$d->isLastN_2_d_x;
14188  
14189 is_deeply [$b->nextN_3_b_c_d], [$b, $c, $d];
14190 is_deeply [$d->prevN_3_b_c_d], [$b, $c, $d];
14191  
14192  
14193 =head2 isOnlyChild($node, @context)
14194  
14195 Return the specified B<$node> if it is the only node under its parent ignoring any surrounding blank text.
14196  
14197 Parameter Description
14198 1 $node Node
14199 2 @context Optional context
14200  
14201 Use the optional B<@context> parameter to test the context of the specified
14202 B<$node> as understood by method L<at|/at>. If the context is supplied and
14203 B<$node> is not in this context then this method returns B<undef> immediately.
14204  
14205  
14206  
14207 B<Example:>
14208  
14209  
14210 {my $a = Data::Edit::Xml::new(<<END);
14211 <a>
14212 <b>
14213 <c>
14214 <d/>
14215 </c>
14216 </b>
14217 <e>
14218 <f/>
14219 </e>
14220 </a>
14221 END
14222  
14223 my ($d, $c, $b, $f, $e) = $a->byList;
14224  
14225  
14226 ok $d->isOnlyChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14227  
14228  
14229  
14230 ok !$d->isOnlyChild(qw(b)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14231  
14232  
14233 {my $a = Data::Edit::Xml::new(<<END);
14234 <a>
14235 <b>
14236 <c>
14237 <d/>
14238 </c>
14239 </b>
14240 <b>
14241 <c/>
14242 </b>
14243 <e>
14244 <f/>
14245 </e>
14246 </a>
14247 END
14248  
14249 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
14250  
14251  
14252 ok $a->isOnlyChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14253  
14254  
14255 my $a = Data::Edit::Xml::new(<<END);
14256 <a>
14257 <b>
14258 <c>
14259 <d>
14260 <e/>
14261 </d>
14262 </c>
14263 </b>
14264 <f>
14265 <g/>
14266 </f>
14267 </a>
14268 END
14269  
14270  
14271 =head2 isOnlyChildToDepth($node, $depth, @context)
14272  
14273 Return the specified B<$node> if it and its ancestors are L<only children|/isOnlyChild> to the specified depth else return B<undef>. isOnlyChildToDepth(1) is the same as L<isOnlychild|/isOnlyChild>
14274  
14275 Parameter Description
14276 1 $node Node
14277 2 $depth Depth to which each parent node must also be an only child
14278 3 @context Optional context
14279  
14280 Use the optional B<@context> parameter to test the context of the specified
14281 B<$node> as understood by method L<at|/at>. If the context is supplied and
14282 B<$node> is not in this context then this method returns B<undef> immediately.
14283  
14284  
14285  
14286 B<Example:>
14287  
14288  
14289 {my $a = Data::Edit::Xml::new(<<END);
14290 <a>
14291 <b>
14292 <c>
14293 <d/>
14294 </c>
14295 </b>
14296 <e>
14297 <f/>
14298 </e>
14299 </a>
14300 END
14301  
14302 my ($d, $c, $b, $f, $e) = $a->byList;
14303  
14304  
14305 ok $d->isOnlyChildToDepth(1, qw(d c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14306  
14307  
14308  
14309 ok $d->isOnlyChildToDepth(2, qw(d c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14310  
14311  
14312  
14313 ok !$d->isOnlyChildToDepth(3, qw(d c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14314  
14315  
14316  
14317 =head2 isOnlyChildN($node, $depth, @context)
14318  
14319 Return the specified B<$node> if it is an only child of B<$depth> ancestors with L<only children|/hasSingleChild> in the opptional B<@context> else return B<undef>. isOnlyChildN(1) is the same as L<isOnlychild|/isOnlyChild>.
14320  
14321 Parameter Description
14322 1 $node Node
14323 2 $depth Depth to which each parent node must also be an only child
14324 3 @context Optional context
14325  
14326 Use the optional B<@context> parameter to test the context of the specified
14327 B<$node> as understood by method L<at|/at>. If the context is supplied and
14328 B<$node> is not in this context then this method returns B<undef> immediately.
14329  
14330  
14331  
14332 B<Example:>
14333  
14334  
14335 my $a = Data::Edit::Xml::new(<<END);
14336 <a>
14337 <b>
14338 <c>
14339 <d>
14340 <e/>
14341 </d>
14342 </c>
14343 </b>
14344 <f>
14345 <g/>
14346 </f>
14347 </a>
14348 END
14349  
14350  
14351 =head2 isOnlyChildText($node, @context)
14352  
14353 Return the specified B<$node> if it is a text node and it is an only child else and its parent is in the specified optional context else return B<undef>.
14354  
14355 Parameter Description
14356 1 $node Node
14357 2 @context Optional context
14358  
14359 Use the optional B<@context> parameter to test the context of the specified
14360 B<$node> as understood by method L<at|/at>. If the context is supplied and
14361 B<$node> is not in this context then this method returns B<undef> immediately.
14362  
14363  
14364  
14365 B<Example:>
14366  
14367  
14368 if (1)
14369 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
14370  
14371 ok $a->first->isOnlyChildText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14372  
14373 }
14374  
14375  
14376 =head2 hasSingleChild($node, @context)
14377  
14378 Return the only child of the specified B<$node> if the child is the only node under its parent ignoring any surrounding blank text and has the optional specified context, else return B<undef>.
14379  
14380 Parameter Description
14381 1 $node Node
14382 2 @context Optional context
14383  
14384 Use the optional B<@context> parameter to test the context of the specified
14385 B<$node> as understood by method L<at|/at>. If the context is supplied and
14386 B<$node> is not in this context then this method returns B<undef> immediately.
14387  
14388  
14389  
14390 B<Example:>
14391  
14392  
14393 {my $a = Data::Edit::Xml::new(<<END);
14394 <a>
14395 <b id="b" b="bb">
14396 <b id="c" c="cc"/>
14397 </b>
14398 </a>
14399 END
14400  
14401 my ($c, $b) = $a->byList;
14402  
14403 is_deeply [$b->id, $c->id], [qw(b c)];
14404  
14405  
14406 ok $c == $b->hasSingleChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14407  
14408  
14409  
14410 ok $b == $a->hasSingleChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14411  
14412  
14413  
14414 =head2 hasSingleChildText($node, @context)
14415  
14416 Return the only child of the specified B<$node> if the child is a text node and the child is the only node under its parent ignoring any surrounding blank text and the child has the optional specified context, else return B<undef>.
14417  
14418 Parameter Description
14419 1 $node Node
14420 2 @context Optional context
14421  
14422 Use the optional B<@context> parameter to test the context of the specified
14423 B<$node> as understood by method L<at|/at>. If the context is supplied and
14424 B<$node> is not in this context then this method returns B<undef> immediately.
14425  
14426  
14427  
14428 B<Example:>
14429  
14430  
14431 my $a = Data::Edit::Xml::new(<<END);
14432 <a>aa
14433 <b>bb</b>
14434 </a>
14435 END
14436  
14437 ok !$a->hasSingleChildText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14438  
14439  
14440 ok $a->last->hasSingleChildText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14441  
14442  
14443  
14444 =head2 hasSingleChildToDepth($node, $depth, @context)
14445  
14446 Return the descendant of the specified B<$node> if it has single children to the specified depth in the specified optional B<@context> else return B<undef>. L<hasSingleChildToDepth(0)|/hasSingleChildToDepth> is equivalent to L<hasSingleChild|/hasSingleChild>.
14447  
14448 Parameter Description
14449 1 $node Node
14450 2 $depth Depth
14451 3 @context Optional context
14452  
14453 Use the optional B<@context> parameter to test the context of the specified
14454 B<$node> as understood by method L<at|/at>. If the context is supplied and
14455 B<$node> is not in this context then this method returns B<undef> immediately.
14456  
14457  
14458  
14459 B<Example:>
14460  
14461  
14462 {my $a = Data::Edit::Xml::new(<<END);
14463 <a>
14464 <b>
14465 <c/>
14466 <d/>
14467 <e>
14468 <j/>
14469 </e>
14470 <f/>
14471 </b>
14472 <g>
14473 <h>
14474 <i>
14475 <k/>
14476 <l/>
14477 </i>
14478 </h>
14479 </g>
14480 </a>
14481 END
14482  
14483 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
14484  
14485  
14486 ok $h == $g->hasSingleChildToDepth(1); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14487  
14488  
14489 ok $i == $g->hasSingleChildToDepth_2_i_h_g;
14490  
14491 ok !$g->hasSingleChildToDepth_2_i_h_G;
14492  
14493  
14494 ok !$g->hasSingleChildToDepth(0); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14495  
14496  
14497  
14498 ok !$g->hasSingleChildToDepth(3); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14499  
14500  
14501  
14502 ok $i == $i->hasSingleChildToDepth(0); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14503  
14504  
14505  
14506 =head2 isEmpty($node, @context)
14507  
14508 Confirm that the specified B<$node> is empty, that is: the specified B<$node> has no content, not even a blank string of text. To test for blank nodes, see L<isAllBlankText|/isAllBlankText>.
14509  
14510 Parameter Description
14511 1 $node Node
14512 2 @context Optional context
14513  
14514 Use the optional B<@context> parameter to test the context of the specified
14515 B<$node> as understood by method L<at|/at>. If the context is supplied and
14516 B<$node> is not in this context then this method returns B<undef> immediately.
14517  
14518  
14519  
14520 B<Example:>
14521  
14522  
14523 my $x = Data::Edit::Xml::new(<<END);
14524 <a>
14525  
14526 </a>
14527 END
14528  
14529  
14530 ok $x->isEmpty; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14531  
14532  
14533 {my $a = Data::Edit::Xml::new(<<END);
14534 <a>
14535 <b>
14536 <c>
14537 <d/>
14538 </c>
14539 </b>
14540 <e>
14541 <f/>
14542 </e>
14543 </a>
14544 END
14545  
14546 my ($d, $c, $b, $f, $e) = $a->byList;
14547  
14548  
14549 ok $d->isEmpty; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14550  
14551  
14552 my $a = Data::Edit::Xml::new(q(<a><b><c/></b></a>));
14553  
14554 my ($c, $b) = $a->byList;
14555  
14556  
14557 ok $c->isEmpty; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14558  
14559 ok $b->hasContent;
14560  
14561  
14562 =head2 hasContent($node, @context)
14563  
14564 Confirm that the specified B<$node> has content. Return the specified node if it has content else return B<undef> if it does not.
14565  
14566 Parameter Description
14567 1 $node Node
14568 2 @context Optional context
14569  
14570 Use the optional B<@context> parameter to test the context of the specified
14571 B<$node> as understood by method L<at|/at>. If the context is supplied and
14572 B<$node> is not in this context then this method returns B<undef> immediately.
14573  
14574  
14575  
14576 B<Example:>
14577  
14578  
14579 my $a = Data::Edit::Xml::new(q(<a><b><c/></b></a>));
14580  
14581 my ($c, $b) = $a->byList;
14582  
14583 ok $c->isEmpty;
14584  
14585 ok $b->hasContent; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14586  
14587  
14588  
14589 =head2 over($node, $re, @context)
14590  
14591 Confirm that the string representing the tags at the level below the specified B<$node> match a regular expression where each pair of tags is separated by a single space. Use L<contentAsTags|/contentAsTags> to visualize the tags at the next level.
14592  
14593 Parameter Description
14594 1 $node Node
14595 2 $re Regular expression
14596 3 @context Optional context.
14597  
14598 Use the optional B<@context> parameter to test the context of the specified
14599 B<$node> as understood by method L<at|/at>. If the context is supplied and
14600 B<$node> is not in this context then this method returns B<undef> immediately.
14601  
14602  
14603  
14604 B<Example:>
14605  
14606  
14607 {my $x = Data::Edit::Xml::new(<<END);
14608 <a>
14609 <b>
14610 <c/><d/><e/><f/><g/>
14611 </b>
14612 </a>
14613 END
14614  
14615  
14616 ok $x->go(q(b))->over(qr(d.+e)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14617  
14618  
14619  
14620 =head2 over2($node, $re, @context)
14621  
14622 Confirm that the string representing the tags at the level below the specified B<$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 L<contentAsTags2|/contentAsTags2> to visualize the tags at the next level.
14623  
14624 Parameter Description
14625 1 $node Node
14626 2 $re Regular expression
14627 3 @context Optional context.
14628  
14629 Use the optional B<@context> parameter to test the context of the specified
14630 B<$node> as understood by method L<at|/at>. If the context is supplied and
14631 B<$node> is not in this context then this method returns B<undef> immediately.
14632  
14633  
14634  
14635 B<Example:>
14636  
14637  
14638 {my $x = Data::Edit::Xml::new(<<END);
14639 <a>
14640 <b>
14641 <c/><d/><e/><f/><g/>
14642 </b>
14643 </a>
14644 END
14645  
14646  
14647 ok $x->go(q(b))->over2(qr(\A c d e f g \Z)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14648  
14649  
14650 ok $x->go(q(b))->contentAsTags eq q(c d e f g) ;
14651  
14652  
14653 =head2 overAllTags($node, @tags)
14654  
14655 Return the specified b<$node> if all of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
14656  
14657 Parameter Description
14658 1 $node Node
14659 2 @tags Tags.
14660  
14661 B<Example:>
14662  
14663  
14664 if (1)
14665 {my $a = Data::Edit::Xml::new(<<END);
14666 <a>
14667 <b/>
14668 <c/>
14669 <d/>
14670 </a>
14671 END
14672  
14673 ok $a->overAllTags_b_c_d;
14674 ok !$a->overAllTags_b_c;
14675 ok !$a->overAllTags_b_c_d_e;
14676 ok $a->oat_b_c_d;
14677 ok !$a->oat_B_c_d;
14678  
14679 ok $a->overFirstTags_b_c_d;
14680 ok $a->overFirstTags_b_c;
14681 ok !$a->overFirstTags_b_c_d_e;
14682 ok $a->oft_b_c;
14683 ok !$a->oft_B_c;
14684  
14685 ok $a->overLastTags_b_c_d;
14686 ok $a->overLastTags_c_d;
14687 ok !$a->overLastTags_b_c_d_e;
14688 ok $a->olt_c_d;
14689 ok !$a->olt_C_d;
14690 }
14691  
14692  
14693 B<oat> is a synonym for L<overAllTags|/overAllTags>.
14694  
14695  
14696 =head2 overFirstTags($node, @tags)
14697  
14698 Return the specified b<$node> if the first of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
14699  
14700 Parameter Description
14701 1 $node Node
14702 2 @tags Tags.
14703  
14704 B<Example:>
14705  
14706  
14707 if (1)
14708 {my $a = Data::Edit::Xml::new(<<END);
14709 <a>
14710 <b/>
14711 <c/>
14712 <d/>
14713 </a>
14714 END
14715  
14716 ok $a->overAllTags_b_c_d;
14717 ok !$a->overAllTags_b_c;
14718 ok !$a->overAllTags_b_c_d_e;
14719 ok $a->oat_b_c_d;
14720 ok !$a->oat_B_c_d;
14721  
14722 ok $a->overFirstTags_b_c_d;
14723 ok $a->overFirstTags_b_c;
14724 ok !$a->overFirstTags_b_c_d_e;
14725 ok $a->oft_b_c;
14726 ok !$a->oft_B_c;
14727  
14728 ok $a->overLastTags_b_c_d;
14729 ok $a->overLastTags_c_d;
14730 ok !$a->overLastTags_b_c_d_e;
14731 ok $a->olt_c_d;
14732 ok !$a->olt_C_d;
14733 }
14734  
14735  
14736 B<oft> is a synonym for L<overFirstTags|/overFirstTags>.
14737  
14738  
14739 =head2 overLastTags($node, @tags)
14740  
14741 Return the specified b<$node> if the last of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
14742  
14743 Parameter Description
14744 1 $node Node
14745 2 @tags Tags.
14746  
14747 B<Example:>
14748  
14749  
14750 if (1)
14751 {my $a = Data::Edit::Xml::new(<<END);
14752 <a>
14753 <b/>
14754 <c/>
14755 <d/>
14756 </a>
14757 END
14758  
14759 ok $a->overAllTags_b_c_d;
14760 ok !$a->overAllTags_b_c;
14761 ok !$a->overAllTags_b_c_d_e;
14762 ok $a->oat_b_c_d;
14763 ok !$a->oat_B_c_d;
14764  
14765 ok $a->overFirstTags_b_c_d;
14766 ok $a->overFirstTags_b_c;
14767 ok !$a->overFirstTags_b_c_d_e;
14768 ok $a->oft_b_c;
14769 ok !$a->oft_B_c;
14770  
14771 ok $a->overLastTags_b_c_d;
14772 ok $a->overLastTags_c_d;
14773 ok !$a->overLastTags_b_c_d_e;
14774 ok $a->olt_c_d;
14775 ok !$a->olt_C_d;
14776 }
14777  
14778  
14779 B<olt> is a synonym for L<overLastTags|/overLastTags>.
14780  
14781  
14782 =head2 matchAfter($node, $re, @context)
14783  
14784 Confirm that the string representing the tags following the specified B<$node> matches a regular expression where each pair of tags is separated by a single space. Use L<contentAfterAsTags|/contentAfterAsTags> to visualize these tags.
14785  
14786 Parameter Description
14787 1 $node Node
14788 2 $re Regular expression
14789 3 @context Optional context.
14790  
14791 Use the optional B<@context> parameter to test the context of the specified
14792 B<$node> as understood by method L<at|/at>. If the context is supplied and
14793 B<$node> is not in this context then this method returns B<undef> immediately.
14794  
14795  
14796  
14797 B<Example:>
14798  
14799  
14800 {my $x = Data::Edit::Xml::new(<<END);
14801 <a>
14802 <b>
14803 <c/><d/><e/><f/><g/>
14804 </b>
14805 </a>
14806 END
14807  
14808  
14809 ok $x->go(qw(b e))->matchAfter (qr(\Af g\Z)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14810  
14811  
14812  
14813 =head2 matchAfter2($node, $re, @context)
14814  
14815 Confirm that the string representing the tags following the specified B<$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 L<contentAfterAsTags2|/contentAfterAsTags2> to visualize these tags.
14816  
14817 Parameter Description
14818 1 $node Node
14819 2 $re Regular expression
14820 3 @context Optional context.
14821  
14822 Use the optional B<@context> parameter to test the context of the specified
14823 B<$node> as understood by method L<at|/at>. If the context is supplied and
14824 B<$node> is not in this context then this method returns B<undef> immediately.
14825  
14826  
14827  
14828 B<Example:>
14829  
14830  
14831 {my $x = Data::Edit::Xml::new(<<END);
14832 <a>
14833 <b>
14834 <c/><d/><e/><f/><g/>
14835 </b>
14836 </a>
14837 END
14838  
14839  
14840 ok $x->go(qw(b e))->matchAfter2 (qr(\A f g \Z)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14841  
14842  
14843  
14844 =head2 matchBefore($node, $re, @context)
14845  
14846 Confirm that the string representing the tags preceding the specified B<$node> matches a regular expression where each pair of tags is separated by a single space. Use L<contentBeforeAsTags|/contentBeforeAsTags> to visualize these tags.
14847  
14848 Parameter Description
14849 1 $node Node
14850 2 $re Regular expression
14851 3 @context Optional context.
14852  
14853 Use the optional B<@context> parameter to test the context of the specified
14854 B<$node> as understood by method L<at|/at>. If the context is supplied and
14855 B<$node> is not in this context then this method returns B<undef> immediately.
14856  
14857  
14858  
14859 B<Example:>
14860  
14861  
14862 {my $x = Data::Edit::Xml::new(<<END);
14863 <a>
14864 <b>
14865 <c/><d/><e/><f/><g/>
14866 </b>
14867 </a>
14868 END
14869  
14870  
14871 ok $x->go(qw(b e))->matchBefore (qr(\Ac d\Z)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14872  
14873  
14874  
14875 =head2 matchBefore2($node, $re, @context)
14876  
14877 Confirm that the string representing the tags preceding the specified B<$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 L<contentBeforeAsTags2|/contentBeforeAsTags2> to visualize these tags.
14878  
14879 Parameter Description
14880 1 $node Node
14881 2 $re Regular expression
14882 3 @context Optional context.
14883  
14884 Use the optional B<@context> parameter to test the context of the specified
14885 B<$node> as understood by method L<at|/at>. If the context is supplied and
14886 B<$node> is not in this context then this method returns B<undef> immediately.
14887  
14888  
14889  
14890 B<Example:>
14891  
14892  
14893 {my $x = Data::Edit::Xml::new(<<END);
14894 <a>
14895 <b>
14896 <c/><d/><e/><f/><g/>
14897 </b>
14898 </a>
14899 END
14900  
14901  
14902 ok $x->go(qw(b e))->matchBefore2(qr(\A c d \Z)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14903  
14904  
14905  
14906 =head2 parentage($node)
14907  
14908 Return a reference to an array of the nodes along the path from the root to the specified B<$Node> inclusive.
14909  
14910 Parameter Description
14911 1 $node Node.
14912  
14913 B<Example:>
14914  
14915  
14916 my $a = Data::Edit::Xml::new(<<END);
14917 <a>
14918 <b>
14919 <c>
14920 <d/>
14921 </c>
14922 </b>
14923 </a>
14924 END
14925  
14926 my ($d, $c, $b) = $a->byList;
14927  
14928 is_deeply $a->go_b_c_d__parentage, [$a, $b, $c, $d];
14929  
14930  
14931 B<p> is a synonym for L<parentage|/parentage>.
14932  
14933  
14934 =head2 path($node)
14935  
14936 Return a list of strings representing the path to a node from the root of the parse tree which can then be reused by L<go|/go> to retrieve the node as long as the structure of the L<parse|/parse> tree has not changed along the path.
14937  
14938 Parameter Description
14939 1 $node Node.
14940  
14941 B<Example:>
14942  
14943  
14944 my $x = Data::Edit::Xml::new(<<END);
14945 <a id='a1'>
14946 <b id='b1'>
14947 <c id='c1'/>
14948 <c id='c2'/>
14949 <d id='d1'>
14950 <e id='e1'/>
14951 </d>
14952 <c id='c3'/>
14953 <c id='c4'/>
14954 <d id='d2'>
14955 <e id='e2'/>
14956 </d>
14957 <c id='c5'/>
14958 <c id='c6'/>
14959 </b>
14960 </a>
14961 END
14962  
14963  
14964 is_deeply [$x->go(qw(b d 1 e))->path], [qw(b d 1 e)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14965  
14966  
14967  
14968 $x->by(sub {ok $x->go($_->path) == $_}); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
14969  
14970  
14971  
14972 =head2 pathString($node)
14973  
14974 Return a string representing the L<path|/path> to the specified B<$node> from the root of the parse tree.
14975  
14976 Parameter Description
14977 1 $node Node.
14978  
14979 B<Example:>
14980  
14981  
14982 ok -z $a eq <<END;
14983 <a id="1">
14984 <b id="2">
14985 <c id="3">
14986 <e id="4"/>
14987 </c>
14988 <d id="5">
14989 <e id="6"/>
14990 </d>
14991 <c id="7">
14992 <d id="8">
14993 <e id="9"/>
14994 </d>
14995 </c>
14996 <d id="10">
14997 <e id="11"/>
14998 </d>
14999 <c id="12">
15000 <d id="13">
15001 <e id="14"/>
15002 </d>
15003 </c>
15004 </b>
15005 </a>
15006 END
15007  
15008  
15009 ok $a->findByNumber(9)->pathString eq 'b c 1 d e'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15010  
15011  
15012  
15013 =head2 Match
15014  
15015 Locate adjacent nodes that match horizontally and vertically
15016  
15017 =head3 an($node, $current, @context)
15018  
15019 Return the next node if the specified B<$node> has the tag specified by B<$current> and the next node is in the specified B<@context>.
15020  
15021 Parameter Description
15022 1 $node Node
15023 2 $current Tag node must match
15024 3 @context Optional context of the next node.
15025  
15026 Use the optional B<@context> parameter to test the context of the specified
15027 B<$node> as understood by method L<at|/at>. If the context is supplied and
15028 B<$node> is not in this context then this method returns B<undef> immediately.
15029  
15030  
15031  
15032 B<Example:>
15033  
15034  
15035 {my $a = Data::Edit::Xml::new(<<END);
15036 <a>
15037 <b>
15038 <c/>
15039 <d/>
15040 <e>
15041 <j/>
15042 </e>
15043 <f/>
15044 </b>
15045 <g>
15046 <h>
15047 <i>
15048 <k/>
15049 <l/>
15050 </i>
15051 </h>
15052 </g>
15053 </a>
15054 END
15055  
15056 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
15057  
15058 ok $e == $d->an_d_e_b_a;
15059  
15060 ok $f == $e->an_e;
15061  
15062 ok !$f->an_f;
15063  
15064  
15065 =head3 ap($node, $current, @context)
15066  
15067 Return the previous node if the specified B<$node> has the tag specified by B<$current> and the previous node is in the specified B<@context>.
15068  
15069 Parameter Description
15070 1 $node Node
15071 2 $current Tag node must match
15072 3 @context Optional context of the previous node.
15073  
15074 Use the optional B<@context> parameter to test the context of the specified
15075 B<$node> as understood by method L<at|/at>. If the context is supplied and
15076 B<$node> is not in this context then this method returns B<undef> immediately.
15077  
15078  
15079  
15080 B<Example:>
15081  
15082  
15083 {my $a = Data::Edit::Xml::new(<<END);
15084 <a>
15085 <b>
15086 <c/>
15087 <d/>
15088 <e>
15089 <j/>
15090 </e>
15091 <f/>
15092 </b>
15093 <g>
15094 <h>
15095 <i>
15096 <k/>
15097 <l/>
15098 </i>
15099 </h>
15100 </g>
15101 </a>
15102 END
15103  
15104 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
15105  
15106 ok $c == $d->ap_d_c_b_a;
15107  
15108 ok $c == $d->ap_d;
15109  
15110 ok !$c->ap_c;
15111  
15112  
15113 =head3 apn($node, $prev, $current, @context)
15114  
15115 Return (previous node, next node) if the B<$previous> and B<$current> nodes have the specified tags and the next node is in the specified B<@context> else return B<()>. The specified B<@context> must have at least one element otherwise B<()> is returned.
15116  
15117 Parameter Description
15118 1 $node Current node
15119 2 $prev Tag for the previous node
15120 3 $current Tag for specified node
15121 4 @context Context for the next node.
15122  
15123 Use the B<@context> parameter to test the context of the specified
15124 B<$node> as understood by method L<at|/at>. If a context is supplied and
15125 B<$node> is not in this context then this method returns an empty list B<()>
15126 immediately.
15127  
15128  
15129  
15130 B<Example:>
15131  
15132  
15133 {my $a = Data::Edit::Xml::new(<<END);
15134 <a>
15135 <b>
15136 <c/>
15137 <d/>
15138 <e>
15139 <j/>
15140 </e>
15141 <f/>
15142 </b>
15143 <g>
15144 <h>
15145 <i>
15146 <k/>
15147 <l/>
15148 </i>
15149 </h>
15150 </g>
15151 </a>
15152 END
15153  
15154 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
15155  
15156 is_deeply[$c, $e], [$d->apn_c_d_e_b_a];
15157  
15158  
15159 =head3 matchesFirst($node, @sequence)
15160  
15161 Return the specified B<$node> if its children L<match|/atPositionMatch> the specified <@sequence> forwards from the first child else return B<undef>.
15162  
15163 Parameter Description
15164 1 $node Node
15165 2 @sequence Sequence.
15166  
15167 B<Example:>
15168  
15169  
15170 if (1)
15171 {my $a = Data::Edit::Xml::new(<<END);
15172 <a>
15173 <b/>
15174 <c/>
15175 <d/>
15176 <e/>
15177 <f/>
15178 </a>
15179 END
15180 my ($b, $c, $d, $e, $f) = $a->byList;
15181  
15182 ok $a->matchesFirst_b_c_d_e_f;
15183 ok !$a->matchesFirst_c;
15184 ok $a->matchesLast_f_e_d_c_b;
15185 ok !$a->matchesLast_f_d;
15186 ok $c->matchesNext_d_e_f;
15187 ok !$d->matchesNext_e_f_a;
15188 ok $e->matchesPrev_d_c_b;
15189 ok !$e->matchesPrev_d_c_b_a;
15190 }
15191  
15192  
15193 =head3 matchesLast($node, @sequence)
15194  
15195 Return the specified B<$node> if its children L<match|/atPositionMatch> the specified <@sequence> backwards from the last child else return B<undef>.
15196  
15197 Parameter Description
15198 1 $node Node
15199 2 @sequence Sequence.
15200  
15201 B<Example:>
15202  
15203  
15204 if (1)
15205 {my $a = Data::Edit::Xml::new(<<END);
15206 <a>
15207 <b/>
15208 <c/>
15209 <d/>
15210 <e/>
15211 <f/>
15212 </a>
15213 END
15214 my ($b, $c, $d, $e, $f) = $a->byList;
15215  
15216 ok $a->matchesFirst_b_c_d_e_f;
15217 ok !$a->matchesFirst_c;
15218 ok $a->matchesLast_f_e_d_c_b;
15219 ok !$a->matchesLast_f_d;
15220 ok $c->matchesNext_d_e_f;
15221 ok !$d->matchesNext_e_f_a;
15222 ok $e->matchesPrev_d_c_b;
15223 ok !$e->matchesPrev_d_c_b_a;
15224 }
15225  
15226  
15227 =head3 matchesNext($node, @sequence)
15228  
15229 Return the specified B<$node> if its following siblings L<match|/atPositionMatch> the specified <@sequence> else return B<undef>.
15230  
15231 Parameter Description
15232 1 $node Node
15233 2 @sequence Sequence.
15234  
15235 B<Example:>
15236  
15237  
15238 if (1)
15239 {my $a = Data::Edit::Xml::new(<<END);
15240 <a>
15241 <b/>
15242 <c/>
15243 <d/>
15244 <e/>
15245 <f/>
15246 </a>
15247 END
15248 my ($b, $c, $d, $e, $f) = $a->byList;
15249  
15250 ok $a->matchesFirst_b_c_d_e_f;
15251 ok !$a->matchesFirst_c;
15252 ok $a->matchesLast_f_e_d_c_b;
15253 ok !$a->matchesLast_f_d;
15254 ok $c->matchesNext_d_e_f;
15255 ok !$d->matchesNext_e_f_a;
15256 ok $e->matchesPrev_d_c_b;
15257 ok !$e->matchesPrev_d_c_b_a;
15258 }
15259  
15260  
15261 =head3 matchesPrev($node, @sequence)
15262  
15263 Return the specified B<$node> if the siblings before $node L<match|/atPositionMatch> the specified <@sequence> with the first element of @sequence nearest to $node and the last element furthest else return B<undef>.
15264  
15265 Parameter Description
15266 1 $node Node
15267 2 @sequence Sequence.
15268  
15269 B<Example:>
15270  
15271  
15272 if (1)
15273 {my $a = Data::Edit::Xml::new(<<END);
15274 <a>
15275 <b/>
15276 <c/>
15277 <d/>
15278 <e/>
15279 <f/>
15280 </a>
15281 END
15282 my ($b, $c, $d, $e, $f) = $a->byList;
15283  
15284 ok $a->matchesFirst_b_c_d_e_f;
15285 ok !$a->matchesFirst_c;
15286 ok $a->matchesLast_f_e_d_c_b;
15287 ok !$a->matchesLast_f_d;
15288 ok $c->matchesNext_d_e_f;
15289 ok !$d->matchesNext_e_f_a;
15290 ok $e->matchesPrev_d_c_b;
15291 ok !$e->matchesPrev_d_c_b_a;
15292 }
15293  
15294  
15295 =head2 Child of, Parent of, Sibling of
15296  
15297 Nodes that are directly above, below or adjacent to another node.
15298  
15299 =head3 parentOf($parent, $child, @context)
15300  
15301 Returns the specified B<$parent> node if it is the parent of the specified B<$child> node and the B<$parent> node is in the specified optional context.
15302  
15303 Parameter Description
15304 1 $parent Parent
15305 2 $child Child
15306 3 @context Optional context
15307  
15308 Use the optional B<@context> parameter to test the context of the specified
15309 B<$node> as understood by method L<at|/at>. If the context is supplied and
15310 B<$node> is not in this context then this method returns B<undef> immediately.
15311  
15312  
15313  
15314 B<Example:>
15315  
15316  
15317 {my $a = Data::Edit::Xml::new(<<END);
15318 <a>
15319 <b>
15320 <c/>
15321 <d/>
15322 <e>
15323 <j/>
15324 </e>
15325 <f/>
15326 </b>
15327 <g>
15328 <h>
15329 <i>
15330 <k/>
15331 <l/>
15332 </i>
15333 </h>
15334 </g>
15335 </a>
15336 END
15337  
15338  
15339 ok $e->parentOf($j); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15340  
15341  
15342  
15343 =head3 childOf($child, $parent, @context)
15344  
15345 Returns the specified B<$child> node if it is a child of the specified B<$parent> node and the B<$child> node is in the specified optional context.
15346  
15347 Parameter Description
15348 1 $child Child
15349 2 $parent Parent
15350 3 @context Optional context
15351  
15352 Use the optional B<@context> parameter to test the context of the specified
15353 B<$node> as understood by method L<at|/at>. If the context is supplied and
15354 B<$node> is not in this context then this method returns B<undef> immediately.
15355  
15356  
15357  
15358 B<Example:>
15359  
15360  
15361 {my $a = Data::Edit::Xml::new(<<END);
15362 <a>
15363 <b>
15364 <c/>
15365 <d/>
15366 <e>
15367 <j/>
15368 </e>
15369 <f/>
15370 </b>
15371 <g>
15372 <h>
15373 <i>
15374 <k/>
15375 <l/>
15376 </i>
15377 </h>
15378 </g>
15379 </a>
15380 END
15381  
15382  
15383 ok $j->childOf($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15384  
15385  
15386  
15387 =head3 succeedingSiblingOf($child, $sibling, @context)
15388  
15389 Returns the specified B<$child> node if it has the same parent as B<$sibling> and occurs after B<$sibling> and has the optionally specified context else returns B<undef>.
15390  
15391 Parameter Description
15392 1 $child Child
15393 2 $sibling Sibling thought to occur before child
15394 3 @context Optional context
15395  
15396 Use the optional B<@context> parameter to test the context of the specified
15397 B<$node> as understood by method L<at|/at>. If the context is supplied and
15398 B<$node> is not in this context then this method returns B<undef> immediately.
15399  
15400  
15401  
15402 B<Example:>
15403  
15404  
15405 my $a = Data::Edit::Xml::new(<<END);
15406 <a>
15407 <b>
15408 <c/>
15409 <d/>
15410 <e/>
15411 </b>
15412 <B>
15413 <C/>
15414 <D/>
15415 <E/>
15416 </B>
15417 </a>
15418 END
15419  
15420 my ($c, $d, $e, $b, $C, $D, $B) = $a->byList;
15421  
15422 ok !$e->succeedingSiblingOf($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15423  
15424  
15425 ok $e->succeedingSiblingOf($d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15426  
15427  
15428 ok $e->succeedingSiblingOf($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15429  
15430  
15431 ok !$e->succeedingSiblingOf($b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15432  
15433  
15434 ok !$e->succeedingSiblingOf($B); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15435  
15436  
15437 ok !$e->succeedingSiblingOf($C); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15438  
15439  
15440 ok !$c->precedingSiblingOf($c);
15441 ok $c->precedingSiblingOf($d);
15442 ok $c->precedingSiblingOf($e);
15443 ok !$c->precedingSiblingOf($b);
15444 ok !$c->precedingSiblingOf($B);
15445 ok !$c->precedingSiblingOf($C);
15446  
15447  
15448 =head3 precedingSiblingOf($child, $sibling, @context)
15449  
15450 Returns the specified B<$child> node if it has the same parent as B<$sibling> and occurs before B<$sibling> and has the optionally specified context else returns B<undef>.
15451  
15452 Parameter Description
15453 1 $child Child
15454 2 $sibling Sibling thought to occur after child
15455 3 @context Optional context
15456  
15457 Use the optional B<@context> parameter to test the context of the specified
15458 B<$node> as understood by method L<at|/at>. If the context is supplied and
15459 B<$node> is not in this context then this method returns B<undef> immediately.
15460  
15461  
15462  
15463 B<Example:>
15464  
15465  
15466 my $a = Data::Edit::Xml::new(<<END);
15467 <a>
15468 <b>
15469 <c/>
15470 <d/>
15471 <e/>
15472 </b>
15473 <B>
15474 <C/>
15475 <D/>
15476 <E/>
15477 </B>
15478 </a>
15479 END
15480  
15481 my ($c, $d, $e, $b, $C, $D, $B) = $a->byList;
15482 ok !$e->succeedingSiblingOf($e);
15483 ok $e->succeedingSiblingOf($d);
15484 ok $e->succeedingSiblingOf($c);
15485 ok !$e->succeedingSiblingOf($b);
15486 ok !$e->succeedingSiblingOf($B);
15487 ok !$e->succeedingSiblingOf($C);
15488  
15489  
15490 ok !$c->precedingSiblingOf($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15491  
15492  
15493 ok $c->precedingSiblingOf($d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15494  
15495  
15496 ok $c->precedingSiblingOf($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15497  
15498  
15499 ok !$c->precedingSiblingOf($b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15500  
15501  
15502 ok !$c->precedingSiblingOf($B); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15503  
15504  
15505 ok !$c->precedingSiblingOf($C); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15506  
15507  
15508  
15509 =head1 Navigation
15510  
15511 Move around in the L<parse|/parse> tree.
15512  
15513 =head2 go($node, @path)
15514  
15515 Return the node reached from the specified B<$node> via the specified L<path|/path>: (index positionB<?>)B<*> 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. B<*> can be used as the last position to retrieve all nodes with the final tag.
15516  
15517 Parameter Description
15518 1 $node Node
15519 2 @path Search specification.
15520  
15521 B<Example:>
15522  
15523  
15524 my $x = Data::Edit::Xml::new(my $s = <<END);
15525 <aa>
15526 <a>
15527 <b/>
15528 <c id="1"/><c id="2"/><c id="3"/><c id="4"/>
15529 <d/>
15530 </a>
15531 </aa>
15532 END
15533  
15534  
15535 ok $x->go(qw(a c)) ->id == 1; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15536  
15537  
15538  
15539 ok $x->go(qw(a c -2))->id == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15540  
15541  
15542  
15543 ok $x->go(qw(a c *)) == 4; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15544  
15545  
15546  
15547 ok 1234 == join '', map {$_->id} $x->go(qw(a c *)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15548  
15549  
15550  
15551 =head2 c($node, $tag)
15552  
15553 Return an array of all the nodes with the specified tag below the specified B<$node>.
15554  
15555 Parameter Description
15556 1 $node Node
15557 2 $tag Tag.
15558  
15559 B<Example:>
15560  
15561  
15562 {my $x = Data::Edit::Xml::new(<<END);
15563 <a>
15564  
15565 <b id="b1"><c id="1"/></b> # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15566  
15567  
15568 <d id="d1"><c id="2"/></d> # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15569  
15570  
15571 <e id="e1"><c id="3"/></e> # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15572  
15573  
15574 <b id="b2"><c id="4"/></b> # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15575  
15576  
15577 <d id="d2"><c id="5"/></d> # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15578  
15579  
15580 <e id="e2"><c id="6"/></e> # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15581  
15582 </a>
15583 END
15584  
15585  
15586 is_deeply [map{$_->id} $x->c(q(d))], [qw(d1 d2)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15587  
15588  
15589  
15590 =head2 cText($node)
15591  
15592 Return an array of all the text nodes immediately below the specified B<$node>.
15593  
15594 Parameter Description
15595 1 $node Node.
15596  
15597 B<Example:>
15598  
15599  
15600 my $a = Data::Edit::Xml::new(<<END);
15601 <a>
15602 <b>b1
15603 <c/>
15604 b2
15605 <d/>
15606 b3
15607 </b>
15608 <e>
15609 <f/>
15610 </e>
15611 </a>
15612 END
15613  
15614 my (undef, $c, undef, $d, undef, $b, $f, $e) = $a->byList;
15615 is_deeply ["b".."f"], [map {-t $_} ($b, $c, $d, $e, $f)];
15616  
15617  
15618 ok $b->cText == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15619  
15620  
15621  
15622 my @b = $b->cText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15623  
15624 ok "b1 b2 b3" eq join " ", map {trim $_->text} @b;
15625  
15626 ok !$e->cText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15627  
15628  
15629 ok !$a->cText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15630  
15631  
15632  
15633 =head2 findById($node, $id)
15634  
15635 Find a node in the parse tree under the specified B<$node> with the specified B<$id>.
15636  
15637 Parameter Description
15638 1 $node Parse tree
15639 2 $id Id desired.
15640  
15641 B<Example:>
15642  
15643  
15644 ok -p $a eq <<END;
15645 <a id="i1">
15646 <b id="i2"/>
15647 <c id="i3"/>
15648 <B id="i4">
15649 <c id="i5"/>
15650 </B>
15651 <c id="i6"/>
15652 <b id="i7"/>
15653 </a>
15654 END
15655  
15656 ok -t $a->findById_i4 eq q(B);
15657  
15658 ok -t $a->findById_i5 eq q(c);
15659  
15660  
15661 =head2 matchesNode($first, $second, @attributes)
15662  
15663 Return the B<$first> node if it matches the B<$second> node's tag and the specified B<@attributes> else return B<undef>.
15664  
15665 Parameter Description
15666 1 $first First node
15667 2 $second Second node
15668 3 @attributes Attributes to match on
15669  
15670 B<Example:>
15671  
15672  
15673 if (1)
15674 {my $a = Data::Edit::Xml::new(<<END);
15675 <a id="1">
15676 <b id="2" name="b">
15677 <c id="3" name="c"/>
15678 </b>
15679 <c id="4">
15680 <b id="5" name="b">
15681 <c id="6" name="c"/>
15682 </b>
15683 </c>
15684 </a>
15685 END
15686  
15687 my ($c, $b, $C, $B) = $a->byList;
15688 ok $b->id == 2;
15689 ok $c->id == 3;
15690 ok $B->id == 5;
15691 ok $C->id == 6;
15692  
15693 ok $c->matchesNode($C, qw(name)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15694  
15695  
15696 ok !$c->matchesNode($C, qw(id name)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15697  
15698 ok $c->matchesSubTree($C, qw(name));
15699 ok $b->matchesSubTree($B, qw(name));
15700 ok !$c->matchesSubTree($C, qw(id name));
15701 ok !$b->matchesSubTree($C, qw(name));
15702  
15703 is_deeply [$a->findMatchingSubTrees($b, qw(name))], [$b, $B];
15704 is_deeply [$a->findMatchingSubTrees($c, qw(name))], [$c, $C];
15705 is_deeply [$a->findMatchingSubTrees(new(q(<c/>)))], [$c, $C];
15706 is_deeply [$a->findMatchingSubTrees(new(q(<b><c/></b>)))], [$b, $B];
15707 is_deeply [$a->findMatchingSubTrees(new(q(<b id="2"><c id="3"/></b>)), q(id))], [$b];
15708 }
15709  
15710  
15711 =head2 matchesSubTree($first, $second, @attributes)
15712  
15713 Return the B<$first> node if it L<matches|/matchesNode> the B<$second> node and the nodes under the first node match the corresponding nodes under the second node, else return B<undef>.
15714  
15715 Parameter Description
15716 1 $first First node
15717 2 $second Second node
15718 3 @attributes Attributes to match on
15719  
15720 B<Example:>
15721  
15722  
15723 if (1)
15724 {my $a = Data::Edit::Xml::new(<<END);
15725 <a id="1">
15726 <b id="2" name="b">
15727 <c id="3" name="c"/>
15728 </b>
15729 <c id="4">
15730 <b id="5" name="b">
15731 <c id="6" name="c"/>
15732 </b>
15733 </c>
15734 </a>
15735 END
15736  
15737 my ($c, $b, $C, $B) = $a->byList;
15738 ok $b->id == 2;
15739 ok $c->id == 3;
15740 ok $B->id == 5;
15741 ok $C->id == 6;
15742 ok $c->matchesNode($C, qw(name));
15743 ok !$c->matchesNode($C, qw(id name));
15744  
15745 ok $c->matchesSubTree($C, qw(name)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15746  
15747  
15748 ok $b->matchesSubTree($B, qw(name)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15749  
15750  
15751 ok !$c->matchesSubTree($C, qw(id name)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15752  
15753  
15754 ok !$b->matchesSubTree($C, qw(name)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15755  
15756  
15757 is_deeply [$a->findMatchingSubTrees($b, qw(name))], [$b, $B];
15758 is_deeply [$a->findMatchingSubTrees($c, qw(name))], [$c, $C];
15759 is_deeply [$a->findMatchingSubTrees(new(q(<c/>)))], [$c, $C];
15760 is_deeply [$a->findMatchingSubTrees(new(q(<b><c/></b>)))], [$b, $B];
15761 is_deeply [$a->findMatchingSubTrees(new(q(<b id="2"><c id="3"/></b>)), q(id))], [$b];
15762 }
15763  
15764  
15765 =head2 findMatchingSubTrees($node, $subTree, @attributes)
15766  
15767 Find nodes in the parse tree whose sub tree matches the specified B<$subTree> excluding any of the specified B<$attributes>.
15768  
15769 Parameter Description
15770 1 $node Parse tree
15771 2 $subTree Parse tree to match
15772 3 @attributes Attributes to match on
15773  
15774 B<Example:>
15775  
15776  
15777 if (1)
15778 {my $a = Data::Edit::Xml::new(<<END);
15779 <a id="1">
15780 <b id="2" name="b">
15781 <c id="3" name="c"/>
15782 </b>
15783 <c id="4">
15784 <b id="5" name="b">
15785 <c id="6" name="c"/>
15786 </b>
15787 </c>
15788 </a>
15789 END
15790  
15791 my ($c, $b, $C, $B) = $a->byList;
15792 ok $b->id == 2;
15793 ok $c->id == 3;
15794 ok $B->id == 5;
15795 ok $C->id == 6;
15796 ok $c->matchesNode($C, qw(name));
15797 ok !$c->matchesNode($C, qw(id name));
15798 ok $c->matchesSubTree($C, qw(name));
15799 ok $b->matchesSubTree($B, qw(name));
15800 ok !$c->matchesSubTree($C, qw(id name));
15801 ok !$b->matchesSubTree($C, qw(name));
15802  
15803  
15804 is_deeply [$a->findMatchingSubTrees($b, qw(name))], [$b, $B]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15805  
15806  
15807 is_deeply [$a->findMatchingSubTrees($c, qw(name))], [$c, $C]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15808  
15809  
15810 is_deeply [$a->findMatchingSubTrees(new(q(<c/>)))], [$c, $C]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15811  
15812  
15813 is_deeply [$a->findMatchingSubTrees(new(q(<b><c/></b>)))], [$b, $B]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15814  
15815  
15816 is_deeply [$a->findMatchingSubTrees(new(q(<b id="2"><c id="3"/></b>)), q(id))], [$b]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15817  
15818 }
15819  
15820  
15821 =head2 First
15822  
15823 Find nodes that are first amongst their siblings.
15824  
15825 =head3 first($node, @context)
15826  
15827 Return the first node below the specified B<$node> optionally checking the first node's context. See L<addFirst|/addFirst> to ensure that an expected node is in position.
15828  
15829 Parameter Description
15830 1 $node Node
15831 2 @context Optional context.
15832  
15833 Use the optional B<@context> parameter to test the context of the specified
15834 B<$node> as understood by method L<at|/at>. If the context is supplied and
15835 B<$node> is not in this context then this method returns B<undef> immediately.
15836  
15837 Use B<firstNonBlank> to skip a (rare) initial blank text CDATA. Use B<firstNonBlankX> to die rather
15838 then receive a returned B<undef> or false result.
15839  
15840  
15841  
15842 B<Example:>
15843  
15844  
15845 my $a = Data::Edit::Xml::new(<<END);
15846 <a id="11">
15847 <b id="12">
15848 <c id="13"/>
15849 <d id="14"/>
15850 <b id="15">
15851 <c id="16"/>
15852 <d id="17"/>
15853 <e id="18"/>
15854 <f id="19"/>
15855 <g id="20"/>
15856 </b>
15857 <f id="21"/>
15858 <g id="22"/>
15859 </b>
15860 <b id="23">
15861 <c id="24"/>
15862 <d id="25"/>
15863 <b id="26">
15864 <c id="27"/>
15865 <d id="28"/>
15866 <e id="29"/>
15867 <f id="30"/>
15868 <g id="31"/>
15869 </b>
15870 <f id="32"/>
15871 <g id="33"/>
15872 </b>
15873 </a>
15874 END
15875  
15876  
15877 ok $a->go(q(b))->first->id == 13; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15878  
15879  
15880  
15881 ok $a->go(q(b))->first(qw(c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15882  
15883  
15884  
15885 ok !$a->go(q(b))->first(qw(b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15886  
15887  
15888  
15889 =head3 firstn($node, $N, @context)
15890  
15891 Return the B<$n>'th first node below the specified B<$node> optionally checking its context or B<undef> if there is no such node. B<firstn(1)> is identical in effect to L<first|/first>.
15892  
15893 Parameter Description
15894 1 $node Node
15895 2 $N Number of times to go first
15896 3 @context Optional context.
15897  
15898 Use the optional B<@context> parameter to test the context of the specified
15899 B<$node> as understood by method L<at|/at>. If the context is supplied and
15900 B<$node> is not in this context then this method returns B<undef> immediately.
15901  
15902  
15903  
15904 B<Example:>
15905  
15906  
15907 if (1)
15908 {my $a = Data::Edit::Xml::new(<<END);
15909 <a><b><c><d/><e/><f/></c></b></a>
15910 END
15911 ok -p $a eq <<END;
15912 <a>
15913 <b>
15914 <c>
15915 <d/>
15916 <e/>
15917 <f/>
15918 </c>
15919 </b>
15920 </a>
15921 END
15922 ok -t $a->firstn_0 eq q(a);
15923 ok -t $a->firstn_1 eq q(b);
15924 ok -t $a->firstn_2 eq q(c);
15925 ok -t $a->firstn_3 eq q(d);
15926  
15927 ok -t $a->firstn_3__nextn_0 eq q(d);
15928 ok -t $a->firstn_3__nextn_1 eq q(e);
15929 ok -t $a->firstn_3__nextn_2 eq q(f);
15930 }
15931  
15932  
15933 =head3 firstText($node, @context)
15934  
15935 Return the first node under the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
15936  
15937 Parameter Description
15938 1 $node Node
15939 2 @context Optional context.
15940  
15941 Use the optional B<@context> parameter to test the context of the specified
15942 B<$node> as understood by method L<at|/at>. If the context is supplied and
15943 B<$node> is not in this context then this method returns B<undef> immediately.
15944  
15945  
15946  
15947 B<Example:>
15948  
15949  
15950 my $a = Data::Edit::Xml::new("<a>AA<b/>BB<c/>CC<d/><e/><f/>DD<g/>HH</a>");
15951 ok -p $a eq <<END;
15952 <a>AA
15953 <b/>
15954 BB
15955 <c/>
15956 CC
15957 <d/>
15958 <e/>
15959 <f/>
15960 DD
15961 <g/>
15962 HH
15963 </a>
15964 END
15965 ok $a->firstText_a__text eq q(AA);
15966 ok !$a->go_c__firstText_c_a;
15967 ok !$a->go_c__firstText_c_b;
15968 ok $a->lastText__text eq q(HH);
15969 ok $a->lastText_a__text eq q(HH);
15970 ok !$a->go_c__lastText;
15971 ok $a->go_c__nextText_c_a__text eq q(CC);
15972 ok !$a->go_e__nextText;
15973 ok $a->go_c__prevText_c__text eq q(BB);
15974 ok !$a->go_e__prevText;
15975  
15976  
15977 =head3 firstTextMatches($node, $match, @context)
15978  
15979 Return the first node under the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context. Else return B<undef>.
15980  
15981 Parameter Description
15982 1 $node Node
15983 2 $match Regular expression the text must match
15984 3 @context Optional context of specified node.
15985  
15986 Use the optional B<@context> parameter to test the context of the specified
15987 B<$node> as understood by method L<at|/at>. If the context is supplied and
15988 B<$node> is not in this context then this method returns B<undef> immediately.
15989  
15990  
15991  
15992 B<Example:>
15993  
15994  
15995 {my $a = Data::Edit::Xml::new(<<END);
15996 <a>
15997 <b>bb<c>cc</c>BB
15998 </b>
15999 </a>
16000 END
16001  
16002 my ($bb, $cc, $c, $BB, $b) = $a->byList;
16003  
16004 ok $bb->matchesText(qr(bb));
16005  
16006  
16007 ok $b->at_b_a && $b->firstTextMatches(qr(bb)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16008  
16009  
16010  
16011 ok $b->firstTextMatches(qr(bb), qw(b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16012  
16013  
16014  
16015 ok $c->at_c_b && $c->firstTextMatches(qr(cc)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16016  
16017  
16018  
16019 ok $c->at_c_b && !$c->firstTextMatches(qr(bb)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16020  
16021  
16022  
16023 =head3 firstBy($node, @tags)
16024  
16025 Return a list of the first instance of each specified tag encountered in a post-order traversal from the specified B<$node> or a hash of all first instances if no tags are specified.
16026  
16027 Parameter Description
16028 1 $node Node
16029 2 @tags Tags to search for.
16030  
16031 B<Example:>
16032  
16033  
16034 my $a = Data::Edit::Xml::new(<<END);
16035 <a id="11">
16036 <b id="12">
16037 <c id="13"/>
16038 <d id="14"/>
16039 <b id="15">
16040 <c id="16"/>
16041 <d id="17"/>
16042 <e id="18"/>
16043 <f id="19"/>
16044 <g id="20"/>
16045 </b>
16046 <f id="21"/>
16047 <g id="22"/>
16048 </b>
16049 <b id="23">
16050 <c id="24"/>
16051 <d id="25"/>
16052 <b id="26">
16053 <c id="27"/>
16054 <d id="28"/>
16055 <e id="29"/>
16056 <f id="30"/>
16057 <g id="31"/>
16058 </b>
16059 <f id="32"/>
16060 <g id="33"/>
16061 </b>
16062 </a>
16063 END
16064  
16065  
16066 {my %f = $a->firstBy; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16067  
16068  
16069 ok $f{b}->id == 12;
16070  
16071  
16072 =head3 firstDown($node, @tags)
16073  
16074 Return a list of the first instance of each specified tag encountered in a pre-order traversal from the specified B<$node> or a hash of all first instances if no tags are specified.
16075  
16076 Parameter Description
16077 1 $node Node
16078 2 @tags Tags to search for.
16079  
16080 B<Example:>
16081  
16082  
16083  
16084 {my %f = $a->firstDown; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16085  
16086  
16087 ok $f{b}->id == 15;
16088  
16089  
16090 =head3 firstIn($node, @tags)
16091  
16092 Return the first child node matching one of the named tags under the specified parent node.
16093  
16094 Parameter Description
16095 1 $node Parent node
16096 2 @tags Child tags to search for.
16097  
16098 B<Example:>
16099  
16100  
16101 ok $a->prettyStringCDATA eq <<'END';
16102 <a><CDATA> </CDATA>
16103 <A/>
16104 <CDATA> </CDATA>
16105 <C/>
16106 <CDATA> </CDATA>
16107 <E/>
16108 <CDATA> </CDATA>
16109 <G/>
16110 <CDATA> </CDATA>
16111 </a>
16112 END
16113  
16114  
16115 ok $a->firstIn(qw(b B c C))->tag eq qq(C); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16116  
16117  
16118  
16119 =head3 firstNot($node, @tags)
16120  
16121 Return the first child node that does not match any of the named B<@tags> under the specified parent B<$node>. Return B<undef> if there is no such child node.
16122  
16123 Parameter Description
16124 1 $node Parent node
16125 2 @tags Child tags to avoid.
16126  
16127 B<Example:>
16128  
16129  
16130 {my $a = Data::Edit::Xml::new(<<END);
16131 <a>
16132 <b/>
16133 <c/>
16134 <d/>
16135 <e/>
16136 <f/>
16137 </a>
16138 END
16139  
16140 my ($b, $c, $d, $e, $f) = $a->byList;
16141  
16142 ok $c == $a->firstNot_a_b;
16143  
16144  
16145 =head3 firstInIndex($node, @context)
16146  
16147 Return the specified B<$node> if it is first in its index and optionally L<at|/at> the specified context else B<undef>
16148  
16149 Parameter Description
16150 1 $node Node
16151 2 @context Optional context.
16152  
16153 Use the optional B<@context> parameter to test the context of the specified
16154 B<$node> as understood by method L<at|/at>. If the context is supplied and
16155 B<$node> is not in this context then this method returns B<undef> immediately.
16156  
16157  
16158  
16159 B<Example:>
16160  
16161  
16162 ok -z $a eq <<END;
16163 <a id="1">
16164 <b id="2">
16165 <c id="3">
16166 <e id="4"/>
16167 </c>
16168 <d id="5">
16169 <e id="6"/>
16170 </d>
16171 <c id="7">
16172 <d id="8">
16173 <e id="9"/>
16174 </d>
16175 </c>
16176 <d id="10">
16177 <e id="11"/>
16178 </d>
16179 <c id="12">
16180 <d id="13">
16181 <e id="14"/>
16182 </d>
16183 </c>
16184 </b>
16185 </a>
16186 END
16187  
16188  
16189 ok $a->findByNumber (5)->firstInIndex; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16190  
16191  
16192  
16193 ok !$a->findByNumber(7) ->firstInIndex; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16194  
16195  
16196  
16197 =head3 firstOf($node, @tags)
16198  
16199 Return an array of the nodes that are continuously first under their specified parent node and that match the specified list of tags.
16200  
16201 Parameter Description
16202 1 $node Node
16203 2 @tags Tags to search for.
16204  
16205 B<Example:>
16206  
16207  
16208 {my $a = Data::Edit::Xml::new(<<END);
16209 <a><b><c/><d/><d/><e/><d/><d/><c/></b></a>
16210 END
16211  
16212  
16213 is_deeply [qw(c d d)], [map {-t $_} $a->go(q(b))->firstOf(qw(c d))]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16214  
16215  
16216  
16217 =head3 firstWhile($node, @tags)
16218  
16219 Go first from the specified B<$node> and continue deeper firstly as long as each first child node matches one of the specified B<@tags>. Return the deepest such node encountered or else return B<undef> if no such node is encountered.
16220  
16221 Parameter Description
16222 1 $node Node
16223 2 @tags Tags to search for.
16224  
16225 B<Example:>
16226  
16227  
16228 my $a = Data::Edit::Xml::new(<<END);
16229 <a>
16230 <b>
16231 <c>
16232 <d>
16233 <e>
16234 <f/>
16235 </e>
16236 </d>
16237 </c>
16238 </b>
16239 <B>
16240 <C>
16241 <D>
16242 <E>
16243 <F/>
16244 </E>
16245 </D>
16246 </C>
16247 </B>
16248 </a>
16249 END
16250 my ($f, $e, $d, $c, $b, $F, $E, $D, $C, $B) = $a->byList;
16251  
16252 ok eval qq(-t \$$_ eq q($_)), $_ for qw(a b c d e f B C D E F);
16253  
16254 ok $d == $a->firstWhile_a_d_c_b;
16255 ok $f == $a->firstWhile_a_d_c_b_e_f_g_h;
16256 ok !$b->firstWhile_a;
16257  
16258 ok $e == $a->firstUntil_e_d;
16259 ok !$c->firstUntil_c;
16260 ok !$b->firstUntil_a;
16261  
16262 ok $D == $a->lastWhile_a_D_C_B;
16263 ok $F == $a->lastWhile_a_D_C_B_E_F_G_H;
16264 ok !$B->lastWhile_a;
16265  
16266 ok $E == $a->lastUntil_E_D;
16267 ok !$C->lastUntil_C;
16268 ok !$B->lastUntil_a;
16269  
16270  
16271 =head3 firstUntil($node, @context)
16272  
16273 Go first from the specified B<$node> and continue deeper firstly until a first child node matches the specified B<@context> or return B<undef> if there is no such node. Return the first child of the specified B<$node> if no B<@context> is specified.
16274  
16275 Parameter Description
16276 1 $node Node
16277 2 @context Context to search for.
16278  
16279 Use the optional B<@context> parameter to test the context of the specified
16280 B<$node> as understood by method L<at|/at>. If the context is supplied and
16281 B<$node> is not in this context then this method returns B<undef> immediately.
16282  
16283  
16284  
16285 B<Example:>
16286  
16287  
16288 my $a = Data::Edit::Xml::new(<<END);
16289 <a>
16290 <b>
16291 <c>
16292 <d>
16293 <e>
16294 <f/>
16295 </e>
16296 </d>
16297 </c>
16298 </b>
16299 <B>
16300 <C>
16301 <D>
16302 <E>
16303 <F/>
16304 </E>
16305 </D>
16306 </C>
16307 </B>
16308 </a>
16309 END
16310 my ($f, $e, $d, $c, $b, $F, $E, $D, $C, $B) = $a->byList;
16311  
16312 ok eval qq(-t \$$_ eq q($_)), $_ for qw(a b c d e f B C D E F);
16313  
16314 ok $d == $a->firstWhile_a_d_c_b;
16315 ok $f == $a->firstWhile_a_d_c_b_e_f_g_h;
16316 ok !$b->firstWhile_a;
16317  
16318 ok $e == $a->firstUntil_e_d;
16319 ok !$c->firstUntil_c;
16320 ok !$b->firstUntil_a;
16321  
16322 ok $D == $a->lastWhile_a_D_C_B;
16323 ok $F == $a->lastWhile_a_D_C_B_E_F_G_H;
16324 ok !$B->lastWhile_a;
16325  
16326 ok $E == $a->lastUntil_E_D;
16327 ok !$C->lastUntil_C;
16328 ok !$B->lastUntil_a;
16329  
16330  
16331 =head3 firstUntilText($node, @context)
16332  
16333 Go first from the specified B<$node> and continue deeper firstly until a text node is encountered whose parent matches the specified B<@context> or return B<undef> if there is no such node.
16334  
16335 Parameter Description
16336 1 $node Node
16337 2 @context Context to search for.
16338  
16339 Use the optional B<@context> parameter to test the context of the specified
16340 B<$node> as understood by method L<at|/at>. If the context is supplied and
16341 B<$node> is not in this context then this method returns B<undef> immediately.
16342  
16343  
16344  
16345 B<Example:>
16346  
16347  
16348 my $a = Data::Edit::Xml::new(<<END);
16349 <a>
16350 <b>
16351 cccc
16352 <d/>
16353 <e/>
16354 </b>
16355 <f>
16356 <g/>
16357 hhhh
16358 <i/>
16359 </f>
16360 <j>
16361 <k/>
16362 <l/>
16363 mmmm
16364 </j>
16365 </a>
16366 END
16367  
16368  
16369 ok $a->firstUntilText->text =~ m(cccc)s; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16370  
16371 ok $a->lastUntilText ->text =~ m(mmmm)s;
16372  
16373  
16374  
16375 =head3 firstContextOf($node, @context)
16376  
16377 Return the first node encountered in the specified context in a depth first post-order traversal of the L<parse|/parse> tree.
16378  
16379 Parameter Description
16380 1 $node Node
16381 2 @context Array of tags specifying context.
16382  
16383 Use the optional B<@context> parameter to test the context of the specified
16384 B<$node> as understood by method L<at|/at>. If the context is supplied and
16385 B<$node> is not in this context then this method returns B<undef> immediately.
16386  
16387  
16388  
16389 B<Example:>
16390  
16391  
16392 my $x = Data::Edit::Xml::new(<<END);
16393 <a id="a1">
16394 <b1 id="b1">
16395 <c id="c1">
16396 <d id="d1">DD11</d>
16397 <e id="e1">EE11</e>
16398 </c>
16399 </b1>
16400 <b2 id="b2">
16401 <c id="c2">
16402 <d id="d2">DD22</d>
16403 <e id="e2">EE22</e>
16404 </c>
16405 </b2>
16406 <b3 id="b3">
16407 <c id="c3">
16408 <d id="d3">DD33</d>
16409 <e id="e3">EE33</e>
16410 </c>
16411 </b3>
16412 </a>
16413 END
16414  
16415  
16416 ok $x->firstContextOf(qw(d c)) ->id eq qq(d1); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16417  
16418  
16419  
16420 ok $x->firstContextOf(qw(e c b2)) ->id eq qq(e2); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16421  
16422  
16423  
16424 ok $x->firstContextOf(qw(CDATA d c b2))->string eq qq(DD22); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16425  
16426  
16427  
16428 =head3 firstSibling($node, @context)
16429  
16430 Return the first sibling of the specified B<$node> in the optional B<@context> else B<undef>
16431  
16432 Parameter Description
16433 1 $node Node
16434 2 @context Array of tags specifying context.
16435  
16436 Use the optional B<@context> parameter to test the context of the specified
16437 B<$node> as understood by method L<at|/at>. If the context is supplied and
16438 B<$node> is not in this context then this method returns B<undef> immediately.
16439  
16440  
16441  
16442 B<Example:>
16443  
16444  
16445 my $a = Data::Edit::Xml::new(<<END);
16446 <a id="11">
16447 <b id="12">
16448 <c id="13"/>
16449 <d id="14"/>
16450 <b id="15">
16451 <c id="16"/>
16452 <d id="17"/>
16453 <e id="18"/>
16454 <f id="19"/>
16455 <g id="20"/>
16456 </b>
16457 <f id="21"/>
16458 <g id="22"/>
16459 </b>
16460 <b id="23">
16461 <c id="24"/>
16462 <d id="25"/>
16463 <b id="26">
16464 <c id="27"/>
16465 <d id="28"/>
16466 <e id="29"/>
16467 <f id="30"/>
16468 <g id="31"/>
16469 </b>
16470 <f id="32"/>
16471 <g id="33"/>
16472 </b>
16473 </a>
16474 END
16475  
16476  
16477 ok $a->go(qw(b b))->firstSibling->id == 13; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16478  
16479  
16480  
16481 =head2 Last
16482  
16483 Find nodes that are last amongst their siblings.
16484  
16485 =head3 last($node, @context)
16486  
16487 Return the last node below the specified B<$node> optionally checking the last node's context. See L<addLast|/addLast> to ensure that an expected node is in position.
16488  
16489 Parameter Description
16490 1 $node Node
16491 2 @context Optional context.
16492  
16493 Use the optional B<@context> parameter to test the context of the specified
16494 B<$node> as understood by method L<at|/at>. If the context is supplied and
16495 B<$node> is not in this context then this method returns B<undef> immediately.
16496  
16497 Use B<lastNonBlank> to skip a (rare) initial blank text CDATA. Use B<lastNonBlankX> to die rather
16498 then receive a returned B<undef> or false result.
16499  
16500  
16501  
16502 B<Example:>
16503  
16504  
16505 my $a = Data::Edit::Xml::new(<<END);
16506 <a id="11">
16507 <b id="12">
16508 <c id="13"/>
16509 <d id="14"/>
16510 <b id="15">
16511 <c id="16"/>
16512 <d id="17"/>
16513 <e id="18"/>
16514 <f id="19"/>
16515 <g id="20"/>
16516 </b>
16517 <f id="21"/>
16518 <g id="22"/>
16519 </b>
16520 <b id="23">
16521 <c id="24"/>
16522 <d id="25"/>
16523 <b id="26">
16524 <c id="27"/>
16525 <d id="28"/>
16526 <e id="29"/>
16527 <f id="30"/>
16528 <g id="31"/>
16529 </b>
16530 <f id="32"/>
16531 <g id="33"/>
16532 </b>
16533 </a>
16534 END
16535  
16536  
16537 ok $a->go(q(b))->last ->id == 22; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16538  
16539  
16540  
16541 ok $a->go(q(b))->last(qw(g b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16542  
16543  
16544  
16545 ok !$a->go(q(b))->last(qw(b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16546  
16547  
16548  
16549 ok !$a->go(q(b))->last(qw(b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16550  
16551  
16552  
16553 =head3 lastn($node, $N, @context)
16554  
16555 Return the B<$n>'th last node below the specified B<$node> optionally checking its context or B<undef> if there is no such node. B<lastn(1)> is identical in effect to L<last|/last>.
16556  
16557 Parameter Description
16558 1 $node Node
16559 2 $N Number of times to go last
16560 3 @context Optional context.
16561  
16562 Use the optional B<@context> parameter to test the context of the specified
16563 B<$node> as understood by method L<at|/at>. If the context is supplied and
16564 B<$node> is not in this context then this method returns B<undef> immediately.
16565  
16566  
16567  
16568 B<Example:>
16569  
16570  
16571 if (1)
16572 {my $a = Data::Edit::Xml::new(<<END);
16573 <a><b><c><d/><e/><f/></c></b>
16574 <B><C><D/><E/><F/></C></B></a>
16575 END
16576 ok -p $a eq <<END;
16577 <a>
16578 <b>
16579 <c>
16580 <d/>
16581 <e/>
16582 <f/>
16583 </c>
16584 </b>
16585 <B>
16586 <C>
16587 <D/>
16588 <E/>
16589 <F/>
16590 </C>
16591 </B>
16592 </a>
16593 END
16594  
16595 ok -t $a->lastn_0 eq q(a);
16596 ok -t $a->lastn_1 eq q(B);
16597 ok -t $a->lastn_2 eq q(C);
16598 ok -t $a->lastn_3 eq q(F);
16599  
16600 ok -t $a->lastn_3__prevn_0 eq q(F);
16601 ok -t $a->lastn_3__prevn_1 eq q(E);
16602 ok -t $a->lastn_3__prevn_2 eq q(D);
16603 }
16604  
16605  
16606 =head3 lastText($node, @context)
16607  
16608 Return the last node under the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
16609  
16610 Parameter Description
16611 1 $node Node
16612 2 @context Optional context.
16613  
16614 Use the optional B<@context> parameter to test the context of the specified
16615 B<$node> as understood by method L<at|/at>. If the context is supplied and
16616 B<$node> is not in this context then this method returns B<undef> immediately.
16617  
16618  
16619  
16620 B<Example:>
16621  
16622  
16623 my $a = Data::Edit::Xml::new("<a>AA<b/>BB<c/>CC<d/><e/><f/>DD<g/>HH</a>");
16624 ok -p $a eq <<END;
16625 <a>AA
16626 <b/>
16627 BB
16628 <c/>
16629 CC
16630 <d/>
16631 <e/>
16632 <f/>
16633 DD
16634 <g/>
16635 HH
16636 </a>
16637 END
16638 ok $a->firstText_a__text eq q(AA);
16639 ok !$a->go_c__firstText_c_a;
16640 ok !$a->go_c__firstText_c_b;
16641 ok $a->lastText__text eq q(HH);
16642 ok $a->lastText_a__text eq q(HH);
16643 ok !$a->go_c__lastText;
16644 ok $a->go_c__nextText_c_a__text eq q(CC);
16645 ok !$a->go_e__nextText;
16646 ok $a->go_c__prevText_c__text eq q(BB);
16647 ok !$a->go_e__prevText;
16648  
16649  
16650 =head3 lastTextMatches($node, $match, @context)
16651  
16652 Return the last node under the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context. Else return B<undef>.
16653  
16654 Parameter Description
16655 1 $node Node
16656 2 $match Regular expression the text must match
16657 3 @context Optional context of specified node.
16658  
16659 Use the optional B<@context> parameter to test the context of the specified
16660 B<$node> as understood by method L<at|/at>. If the context is supplied and
16661 B<$node> is not in this context then this method returns B<undef> immediately.
16662  
16663  
16664  
16665 B<Example:>
16666  
16667  
16668 {my $a = Data::Edit::Xml::new(<<END);
16669 <a>
16670 <b>bb<c>cc</c>BB
16671 </b>
16672 </a>
16673 END
16674  
16675 my ($bb, $cc, $c, $BB, $b) = $a->byList;
16676  
16677 ok $BB->matchesText(qr(BB));
16678  
16679  
16680 ok $b->at_b_a && $b->lastTextMatches(qr(BB)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16681  
16682  
16683  
16684 ok $b->lastTextMatches(qr(BB), qw(b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16685  
16686  
16687  
16688 ok $c->at_c_b && $c->lastTextMatches(qr(cc)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16689  
16690  
16691  
16692 ok $c->at_c_b && !$c->lastTextMatches(qr(bb)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16693  
16694  
16695  
16696 =head3 lastBy($node, @tags)
16697  
16698 Return a list of the last instance of each specified tag encountered in a post-order traversal from the specified B<$node> or a hash of all last instances if no tags are specified.
16699  
16700 Parameter Description
16701 1 $node Node
16702 2 @tags Tags to search for.
16703  
16704 B<Example:>
16705  
16706  
16707 my $a = Data::Edit::Xml::new(<<END);
16708 <a id="11">
16709 <b id="12">
16710 <c id="13"/>
16711 <d id="14"/>
16712 <b id="15">
16713 <c id="16"/>
16714 <d id="17"/>
16715 <e id="18"/>
16716 <f id="19"/>
16717 <g id="20"/>
16718 </b>
16719 <f id="21"/>
16720 <g id="22"/>
16721 </b>
16722 <b id="23">
16723 <c id="24"/>
16724 <d id="25"/>
16725 <b id="26">
16726 <c id="27"/>
16727 <d id="28"/>
16728 <e id="29"/>
16729 <f id="30"/>
16730 <g id="31"/>
16731 </b>
16732 <f id="32"/>
16733 <g id="33"/>
16734 </b>
16735 </a>
16736 END
16737  
16738  
16739 {my %l = $a->lastBy; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16740  
16741  
16742 ok $l{b}->id == 23;
16743  
16744  
16745 =head3 lastDown($node, @tags)
16746  
16747 Return a list of the last instance of each specified tag encountered in a pre-order traversal from the specified B<$node> or a hash of all last instances if no tags are specified.
16748  
16749 Parameter Description
16750 1 $node Node
16751 2 @tags Tags to search for.
16752  
16753 B<Example:>
16754  
16755  
16756  
16757 {my %l = $a->lastDown; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16758  
16759  
16760 ok $l{b}->id == 26;
16761  
16762  
16763 =head3 lastIn($node, @tags)
16764  
16765 Return the last child node matching one of the named tags under the specified parent node.
16766  
16767 Parameter Description
16768 1 $node Parent node
16769 2 @tags Child tags to search for.
16770  
16771 B<Example:>
16772  
16773  
16774 ok $a->prettyStringCDATA eq <<'END';
16775 <a><CDATA> </CDATA>
16776 <A/>
16777 <CDATA> </CDATA>
16778 <C/>
16779 <CDATA> </CDATA>
16780 <E/>
16781 <CDATA> </CDATA>
16782 <G/>
16783 <CDATA> </CDATA>
16784 </a>
16785 END
16786  
16787  
16788 ok $a->lastIn(qw(e E f F))->tag eq qq(E); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16789  
16790  
16791  
16792 =head3 lastNot($node, @tags)
16793  
16794 Return the last child node that does not match any of the named B<@tags> under the specified parent B<$node>. Return B<undef> if there is no such child node.
16795  
16796 Parameter Description
16797 1 $node Parent node
16798 2 @tags Child tags to avoid.
16799  
16800 B<Example:>
16801  
16802  
16803 {my $a = Data::Edit::Xml::new(<<END);
16804 <a>
16805 <b/>
16806 <c/>
16807 <d/>
16808 <e/>
16809 <f/>
16810 </a>
16811 END
16812  
16813 my ($b, $c, $d, $e, $f) = $a->byList;
16814  
16815 ok $d == $a->lastNot_e_f;
16816  
16817  
16818 =head3 lastOf($node, @tags)
16819  
16820 Return an array of the nodes that are continuously last under their specified parent node and that match the specified list of tags.
16821  
16822 Parameter Description
16823 1 $node Node
16824 2 @tags Tags to search for.
16825  
16826 B<Example:>
16827  
16828  
16829 {my $a = Data::Edit::Xml::new(<<END);
16830 <a><b><c/><d/><d/><e/><d/><d/><c/></b></a>
16831 END
16832  
16833  
16834 is_deeply [qw(d d c)], [map {-t $_} $a->go(q(b))->lastOf (qw(c d))]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16835  
16836  
16837  
16838 =head3 lastInIndex($node, @context)
16839  
16840 Return the specified B<$node> if it is last in its index and optionally L<at|/at> the specified context else B<undef>
16841  
16842 Parameter Description
16843 1 $node Node
16844 2 @context Optional context.
16845  
16846 Use the optional B<@context> parameter to test the context of the specified
16847 B<$node> as understood by method L<at|/at>. If the context is supplied and
16848 B<$node> is not in this context then this method returns B<undef> immediately.
16849  
16850  
16851  
16852 B<Example:>
16853  
16854  
16855 ok -z $a eq <<END;
16856 <a id="1">
16857 <b id="2">
16858 <c id="3">
16859 <e id="4"/>
16860 </c>
16861 <d id="5">
16862 <e id="6"/>
16863 </d>
16864 <c id="7">
16865 <d id="8">
16866 <e id="9"/>
16867 </d>
16868 </c>
16869 <d id="10">
16870 <e id="11"/>
16871 </d>
16872 <c id="12">
16873 <d id="13">
16874 <e id="14"/>
16875 </d>
16876 </c>
16877 </b>
16878 </a>
16879 END
16880  
16881  
16882 ok $a->findByNumber(10)->lastInIndex; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16883  
16884  
16885  
16886 ok !$a->findByNumber(7) ->lastInIndex; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16887  
16888  
16889  
16890 =head3 lastContextOf($node, @context)
16891  
16892 Return the last node encountered in the specified context in a depth first reverse pre-order traversal of the L<parse|/parse> tree.
16893  
16894 Parameter Description
16895 1 $node Node
16896 2 @context Array of tags specifying context.
16897  
16898 Use the optional B<@context> parameter to test the context of the specified
16899 B<$node> as understood by method L<at|/at>. If the context is supplied and
16900 B<$node> is not in this context then this method returns B<undef> immediately.
16901  
16902  
16903  
16904 B<Example:>
16905  
16906  
16907 my $x = Data::Edit::Xml::new(<<END);
16908 <a id="a1">
16909 <b1 id="b1">
16910 <c id="c1">
16911 <d id="d1">DD11</d>
16912 <e id="e1">EE11</e>
16913 </c>
16914 </b1>
16915 <b2 id="b2">
16916 <c id="c2">
16917 <d id="d2">DD22</d>
16918 <e id="e2">EE22</e>
16919 </c>
16920 </b2>
16921 <b3 id="b3">
16922 <c id="c3">
16923 <d id="d3">DD33</d>
16924 <e id="e3">EE33</e>
16925 </c>
16926 </b3>
16927 </a>
16928 END
16929  
16930  
16931 ok $x-> lastContextOf(qw(d c)) ->id eq qq(d3); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16932  
16933  
16934  
16935 ok $x-> lastContextOf(qw(e c b2 )) ->id eq qq(e2); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16936  
16937  
16938  
16939 ok $x-> lastContextOf(qw(CDATA e c b2))->string eq qq(EE22); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16940  
16941  
16942  
16943 =head3 lastSibling($node, @context)
16944  
16945 Return the last sibling of the specified B<$node> in the optional B<@context> else B<undef>
16946  
16947 Parameter Description
16948 1 $node Node
16949 2 @context Array of tags specifying context.
16950  
16951 Use the optional B<@context> parameter to test the context of the specified
16952 B<$node> as understood by method L<at|/at>. If the context is supplied and
16953 B<$node> is not in this context then this method returns B<undef> immediately.
16954  
16955  
16956  
16957 B<Example:>
16958  
16959  
16960 my $a = Data::Edit::Xml::new(<<END);
16961 <a id="11">
16962 <b id="12">
16963 <c id="13"/>
16964 <d id="14"/>
16965 <b id="15">
16966 <c id="16"/>
16967 <d id="17"/>
16968 <e id="18"/>
16969 <f id="19"/>
16970 <g id="20"/>
16971 </b>
16972 <f id="21"/>
16973 <g id="22"/>
16974 </b>
16975 <b id="23">
16976 <c id="24"/>
16977 <d id="25"/>
16978 <b id="26">
16979 <c id="27"/>
16980 <d id="28"/>
16981 <e id="29"/>
16982 <f id="30"/>
16983 <g id="31"/>
16984 </b>
16985 <f id="32"/>
16986 <g id="33"/>
16987 </b>
16988 </a>
16989 END
16990  
16991  
16992 ok $a->go(qw(b b))->lastSibling ->id == 22; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
16993  
16994  
16995  
16996 =head3 lastWhile($node, @tags)
16997  
16998 Go last from the specified B<$node> and continue deeper lastly as long as each last child node matches one of the specified B<@tags>. Return the deepest such node encountered or else return B<undef> if no such node is encountered.
16999  
17000 Parameter Description
17001 1 $node Node
17002 2 @tags Tags to search for.
17003  
17004 B<Example:>
17005  
17006  
17007 my $a = Data::Edit::Xml::new(<<END);
17008 <a>
17009 <b>
17010 <c>
17011 <d>
17012 <e>
17013 <f/>
17014 </e>
17015 </d>
17016 </c>
17017 </b>
17018 <B>
17019 <C>
17020 <D>
17021 <E>
17022 <F/>
17023 </E>
17024 </D>
17025 </C>
17026 </B>
17027 </a>
17028 END
17029 my ($f, $e, $d, $c, $b, $F, $E, $D, $C, $B) = $a->byList;
17030  
17031 ok eval qq(-t \$$_ eq q($_)), $_ for qw(a b c d e f B C D E F);
17032  
17033 ok $d == $a->firstWhile_a_d_c_b;
17034 ok $f == $a->firstWhile_a_d_c_b_e_f_g_h;
17035 ok !$b->firstWhile_a;
17036  
17037 ok $e == $a->firstUntil_e_d;
17038 ok !$c->firstUntil_c;
17039 ok !$b->firstUntil_a;
17040  
17041 ok $D == $a->lastWhile_a_D_C_B;
17042 ok $F == $a->lastWhile_a_D_C_B_E_F_G_H;
17043 ok !$B->lastWhile_a;
17044  
17045 ok $E == $a->lastUntil_E_D;
17046 ok !$C->lastUntil_C;
17047 ok !$B->lastUntil_a;
17048  
17049  
17050 =head3 lastUntil($node, @context)
17051  
17052 Go last from the specified B<$node> and continue deeper lastly until a last child node matches the specified B<@context> or return B<undef> if there is no such node. Return the last child of the specified B<$node> if no B<@context> is specified.
17053  
17054 Parameter Description
17055 1 $node Node
17056 2 @context Context to search for.
17057  
17058 Use the optional B<@context> parameter to test the context of the specified
17059 B<$node> as understood by method L<at|/at>. If the context is supplied and
17060 B<$node> is not in this context then this method returns B<undef> immediately.
17061  
17062  
17063  
17064 B<Example:>
17065  
17066  
17067 my $a = Data::Edit::Xml::new(<<END);
17068 <a>
17069 <b>
17070 <c>
17071 <d>
17072 <e>
17073 <f/>
17074 </e>
17075 </d>
17076 </c>
17077 </b>
17078 <B>
17079 <C>
17080 <D>
17081 <E>
17082 <F/>
17083 </E>
17084 </D>
17085 </C>
17086 </B>
17087 </a>
17088 END
17089 my ($f, $e, $d, $c, $b, $F, $E, $D, $C, $B) = $a->byList;
17090  
17091 ok eval qq(-t \$$_ eq q($_)), $_ for qw(a b c d e f B C D E F);
17092  
17093 ok $d == $a->firstWhile_a_d_c_b;
17094 ok $f == $a->firstWhile_a_d_c_b_e_f_g_h;
17095 ok !$b->firstWhile_a;
17096  
17097 ok $e == $a->firstUntil_e_d;
17098 ok !$c->firstUntil_c;
17099 ok !$b->firstUntil_a;
17100  
17101 ok $D == $a->lastWhile_a_D_C_B;
17102 ok $F == $a->lastWhile_a_D_C_B_E_F_G_H;
17103 ok !$B->lastWhile_a;
17104  
17105 ok $E == $a->lastUntil_E_D;
17106 ok !$C->lastUntil_C;
17107 ok !$B->lastUntil_a;
17108  
17109  
17110 =head3 lastUntilText($node, @context)
17111  
17112 Go last from the specified B<$node> and continue deeper lastly until a last child text node matches the specified B<@context> or return B<undef> if there is no such node.
17113  
17114 Parameter Description
17115 1 $node Node
17116 2 @context Context to search for.
17117  
17118 Use the optional B<@context> parameter to test the context of the specified
17119 B<$node> as understood by method L<at|/at>. If the context is supplied and
17120 B<$node> is not in this context then this method returns B<undef> immediately.
17121  
17122  
17123  
17124 B<Example:>
17125  
17126  
17127 my $a = Data::Edit::Xml::new(<<END);
17128 <a>
17129 <b>
17130 cccc
17131 <d/>
17132 <e/>
17133 </b>
17134 <f>
17135 <g/>
17136 hhhh
17137 <i/>
17138 </f>
17139 <j>
17140 <k/>
17141 <l/>
17142 mmmm
17143 </j>
17144 </a>
17145 END
17146  
17147 ok $a->firstUntilText->text =~ m(cccc)s;
17148  
17149 ok $a->lastUntilText ->text =~ m(mmmm)s; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17150  
17151  
17152  
17153  
17154 =head2 Next
17155  
17156 Find sibling nodes after the specified B<$node>.
17157  
17158 =head3 next($node, @context)
17159  
17160 Return the node next to the specified B<$node>, optionally checking the next node's context. See L<addNext|/addNext> to ensure that an expected node is in position.
17161  
17162 Parameter Description
17163 1 $node Node
17164 2 @context Optional context.
17165  
17166 Use the optional B<@context> parameter to test the context of the specified
17167 B<$node> as understood by method L<at|/at>. If the context is supplied and
17168 B<$node> is not in this context then this method returns B<undef> immediately.
17169  
17170 Use B<nextNonBlank> to skip a (rare) initial blank text CDATA. Use B<nextNonBlankX> to die rather
17171 then receive a returned B<undef> or false result.
17172  
17173  
17174  
17175 B<Example:>
17176  
17177  
17178 my $a = Data::Edit::Xml::new(<<END);
17179 <a id="11">
17180 <b id="12">
17181 <c id="13"/>
17182 <d id="14"/>
17183 <b id="15">
17184 <c id="16"/>
17185 <d id="17"/>
17186 <e id="18"/>
17187 <f id="19"/>
17188 <g id="20"/>
17189 </b>
17190 <f id="21"/>
17191 <g id="22"/>
17192 </b>
17193 <b id="23">
17194 <c id="24"/>
17195 <d id="25"/>
17196 <b id="26">
17197 <c id="27"/>
17198 <d id="28"/>
17199 <e id="29"/>
17200 <f id="30"/>
17201 <g id="31"/>
17202 </b>
17203 <f id="32"/>
17204 <g id="33"/>
17205 </b>
17206 </a>
17207 END
17208  
17209  
17210 ok $a->go(qw(b b e))->next ->id == 19; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17211  
17212  
17213  
17214 ok $a->go(qw(b b e))->next(qw(f b b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17215  
17216  
17217  
17218 ok !$a->go(qw(b b e))->next(qw(f b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17219  
17220  
17221  
17222 =head3 nextn($node, $N, @context)
17223  
17224 Return the B<$n>'th next node after the specified B<$node> optionally checking its context or B<undef> if there is no such node. B<nextn(1)> is identical in effect to L<next|/next>.
17225  
17226 Parameter Description
17227 1 $node Node
17228 2 $N Number of times to go next
17229 3 @context Optional context.
17230  
17231 Use the optional B<@context> parameter to test the context of the specified
17232 B<$node> as understood by method L<at|/at>. If the context is supplied and
17233 B<$node> is not in this context then this method returns B<undef> immediately.
17234  
17235  
17236  
17237 B<Example:>
17238  
17239  
17240 if (1)
17241 {my $a = Data::Edit::Xml::new(<<END);
17242 <a><b><c><d/><e/><f/></c></b></a>
17243 END
17244 ok -p $a eq <<END;
17245 <a>
17246 <b>
17247 <c>
17248 <d/>
17249 <e/>
17250 <f/>
17251 </c>
17252 </b>
17253 </a>
17254 END
17255 ok -t $a->firstn_0 eq q(a);
17256 ok -t $a->firstn_1 eq q(b);
17257 ok -t $a->firstn_2 eq q(c);
17258 ok -t $a->firstn_3 eq q(d);
17259  
17260 ok -t $a->firstn_3__nextn_0 eq q(d);
17261 ok -t $a->firstn_3__nextn_1 eq q(e);
17262 ok -t $a->firstn_3__nextn_2 eq q(f);
17263 }
17264  
17265  
17266 =head3 nextText($node, @context)
17267  
17268 Return the node after the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
17269  
17270 Parameter Description
17271 1 $node Node
17272 2 @context Optional context.
17273  
17274 Use the optional B<@context> parameter to test the context of the specified
17275 B<$node> as understood by method L<at|/at>. If the context is supplied and
17276 B<$node> is not in this context then this method returns B<undef> immediately.
17277  
17278  
17279  
17280 B<Example:>
17281  
17282  
17283 my $a = Data::Edit::Xml::new("<a>AA<b/>BB<c/>CC<d/><e/><f/>DD<g/>HH</a>");
17284 ok -p $a eq <<END;
17285 <a>AA
17286 <b/>
17287 BB
17288 <c/>
17289 CC
17290 <d/>
17291 <e/>
17292 <f/>
17293 DD
17294 <g/>
17295 HH
17296 </a>
17297 END
17298 ok $a->firstText_a__text eq q(AA);
17299 ok !$a->go_c__firstText_c_a;
17300 ok !$a->go_c__firstText_c_b;
17301 ok $a->lastText__text eq q(HH);
17302 ok $a->lastText_a__text eq q(HH);
17303 ok !$a->go_c__lastText;
17304 ok $a->go_c__nextText_c_a__text eq q(CC);
17305 ok !$a->go_e__nextText;
17306 ok $a->go_c__prevText_c__text eq q(BB);
17307 ok !$a->go_e__prevText;
17308  
17309  
17310 =head3 nextTextMatches($node, $match, @context)
17311  
17312 Return the next node to the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context. Else return B<undef>.
17313  
17314 Parameter Description
17315 1 $node Node
17316 2 $match Regular expression the text must match
17317 3 @context Optional context of specified node.
17318  
17319 Use the optional B<@context> parameter to test the context of the specified
17320 B<$node> as understood by method L<at|/at>. If the context is supplied and
17321 B<$node> is not in this context then this method returns B<undef> immediately.
17322  
17323  
17324  
17325 B<Example:>
17326  
17327  
17328 {my $a = Data::Edit::Xml::new(<<END);
17329 <a>
17330 <b>bb<c>cc</c>BB
17331 </b>
17332 </a>
17333 END
17334  
17335 ok $cc->matchesText(qr(cc));
17336  
17337  
17338 ok $c->at_c_b && $c->nextTextMatches(qr(BB)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17339  
17340  
17341  
17342 ok $b->at_b && !$b->nextTextMatches(qr(BB)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17343  
17344  
17345  
17346 =head3 nextIn($node, @tags)
17347  
17348 Return the nearest sibling after the specified B<$node> that matches one of the named tags or B<undef> if there is no such sibling node.
17349  
17350 Parameter Description
17351 1 $node Node
17352 2 @tags Tags to search for.
17353  
17354 B<Example:>
17355  
17356  
17357 ok $a->prettyStringCDATA eq <<'END';
17358 <a><CDATA> </CDATA>
17359 <A/>
17360 <CDATA> </CDATA>
17361 <C/>
17362 <CDATA> </CDATA>
17363 <E/>
17364 <CDATA> </CDATA>
17365 <G/>
17366 <CDATA> </CDATA>
17367 </a>
17368 END
17369  
17370  
17371 ok $a->firstIn(qw(b B c C))->nextIn(qw(A G))->tag eq qq(G); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17372  
17373  
17374  
17375 =head3 nextOn($node, @tags)
17376  
17377 Step forwards as far as possible from the specified B<$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.
17378  
17379 Parameter Description
17380 1 $node Start node
17381 2 @tags Tags identifying nodes that can be step on to context.
17382  
17383 B<Example:>
17384  
17385  
17386 ok -p $a eq <<END;
17387 <a>
17388 <b>
17389 <c id="1"/>
17390 <d id="2"/>
17391 <c id="3"/>
17392 <d id="4"/>
17393 <e id="5"/>
17394 </b>
17395 </a>
17396 END
17397  
17398 ok $c->id == 1;
17399  
17400 ok $e->id == 5;
17401  
17402  
17403 ok $c->nextOn(qw(d)) ->id == 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17404  
17405  
17406  
17407 ok $c->nextOn(qw(c d))->id == 4; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17408  
17409  
17410  
17411 ok $e->nextOn(qw(c d)) == $e; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17412  
17413  
17414  
17415 =head3 nextWhile($node, @tags)
17416  
17417 Go to the next sibling of the specified B<$node> and continue forwards while the tag of each sibling node matches one of the specified B<@tags>. Return the first sibling node that does not match else B<undef> if there is no such sibling.
17418  
17419 Parameter Description
17420 1 $node Node
17421 2 @tags Child tags to avoid.
17422  
17423 B<Example:>
17424  
17425  
17426 {my $a = Data::Edit::Xml::new(<<END);
17427 <a>
17428 <b/>
17429 <c/>
17430 <d/>
17431 <e/>
17432 <f/>
17433 </a>
17434 END
17435  
17436 my ($b, $c, $d, $e, $f) = $a->byList;
17437  
17438 ok $e == $b->nextWhile_c_d;
17439  
17440  
17441 ok $c == $b->nextWhile; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17442  
17443  
17444  
17445 =head3 nextUntil($node, @tags)
17446  
17447 Go to the next sibling of the specified B<$node> and continue forwards until the tag of a sibling node matches one of the specified B<@tags>. Return the matching sibling node else B<undef> if there is no such sibling node.
17448  
17449 Parameter Description
17450 1 $node Node
17451 2 @tags Tags to look for.
17452  
17453 B<Example:>
17454  
17455  
17456 {my $a = Data::Edit::Xml::new(<<END);
17457 <a>
17458 <b/>
17459 <c/>
17460 <d/>
17461 <e/>
17462 <f/>
17463 </a>
17464 END
17465  
17466 my ($b, $c, $d, $e, $f) = $a->byList;
17467  
17468 ok $e == $b->nextUntil_e_f;
17469  
17470  
17471 ok !$b->nextUntil; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17472  
17473  
17474  
17475 =head2 Prev
17476  
17477 Find sibling nodes before the specified B<$node>.
17478  
17479 =head3 prev($node, @context)
17480  
17481 Return the node before the specified B<$node>, optionally checking the previous node's context. See L<addLast|/addLast> to ensure that an expected node is in position.
17482  
17483 Parameter Description
17484 1 $node Node
17485 2 @context Optional context.
17486  
17487 Use the optional B<@context> parameter to test the context of the specified
17488 B<$node> as understood by method L<at|/at>. If the context is supplied and
17489 B<$node> is not in this context then this method returns B<undef> immediately.
17490  
17491 Use B<prevNonBlank> to skip a (rare) initial blank text CDATA. Use B<prevNonBlankX> to die rather
17492 then receive a returned B<undef> or false result.
17493  
17494  
17495  
17496 B<Example:>
17497  
17498  
17499 my $a = Data::Edit::Xml::new(<<END);
17500 <a id="11">
17501 <b id="12">
17502 <c id="13"/>
17503 <d id="14"/>
17504 <b id="15">
17505 <c id="16"/>
17506 <d id="17"/>
17507 <e id="18"/>
17508 <f id="19"/>
17509 <g id="20"/>
17510 </b>
17511 <f id="21"/>
17512 <g id="22"/>
17513 </b>
17514 <b id="23">
17515 <c id="24"/>
17516 <d id="25"/>
17517 <b id="26">
17518 <c id="27"/>
17519 <d id="28"/>
17520 <e id="29"/>
17521 <f id="30"/>
17522 <g id="31"/>
17523 </b>
17524 <f id="32"/>
17525 <g id="33"/>
17526 </b>
17527 </a>
17528 END
17529  
17530  
17531 ok $a->go(qw(b b e))->prev ->id == 17; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17532  
17533  
17534  
17535 ok $a->go(qw(b b e))->prev(qw(d b b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17536  
17537  
17538  
17539 ok !$a->go(qw(b b e))->prev(qw(d b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17540  
17541  
17542  
17543 =head3 prevText($node, @context)
17544  
17545 Return the node before the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
17546  
17547 Parameter Description
17548 1 $node Node
17549 2 @context Optional context.
17550  
17551 Use the optional B<@context> parameter to test the context of the specified
17552 B<$node> as understood by method L<at|/at>. If the context is supplied and
17553 B<$node> is not in this context then this method returns B<undef> immediately.
17554  
17555  
17556  
17557 B<Example:>
17558  
17559  
17560 my $a = Data::Edit::Xml::new("<a>AA<b/>BB<c/>CC<d/><e/><f/>DD<g/>HH</a>");
17561 ok -p $a eq <<END;
17562 <a>AA
17563 <b/>
17564 BB
17565 <c/>
17566 CC
17567 <d/>
17568 <e/>
17569 <f/>
17570 DD
17571 <g/>
17572 HH
17573 </a>
17574 END
17575 ok $a->firstText_a__text eq q(AA);
17576 ok !$a->go_c__firstText_c_a;
17577 ok !$a->go_c__firstText_c_b;
17578 ok $a->lastText__text eq q(HH);
17579 ok $a->lastText_a__text eq q(HH);
17580 ok !$a->go_c__lastText;
17581 ok $a->go_c__nextText_c_a__text eq q(CC);
17582 ok !$a->go_e__nextText;
17583 ok $a->go_c__prevText_c__text eq q(BB);
17584 ok !$a->go_e__prevText;
17585  
17586  
17587 =head3 prevn($node, $N, @context)
17588  
17589 Return the B<$n>'th previous node after the specified B<$node> optionally checking its context or B<undef> if there is no such node. B<prevn(1)> is identical in effect to L<prev|/prev>.
17590  
17591 Parameter Description
17592 1 $node Node
17593 2 $N Number of times to go prev
17594 3 @context Optional context.
17595  
17596 Use the optional B<@context> parameter to test the context of the specified
17597 B<$node> as understood by method L<at|/at>. If the context is supplied and
17598 B<$node> is not in this context then this method returns B<undef> immediately.
17599  
17600  
17601  
17602 B<Example:>
17603  
17604  
17605 if (1)
17606 {my $a = Data::Edit::Xml::new(<<END);
17607 <a><b><c><d/><e/><f/></c></b>
17608 <B><C><D/><E/><F/></C></B></a>
17609 END
17610 ok -p $a eq <<END;
17611 <a>
17612 <b>
17613 <c>
17614 <d/>
17615 <e/>
17616 <f/>
17617 </c>
17618 </b>
17619 <B>
17620 <C>
17621 <D/>
17622 <E/>
17623 <F/>
17624 </C>
17625 </B>
17626 </a>
17627 END
17628  
17629 ok -t $a->lastn_0 eq q(a);
17630 ok -t $a->lastn_1 eq q(B);
17631 ok -t $a->lastn_2 eq q(C);
17632 ok -t $a->lastn_3 eq q(F);
17633  
17634 ok -t $a->lastn_3__prevn_0 eq q(F);
17635 ok -t $a->lastn_3__prevn_1 eq q(E);
17636 ok -t $a->lastn_3__prevn_2 eq q(D);
17637 }
17638  
17639  
17640 =head3 prevTextMatches($node, $match, @context)
17641  
17642 Return the previous node to the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context. Else return B<undef>.
17643  
17644 Parameter Description
17645 1 $node Node
17646 2 $match Regular expression the text must match
17647 3 @context Optional context of specified node.
17648  
17649 Use the optional B<@context> parameter to test the context of the specified
17650 B<$node> as understood by method L<at|/at>. If the context is supplied and
17651 B<$node> is not in this context then this method returns B<undef> immediately.
17652  
17653  
17654  
17655 B<Example:>
17656  
17657  
17658 {my $a = Data::Edit::Xml::new(<<END);
17659 <a>
17660 <b>bb<c>cc</c>BB
17661 </b>
17662 </a>
17663 END
17664  
17665 ok $cc->matchesText(qr(cc));
17666  
17667  
17668 ok $c->at_c_b && $c->prevTextMatches(qr(bb)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17669  
17670  
17671  
17672 ok $b->at_b && !$b->prevTextMatches(qr(bb)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17673  
17674  
17675  
17676 =head3 prevIn($node, @tags)
17677  
17678 Return the nearest sibling node before the specified B<$node> which matches one of the named tags or B<undef> if there is no such sibling node.
17679  
17680 Parameter Description
17681 1 $node Node
17682 2 @tags Tags to search for.
17683  
17684 B<Example:>
17685  
17686  
17687 ok $a->prettyStringCDATA eq <<'END';
17688 <a><CDATA> </CDATA>
17689 <A/>
17690 <CDATA> </CDATA>
17691 <C/>
17692 <CDATA> </CDATA>
17693 <E/>
17694 <CDATA> </CDATA>
17695 <G/>
17696 <CDATA> </CDATA>
17697 </a>
17698 END
17699  
17700  
17701 ok $a->lastIn(qw(e E f F))->prevIn(qw(A G))->tag eq qq(A); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17702  
17703  
17704  
17705 =head3 prevOn($node, @tags)
17706  
17707 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.
17708  
17709 Parameter Description
17710 1 $node Start node
17711 2 @tags Tags identifying nodes that can be step on to context.
17712  
17713 B<Example:>
17714  
17715  
17716 ok -p $a eq <<END;
17717 <a>
17718 <b>
17719 <c id="1"/>
17720 <d id="2"/>
17721 <c id="3"/>
17722 <d id="4"/>
17723 <e id="5"/>
17724 </b>
17725 </a>
17726 END
17727  
17728 ok $c->id == 1;
17729  
17730 ok $e->id == 5;
17731  
17732  
17733 ok $e->prevOn(qw(d)) ->id == 4; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17734  
17735  
17736  
17737 ok $e->prevOn(qw(c d)) == $c; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17738  
17739  
17740  
17741 =head3 prevWhile($node, @tags)
17742  
17743 Go to the previous sibling of the specified B<$node> and continue backwards while the tag of each sibling node matches one of the specified B<@tags>. Return the first sibling node that does not match else B<undef> if there is no such sibling.
17744  
17745 Parameter Description
17746 1 $node Parent node
17747 2 @tags Child tags to avoid.
17748  
17749 B<Example:>
17750  
17751  
17752 {my $a = Data::Edit::Xml::new(<<END);
17753 <a>
17754 <b/>
17755 <c/>
17756 <d/>
17757 <e/>
17758 <f/>
17759 </a>
17760 END
17761  
17762 my ($b, $c, $d, $e, $f) = $a->byList;
17763  
17764 ok $c == $f->prevWhile_e_d;
17765  
17766  
17767 ok $b == $c->prevWhile; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17768  
17769  
17770  
17771 =head3 prevUntil($node, @tags)
17772  
17773 Go to the previous sibling of the specified B<$node> and continue backwards until the tag of a sibling node matches one of the specified B<@tags>. Return the matching sibling node else B<undef> if there is no such sibling node.
17774  
17775 Parameter Description
17776 1 $node Node
17777 2 @tags Tags to look for.
17778  
17779 B<Example:>
17780  
17781  
17782 {my $a = Data::Edit::Xml::new(<<END);
17783 <a>
17784 <b/>
17785 <c/>
17786 <d/>
17787 <e/>
17788 <f/>
17789 </a>
17790 END
17791  
17792 my ($b, $c, $d, $e, $f) = $a->byList;
17793  
17794 ok $b == $f->prevUntil_a_b;
17795  
17796  
17797 ok !$c->prevUntil; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17798  
17799  
17800  
17801 =head2 Up
17802  
17803 Methods for moving up the L<parse|/parse> tree from a node.
17804  
17805 =head3 top($node, @context)
17806  
17807 Return the top of the parse tree containing the current B<$node> after optionally checking that the $node is in the optional B<@context>.
17808  
17809 Parameter Description
17810 1 $node Start node
17811 2 @context Optional context
17812  
17813 Use the optional B<@context> parameter to test the context of the specified
17814 B<$node> as understood by method L<at|/at>. If the context is supplied and
17815 B<$node> is not in this context then this method returns B<undef> immediately.
17816  
17817  
17818  
17819 B<Example:>
17820  
17821  
17822 my $a = Data::Edit::Xml::new(<<END);
17823 <a><b><c><d/></c></b></a>
17824 END
17825  
17826 $a->by(sub
17827 {ok $a == $_->root;
17828  
17829 ok $a == $_->top; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
17830  
17831 });
17832  
17833  
17834 =head3 up($node, @context)
17835  
17836 Return the parent of the current node optionally checking the parent node's context or return B<undef> if the specified B<$node> is the root of the L<parse|/parse> tree. See L<addWrapWith|/addWrapWith> to ensure that an expected node is in position.
17837  
17838 Parameter Description
17839 1 $node Start node
17840 2 @context Optional context of parent.
17841  
17842 Use the optional B<@context> parameter to test the context of the specified
17843 B<$node> as understood by method L<at|/at>. If the context is supplied and
17844 B<$node> is not in this context then this method returns B<undef> immediately.
17845  
17846  
17847  
17848 B<Example:>
17849  
17850  
17851 if (1)
17852 {my $a = Data::Edit::Xml::new(<<END);
17853 <a><b><c><b><b><b><b><c/></b></b></b></b></c></b></a>
17854 END
17855  
17856 $a->numberTree;
17857 ok -z $a eq <<END;
17858 <a id="1">
17859 <b id="2">
17860 <c id="3">
17861 <b id="4">
17862 <b id="5">
17863 <b id="6">
17864 <b id="7">
17865 <c id="8"/>
17866 </b>
17867 </b>
17868 </b>
17869 </b>
17870 </c>
17871 </b>
17872 </a>
17873 END
17874  
17875 my $c = $a->findByNumber(8);
17876 ok -t $c eq q(c);
17877 ok $c->up_b__number == 7;
17878 ok $c->upn_2__number == 6;
17879 ok $c->upWhile_b__number == 4;
17880 ok $c->upWhile_a_b__number == 4;
17881 ok $c->upWhile_b_c__number == 2;
17882  
17883 ok $c->upUntil__number == 8;
17884 ok $c->upUntil_b_c__number == 4;
17885 }
17886  
17887  
17888 =head3 upn($node, $levels, @context)
17889  
17890 Go up the specified number of levels from the specified B<$node> and return the node reached optionally checking the parent node's context or B<undef> if there is no such node.L<upn(1)|/up> is identical in effect to L<up|/up>. Or use L<ancestry|/ancestry> to get the path back to the root node.
17891  
17892 Parameter Description
17893 1 $node Start node
17894 2 $levels Number of levels to go up
17895 3 @context Optional context.
17896  
17897 Use the optional B<@context> parameter to test the context of the specified
17898 B<$node> as understood by method L<at|/at>. If the context is supplied and
17899 B<$node> is not in this context then this method returns B<undef> immediately.
17900  
17901  
17902  
17903 B<Example:>
17904  
17905  
17906 if (1)
17907 {my $a = Data::Edit::Xml::new(<<END);
17908 <a><b><c><b><b><b><b><c/></b></b></b></b></c></b></a>
17909 END
17910  
17911 $a->numberTree;
17912 ok -z $a eq <<END;
17913 <a id="1">
17914 <b id="2">
17915 <c id="3">
17916 <b id="4">
17917 <b id="5">
17918 <b id="6">
17919 <b id="7">
17920 <c id="8"/>
17921 </b>
17922 </b>
17923 </b>
17924 </b>
17925 </c>
17926 </b>
17927 </a>
17928 END
17929  
17930 my $c = $a->findByNumber(8);
17931 ok -t $c eq q(c);
17932 ok $c->up_b__number == 7;
17933 ok $c->upn_2__number == 6;
17934 ok $c->upWhile_b__number == 4;
17935 ok $c->upWhile_a_b__number == 4;
17936 ok $c->upWhile_b_c__number == 2;
17937  
17938 ok $c->upUntil__number == 8;
17939 ok $c->upUntil_b_c__number == 4;
17940 }
17941  
17942 if (1)
17943 {my $a = Data::Edit::Xml::new(<<END);
17944 <a><b><c><d><e/></d></c></b></a>
17945 END
17946  
17947 my ($e, $d, $c, $b) = $a->byList;
17948  
17949 ok $e = $e->upn_0_e_d_c_b_a;
17950 ok $d = $e->upn_1_d_c_b_a;
17951 ok $c = $e->upn_2_c_b_a;
17952 ok $b = $e->upn_3_b_a;
17953 ok $a = $e->upn_4_a;
17954 ok !$e->upn_5;
17955  
17956 is_deeply [$e, $d, $c, $b, $a], [$e->ancestry];
17957 }
17958  
17959 {my $a = Data::Edit::Xml::new(<<END);
17960 <a><b><c><d><e/></d></c></b></a>
17961 END
17962  
17963 my ($e, $d, $c, $b) = $a->byList;
17964  
17965 ok $e = $e->upn_0_e_d_c_b_a;
17966  
17967 ok $d = $e->upn_1_d_c_b_a;
17968  
17969 ok $c = $e->upn_2_c_b_a;
17970  
17971 ok $b = $e->upn_3_b_a;
17972  
17973 ok $a = $e->upn_4_a;
17974  
17975 ok !$e->upn_5;
17976  
17977  
17978 =head3 upWhile($node, @tags)
17979  
17980 Go up one level from the specified B<$node> and then continue up while each node matches on of the specified <@tags>. Return the last matching node or B<undef> if no node matched any of the specified B<@tags>.
17981  
17982 Parameter Description
17983 1 $node Start node
17984 2 @tags Tags to match
17985  
17986 B<Example:>
17987  
17988  
17989 if (1)
17990 {my $a = Data::Edit::Xml::new(<<END);
17991 <a><b><c><b><b><b><b><c/></b></b></b></b></c></b></a>
17992 END
17993  
17994 $a->numberTree;
17995 ok -z $a eq <<END;
17996 <a id="1">
17997 <b id="2">
17998 <c id="3">
17999 <b id="4">
18000 <b id="5">
18001 <b id="6">
18002 <b id="7">
18003 <c id="8"/>
18004 </b>
18005 </b>
18006 </b>
18007 </b>
18008 </c>
18009 </b>
18010 </a>
18011 END
18012  
18013 my $c = $a->findByNumber(8);
18014 ok -t $c eq q(c);
18015 ok $c->up_b__number == 7;
18016 ok $c->upn_2__number == 6;
18017 ok $c->upWhile_b__number == 4;
18018 ok $c->upWhile_a_b__number == 4;
18019 ok $c->upWhile_b_c__number == 2;
18020  
18021 ok $c->upUntil__number == 8;
18022 ok $c->upUntil_b_c__number == 4;
18023 }
18024  
18025  
18026 =head3 upWhileFirst($node, @context)
18027  
18028 Move up from the specified B<$node> as long as each node is a first node or return B<undef> if the specified B<$node> is not a first node.
18029  
18030 Parameter Description
18031 1 $node Start node
18032 2 @context Optional context
18033  
18034 Use the optional B<@context> parameter to test the context of the specified
18035 B<$node> as understood by method L<at|/at>. If the context is supplied and
18036 B<$node> is not in this context then this method returns B<undef> immediately.
18037  
18038  
18039  
18040 B<Example:>
18041  
18042  
18043 {my $a = Data::Edit::Xml::new(<<END);
18044 <a>
18045 <b>
18046 <c/>
18047 <d/>
18048 <e>
18049 <j/>
18050 </e>
18051 <f/>
18052 </b>
18053 <g>
18054 <h>
18055 <i>
18056 <k/>
18057 <l/>
18058 </i>
18059 </h>
18060 </g>
18061 </a>
18062 END
18063  
18064 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
18065  
18066  
18067 ok $h == $i->upWhileFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18068  
18069  
18070  
18071 ok $a == $c->upWhileFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18072  
18073  
18074  
18075 ok !$d->upWhileFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18076  
18077  
18078  
18079 =head3 upWhileLast($node, @context)
18080  
18081 Move up from the specified B<$node> as long as each node is a last node or return B<undef> if the specified B<$node> is not a last node.
18082  
18083 Parameter Description
18084 1 $node Start node
18085 2 @context Optional context
18086  
18087 Use the optional B<@context> parameter to test the context of the specified
18088 B<$node> as understood by method L<at|/at>. If the context is supplied and
18089 B<$node> is not in this context then this method returns B<undef> immediately.
18090  
18091  
18092  
18093 B<Example:>
18094  
18095  
18096 {my $a = Data::Edit::Xml::new(<<END);
18097 <a>
18098 <b>
18099 <c/>
18100 <d/>
18101 <e>
18102 <j/>
18103 </e>
18104 <f/>
18105 </b>
18106 <g>
18107 <h>
18108 <i>
18109 <k/>
18110 <l/>
18111 </i>
18112 </h>
18113 </g>
18114 </a>
18115 END
18116  
18117 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
18118  
18119  
18120 ok $j == $j->upWhileLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18121  
18122  
18123  
18124 ok $a == $l->upWhileLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18125  
18126  
18127  
18128 ok !$d->upWhileLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18129  
18130  
18131 ok $i == $k->upUntilLast;
18132  
18133  
18134 =head3 upWhileIsOnlyChild($node, @context)
18135  
18136 Move up from the specified B<$node> as long as each node is an only child or return B<undef> if the specified B<$node> is not an only child.
18137  
18138 Parameter Description
18139 1 $node Start node
18140 2 @context Optional context
18141  
18142 Use the optional B<@context> parameter to test the context of the specified
18143 B<$node> as understood by method L<at|/at>. If the context is supplied and
18144 B<$node> is not in this context then this method returns B<undef> immediately.
18145  
18146  
18147  
18148 B<Example:>
18149  
18150  
18151 {my $a = Data::Edit::Xml::new(<<END);
18152 <a>
18153 <b>
18154 <c/>
18155 <d/>
18156 <e>
18157 <j/>
18158 </e>
18159 <f/>
18160 </b>
18161 <g>
18162 <h>
18163 <i>
18164 <k/>
18165 <l/>
18166 </i>
18167 </h>
18168 </g>
18169 </a>
18170 END
18171  
18172 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
18173  
18174  
18175 ok $h == $i->upWhileIsOnlyChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18176  
18177  
18178  
18179 ok $j == $j->upWhileIsOnlyChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18180  
18181  
18182  
18183 ok !$d->upWhileIsOnlyChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18184  
18185  
18186  
18187 =head3 upUntil($node, @context)
18188  
18189 Find the first node going up from B<$node> that matches the specified B<@context>. The first such node will be the specified $node if no @context is specified or the specified $node matches the specified @context>.
18190  
18191 Parameter Description
18192 1 $node Start node
18193 2 @context Context.
18194  
18195 Use the optional B<@context> parameter to test the context of the specified
18196 B<$node> as understood by method L<at|/at>. If the context is supplied and
18197 B<$node> is not in this context then this method returns B<undef> immediately.
18198  
18199  
18200  
18201 B<Example:>
18202  
18203  
18204 if (1)
18205 {my $a = Data::Edit::Xml::new(<<END);
18206 <a><b><c><b><b><b><b><c/></b></b></b></b></c></b></a>
18207 END
18208  
18209 $a->numberTree;
18210 ok -z $a eq <<END;
18211 <a id="1">
18212 <b id="2">
18213 <c id="3">
18214 <b id="4">
18215 <b id="5">
18216 <b id="6">
18217 <b id="7">
18218 <c id="8"/>
18219 </b>
18220 </b>
18221 </b>
18222 </b>
18223 </c>
18224 </b>
18225 </a>
18226 END
18227  
18228 my $c = $a->findByNumber(8);
18229 ok -t $c eq q(c);
18230 ok $c->up_b__number == 7;
18231 ok $c->upn_2__number == 6;
18232 ok $c->upWhile_b__number == 4;
18233 ok $c->upWhile_a_b__number == 4;
18234 ok $c->upWhile_b_c__number == 2;
18235  
18236 ok $c->upUntil__number == 8;
18237 ok $c->upUntil_b_c__number == 4;
18238 }
18239  
18240  
18241 =head3 upUntilFirst($node, @context)
18242  
18243 Move up from the specified B<$node> until we reach the root or a first node.
18244  
18245 Parameter Description
18246 1 $node Start node
18247 2 @context Optional context
18248  
18249 Use the optional B<@context> parameter to test the context of the specified
18250 B<$node> as understood by method L<at|/at>. If the context is supplied and
18251 B<$node> is not in this context then this method returns B<undef> immediately.
18252  
18253  
18254  
18255 B<Example:>
18256  
18257  
18258 {my $a = Data::Edit::Xml::new(<<END);
18259 <a>
18260 <b>
18261 <c/>
18262 <d/>
18263 <e>
18264 <j/>
18265 </e>
18266 <f/>
18267 </b>
18268 <g>
18269 <h>
18270 <i>
18271 <k/>
18272 <l/>
18273 </i>
18274 </h>
18275 </g>
18276 </a>
18277 END
18278  
18279 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
18280  
18281  
18282 ok $b == $d->upUntilFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18283  
18284  
18285  
18286 =head3 upUntilLast($node, @context)
18287  
18288 Move up from the specified B<$node> until we reach the root or a last node.
18289  
18290 Parameter Description
18291 1 $node Start node
18292 2 @context Optional context
18293  
18294 Use the optional B<@context> parameter to test the context of the specified
18295 B<$node> as understood by method L<at|/at>. If the context is supplied and
18296 B<$node> is not in this context then this method returns B<undef> immediately.
18297  
18298  
18299  
18300 B<Example:>
18301  
18302  
18303 {my $a = Data::Edit::Xml::new(<<END);
18304 <a>
18305 <b>
18306 <c/>
18307 <d/>
18308 <e>
18309 <j/>
18310 </e>
18311 <f/>
18312 </b>
18313 <g>
18314 <h>
18315 <i>
18316 <k/>
18317 <l/>
18318 </i>
18319 </h>
18320 </g>
18321 </a>
18322 END
18323  
18324 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
18325  
18326  
18327 =head3 upUntilIsOnlyChild($node, @context)
18328  
18329 Move up from the specified B<$node> until we reach the root or another only child.
18330  
18331 Parameter Description
18332 1 $node Start node
18333 2 @context Optional context
18334  
18335 Use the optional B<@context> parameter to test the context of the specified
18336 B<$node> as understood by method L<at|/at>. If the context is supplied and
18337 B<$node> is not in this context then this method returns B<undef> immediately.
18338  
18339  
18340  
18341 B<Example:>
18342  
18343  
18344 {my $a = Data::Edit::Xml::new(<<END);
18345 <a>
18346 <b>
18347 <c/>
18348 <d/>
18349 <e>
18350 <j/>
18351 </e>
18352 <f/>
18353 </b>
18354 <g>
18355 <h>
18356 <i>
18357 <k/>
18358 <l/>
18359 </i>
18360 </h>
18361 </g>
18362 </a>
18363 END
18364  
18365 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
18366  
18367  
18368 ok $i == $k->upUntilIsOnlyChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18369  
18370  
18371  
18372 =head3 upThru($node, @tags)
18373  
18374 Go up the specified path from the specified B<$node> returning the node at the top or B<undef> if no such node exists.
18375  
18376 Parameter Description
18377 1 $node Start node
18378 2 @tags Tags identifying path.
18379  
18380 B<Example:>
18381  
18382  
18383 {my $a = Data::Edit::Xml::new(<<END);
18384 <a>
18385 <b>
18386 <c/>
18387 <d>
18388 <e/>
18389 <f/>
18390 </d>
18391 </b>
18392 </a>
18393 END
18394  
18395 my ($c, $e, $f, $d, $b) = $a->byList;
18396  
18397 ok -t $f eq q(f);
18398  
18399  
18400 ok -t $f->upThru eq q(f); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18401  
18402  
18403  
18404 ok -t $f->upThru(qw(d)) eq q(d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18405  
18406  
18407  
18408 ok -t eval{$f->upThru(qw(d))->last->prev} eq q(e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18409  
18410  
18411  
18412 ok ! eval{$f->upThru(qw(d b))->next}; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18413  
18414  
18415  
18416 =head2 down
18417  
18418 Methods for moving down through the L<parse|/parse> tree from a node.
18419  
18420 =head3 downWhileFirst($node, @context)
18421  
18422 Move down from the specified B<$node> as long as each lower node is a first node.
18423  
18424 Parameter Description
18425 1 $node Start node
18426 2 @context Optional context
18427  
18428 Use the optional B<@context> parameter to test the context of the specified
18429 B<$node> as understood by method L<at|/at>. If the context is supplied and
18430 B<$node> is not in this context then this method returns B<undef> immediately.
18431  
18432  
18433  
18434 B<Example:>
18435  
18436  
18437 {my $a = Data::Edit::Xml::new(<<END);
18438 <a>
18439 <b>
18440 <c/>
18441 <d/>
18442 <e>
18443 <j/>
18444 </e>
18445 <f/>
18446 </b>
18447 <g>
18448 <h>
18449 <i>
18450 <k/>
18451 <l/>
18452 </i>
18453 </h>
18454 </g>
18455 </a>
18456 END
18457  
18458 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
18459  
18460  
18461 ok $k == $g->downWhileFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18462  
18463  
18464  
18465 ok $c == $a->downWhileFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18466  
18467  
18468  
18469 ok $c == $c->downWhileFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18470  
18471  
18472  
18473 ok !$d->downWhileFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18474  
18475  
18476  
18477 B<firstLeaf> is a synonym for L<downWhileFirst|/downWhileFirst>.
18478  
18479  
18480 =head3 downWhileLast($node, @context)
18481  
18482 Move down from the specified B<$node> as long as each lower node is a last node.
18483  
18484 Parameter Description
18485 1 $node Start node
18486 2 @context Optional context
18487  
18488 Use the optional B<@context> parameter to test the context of the specified
18489 B<$node> as understood by method L<at|/at>. If the context is supplied and
18490 B<$node> is not in this context then this method returns B<undef> immediately.
18491  
18492  
18493  
18494 B<Example:>
18495  
18496  
18497 {my $a = Data::Edit::Xml::new(<<END);
18498 <a>
18499 <b>
18500 <c/>
18501 <d/>
18502 <e>
18503 <j/>
18504 </e>
18505 <f/>
18506 </b>
18507 <g>
18508 <h>
18509 <i>
18510 <k/>
18511 <l/>
18512 </i>
18513 </h>
18514 </g>
18515 </a>
18516 END
18517  
18518 my ($c, $d, $j, $e, $f, $b, $k, $l, $i, $h, $g) = $a->byList;
18519  
18520  
18521 ok $l == $a->downWhileLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18522  
18523  
18524  
18525 ok $l == $g->downWhileLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18526  
18527  
18528  
18529 ok !$d->downWhileLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18530  
18531  
18532  
18533 B<lastLeaf> is a synonym for L<downWhileLast|/downWhileLast>.
18534  
18535  
18536 =head3 downWhileHasSingleChild($node, @context)
18537  
18538 Move down from the specified B<$node> as long as it has a single child else return undef.
18539  
18540 Parameter Description
18541 1 $node Start node
18542 2 @context Optional context
18543  
18544 Use the optional B<@context> parameter to test the context of the specified
18545 B<$node> as understood by method L<at|/at>. If the context is supplied and
18546 B<$node> is not in this context then this method returns B<undef> immediately.
18547  
18548  
18549  
18550 B<Example:>
18551  
18552  
18553  
18554 ok $h == $g->downWhileHasSingleChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18555  
18556  
18557  
18558 ok $h == $h->downWhileHasSingleChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18559  
18560  
18561  
18562 ok !$i->downWhileHasSingleChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18563  
18564  
18565  
18566 =head1 Editing
18567  
18568 Edit the data in the L<parse|/parse> tree and change the structure of the L<parse|/parse> tree by L<wrapping and unwrapping|/Wrap and unwrap> nodes, by L<replacing|/Replace> nodes, by L<cutting and pasting|/Cut and Put> nodes, by L<concatenating|/Fusion> nodes, by L<splitting|/Fission> nodes, by adding new L<text|/Put as text> nodes or L<swapping|/swap> nodes.
18569  
18570 =head2 change($node, $name, @context)
18571  
18572 Change the name of the specified B<$node>, optionally confirming that the B<$node> is in a specified context and return the B<$node>.
18573  
18574 Parameter Description
18575 1 $node Node
18576 2 $name New name
18577 3 @context Optional context.
18578  
18579 Use the optional B<@context> parameter to test the context of the specified
18580 B<$node> as understood by method L<at|/at>. If the context is supplied and
18581 B<$node> is not in this context then this method returns B<undef> immediately.
18582  
18583  
18584  
18585 B<Example:>
18586  
18587  
18588 {my $a = Data::Edit::Xml::new('<a/>');
18589  
18590  
18591 $a->change(qq(b)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18592  
18593  
18594 ok -s $a eq '<b/>';
18595  
18596  
18597 B<cc> is a synonym for L<change|/change>.
18598  
18599  
18600 B<ck> is a synonym for L<change|/change>.
18601  
18602  
18603 =head2 changeKids($node, $name, @context)
18604  
18605 Change the names of all the immediate children of the specified B<$node>, if they match the optional B<@context>, to the specified B<$tag> and return the B<$node>.
18606  
18607 Parameter Description
18608 1 $node Node
18609 2 $name New name
18610 3 @context Optional context.
18611  
18612 Use the optional B<@context> parameter to test the context of the specified
18613 B<$node> as understood by method L<at|/at>. If the context is supplied and
18614 B<$node> is not in this context then this method returns B<undef> immediately.
18615  
18616  
18617  
18618 B<Example:>
18619  
18620  
18621 my $a = Data::Edit::Xml::new(<<END);
18622 <a>
18623 <b>
18624 <c/>
18625 <d/>
18626 <e/>
18627 </b>
18628 <f>
18629 <g/>
18630 <h>
18631 <i/>
18632 </h>
18633 </f>
18634 <j>
18635 <k/>
18636 <l>
18637 <m/>
18638 </l>
18639 </j>
18640 </a>
18641 END
18642  
18643  
18644 $a->changeKids(q(B), qr(\A(b|j|k|l|m)\Z), q(a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
18645  
18646  
18647 ok -p $a eq <<END;
18648 <a>
18649 <B>
18650 <c/>
18651 <d/>
18652 <e/>
18653 </B>
18654 <f>
18655 <g/>
18656 <h>
18657 <i/>
18658 </h>
18659 </f>
18660 <B>
18661 <k/>
18662 <l>
18663 <m/>
18664 </l>
18665 </B>
18666 </a>
18667 END
18668  
18669 $a->go_f__changeKids_F;
18670  
18671 ok -p $a eq <<END;
18672 <a>
18673 <B>
18674 <c/>
18675 <d/>
18676 <e/>
18677 </B>
18678 <f>
18679 <F/>
18680 <F>
18681 <i/>
18682 </F>
18683 </f>
18684 <B>
18685 <k/>
18686 <l>
18687 <m/>
18688 </l>
18689 </B>
18690 </a>
18691 END
18692  
18693  
18694 =head2 changeText($node, $rf, $rt, $flags, @context)
18695  
18696 Change the content of the specified text B<$node> that matches a regular expression B<$rf> presented as a string to a string B<$rt> in the optional B<@context> and return the specified $node else return B<undef>. For a more efficient non unitary method see L<editText>.
18697  
18698 Parameter Description
18699 1 $node Text node
18700 2 $rf From re
18701 3 $rt To string
18702 4 $flags Re flags
18703 5 @context Optional context
18704  
18705 Use the optional B<@context> parameter to test the context of the specified
18706 B<$node> as understood by method L<at|/at>. If the context is supplied and
18707 B<$node> is not in this context then this method returns B<undef> immediately.
18708  
18709  
18710  
18711 B<Example:>
18712  
18713  
18714 my $a = Data::Edit::Xml::new(<<END);
18715 <a>abcdcba</a>
18716 END
18717  
18718  
18719 =head2 changeTextToSpace($node, $re, @context)
18720  
18721 Change each instance of the content of the specified text B<$node> that matches a regular expression B<$re> to one space and return the specified $node else return B<undef>.
18722  
18723 Parameter Description
18724 1 $node Text node
18725 2 $re Regular expression
18726 3 @context Optional context
18727  
18728 Use the optional B<@context> parameter to test the context of the specified
18729 B<$node> as understood by method L<at|/at>. If the context is supplied and
18730 B<$node> is not in this context then this method returns B<undef> immediately.
18731  
18732  
18733  
18734 B<Example:>
18735  
18736  
18737 my $a = Data::Edit::Xml::new(<<END);
18738 <a>abcdcba</a>
18739 END
18740  
18741  
18742 =head2 dupPutNext($tree, @context)
18743  
18744 Duplicate the specified B<$tree> in the optional B<@context>, place the new tree next after $tree and return the root of the new tree on success else B<undef>.
18745  
18746 Parameter Description
18747 1 $tree Node
18748 2 @context Optional context.
18749  
18750 Use the optional B<@context> parameter to test the context of the specified
18751 B<$node> as understood by method L<at|/at>. If the context is supplied and
18752 B<$node> is not in this context then this method returns B<undef> immediately.
18753  
18754  
18755  
18756 B<Example:>
18757  
18758  
18759 my $a = Data::Edit::Xml::new(<<END);
18760 <a>
18761 <b>
18762 <c/>
18763 </b>
18764 <d>
18765 <e/>
18766 </d>
18767 </a>
18768 END
18769  
18770 $a->first__dupPutNext_b;
18771  
18772 ok -p $a eq <<END;
18773 <a>
18774 <b>
18775 <c/>
18776 </b>
18777 <b>
18778 <c/>
18779 </b>
18780 <d>
18781 <e/>
18782 </d>
18783 </a>
18784 END
18785  
18786 $a->last__dupPutPrev_d;
18787  
18788 ok -p $a eq <<END;
18789 <a>
18790 <b>
18791 <c/>
18792 </b>
18793 <b>
18794 <c/>
18795 </b>
18796 <d>
18797 <e/>
18798 </d>
18799 <d>
18800 <e/>
18801 </d>
18802 </a>
18803 END
18804  
18805  
18806 B<r> is a synonym for L<dupPutNext|/dupPutNext>.
18807  
18808  
18809 =head2 dupPutPrev($tree, @context)
18810  
18811 Duplicate the specified B<$tree> in the optional B<@context>, place the new tree before $tree and return the root of the new tree on success else B<undef>.
18812  
18813 Parameter Description
18814 1 $tree Node
18815 2 @context Optional context.
18816  
18817 Use the optional B<@context> parameter to test the context of the specified
18818 B<$node> as understood by method L<at|/at>. If the context is supplied and
18819 B<$node> is not in this context then this method returns B<undef> immediately.
18820  
18821  
18822  
18823 B<Example:>
18824  
18825  
18826 my $a = Data::Edit::Xml::new(<<END);
18827 <a>
18828 <b>
18829 <c/>
18830 </b>
18831 <d>
18832 <e/>
18833 </d>
18834 </a>
18835 END
18836  
18837 $a->first__dupPutNext_b;
18838  
18839 ok -p $a eq <<END;
18840 <a>
18841 <b>
18842 <c/>
18843 </b>
18844 <b>
18845 <c/>
18846 </b>
18847 <d>
18848 <e/>
18849 </d>
18850 </a>
18851 END
18852  
18853 $a->last__dupPutPrev_d;
18854  
18855 ok -p $a eq <<END;
18856 <a>
18857 <b>
18858 <c/>
18859 </b>
18860 <b>
18861 <c/>
18862 </b>
18863 <d>
18864 <e/>
18865 </d>
18866 <d>
18867 <e/>
18868 </d>
18869 </a>
18870 END
18871  
18872  
18873 =head2 dupPutNextN($node, $N, @context)
18874  
18875 Duplicate the specified B<$tree> B<$N> times in the optional B<@context>, placing each copy after $tree and return the last new node created on success else B<undef>.
18876  
18877 Parameter Description
18878 1 $node Node
18879 2 $N Number of duplications
18880 3 @context Optional context.
18881  
18882 Use the optional B<@context> parameter to test the context of the specified
18883 B<$node> as understood by method L<at|/at>. If the context is supplied and
18884 B<$node> is not in this context then this method returns B<undef> immediately.
18885  
18886  
18887  
18888 B<Example:>
18889  
18890  
18891 my $a = Data::Edit::Xml::new(<<END);
18892 <a>
18893 <b>
18894 <c/>
18895 </b>
18896 <d>
18897 <e/>
18898 <f/>
18899 <g/>
18900 </d>
18901 </a>
18902 END
18903  
18904 $a->go_b__dupPutNextN_2;
18905  
18906 ok -p $a eq <<END;
18907 <a>
18908 <b>
18909 <c/>
18910 </b>
18911 <b>
18912 <c/>
18913 </b>
18914 <b>
18915 <c/>
18916 </b>
18917 <d>
18918 <e/>
18919 <f/>
18920 <g/>
18921 </d>
18922 </a>
18923 END
18924  
18925  
18926 B<rN> is a synonym for L<dupPutNextN|/dupPutNextN>.
18927  
18928  
18929 =head2 setSelectionStart($node, @context)
18930  
18931 Set the selection to start at the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>..
18932  
18933 Parameter Description
18934 1 $node Node
18935 2 @context Optional context.
18936  
18937 Use the optional B<@context> parameter to test the context of the specified
18938 B<$node> as understood by method L<at|/at>. If the context is supplied and
18939 B<$node> is not in this context then this method returns B<undef> immediately.
18940  
18941  
18942  
18943 B<Example:>
18944  
18945  
18946 my $a = Data::Edit::Xml::new(<<END);
18947 <a>
18948 <b>
18949 <c/>
18950 </b>
18951 <b>
18952 <c/>
18953 </b>
18954 <d>
18955 <e/>
18956 <f/>
18957 <g/>
18958 </d>
18959 </a>
18960 END
18961 $a->go_b_1__setSelectionStart;
18962 $a->go_d__setSelectionEnd;
18963 $a->first__moveSelectionBefore;
18964  
18965 ok -p $a eq <<END;
18966 <a>
18967 <b>
18968 <c/>
18969 </b>
18970 <d>
18971 <e/>
18972 <f/>
18973 <g/>
18974 </d>
18975 <b>
18976 <c/>
18977 </b>
18978 </a>
18979 END
18980  
18981 $a->go_d_e__setSelectionStart;
18982 $a->go_d_g__setSelectionEnd;
18983 $a->go_b_c__moveSelectionAfter;
18984 ok -p $a eq <<END;
18985 <a>
18986 <b>
18987 <c/>
18988 <e/>
18989 <f/>
18990 <g/>
18991 </b>
18992 <d/>
18993 <b>
18994 <c/>
18995 </b>
18996 </a>
18997 END
18998  
18999 $a->go_b_e__setSelectionStart;
19000 $a->go_b_f__setSelectionEnd;
19001 $a->last__moveSelectionFirst;
19002  
19003 ok -p $a eq <<END;
19004 <a>
19005 <b>
19006 <c/>
19007 <g/>
19008 </b>
19009 <d/>
19010 <b>
19011 <e><!-- start --></e>
19012 <f><!-- end --></f>
19013 <c/>
19014 </b>
19015 </a>
19016 END
19017  
19018 $a->go_d__setSelectionStart;
19019 $a->last__setSelectionEnd;
19020 $a->go_b__moveSelectionLast;
19021  
19022 ok -p $a eq <<END;
19023 <a>
19024 <b>
19025 <c/>
19026 <g/>
19027 <d/>
19028 <b>
19029 <e><!-- start --></e>
19030 <f><!-- end --></f>
19031 <c/>
19032 </b>
19033 </b>
19034 </a>
19035 END
19036  
19037  
19038 B<ss> is a synonym for L<setSelectionStart|/setSelectionStart>.
19039  
19040  
19041 =head2 setSelectionEnd($node, @context)
19042  
19043 Set the selection to end at the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>..
19044  
19045 Parameter Description
19046 1 $node Node
19047 2 @context Optional context.
19048  
19049 Use the optional B<@context> parameter to test the context of the specified
19050 B<$node> as understood by method L<at|/at>. If the context is supplied and
19051 B<$node> is not in this context then this method returns B<undef> immediately.
19052  
19053  
19054  
19055 B<Example:>
19056  
19057  
19058 my $a = Data::Edit::Xml::new(<<END);
19059 <a>
19060 <b>
19061 <c/>
19062 </b>
19063 <b>
19064 <c/>
19065 </b>
19066 <d>
19067 <e/>
19068 <f/>
19069 <g/>
19070 </d>
19071 </a>
19072 END
19073 $a->go_b_1__setSelectionStart;
19074 $a->go_d__setSelectionEnd;
19075 $a->first__moveSelectionBefore;
19076  
19077 ok -p $a eq <<END;
19078 <a>
19079 <b>
19080 <c/>
19081 </b>
19082 <d>
19083 <e/>
19084 <f/>
19085 <g/>
19086 </d>
19087 <b>
19088 <c/>
19089 </b>
19090 </a>
19091 END
19092  
19093 $a->go_d_e__setSelectionStart;
19094 $a->go_d_g__setSelectionEnd;
19095 $a->go_b_c__moveSelectionAfter;
19096 ok -p $a eq <<END;
19097 <a>
19098 <b>
19099 <c/>
19100 <e/>
19101 <f/>
19102 <g/>
19103 </b>
19104 <d/>
19105 <b>
19106 <c/>
19107 </b>
19108 </a>
19109 END
19110  
19111 $a->go_b_e__setSelectionStart;
19112 $a->go_b_f__setSelectionEnd;
19113 $a->last__moveSelectionFirst;
19114  
19115 ok -p $a eq <<END;
19116 <a>
19117 <b>
19118 <c/>
19119 <g/>
19120 </b>
19121 <d/>
19122 <b>
19123 <e><!-- start --></e>
19124 <f><!-- end --></f>
19125 <c/>
19126 </b>
19127 </a>
19128 END
19129  
19130 $a->go_d__setSelectionStart;
19131 $a->last__setSelectionEnd;
19132 $a->go_b__moveSelectionLast;
19133  
19134 ok -p $a eq <<END;
19135 <a>
19136 <b>
19137 <c/>
19138 <g/>
19139 <d/>
19140 <b>
19141 <e><!-- start --></e>
19142 <f><!-- end --></f>
19143 <c/>
19144 </b>
19145 </b>
19146 </a>
19147 END
19148  
19149  
19150 B<se> is a synonym for L<setSelectionEnd|/setSelectionEnd>.
19151  
19152  
19153 =head2 moveSelectionFirst($node, @context)
19154  
19155 Move the current selection (if there is one) so that it is first under the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
19156  
19157 Parameter Description
19158 1 $node Node
19159 2 @context Optional context.
19160  
19161 Use the optional B<@context> parameter to test the context of the specified
19162 B<$node> as understood by method L<at|/at>. If the context is supplied and
19163 B<$node> is not in this context then this method returns B<undef> immediately.
19164  
19165  
19166  
19167 B<Example:>
19168  
19169  
19170 my $a = Data::Edit::Xml::new(<<END);
19171 <a>
19172 <b>
19173 <c/>
19174 </b>
19175 <b>
19176 <c/>
19177 </b>
19178 <d>
19179 <e/>
19180 <f/>
19181 <g/>
19182 </d>
19183 </a>
19184 END
19185 $a->go_b_1__setSelectionStart;
19186 $a->go_d__setSelectionEnd;
19187 $a->first__moveSelectionBefore;
19188  
19189 ok -p $a eq <<END;
19190 <a>
19191 <b>
19192 <c/>
19193 </b>
19194 <d>
19195 <e/>
19196 <f/>
19197 <g/>
19198 </d>
19199 <b>
19200 <c/>
19201 </b>
19202 </a>
19203 END
19204  
19205 $a->go_d_e__setSelectionStart;
19206 $a->go_d_g__setSelectionEnd;
19207 $a->go_b_c__moveSelectionAfter;
19208 ok -p $a eq <<END;
19209 <a>
19210 <b>
19211 <c/>
19212 <e/>
19213 <f/>
19214 <g/>
19215 </b>
19216 <d/>
19217 <b>
19218 <c/>
19219 </b>
19220 </a>
19221 END
19222  
19223 $a->go_b_e__setSelectionStart;
19224 $a->go_b_f__setSelectionEnd;
19225 $a->last__moveSelectionFirst;
19226  
19227 ok -p $a eq <<END;
19228 <a>
19229 <b>
19230 <c/>
19231 <g/>
19232 </b>
19233 <d/>
19234 <b>
19235 <e><!-- start --></e>
19236 <f><!-- end --></f>
19237 <c/>
19238 </b>
19239 </a>
19240 END
19241  
19242 $a->go_d__setSelectionStart;
19243 $a->last__setSelectionEnd;
19244 $a->go_b__moveSelectionLast;
19245  
19246 ok -p $a eq <<END;
19247 <a>
19248 <b>
19249 <c/>
19250 <g/>
19251 <d/>
19252 <b>
19253 <e><!-- start --></e>
19254 <f><!-- end --></f>
19255 <c/>
19256 </b>
19257 </b>
19258 </a>
19259 END
19260  
19261  
19262 B<mf> is a synonym for L<moveSelectionFirst|/moveSelectionFirst>.
19263  
19264  
19265 =head2 moveSelectionAfter($node, @context)
19266  
19267 Move the current selection (if there is one) after the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
19268  
19269 Parameter Description
19270 1 $node Node
19271 2 @context Optional context.
19272  
19273 Use the optional B<@context> parameter to test the context of the specified
19274 B<$node> as understood by method L<at|/at>. If the context is supplied and
19275 B<$node> is not in this context then this method returns B<undef> immediately.
19276  
19277  
19278  
19279 B<Example:>
19280  
19281  
19282 my $a = Data::Edit::Xml::new(<<END);
19283 <a>
19284 <b>
19285 <c/>
19286 </b>
19287 <b>
19288 <c/>
19289 </b>
19290 <d>
19291 <e/>
19292 <f/>
19293 <g/>
19294 </d>
19295 </a>
19296 END
19297 $a->go_b_1__setSelectionStart;
19298 $a->go_d__setSelectionEnd;
19299 $a->first__moveSelectionBefore;
19300  
19301 ok -p $a eq <<END;
19302 <a>
19303 <b>
19304 <c/>
19305 </b>
19306 <d>
19307 <e/>
19308 <f/>
19309 <g/>
19310 </d>
19311 <b>
19312 <c/>
19313 </b>
19314 </a>
19315 END
19316  
19317 $a->go_d_e__setSelectionStart;
19318 $a->go_d_g__setSelectionEnd;
19319 $a->go_b_c__moveSelectionAfter;
19320 ok -p $a eq <<END;
19321 <a>
19322 <b>
19323 <c/>
19324 <e/>
19325 <f/>
19326 <g/>
19327 </b>
19328 <d/>
19329 <b>
19330 <c/>
19331 </b>
19332 </a>
19333 END
19334  
19335 $a->go_b_e__setSelectionStart;
19336 $a->go_b_f__setSelectionEnd;
19337 $a->last__moveSelectionFirst;
19338  
19339 ok -p $a eq <<END;
19340 <a>
19341 <b>
19342 <c/>
19343 <g/>
19344 </b>
19345 <d/>
19346 <b>
19347 <e><!-- start --></e>
19348 <f><!-- end --></f>
19349 <c/>
19350 </b>
19351 </a>
19352 END
19353  
19354 $a->go_d__setSelectionStart;
19355 $a->last__setSelectionEnd;
19356 $a->go_b__moveSelectionLast;
19357  
19358 ok -p $a eq <<END;
19359 <a>
19360 <b>
19361 <c/>
19362 <g/>
19363 <d/>
19364 <b>
19365 <e><!-- start --></e>
19366 <f><!-- end --></f>
19367 <c/>
19368 </b>
19369 </b>
19370 </a>
19371 END
19372  
19373  
19374 B<ma> is a synonym for L<moveSelectionAfter|/moveSelectionAfter>.
19375  
19376  
19377 =head2 moveSelectionBefore($node, @context)
19378  
19379 Move the current selection (if there is one) before the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
19380  
19381 Parameter Description
19382 1 $node Node
19383 2 @context Optional context.
19384  
19385 Use the optional B<@context> parameter to test the context of the specified
19386 B<$node> as understood by method L<at|/at>. If the context is supplied and
19387 B<$node> is not in this context then this method returns B<undef> immediately.
19388  
19389  
19390  
19391 B<Example:>
19392  
19393  
19394 my $a = Data::Edit::Xml::new(<<END);
19395 <a>
19396 <b>
19397 <c/>
19398 </b>
19399 <b>
19400 <c/>
19401 </b>
19402 <d>
19403 <e/>
19404 <f/>
19405 <g/>
19406 </d>
19407 </a>
19408 END
19409 $a->go_b_1__setSelectionStart;
19410 $a->go_d__setSelectionEnd;
19411 $a->first__moveSelectionBefore;
19412  
19413 ok -p $a eq <<END;
19414 <a>
19415 <b>
19416 <c/>
19417 </b>
19418 <d>
19419 <e/>
19420 <f/>
19421 <g/>
19422 </d>
19423 <b>
19424 <c/>
19425 </b>
19426 </a>
19427 END
19428  
19429 $a->go_d_e__setSelectionStart;
19430 $a->go_d_g__setSelectionEnd;
19431 $a->go_b_c__moveSelectionAfter;
19432 ok -p $a eq <<END;
19433 <a>
19434 <b>
19435 <c/>
19436 <e/>
19437 <f/>
19438 <g/>
19439 </b>
19440 <d/>
19441 <b>
19442 <c/>
19443 </b>
19444 </a>
19445 END
19446  
19447 $a->go_b_e__setSelectionStart;
19448 $a->go_b_f__setSelectionEnd;
19449 $a->last__moveSelectionFirst;
19450  
19451 ok -p $a eq <<END;
19452 <a>
19453 <b>
19454 <c/>
19455 <g/>
19456 </b>
19457 <d/>
19458 <b>
19459 <e><!-- start --></e>
19460 <f><!-- end --></f>
19461 <c/>
19462 </b>
19463 </a>
19464 END
19465  
19466 $a->go_d__setSelectionStart;
19467 $a->last__setSelectionEnd;
19468 $a->go_b__moveSelectionLast;
19469  
19470 ok -p $a eq <<END;
19471 <a>
19472 <b>
19473 <c/>
19474 <g/>
19475 <d/>
19476 <b>
19477 <e><!-- start --></e>
19478 <f><!-- end --></f>
19479 <c/>
19480 </b>
19481 </b>
19482 </a>
19483 END
19484  
19485  
19486 B<mb> is a synonym for L<moveSelectionBefore|/moveSelectionBefore>.
19487  
19488  
19489 =head2 moveSelectionLast($node, @context)
19490  
19491 Move the current selection (if there is one) so that it is last under the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
19492  
19493 Parameter Description
19494 1 $node Node
19495 2 @context Optional context.
19496  
19497 Use the optional B<@context> parameter to test the context of the specified
19498 B<$node> as understood by method L<at|/at>. If the context is supplied and
19499 B<$node> is not in this context then this method returns B<undef> immediately.
19500  
19501  
19502  
19503 B<Example:>
19504  
19505  
19506 my $a = Data::Edit::Xml::new(<<END);
19507 <a>
19508 <b>
19509 <c/>
19510 </b>
19511 <b>
19512 <c/>
19513 </b>
19514 <d>
19515 <e/>
19516 <f/>
19517 <g/>
19518 </d>
19519 </a>
19520 END
19521 $a->go_b_1__setSelectionStart;
19522 $a->go_d__setSelectionEnd;
19523 $a->first__moveSelectionBefore;
19524  
19525 ok -p $a eq <<END;
19526 <a>
19527 <b>
19528 <c/>
19529 </b>
19530 <d>
19531 <e/>
19532 <f/>
19533 <g/>
19534 </d>
19535 <b>
19536 <c/>
19537 </b>
19538 </a>
19539 END
19540  
19541 $a->go_d_e__setSelectionStart;
19542 $a->go_d_g__setSelectionEnd;
19543 $a->go_b_c__moveSelectionAfter;
19544 ok -p $a eq <<END;
19545 <a>
19546 <b>
19547 <c/>
19548 <e/>
19549 <f/>
19550 <g/>
19551 </b>
19552 <d/>
19553 <b>
19554 <c/>
19555 </b>
19556 </a>
19557 END
19558  
19559 $a->go_b_e__setSelectionStart;
19560 $a->go_b_f__setSelectionEnd;
19561 $a->last__moveSelectionFirst;
19562  
19563 ok -p $a eq <<END;
19564 <a>
19565 <b>
19566 <c/>
19567 <g/>
19568 </b>
19569 <d/>
19570 <b>
19571 <e><!-- start --></e>
19572 <f><!-- end --></f>
19573 <c/>
19574 </b>
19575 </a>
19576 END
19577  
19578 $a->go_d__setSelectionStart;
19579 $a->last__setSelectionEnd;
19580 $a->go_b__moveSelectionLast;
19581  
19582 ok -p $a eq <<END;
19583 <a>
19584 <b>
19585 <c/>
19586 <g/>
19587 <d/>
19588 <b>
19589 <e><!-- start --></e>
19590 <f><!-- end --></f>
19591 <c/>
19592 </b>
19593 </b>
19594 </a>
19595 END
19596  
19597  
19598 B<ml> is a synonym for L<moveSelectionLast|/moveSelectionLast>.
19599  
19600  
19601 =head2 Cut and Put
19602  
19603 Cut and paste nodes in the L<parse|/parse> tree.
19604  
19605 =head3 cut($node, @context)
19606  
19607 Cut out and return the specified B<$node> so that it can be reinserted else where in the L<parse|/parse> tree.
19608  
19609 Parameter Description
19610 1 $node Node to cut out
19611 2 @context Optional context
19612  
19613 Use the optional B<@context> parameter to test the context of the specified
19614 B<$node> as understood by method L<at|/at>. If the context is supplied and
19615 B<$node> is not in this context then this method returns B<undef> immediately.
19616  
19617  
19618  
19619 B<Example:>
19620  
19621  
19622 ok -p $a eq <<END;
19623 <a id="aa">
19624 <b id="bb">
19625 <c id="cc"/>
19626 </b>
19627 </a>
19628 END
19629  
19630  
19631 my $c = $a->go(qw(b c))->cut; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
19632  
19633  
19634 ok -p $a eq <<END;
19635 <a id="aa">
19636 <b id="bb"/>
19637 </a>
19638 END
19639  
19640  
19641 B<x> is a synonym for L<cut|/cut>.
19642  
19643  
19644 =head3 cutFirst($node, @context)
19645  
19646 Cut out the first node below the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack. Return $node on success else return B<undef>. The cut out node can be reinserted using one of the putCutOut(First|Last|Next|Prev) methods.
19647  
19648 Parameter Description
19649 1 $node Node
19650 2 @context Optional context
19651  
19652 Use the optional B<@context> parameter to test the context of the specified
19653 B<$node> as understood by method L<at|/at>. If the context is supplied and
19654 B<$node> is not in this context then this method returns B<undef> immediately.
19655  
19656  
19657  
19658 B<Example:>
19659  
19660  
19661 my $a = Data::Edit::Xml::new(<<END);
19662 <a>
19663 <b/>
19664 <c/>
19665 <d/>
19666 <e/>
19667 <f/>
19668 </a>
19669 END
19670  
19671 my ($b, $c, $d, $e, $f) = $a->byList;
19672 $b->cutNext_c_a;
19673 ok -p $a eq <<END;
19674 <a>
19675 <b/>
19676 <d/>
19677 <e/>
19678 <f/>
19679 </a>
19680 END
19681  
19682 $f->cutPrev_e_a;
19683 ok -p $a eq <<END;
19684 <a>
19685 <b/>
19686 <d/>
19687 <f/>
19688 </a>
19689 END
19690 $a->cutFirst_b;
19691 ok -p $a eq <<END;
19692 <a>
19693 <d/>
19694 <f/>
19695 </a>
19696 END
19697 $a->cutLast_f;
19698 ok -p $a eq <<END;
19699 <a>
19700 <d/>
19701 </a>
19702 END
19703  
19704 ok @saveLastCutOut == 4;
19705  
19706 $a->putCutOutFirst;
19707 ok -p $a eq <<END;
19708 <a>
19709 <f/>
19710 <d/>
19711 </a>
19712 END
19713  
19714 $a->putCutOutLast;
19715 ok -p $a eq <<END;
19716 <a>
19717 <f/>
19718 <d/>
19719 <b/>
19720 </a>
19721 END
19722  
19723 $d->putCutOutPrev;
19724 ok -p $a eq <<END;
19725 <a>
19726 <f/>
19727 <e/>
19728 <d/>
19729 <b/>
19730 </a>
19731 END
19732  
19733 $d->putCutOutNext;
19734 ok -p $a eq <<END;
19735 <a>
19736 <f/>
19737 <e/>
19738 <d/>
19739 <c/>
19740 <b/>
19741 </a>
19742 END
19743  
19744  
19745  
19746 =head3 putCutOutFirst($node, @context)
19747  
19748 Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it first under the specified B<$node> if $node is in the optional B<@context>. Return $node on success else return B<undef>.
19749  
19750 Parameter Description
19751 1 $node Node
19752 2 @context Optional context
19753  
19754 Use the optional B<@context> parameter to test the context of the specified
19755 B<$node> as understood by method L<at|/at>. If the context is supplied and
19756 B<$node> is not in this context then this method returns B<undef> immediately.
19757  
19758  
19759  
19760 B<Example:>
19761  
19762  
19763 my $a = Data::Edit::Xml::new(<<END);
19764 <a>
19765 <b/>
19766 <c/>
19767 <d/>
19768 <e/>
19769 <f/>
19770 </a>
19771 END
19772  
19773 my ($b, $c, $d, $e, $f) = $a->byList;
19774 $b->cutNext_c_a;
19775 ok -p $a eq <<END;
19776 <a>
19777 <b/>
19778 <d/>
19779 <e/>
19780 <f/>
19781 </a>
19782 END
19783  
19784 $f->cutPrev_e_a;
19785 ok -p $a eq <<END;
19786 <a>
19787 <b/>
19788 <d/>
19789 <f/>
19790 </a>
19791 END
19792 $a->cutFirst_b;
19793 ok -p $a eq <<END;
19794 <a>
19795 <d/>
19796 <f/>
19797 </a>
19798 END
19799 $a->cutLast_f;
19800 ok -p $a eq <<END;
19801 <a>
19802 <d/>
19803 </a>
19804 END
19805  
19806 ok @saveLastCutOut == 4;
19807  
19808  
19809 $a->putCutOutFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
19810  
19811 ok -p $a eq <<END;
19812 <a>
19813 <f/>
19814 <d/>
19815 </a>
19816 END
19817  
19818 $a->putCutOutLast;
19819 ok -p $a eq <<END;
19820 <a>
19821 <f/>
19822 <d/>
19823 <b/>
19824 </a>
19825 END
19826  
19827 $d->putCutOutPrev;
19828 ok -p $a eq <<END;
19829 <a>
19830 <f/>
19831 <e/>
19832 <d/>
19833 <b/>
19834 </a>
19835 END
19836  
19837 $d->putCutOutNext;
19838 ok -p $a eq <<END;
19839 <a>
19840 <f/>
19841 <e/>
19842 <d/>
19843 <c/>
19844 <b/>
19845 </a>
19846 END
19847  
19848  
19849  
19850 =head3 cutLast($node, @context)
19851  
19852 Cut out the last node below the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack. Return $node on success else return B<undef>. The cut out node can be reinserted using one of the putCutOut(First|Last|Next|Prev) methods.
19853  
19854 Parameter Description
19855 1 $node Node
19856 2 @context Optional context
19857  
19858 Use the optional B<@context> parameter to test the context of the specified
19859 B<$node> as understood by method L<at|/at>. If the context is supplied and
19860 B<$node> is not in this context then this method returns B<undef> immediately.
19861  
19862  
19863  
19864 B<Example:>
19865  
19866  
19867 my $a = Data::Edit::Xml::new(<<END);
19868 <a>
19869 <b/>
19870 <c/>
19871 <d/>
19872 <e/>
19873 <f/>
19874 </a>
19875 END
19876  
19877 my ($b, $c, $d, $e, $f) = $a->byList;
19878 $b->cutNext_c_a;
19879 ok -p $a eq <<END;
19880 <a>
19881 <b/>
19882 <d/>
19883 <e/>
19884 <f/>
19885 </a>
19886 END
19887  
19888 $f->cutPrev_e_a;
19889 ok -p $a eq <<END;
19890 <a>
19891 <b/>
19892 <d/>
19893 <f/>
19894 </a>
19895 END
19896 $a->cutFirst_b;
19897 ok -p $a eq <<END;
19898 <a>
19899 <d/>
19900 <f/>
19901 </a>
19902 END
19903 $a->cutLast_f;
19904 ok -p $a eq <<END;
19905 <a>
19906 <d/>
19907 </a>
19908 END
19909  
19910 ok @saveLastCutOut == 4;
19911  
19912 $a->putCutOutFirst;
19913 ok -p $a eq <<END;
19914 <a>
19915 <f/>
19916 <d/>
19917 </a>
19918 END
19919  
19920 $a->putCutOutLast;
19921 ok -p $a eq <<END;
19922 <a>
19923 <f/>
19924 <d/>
19925 <b/>
19926 </a>
19927 END
19928  
19929 $d->putCutOutPrev;
19930 ok -p $a eq <<END;
19931 <a>
19932 <f/>
19933 <e/>
19934 <d/>
19935 <b/>
19936 </a>
19937 END
19938  
19939 $d->putCutOutNext;
19940 ok -p $a eq <<END;
19941 <a>
19942 <f/>
19943 <e/>
19944 <d/>
19945 <c/>
19946 <b/>
19947 </a>
19948 END
19949  
19950  
19951  
19952 =head3 putCutOutLast($node, @context)
19953  
19954 Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it last under the specified B<$node> if $node is in the optional B<@context>. Return $node on success else return B<undef>.
19955  
19956 Parameter Description
19957 1 $node Node
19958 2 @context Optional context
19959  
19960 Use the optional B<@context> parameter to test the context of the specified
19961 B<$node> as understood by method L<at|/at>. If the context is supplied and
19962 B<$node> is not in this context then this method returns B<undef> immediately.
19963  
19964  
19965  
19966 B<Example:>
19967  
19968  
19969 my $a = Data::Edit::Xml::new(<<END);
19970 <a>
19971 <b/>
19972 <c/>
19973 <d/>
19974 <e/>
19975 <f/>
19976 </a>
19977 END
19978  
19979 my ($b, $c, $d, $e, $f) = $a->byList;
19980 $b->cutNext_c_a;
19981 ok -p $a eq <<END;
19982 <a>
19983 <b/>
19984 <d/>
19985 <e/>
19986 <f/>
19987 </a>
19988 END
19989  
19990 $f->cutPrev_e_a;
19991 ok -p $a eq <<END;
19992 <a>
19993 <b/>
19994 <d/>
19995 <f/>
19996 </a>
19997 END
19998 $a->cutFirst_b;
19999 ok -p $a eq <<END;
20000 <a>
20001 <d/>
20002 <f/>
20003 </a>
20004 END
20005 $a->cutLast_f;
20006 ok -p $a eq <<END;
20007 <a>
20008 <d/>
20009 </a>
20010 END
20011  
20012 ok @saveLastCutOut == 4;
20013  
20014 $a->putCutOutFirst;
20015 ok -p $a eq <<END;
20016 <a>
20017 <f/>
20018 <d/>
20019 </a>
20020 END
20021  
20022  
20023 $a->putCutOutLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20024  
20025 ok -p $a eq <<END;
20026 <a>
20027 <f/>
20028 <d/>
20029 <b/>
20030 </a>
20031 END
20032  
20033 $d->putCutOutPrev;
20034 ok -p $a eq <<END;
20035 <a>
20036 <f/>
20037 <e/>
20038 <d/>
20039 <b/>
20040 </a>
20041 END
20042  
20043 $d->putCutOutNext;
20044 ok -p $a eq <<END;
20045 <a>
20046 <f/>
20047 <e/>
20048 <d/>
20049 <c/>
20050 <b/>
20051 </a>
20052 END
20053  
20054  
20055  
20056 =head3 cutNext($node, @context)
20057  
20058 Cut out the next node beyond the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack. Return the current node on success else return B<undef>. The cut out node can be reinserted using one of the putCutOut(First|Last|Next|Prev) methods.
20059  
20060 Parameter Description
20061 1 $node Node
20062 2 @context Optional context
20063  
20064 Use the optional B<@context> parameter to test the context of the specified
20065 B<$node> as understood by method L<at|/at>. If the context is supplied and
20066 B<$node> is not in this context then this method returns B<undef> immediately.
20067  
20068  
20069  
20070 B<Example:>
20071  
20072  
20073 my $a = Data::Edit::Xml::new(<<END);
20074 <a>
20075 <b/>
20076 <c/>
20077 <d/>
20078 <e/>
20079 <f/>
20080 </a>
20081 END
20082  
20083 my ($b, $c, $d, $e, $f) = $a->byList;
20084 $b->cutNext_c_a;
20085 ok -p $a eq <<END;
20086 <a>
20087 <b/>
20088 <d/>
20089 <e/>
20090 <f/>
20091 </a>
20092 END
20093  
20094 $f->cutPrev_e_a;
20095 ok -p $a eq <<END;
20096 <a>
20097 <b/>
20098 <d/>
20099 <f/>
20100 </a>
20101 END
20102 $a->cutFirst_b;
20103 ok -p $a eq <<END;
20104 <a>
20105 <d/>
20106 <f/>
20107 </a>
20108 END
20109 $a->cutLast_f;
20110 ok -p $a eq <<END;
20111 <a>
20112 <d/>
20113 </a>
20114 END
20115  
20116 ok @saveLastCutOut == 4;
20117  
20118 $a->putCutOutFirst;
20119 ok -p $a eq <<END;
20120 <a>
20121 <f/>
20122 <d/>
20123 </a>
20124 END
20125  
20126 $a->putCutOutLast;
20127 ok -p $a eq <<END;
20128 <a>
20129 <f/>
20130 <d/>
20131 <b/>
20132 </a>
20133 END
20134  
20135 $d->putCutOutPrev;
20136 ok -p $a eq <<END;
20137 <a>
20138 <f/>
20139 <e/>
20140 <d/>
20141 <b/>
20142 </a>
20143 END
20144  
20145 $d->putCutOutNext;
20146 ok -p $a eq <<END;
20147 <a>
20148 <f/>
20149 <e/>
20150 <d/>
20151 <c/>
20152 <b/>
20153 </a>
20154 END
20155  
20156  
20157  
20158 =head3 putCutOutNext($node, @context)
20159  
20160 Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it next after the specified B<$node> if $node is in the optional B<@context>. Return $node on success else return B<undef>.
20161  
20162 Parameter Description
20163 1 $node Node
20164 2 @context Optional context
20165  
20166 Use the optional B<@context> parameter to test the context of the specified
20167 B<$node> as understood by method L<at|/at>. If the context is supplied and
20168 B<$node> is not in this context then this method returns B<undef> immediately.
20169  
20170  
20171  
20172 B<Example:>
20173  
20174  
20175 my $a = Data::Edit::Xml::new(<<END);
20176 <a>
20177 <b/>
20178 <c/>
20179 <d/>
20180 <e/>
20181 <f/>
20182 </a>
20183 END
20184  
20185 my ($b, $c, $d, $e, $f) = $a->byList;
20186 $b->cutNext_c_a;
20187 ok -p $a eq <<END;
20188 <a>
20189 <b/>
20190 <d/>
20191 <e/>
20192 <f/>
20193 </a>
20194 END
20195  
20196 $f->cutPrev_e_a;
20197 ok -p $a eq <<END;
20198 <a>
20199 <b/>
20200 <d/>
20201 <f/>
20202 </a>
20203 END
20204 $a->cutFirst_b;
20205 ok -p $a eq <<END;
20206 <a>
20207 <d/>
20208 <f/>
20209 </a>
20210 END
20211 $a->cutLast_f;
20212 ok -p $a eq <<END;
20213 <a>
20214 <d/>
20215 </a>
20216 END
20217  
20218 ok @saveLastCutOut == 4;
20219  
20220 $a->putCutOutFirst;
20221 ok -p $a eq <<END;
20222 <a>
20223 <f/>
20224 <d/>
20225 </a>
20226 END
20227  
20228 $a->putCutOutLast;
20229 ok -p $a eq <<END;
20230 <a>
20231 <f/>
20232 <d/>
20233 <b/>
20234 </a>
20235 END
20236  
20237 $d->putCutOutPrev;
20238 ok -p $a eq <<END;
20239 <a>
20240 <f/>
20241 <e/>
20242 <d/>
20243 <b/>
20244 </a>
20245 END
20246  
20247  
20248 $d->putCutOutNext; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20249  
20250 ok -p $a eq <<END;
20251 <a>
20252 <f/>
20253 <e/>
20254 <d/>
20255 <c/>
20256 <b/>
20257 </a>
20258 END
20259  
20260  
20261  
20262 =head3 cutPrev($node, @context)
20263  
20264 Cut out the previous node before the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack. Return the current node on success else return B<undef>. The cut out node can be reinserted using one of the putCutOut(First|Last|Next|Prev) methods.
20265  
20266 Parameter Description
20267 1 $node Node
20268 2 @context Optional context
20269  
20270 Use the optional B<@context> parameter to test the context of the specified
20271 B<$node> as understood by method L<at|/at>. If the context is supplied and
20272 B<$node> is not in this context then this method returns B<undef> immediately.
20273  
20274  
20275  
20276 B<Example:>
20277  
20278  
20279 my $a = Data::Edit::Xml::new(<<END);
20280 <a>
20281 <b/>
20282 <c/>
20283 <d/>
20284 <e/>
20285 <f/>
20286 </a>
20287 END
20288  
20289 my ($b, $c, $d, $e, $f) = $a->byList;
20290 $b->cutNext_c_a;
20291 ok -p $a eq <<END;
20292 <a>
20293 <b/>
20294 <d/>
20295 <e/>
20296 <f/>
20297 </a>
20298 END
20299  
20300 $f->cutPrev_e_a;
20301 ok -p $a eq <<END;
20302 <a>
20303 <b/>
20304 <d/>
20305 <f/>
20306 </a>
20307 END
20308 $a->cutFirst_b;
20309 ok -p $a eq <<END;
20310 <a>
20311 <d/>
20312 <f/>
20313 </a>
20314 END
20315 $a->cutLast_f;
20316 ok -p $a eq <<END;
20317 <a>
20318 <d/>
20319 </a>
20320 END
20321  
20322 ok @saveLastCutOut == 4;
20323  
20324 $a->putCutOutFirst;
20325 ok -p $a eq <<END;
20326 <a>
20327 <f/>
20328 <d/>
20329 </a>
20330 END
20331  
20332 $a->putCutOutLast;
20333 ok -p $a eq <<END;
20334 <a>
20335 <f/>
20336 <d/>
20337 <b/>
20338 </a>
20339 END
20340  
20341 $d->putCutOutPrev;
20342 ok -p $a eq <<END;
20343 <a>
20344 <f/>
20345 <e/>
20346 <d/>
20347 <b/>
20348 </a>
20349 END
20350  
20351 $d->putCutOutNext;
20352 ok -p $a eq <<END;
20353 <a>
20354 <f/>
20355 <e/>
20356 <d/>
20357 <c/>
20358 <b/>
20359 </a>
20360 END
20361  
20362  
20363  
20364 =head3 putCutOutPrev($node, @context)
20365  
20366 Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it before the specified B<$node> if $node is in the optional B<@context>. Return $node on success else return B<undef>.
20367  
20368 Parameter Description
20369 1 $node Node
20370 2 @context Optional context
20371  
20372 Use the optional B<@context> parameter to test the context of the specified
20373 B<$node> as understood by method L<at|/at>. If the context is supplied and
20374 B<$node> is not in this context then this method returns B<undef> immediately.
20375  
20376  
20377  
20378 B<Example:>
20379  
20380  
20381 my $a = Data::Edit::Xml::new(<<END);
20382 <a>
20383 <b/>
20384 <c/>
20385 <d/>
20386 <e/>
20387 <f/>
20388 </a>
20389 END
20390  
20391 my ($b, $c, $d, $e, $f) = $a->byList;
20392 $b->cutNext_c_a;
20393 ok -p $a eq <<END;
20394 <a>
20395 <b/>
20396 <d/>
20397 <e/>
20398 <f/>
20399 </a>
20400 END
20401  
20402 $f->cutPrev_e_a;
20403 ok -p $a eq <<END;
20404 <a>
20405 <b/>
20406 <d/>
20407 <f/>
20408 </a>
20409 END
20410 $a->cutFirst_b;
20411 ok -p $a eq <<END;
20412 <a>
20413 <d/>
20414 <f/>
20415 </a>
20416 END
20417 $a->cutLast_f;
20418 ok -p $a eq <<END;
20419 <a>
20420 <d/>
20421 </a>
20422 END
20423  
20424 ok @saveLastCutOut == 4;
20425  
20426 $a->putCutOutFirst;
20427 ok -p $a eq <<END;
20428 <a>
20429 <f/>
20430 <d/>
20431 </a>
20432 END
20433  
20434 $a->putCutOutLast;
20435 ok -p $a eq <<END;
20436 <a>
20437 <f/>
20438 <d/>
20439 <b/>
20440 </a>
20441 END
20442  
20443  
20444 $d->putCutOutPrev; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20445  
20446 ok -p $a eq <<END;
20447 <a>
20448 <f/>
20449 <e/>
20450 <d/>
20451 <b/>
20452 </a>
20453 END
20454  
20455 $d->putCutOutNext;
20456 ok -p $a eq <<END;
20457 <a>
20458 <f/>
20459 <e/>
20460 <d/>
20461 <c/>
20462 <b/>
20463 </a>
20464 END
20465  
20466  
20467  
20468 =head3 cutIfEmpty($node, @context)
20469  
20470 Cut out and return the specified B<$node> so that it can be reinserted else where in the L<parse|/parse> tree if it is empty.
20471  
20472 Parameter Description
20473 1 $node Node to cut out
20474 2 @context Optional context
20475  
20476 Use the optional B<@context> parameter to test the context of the specified
20477 B<$node> as understood by method L<at|/at>. If the context is supplied and
20478 B<$node> is not in this context then this method returns B<undef> immediately.
20479  
20480  
20481  
20482 B<Example:>
20483  
20484  
20485 my $a = Data::Edit::Xml::new(<<END);
20486 <a>
20487 <b>bb</b>
20488 <c/>
20489 <d></d>
20490 <e>ee</e>
20491 </a>
20492 END
20493  
20494 my (undef, $b, $c, $d, undef, $e) = $a->byList;
20495 is_deeply [q(b)..q(e)], [map {-t $_} ($b, $c, $d, $e)];
20496  
20497  
20498 $c->cutIfEmpty; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20499  
20500 ok -p $a eq <<END;
20501 <a>
20502 <b>bb</b>
20503 <d/>
20504 <e>ee</e>
20505 </a>
20506 END
20507  
20508  
20509 $d->cutIfEmpty; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20510  
20511 ok -p $a eq <<END;
20512 <a>
20513 <b>bb</b>
20514 <e>ee</e>
20515 </a>
20516 END
20517  
20518  
20519 ok !$_->cutIfEmpty for $a, $b, $e; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20520  
20521  
20522  
20523 =head3 deleteContent($node, @context)
20524  
20525 Delete the content of the specified B<$node>.
20526  
20527 Parameter Description
20528 1 $node Node
20529 2 @context Optional context
20530  
20531 Use the optional B<@context> parameter to test the context of the specified
20532 B<$node> as understood by method L<at|/at>. If the context is supplied and
20533 B<$node> is not in this context then this method returns B<undef> immediately.
20534  
20535  
20536  
20537 B<Example:>
20538  
20539  
20540 {my $a = Data::Edit::Xml::new(<<END);
20541 <a>
20542 <b>bb<c>cc</c>BB
20543 </b>
20544 </a>
20545 END
20546  
20547  
20548 $b->deleteContent; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20549  
20550  
20551 ok -p $a eq <<END;
20552 <a>
20553 <b/>
20554 </a>
20555 END
20556  
20557  
20558 =head3 putFirst($old, $new, @context)
20559  
20560 Place a L<cut out|/cut> or L<new|/new> node at the front of the content of the specified B<$node> and return the new node. See L<putFirstCut|/putFirstCut> to cut and put first in one operation. See L<addFirst|/addFirst> to perform this operation conditionally.
20561  
20562 Parameter Description
20563 1 $old Original node
20564 2 $new New node
20565 3 @context Optional context.
20566  
20567 Use the optional B<@context> parameter to test the context of the specified
20568 B<$node> as understood by method L<at|/at>. If the context is supplied and
20569 B<$node> is not in this context then this method returns B<undef> immediately.
20570  
20571  
20572  
20573 B<Example:>
20574  
20575  
20576 ok -p $a eq <<END;
20577 <a id="aa">
20578 <b id="bb">
20579 <c id="cc"/>
20580 </b>
20581 </a>
20582 END
20583  
20584 my $c = $a->go(qw(b c))->cut;
20585  
20586  
20587 $a->putFirst($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20588  
20589  
20590 ok -p $a eq <<END;
20591 <a id="aa">
20592 <c id="cc"/>
20593 <b id="bb"/>
20594 </a>
20595 END
20596  
20597  
20598 =head3 putFirstCut($first, $second, @context)
20599  
20600 Cut out the B<$second> node, place it first under the B<$first> node and return the B<$second> node.
20601  
20602 Parameter Description
20603 1 $first First node
20604 2 $second Second node
20605 3 @context Optional context.
20606  
20607 Use the optional B<@context> parameter to test the context of the specified
20608 B<$node> as understood by method L<at|/at>. If the context is supplied and
20609 B<$node> is not in this context then this method returns B<undef> immediately.
20610  
20611  
20612  
20613 B<Example:>
20614  
20615  
20616 {my $a = Data::Edit::Xml::new(<<END);
20617 <a>
20618 <b>
20619 <c/>
20620 <d/>
20621 </b>
20622 </a>
20623 END
20624  
20625 my ($c, $d, $b) = $a->byList;
20626  
20627  
20628 $c->putFirstCut($d, qw(c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20629  
20630  
20631 ok -p $a eq <<END;
20632 <a>
20633 <b>
20634 <c>
20635 <d/>
20636 </c>
20637 </b>
20638 </a>
20639 END
20640  
20641  
20642 =head3 putLast($old, $new, @context)
20643  
20644 Place a L<cut out|/cut> or L<new|/new> node last in the content of the specified B<$node> and return the new node. See L<putLastCut|/putLastCut> to cut and put last in one operation. See L<addLast|/addLast> to perform this operation conditionally.
20645  
20646 Parameter Description
20647 1 $old Original node
20648 2 $new New node
20649 3 @context Optional context.
20650  
20651 Use the optional B<@context> parameter to test the context of the specified
20652 B<$node> as understood by method L<at|/at>. If the context is supplied and
20653 B<$node> is not in this context then this method returns B<undef> immediately.
20654  
20655  
20656  
20657 B<Example:>
20658  
20659  
20660 ok -p $a eq <<END;
20661 <a id="aa">
20662 <c id="cc"/>
20663 <b id="bb"/>
20664 </a>
20665 END
20666  
20667  
20668 $a->putLast($a->go(qw(c))->cut); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20669  
20670  
20671 ok -p $a eq <<END;
20672 <a id="aa">
20673 <b id="bb"/>
20674 <c id="cc"/>
20675 </a>
20676 END
20677  
20678  
20679 =head3 putLastCut($first, $second, @context)
20680  
20681 Cut out the B<$second> node, place it last under the B<$first> node and return the B<$second> node.
20682  
20683 Parameter Description
20684 1 $first First node
20685 2 $second Second node
20686 3 @context Optional context.
20687  
20688 Use the optional B<@context> parameter to test the context of the specified
20689 B<$node> as understood by method L<at|/at>. If the context is supplied and
20690 B<$node> is not in this context then this method returns B<undef> immediately.
20691  
20692  
20693  
20694 B<Example:>
20695  
20696  
20697 {my $a = Data::Edit::Xml::new(<<END);
20698 <a>
20699 <b>
20700 <c/>
20701 <d/>
20702 </b>
20703 </a>
20704 END
20705  
20706 my ($c, $d, $b) = $a->byList;
20707  
20708  
20709 $a->putLastCut($d, qw(a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20710  
20711  
20712 ok -p $a eq <<END;
20713 <a>
20714 <b>
20715 <c/>
20716 </b>
20717 <d/>
20718 </a>
20719 END
20720  
20721  
20722 =head3 putNext($old, $new, @context)
20723  
20724 Place a L<cut out|/cut> or L<new|/new> node just after the specified B<$node> and return the new node. See L<putNextCut|/putNextCut> to cut and put next in one operation. See L<addNext|/addNext> to perform this operation conditionally.
20725  
20726 Parameter Description
20727 1 $old Original node
20728 2 $new New node
20729 3 @context Optional context.
20730  
20731 Use the optional B<@context> parameter to test the context of the specified
20732 B<$node> as understood by method L<at|/at>. If the context is supplied and
20733 B<$node> is not in this context then this method returns B<undef> immediately.
20734  
20735  
20736  
20737 B<Example:>
20738  
20739  
20740 ok -p $a eq <<END;
20741 <a id="aa">
20742 <b id="bb"/>
20743 <c id="cc"/>
20744 </a>
20745 END
20746  
20747  
20748 $a->go(qw(c))->putNext($a->go(q(b))->cut); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20749  
20750  
20751 ok -p $a eq <<END;
20752 <a id="aa">
20753 <c id="cc"/>
20754 <b id="bb"/>
20755 </a>
20756 END
20757  
20758  
20759 =head3 putNextCut($first, $second, @context)
20760  
20761 Cut out the B<$second> node, place it after the B<$first> node and return the B<$second> node.
20762  
20763 Parameter Description
20764 1 $first First node
20765 2 $second Second node
20766 3 @context Optional context.
20767  
20768 Use the optional B<@context> parameter to test the context of the specified
20769 B<$node> as understood by method L<at|/at>. If the context is supplied and
20770 B<$node> is not in this context then this method returns B<undef> immediately.
20771  
20772  
20773  
20774 B<Example:>
20775  
20776  
20777 {my $a = Data::Edit::Xml::new(<<END);
20778 <a>
20779 <b>
20780 <c/>
20781 <d/>
20782 </b>
20783 </a>
20784 END
20785  
20786 my ($c, $d, $b) = $a->byList;
20787  
20788  
20789 $d->putNextCut($c, qw(d b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20790  
20791  
20792 ok -p $a eq <<END;
20793 <a>
20794 <b>
20795 <d/>
20796 <c/>
20797 </b>
20798 </a>
20799 END
20800  
20801  
20802 =head3 putPrev($old, $new, @context)
20803  
20804 Place a L<cut out|/cut> or L<new|/new> node just before the specified B<$node> and return the new node. See L<putPrevCut|/putPrevCut> to cut and put previous in one operation. See L<addPrev|/addPrev> to perform this operation conditionally.
20805  
20806 Parameter Description
20807 1 $old Original node
20808 2 $new New node
20809 3 @context Optional context.
20810  
20811 Use the optional B<@context> parameter to test the context of the specified
20812 B<$node> as understood by method L<at|/at>. If the context is supplied and
20813 B<$node> is not in this context then this method returns B<undef> immediately.
20814  
20815  
20816  
20817 B<Example:>
20818  
20819  
20820 ok -p $a eq <<END;
20821 <a id="aa">
20822 <c id="cc"/>
20823 <b id="bb"/>
20824 </a>
20825 END
20826  
20827  
20828 $a->go(qw(c))->putPrev($a->go(q(b))->cut); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20829  
20830  
20831 ok -p $a eq <<END;
20832 <a id="aa">
20833 <b id="bb"/>
20834 <c id="cc"/>
20835 </a>
20836 END
20837  
20838  
20839 =head3 putPrevCut($first, $second, @context)
20840  
20841 Cut out the B<$second> node, place it before the B<$first> node and return the B<$second> node.
20842  
20843 Parameter Description
20844 1 $first First node
20845 2 $second Second node
20846 3 @context Optional context.
20847  
20848 Use the optional B<@context> parameter to test the context of the specified
20849 B<$node> as understood by method L<at|/at>. If the context is supplied and
20850 B<$node> is not in this context then this method returns B<undef> immediately.
20851  
20852  
20853  
20854 B<Example:>
20855  
20856  
20857 {my $a = Data::Edit::Xml::new(<<END);
20858 <a>
20859 <b>
20860 <c/>
20861 <d/>
20862 </b>
20863 </a>
20864 END
20865  
20866 my ($c, $d, $b) = $a->byList;
20867  
20868  
20869 $c->putPrevCut($d, qw(c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20870  
20871  
20872 ok -p $a eq <<END;
20873 <a>
20874 <b>
20875 <d/>
20876 <c/>
20877 </b>
20878 </a>
20879 END
20880  
20881  
20882 =head2 Put Siblings or Contents
20883  
20884 Move a node and its siblings up and down the parse tree.
20885  
20886 =head3 putSiblingsFirst($node, @context)
20887  
20888 Move the siblings preceding the specified B<$node> in the optional B<@context> down one level and place them first under the specified B<$node> preceding any existing content. Return the specified B<$node>.
20889  
20890 Parameter Description
20891 1 $node Node whose start should be moved
20892 2 @context Optional context of node.
20893  
20894 Use the optional B<@context> parameter to test the context of the specified
20895 B<$node> as understood by method L<at|/at>. If the context is supplied and
20896 B<$node> is not in this context then this method returns B<undef> immediately.
20897  
20898  
20899  
20900 B<Example:>
20901  
20902  
20903 my $a = Data::Edit::Xml::new(<<END);
20904 <a>
20905 <b/><c/><d/><e/><f/>
20906 </a>
20907 END
20908  
20909 my ($b, $c, $d, $e, $f) = $a->byList;
20910  
20911  
20912 $d->putSiblingsFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20913  
20914 ok -p $a eq <<END;
20915 <a>
20916 <d>
20917 <b/>
20918 <c/>
20919 </d>
20920 <e/>
20921 <f/>
20922 </a>
20923 END
20924  
20925  
20926 =head3 putSiblingsLast($node, @context)
20927  
20928 Move the siblings following the specified B<$node> in the optional B<@context> down one level so that they are last under the specified B<$node> following any existing content. Return the specified B<$node>.
20929  
20930 Parameter Description
20931 1 $node Node whose start should be moved
20932 2 @context Optional context of node.
20933  
20934 Use the optional B<@context> parameter to test the context of the specified
20935 B<$node> as understood by method L<at|/at>. If the context is supplied and
20936 B<$node> is not in this context then this method returns B<undef> immediately.
20937  
20938  
20939  
20940 B<Example:>
20941  
20942  
20943 my $a = Data::Edit::Xml::new(<<END);
20944 <a>
20945 <b/><c/><d/><e/><f/>
20946 </a>
20947 END
20948  
20949 my ($b, $c, $d, $e, $f) = $a->byList;
20950  
20951  
20952 $d->putSiblingsLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20953  
20954 ok -p $a eq <<END;
20955 <a>
20956 <b/>
20957 <c/>
20958 <d>
20959 <e/>
20960 <f/>
20961 </d>
20962 </a>
20963 END
20964  
20965  
20966 =head3 putSiblingsAfterParent($node, @context)
20967  
20968 Move the specified B<$node> and its following siblings up one level and place them after the parent of the specified B<$node> if the specified B<$node> is in the optional B<@context>. Return the specified B<$node> if the move was made successfully, else confess that the specified move is not possible.
20969  
20970 Parameter Description
20971 1 $node Node whose start should be moved
20972 2 @context Optional context of node.
20973  
20974 Use the optional B<@context> parameter to test the context of the specified
20975 B<$node> as understood by method L<at|/at>. If the context is supplied and
20976 B<$node> is not in this context then this method returns B<undef> immediately.
20977  
20978  
20979  
20980 B<Example:>
20981  
20982  
20983 my $a = Data::Edit::Xml::new(<<END);
20984 <a>
20985 <b>
20986 <c/>d<e/>
20987 </b>
20988 </a>
20989 END
20990  
20991 my ($c, $d, $e, $b) = $a->byList;
20992  
20993  
20994 $d->putSiblingsAfterParent; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
20995  
20996  
20997 ok -p $a eq <<END;
20998 <a>
20999 <b>
21000 <c/>
21001 </b>
21002 d
21003 <e/>
21004 </a>
21005 END
21006  
21007  
21008 =head3 putSiblingsBeforeParent($node, @context)
21009  
21010 Move the specified B<$node> and its preceding siblings up one level and place them before the parent of the specified B<$node> if the specified B<$node> is in the optional B<@context>. Return the specified B<$node> if the move was made successfully, else confess that the specified move is not possible.
21011  
21012 Parameter Description
21013 1 $node Node whose start should be moved
21014 2 @context Optional context of node.
21015  
21016 Use the optional B<@context> parameter to test the context of the specified
21017 B<$node> as understood by method L<at|/at>. If the context is supplied and
21018 B<$node> is not in this context then this method returns B<undef> immediately.
21019  
21020  
21021  
21022 B<Example:>
21023  
21024  
21025 my $a = Data::Edit::Xml::new(<<END);
21026 <a>
21027 <b>
21028 <c/>d<e/>
21029 </b>
21030 </a>
21031 END
21032  
21033 my ($c, $d, $e, $b) = $a->byList;
21034  
21035  
21036 $d->putSiblingsBeforeParent; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21037  
21038  
21039 ok -p $a eq <<END;
21040 <a>
21041 <c/>
21042 d
21043 <b>
21044 <e/>
21045 </b>
21046 </a>
21047 END
21048  
21049  
21050 =head3 putContentAfter($node, @context)
21051  
21052 Move the content of the specified B<$node> and place it after that node if that node is in the optional B<@context>. Return the specified B<$node> or confess if the move is not possible.
21053  
21054 Parameter Description
21055 1 $node Node whose start should be moved
21056 2 @context Optional context of node.
21057  
21058 Use the optional B<@context> parameter to test the context of the specified
21059 B<$node> as understood by method L<at|/at>. If the context is supplied and
21060 B<$node> is not in this context then this method returns B<undef> immediately.
21061  
21062  
21063  
21064 B<Example:>
21065  
21066  
21067 my $a = Data::Edit::Xml::new(<<END);
21068 <a>
21069 <b>
21070 <c/><d/>
21071 </b>
21072 </a>
21073 END
21074  
21075 my ($c, $d, $b) = $a->byList;
21076  
21077  
21078 $b->putContentAfter; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21079  
21080 ok -p $a eq <<END;
21081 <a>
21082 <b/>
21083 <c/>
21084 <d/>
21085 </a>
21086 END
21087  
21088  
21089 =head3 putContentBefore($node, @context)
21090  
21091 Move the content of the specified B<$node> and place it before that node if that node is in the optional B<@context>. Return the specified B<$node> or confess if the move is not possible.
21092  
21093 Parameter Description
21094 1 $node Node whose start should be moved
21095 2 @context Optional context of node.
21096  
21097 Use the optional B<@context> parameter to test the context of the specified
21098 B<$node> as understood by method L<at|/at>. If the context is supplied and
21099 B<$node> is not in this context then this method returns B<undef> immediately.
21100  
21101  
21102  
21103 B<Example:>
21104  
21105  
21106 my $a = Data::Edit::Xml::new(<<END);
21107 <a>
21108 <b>
21109 <c/><d/>
21110 </b>
21111 </a>
21112 END
21113  
21114 my ($c, $d, $b) = $a->byList;
21115  
21116  
21117 $b->putContentBefore; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21118  
21119 ok -p $a eq <<END;
21120 <a>
21121 <c/>
21122 <d/>
21123 <b/>
21124 </a>
21125 END
21126  
21127  
21128 =head2 Move
21129  
21130 Move nodes around in the L<parse|/parse> tree by cutting and pasting them.
21131  
21132 =head3 moveFirst($node, @context)
21133  
21134 Move the specified node so that is is the first sibling under its parent. Returns the specified $node on success otherwise B<undef>.
21135  
21136 Parameter Description
21137 1 $node Node to be moved
21138 2 @context Optional context of node.
21139  
21140 Use the optional B<@context> parameter to test the context of the specified
21141 B<$node> as understood by method L<at|/at>. If the context is supplied and
21142 B<$node> is not in this context then this method returns B<undef> immediately.
21143  
21144  
21145  
21146 B<Example:>
21147  
21148  
21149 my $a = Data::Edit::Xml::new(<<END);
21150 <a><b/><c/><d/></a>
21151 END
21152  
21153 my ($b, $c, $d) = $a->byList;
21154  
21155 $d->moveFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21156  
21157 $b->moveLast;
21158  
21159 ok -p $a eq <<END;
21160 <a>
21161 <d/>
21162 <c/>
21163 <b/>
21164 </a>
21165 END
21166  
21167  
21168 =head3 moveLast($node, @context)
21169  
21170 Move the specified node so that is is the last sibling under its parent. Returns the specified $node on success otherwise B<undef>.
21171  
21172 Parameter Description
21173 1 $node Node to be moved
21174 2 @context Optional context of node.
21175  
21176 Use the optional B<@context> parameter to test the context of the specified
21177 B<$node> as understood by method L<at|/at>. If the context is supplied and
21178 B<$node> is not in this context then this method returns B<undef> immediately.
21179  
21180  
21181  
21182 B<Example:>
21183  
21184  
21185 my $a = Data::Edit::Xml::new(<<END);
21186 <a><b/><c/><d/></a>
21187 END
21188  
21189 my ($b, $c, $d) = $a->byList;
21190 $d->moveFirst;
21191  
21192 $b->moveLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21193  
21194  
21195 ok -p $a eq <<END;
21196 <a>
21197 <d/>
21198 <c/>
21199 <b/>
21200 </a>
21201 END
21202  
21203  
21204 =head3 moveStartFirst($node, @context)
21205  
21206 Move the start of a B<$node> to contain all of its preceding siblings as children. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
21207  
21208 Parameter Description
21209 1 $node Node whose start should be moved
21210 2 @context Optional context of node.
21211  
21212 Use the optional B<@context> parameter to test the context of the specified
21213 B<$node> as understood by method L<at|/at>. If the context is supplied and
21214 B<$node> is not in this context then this method returns B<undef> immediately.
21215  
21216  
21217  
21218 B<Example:>
21219  
21220  
21221 my $a = Data::Edit::Xml::new(<<END);
21222 <a>
21223 <b/>
21224 <c/>
21225 <d>
21226 <e/>
21227 </d>
21228 </a>
21229 END
21230  
21231 my ($b, $c, $e, $d) = $a->byList;
21232  
21233  
21234 $d->moveStartFirst; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21235  
21236 ok -p $a eq <<END;
21237 <a>
21238 <d>
21239 <b/>
21240 <c/>
21241 <e/>
21242 </d>
21243 </a>
21244 END
21245  
21246  
21247 =head3 moveStartAfter($node, $to, @context)
21248  
21249 Move the start end of a B<$node> to just after the specified B<$target> node assuming that the B<$target> node is either a preceding sibling or a child of B<$node>. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
21250  
21251 Parameter Description
21252 1 $node Node whose start should be moved
21253 2 $to Target node
21254 3 @context Optional context of node.
21255  
21256 Use the optional B<@context> parameter to test the context of the specified
21257 B<$node> as understood by method L<at|/at>. If the context is supplied and
21258 B<$node> is not in this context then this method returns B<undef> immediately.
21259  
21260  
21261  
21262 B<Example:>
21263  
21264  
21265 my $a = Data::Edit::Xml::new(<<END);
21266 <a>
21267 <b/>
21268 <c/>
21269 <d>
21270 <e/>
21271 </d>
21272 </a>
21273 END
21274  
21275 my ($b, $c, $e, $d) = $a->byList;
21276  
21277  
21278 $d->moveStartAfter($b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21279  
21280 ok -p $a eq <<END;
21281 <a>
21282 <b/>
21283 <d>
21284 <c/>
21285 <e/>
21286 </d>
21287 </a>
21288 END
21289  
21290  
21291 $d->moveStartAfter($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21292  
21293 ok -t $d eq q(d);
21294 ok -t $c eq q(c);
21295 ok -p $a eq <<END;
21296 <a>
21297 <b/>
21298 <c/>
21299 <d>
21300 <e/>
21301 </d>
21302 </a>
21303 END
21304  
21305  
21306 $d->moveStartAfter($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21307  
21308 ok -p $a eq <<END;
21309 <a>
21310 <b/>
21311 <c/>
21312 <e/>
21313 <d/>
21314 </a>
21315 END
21316  
21317  
21318 =head3 moveStartBefore($node, $to, @context)
21319  
21320 Move the start of a B<$node> to just before the specified B<$target> node assuming that the B<$target> node is either a preceding sibling or a child of B<$node>. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
21321  
21322 Parameter Description
21323 1 $node Node whose start should be moved
21324 2 $to Target node
21325 3 @context Optional context of node.
21326  
21327 Use the optional B<@context> parameter to test the context of the specified
21328 B<$node> as understood by method L<at|/at>. If the context is supplied and
21329 B<$node> is not in this context then this method returns B<undef> immediately.
21330  
21331  
21332  
21333 B<Example:>
21334  
21335  
21336 my $a = Data::Edit::Xml::new(<<END);
21337 <a>
21338 <b/>
21339 <c/>
21340 <d>
21341 <e/>
21342 </d>
21343 </a>
21344 END
21345  
21346 my ($b, $c, $e, $d) = $a->byList;
21347  
21348  
21349 $d->moveStartBefore($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21350  
21351 ok -p $a eq <<END;
21352 <a>
21353 <b/>
21354 <d>
21355 <c/>
21356 <e/>
21357 </d>
21358 </a>
21359 END
21360  
21361  
21362 $d->moveStartBefore($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21363  
21364 ok -t $d eq q(d);
21365 ok -t $e eq q(e);
21366 ok -p $a eq <<END;
21367 <a>
21368 <b/>
21369 <c/>
21370 <d>
21371 <e/>
21372 </d>
21373 </a>
21374 END
21375  
21376 $d->moveEndBefore($e);
21377 ok -t $d eq q(d);
21378 ok -t $e eq q(e);
21379 ok -p $a eq <<END;
21380 <a>
21381 <b/>
21382 <c/>
21383 <d/>
21384 <e/>
21385 </a>
21386 END
21387  
21388  
21389 =head3 moveEndLast($node, @context)
21390  
21391 Move the end of a B<$node> to contain all of its following siblings as children. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
21392  
21393 Parameter Description
21394 1 $node Node whose end should be moved
21395 2 @context Optional context of node.
21396  
21397 Use the optional B<@context> parameter to test the context of the specified
21398 B<$node> as understood by method L<at|/at>. If the context is supplied and
21399 B<$node> is not in this context then this method returns B<undef> immediately.
21400  
21401  
21402  
21403 B<Example:>
21404  
21405  
21406 my $a = Data::Edit::Xml::new(<<END);
21407 <a>
21408 <b>
21409 <c/>
21410 </b>
21411 <d/>
21412 <e/>
21413 </a>
21414 END
21415  
21416 my ($c, $b, $d, $e) = $a->byList;
21417  
21418  
21419 $b->moveEndLast; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21420  
21421 ok -p $a eq <<END;
21422 <a>
21423 <b>
21424 <c/>
21425 <d/>
21426 <e/>
21427 </b>
21428 </a>
21429 END
21430  
21431  
21432 =head3 moveEndAfter($node, $to, @context)
21433  
21434 Move the end of a B<$node> to just after the specified B<$target> node assuming that the B<$target> node is either a subsequent sibling or a child of B<$node>. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
21435  
21436 Parameter Description
21437 1 $node Node whose end should be moved
21438 2 $to Target node
21439 3 @context Optional context of node.
21440  
21441 Use the optional B<@context> parameter to test the context of the specified
21442 B<$node> as understood by method L<at|/at>. If the context is supplied and
21443 B<$node> is not in this context then this method returns B<undef> immediately.
21444  
21445  
21446  
21447 B<Example:>
21448  
21449  
21450 my $a = Data::Edit::Xml::new(<<END);
21451 <a>
21452 <b>
21453 <c/>
21454 </b>
21455 <d/>
21456 <e/>
21457 </a>
21458 END
21459  
21460 my ($c, $b, $d, $e) = $a->byList;
21461  
21462  
21463 $b->moveEndAfter($d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21464  
21465 ok -p $a eq <<END;
21466 <a>
21467 <b>
21468 <c/>
21469 <d/>
21470 </b>
21471 <e/>
21472 </a>
21473 END
21474  
21475  
21476 $b->moveEndAfter($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21477  
21478 ok -p $a eq <<END;
21479 <a>
21480 <b>
21481 <c/>
21482 </b>
21483 <d/>
21484 <e/>
21485 </a>
21486 END
21487  
21488  
21489 =head3 moveEndBefore($node, $to, @context)
21490  
21491 Move the end of a B<$node> to just before the specified B<$target> node assuming that the B<$target> node is either a subsequent sibling or a child of B<$node>. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
21492  
21493 Parameter Description
21494 1 $node Node whose end should be moved
21495 2 $to Target node
21496 3 @context Optional context of node.
21497  
21498 Use the optional B<@context> parameter to test the context of the specified
21499 B<$node> as understood by method L<at|/at>. If the context is supplied and
21500 B<$node> is not in this context then this method returns B<undef> immediately.
21501  
21502  
21503  
21504 B<Example:>
21505  
21506  
21507 my $a = Data::Edit::Xml::new(<<END);
21508 <a>
21509 <b>
21510 <c/>
21511 </b>
21512 <d/>
21513 <e/>
21514 </a>
21515 END
21516  
21517 my ($c, $b, $d, $e) = $a->byList;
21518  
21519  
21520 $b->moveEndBefore($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21521  
21522 ok -p $a eq <<END;
21523 <a>
21524 <b>
21525 <c/>
21526 <d/>
21527 </b>
21528 <e/>
21529 </a>
21530 END
21531  
21532  
21533 $b->moveEndBefore($d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21534  
21535 ok -p $a eq <<END;
21536 <a>
21537 <b>
21538 <c/>
21539 </b>
21540 <d/>
21541 <e/>
21542 </a>
21543 END
21544  
21545  
21546 =head3 putNextFirstCut($node, @context)
21547  
21548 Move the specified B<$node> so it is first in the next node with the optional context. Return $node on success else return B<undef> on failure.
21549  
21550 Parameter Description
21551 1 $node Node
21552 2 @context Context
21553  
21554 Use the optional B<@context> parameter to test the context of the specified
21555 B<$node> as understood by method L<at|/at>. If the context is supplied and
21556 B<$node> is not in this context then this method returns B<undef> immediately.
21557  
21558  
21559  
21560 B<Example:>
21561  
21562  
21563 my $a = Data::Edit::Xml::new(<<END);
21564 <a>
21565 <b/>
21566 <c>
21567 <d/>
21568 </c>
21569 </a>
21570 END
21571  
21572 my ($b, $d, $c) = $a->byList;
21573  
21574 ok !$b->putNextFirstCut_c_x;
21575  
21576 $b->putNextFirstCut_c_a;
21577 ok -p $a eq <<END;
21578 <a>
21579 <c>
21580 <b/>
21581 <d/>
21582 </c>
21583 </a>
21584 END
21585  
21586  
21587 =head3 putNextFirstCut2($node, @context)
21588  
21589 Move the specified B<$node> so it is first in the first node with the specified optional B<@context> of the next node. Return $node on success else return B<undef> on failure.
21590  
21591 Parameter Description
21592 1 $node Node
21593 2 @context Context
21594  
21595 Use the optional B<@context> parameter to test the context of the specified
21596 B<$node> as understood by method L<at|/at>. If the context is supplied and
21597 B<$node> is not in this context then this method returns B<undef> immediately.
21598  
21599  
21600  
21601 B<Example:>
21602  
21603  
21604 my $a = Data::Edit::Xml::new(<<END);
21605 <a>
21606 <b/>
21607 <c>
21608 <d/>
21609 </c>
21610 </a>
21611 END
21612  
21613 my ($b, $d, $c) = $a->byList;
21614  
21615 ok !$b->putNextFirstCut2_c_a;
21616  
21617 $b->putNextFirstCut2_d_c_a;
21618  
21619 ok -p $a eq <<END;
21620 <a>
21621 <c>
21622 <d>
21623 <b/>
21624 </d>
21625 </c>
21626 </a>
21627 END
21628  
21629  
21630 =head3 putPrevLastCut($node, @context)
21631  
21632 Move the specified B<$node> so it is last in the preceding node with the optional context. Return $node on success else return B<undef> on failure.
21633  
21634 Parameter Description
21635 1 $node Node
21636 2 @context Context
21637  
21638 Use the optional B<@context> parameter to test the context of the specified
21639 B<$node> as understood by method L<at|/at>. If the context is supplied and
21640 B<$node> is not in this context then this method returns B<undef> immediately.
21641  
21642  
21643  
21644 B<Example:>
21645  
21646  
21647 my $a = Data::Edit::Xml::new(<<END);
21648 <a>
21649 <b>
21650 <c/>
21651 </b>
21652 <d/>
21653 </a>
21654 END
21655  
21656 my ($c, $b, $d) = $a->byList;
21657  
21658 ok !$d->putPrevLastCut_b_c;
21659  
21660 $d->putPrevLastCut_b_a;
21661 ok -p $a eq <<END;
21662 <a>
21663 <b>
21664 <c/>
21665 <d/>
21666 </b>
21667 </a>
21668 END
21669  
21670  
21671 =head3 putPrevLastCut2($node, @context)
21672  
21673 Move the specified B<$node> so it is last in the last node with the specified optional context of the preceding node. Return the specified $node on success else return B<undef> on failure.
21674  
21675 Parameter Description
21676 1 $node Node
21677 2 @context Context
21678  
21679 Use the optional B<@context> parameter to test the context of the specified
21680 B<$node> as understood by method L<at|/at>. If the context is supplied and
21681 B<$node> is not in this context then this method returns B<undef> immediately.
21682  
21683  
21684  
21685 B<Example:>
21686  
21687  
21688 my $a = Data::Edit::Xml::new(<<END);
21689 <a>
21690 <b>
21691 <c/>
21692 </b>
21693 <d/>
21694 </a>
21695 END
21696  
21697 my ($c, $b, $d) = $a->byList;
21698  
21699 ok !$d->putPrevLastCut2_c_a;
21700  
21701 $d->putPrevLastCut2_c_b_a;
21702 ok -p $a eq <<END;
21703 <a>
21704 <b>
21705 <c>
21706 <d/>
21707 </c>
21708 </b>
21709 </a>
21710 END
21711  
21712  
21713 =head3 putUpNextCut($node, @context)
21714  
21715 Move the specified B<$node>, in the optional B<@context>, which must be last under its parent, so that it is next after its parent. Return $node on success else return B<undef> on failure.
21716  
21717 Parameter Description
21718 1 $node Node
21719 2 @context Context
21720  
21721 Use the optional B<@context> parameter to test the context of the specified
21722 B<$node> as understood by method L<at|/at>. If the context is supplied and
21723 B<$node> is not in this context then this method returns B<undef> immediately.
21724  
21725  
21726  
21727 B<Example:>
21728  
21729  
21730 my $a = Data::Edit::Xml::new(<<END);
21731 <a>
21732 <b>
21733 <c>
21734 <d/>
21735 </c>
21736 </b>
21737 </a>
21738 END
21739  
21740 $a->by(sub{$_->putUpNextCut_d_c_b_a});
21741  
21742 ok -p $a eq <<END
21743 <a>
21744 <b>
21745 <c/>
21746 <d/>
21747 </b>
21748 </a>
21749 END
21750  
21751  
21752 =head3 putUpNextCut2($node, @context)
21753  
21754 Move the specified B<$node>, in the optional B<@context>, if $node is last after its parent which must also be last under its parent, so that $node is next after its grandparent. Return $node on success else return B<undef> on failure.
21755  
21756 Parameter Description
21757 1 $node Node
21758 2 @context Context
21759  
21760 Use the optional B<@context> parameter to test the context of the specified
21761 B<$node> as understood by method L<at|/at>. If the context is supplied and
21762 B<$node> is not in this context then this method returns B<undef> immediately.
21763  
21764  
21765  
21766 B<Example:>
21767  
21768  
21769 my $a = Data::Edit::Xml::new(<<END);
21770 <a>
21771 <b>
21772 <c>
21773 <d/>
21774 </c>
21775 </b>
21776 </a>
21777 END
21778  
21779 $a->by(sub{$_->putUpNextCut2_d_c_b_a});
21780  
21781 ok -p $a eq <<END
21782 <a>
21783 <b>
21784 <c/>
21785 </b>
21786 <d/>
21787 </a>
21788 END
21789  
21790  
21791 =head3 putUpPrevCut($node, @context)
21792  
21793 Move the specified B<$node> in the optional B<@context>, if $node is first under its parent, so that it is prior to its parent. Return $node on success else return B<undef> on failure.
21794  
21795 Parameter Description
21796 1 $node Node
21797 2 @context Context
21798  
21799 Use the optional B<@context> parameter to test the context of the specified
21800 B<$node> as understood by method L<at|/at>. If the context is supplied and
21801 B<$node> is not in this context then this method returns B<undef> immediately.
21802  
21803  
21804  
21805 B<Example:>
21806  
21807  
21808 my $a = Data::Edit::Xml::new(<<END);
21809 <a>
21810 <b>
21811 <c>
21812 <d/>
21813 </c>
21814 </b>
21815 </a>
21816 END
21817  
21818 $a->by(sub{$_->putUpPrevCut_d_c_b_a});
21819  
21820 ok -p $a eq <<END
21821 <a>
21822 <b>
21823 <d/>
21824 <c/>
21825 </b>
21826 </a>
21827 END
21828  
21829  
21830 =head3 putUpPrevCut2($node, @context)
21831  
21832 Move the specified B<$node>, in the optional B<@context>, if $node is first under its parent which must also be first under its parent, so that $node is prior to its grandparent. Return the specified B<$node> on success else return B<undef> on failure.
21833  
21834 Parameter Description
21835 1 $node Node
21836 2 @context Context
21837  
21838 Use the optional B<@context> parameter to test the context of the specified
21839 B<$node> as understood by method L<at|/at>. If the context is supplied and
21840 B<$node> is not in this context then this method returns B<undef> immediately.
21841  
21842  
21843  
21844 B<Example:>
21845  
21846  
21847 my $a = Data::Edit::Xml::new(<<END);
21848 <a>
21849 <b>
21850 <c>
21851 <d/>
21852 </c>
21853 </b>
21854 </a>
21855 END
21856  
21857 $a->by(sub{$_->putUpPrevCut2_d_c_b_a});
21858  
21859 ok -p $a eq <<END
21860 <a>
21861 <d/>
21862 <b>
21863 <c/>
21864 </b>
21865 </a>
21866 END
21867  
21868  
21869 =head3 moveBlockFirst($start, $end, $parent, @context)
21870  
21871 Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> first under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
21872  
21873 Parameter Description
21874 1 $start First sibling
21875 2 $end Last sibling
21876 3 $parent Parent to move first under
21877 4 @context Optional context
21878  
21879 Use the optional B<@context> parameter to test the context of the specified
21880 B<$node> as understood by method L<at|/at>. If the context is supplied and
21881 B<$node> is not in this context then this method returns B<undef> immediately.
21882  
21883  
21884  
21885 B<Example:>
21886  
21887  
21888 my $x = Data::Edit::Xml::new(<<END);
21889 <x>
21890 <a/>
21891 <b/>
21892 <c/>
21893 <d/>
21894 <e/>
21895 <f>
21896 <g/>
21897 </f>
21898 <h/>
21899 </x>
21900 END
21901 my ($a, $b, $c, $d, $e, $g, $f, $h) = $x->byList;
21902  
21903  
21904 $c->moveBlockFirst($d, $f, qw(c x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21905  
21906  
21907 ok -p $x eq <<END;
21908 <x>
21909 <a/>
21910 <b/>
21911 <e/>
21912 <f>
21913 <c/>
21914 <d/>
21915 <g/>
21916 </f>
21917 <h/>
21918 </x>
21919 END
21920  
21921  
21922 =head3 moveBlockLast($start, $end, $parent, @context)
21923  
21924 Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> last under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
21925  
21926 Parameter Description
21927 1 $start First sibling
21928 2 $end Last sibling
21929 3 $parent Parent to move last under
21930 4 @context Optional context
21931  
21932 Use the optional B<@context> parameter to test the context of the specified
21933 B<$node> as understood by method L<at|/at>. If the context is supplied and
21934 B<$node> is not in this context then this method returns B<undef> immediately.
21935  
21936  
21937  
21938 B<Example:>
21939  
21940  
21941 my $x = Data::Edit::Xml::new(<<END);
21942 <x>
21943 <a/>
21944 <b/>
21945 <c/>
21946 <d/>
21947 <e/>
21948 <f>
21949 <g/>
21950 </f>
21951 <h/>
21952 </x>
21953 END
21954 my ($a, $b, $c, $d, $e, $g, $f, $h) = $x->byList;
21955  
21956  
21957 $c->moveBlockLast($d, $f, qw(c x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
21958  
21959  
21960 ok -p $x eq <<END;
21961 <x>
21962 <a/>
21963 <b/>
21964 <e/>
21965 <f>
21966 <g/>
21967 <c/>
21968 <d/>
21969 </f>
21970 <h/>
21971 </x>
21972 END
21973  
21974  
21975 =head3 moveBlockAfter($start, $end, $after, @context)
21976  
21977 Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> after the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
21978  
21979 Parameter Description
21980 1 $start First sibling
21981 2 $end Last sibling
21982 3 $after Node to move after
21983 4 @context Optional context
21984  
21985 Use the optional B<@context> parameter to test the context of the specified
21986 B<$node> as understood by method L<at|/at>. If the context is supplied and
21987 B<$node> is not in this context then this method returns B<undef> immediately.
21988  
21989  
21990  
21991 B<Example:>
21992  
21993  
21994 my $x = Data::Edit::Xml::new(q(<x><a/><b/><c/><d/><e/><f/><g/><h/></x>));
21995  
21996 my ($a, $b, $c, $d, $e, $f, $g, $h) = $x->byList;
21997  
21998  
21999 $c->moveBlockAfter($d, $f, qw(c x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22000  
22001  
22002 ok -C $x eq q(<a/><b/><e/><f/><c/><d/><g/><h/>);
22003  
22004  
22005 =head3 moveBlockBefore($start, $end, $before, @context)
22006  
22007 Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> before the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
22008  
22009 Parameter Description
22010 1 $start First sibling
22011 2 $end Last sibling
22012 3 $before Node to move before
22013 4 @context Optional context
22014  
22015 Use the optional B<@context> parameter to test the context of the specified
22016 B<$node> as understood by method L<at|/at>. If the context is supplied and
22017 B<$node> is not in this context then this method returns B<undef> immediately.
22018  
22019  
22020  
22021 B<Example:>
22022  
22023  
22024 my $x = Data::Edit::Xml::new(q(<x><a/><b/><c/><d/><e/><f/><g/><h/></x>));
22025  
22026 my ($a, $b, $c, $d, $e, $f, $g, $h) = $x->byList;
22027  
22028  
22029 $f->moveBlockBefore($g, $b, qw(f x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22030  
22031  
22032 ok -C $x eq q(<a/><f/><g/><b/><c/><d/><e/><h/>);
22033  
22034  
22035 =head3 moveBlockToLastFirst($start, $parent, @context)
22036  
22037 Move the siblings starting with B<$start> in the optional context first under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
22038  
22039 Parameter Description
22040 1 $start Start sibling
22041 2 $parent Parent to move first under
22042 3 @context Optional context
22043  
22044 Use the optional B<@context> parameter to test the context of the specified
22045 B<$node> as understood by method L<at|/at>. If the context is supplied and
22046 B<$node> is not in this context then this method returns B<undef> immediately.
22047  
22048  
22049  
22050 B<Example:>
22051  
22052  
22053 my $x = Data::Edit::Xml::new(<<END);
22054 <x>
22055 <a/>
22056 <b/>
22057 <c/>
22058 </x>
22059 END
22060 my ($a, $b, $c) = $x->byList;
22061  
22062  
22063 $b->moveBlockToLastFirst($a); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22064  
22065  
22066 ok -p $x eq <<END;
22067 <x>
22068 <a>
22069 <b/>
22070 <c/>
22071 </a>
22072 </x>
22073 END
22074  
22075  
22076 =head3 moveBlockToLastLast($start, $parent, @context)
22077  
22078 Move the block of siblings starting with B<$start> in the optional context last under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
22079  
22080 Parameter Description
22081 1 $start First sibling
22082 2 $parent Parent to move last under
22083 3 @context Optional context
22084  
22085 Use the optional B<@context> parameter to test the context of the specified
22086 B<$node> as understood by method L<at|/at>. If the context is supplied and
22087 B<$node> is not in this context then this method returns B<undef> immediately.
22088  
22089  
22090  
22091 B<Example:>
22092  
22093  
22094 my $x = Data::Edit::Xml::new(<<END);
22095 <x>
22096 <a>
22097 <b/>
22098 <c/>
22099 <d/>
22100 </a>
22101 <e>
22102 <f/>
22103 <g/>
22104 <h/>
22105 </e>
22106 </x>
22107 END
22108 my ($b, $c, $d, $a, $f, $g, $h, $e) = $x->byList;
22109  
22110  
22111 $c->moveBlockToLastLast($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22112  
22113  
22114 ok -p $x eq <<END;
22115 <x>
22116 <a>
22117 <b/>
22118 </a>
22119 <e>
22120 <f/>
22121 <g/>
22122 <h/>
22123 <c/>
22124 <d/>
22125 </e>
22126 </x>
22127 END
22128  
22129  
22130 =head3 moveBlockToLastAfter($start, $after, @context)
22131  
22132 Move the block of siblings starting with B<$start> in the optional context after the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
22133  
22134 Parameter Description
22135 1 $start First sibling
22136 2 $after Node to move after
22137 3 @context Optional context
22138  
22139 Use the optional B<@context> parameter to test the context of the specified
22140 B<$node> as understood by method L<at|/at>. If the context is supplied and
22141 B<$node> is not in this context then this method returns B<undef> immediately.
22142  
22143  
22144  
22145 B<Example:>
22146  
22147  
22148 my $x = Data::Edit::Xml::new(<<END);
22149 <x>
22150 <a>
22151 <b/>
22152 <c/>
22153 <d/>
22154 </a>
22155 <e/>
22156 </x>
22157 END
22158 my ($b, $c, $d, $a, $e) = $x->byList;
22159  
22160  
22161 $c->moveBlockToLastAfter($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22162  
22163  
22164 ok -p $x eq <<END;
22165 <x>
22166 <a>
22167 <b/>
22168 </a>
22169 <e/>
22170 <c/>
22171 <d/>
22172 </x>
22173 END
22174  
22175  
22176 =head3 moveBlockToLastBefore($start, $before, @context)
22177  
22178 Move the block of siblings starting with B<$start> in the optional context before the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
22179  
22180 Parameter Description
22181 1 $start First sibling
22182 2 $before Node to move before
22183 3 @context Optional context
22184  
22185 Use the optional B<@context> parameter to test the context of the specified
22186 B<$node> as understood by method L<at|/at>. If the context is supplied and
22187 B<$node> is not in this context then this method returns B<undef> immediately.
22188  
22189  
22190  
22191 B<Example:>
22192  
22193  
22194 my $x = Data::Edit::Xml::new(<<END);
22195 <x>
22196 <a/>
22197 <b>
22198 <c/>
22199 <d/>
22200 <e/>
22201 </b>
22202 </x>
22203 END
22204 my ($a, $c, $d, $e, $b) = $x->byList;
22205  
22206  
22207 $d->moveBlockToLastBefore($b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22208  
22209  
22210 ok -p $x eq <<END;
22211 <x>
22212 <a/>
22213 <d/>
22214 <e/>
22215 <b>
22216 <c/>
22217 </b>
22218 </x>
22219 END
22220  
22221  
22222 =head3 moveBlockFromFirstFirst($start, $parent, @context)
22223  
22224 Move the siblings starting with B<$start> in the optional context first under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
22225  
22226 Parameter Description
22227 1 $start Start sibling
22228 2 $parent Parent to move first under
22229 3 @context Optional context
22230  
22231 Use the optional B<@context> parameter to test the context of the specified
22232 B<$node> as understood by method L<at|/at>. If the context is supplied and
22233 B<$node> is not in this context then this method returns B<undef> immediately.
22234  
22235  
22236  
22237 B<Example:>
22238  
22239  
22240 my $x = Data::Edit::Xml::new(<<END);
22241 <x>
22242 <a>
22243 <b/>
22244 <c/>
22245 <d/>
22246 </a>
22247 <e>
22248 <f/>
22249 <g/>
22250 <h/>
22251 </e>
22252 </x>
22253 END
22254 my ($b, $c, $d, $a, $f, $g, $h, $e) = $x->byList;
22255  
22256  
22257 $g->moveBlockFromFirstFirst($a); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22258  
22259  
22260 ok -p $x eq <<END;
22261 <x>
22262 <a>
22263 <f/>
22264 <g/>
22265 <b/>
22266 <c/>
22267 <d/>
22268 </a>
22269 <e>
22270 <h/>
22271 </e>
22272 </x>
22273 END
22274  
22275  
22276 =head3 moveBlockFromFirstLast($start, $parent, @context)
22277  
22278 Move the block of siblings starting with B<$start> in the optional context last under the specified B<$parent> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
22279  
22280 Parameter Description
22281 1 $start First sibling
22282 2 $parent Parent to move last under
22283 3 @context Optional context
22284  
22285 Use the optional B<@context> parameter to test the context of the specified
22286 B<$node> as understood by method L<at|/at>. If the context is supplied and
22287 B<$node> is not in this context then this method returns B<undef> immediately.
22288  
22289  
22290  
22291 B<Example:>
22292  
22293  
22294 my $x = Data::Edit::Xml::new(<<END);
22295 <x>
22296 <a/>
22297 <b/>
22298 <c/>
22299 </x>
22300 END
22301 my ($a, $b, $c) = $x->byList;
22302  
22303  
22304 $b->moveBlockFromFirstLast($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22305  
22306  
22307 ok -p $x eq <<END;
22308 <x>
22309 <c>
22310 <a/>
22311 <b/>
22312 </c>
22313 </x>
22314 END
22315  
22316  
22317 =head3 moveBlockFromFirstAfter($start, $after, @context)
22318  
22319 Move the block of siblings starting with B<$start> in the optional context after the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
22320  
22321 Parameter Description
22322 1 $start First sibling
22323 2 $after Node to move after
22324 3 @context Optional context
22325  
22326 Use the optional B<@context> parameter to test the context of the specified
22327 B<$node> as understood by method L<at|/at>. If the context is supplied and
22328 B<$node> is not in this context then this method returns B<undef> immediately.
22329  
22330  
22331  
22332 B<Example:>
22333  
22334  
22335 my $x = Data::Edit::Xml::new(<<END);
22336 <x>
22337 <a>
22338 <b/>
22339 <c/>
22340 <d/>
22341 </a>
22342 <e/>
22343 </x>
22344 END
22345 my ($b, $c, $d, $a, $e) = $x->byList;
22346  
22347  
22348 $c->moveBlockFromFirstAfter($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22349  
22350  
22351 ok -p $x eq <<END;
22352 <x>
22353 <a>
22354 <d/>
22355 </a>
22356 <e/>
22357 <b/>
22358 <c/>
22359 </x>
22360 END
22361  
22362  
22363 =head3 moveBlockFromFirstBefore($start, $before, @context)
22364  
22365 Move the block of siblings starting with B<$start> in the optional context before the specified B<$after> node. Returns B<$node> if the move was made successfully, else confess that the specified move is impossible.
22366  
22367 Parameter Description
22368 1 $start First sibling
22369 2 $before Node to move before
22370 3 @context Optional context
22371  
22372 Use the optional B<@context> parameter to test the context of the specified
22373 B<$node> as understood by method L<at|/at>. If the context is supplied and
22374 B<$node> is not in this context then this method returns B<undef> immediately.
22375  
22376  
22377  
22378 B<Example:>
22379  
22380  
22381 my $x = Data::Edit::Xml::new(<<END);
22382 <x>
22383 <a/>
22384 <b>
22385 <c/>
22386 <d/>
22387 <e/>
22388 </b>
22389 </x>
22390 END
22391 my ($a, $c, $d, $e, $b) = $x->byList;
22392  
22393  
22394 $d->moveBlockFromFirstBefore($b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22395  
22396  
22397 ok -p $x eq <<END;
22398 <x>
22399 <a/>
22400 <c/>
22401 <d/>
22402 <b>
22403 <e/>
22404 </b>
22405 </x>
22406 END
22407  
22408  
22409 =head2 Add selectively
22410  
22411 Add new nodes unless they already exist.
22412  
22413 =head3 addFirst($node, $tag, @context)
22414  
22415 Add a new node L<first|/first> below the specified B<$node> with the specified B<$tag> unless a node with that tag already exists in that position. Return the new node if it was created unless return the pre-existing node.
22416  
22417 Parameter Description
22418 1 $node Node
22419 2 $tag Tag of new node
22420 3 @context Optional context
22421  
22422 Use the optional B<@context> parameter to test the context of the specified
22423 B<$node> as understood by method L<at|/at>. If the context is supplied and
22424 B<$node> is not in this context then this method returns B<undef> immediately.
22425  
22426  
22427  
22428 B<Example:>
22429  
22430  
22431 {my $a = Data::Edit::Xml::newTree(q(a));
22432  
22433 $a->addFirst_b for 1..2;
22434  
22435 ok -p $a eq <<END;
22436 <a>
22437 <b/>
22438 </a>
22439 END
22440  
22441  
22442 =head3 addNext($node, $tag, @context)
22443  
22444 Add a new node L<next|/next> the specified B<$node> and return the new node unless a node with that tag already exists in which case return the existing B<$node>.
22445  
22446 Parameter Description
22447 1 $node Node
22448 2 $tag Tag of new node
22449 3 @context Optional context
22450  
22451 Use the optional B<@context> parameter to test the context of the specified
22452 B<$node> as understood by method L<at|/at>. If the context is supplied and
22453 B<$node> is not in this context then this method returns B<undef> immediately.
22454  
22455  
22456  
22457 B<Example:>
22458  
22459  
22460 ok -p $a eq <<END;
22461 <a>
22462 <b/>
22463 <e/>
22464 </a>
22465 END
22466  
22467 $a->addFirst_b__addNext_c;
22468  
22469 ok -p $a eq <<END;
22470 <a>
22471 <b/>
22472 <c/>
22473 <e/>
22474 </a>
22475 END
22476  
22477  
22478 =head3 addPrev($node, $tag, @context)
22479  
22480 Add a new node L<before|/prev> the specified B<$node> with the specified B<$tag> unless a node with that tag already exists in that position. Return the new node if it was created unless return the pre-existing node.
22481  
22482 Parameter Description
22483 1 $node Node
22484 2 $tag Tag of new node
22485 3 @context Optional context
22486  
22487 Use the optional B<@context> parameter to test the context of the specified
22488 B<$node> as understood by method L<at|/at>. If the context is supplied and
22489 B<$node> is not in this context then this method returns B<undef> immediately.
22490  
22491  
22492  
22493 B<Example:>
22494  
22495  
22496 ok -p $a eq <<END;
22497 <a>
22498 <b/>
22499 <c/>
22500 <e/>
22501 </a>
22502 END
22503  
22504 $a->addLast_e__addPrev_d;
22505  
22506 ok -p $a eq <<END;
22507 <a>
22508 <b/>
22509 <c/>
22510 <d/>
22511 <e/>
22512 </a>
22513 END
22514  
22515  
22516 =head3 addLast($node, $tag, @context)
22517  
22518 Add a new node L<last|/last> below the specified B<$node> with the specified B<$tag> unless a node with that tag already exists in that position. Return the new node if it was created unless return the pre-existing node..
22519  
22520 Parameter Description
22521 1 $node Node
22522 2 $tag Tag of new node
22523 3 @context Optional context
22524  
22525 Use the optional B<@context> parameter to test the context of the specified
22526 B<$node> as understood by method L<at|/at>. If the context is supplied and
22527 B<$node> is not in this context then this method returns B<undef> immediately.
22528  
22529  
22530  
22531 B<Example:>
22532  
22533  
22534 ok -p $a eq <<END;
22535 <a>
22536 <b/>
22537 </a>
22538 END
22539  
22540  
22541 $a->addLast(qw(e)) for 1..2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22542  
22543  
22544 ok -p $a eq <<END;
22545 <a>
22546 <b/>
22547 <e/>
22548 </a>
22549 END
22550  
22551  
22552 =head3 addWrapWith($node, $tag, @context)
22553  
22554 L<Wrap|/wrap> the specified B<$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 B<$node>.
22555  
22556 Parameter Description
22557 1 $node Node
22558 2 $tag Tag of new node
22559 3 @context Optional context
22560  
22561 Use the optional B<@context> parameter to test the context of the specified
22562 B<$node> as understood by method L<at|/at>. If the context is supplied and
22563 B<$node> is not in this context then this method returns B<undef> immediately.
22564  
22565  
22566  
22567 B<Example:>
22568  
22569  
22570 {my $a = Data::Edit::Xml::new(q(<a><b/></a>));
22571  
22572 my $b = $a->first;
22573  
22574 $b->addWrapWith_c for 1..2;
22575  
22576 ok -p $a eq <<END;
22577 <a>
22578 <c>
22579 <b/>
22580 </c>
22581 </a>
22582 END
22583  
22584  
22585 =head3 addSingleChild($node, $tag, @context)
22586  
22587 Wrap the content of a specified B<$node> in a new node with the specified B<$tag> unless the content is already wrapped in a single child with the specified B<$tag>.
22588  
22589 Parameter Description
22590 1 $node Node
22591 2 $tag Tag of new node
22592 3 @context Optional context
22593  
22594 Use the optional B<@context> parameter to test the context of the specified
22595 B<$node> as understood by method L<at|/at>. If the context is supplied and
22596 B<$node> is not in this context then this method returns B<undef> immediately.
22597  
22598  
22599  
22600 B<Example:>
22601  
22602  
22603 ok -p $a eq <<END;
22604 <a>
22605 <c>
22606 <b/>
22607 </c>
22608 </a>
22609 END
22610  
22611 $a->addSingleChild_d for 1..2;
22612  
22613 ok -p $a eq <<END;
22614 <a>
22615 <d>
22616 <c>
22617 <b/>
22618 </c>
22619 </d>
22620 </a>
22621 END
22622  
22623  
22624 =head2 Add text selectively
22625  
22626 Add new text unless it already exists.
22627  
22628 =head3 addFirstAsText($node, $text, @context)
22629  
22630 Add a new text node first below the specified B<$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 B<$node>.
22631  
22632 Parameter Description
22633 1 $node Node
22634 2 $text Text
22635 3 @context Optional context
22636  
22637 Use the optional B<@context> parameter to test the context of the specified
22638 B<$node> as understood by method L<at|/at>. If the context is supplied and
22639 B<$node> is not in this context then this method returns B<undef> immediately.
22640  
22641  
22642  
22643 B<Example:>
22644  
22645  
22646 {my $a = Data::Edit::Xml::newTree(q(a));
22647  
22648  
22649 $a->addFirstAsText(q(aaaa)) for 1..2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22650  
22651  
22652 ok -s $a eq q(<a>aaaa</a>);
22653  
22654  
22655 =head3 addNextAsText($node, $text, @context)
22656  
22657 Add a new text node after the specified B<$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 B<$node>.
22658  
22659 Parameter Description
22660 1 $node Node
22661 2 $text Text
22662 3 @context Optional context
22663  
22664 Use the optional B<@context> parameter to test the context of the specified
22665 B<$node> as understood by method L<at|/at>. If the context is supplied and
22666 B<$node> is not in this context then this method returns B<undef> immediately.
22667  
22668  
22669  
22670 B<Example:>
22671  
22672  
22673 {my $a = Data::Edit::Xml::new(q(<a><b/></a>));
22674  
22675  
22676 $a->go(q(b))->addNextAsText(q(bbbb)) for 1..2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22677  
22678  
22679 ok -p $a eq <<END;
22680 <a>
22681 <b/>
22682 bbbb
22683 </a>
22684 END
22685  
22686  
22687 =head3 addPrevAsText($node, $text, @context)
22688  
22689 Add a new text node before the specified B<$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 B<$node>.
22690  
22691 Parameter Description
22692 1 $node Node
22693 2 $text Text
22694 3 @context Optional context
22695  
22696 Use the optional B<@context> parameter to test the context of the specified
22697 B<$node> as understood by method L<at|/at>. If the context is supplied and
22698 B<$node> is not in this context then this method returns B<undef> immediately.
22699  
22700  
22701  
22702 B<Example:>
22703  
22704  
22705 ok -p $a eq <<END;
22706 <a>
22707 <b/>
22708 bbbb
22709 </a>
22710 END
22711  
22712  
22713 $a->go(q(b))->addPrevAsText(q(aaaa)) for 1..2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22714  
22715  
22716 ok -p $a eq <<END;
22717 <a>aaaa
22718 <b/>
22719 bbbb
22720 </a>
22721 END
22722  
22723  
22724 =head3 addLastAsText($node, $text, @context)
22725  
22726 Add a new text node last below the specified B<$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 B<$node>.
22727  
22728 Parameter Description
22729 1 $node Node
22730 2 $text Text
22731 3 @context Optional context
22732  
22733 Use the optional B<@context> parameter to test the context of the specified
22734 B<$node> as understood by method L<at|/at>. If the context is supplied and
22735 B<$node> is not in this context then this method returns B<undef> immediately.
22736  
22737  
22738  
22739 B<Example:>
22740  
22741  
22742 ok -s $a eq q(<a>aaaa</a>);
22743  
22744  
22745 $a->addLastAsText(q(dddd)) for 1..2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22746  
22747  
22748 ok -s $a eq q(<a>aaaadddd</a>);
22749  
22750  
22751 =head3 joinWithText($node, $text, $over, @context)
22752  
22753 Insert some text between the children of the current B<$node> as specified by B<$text> between all the children of the current $node as long as they all have a tag of B<$over>. Return the current $node on success or B<undef> on failure.
22754  
22755 Parameter Description
22756 1 $node Node
22757 2 $text Text
22758 3 $over Child tag
22759 4 @context Optional context
22760  
22761 Use the optional B<@context> parameter to test the context of the specified
22762 B<$node> as understood by method L<at|/at>. If the context is supplied and
22763 B<$node> is not in this context then this method returns B<undef> immediately.
22764  
22765  
22766  
22767 B<Example:>
22768  
22769  
22770 my $a = Data::Edit::Xml::new(<<END);
22771 <a>
22772 <b/>
22773 <b/>
22774 <b/>
22775 </a>
22776 END
22777  
22778 $a->joinWithText_CC_b_a;
22779  
22780 ok -p $a eq <<END;
22781 <a>
22782 <b/>
22783 CC
22784 <b/>
22785 CC
22786 <b/>
22787 </a>
22788 END
22789  
22790  
22791 =head2 Fission
22792  
22793 Split the parent L<before|/splitBefore> or L<after|/splitAfter> the specified sibling.
22794  
22795 =head3 splitBefore($node, @context)
22796  
22797 Split the parent node into two identical nodes except all the siblings before the specified B<$node> are retained by the existing parent while any following siblings become siblings of the new parent node which is placed after the existing parent. The new parent is returned.
22798  
22799 Parameter Description
22800 1 $node Node to split before
22801 2 @context Optional context
22802  
22803 Use the optional B<@context> parameter to test the context of the specified
22804 B<$node> as understood by method L<at|/at>. If the context is supplied and
22805 B<$node> is not in this context then this method returns B<undef> immediately.
22806  
22807  
22808  
22809 B<Example:>
22810  
22811  
22812 my $a = Data::Edit::Xml::new(<<END);
22813 <a>
22814 <b>
22815 <c/>
22816 <d/>
22817 <e/>
22818 </b>
22819 </a>
22820 END
22821  
22822 $a->go_b_d__splitBefore;
22823  
22824 ok -p $a eq <<END;
22825 <a>
22826 <b>
22827 <c/>
22828 </b>
22829 <b>
22830 <d/>
22831 <e/>
22832 </b>
22833 </a>
22834 END
22835  
22836  
22837 =head3 splitAfter($node, @context)
22838  
22839 Split the parent node into two identical nodes except all the siblings after the specified B<$node> are retained by the existing parent while any preceding siblings become siblings of the new parent node which is placed before the existing parent. The new parent is returned
22840  
22841 Parameter Description
22842 1 $node Node to split before
22843 2 @context Optional context
22844  
22845 Use the optional B<@context> parameter to test the context of the specified
22846 B<$node> as understood by method L<at|/at>. If the context is supplied and
22847 B<$node> is not in this context then this method returns B<undef> immediately.
22848  
22849  
22850  
22851 B<Example:>
22852  
22853  
22854 my $a = Data::Edit::Xml::new(<<END);
22855 <a>
22856 <b>
22857 <c/>
22858 <d/>
22859 <e/>
22860 </b>
22861 </a>
22862 END
22863  
22864 $a->go_b_d__splitAfter;
22865  
22866 ok -p $a eq <<END;
22867 <a>
22868 <b>
22869 <c/>
22870 <d/>
22871 </b>
22872 <b>
22873 <e/>
22874 </b>
22875 </a>
22876 END
22877  
22878  
22879 =head2 Fusion
22880  
22881 Join consecutive nodes
22882  
22883 =head3 concatenate($target, $source, @context)
22884  
22885 Concatenate two successive nodes and return the B<$target> node.
22886  
22887 Parameter Description
22888 1 $target Target node to replace
22889 2 $source Node to concatenate
22890 3 @context Optional context of $target
22891  
22892 Use the optional B<@context> parameter to test the context of the specified
22893 B<$node> as understood by method L<at|/at>. If the context is supplied and
22894 B<$node> is not in this context then this method returns B<undef> immediately.
22895  
22896  
22897  
22898 B<Example:>
22899  
22900  
22901 {my $s = <<END;
22902 <a>
22903 <b>
22904 <A/>
22905 <B/>
22906 </b>
22907 <c>
22908 <C/>
22909 <D/>
22910 </c>
22911 </a>
22912 END
22913  
22914 my $a = Data::Edit::Xml::new($s);
22915  
22916  
22917 $a->go(q(b))->concatenate($a->go(q(c))); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22918  
22919  
22920 my $t = <<END;
22921 <a>
22922 <b>
22923 <A/>
22924 <B/>
22925 <C/>
22926 <D/>
22927 </b>
22928 </a>
22929 END
22930  
22931 ok $t eq -p $a;
22932  
22933  
22934 =head3 concatenateSiblings($node, @context)
22935  
22936 Concatenate the nodes that precede and follow the specified B<$node> in the optioonal B<@context> as long as they have the same tag as the specified B<$node> and return the specified B<$node>.
22937  
22938 Parameter Description
22939 1 $node Concatenate around this node
22940 2 @context Optional context.
22941  
22942 Use the optional B<@context> parameter to test the context of the specified
22943 B<$node> as understood by method L<at|/at>. If the context is supplied and
22944 B<$node> is not in this context then this method returns B<undef> immediately.
22945  
22946  
22947  
22948 B<Example:>
22949  
22950  
22951 ok -p $a eq <<END;
22952 <a>
22953 <b>
22954 <c id="1"/>
22955 </b>
22956 <b>
22957 <c id="2"/>
22958 </b>
22959 <b>
22960 <c id="3"/>
22961 </b>
22962 <b>
22963 <c id="4"/>
22964 </b>
22965 </a>
22966 END
22967  
22968  
22969 $a->go(qw(b 3))->concatenateSiblings; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
22970  
22971  
22972 ok -p $a eq <<END;
22973 <a>
22974 <b>
22975 <c id="1"/>
22976 <c id="2"/>
22977 <c id="3"/>
22978 <c id="4"/>
22979 </b>
22980 </a>
22981 END
22982  
22983  
22984 =head3 mergeDuplicateChildWithParent($parent, @context)
22985  
22986 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.
22987  
22988 Parameter Description
22989 1 $parent Parent this node
22990 2 @context Optional context.
22991  
22992 Use the optional B<@context> parameter to test the context of the specified
22993 B<$node> as understood by method L<at|/at>. If the context is supplied and
22994 B<$node> is not in this context then this method returns B<undef> immediately.
22995  
22996  
22997  
22998 B<Example:>
22999  
23000  
23001 {my $a = Data::Edit::Xml::new(<<END);
23002 <a>
23003 <b id="b" b="bb">
23004 <b id="c" c="cc"/>
23005 </b>
23006 </a>
23007 END
23008  
23009 my ($c, $b) = $a->byList;
23010  
23011 is_deeply [$b->id, $c->id], [qw(b c)];
23012  
23013 ok $c == $b->hasSingleChild;
23014  
23015  
23016 $b->mergeDuplicateChildWithParent; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23017  
23018  
23019 ok -p $a eq <<END;
23020 <a>
23021 <b b="bb" c="cc" id="b"/>
23022 </a>
23023 END
23024  
23025 ok $b == $a->hasSingleChild;
23026  
23027  
23028 =head2 Put as text
23029  
23030 Add text to the L<parse|/parse> tree.
23031  
23032 =head3 putFirstAsText($node, $text, @context)
23033  
23034 Add a new text node first under a parent and return the new text node.
23035  
23036 Parameter Description
23037 1 $node The parent node
23038 2 $text The string to be added which might contain unparsed Xml as well as text
23039 3 @context Optional context.
23040  
23041 Use the optional B<@context> parameter to test the context of the specified
23042 B<$node> as understood by method L<at|/at>. If the context is supplied and
23043 B<$node> is not in this context then this method returns B<undef> immediately.
23044  
23045  
23046  
23047 B<Example:>
23048  
23049  
23050 ok -p $x eq <<END;
23051 <a id="aa">
23052 <b id="bb">
23053 <c id="cc"/>
23054 </b>
23055 </a>
23056 END
23057  
23058  
23059 $x->go(qw(b c))->putFirstAsText("<d id=\"dd\">DDDD</d>"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23060  
23061  
23062 ok -p $x eq <<END;
23063 <a id="aa">
23064 <b id="bb">
23065 <c id="cc"><d id="dd">DDDD</d></c>
23066 </b>
23067 </a>
23068 END
23069  
23070  
23071 =head3 putTextFirst($node, @text)
23072  
23073 Given a B<$node> place some B<@text> first under the $node and return the new text node else return B<undef> if this is not possible.
23074  
23075 Parameter Description
23076 1 $node The parent node
23077 2 @text The text to be added
23078  
23079 B<Example:>
23080  
23081  
23082 my $a = Data::Edit::Xml::new(q(<a><b><c/></b></a>));
23083  
23084 my $b = $a->first;
23085  
23086 $b->putTextPrev(qw(Before the B node));
23087 $b->putTextNext(qw(After the B node));
23088  
23089 $b->putTextFirst(qw(First under the B node)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23090  
23091 $b->putTextLast(qw(Last under the B node));
23092  
23093 ok -p $a eq <<END;
23094 <a>Before the B node
23095 <b>First under the B node
23096 <c/>
23097 Last under the B node
23098 </b>
23099 After the B node
23100 </a>
23101 END
23102  
23103  
23104 =head3 putLastAsText($node, $text, @context)
23105  
23106 Add a new text node last under a parent and return the new text node.
23107  
23108 Parameter Description
23109 1 $node The parent node
23110 2 $text The string to be added which might contain unparsed Xml as well as text
23111 3 @context Optional context.
23112  
23113 Use the optional B<@context> parameter to test the context of the specified
23114 B<$node> as understood by method L<at|/at>. If the context is supplied and
23115 B<$node> is not in this context then this method returns B<undef> immediately.
23116  
23117  
23118  
23119 B<Example:>
23120  
23121  
23122 ok -p $x eq <<END;
23123 <a id="aa">
23124 <b id="bb">
23125 <c id="cc"><d id="dd">DDDD</d></c>
23126 </b>
23127 </a>
23128 END
23129  
23130  
23131 $x->go(qw(b c))->putLastAsText("<e id=\"ee\">EEEE</e>"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23132  
23133  
23134 ok -p $x eq <<END;
23135 <a id="aa">
23136 <b id="bb">
23137 <c id="cc"><d id="dd">DDDD</d><e id="ee">EEEE</e></c>
23138 </b>
23139 </a>
23140 END
23141  
23142  
23143 =head3 putTextLast($node, @text)
23144  
23145 Given a B<$node> place some B<@text> last under the $node and return the new text node else return B<undef> if this is not possible.
23146  
23147 Parameter Description
23148 1 $node The parent node
23149 2 @text The text to be added
23150  
23151 B<Example:>
23152  
23153  
23154 my $a = Data::Edit::Xml::new(q(<a><b><c/></b></a>));
23155  
23156 my $b = $a->first;
23157  
23158 $b->putTextPrev(qw(Before the B node));
23159 $b->putTextNext(qw(After the B node));
23160 $b->putTextFirst(qw(First under the B node));
23161  
23162 $b->putTextLast(qw(Last under the B node)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23163  
23164  
23165 ok -p $a eq <<END;
23166 <a>Before the B node
23167 <b>First under the B node
23168 <c/>
23169 Last under the B node
23170 </b>
23171 After the B node
23172 </a>
23173 END
23174  
23175  
23176 =head3 putNextAsText($node, $text, @context)
23177  
23178 Add a new text node following the specified B<$node> and return the new text node.
23179  
23180 Parameter Description
23181 1 $node The parent node
23182 2 $text The string to be added which might contain unparsed Xml as well as text
23183 3 @context Optional context.
23184  
23185 Use the optional B<@context> parameter to test the context of the specified
23186 B<$node> as understood by method L<at|/at>. If the context is supplied and
23187 B<$node> is not in this context then this method returns B<undef> immediately.
23188  
23189  
23190  
23191 B<Example:>
23192  
23193  
23194 ok -p $x eq <<END;
23195 <a id="aa">
23196 <b id="bb">
23197 <c id="cc"><d id="dd">DDDD</d><e id="ee">EEEE</e></c>
23198 </b>
23199 </a>
23200 END
23201  
23202  
23203 $x->go(qw(b c))->putNextAsText("<n id=\"nn\">NNNN</n>"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23204  
23205  
23206 ok -p $x eq <<END;
23207 <a id="aa">
23208 <b id="bb">
23209 <c id="cc"><d id="dd">DDDD</d><e id="ee">EEEE</e></c>
23210 <n id="nn">NNNN</n>
23211 </b>
23212 </a>
23213 END
23214  
23215  
23216 =head3 putTextNext($node, @text)
23217  
23218 Given a B<$node> place some B<@text> next to the $node and return the new text node else return B<undef> if this is not possible.
23219  
23220 Parameter Description
23221 1 $node The parent node
23222 2 @text The text to be added
23223  
23224 B<Example:>
23225  
23226  
23227 my $a = Data::Edit::Xml::new(q(<a><b><c/></b></a>));
23228  
23229 my $b = $a->first;
23230  
23231 $b->putTextPrev(qw(Before the B node));
23232  
23233 $b->putTextNext(qw(After the B node)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23234  
23235 $b->putTextFirst(qw(First under the B node));
23236 $b->putTextLast(qw(Last under the B node));
23237  
23238 ok -p $a eq <<END;
23239 <a>Before the B node
23240 <b>First under the B node
23241 <c/>
23242 Last under the B node
23243 </b>
23244 After the B node
23245 </a>
23246 END
23247  
23248  
23249 =head3 putPrevAsText($node, $text, @context)
23250  
23251 Add a new text node following the specified B<$node> and return the new text node
23252  
23253 Parameter Description
23254 1 $node The parent node
23255 2 $text The string to be added which might contain unparsed Xml as well as text
23256 3 @context Optional context.
23257  
23258 Use the optional B<@context> parameter to test the context of the specified
23259 B<$node> as understood by method L<at|/at>. If the context is supplied and
23260 B<$node> is not in this context then this method returns B<undef> immediately.
23261  
23262  
23263  
23264 B<Example:>
23265  
23266  
23267 ok -p $x eq <<END;
23268 <a id="aa">
23269 <b id="bb">
23270 <c id="cc"><d id="dd">DDDD</d><e id="ee">EEEE</e></c>
23271 <n id="nn">NNNN</n>
23272 </b>
23273 </a>
23274 END
23275  
23276  
23277 $x->go(qw(b c))->putPrevAsText("<p id=\"pp\">PPPP</p>"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23278  
23279  
23280 ok -p $x eq <<END;
23281 <a id="aa">
23282 <b id="bb"><p id="pp">PPPP</p>
23283 <c id="cc"><d id="dd">DDDD</d><e id="ee">EEEE</e></c>
23284 <n id="nn">NNNN</n>
23285 </b>
23286 </a>
23287 END
23288  
23289  
23290 =head3 putTextPrev($node, @text)
23291  
23292 Given a B<$node> place some B<@text> prior to the $node and return the new text node else return B<undef> if this is not possible.
23293  
23294 Parameter Description
23295 1 $node The parent node
23296 2 @text The text to be added
23297  
23298 B<Example:>
23299  
23300  
23301 my $a = Data::Edit::Xml::new(q(<a><b><c/></b></a>));
23302  
23303 my $b = $a->first;
23304  
23305  
23306 $b->putTextPrev(qw(Before the B node)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23307  
23308 $b->putTextNext(qw(After the B node));
23309 $b->putTextFirst(qw(First under the B node));
23310 $b->putTextLast(qw(Last under the B node));
23311  
23312 ok -p $a eq <<END;
23313 <a>Before the B node
23314 <b>First under the B node
23315 <c/>
23316 Last under the B node
23317 </b>
23318 After the B node
23319 </a>
23320 END
23321  
23322  
23323 =head2 Put as tree
23324  
23325 Add parsed text to the L<parse|/parse> tree.
23326  
23327 =head3 putFirstAsTree($node, $text, @context)
23328  
23329 Put parsed text first under the specified B<$node> parent and return a reference to the parsed tree. Confess if the text cannot be parsed successfully.
23330  
23331 Parameter Description
23332 1 $node The parent node
23333 2 $text The string to be parsed and added
23334 3 @context Context
23335  
23336 Use the optional B<@context> parameter to test the context of the specified
23337 B<$node> as understood by method L<at|/at>. If the context is supplied and
23338 B<$node> is not in this context then this method returns B<undef> immediately.
23339  
23340  
23341  
23342 B<Example:>
23343  
23344  
23345 if (1)
23346 {my $a = Data::Edit::Xml::new(q(<a/>));
23347  
23348 ok -p $a eq <<END;
23349 <a/>
23350 END
23351  
23352  
23353 my $b = $a->putFirstAsTree(q(<b/>)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23354  
23355 ok -p $a eq <<END;
23356 <a>
23357 <b/>
23358 </a>
23359 END
23360  
23361 $b->putNextAsTree(q(<c/>));
23362 ok -p $a eq <<END;
23363 <a>
23364 <b/>
23365 <c/>
23366 </a>
23367 END
23368  
23369 my $e = $a->putLastAsTree(q(<e/>));
23370 ok -p $a eq <<END;
23371 <a>
23372 <b/>
23373 <c/>
23374 <e/>
23375 </a>
23376 END
23377  
23378 $e->putPrevAsTree(q(<d/>));
23379 ok -p $a eq <<END;
23380 <a>
23381 <b/>
23382 <c/>
23383 <d/>
23384 <e/>
23385 </a>
23386 END
23387 }
23388  
23389  
23390 =head3 putLastAsTree($node, $text, @context)
23391  
23392 Put parsed text last under the specified B<$node> parent and return a reference to the parsed tree. Confess if the text cannot be parsed successfully.
23393  
23394 Parameter Description
23395 1 $node The parent node
23396 2 $text The string to be parsed and added
23397 3 @context Context
23398  
23399 Use the optional B<@context> parameter to test the context of the specified
23400 B<$node> as understood by method L<at|/at>. If the context is supplied and
23401 B<$node> is not in this context then this method returns B<undef> immediately.
23402  
23403  
23404  
23405 B<Example:>
23406  
23407  
23408 if (1)
23409 {my $a = Data::Edit::Xml::new(q(<a/>));
23410  
23411 ok -p $a eq <<END;
23412 <a/>
23413 END
23414  
23415 my $b = $a->putFirstAsTree(q(<b/>));
23416 ok -p $a eq <<END;
23417 <a>
23418 <b/>
23419 </a>
23420 END
23421  
23422 $b->putNextAsTree(q(<c/>));
23423 ok -p $a eq <<END;
23424 <a>
23425 <b/>
23426 <c/>
23427 </a>
23428 END
23429  
23430  
23431 my $e = $a->putLastAsTree(q(<e/>)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23432  
23433 ok -p $a eq <<END;
23434 <a>
23435 <b/>
23436 <c/>
23437 <e/>
23438 </a>
23439 END
23440  
23441 $e->putPrevAsTree(q(<d/>));
23442 ok -p $a eq <<END;
23443 <a>
23444 <b/>
23445 <c/>
23446 <d/>
23447 <e/>
23448 </a>
23449 END
23450 }
23451  
23452  
23453 =head3 putNextAsTree($node, $text, @context)
23454  
23455 Put parsed text after the specified B<$node> parent and return a reference to the parsed tree. Confess if the text cannot be parsed successfully.
23456  
23457 Parameter Description
23458 1 $node The parent node
23459 2 $text The string to be parsed and added
23460 3 @context Context
23461  
23462 Use the optional B<@context> parameter to test the context of the specified
23463 B<$node> as understood by method L<at|/at>. If the context is supplied and
23464 B<$node> is not in this context then this method returns B<undef> immediately.
23465  
23466  
23467  
23468 B<Example:>
23469  
23470  
23471 if (1)
23472 {my $a = Data::Edit::Xml::new(q(<a/>));
23473  
23474 ok -p $a eq <<END;
23475 <a/>
23476 END
23477  
23478 my $b = $a->putFirstAsTree(q(<b/>));
23479 ok -p $a eq <<END;
23480 <a>
23481 <b/>
23482 </a>
23483 END
23484  
23485  
23486 $b->putNextAsTree(q(<c/>)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23487  
23488 ok -p $a eq <<END;
23489 <a>
23490 <b/>
23491 <c/>
23492 </a>
23493 END
23494  
23495 my $e = $a->putLastAsTree(q(<e/>));
23496 ok -p $a eq <<END;
23497 <a>
23498 <b/>
23499 <c/>
23500 <e/>
23501 </a>
23502 END
23503  
23504 $e->putPrevAsTree(q(<d/>));
23505 ok -p $a eq <<END;
23506 <a>
23507 <b/>
23508 <c/>
23509 <d/>
23510 <e/>
23511 </a>
23512 END
23513 }
23514  
23515  
23516 =head3 putPrevAsTree($node, $text, @context)
23517  
23518 Put parsed text before the specified B<$parent> parent and return a reference to the parsed tree. Confess if the text cannot be parsed successfully.
23519  
23520 Parameter Description
23521 1 $node The parent node
23522 2 $text The string to be parsed and added
23523 3 @context Context
23524  
23525 Use the optional B<@context> parameter to test the context of the specified
23526 B<$node> as understood by method L<at|/at>. If the context is supplied and
23527 B<$node> is not in this context then this method returns B<undef> immediately.
23528  
23529  
23530  
23531 B<Example:>
23532  
23533  
23534 if (1)
23535 {my $a = Data::Edit::Xml::new(q(<a/>));
23536  
23537 ok -p $a eq <<END;
23538 <a/>
23539 END
23540  
23541 my $b = $a->putFirstAsTree(q(<b/>));
23542 ok -p $a eq <<END;
23543 <a>
23544 <b/>
23545 </a>
23546 END
23547  
23548 $b->putNextAsTree(q(<c/>));
23549 ok -p $a eq <<END;
23550 <a>
23551 <b/>
23552 <c/>
23553 </a>
23554 END
23555  
23556 my $e = $a->putLastAsTree(q(<e/>));
23557 ok -p $a eq <<END;
23558 <a>
23559 <b/>
23560 <c/>
23561 <e/>
23562 </a>
23563 END
23564  
23565  
23566 $e->putPrevAsTree(q(<d/>)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23567  
23568 ok -p $a eq <<END;
23569 <a>
23570 <b/>
23571 <c/>
23572 <d/>
23573 <e/>
23574 </a>
23575 END
23576 }
23577  
23578  
23579 =head2 Put as comment
23580  
23581 Add some comments to the parse tree relative to the specified B<$node> in the optional B<$context> and return the specified B<$node>.
23582  
23583 =head3 putFirstAsComment($node, $text, @context)
23584  
23585 Put a comment first under the specified B<$node> and return the specified B<$node>.
23586  
23587 Parameter Description
23588 1 $node Parent node
23589 2 $text Comment
23590 3 @context Context
23591  
23592 Use the optional B<@context> parameter to test the context of the specified
23593 B<$node> as understood by method L<at|/at>. If the context is supplied and
23594 B<$node> is not in this context then this method returns B<undef> immediately.
23595  
23596  
23597  
23598 B<Example:>
23599  
23600  
23601 my $a = Data::Edit::Xml::new(<<END);
23602 <a>
23603 <b>
23604 <c/>
23605 </b>
23606 </a>
23607 END
23608  
23609  
23610 $a->putFirstAsComment(q(First)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23611  
23612 $a->putLastAsComment (q(Last));
23613 $a->go_b_c->putPrevAsComment(q(Before C));
23614 $a->go_b_c->putNextAsComment(q(After C));
23615  
23616 ok -p $a eq <<END;
23617 <a><!-- First -->
23618 <b><!-- Before C -->
23619 <c/>
23620 <!-- After C -->
23621 </b>
23622 <!-- Last -->
23623 </a>
23624 END
23625  
23626  
23627 =head3 putLastAsComment($node, $text, @context)
23628  
23629 Put a comment last under the specified B<$node> and return the specified B<$node>.
23630  
23631 Parameter Description
23632 1 $node Parent node
23633 2 $text Comment
23634 3 @context Context
23635  
23636 Use the optional B<@context> parameter to test the context of the specified
23637 B<$node> as understood by method L<at|/at>. If the context is supplied and
23638 B<$node> is not in this context then this method returns B<undef> immediately.
23639  
23640  
23641  
23642 B<Example:>
23643  
23644  
23645 my $a = Data::Edit::Xml::new(<<END);
23646 <a>
23647 <b>
23648 <c/>
23649 </b>
23650 </a>
23651 END
23652  
23653 $a->putFirstAsComment(q(First));
23654  
23655 $a->putLastAsComment (q(Last)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23656  
23657 $a->go_b_c->putPrevAsComment(q(Before C));
23658 $a->go_b_c->putNextAsComment(q(After C));
23659  
23660 ok -p $a eq <<END;
23661 <a><!-- First -->
23662 <b><!-- Before C -->
23663 <c/>
23664 <!-- After C -->
23665 </b>
23666 <!-- Last -->
23667 </a>
23668 END
23669  
23670  
23671 =head3 putNextAsComment($node, $text, @context)
23672  
23673 Put a comment after the specified B<$node> and return the specified B<$node>
23674  
23675 Parameter Description
23676 1 $node Node
23677 2 $text Comment
23678 3 @context Context
23679  
23680 Use the optional B<@context> parameter to test the context of the specified
23681 B<$node> as understood by method L<at|/at>. If the context is supplied and
23682 B<$node> is not in this context then this method returns B<undef> immediately.
23683  
23684  
23685  
23686 B<Example:>
23687  
23688  
23689 my $a = Data::Edit::Xml::new(<<END);
23690 <a>
23691 <b>
23692 <c/>
23693 </b>
23694 </a>
23695 END
23696  
23697 $a->putFirstAsComment(q(First));
23698 $a->putLastAsComment (q(Last));
23699 $a->go_b_c->putPrevAsComment(q(Before C));
23700  
23701 $a->go_b_c->putNextAsComment(q(After C)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23702  
23703  
23704 ok -p $a eq <<END;
23705 <a><!-- First -->
23706 <b><!-- Before C -->
23707 <c/>
23708 <!-- After C -->
23709 </b>
23710 <!-- Last -->
23711 </a>
23712 END
23713  
23714  
23715 =head3 putPrevAsComment($node, $text, @context)
23716  
23717 Put a comment before the specified B<$parent> parentand return the specified B<$node>
23718  
23719 Parameter Description
23720 1 $node Node
23721 2 $text Comment
23722 3 @context Context
23723  
23724 Use the optional B<@context> parameter to test the context of the specified
23725 B<$node> as understood by method L<at|/at>. If the context is supplied and
23726 B<$node> is not in this context then this method returns B<undef> immediately.
23727  
23728  
23729  
23730 B<Example:>
23731  
23732  
23733 my $a = Data::Edit::Xml::new(<<END);
23734 <a>
23735 <b>
23736 <c/>
23737 </b>
23738 </a>
23739 END
23740  
23741 $a->putFirstAsComment(q(First));
23742 $a->putLastAsComment (q(Last));
23743  
23744 $a->go_b_c->putPrevAsComment(q(Before C)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23745  
23746 $a->go_b_c->putNextAsComment(q(After C));
23747  
23748 ok -p $a eq <<END;
23749 <a><!-- First -->
23750 <b><!-- Before C -->
23751 <c/>
23752 <!-- After C -->
23753 </b>
23754 <!-- Last -->
23755 </a>
23756 END
23757  
23758  
23759 =head2 Break in and out
23760  
23761 Break nodes out of nodes or push them back
23762  
23763 =head3 breakIn($start, @context)
23764  
23765 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 L<breakInBackwards|/breakInBackwards>, to concatenate only the following nodes, use L<breakInForwards|/breakInForwards>.
23766  
23767 Parameter Description
23768 1 $start The start node
23769 2 @context Optional context.
23770  
23771 Use the optional B<@context> parameter to test the context of the specified
23772 B<$node> as understood by method L<at|/at>. If the context is supplied and
23773 B<$node> is not in this context then this method returns B<undef> immediately.
23774  
23775  
23776  
23777 B<Example:>
23778  
23779  
23780 ok -p $a eq <<END;
23781 <a>
23782 <d/>
23783 <b>
23784 <c/>
23785 <c/>
23786 </b>
23787 <e/>
23788 <b>
23789 <c/>
23790 <c/>
23791 </b>
23792 <d/>
23793 </a>
23794 END
23795  
23796  
23797 $a->go(qw(b 1))->breakIn; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23798  
23799  
23800 ok -p $a eq <<END;
23801 <a>
23802 <b>
23803 <d/>
23804 <c/>
23805 <c/>
23806 <e/>
23807 <c/>
23808 <c/>
23809 <d/>
23810 </b>
23811 </a>
23812 END
23813  
23814  
23815 =head3 breakInForwards($start, @context)
23816  
23817 Concatenate the nodes following the start node, unwrapping nodes whose tag matches the start node and return the start node in the manner of L<breakIn|/breakIn>.
23818  
23819 Parameter Description
23820 1 $start The start node
23821 2 @context Optional context..
23822  
23823 Use the optional B<@context> parameter to test the context of the specified
23824 B<$node> as understood by method L<at|/at>. If the context is supplied and
23825 B<$node> is not in this context then this method returns B<undef> immediately.
23826  
23827  
23828  
23829 B<Example:>
23830  
23831  
23832 ok -p $a eq <<END;
23833 <a>
23834 <d/>
23835 <b>
23836 <c/>
23837 <c/>
23838 </b>
23839 <e/>
23840 <b>
23841 <c/>
23842 <c/>
23843 </b>
23844 <d/>
23845 </a>
23846 END
23847  
23848  
23849 $a->go(q(b))->breakInForwards; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23850  
23851  
23852 ok -p $a eq <<END;
23853 <a>
23854 <d/>
23855 <b>
23856 <c/>
23857 <c/>
23858 <e/>
23859 <c/>
23860 <c/>
23861 <d/>
23862 </b>
23863 </a>
23864 END
23865  
23866  
23867 =head3 breakInBackwards($start, @context)
23868  
23869 Concatenate the nodes preceding the start node, unwrapping nodes whose tag matches the start node and return the start node in the manner of L<breakIn|/breakIn>.
23870  
23871 Parameter Description
23872 1 $start The start node
23873 2 @context Optional context..
23874  
23875 Use the optional B<@context> parameter to test the context of the specified
23876 B<$node> as understood by method L<at|/at>. If the context is supplied and
23877 B<$node> is not in this context then this method returns B<undef> immediately.
23878  
23879  
23880  
23881 B<Example:>
23882  
23883  
23884 ok -p $a eq <<END;
23885 <a>
23886 <d/>
23887 <b>
23888 <c/>
23889 <c/>
23890 </b>
23891 <e/>
23892 <b>
23893 <c/>
23894 <c/>
23895 </b>
23896 <d/>
23897 </a>
23898 END
23899  
23900  
23901 $a->go(qw(b 1))->breakInBackwards; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23902  
23903  
23904 ok -p $a eq <<END;
23905 <a>
23906 <b>
23907 <d/>
23908 <c/>
23909 <c/>
23910 <e/>
23911 <c/>
23912 <c/>
23913 </b>
23914 <d/>
23915 </a>
23916 END
23917  
23918  
23919 =head3 breakOut($parent, @tags)
23920  
23921 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.
23922  
23923 Parameter Description
23924 1 $parent The parent node
23925 2 @tags The tags of the modes to be broken out.
23926  
23927 B<Example:>
23928  
23929  
23930 my $A = Data::Edit::Xml::new("<a><b><d/><c/><c/><e/><c/><c/><d/></b></a>");
23931  
23932  
23933 $a->go(q(b))->breakOut($a, qw(d e)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23934  
23935  
23936 ok -p $a eq <<END;
23937 <a>
23938 <d/>
23939 <b>
23940 <c/>
23941 <c/>
23942 </b>
23943 <e/>
23944 <b>
23945 <c/>
23946 <c/>
23947 </b>
23948 <d/>
23949 </a>
23950 END
23951  
23952  
23953 =head3 breakOutChild($node, @context)
23954  
23955 Lift the specified B<$node> up one level splitting its parent. Return the specified B<$node> on success or B<undef> if the operation is not possible.
23956  
23957 Parameter Description
23958 1 $node Node to break out
23959 2 @context Optional context
23960  
23961 Use the optional B<@context> parameter to test the context of the specified
23962 B<$node> as understood by method L<at|/at>. If the context is supplied and
23963 B<$node> is not in this context then this method returns B<undef> immediately.
23964  
23965  
23966  
23967 B<Example:>
23968  
23969  
23970 my $a = Data::Edit::Xml::new(<<END);
23971 <a>
23972 <b>
23973 <c/>
23974 <d/>
23975 <e/>
23976 </b>
23977 </a>
23978 END
23979  
23980 my ($c, $d, $e, $b) = $a->byList;
23981  
23982 $d->breakOutChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
23983  
23984  
23985 ok -p $a eq <<END;
23986 <a>
23987 <b>
23988 <c/>
23989 </b>
23990 <d/>
23991 <b>
23992 <e/>
23993 </b>
23994 </a>
23995 END
23996  
23997  
23998 =head2 Split and Zip
23999  
24000 Move a node up the parse tree by splitting its parent nodes
24001  
24002 =head3 splitParentAfter($node, @context)
24003  
24004 Finish and restart the parent of the specified B<$node> just after the specified B<$node> and return the newly created parent node on success or B<undef> on failure.
24005  
24006 Parameter Description
24007 1 $node The splitting node
24008 2 @context Optional context.
24009  
24010 Use the optional B<@context> parameter to test the context of the specified
24011 B<$node> as understood by method L<at|/at>. If the context is supplied and
24012 B<$node> is not in this context then this method returns B<undef> immediately.
24013  
24014  
24015  
24016 B<Example:>
24017  
24018  
24019 my $a = Data::Edit::Xml::new(<<END);
24020 <a>
24021 <b>
24022 <c/>
24023 <d/>
24024 <e/>
24025 </b>
24026 </a>
24027 END
24028  
24029 $a->go_b_d__splitParentAfter;
24030  
24031 ok -p $a eq <<END;
24032 <a>
24033 <b>
24034 <c/>
24035 <d/>
24036 </b>
24037 <b>
24038 <e/>
24039 </b>
24040 </a>
24041 END
24042  
24043  
24044 B<spa> is a synonym for L<splitParentAfter|/splitParentAfter>.
24045  
24046  
24047 =head3 splitParentBefore($node, @context)
24048  
24049 Finish and restart the parent of the specified B<$node> just before the specified B<$node> and return the newly created parent node on success or B<undef> on failure.
24050  
24051 Parameter Description
24052 1 $node The splitting node
24053 2 @context Optional context.
24054  
24055 Use the optional B<@context> parameter to test the context of the specified
24056 B<$node> as understood by method L<at|/at>. If the context is supplied and
24057 B<$node> is not in this context then this method returns B<undef> immediately.
24058  
24059  
24060  
24061 B<Example:>
24062  
24063  
24064 my $a = Data::Edit::Xml::new(<<END);
24065 <a>
24066 <b>
24067 <c/>
24068 <d/>
24069 <e/>
24070 </b>
24071 </a>
24072 END
24073  
24074 $a->go_b_d__splitParentBefore;
24075  
24076 ok -p $a ne <<END;
24077 <a>
24078 <b>
24079 <c/>
24080 </b>
24081 <b>
24082 <d/>
24083 <e/>
24084 </b>
24085 </a>
24086 END
24087  
24088  
24089 B<spb> is a synonym for L<splitParentBefore|/splitParentBefore>.
24090  
24091  
24092 =head3 splitTo($node, $parent, @context)
24093  
24094 Lift the specified B<$node> up until it splits the specified B<$parent> node. Return the specified B<$node> on success or B<undef> if the operation is not possible.
24095  
24096 Parameter Description
24097 1 $node Node to break out
24098 2 $parent Ancestral node to split
24099 3 @context Optional context
24100  
24101 Use the optional B<@context> parameter to test the context of the specified
24102 B<$node> as understood by method L<at|/at>. If the context is supplied and
24103 B<$node> is not in this context then this method returns B<undef> immediately.
24104  
24105  
24106  
24107 B<Example:>
24108  
24109  
24110 my $a = Data::Edit::Xml::new(<<END);
24111 <a>
24112 <b>
24113 <c>
24114 <d>
24115 <e/>
24116 </d>
24117 </c>
24118 </b>
24119 </a>
24120 END
24121  
24122 my ($e, $d, $c, $b) = $a->byList;
24123  
24124  
24125 ok !$a->splitTo($a); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24126  
24127  
24128 ok !$b->splitTo($a); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24129  
24130  
24131 ok $e->splitTo($b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24132  
24133  
24134 ok -p $a eq <<END;
24135 <a>
24136 <b>
24137 <c>
24138 <d/>
24139 </c>
24140 </b>
24141 <e/>
24142 <b>
24143 <c>
24144 <d/>
24145 </c>
24146 </b>
24147 </a>
24148 END
24149  
24150 my $a = Data::Edit::Xml::new(<<END);
24151 <a>
24152 <b>
24153 <c>
24154 <d>
24155 <e/>
24156 </d>
24157 </c>
24158 </b>
24159 </a>
24160 END
24161  
24162 my ($e, $d, $c, $b) = $a->byList;
24163  
24164  
24165 ok !$a->splitTo($a); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24166  
24167  
24168 ok !$b->splitTo($a); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24169  
24170  
24171 ok $e->splitTo($b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24172  
24173  
24174 ok -p $a eq <<END;
24175 <a>
24176 <b>
24177 <c>
24178 <d/>
24179 </c>
24180 </b>
24181 <e/>
24182 <b>
24183 <c>
24184 <d/>
24185 </c>
24186 </b>
24187 </a>
24188 END
24189  
24190 ok $e->zipDownOnce; # Invalidates b
24191 ok -p $a eq <<END;
24192 <a>
24193 <b>
24194 <c>
24195 <d/>
24196 </c>
24197 <e/>
24198 <c>
24199 <d/>
24200 </c>
24201 </b>
24202 </a>
24203 END
24204  
24205  
24206 ok $e->splitTo($a->first); # b invalidated by zipDownOnce # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24207  
24208 $e->zipDown;
24209  
24210 ok -p $a eq <<END;
24211 <a>
24212 <b>
24213 <c>
24214 <d>
24215 <e/>
24216 </d>
24217 </c>
24218 </b>
24219 </a>
24220 END
24221  
24222  
24223 =head3 adoptChild($parent, $child, @context)
24224  
24225 Lift the specified B<$child> node up until it is an immediate child of the specified B<$parent> node by splitting any intervening nodes. Return the specified B<$child> node on success or B<undef> if the operation is not possible.
24226  
24227 Parameter Description
24228 1 $parent Adopting parent node
24229 2 $child Child node to adopt
24230 3 @context Optional context of child
24231  
24232 Use the optional B<@context> parameter to test the context of the specified
24233 B<$node> as understood by method L<at|/at>. If the context is supplied and
24234 B<$node> is not in this context then this method returns B<undef> immediately.
24235  
24236  
24237  
24238 B<Example:>
24239  
24240  
24241 my $a = Data::Edit::Xml::new(<<END);
24242 <a>
24243 <b>
24244 <c>
24245 <d>
24246 <e/>
24247 </d>
24248 </c>
24249 </b>
24250 </a>
24251 END
24252  
24253 my ($e, $d, $c, $b) = $a->byList;
24254  
24255  
24256 $a->adoptChild($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24257  
24258 ok -p $a eq <<END;
24259 <a>
24260 <b>
24261 <c>
24262 <d/>
24263 </c>
24264 </b>
24265 <e/>
24266 <b>
24267 <c>
24268 <d/>
24269 </c>
24270 </b>
24271 </a>
24272 END
24273  
24274 $e->zipDown;
24275 ok -p $a eq <<END;
24276 <a>
24277 <b>
24278 <c>
24279 <d>
24280 <e/>
24281 </d>
24282 </c>
24283 </b>
24284 </a>
24285 END
24286  
24287  
24288  
24289 =head3 zipDownOnce($node, @context)
24290  
24291 Push a node down one level by making it a child of a node formed by merging the preceding and following siblings if they have the same tag.
24292  
24293 Parameter Description
24294 1 $node Node
24295 2 @context Optional context
24296  
24297 Use the optional B<@context> parameter to test the context of the specified
24298 B<$node> as understood by method L<at|/at>. If the context is supplied and
24299 B<$node> is not in this context then this method returns B<undef> immediately.
24300  
24301  
24302  
24303 B<Example:>
24304  
24305  
24306 my $a = Data::Edit::Xml::new(<<END);
24307 <a>
24308 <b>
24309 <c>
24310 <d>
24311 <e/>
24312 </d>
24313 </c>
24314 </b>
24315 </a>
24316 END
24317  
24318 my ($e, $d, $c, $b) = $a->byList;
24319  
24320 ok !$a->splitTo($a);
24321 ok !$b->splitTo($a);
24322 ok $e->splitTo($b);
24323  
24324 ok -p $a eq <<END;
24325 <a>
24326 <b>
24327 <c>
24328 <d/>
24329 </c>
24330 </b>
24331 <e/>
24332 <b>
24333 <c>
24334 <d/>
24335 </c>
24336 </b>
24337 </a>
24338 END
24339  
24340  
24341 ok $e->zipDownOnce; # Invalidates b # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24342  
24343 ok -p $a eq <<END;
24344 <a>
24345 <b>
24346 <c>
24347 <d/>
24348 </c>
24349 <e/>
24350 <c>
24351 <d/>
24352 </c>
24353 </b>
24354 </a>
24355 END
24356  
24357  
24358 ok $e->splitTo($a->first); # b invalidated by zipDownOnce # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24359  
24360 $e->zipDown;
24361  
24362 ok -p $a eq <<END;
24363 <a>
24364 <b>
24365 <c>
24366 <d>
24367 <e/>
24368 </d>
24369 </c>
24370 </b>
24371 </a>
24372 END
24373  
24374  
24375 =head3 zipDown($node, @context)
24376  
24377 Push a node down as many levels as possible by making it a child of a node formed by merging the preceding and following siblings if they have the same tag.
24378  
24379 Parameter Description
24380 1 $node Node
24381 2 @context Optional context
24382  
24383 Use the optional B<@context> parameter to test the context of the specified
24384 B<$node> as understood by method L<at|/at>. If the context is supplied and
24385 B<$node> is not in this context then this method returns B<undef> immediately.
24386  
24387  
24388  
24389 B<Example:>
24390  
24391  
24392 my $a = Data::Edit::Xml::new(<<END);
24393 <a>
24394 <b>
24395 <c>
24396 <d>
24397 <e/>
24398 </d>
24399 </c>
24400 </b>
24401 </a>
24402 END
24403  
24404 my ($e, $d, $c, $b) = $a->byList;
24405  
24406 $a->adoptChild($e);
24407 ok -p $a eq <<END;
24408 <a>
24409 <b>
24410 <c>
24411 <d/>
24412 </c>
24413 </b>
24414 <e/>
24415 <b>
24416 <c>
24417 <d/>
24418 </c>
24419 </b>
24420 </a>
24421 END
24422  
24423  
24424 $e->zipDown; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24425  
24426 ok -p $a eq <<END;
24427 <a>
24428 <b>
24429 <c>
24430 <d>
24431 <e/>
24432 </d>
24433 </c>
24434 </b>
24435 </a>
24436 END
24437  
24438  
24439 my $a = Data::Edit::Xml::new(<<END);
24440 <a>
24441 <b>
24442 <c>
24443 <d>
24444 <e/>
24445 </d>
24446 </c>
24447 </b>
24448 </a>
24449 END
24450  
24451 my ($e, $d, $c, $b) = $a->byList;
24452  
24453 ok !$a->splitTo($a);
24454 ok !$b->splitTo($a);
24455 ok $e->splitTo($b);
24456  
24457 ok -p $a eq <<END;
24458 <a>
24459 <b>
24460 <c>
24461 <d/>
24462 </c>
24463 </b>
24464 <e/>
24465 <b>
24466 <c>
24467 <d/>
24468 </c>
24469 </b>
24470 </a>
24471 END
24472  
24473 ok $e->zipDownOnce; # Invalidates b
24474 ok -p $a eq <<END;
24475 <a>
24476 <b>
24477 <c>
24478 <d/>
24479 </c>
24480 <e/>
24481 <c>
24482 <d/>
24483 </c>
24484 </b>
24485 </a>
24486 END
24487  
24488 ok $e->splitTo($a->first); # b invalidated by zipDownOnce
24489  
24490 $e->zipDown; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24491  
24492  
24493 ok -p $a eq <<END;
24494 <a>
24495 <b>
24496 <c>
24497 <d>
24498 <e/>
24499 </d>
24500 </c>
24501 </b>
24502 </a>
24503 END
24504  
24505  
24506 =head3 splitAndWrapFromStart($parent, $split, $wrap, %attributes)
24507  
24508 Split the child nodes of B<$parent> on the child nodes with a tag of B<$split> wrapping the splitting node and all preceding nodes from the previous splitting node or the start with the specified B<$wrap>ping node with optional B<%attributes>. Returns an array of the wrapping nodes created.
24509  
24510 Parameter Description
24511 1 $parent Parent node
24512 2 $split Tag of splitting nodes
24513 3 $wrap Tag for wrapping node
24514 4 %attributes Attributes for wrapping nodes
24515  
24516 Use the optional B<@context> parameter to test the context of the specified
24517 B<$node> as understood by method L<at|/at>. If the context is supplied and
24518 B<$node> is not in this context then this method returns B<undef> immediately.
24519  
24520  
24521  
24522 B<Example:>
24523  
24524  
24525  
24526 my $A = Data::Edit::Xml::new(<<END);
24527 <a>
24528 <PP/>
24529 <b>
24530 <c/>
24531 </b>
24532 <QQ/>
24533 <b>
24534 <d/>
24535 </b>
24536 <RR/>
24537 <b>
24538 <e/>
24539 </b>
24540 <SS/>
24541 </a>
24542 END
24543  
24544 my $a = $A->clone;
24545  
24546 ok 3 == $a->splitAndWrapFromStart(qw(b B)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24547  
24548  
24549 ok -p $a eq <<END;
24550 <a>
24551 <B>
24552 <PP/>
24553 <b>
24554 <c/>
24555 </b>
24556 </B>
24557 <B>
24558 <QQ/>
24559 <b>
24560 <d/>
24561 </b>
24562 </B>
24563 <B>
24564 <RR/>
24565 <b>
24566 <e/>
24567 </b>
24568 </B>
24569 <SS/>
24570 </a>
24571 END
24572  
24573  
24574 my $b = $A->clone;
24575 ok 3 == $b->splitAndWrapToEnd(qw(b B));
24576  
24577 ok -p $b eq <<END;
24578 <a>
24579 <PP/>
24580 <B>
24581 <b>
24582 <c/>
24583 </b>
24584 <QQ/>
24585 </B>
24586 <B>
24587 <b>
24588 <d/>
24589 </b>
24590 <RR/>
24591 </B>
24592 <B>
24593 <b>
24594 <e/>
24595 </b>
24596 <SS/>
24597 </B>
24598 </a>
24599 END
24600  
24601  
24602 =head3 splitAndWrapToEnd($parent, $split, $wrap, %attributes)
24603  
24604 Split the sequence of child nodes under the specified B<$parent> node on those child nodes whose tag value is B<$split> wrapping the splitting node and all following nodes up until the next splitting node or the end of the sequence with newly created nodes whose tag is B<$wrap> with optional attributes B<%attributes>. Returns an array of the wrapping nodes so created.
24605  
24606 Parameter Description
24607 1 $parent Parent node
24608 2 $split Tag of splitting nodes
24609 3 $wrap Tag for wrapping node
24610 4 %attributes Attributes for wrapping nodes
24611  
24612 Use the optional B<@context> parameter to test the context of the specified
24613 B<$node> as understood by method L<at|/at>. If the context is supplied and
24614 B<$node> is not in this context then this method returns B<undef> immediately.
24615  
24616  
24617  
24618 B<Example:>
24619  
24620  
24621  
24622 my $A = Data::Edit::Xml::new(<<END);
24623 <a>
24624 <PP/>
24625 <b>
24626 <c/>
24627 </b>
24628 <QQ/>
24629 <b>
24630 <d/>
24631 </b>
24632 <RR/>
24633 <b>
24634 <e/>
24635 </b>
24636 <SS/>
24637 </a>
24638 END
24639  
24640 my $a = $A->clone;
24641 ok 3 == $a->splitAndWrapFromStart(qw(b B));
24642  
24643 ok -p $a eq <<END;
24644 <a>
24645 <B>
24646 <PP/>
24647 <b>
24648 <c/>
24649 </b>
24650 </B>
24651 <B>
24652 <QQ/>
24653 <b>
24654 <d/>
24655 </b>
24656 </B>
24657 <B>
24658 <RR/>
24659 <b>
24660 <e/>
24661 </b>
24662 </B>
24663 <SS/>
24664 </a>
24665 END
24666  
24667  
24668 my $b = $A->clone;
24669  
24670 ok 3 == $b->splitAndWrapToEnd(qw(b B)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24671  
24672  
24673 ok -p $b eq <<END;
24674 <a>
24675 <PP/>
24676 <B>
24677 <b>
24678 <c/>
24679 </b>
24680 <QQ/>
24681 </B>
24682 <B>
24683 <b>
24684 <d/>
24685 </b>
24686 <RR/>
24687 </B>
24688 <B>
24689 <b>
24690 <e/>
24691 </b>
24692 <SS/>
24693 </B>
24694 </a>
24695 END
24696  
24697  
24698 =head2 Replace
24699  
24700 Replace nodes in the L<parse|/parse> tree with nodes or text
24701  
24702 =head3 replaceWith($old, $new, @context)
24703  
24704 Replace a node (and all its content) with a L<new node|/newTag> (and all its content) and return the new node. If the node to be replaced is the root of the L<parse|/parse> tree then no action is taken other then returning the new node.
24705  
24706 Parameter Description
24707 1 $old Old node
24708 2 $new New node
24709 3 @context Optional context..
24710  
24711 Use the optional B<@context> parameter to test the context of the specified
24712 B<$node> as understood by method L<at|/at>. If the context is supplied and
24713 B<$node> is not in this context then this method returns B<undef> immediately.
24714  
24715  
24716  
24717 B<Example:>
24718  
24719  
24720 {my $x = Data::Edit::Xml::new(qq(<a><b><c id="cc"/></b></a>));
24721  
24722  
24723 $x->go(qw(b c))->replaceWith($x->newTag(qw(d id dd))); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24724  
24725  
24726 ok -s $x eq '<a><b><d id="dd"/></b></a>';
24727  
24728  
24729 =head3 replaceWithText($old, $text, @context)
24730  
24731 Replace a node (and all its content) with a new text node and return the new node.
24732  
24733 Parameter Description
24734 1 $old Old node
24735 2 $text Text of new node
24736 3 @context Optional context.
24737  
24738 Use the optional B<@context> parameter to test the context of the specified
24739 B<$node> as understood by method L<at|/at>. If the context is supplied and
24740 B<$node> is not in this context then this method returns B<undef> immediately.
24741  
24742  
24743  
24744 B<Example:>
24745  
24746  
24747 {my $x = Data::Edit::Xml::new(qq(<a><b><c id="cc"/></b></a>));
24748  
24749  
24750 $x->go(qw(b c))->replaceWithText(qq(BBBB)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24751  
24752  
24753 ok -s $x eq '<a><b>BBBB</b></a>';
24754  
24755  
24756 =head3 replaceWithBlank($old, @context)
24757  
24758 Replace a node (and all its content) with a new blank text node and return the new node.
24759  
24760 Parameter Description
24761 1 $old Old node
24762 2 @context Optional context.
24763  
24764 Use the optional B<@context> parameter to test the context of the specified
24765 B<$node> as understood by method L<at|/at>. If the context is supplied and
24766 B<$node> is not in this context then this method returns B<undef> immediately.
24767  
24768  
24769  
24770 B<Example:>
24771  
24772  
24773 {my $x = Data::Edit::Xml::new(qq(<a><b><c id="cc"/></b></a>));
24774  
24775  
24776 $x->go(qw(b c))->replaceWithBlank; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24777  
24778  
24779 ok -s $x eq '<a><b> </b></a>';
24780  
24781  
24782 =head3 replaceContentWithMovedContent($node, @nodes)
24783  
24784 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.
24785  
24786 Parameter Description
24787 1 $node Target node
24788 2 @nodes Source nodes
24789  
24790 B<Example:>
24791  
24792  
24793 my $a = Data::Edit::Xml::new(<<END);
24794 <a>
24795 <b>
24796 <b1/>
24797 <b2/>
24798 </b>
24799 <c>
24800 <c1/>
24801 <c2/>
24802 </c>
24803 <d>
24804 <d1/>
24805 <d2/>
24806 </d>
24807 </a>
24808 END
24809  
24810 my ($b, $c, $d) = $a->contents;
24811  
24812  
24813 $d->replaceContentWithMovedContent($c, $b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24814  
24815  
24816 ok -p $a eq <<END;
24817 <a>
24818 <b/>
24819 <c/>
24820 <d>
24821 <c1/>
24822 <c2/>
24823 <b1/>
24824 <b2/>
24825 </d>
24826 </a>
24827 END
24828  
24829 my $a = Data::Edit::Xml::new(<<END);
24830 <a>
24831 <d>
24832 <b>
24833 <b1/>
24834 <b2/>
24835 </b>
24836 <c>
24837 <c1/>
24838 <c2/>
24839 </c>
24840 </d>
24841 </a>
24842 END
24843  
24844 my ($d) = $a->contents;
24845  
24846 my ($b, $c) = $d->contents;
24847  
24848  
24849 $d->replaceContentWithMovedContent($c, $b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24850  
24851  
24852 ok -p $a eq <<END;
24853 <a>
24854 <d>
24855 <c1/>
24856 <c2/>
24857 <b1/>
24858 <b2/>
24859 </d>
24860 </a>
24861 END
24862  
24863  
24864 =head3 replaceContentWith($node, @content)
24865  
24866 Replace the content of a node with the specified nodes and return the replaced content
24867  
24868 Parameter Description
24869 1 $node Node whose content is to be replaced
24870 2 @content New content
24871  
24872 B<Example:>
24873  
24874  
24875 {my $x = Data::Edit::Xml::new(qq(<a><b/><c/></a>));
24876  
24877  
24878 $x->replaceContentWith(map {$x->newTag($_)} qw(B C)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24879  
24880  
24881 ok -s $x eq '<a><B/><C/></a>';
24882  
24883  
24884 =head3 replaceContentWithText($node, @text)
24885  
24886 Replace the content of a node with the specified texts and return the replaced content
24887  
24888 Parameter Description
24889 1 $node Node whose content is to be replaced
24890 2 @text Texts to form new content
24891  
24892 B<Example:>
24893  
24894  
24895 {my $x = Data::Edit::Xml::new(qq(<a><b/><c/></a>));
24896  
24897  
24898 $x->replaceContentWithText(qw(b c)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24899  
24900  
24901 ok -s $x eq '<a>bc</a>';
24902  
24903  
24904 =head2 Swap
24905  
24906 Swap nodes both singly and in blocks
24907  
24908 =head3 invert($parent, @context)
24909  
24910 Swap a parent and child node where the child is the only child of the parent and return the parent.
24911  
24912 Parameter Description
24913 1 $parent Parent
24914 2 @context Context
24915  
24916 Use the optional B<@context> parameter to test the context of the specified
24917 B<$node> as understood by method L<at|/at>. If the context is supplied and
24918 B<$node> is not in this context then this method returns B<undef> immediately.
24919  
24920  
24921  
24922 B<Example:>
24923  
24924  
24925 {my $a = Data::Edit::Xml::new(<<END);
24926 <a>
24927 <b id="b">
24928 <c id="c">
24929 <d/>
24930 <e/>
24931 </c>
24932 </b>
24933 </a>
24934 END
24935  
24936  
24937 $a->first->invert; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24938  
24939  
24940 ok -p $a eq <<END;
24941 <a>
24942 <c id="c">
24943 <b id="b">
24944 <d/>
24945 <e/>
24946 </b>
24947 </c>
24948 </a>
24949 END
24950  
24951  
24952 $a->first->invert; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
24953  
24954  
24955 ok -p $a eq <<END;
24956 <a>
24957 <b id="b">
24958 <c id="c">
24959 <d/>
24960 <e/>
24961 </c>
24962 </b>
24963 </a>
24964 END
24965  
24966  
24967 =head3 invertFirst($parent, @context)
24968  
24969 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.
24970  
24971 Parameter Description
24972 1 $parent Parent
24973 2 @context Context
24974  
24975 Use the optional B<@context> parameter to test the context of the specified
24976 B<$node> as understood by method L<at|/at>. If the context is supplied and
24977 B<$node> is not in this context then this method returns B<undef> immediately.
24978  
24979  
24980  
24981 B<Example:>
24982  
24983  
24984 {my $a = Data::Edit::Xml::new(<<END);
24985 <a>
24986 <b>
24987 <c>
24988 <d/>
24989 <e/>
24990 </c>
24991 <f/>
24992 <g/>
24993 </b>
24994 </a>
24995 END
24996  
24997 ok -p $a eq <<END;
24998 <a>
24999 <c>
25000 <d/>
25001 <e/>
25002 <b>
25003 <f/>
25004 <g/>
25005 </b>
25006 </c>
25007 </a>
25008 END
25009  
25010  
25011 =head3 invertLast($parent, @context)
25012  
25013 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.
25014  
25015 Parameter Description
25016 1 $parent Parent
25017 2 @context Context
25018  
25019 Use the optional B<@context> parameter to test the context of the specified
25020 B<$node> as understood by method L<at|/at>. If the context is supplied and
25021 B<$node> is not in this context then this method returns B<undef> immediately.
25022  
25023  
25024  
25025 B<Example:>
25026  
25027  
25028 {my $a = Data::Edit::Xml::new(<<END);
25029 <a>
25030 <b>
25031 <c>
25032 <d/>
25033 <e/>
25034 </c>
25035 <f/>
25036 <g/>
25037 </b>
25038 </a>
25039 END
25040  
25041 ok -p $a eq <<END;
25042 <a>
25043 <c>
25044 <d/>
25045 <e/>
25046 <b>
25047 <f/>
25048 <g/>
25049 </b>
25050 </c>
25051 </a>
25052 END
25053  
25054 ok -p $a eq <<END;
25055 <a>
25056 <b>
25057 <c>
25058 <d/>
25059 <e/>
25060 </c>
25061 <f/>
25062 <g/>
25063 </b>
25064 </a>
25065 END
25066  
25067  
25068 =head3 swap($first, $second, @context)
25069  
25070 Swap two nodes optionally checking that the first node is in the specified context and return the first node.
25071  
25072 Parameter Description
25073 1 $first First node
25074 2 $second Second node
25075 3 @context Optional context
25076  
25077 Use the optional B<@context> parameter to test the context of the specified
25078 B<$node> as understood by method L<at|/at>. If the context is supplied and
25079 B<$node> is not in this context then this method returns B<undef> immediately.
25080  
25081  
25082  
25083 B<Example:>
25084  
25085  
25086 ok <<END eq -p $x;
25087 <x>
25088 <a a="1" b="2"/>
25089 <b/>
25090 <c a="1" b="3" c="4"/>
25091 </x>
25092 END
25093  
25094  
25095 $a->swap($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25096  
25097  
25098 ok <<END eq -p $x;
25099 <x>
25100 <c a="1" b="3" c="4"/>
25101 <b/>
25102 <a a="1" b="2"/>
25103 </x>
25104 END
25105  
25106  
25107 =head3 swapFirstSibling($node, @context)
25108  
25109 Swap B<$node> with its first sibling node and return B<$node>.
25110  
25111 Parameter Description
25112 1 $node Node
25113 2 @context Optional context
25114  
25115 Use the optional B<@context> parameter to test the context of the specified
25116 B<$node> as understood by method L<at|/at>. If the context is supplied and
25117 B<$node> is not in this context then this method returns B<undef> immediately.
25118  
25119  
25120  
25121 B<Example:>
25122  
25123  
25124 my $a = Data::Edit::Xml::new(<<END);
25125 <a>
25126 <b/>
25127 <c/>
25128 <d/>
25129 <e/>
25130 <f/>
25131 <g/>
25132 </a>
25133 END
25134  
25135 $a->go_f__swapFirstSibling;
25136  
25137 ok -p $a eq <<END;
25138 <a>
25139 <f/>
25140 <c/>
25141 <d/>
25142 <e/>
25143 <b/>
25144 <g/>
25145 </a>
25146 END
25147  
25148 $a->go_c__swapLastSibling;
25149  
25150 ok -p $a eq <<END;
25151 <a>
25152 <f/>
25153 <g/>
25154 <d/>
25155 <e/>
25156 <b/>
25157 <c/>
25158 </a>
25159 END
25160  
25161  
25162 B<sfs> is a synonym for L<swapFirstSibling|/swapFirstSibling>.
25163  
25164  
25165 =head3 swapNext($node, @context)
25166  
25167 Swap B<$node> with its following node if $B<$node> matches the first element of the specified context and the next node matches the rest. Return the node that originally followed B<$node> on success or B<undef> on failure.
25168  
25169 Parameter Description
25170 1 $node Node
25171 2 @context Optional context
25172  
25173 Use the optional B<@context> parameter to test the context of the specified
25174 B<$node> as understood by method L<at|/at>. If the context is supplied and
25175 B<$node> is not in this context then this method returns B<undef> immediately.
25176  
25177  
25178  
25179 B<Example:>
25180  
25181  
25182 my $a = Data::Edit::Xml::new(<<END);
25183 <a>
25184 <b>
25185 <c>
25186 <d/>
25187 <e/>
25188 </c>
25189 <f>
25190 <g/>
25191 </f>
25192 </b>
25193 </a>
25194 END
25195  
25196 my ($d, $e, $c, $g, $f, $b) = $a->byList;
25197  
25198 ok -t $b eq q(b);
25199  
25200  
25201 $d->swapNext; $g->swapPrev; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25202  
25203 ok $d->after($e);
25204 ok -p $a eq <<END;
25205 <a>
25206 <b>
25207 <c>
25208 <e/>
25209 <d/>
25210 </c>
25211 <f>
25212 <g/>
25213 </f>
25214 </b>
25215 </a>
25216 END
25217  
25218  
25219 $d->swapPrev; $c->swapNext; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25220  
25221 ok $f->before($c);
25222 ok -p $a eq <<END;
25223 <a>
25224 <b>
25225 <f>
25226 <g/>
25227 </f>
25228 <c>
25229 <d/>
25230 <e/>
25231 </c>
25232 </b>
25233 </a>
25234 END
25235  
25236  
25237 B<sn> is a synonym for L<swapNext|/swapNext>.
25238  
25239  
25240 =head3 swapPrev($node, @context)
25241  
25242 Swap B<$node> with its preceding node if $B<$node> matches the first element of the specified context and the previous node matches the rest. Return the node that originally followed B<$node> on success or B<undef> on failure.
25243  
25244 Parameter Description
25245 1 $node Node
25246 2 @context Optional context
25247  
25248 Use the optional B<@context> parameter to test the context of the specified
25249 B<$node> as understood by method L<at|/at>. If the context is supplied and
25250 B<$node> is not in this context then this method returns B<undef> immediately.
25251  
25252  
25253  
25254 B<Example:>
25255  
25256  
25257 my $a = Data::Edit::Xml::new(<<END);
25258 <a>
25259 <b>
25260 <c>
25261 <d/>
25262 <e/>
25263 </c>
25264 <f>
25265 <g/>
25266 </f>
25267 </b>
25268 </a>
25269 END
25270  
25271 my ($d, $e, $c, $g, $f, $b) = $a->byList;
25272  
25273 ok -t $b eq q(b);
25274  
25275  
25276 $d->swapNext; $g->swapPrev; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25277  
25278 ok $d->after($e);
25279 ok -p $a eq <<END;
25280 <a>
25281 <b>
25282 <c>
25283 <e/>
25284 <d/>
25285 </c>
25286 <f>
25287 <g/>
25288 </f>
25289 </b>
25290 </a>
25291 END
25292  
25293  
25294 $d->swapPrev; $c->swapNext; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25295  
25296 ok $f->before($c);
25297 ok -p $a eq <<END;
25298 <a>
25299 <b>
25300 <f>
25301 <g/>
25302 </f>
25303 <c>
25304 <d/>
25305 <e/>
25306 </c>
25307 </b>
25308 </a>
25309 END
25310  
25311  
25312 B<sp> is a synonym for L<swapPrev|/swapPrev>.
25313  
25314  
25315 =head3 swapLastSibling($node, @context)
25316  
25317 Swap B<$node> with its last sibling node and return B<$node>.
25318  
25319 Parameter Description
25320 1 $node Node
25321 2 @context Optional context
25322  
25323 Use the optional B<@context> parameter to test the context of the specified
25324 B<$node> as understood by method L<at|/at>. If the context is supplied and
25325 B<$node> is not in this context then this method returns B<undef> immediately.
25326  
25327  
25328  
25329 B<Example:>
25330  
25331  
25332 my $a = Data::Edit::Xml::new(<<END);
25333 <a>
25334 <b/>
25335 <c/>
25336 <d/>
25337 <e/>
25338 <f/>
25339 <g/>
25340 </a>
25341 END
25342  
25343 $a->go_f__swapFirstSibling;
25344  
25345 ok -p $a eq <<END;
25346 <a>
25347 <f/>
25348 <c/>
25349 <d/>
25350 <e/>
25351 <b/>
25352 <g/>
25353 </a>
25354 END
25355  
25356 $a->go_c__swapLastSibling;
25357  
25358 ok -p $a eq <<END;
25359 <a>
25360 <f/>
25361 <g/>
25362 <d/>
25363 <e/>
25364 <b/>
25365 <c/>
25366 </a>
25367 END
25368  
25369  
25370 B<sls> is a synonym for L<swapLastSibling|/swapLastSibling>.
25371  
25372  
25373 =head3 swapTags($first, $second, @context)
25374  
25375 Swap the tags of two nodes optionally checking that the first node is in the specified context and return (B<$first>, B<$second>) nodes.
25376  
25377 Parameter Description
25378 1 $first First node
25379 2 $second Second node
25380 3 @context Optional context
25381  
25382 Use the optional B<@context> parameter to test the context of the specified
25383 B<$node> as understood by method L<at|/at>. If the context is supplied and
25384 B<$node> is not in this context then this method returns B<undef> immediately.
25385  
25386  
25387  
25388 B<Example:>
25389  
25390  
25391 my $a = Data::Edit::Xml::new(<<END);
25392 <a>
25393 <b>
25394 <c/>
25395 </b>
25396 </a>
25397 END
25398  
25399  
25400 $a->swapTags($a->first); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25401  
25402 ok -p $a eq <<END;
25403 <b>
25404 <a>
25405 <c/>
25406 </a>
25407 </b>
25408 END
25409  
25410 my ($C, $A) = $a->downWhileFirst->swapTagWithParent;
25411 ok -t $A eq q(a);
25412 ok -t $C eq q(c);
25413 ok -p $a eq <<END;
25414 <b>
25415 <c>
25416 <a/>
25417 </c>
25418 </b>
25419 END
25420  
25421  
25422 =head3 swapTagWithParent($node, @context)
25423  
25424 Swap the tags of the specified B<$node> and its parent optionally checking that the B<$node> is in the specified context and return (parent of B<$node>, B<$node>) or () if there is no such parent node.
25425  
25426 Parameter Description
25427 1 $node Node
25428 2 @context Optional context
25429  
25430 Use the optional B<@context> parameter to test the context of the specified
25431 B<$node> as understood by method L<at|/at>. If the context is supplied and
25432 B<$node> is not in this context then this method returns B<undef> immediately.
25433  
25434  
25435  
25436 B<Example:>
25437  
25438  
25439 my $a = Data::Edit::Xml::new(<<END);
25440 <a>
25441 <b>
25442 <c/>
25443 </b>
25444 </a>
25445 END
25446  
25447 $a->swapTags($a->first);
25448 ok -p $a eq <<END;
25449 <b>
25450 <a>
25451 <c/>
25452 </a>
25453 </b>
25454 END
25455  
25456  
25457 my ($C, $A) = $a->downWhileFirst->swapTagWithParent; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25458  
25459 ok -t $A eq q(a);
25460 ok -t $C eq q(c);
25461 ok -p $a eq <<END;
25462 <b>
25463 <c>
25464 <a/>
25465 </c>
25466 </b>
25467 END
25468  
25469  
25470 =head3 reorder($node, $first, $second, @context)
25471  
25472 If the current B<$node> has a context of (B<$first>, @context) and the preceding node has a context of (B<$second>, B<@context>), then swap the current node with the previous node.Return the current node regardless
25473  
25474 Parameter Description
25475 1 $node Node
25476 2 $first First tag
25477 3 $second Second tag
25478 4 @context Optional context
25479  
25480 Use the optional B<@context> parameter to test the context of the specified
25481 B<$node> as understood by method L<at|/at>. If the context is supplied and
25482 B<$node> is not in this context then this method returns B<undef> immediately.
25483  
25484  
25485  
25486 B<Example:>
25487  
25488  
25489 my $a = Data::Edit::Xml::new(<<END);
25490 <a>
25491 <d>
25492 <c/>
25493 </d>
25494 <b>
25495 <c/>
25496 </b>
25497 </a>
25498 END
25499  
25500 $a->by(sub {$_->reorder_b_d_a});
25501  
25502 ok -p $a eq <<END;
25503 <a>
25504 <b>
25505 <c/>
25506 </b>
25507 <d>
25508 <c/>
25509 </d>
25510 </a>
25511 END
25512  
25513 $a->by(sub {$_->reorder_b_d_a});
25514  
25515 ok -p $a eq <<END;
25516 <a>
25517 <b>
25518 <c/>
25519 </b>
25520 <d>
25521 <c/>
25522 </d>
25523 </a>
25524 END
25525  
25526  
25527 =head2 Wrap and unwrap
25528  
25529 Wrap and unwrap nodes to alter the depth of the L<parse|/parse> tree
25530  
25531 =head3 Wrap
25532  
25533 Wrap nodes to deepen the L<parse|/parse> tree
25534  
25535 =head4 wrapWith($node, $tag, @context)
25536  
25537 Wrap the specified B<$node> in a new node created from the specified B<$tag> in the optional B<@context> forcing the specified $node down to deepen the L<parse|/parse> tree - return the new wrapping node or B<undef> if this is not possible. See L<addWrapWith|/addWrapWith> to perform this operation conditionally.
25538  
25539 Parameter Description
25540 1 $node Node
25541 2 $tag Tag for the new node or tag
25542 3 @context Optional context
25543  
25544 B<Example:>
25545  
25546  
25547 ok -p $x eq <<END;
25548 <a>
25549 <b>
25550 <c id="11"/>
25551 </b>
25552 </a>
25553 END
25554  
25555  
25556 $x->go(qw(b c))->wrapWith(qw(C)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25557  
25558  
25559 ok -p $x eq <<END;
25560 <a>
25561 <b>
25562 <C>
25563 <c id="11"/>
25564 </C>
25565 </b>
25566 </a>
25567 END
25568  
25569  
25570 =head4 wrapWithDup($node, @context)
25571  
25572 Wrap the specified B<$node> in a new node with the same tag as $node in the optional B<@context> making $node an L<only child|/isOnlyChild> of the new node. Return the new wrapping node or B<undef> if this is not possible.
25573  
25574 Parameter Description
25575 1 $node Node
25576 2 @context Optional context
25577  
25578 B<Example:>
25579  
25580  
25581 my $a = Data::Edit::Xml::new(<<END);
25582 <a><b><c/></b></a>
25583 END
25584  
25585 my ($c, $b) = $a->byList;
25586  
25587  
25588 $c->wrapWithDup->id = 'c'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25589  
25590 ok -p $a eq <<END;
25591 <a>
25592 <b>
25593 <c id="c">
25594 <c/>
25595 </c>
25596 </b>
25597 </a>
25598 END
25599  
25600 $b->wrapContentWithDup->id = 'b';
25601 ok -p $a eq <<END;
25602 <a>
25603 <b>
25604 <b id="b">
25605 <c id="c">
25606 <c/>
25607 </c>
25608 </b>
25609 </b>
25610 </a>
25611 END
25612  
25613  
25614 =head4 wrapUp($node, @tags)
25615  
25616 Wrap the specified B<$node> in a sequence of new nodes created from the specified B<@tags> forcing the original node down - deepening the L<parse|/parse> tree - return the array of wrapping nodes if want array else the last wrapping node.
25617  
25618 Parameter Description
25619 1 $node Node to wrap
25620 2 @tags Tags to wrap the node with - with the uppermost tag rightmost.
25621  
25622 B<Example:>
25623  
25624  
25625 my $c = Data::Edit::Xml::newTree("c", id=>33);
25626  
25627  
25628 my ($b, $a) = $c->wrapUp(qw(b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25629  
25630  
25631 ok -p $a eq <<'END';
25632 <a>
25633 <b>
25634 <c id="33"/>
25635 </b>
25636 </a>
25637 END
25638  
25639  
25640 =head4 wrapWithN($node, $N, @context)
25641  
25642 Wrap this B<$node> with the first B<$N> elements of B<@context>. If B<@context> contains more then B<$N> entries, the remainder are checked as the context of B<$node>. Returns the upper most wrapping node or B<undef> if the specified B<$node> does not match these conditions.
25643  
25644 Parameter Description
25645 1 $node Node
25646 2 $N Number of tags wrapping tags
25647 3 @context Tags and optional context
25648  
25649 Use the optional B<@context> parameter to test the context of the specified
25650 B<$node> as understood by method L<at|/at>. If the context is supplied and
25651 B<$node> is not in this context then this method returns B<undef> immediately.
25652  
25653  
25654  
25655 B<Example:>
25656  
25657  
25658 my $a = Data::Edit::Xml::new(<<END);
25659 <a>
25660 <d/>
25661 </a>
25662 END
25663  
25664 ok !$a->go_d__wrapWithN_2_c_b_a;
25665 $a->by(sub{$_->wrapWithN_2_c_b_d_a});
25666  
25667 ok -p $a eq <<END;
25668 <a>
25669 <b>
25670 <c>
25671 <d/>
25672 </c>
25673 </b>
25674 </a>
25675 END
25676  
25677  
25678 =head4 wrapWithAll($node, @tags)
25679  
25680 Wrap this B<$node> wrapped with the specified B<@tags> and return the last wrapping node.
25681  
25682 Parameter Description
25683 1 $node Node
25684 2 @tags Tags
25685  
25686 Use the optional B<@context> parameter to test the context of the specified
25687 B<$node> as understood by method L<at|/at>. If the context is supplied and
25688 B<$node> is not in this context then this method returns B<undef> immediately.
25689  
25690  
25691  
25692 B<Example:>
25693  
25694  
25695 my $a = Data::Edit::Xml::new(<<END);
25696 <a>
25697 <d/>
25698 </a>
25699 END
25700  
25701 $a->go_d__wrapWithAll_c_b;
25702  
25703 ok -p $a eq <<END;
25704 <a>
25705 <b>
25706 <c>
25707 <d/>
25708 </c>
25709 </b>
25710 </a>
25711 END
25712  
25713 my $a = Data::Edit::Xml::new(q(<a id="c4"/>));
25714 my $b = Data::Edit::Xml::new(q(<a id="c5"/>));
25715  
25716 ok -M $a eq -M $b;
25717  
25718  
25719 B<ww> is a synonym for L<wrapWithAll|/wrapWithAll>.
25720  
25721  
25722 =head4 wrapDown($node, @tags)
25723  
25724 Wrap the content of the specified B<$node> in a sequence of new nodes forcing the original node up - deepening the L<parse|/parse> tree - return the array of wrapping nodes if want array else the last wrapping node.
25725  
25726 Parameter Description
25727 1 $node Node to wrap
25728 2 @tags Tags to wrap the node with - with the uppermost tag rightmost.
25729  
25730 B<Example:>
25731  
25732  
25733 my $a = Data::Edit::Xml::newTree("a", id=>33);
25734  
25735  
25736 my ($b, $c) = $a->wrapDown(qw(b c)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25737  
25738  
25739 ok -p $a eq <<END;
25740 <a id="33">
25741 <b>
25742 <c/>
25743 </b>
25744 </a>
25745 END
25746  
25747  
25748 =head4 wrapContentWith($old, $tag, %attributes)
25749  
25750 Wrap the content of the specified B<$node> in a new node created from the specified B<$tag> and B<%attributes>: the specified B<$node> then contains just the new node which, in turn, contains all the content of the specified B<$node>.
25751  
25752 Returns the new wrapping node.
25753  
25754 Parameter Description
25755 1 $old Node
25756 2 $tag Tag for new node
25757 3 %attributes Attributes for new node.
25758  
25759 B<Example:>
25760  
25761  
25762 ok -p $x eq <<END;
25763 <a>
25764 <b>
25765 <c/>
25766 <c/>
25767 <c/>
25768 </b>
25769 </a>
25770 END
25771  
25772  
25773 $x->go(q(b))->wrapContentWith(qw(D id DD)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25774  
25775  
25776 ok -p $x eq <<END;
25777 <a>
25778 <b>
25779 <D id="DD">
25780 <c/>
25781 <c/>
25782 <c/>
25783 </D>
25784 </b>
25785 </a>
25786 END
25787  
25788 ok -p $a eq <<END;
25789 <a>
25790 <b id="1"/>
25791 <c id="2"/>
25792 <d id="3"/>
25793 <c id="4"/>
25794 <d id="5"/>
25795 <e id="6"/>
25796 <b id="7"/>
25797 <c id="8"/>
25798 <d id="9"/>
25799 <f id="10"/>
25800 </a>
25801 END
25802  
25803  
25804 B<wcw> is a synonym for L<wrapContentWith|/wrapContentWith>.
25805  
25806  
25807 =head4 wrapContentWithDup($node, @context)
25808  
25809 Wrap the content if the specified B<$node> in a new node with the same tag as $node in the optional B<@context> making the new node an L<only child|/isOnlyChild> of $node. Return the new wrapping node or B<undef> if this is not possible.
25810  
25811 Parameter Description
25812 1 $node Node
25813 2 @context Optional context
25814  
25815 B<Example:>
25816  
25817  
25818 my $a = Data::Edit::Xml::new(<<END);
25819 <a><b><c/></b></a>
25820 END
25821  
25822 my ($c, $b) = $a->byList;
25823  
25824 $c->wrapWithDup->id = 'c';
25825 ok -p $a eq <<END;
25826 <a>
25827 <b>
25828 <c id="c">
25829 <c/>
25830 </c>
25831 </b>
25832 </a>
25833 END
25834  
25835  
25836 $b->wrapContentWithDup->id = 'b'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25837  
25838 ok -p $a eq <<END;
25839 <a>
25840 <b>
25841 <b id="b">
25842 <c id="c">
25843 <c/>
25844 </c>
25845 </b>
25846 </b>
25847 </a>
25848 END
25849  
25850  
25851 =head4 wrapSiblingsBefore($node, $tag, %attributes)
25852  
25853 If there are any siblings before the specified B<$node>, wrap them with a new node created from the specified B<$tag> and B<%attributes> and return the newly created node.
25854  
25855 Returns B<undef> if the specified B<$node> is the first node under its parent.
25856  
25857 Parameter Description
25858 1 $node Node to wrap before
25859 2 $tag Tag for new node
25860 3 %attributes Attributes for new node.
25861  
25862 B<Example:>
25863  
25864  
25865 {my $a = Data::Edit::Xml::new(q(<a><b/><c/><d/></a>));
25866  
25867 my ($b, $c, $d) = $a->byList;
25868  
25869  
25870 $c->wrapSiblingsBefore(q(X)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
25871  
25872  
25873 ok -p $a eq <<END;
25874 <a>
25875 <X>
25876 <b/>
25877 </X>
25878 <c/>
25879 <d/>
25880 </a>
25881 END
25882  
25883  
25884 =head4 wrapFromFirst($node, $tag, %attributes)
25885  
25886 Wrap this B<$node> and any preceding siblings with a new node created from the specified B<$tag> and B<%attributes> and return the wrapping node.
25887  
25888 Parameter Description
25889 1 $node Node to wrap before
25890 2 $tag Tag for new node
25891 3 %attributes Attributes for new node.
25892  
25893 B<Example:>
25894  
25895  
25896 if (1)
25897 {my $a = Data::Edit::Xml::new(q(<a><b/><c/><d/></a>));
25898  
25899 ok -p $a eq <<END;
25900 <a>
25901 <b/>
25902 <c/>
25903 <d/>
25904 </a>
25905 END
25906  
25907 $a->go_c->wrapFromFirst_B;
25908 ok -p $a eq <<END;
25909 <a>
25910 <B>
25911 <b/>
25912 <c/>
25913 </B>
25914 <d/>
25915 </a>
25916 END
25917 }
25918  
25919  
25920 =head4 wrapFromFirstOrLastIn($node, $tag, @targets)
25921  
25922 Wrap inclusively from the first sibling node to the specified B<$node> or from the last prior sibling node whose tag matches one of the tags in B<@targets> to the specified B<$node> using B<$tag> as the tag of the wrapping node and return the wrapping node.
25923  
25924 Parameter Description
25925 1 $node Node at which to start to wrap
25926 2 $tag Wrapping tag
25927 3 @targets Tags at which to end the wrap.
25928  
25929 B<Example:>
25930  
25931  
25932 my $a = Data::Edit::Xml::new(<<END);
25933 <a><b/><c/><d/><e/><f/></a>
25934 END
25935  
25936 $a->go_d__wrapFromFirstOrLastIn_g_a_b_c;
25937 ok -p $a eq <<END;
25938 <a>
25939 <b/>
25940 <g>
25941 <c/>
25942 <d/>
25943 </g>
25944 <e/>
25945 <f/>
25946 </a>
25947 END
25948  
25949 $a->go_e__wrapFromFirstOrLastIn_i_A_B_C;
25950 ok -p $a eq <<END;
25951 <a>
25952 <i>
25953 <b/>
25954 <g>
25955 <c/>
25956 <d/>
25957 </g>
25958 <e/>
25959 </i>
25960 <f/>
25961 </a>
25962 END
25963  
25964  
25965 =head4 wrapFirstN($node, $N, $tag, @context)
25966  
25967 Wrap the first B<$N> nodes under this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
25968  
25969 Parameter Description
25970 1 $node Node
25971 2 $N Number of nodes to wrap
25972 3 $tag Wrapping tag
25973 4 @context Optional context
25974  
25975 B<Example:>
25976  
25977  
25978 my $a = Data::Edit::Xml::new(<<END);
25979 <a>
25980 <b/>
25981 <c/>
25982 <d/>
25983 </a>
25984 END
25985  
25986 $a->wrapFirstN_2_Z;
25987  
25988 ok -p $a eq <<END;
25989 <a>
25990 <Z>
25991 <b/>
25992 <c/>
25993 </Z>
25994 <d/>
25995 </a>
25996 END
25997  
25998  
25999 =head4 wrapSiblingsBetween($first, $last, $tag, %attributes)
26000  
26001 If there are any siblings between the specified B<$node>s, wrap them with a new node created from the specified B<$tag> and B<%attributes>. Return the wrapping node else B<undef> if there are no nodes to wrap.
26002  
26003 Parameter Description
26004 1 $first First sibling
26005 2 $last Last sibling
26006 3 $tag Tag for new node
26007 4 %attributes Attributes for new node.
26008  
26009 B<Example:>
26010  
26011  
26012 {my $a = Data::Edit::Xml::new(q(<a><b/><c/><d/></a>));
26013  
26014 my ($b, $c, $d) = $a->byList;
26015  
26016  
26017 $b->wrapSiblingsBetween($d, q(Y)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26018  
26019  
26020 ok -p $a eq <<END;
26021 <a>
26022 <b/>
26023 <Y>
26024 <c/>
26025 </Y>
26026 <d/>
26027 </a>
26028 END
26029  
26030  
26031 =head4 wrapSiblingsAfter($node, $tag, %attributes)
26032  
26033 If there are any siblings after the specified B<$node>, wrap them with a new node created from the specified B<$tag> and B<%attributes> and return the newly created node.
26034  
26035 Returns B<undef> if the specified B<$node> is the last node under its parent.
26036  
26037 Parameter Description
26038 1 $node Node to wrap before
26039 2 $tag Tag for new node
26040 3 %attributes Attributes for new node.
26041  
26042 B<Example:>
26043  
26044  
26045 {my $a = Data::Edit::Xml::new(q(<a><b/><c/><d/></a>));
26046  
26047 my ($b, $c, $d) = $a->byList;
26048  
26049  
26050 $c->wrapSiblingsAfter(q(Y)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26051  
26052  
26053 ok -p $a eq <<END;
26054 <a>
26055 <b/>
26056 <c/>
26057 <Y>
26058 <d/>
26059 </Y>
26060 </a>
26061 END
26062  
26063  
26064 =head4 wrapNext($node, $tag, @context)
26065  
26066 Wrap this B<$node> and the following sibling with a new node created from the specified B<$tag>. If the optional context is specified then it should match the first node, next node and the context of the parent of the B<$node> as far as it is specified. Return the new node created or B<undef> on failure.
26067  
26068 Parameter Description
26069 1 $node Node to wrap before
26070 2 $tag Tag for new node
26071 3 @context Context.
26072  
26073 B<Example:>
26074  
26075  
26076 my $a = Data::Edit::Xml::new(<<END);
26077 <a>
26078 <b/>
26079 <c/>
26080 <d/>
26081 </a>
26082 END
26083  
26084 my ($b, $c, $d) = $a->byList;
26085  
26086 $b->wrapNext_e;
26087 ok -p $a eq <<END;
26088 <a>
26089 <e>
26090 <b/>
26091 <c/>
26092 </e>
26093 <d/>
26094 </a>
26095 END
26096  
26097  
26098 =head4 wrapNextN($node, $N, $tag, @context)
26099  
26100 Wrap this B<$node>and the next B<$N>-1 nodes following this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
26101  
26102 Parameter Description
26103 1 $node Node
26104 2 $N Number of nodes to wrap
26105 3 $tag Wrapping tag
26106 4 @context Optional context
26107  
26108 B<Example:>
26109  
26110  
26111 my $a = Data::Edit::Xml::new(<<END);
26112 <a>
26113 <b/>
26114 <c/>
26115 <d/>
26116 <e/>
26117 </a>
26118 END
26119  
26120 $a->go_c__wrapNextN_2_Z;
26121  
26122 ok -p $a eq <<END;
26123 <a>
26124 <b/>
26125 <Z>
26126 <c/>
26127 <d/>
26128 </Z>
26129 <e/>
26130 </a>
26131 END
26132  
26133  
26134 =head4 wrapPrev($node, $tag, @context)
26135  
26136 Wrap this B<$node> and the preceding sibling with a new node created from the specified B<$tag>. If the optional context is specified then it should match the first node, previous node and the context of the parent of the B<$node> as far as it is specified. Return the new node created or B<undef> on failure.
26137  
26138 Parameter Description
26139 1 $node Node to wrap before
26140 2 $tag Tag for new node
26141 3 @context Context.
26142  
26143 B<Example:>
26144  
26145  
26146 my $a = Data::Edit::Xml::new(<<END);
26147 <a>
26148 <b/>
26149 <c/>
26150 <d/>
26151 </a>
26152 END
26153  
26154 my ($b, $c, $d) = $a->byList;
26155  
26156 $c->wrapPrev_e;
26157 ok -p $a eq <<END;
26158 <a>
26159 <e>
26160 <b/>
26161 <c/>
26162 </e>
26163 <d/>
26164 </a>
26165 END
26166  
26167  
26168 =head4 wrapPrevN($node, $N, $tag, @context)
26169  
26170 Wrap this B<$node>and the previous B<$N>-1 nodes following this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
26171  
26172 Parameter Description
26173 1 $node Node
26174 2 $N Number of nodes to wrap
26175 3 $tag Wrapping tag
26176 4 @context Optional context
26177  
26178 B<Example:>
26179  
26180  
26181 my $a = Data::Edit::Xml::new(<<END);
26182 <a>
26183 <b/>
26184 <c/>
26185 <d/>
26186 <e/>
26187 </a>
26188 END
26189  
26190 $a->go_d__wrapPrevN_2_Z;
26191  
26192 ok -p $a eq <<END;
26193 <a>
26194 <b/>
26195 <Z>
26196 <c/>
26197 <d/>
26198 </Z>
26199 <e/>
26200 </a>
26201 END
26202  
26203  
26204 =head4 wrapToLast($node, $tag, %attributes)
26205  
26206 Wrap this B<$node> and any following siblings with a new node created from the specified B<$tag> and B<%attributes> and return the wrapping node.
26207  
26208 Parameter Description
26209 1 $node Node to wrap before
26210 2 $tag Tag for new node
26211 3 %attributes Attributes for new node.
26212  
26213 B<Example:>
26214  
26215  
26216 if (1)
26217 {my $a = Data::Edit::Xml::new(q(<a><b/><c/><d/></a>));
26218  
26219 ok -p $a eq <<END;
26220 <a>
26221 <b/>
26222 <c/>
26223 <d/>
26224 </a>
26225 END
26226  
26227 $a->go_c->wrapToLast_D;
26228 ok -p $a eq <<END;
26229 <a>
26230 <b/>
26231 <D>
26232 <c/>
26233 <d/>
26234 </D>
26235 </a>
26236 END
26237 }
26238  
26239  
26240 =head4 wrapToLastOrFirstIn($node, $tag, @targets)
26241  
26242 Wrap this B<$node> and any following siblings, up to and including the first sibling that matches one of the specified B<@find> nodes or all following siblings if no such match occurs, with a new node created from the specified B<$tag> and return the new wrapping node.
26243  
26244 Parameter Description
26245 1 $node Node at which to start to wrap
26246 2 $tag Wrapping tag
26247 3 @targets Tags at which to end the wrap.
26248  
26249 B<Example:>
26250  
26251  
26252 my $a = Data::Edit::Xml::new(<<END);
26253 <a><b/><c/><d/><e/><f/></a>
26254 END
26255  
26256 $a->go_e__wrapToLastOrFirstIn_g_h;
26257 ok -p $a eq <<END;
26258 <a>
26259 <b/>
26260 <c/>
26261 <d/>
26262 <g>
26263 <e/>
26264 <f/>
26265 </g>
26266 </a>
26267 END
26268  
26269 $a->go_d__wrapToLastOrFirstIn_h_g_c;
26270 ok -p $a eq <<END;
26271 <a>
26272 <b/>
26273 <c/>
26274 <h>
26275 <d/>
26276 <g>
26277 <e/>
26278 <f/>
26279 </g>
26280 </h>
26281 </a>
26282 END
26283  
26284 $a->go_c__wrapToLastOrFirstIn_i_c;
26285 ok -p $a eq <<END;
26286 <a>
26287 <b/>
26288 <i>
26289 <c/>
26290 <h>
26291 <d/>
26292 <g>
26293 <e/>
26294 <f/>
26295 </g>
26296 </h>
26297 </i>
26298 </a>
26299 END
26300  
26301  
26302 =head4 wrapLastN($node, $N, $tag, @context)
26303  
26304 Wrap the last B<$N> nodes under this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
26305  
26306 Parameter Description
26307 1 $node Node
26308 2 $N Number of nodes to wrap
26309 3 $tag Wrapping tag
26310 4 @context Optional context
26311  
26312 B<Example:>
26313  
26314  
26315 my $a = Data::Edit::Xml::new(<<END);
26316 <a>
26317 <b/>
26318 <c/>
26319 <d/>
26320 </a>
26321 END
26322  
26323 $a->wrapLastN_2_Z;
26324  
26325 ok -p $a eq <<END;
26326 <a>
26327 <b/>
26328 <Z>
26329 <c/>
26330 <d/>
26331 </Z>
26332 </a>
26333 END
26334  
26335  
26336 =head4 wrapTo($start, $end, $tag, %attributes)
26337  
26338 Wrap all the nodes from the B<$start> node to the B<$end> node inclusive with a new node created from the specified B<$tag> and B<%attributes> and return the new node.
26339  
26340 Return B<undef> if the B<$start> and B<$end> nodes are not siblings - they must have the same parent for this method to work.
26341  
26342 Parameter Description
26343 1 $start Start node
26344 2 $end End node
26345 3 $tag Tag for the wrapping node
26346 4 %attributes Attributes for the wrapping node
26347  
26348 B<Example:>
26349  
26350  
26351 my $x = Data::Edit::Xml::new(my $s = <<END);
26352 <aa>
26353 <a>
26354 <b/>
26355 <c id="1"/><c id="2"/><c id="3"/><c id="4"/>
26356 <d/>
26357 </a>
26358 </aa>
26359 END
26360  
26361  
26362 $x->go(qw(a c))->wrapTo($x->go(qw(a c -1)), qq(C), id=>1234); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26363  
26364  
26365 ok -p $x eq <<END;
26366 <aa>
26367 <a>
26368 <b/>
26369 <C id="1234">
26370 <c id="1"/>
26371 <c id="2"/>
26372 <c id="3"/>
26373 <c id="4"/>
26374 </C>
26375 <d/>
26376 </a>
26377 </aa>
26378 END
26379  
26380 my $C = $x->go(qw(a C));
26381  
26382  
26383 $C->wrapTo($C, qq(D)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26384  
26385  
26386 ok -p $x eq <<END;
26387 <aa>
26388 <a>
26389 <b/>
26390 <D>
26391 <C id="1234">
26392 <c id="1"/>
26393 <c id="2"/>
26394 <c id="3"/>
26395 <c id="4"/>
26396 </C>
26397 </D>
26398 <d/>
26399 </a>
26400 </aa>
26401 END
26402  
26403 ok -p $a eq <<END;
26404 <a>
26405 <b>
26406 <D id="DD">
26407 <c id="0"/>
26408 <c id="1"/>
26409 </D>
26410 <E id="EE">
26411 <c id="2"/>
26412 </E>
26413 <F id="FF">
26414 <c id="3"/>
26415 </F>
26416 </b>
26417 </a>
26418 END
26419  
26420  
26421 =head4 wrapFrom($end, $start, $tag, %attributes)
26422  
26423 Wrap all the nodes from the B<$start> node to the B<$end> node with a new node created from the specified B<$tag> and B<%attributes> and return the new node. Return B<undef> if the B<$start> and B<$end> nodes are not siblings - they must have the same parent for this method to work.
26424  
26425 Parameter Description
26426 1 $end End node
26427 2 $start Start node
26428 3 $tag Tag for the wrapping node
26429 4 %attributes Attributes for the wrapping node
26430  
26431 B<Example:>
26432  
26433  
26434 {my $a = Data::Edit::Xml::new(my $s = <<END);
26435 <a>
26436 <b>
26437 <c id="0"/><c id="1"/><c id="2"/><c id="3"/>
26438 </b>
26439 </a>
26440 END
26441  
26442 my $b = $a->first;
26443  
26444 my @c = $b->contents;
26445  
26446  
26447 $c[1]->wrapFrom($c[0], qw(D id DD)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26448  
26449  
26450 ok -p $a eq <<END;
26451 <a>
26452 <b>
26453 <D id="DD">
26454 <c id="0"/>
26455 <c id="1"/>
26456 </D>
26457 <c id="2"/>
26458 <c id="3"/>
26459 </b>
26460 </a>
26461 END
26462  
26463  
26464 =head3 Unwrap
26465  
26466 Unwrap nodes to reduce the depth of the L<parse|/parse> tree
26467  
26468 =head4 unwrap($node, @context)
26469  
26470 Unwrap the specified B<$node> if in the optional B<@context> by replacing the node with its contents. Returns the parent node on success, otherwise B<undef> if an attempt is made to unwrap a text node or the root node.
26471  
26472 Parameter Description
26473 1 $node Node to unwrap
26474 2 @context Optional context.
26475  
26476 Use the optional B<@context> parameter to test the context of the specified
26477 B<$node> as understood by method L<at|/at>. If the context is supplied and
26478 B<$node> is not in this context then this method returns B<undef> immediately.
26479  
26480  
26481  
26482 B<Example:>
26483  
26484  
26485 if (1)
26486 {my $x = Data::Edit::Xml::new(q(<a>A<b/>B</a>));
26487 my $b = $x->go_b;
26488 $b->putFirst($x->newText(' c '));
26489 ok -s $x eq q(<a>A<b> c </b>B</a>);
26490  
26491 $b->unwrap; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26492  
26493 ok -s $x eq q(<a>A c B</a>);
26494 }
26495  
26496  
26497 B<u> is a synonym for L<unwrap|/unwrap>.
26498  
26499  
26500 =head4 unwrapParentOfOnlyChild($node, @context)
26501  
26502 Unwrap the parent of the specified B<$node> in the optional B<@context> when the B<$node> is the only child of its parent. Return the specified B<$node> regardless unless the node is not in the optional context in which case return B<undef>.
26503  
26504 Parameter Description
26505 1 $node Node
26506 2 @context Optional context
26507  
26508 Use the optional B<@context> parameter to test the context of the specified
26509 B<$node> as understood by method L<at|/at>. If the context is supplied and
26510 B<$node> is not in this context then this method returns B<undef> immediately.
26511  
26512  
26513  
26514 B<Example:>
26515  
26516  
26517 my $a = Data::Edit::Xml::new(<<END);
26518 <a>
26519 <b>
26520 <c/>
26521 </b>
26522 </a>
26523 END
26524  
26525  
26526 $a->go_b_c->unwrapParentOfOnlyChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26527  
26528  
26529 ok -p $a eq <<END;
26530 <a>
26531 <c/>
26532 </a>
26533 END
26534  
26535  
26536 =head4 unwrapOnlyChild($node, @context)
26537  
26538 Unwrap the specified B<$node> in the optional B<@context> when the B<$node> is the only child of its parent. Return the specified B<$node> regardless unless the node is not in the optional context in which case return B<undef>.
26539  
26540 Parameter Description
26541 1 $node Node
26542 2 @context Optional context
26543  
26544 Use the optional B<@context> parameter to test the context of the specified
26545 B<$node> as understood by method L<at|/at>. If the context is supplied and
26546 B<$node> is not in this context then this method returns B<undef> immediately.
26547  
26548  
26549  
26550 B<Example:>
26551  
26552  
26553 my $a = Data::Edit::Xml::new(<<END);
26554 <a>
26555 <b>
26556 <c/>
26557 </b>
26558 <d/>
26559 </a>
26560 END
26561  
26562  
26563 $a->go_b->unwrapOnlyChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26564  
26565  
26566 ok -p $a eq <<END;
26567 <a>
26568 <b>
26569 <c/>
26570 </b>
26571 <d/>
26572 </a>
26573 END
26574  
26575  
26576 $a->go_b_c->unwrapOnlyChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26577  
26578  
26579 ok -p $a eq <<END;
26580 <a>
26581 <b/>
26582 <d/>
26583 </a>
26584 END
26585  
26586  
26587 =head4 unwrapParentsWithSingleChild($node, @context)
26588  
26589 Unwrap any immediate ancestors of the specified B<$node> in the optional B<@context> which have only a single child and return the specified B<$node> regardless unless the node is not in the optional context in which case return B<undef>.
26590  
26591 Parameter Description
26592 1 $node Node
26593 2 @context Optional context
26594  
26595 Use the optional B<@context> parameter to test the context of the specified
26596 B<$node> as understood by method L<at|/at>. If the context is supplied and
26597 B<$node> is not in this context then this method returns B<undef> immediately.
26598  
26599  
26600  
26601 B<Example:>
26602  
26603  
26604 {my $a = Data::Edit::Xml::new(<<END);
26605 <a>
26606 <b>
26607 <c>
26608 <d/>
26609 </c>
26610 </b>
26611 <e/>
26612 </a>
26613 END
26614  
26615  
26616 $a->go(qw(b c d))->unwrapParentsWithSingleChild; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26617  
26618  
26619 ok -p $a eq <<END;
26620 <a>
26621 <d/>
26622 <e/>
26623 </a>
26624 END
26625  
26626  
26627 =head4 unwrapContentsKeepingText($node, @context)
26628  
26629 Unwrap all the non text nodes below the specified B<$node> adding a leading and a trailing space to prevent unwrapped content from being elided and return the specified B<$node> else B<undef> if not in the optional B<@context>.
26630  
26631 Parameter Description
26632 1 $node Node to unwrap
26633 2 @context Optional context.
26634  
26635 Use the optional B<@context> parameter to test the context of the specified
26636 B<$node> as understood by method L<at|/at>. If the context is supplied and
26637 B<$node> is not in this context then this method returns B<undef> immediately.
26638  
26639  
26640  
26641 B<Example:>
26642  
26643  
26644 ok -p $x eq <<END;
26645 <a>
26646 <b>
26647 <c>
26648 <d>DD</d>
26649 EE
26650 <f>FF</f>
26651 </c>
26652 </b>
26653 </a>
26654 END
26655  
26656  
26657 $x->go(qw(b))->unwrapContentsKeepingText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26658  
26659  
26660 ok -p $x eq <<END;
26661 <a>
26662 <b> DD EE FF </b>
26663 </a>
26664 END
26665  
26666  
26667 =head4 wrapRuns($node, $wrap, @context)
26668  
26669 Wrap consecutive runs of children under the specified parent B<$node> that are not already wrapped with B<$wrap>. Returns an array of any wrapping nodes created. Returns () if the specified B<$node> is not in the optional B<@context>.
26670  
26671 Parameter Description
26672 1 $node Node to unwrap
26673 2 $wrap Tag of wrapping node
26674 3 @context Optional context.
26675  
26676 Use the optional B<@context> parameter to test the context of the specified
26677 B<$node> as understood by method L<at|/at>. If the context is supplied and
26678 B<$node> is not in this context then this method returns B<undef> immediately.
26679  
26680  
26681  
26682 B<Example:>
26683  
26684  
26685 ok -p $a eq <<END;
26686 <a id="i1">
26687 <b id="i2"/>
26688 <c id="i3"/>
26689 <B id="i4">
26690 <c id="i5"/>
26691 </B>
26692 <c id="i6"/>
26693 <b id="i7"/>
26694 </a>
26695 END
26696  
26697  
26698 $a->wrapRuns(q(B)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26699  
26700  
26701 ok -p $a eq <<END;
26702 <a id="i1">
26703 <B>
26704 <b id="i2"/>
26705 <c id="i3"/>
26706 </B>
26707 <B id="i4">
26708 <c id="i5"/>
26709 </B>
26710 <B>
26711 <c id="i6"/>
26712 <b id="i7"/>
26713 </B>
26714 </a>
26715 END
26716  
26717  
26718 =head1 Contents
26719  
26720 The children of each node.
26721  
26722 =head2 contents($node, @context)
26723  
26724 Return a list of all the nodes contained by the specified B<$node> or an empty list if the node is empty or not in the optional B<@context>.
26725  
26726 Parameter Description
26727 1 $node Node
26728 2 @context Optional context.
26729  
26730 Use the B<@context> parameter to test the context of the specified
26731 B<$node> as understood by method L<at|/at>. If a context is supplied and
26732 B<$node> is not in this context then this method returns an empty list B<()>
26733 immediately.
26734  
26735  
26736  
26737 B<Example:>
26738  
26739  
26740 {my $x = Data::Edit::Xml::new(<<END);
26741 <a>
26742 <b id="b1"><c id="1"/></b>
26743 <d id="d1"><c id="2"/></d>
26744 <e id="e1"><c id="3"/></e>
26745 <b id="b2"><c id="4"/></b>
26746 <d id="d2"><c id="5"/></d>
26747 <e id="e2"><c id="6"/></e>
26748 </a>
26749 END
26750  
26751  
26752 is_deeply [map{$_->id} $x->contents], [qw(b1 d1 e1 b2 d2 e2)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26753  
26754  
26755  
26756 =head2 contentAfter($node, @context)
26757  
26758 Return a list of all the sibling nodes following the specified B<$node> or an empty list if the specified B<$node> is last or not in the optional B<@context>.
26759  
26760 Parameter Description
26761 1 $node Node
26762 2 @context Optional context.
26763  
26764 Use the B<@context> parameter to test the context of the specified
26765 B<$node> as understood by method L<at|/at>. If a context is supplied and
26766 B<$node> is not in this context then this method returns an empty list B<()>
26767 immediately.
26768  
26769  
26770  
26771 B<Example:>
26772  
26773  
26774 {my $x = Data::Edit::Xml::new(<<END);
26775 <a>
26776 <b>
26777 <c/><d/><e/><f/><g/>
26778 </b>
26779 </a>
26780 END
26781  
26782  
26783 ok 'f g' eq join ' ', map {$_->tag} $x->go(qw(b e))->contentAfter; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26784  
26785  
26786  
26787 B<ca> is a synonym for L<contentAfter|/contentAfter>.
26788  
26789  
26790 =head2 contentBefore($node, @context)
26791  
26792 Return a list of all the sibling nodes preceding the specified B<$node> (in the normal sibling order) or an empty list if the specified B<$node> is last or not in the optional B<@context>.
26793  
26794 Parameter Description
26795 1 $node Node
26796 2 @context Optional context.
26797  
26798 Use the B<@context> parameter to test the context of the specified
26799 B<$node> as understood by method L<at|/at>. If a context is supplied and
26800 B<$node> is not in this context then this method returns an empty list B<()>
26801 immediately.
26802  
26803  
26804  
26805 B<Example:>
26806  
26807  
26808 {my $x = Data::Edit::Xml::new(<<END);
26809 <a>
26810 <b>
26811 <c/><d/><e/><f/><g/>
26812 </b>
26813 </a>
26814 END
26815  
26816  
26817 ok 'c d' eq join ' ', map {$_->tag} $x->go(qw(b e))->contentBefore; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26818  
26819  
26820  
26821 B<cb> is a synonym for L<contentBefore|/contentBefore>.
26822  
26823  
26824 =head2 contentAsTags($node, @context)
26825  
26826 Return a string containing the tags of all the child nodes of the specified B<$node> separated by single spaces or the empty string if the node is empty or B<undef> if the node does not match the optional context. Use L<over|/over> to test the sequence of tags with a regular expression.
26827  
26828 Parameter Description
26829 1 $node Node
26830 2 @context Optional context.
26831  
26832 Use the B<@context> parameter to test the context of the specified
26833 B<$node> as understood by method L<at|/at>. If a context is supplied and
26834 B<$node> is not in this context then this method returns an empty list B<()>
26835 immediately.
26836  
26837  
26838  
26839 B<Example:>
26840  
26841  
26842 {my $x = Data::Edit::Xml::new(<<END);
26843 <a>
26844 <b>
26845 <c/><d/><e/><f/><g/>
26846 </b>
26847 </a>
26848 END
26849  
26850  
26851 ok $x->go(q(b))->contentAsTags eq 'c d e f g'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26852  
26853  
26854  
26855 =head2 contentAsTags2($node, @context)
26856  
26857 Return a string containing the tags of all the child nodes of the specified B<$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 B<undef> if the node does not match the optional context. Use L<over2|/over2> to test the sequence of tags with a regular expression. Use L<over2|/over2> to test the sequence of tags with a regular expression.
26858  
26859 Parameter Description
26860 1 $node Node
26861 2 @context Optional context.
26862  
26863 Use the B<@context> parameter to test the context of the specified
26864 B<$node> as understood by method L<at|/at>. If a context is supplied and
26865 B<$node> is not in this context then this method returns an empty list B<()>
26866 immediately.
26867  
26868  
26869  
26870 B<Example:>
26871  
26872  
26873  
26874 ok $x->go(q(b))->contentAsTags2 eq q( c d e f g ); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26875  
26876  
26877  
26878 =head2 contentAfterAsTags($node, @context)
26879  
26880 Return a string containing the tags of all the sibling nodes following the specified B<$node> separated by single spaces or the empty string if the node is empty or B<undef> if the node does not match the optional context. Use L<matchAfter|/matchAfter> to test the sequence of tags with a regular expression.
26881  
26882 Parameter Description
26883 1 $node Node
26884 2 @context Optional context.
26885  
26886 Use the B<@context> parameter to test the context of the specified
26887 B<$node> as understood by method L<at|/at>. If a context is supplied and
26888 B<$node> is not in this context then this method returns an empty list B<()>
26889 immediately.
26890  
26891  
26892  
26893 B<Example:>
26894  
26895  
26896 {my $x = Data::Edit::Xml::new(<<END);
26897 <a>
26898 <b>
26899 <c/><d/><e/><f/><g/>
26900 </b>
26901 </a>
26902 END
26903  
26904 ok 'f g' eq join ' ', map {$_->tag} $x->go(qw(b e))->contentAfter;
26905  
26906  
26907 ok $x->go(qw(b e))->contentAfterAsTags eq 'f g'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26908  
26909  
26910  
26911 =head2 contentAfterAsTags2($node, @context)
26912  
26913 Return a string containing the tags of all the sibling nodes following the specified B<$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 B<undef> if the node does not match the optional context. Use L<matchAfter2|/matchAfter2> to test the sequence of tags with a regular expression.
26914  
26915 Parameter Description
26916 1 $node Node
26917 2 @context Optional context.
26918  
26919 Use the B<@context> parameter to test the context of the specified
26920 B<$node> as understood by method L<at|/at>. If a context is supplied and
26921 B<$node> is not in this context then this method returns an empty list B<()>
26922 immediately.
26923  
26924  
26925  
26926 B<Example:>
26927  
26928  
26929 {my $x = Data::Edit::Xml::new(<<END);
26930 <a>
26931 <b>
26932 <c/><d/><e/><f/><g/>
26933 </b>
26934 </a>
26935 END
26936  
26937  
26938 ok $x->go(qw(b e))->contentAfterAsTags2 eq q( f g ); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26939  
26940  
26941  
26942 =head2 contentBeforeAsTags($node, @context)
26943  
26944 Return a string containing the tags of all the sibling nodes preceding the specified B<$node> separated by single spaces or the empty string if the node is empty or B<undef> if the node does not match the optional context. Use L<matchBefore|/matchBefore> to test the sequence of tags with a regular expression.
26945  
26946 Parameter Description
26947 1 $node Node
26948 2 @context Optional context.
26949  
26950 Use the B<@context> parameter to test the context of the specified
26951 B<$node> as understood by method L<at|/at>. If a context is supplied and
26952 B<$node> is not in this context then this method returns an empty list B<()>
26953 immediately.
26954  
26955  
26956  
26957 B<Example:>
26958  
26959  
26960 {my $x = Data::Edit::Xml::new(<<END);
26961 <a>
26962 <b>
26963 <c/><d/><e/><f/><g/>
26964 </b>
26965 </a>
26966 END
26967  
26968 ok 'c d' eq join ' ', map {$_->tag} $x->go(qw(b e))->contentBefore;
26969  
26970  
26971 ok $x->go(qw(b e))->contentBeforeAsTags eq 'c d'; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
26972  
26973  
26974  
26975 =head2 contentBeforeAsTags2($node, @context)
26976  
26977 Return a string containing the tags of all the sibling nodes preceding the specified B<$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 B<undef> if the node does not match the optional context. Use L<matchBefore2|/matchBefore2> to test the sequence of tags with a regular expression.
26978  
26979 Parameter Description
26980 1 $node Node
26981 2 @context Optional context.
26982  
26983 Use the B<@context> parameter to test the context of the specified
26984 B<$node> as understood by method L<at|/at>. If a context is supplied and
26985 B<$node> is not in this context then this method returns an empty list B<()>
26986 immediately.
26987  
26988  
26989  
26990 B<Example:>
26991  
26992  
26993 {my $x = Data::Edit::Xml::new(<<END);
26994 <a>
26995 <b>
26996 <c/><d/><e/><f/><g/>
26997 </b>
26998 </a>
26999 END
27000  
27001  
27002 ok $x->go(qw(b e))->contentBeforeAsTags2 eq q( c d ); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27003  
27004  
27005  
27006 =head2 position($node)
27007  
27008 Return the index of the specified B<$node> in the content of the parent of the B<$node>.
27009  
27010 Parameter Description
27011 1 $node Node.
27012  
27013 B<Example:>
27014  
27015  
27016 my $a = Data::Edit::Xml::new(<<END);
27017 <a id="11">
27018 <b id="12">
27019 <c id="13"/>
27020 <d id="14"/>
27021 <b id="15">
27022 <c id="16"/>
27023 <d id="17"/>
27024 <e id="18"/>
27025 <f id="19"/>
27026 <g id="20"/>
27027 </b>
27028 <f id="21"/>
27029 <g id="22"/>
27030 </b>
27031 <b id="23">
27032 <c id="24"/>
27033 <d id="25"/>
27034 <b id="26">
27035 <c id="27"/>
27036 <d id="28"/>
27037 <e id="29"/>
27038 <f id="30"/>
27039 <g id="31"/>
27040 </b>
27041 <f id="32"/>
27042 <g id="33"/>
27043 </b>
27044 </a>
27045 END
27046  
27047 ok $a->go(qw(b 1 b))->id == 26;
27048  
27049  
27050 ok $a->go(qw(b 1 b))->position == 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27051  
27052  
27053  
27054 =head2 index($node)
27055  
27056 Return the index of the specified B<$node> in its parent index. Use L<position|/position> to find the position of a node under its parent.
27057  
27058 Parameter Description
27059 1 $node Node.
27060  
27061 B<Example:>
27062  
27063  
27064 my $a = Data::Edit::Xml::new(<<END);
27065 <a id="11">
27066 <b id="12">
27067 <c id="13"/>
27068 <d id="14"/>
27069 <b id="15">
27070 <c id="16"/>
27071 <d id="17"/>
27072 <e id="18"/>
27073 <f id="19"/>
27074 <g id="20"/>
27075 </b>
27076 <f id="21"/>
27077 <g id="22"/>
27078 </b>
27079 <b id="23">
27080 <c id="24"/>
27081 <d id="25"/>
27082 <b id="26">
27083 <c id="27"/>
27084 <d id="28"/>
27085 <e id="29"/>
27086 <f id="30"/>
27087 <g id="31"/>
27088 </b>
27089 <f id="32"/>
27090 <g id="33"/>
27091 </b>
27092 </a>
27093 END
27094  
27095 ok $a->go(qw(b 1))->id == 23;
27096  
27097  
27098 ok $a->go(qw(b 1))->index == 1; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27099  
27100  
27101  
27102 =head2 present($node, @names)
27103  
27104 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.
27105  
27106 Parameter Description
27107 1 $node Node
27108 2 @names Possible tags immediately under the node.
27109  
27110 B<Example:>
27111  
27112  
27113  
27114 is_deeply {$a->first->present}, {c=>2, d=>2, e=>1}; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27115  
27116  
27117  
27118 =head2 editText($node, @context)
27119  
27120 Return the text of a text B<$node> as an lvalue string reference that can be modified by a regular expression, else as a reference to a dummy string that will be ignored. For a unitary version of this method see: L<changeText>
27121  
27122 Parameter Description
27123 1 $node Node to test
27124 2 @context Optional context
27125  
27126 Use the optional B<@context> parameter to test the context of the specified
27127 B<$node> as understood by method L<at|/at>. If the context is supplied and
27128 B<$node> is not in this context then this method returns B<undef> immediately.
27129  
27130  
27131  
27132 B<Example:>
27133  
27134  
27135 my $a = Data::Edit::Xml::new(<<END);
27136 <a><b>bbbb</b><c/></a>
27137 END
27138  
27139  
27140 $a->by(sub{$_->editText =~ s(bbbb) (BBBB)gs}); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27141  
27142  
27143 ok -p $a eq <<END;
27144 <a>
27145 <b>BBBB</b>
27146 <c/>
27147 </a>
27148 END
27149  
27150  
27151 =head2 isText($node, @context)
27152  
27153 Return the specified B<$node> if the specified B<$node> is a text node, optionally in the specified context, else return B<undef>.
27154  
27155 Parameter Description
27156 1 $node Node to test
27157 2 @context Optional context
27158  
27159 Use the optional B<@context> parameter to test the context of the specified
27160 B<$node> as understood by method L<at|/at>. If the context is supplied and
27161 B<$node> is not in this context then this method returns B<undef> immediately.
27162  
27163  
27164  
27165 B<Example:>
27166  
27167  
27168 ok $a->prettyStringCDATA eq <<END;
27169 <a>
27170 <b><CDATA> </CDATA></b>
27171 </a>
27172 END
27173  
27174  
27175 ok $b->first->isText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27176  
27177  
27178  
27179 ok $b->first->isText(qw(b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27180  
27181  
27182 my $a = Data::Edit::Xml::new(<<END);
27183 <a>abcdcba</a>
27184 END
27185  
27186  
27187 =head2 isFirstText($node, @context)
27188  
27189 Return the specified B<$node> if the specified B<$node> is a text node, the first node under its parent and that the parent is optionally in the specified context, else return B<undef>.
27190  
27191 Parameter Description
27192 1 $node Node to test
27193 2 @context Optional context for parent
27194  
27195 Use the optional B<@context> parameter to test the context of the specified
27196 B<$node> as understood by method L<at|/at>. If the context is supplied and
27197 B<$node> is not in this context then this method returns B<undef> immediately.
27198  
27199  
27200  
27201 B<Example:>
27202  
27203  
27204 {my $x = Data::Edit::Xml::new(<<END);
27205 <x>
27206 <a>aaa
27207 <b>bbb</b>
27208 ccc
27209 <d>ddd</d>
27210 eee
27211 </a>
27212 </x>
27213 END
27214  
27215 my $a = $x->first;
27216  
27217 my ($ta, $b, $tc, $d, $te) = $a->contents;
27218  
27219  
27220 ok $ta ->isFirstText(qw(a x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27221  
27222  
27223  
27224 ok $b->first->isFirstText(qw(b a x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27225  
27226  
27227  
27228 ok $b->prev ->isFirstText(qw(a x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27229  
27230  
27231  
27232 ok $d->last ->isFirstText(qw(d a x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27233  
27234  
27235  
27236 =head2 isLastText($node, @context)
27237  
27238 Return the specified B<$node> if the specified B<$node> is a text node, the last node under its parent and that the parent is optionally in the specified context, else return B<undef>.
27239  
27240 Parameter Description
27241 1 $node Node to test
27242 2 @context Optional context for parent
27243  
27244 Use the optional B<@context> parameter to test the context of the specified
27245 B<$node> as understood by method L<at|/at>. If the context is supplied and
27246 B<$node> is not in this context then this method returns B<undef> immediately.
27247  
27248  
27249  
27250 B<Example:>
27251  
27252  
27253 {my $x = Data::Edit::Xml::new(<<END);
27254 <x>
27255 <a>aaa
27256 <b>bbb</b>
27257 ccc
27258 <d>ddd</d>
27259 eee
27260 </a>
27261 </x>
27262 END
27263  
27264  
27265 ok $d->next ->isLastText (qw(a x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27266  
27267  
27268  
27269 ok $d->last ->isLastText (qw(d a x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27270  
27271  
27272  
27273 ok $te ->isLastText (qw(a x)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27274  
27275  
27276  
27277 =head2 matchTree($node, @match)
27278  
27279 Return a list of nodes that match the specified tree of match expressions, else B<()> 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 [].
27280  
27281 Parameter Description
27282 1 $node Node to start matching from
27283 2 @match Tree of match expressions.
27284  
27285 Use the optional B<@context> parameter to test the context of the specified
27286 B<$node> as understood by method L<at|/at>. If the context is supplied and
27287 B<$node> is not in this context then this method returns B<undef> immediately.
27288  
27289  
27290  
27291 B<Example:>
27292  
27293  
27294 if (1)
27295 {my $a = Data::Edit::Xml::new(<<END);
27296 <a>
27297 <b>
27298 <c/>
27299 <d/>
27300 </b>
27301 <e>
27302 <f>
27303 <g/>
27304 </f>
27305 </e>
27306 </a>
27307 END
27308 my ($c, $d, $b, $g, $f, $e) = $a->byList;
27309  
27310  
27311 is_deeply [$b, $c, $d], [$b->matchTree(qw(b c d))]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27312  
27313  
27314 is_deeply [$e, $f, $g], [$e->matchTree(qr(\Ae\Z), [qw(f g)])]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27315  
27316  
27317 is_deeply [$c], [$c->matchTree(qw(c))]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27318  
27319 is_deeply [$a, $b, $c, $d, $e, $f, $g],
27320  
27321 [$a->matchTree({a=>1}, [qw(b c d)], [qw(e), [qw(f g)]])]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27322  
27323 }
27324  
27325  
27326 =head2 matchesText($node, $re, @context)
27327  
27328 Returns an array of regular expression matches in the text of the specified B<$node> if it is text node and it matches the specified regular expression and optionally has the specified context otherwise returns an empty array.
27329  
27330 Parameter Description
27331 1 $node Node to test
27332 2 $re Regular expression
27333 3 @context Optional context
27334  
27335 Use the optional B<@context> parameter to test the context of the specified
27336 B<$node> as understood by method L<at|/at>. If the context is supplied and
27337 B<$node> is not in this context then this method returns B<undef> immediately.
27338  
27339  
27340  
27341 B<Example:>
27342  
27343  
27344 my $x = Data::Edit::Xml::new(<<END);
27345 <a>
27346 <b>
27347 <c>CDECD</c>
27348 </b>
27349 </a>
27350 END
27351  
27352 my $c = $x->go(qw(b c))->first;
27353  
27354  
27355 ok !$c->matchesText(qr(\AD)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27356  
27357  
27358  
27359 ok $c->matchesText(qr(\AC), qw(c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27360  
27361  
27362  
27363 ok !$c->matchesText(qr(\AD), qw(c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27364  
27365  
27366  
27367 is_deeply [qw(E)], [$c->matchesText(qr(CD(.)CD))]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27368  
27369  
27370  
27371 =head2 isBlankText($node, @context)
27372  
27373 Return the specified B<$node> if the specified B<$node> is a text node, optionally in the specified context, and contains nothing other than white space else return B<undef>. See also: L<isAllBlankText|/isAllBlankText>
27374  
27375 Parameter Description
27376 1 $node Node to test
27377 2 @context Optional context
27378  
27379 Use the optional B<@context> parameter to test the context of the specified
27380 B<$node> as understood by method L<at|/at>. If the context is supplied and
27381 B<$node> is not in this context then this method returns B<undef> immediately.
27382  
27383  
27384  
27385 B<Example:>
27386  
27387  
27388 ok $a->prettyStringCDATA eq <<END;
27389 <a>
27390 <b><CDATA> </CDATA></b>
27391 </a>
27392 END
27393  
27394  
27395 ok $b->first->isBlankText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27396  
27397  
27398  
27399 =head2 isAllBlankText($node, @context)
27400  
27401 Return the specified B<$node> if the specified B<$node>, optionally in the specified context, does not contain anything or if it does contain something it is all white space else return B<undef>. See also: L<bitsNodeTextBlank|/bitsNodeTextBlank>
27402  
27403 Parameter Description
27404 1 $node Node to test
27405 2 @context Optional context
27406  
27407 Use the optional B<@context> parameter to test the context of the specified
27408 B<$node> as understood by method L<at|/at>. If the context is supplied and
27409 B<$node> is not in this context then this method returns B<undef> immediately.
27410  
27411  
27412  
27413 B<Example:>
27414  
27415  
27416 {my $a = Data::Edit::Xml::new(<<END);
27417 <a>
27418 <b>
27419 <c>
27420 <z/>
27421 </c>
27422 </b>
27423 <d/>
27424 </a>
27425 END
27426  
27427 $a->by(sub{$_->replaceWithBlank(qw(z))});
27428  
27429 my ($b, $c, $d) = $a->firstBy(qw(b c d));
27430  
27431  
27432 ok $c->isAllBlankText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27433  
27434  
27435  
27436 ok $c->isAllBlankText(qw(c b a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27437  
27438  
27439  
27440 ok !$c->isAllBlankText(qw(c a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27441  
27442  
27443  
27444 =head2 isOnlyChildBlankText($node, @context)
27445  
27446 Return the specified B<$node> if it is a blank text node and an only child else return B<undef>.
27447  
27448 Parameter Description
27449 1 $node Node to test
27450 2 @context Optional context
27451  
27452 Use the optional B<@context> parameter to test the context of the specified
27453 B<$node> as understood by method L<at|/at>. If the context is supplied and
27454 B<$node> is not in this context then this method returns B<undef> immediately.
27455  
27456  
27457  
27458 B<Example:>
27459  
27460  
27461 if (1)
27462 {my $a = Data::Edit::Xml::new(q(<a>aaaa</a>));
27463 $a->first->text = q( );
27464 ok $a->prettyStringCDATA eq qq(<a><CDATA> </CDATA></a>
27465 );
27466  
27467 ok $a->first->isOnlyChildBlankText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27468  
27469  
27470 ok !$a->isOnlyChildBlankText; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27471  
27472 }
27473  
27474 if (1)
27475 {my $a = Data::Edit::Xml::new(q(<a/>));
27476 my $b = $a->new(q(<b/>));
27477 ok -p $a eq qq(<a/>
27478 );
27479 ok -p $b eq qq(<b/>
27480 );
27481 }
27482  
27483  
27484 =head2 bitsNodeTextBlank($node)
27485  
27486 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.
27487  
27488 Parameter Description
27489 1 $node Node to test.
27490  
27491 B<Example:>
27492  
27493  
27494 ok $x->prettyStringCDATA eq <<END;
27495 <a>
27496 <b>
27497 <C/>
27498 </b>
27499 <c>
27500 <D/>
27501 <CDATA>
27502 E
27503 </CDATA>
27504 </c>
27505 <d>
27506 <F/>
27507 <CDATA> </CDATA>
27508 <H/>
27509 </d>
27510 <e/>
27511 </a>
27512 END
27513  
27514 ok '100' eq -B $x;
27515  
27516 ok '100' eq -B $x->go(q(b));
27517  
27518 ok '110' eq -B $x->go(q(c));
27519  
27520 ok '111' eq -B $x->go(q(d));
27521  
27522 ok !-B $x->go(qw(e));
27523  
27524  
27525 =head1 Number
27526  
27527 Number the nodes of a parse tree so that they can be easily retrieved by number - either by a person reading the source L<Xml|https://en.wikipedia.org/wiki/XML> or programmatically.
27528  
27529 =head2 findByNumber($node, $number)
27530  
27531 Find the node with the specified number as made visible by L<prettyStringNumbered|/prettyStringNumbered> in the L<parse|/parse> tree containing the specified B<$node> and return the found node or B<undef> if no such node exists.
27532  
27533 Parameter Description
27534 1 $node Node in the parse tree to search
27535 2 $number Number of the node required.
27536  
27537 B<Example:>
27538  
27539  
27540 if (1)
27541 {my $a = Data::Edit::Xml::new(<<END);
27542 <a><b><c/></b><d><e/></d></a>
27543 END
27544  
27545 $a->numberTree;
27546 ok -z $a eq <<END;
27547 <a id="1">
27548 <b id="2">
27549 <c id="3"/>
27550 </b>
27551 <d id="4">
27552 <e id="5"/>
27553 </d>
27554 </a>
27555 END
27556  
27557 ok -t $a->findByNumber_4 eq q(d);
27558 ok $a->findByNumber_3__up__number == 2;
27559 }
27560  
27561 $a->numberTree;
27562  
27563 ok $a->prettyStringNumbered eq <<END;
27564 <a id="1">
27565 <b id="2">
27566 <A id="3"/>
27567 <B id="4"/>
27568 </b>
27569 <c id="5">
27570 <C id="6"/>
27571 <D id="7"/>
27572 </c>
27573 </a>
27574 END
27575  
27576  
27577 ok q(D) eq -t $a->findByNumber(7); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27578  
27579  
27580  
27581 =head2 findByNumbers($node, @numbers)
27582  
27583 Find the nodes with the specified numbers as made visible by L<prettyStringNumbered|/prettyStringNumbered> in the L<parse|/parse> tree containing the specified B<$node> and return the found nodes in a list with B<undef> for nodes that do not exist.
27584  
27585 Parameter Description
27586 1 $node Node in the parse tree to search
27587 2 @numbers Numbers of the nodes required.
27588  
27589 B<Example:>
27590  
27591  
27592 $a->numberTree;
27593  
27594 ok $a->prettyStringNumbered eq <<END;
27595 <a id="1">
27596 <b id="2">
27597 <A id="3"/>
27598 <B id="4"/>
27599 </b>
27600 <c id="5">
27601 <C id="6"/>
27602 <D id="7"/>
27603 </c>
27604 </a>
27605 END
27606  
27607  
27608 is_deeply [map {-t $_} $a->findByNumbers(1..3)], [qw(a b A)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27609  
27610  
27611  
27612 =head2 numberTree($node)
27613  
27614 Number the nodes in a L<parse|/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 L<prettyStringNumbered|/prettyStringNumbered>. Nodes can be found using L<findByNumber|/findByNumber>. This method differs from L<forestNumberTrees|/forestNumberTrees> in that avoids overwriting the B<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 L<prettyStringNumbered|/prettyStringNumbered>.
27615  
27616 Parameter Description
27617 1 $node Node
27618  
27619 B<Example:>
27620  
27621  
27622  
27623 $a->numberTree; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27624  
27625  
27626 ok -z $a eq <<END;
27627 <a id="1">
27628 <b id="2">
27629 <c id="42" match="mm"/>
27630 </b>
27631 <d id="4">
27632 <e id="5"/>
27633 </d>
27634 </a>
27635 END
27636  
27637 if (1)
27638 {my $a = Data::Edit::Xml::new(<<END);
27639 <a><b><c/></b><d><e/></d></a>
27640 END
27641  
27642  
27643 $a->numberTree; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27644  
27645 ok -z $a eq <<END;
27646 <a id="1">
27647 <b id="2">
27648 <c id="3"/>
27649 </b>
27650 <d id="4">
27651 <e id="5"/>
27652 </d>
27653 </a>
27654 END
27655  
27656 ok -t $a->findByNumber_4 eq q(d);
27657 ok $a->findByNumber_3__up__number == 2;
27658 }
27659  
27660  
27661 =head2 indexIds($node)
27662  
27663 Return a map of the ids at and below the specified B<$node>.
27664  
27665 Parameter Description
27666 1 $node Node
27667  
27668 B<Example:>
27669  
27670  
27671 {my $a = Data::Edit::Xml::new(<<END);
27672 <a id="A">
27673 <b id="B">
27674 <c id="C"/>
27675 <d id="D">
27676 <e id="E"/>
27677 <f id="F"/>
27678 </d>
27679 </b>
27680 </a>
27681 END
27682  
27683  
27684 my $i = $a->indexIds; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27685  
27686  
27687 ok $i->{C}->tag eq q(c);
27688  
27689 ok $i->{E}->tag eq q(e);
27690  
27691  
27692 =head2 numberTreesJustIds($node, $prefix)
27693  
27694 Number the ids of the nodes in a L<parse|/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 L<prettyStringNumbered()|/prettyStringNumbered>. This method differs from L<numberTree|/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 L<parse|/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 L<findByNumber|/findByNumber>. Returns the specified B<$node>.
27695  
27696 Parameter Description
27697 1 $node Node
27698 2 $prefix Prefix for each id at and under the specified B<$node>
27699  
27700 B<Example:>
27701  
27702  
27703 {my $a = Data::Edit::Xml::new(<<END);
27704 <a>A
27705 <b id="bb">B
27706 <c/>
27707 <d>D
27708 <e id="ee"/>
27709 E
27710 <f/>
27711 F
27712 </d>
27713 G
27714 </b>
27715 H
27716 </a>
27717 END
27718  
27719  
27720 $a->numberTreesJustIds(q(T)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27721  
27722  
27723 my $A = Data::Edit::Xml::new(<<END);
27724 <a id="T1">A
27725 <b id="bb">B
27726 <c id="T2"/>
27727 <d id="T3">D
27728 <e id="ee"/>
27729 E
27730 <f id="T4"/>
27731 F
27732 </d>
27733 G
27734 </b>
27735 H
27736 </a>
27737 END
27738  
27739 ok -p $a eq -p $A;
27740  
27741  
27742 =head1 Forest Numbers
27743  
27744 Number the nodes of several parse trees so that they can be easily retrieved by forest number - either by a person reading the source L<Xml|https://en.wikipedia.org/wiki/XML> or programmatically.
27745  
27746 =head2 forestNumberTrees($node, $prefix)
27747  
27748 Number the ids of the nodes in a L<parse|/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 L<prettyString|/prettyString>. This method differs from L<numberTree|/numberTree> in that only non text nodes are numbered and nodes with existing B<id=> attributes have the value of their B<id=> attribute transferred to a L<label|/Labels>. 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 L<parse|/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 L<findByForestNumber|/findByForestNumber>. Returns the specified B<$node>.
27749  
27750 Parameter Description
27751 1 $node Node in parse tree to be numbered
27752 2 $prefix Tree number
27753  
27754 B<Example:>
27755  
27756  
27757 {my $a = Data::Edit::Xml::new(<<END);
27758 <a>
27759 <b id="b">
27760 <c/>
27761 </b>
27762 <b id="B">
27763 <d/>
27764 <e/>
27765 </b>
27766 </a>
27767 END
27768  
27769 my $e = $a->go(qw(b -1 e));
27770  
27771  
27772 $e->forestNumberTrees(1); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27773  
27774  
27775 ok -p $a eq <<END;
27776 <a id="1_1">
27777 <b id="1_2">
27778 <c id="1_3"/>
27779 </b>
27780 <b id="1_4">
27781 <d id="1_5"/>
27782 <e id="1_6"/>
27783 </b>
27784 </a>
27785 END
27786  
27787  
27788 =head2 findByForestNumber($node, $tree, $id)
27789  
27790 Find the node with the specified L<forest number|/forestNumberTrees> as made visible on the id attribute by L<prettyStringNumbered|/prettyStringNumbered> in the L<parse|/parse> tree containing the specified B<$node> and return the found node or B<undef> if no such node exists.
27791  
27792 Parameter Description
27793 1 $node Node in the parse tree to search
27794 2 $tree Forest number
27795 3 $id Id number of the node required.
27796  
27797 B<Example:>
27798  
27799  
27800 ok -p $a eq <<END;
27801 <a id="1_1">
27802 <b id="1_2">
27803 <c id="1_3"/>
27804 </b>
27805 <b id="1_4">
27806 <d id="1_5"/>
27807 <e id="1_6"/>
27808 </b>
27809 </a>
27810 END
27811  
27812  
27813 my $B = $e->findByForestNumber(1, 4); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27814  
27815  
27816 is_deeply [$B->getLabels], ["B"];
27817  
27818  
27819 =head1 Order
27820  
27821 Check the order and relative position of nodes in a parse tree.
27822  
27823 =head2 above($first, $second, @context)
27824  
27825 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 B<undef>
27826  
27827 Parameter Description
27828 1 $first First node
27829 2 $second Second node
27830 3 @context Optional context
27831  
27832 Use the optional B<@context> parameter to test the context of the specified
27833 B<$node> as understood by method L<at|/at>. If the context is supplied and
27834 B<$node> is not in this context then this method returns B<undef> immediately.
27835  
27836  
27837  
27838 B<Example:>
27839  
27840  
27841 my $x = Data::Edit::Xml::new(<<END);
27842 <a id='a1'>
27843 <b id='b1'>
27844 <c id='c1'/>
27845 <c id='c2'/>
27846 <d id='d1'>
27847 <e id='e1'/>
27848 </d>
27849 <c id='c3'/>
27850 <c id='c4'/>
27851 <d id='d2'>
27852 <e id='e2'/>
27853 </d>
27854 <c id='c5'/>
27855 <c id='c6'/>
27856 </b>
27857 </a>
27858 END
27859  
27860 ok $b->id eq 'b1';
27861  
27862 ok $e->id eq "e1";
27863  
27864 ok $E->id eq "e2";
27865  
27866  
27867 ok $b->above($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27868  
27869  
27870  
27871 ok !$E->above($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27872  
27873  
27874  
27875 =head2 abovePath($first, $second)
27876  
27877 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 B<()>.
27878  
27879 Parameter Description
27880 1 $first First node
27881 2 $second Second node
27882  
27883 B<Example:>
27884  
27885  
27886 my $x = Data::Edit::Xml::new(<<END);
27887 <a id='a1'>
27888 <b id='b1'>
27889 <c id='c1'/>
27890 <c id='c2'/>
27891 <d id='d1'>
27892 <e id='e1'/>
27893 </d>
27894 <c id='c3'/>
27895 <c id='c4'/>
27896 <d id='d2'>
27897 <e id='e2'/>
27898 </d>
27899 <c id='c5'/>
27900 <c id='c6'/>
27901 </b>
27902 </a>
27903 END
27904  
27905 my ($a, $b, $c, $d, $e) = $x->firstDown(@tags);
27906  
27907  
27908 is_deeply [$b, $d, $e], [$b->abovePath($e)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27909  
27910  
27911  
27912 is_deeply [], [$c->abovePath($d)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27913  
27914  
27915  
27916 =head2 below($first, $second, @context)
27917  
27918 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 B<undef>
27919  
27920 Parameter Description
27921 1 $first First node
27922 2 $second Second node
27923 3 @context Optional context
27924  
27925 Use the optional B<@context> parameter to test the context of the specified
27926 B<$node> as understood by method L<at|/at>. If the context is supplied and
27927 B<$node> is not in this context then this method returns B<undef> immediately.
27928  
27929  
27930  
27931 B<Example:>
27932  
27933  
27934 my $x = Data::Edit::Xml::new(<<END);
27935 <a id='a1'>
27936 <b id='b1'>
27937 <c id='c1'/>
27938 <c id='c2'/>
27939 <d id='d1'>
27940 <e id='e1'/>
27941 </d>
27942 <c id='c3'/>
27943 <c id='c4'/>
27944 <d id='d2'>
27945 <e id='e2'/>
27946 </d>
27947 <c id='c5'/>
27948 <c id='c6'/>
27949 </b>
27950 </a>
27951 END
27952  
27953 ok $d->id eq 'd1';
27954  
27955 ok $e->id eq "e1";
27956  
27957  
27958 ok !$d->below($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27959  
27960  
27961  
27962 =head2 belowPath($first, $second)
27963  
27964 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 B<()>.
27965  
27966 Parameter Description
27967 1 $first First node
27968 2 $second Second node
27969  
27970 B<Example:>
27971  
27972  
27973 my $x = Data::Edit::Xml::new(<<END);
27974 <a id='a1'>
27975 <b id='b1'>
27976 <c id='c1'/>
27977 <c id='c2'/>
27978 <d id='d1'>
27979 <e id='e1'/>
27980 </d>
27981 <c id='c3'/>
27982 <c id='c4'/>
27983 <d id='d2'>
27984 <e id='e2'/>
27985 </d>
27986 <c id='c5'/>
27987 <c id='c6'/>
27988 </b>
27989 </a>
27990 END
27991  
27992 my ($a, $b, $c, $d, $e) = $x->firstDown(@tags);
27993  
27994  
27995 is_deeply [$e, $d, $b], [$e->belowPath($b)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
27996  
27997  
27998  
27999 is_deeply [$c], [$c->belowPath($c)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28000  
28001  
28002  
28003 =head2 after($first, $second, @context)
28004  
28005 Return the first node if it occurs after the second node in the L<parse|/parse> tree optionally checking that the first node is in the specified context or else B<undef> if the node is L<above|/above>, L<below|/below> or L<before|/before> the target.
28006  
28007 Parameter Description
28008 1 $first First node
28009 2 $second Second node
28010 3 @context Optional context
28011  
28012 Use the optional B<@context> parameter to test the context of the specified
28013 B<$node> as understood by method L<at|/at>. If the context is supplied and
28014 B<$node> is not in this context then this method returns B<undef> immediately.
28015  
28016  
28017  
28018 B<Example:>
28019  
28020  
28021 my $x = Data::Edit::Xml::new(<<END);
28022 <a id='a1'>
28023 <b id='b1'>
28024 <c id='c1'/>
28025 <c id='c2'/>
28026 <d id='d1'>
28027 <e id='e1'/>
28028 </d>
28029 <c id='c3'/>
28030 <c id='c4'/>
28031 <d id='d2'>
28032 <e id='e2'/>
28033 </d>
28034 <c id='c5'/>
28035 <c id='c6'/>
28036 </b>
28037 </a>
28038 END
28039  
28040 ok $c->id eq 'c1';
28041  
28042 ok $e->id eq "e1";
28043  
28044  
28045 ok $e->after($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28046  
28047  
28048  
28049 =head2 before($first, $second, @context)
28050  
28051 Return the first node if it occurs before the second node in the L<parse|/parse> tree optionally checking that the first node is in the specified context or else B<undef> if the node is L<above|/above>, L<below|/below> or L<before|/before> the target.
28052  
28053 Parameter Description
28054 1 $first First node
28055 2 $second Second node
28056 3 @context Optional context
28057  
28058 Use the optional B<@context> parameter to test the context of the specified
28059 B<$node> as understood by method L<at|/at>. If the context is supplied and
28060 B<$node> is not in this context then this method returns B<undef> immediately.
28061  
28062  
28063  
28064 B<Example:>
28065  
28066  
28067 my $x = Data::Edit::Xml::new(<<END);
28068 <a id='a1'>
28069 <b id='b1'>
28070 <c id='c1'/>
28071 <c id='c2'/>
28072 <d id='d1'>
28073 <e id='e1'/>
28074 </d>
28075 <c id='c3'/>
28076 <c id='c4'/>
28077 <d id='d2'>
28078 <e id='e2'/>
28079 </d>
28080 <c id='c5'/>
28081 <c id='c6'/>
28082 </b>
28083 </a>
28084 END
28085  
28086 ok $e->id eq "e1";
28087  
28088 ok $E->id eq "e2";
28089  
28090  
28091 ok $e->before($E); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28092  
28093  
28094  
28095 =head2 disordered($node, @nodes)
28096  
28097 Return the first node that is out of the specified order when performing a pre-ordered traversal of the L<parse|/parse> tree.
28098  
28099 Parameter Description
28100 1 $node Node
28101 2 @nodes Following nodes.
28102  
28103 B<Example:>
28104  
28105  
28106 my $x = Data::Edit::Xml::new(<<END);
28107 <a id='a1'>
28108 <b id='b1'>
28109 <c id='c1'/>
28110 <c id='c2'/>
28111 <d id='d1'>
28112 <e id='e1'/>
28113 </d>
28114 <c id='c3'/>
28115 <c id='c4'/>
28116 <d id='d2'>
28117 <e id='e2'/>
28118 </d>
28119 <c id='c5'/>
28120 <c id='c6'/>
28121 </b>
28122 </a>
28123 END
28124  
28125 ok $b->id eq 'b1';
28126  
28127 ok $c->id eq 'c1';
28128  
28129 ok $d->id eq 'd1';
28130  
28131 ok $e->id eq "e1";
28132  
28133  
28134 ok $e->disordered($c )->id eq "c1"; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28135  
28136  
28137  
28138 ok $b->disordered($c, $e, $d)->id eq "d1"; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28139  
28140  
28141  
28142 ok !$c->disordered($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28143  
28144  
28145  
28146 =head2 commonAncestor($node, @nodes)
28147  
28148 Find the most recent common ancestor of the specified nodes or B<undef> if there is no common ancestor.
28149  
28150 Parameter Description
28151 1 $node Node
28152 2 @nodes @nodes
28153  
28154 B<Example:>
28155  
28156  
28157 ok -z $a eq <<END;
28158 <a id="1">
28159 <b id="2">
28160 <c id="3">
28161 <e id="4"/>
28162 </c>
28163 <d id="5">
28164 <e id="6"/>
28165 </d>
28166 <c id="7">
28167 <d id="8">
28168 <e id="9"/>
28169 </d>
28170 </c>
28171 <d id="10">
28172 <e id="11"/>
28173 </d>
28174 <c id="12">
28175 <d id="13">
28176 <e id="14"/>
28177 </d>
28178 </c>
28179 </b>
28180 </a>
28181 END
28182  
28183 {my ($b, $e, @n) = $a->findByNumbers(2, 4, 6, 9);
28184  
28185  
28186 ok $e == $e->commonAncestor; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28187  
28188  
28189  
28190 ok $e == $e->commonAncestor($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28191  
28192  
28193  
28194 ok $b == $e->commonAncestor($b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28195  
28196  
28197  
28198 ok $b == $e->commonAncestor(@n); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28199  
28200  
28201  
28202 =head2 commonAdjacentAncestors($first, $second)
28203  
28204 Given two nodes, find a pair of adjacent ancestral siblings if such a pair exists else return B<()>.
28205  
28206 Parameter Description
28207 1 $first First node
28208 2 $second Second node
28209  
28210 B<Example:>
28211  
28212  
28213 {my $a = Data::Edit::Xml::new(<<END);
28214 <a>
28215 <b>
28216 <c>
28217 <d/>
28218 </c>
28219 </b>
28220 <b>
28221 <c/>
28222 </b>
28223 <e>
28224 <f/>
28225 </e>
28226 </a>
28227 END
28228  
28229 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
28230  
28231  
28232 is_deeply [$d->commonAdjacentAncestors($C)], [$b, $B]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28233  
28234  
28235  
28236 =head2 ordered($node, @nodes)
28237  
28238 Return the first node if the specified nodes are all in order when performing a pre-ordered traversal of the L<parse|/parse> tree else return B<undef>.
28239  
28240 Parameter Description
28241 1 $node Node
28242 2 @nodes Following nodes.
28243  
28244 B<Example:>
28245  
28246  
28247 my $x = Data::Edit::Xml::new(<<END);
28248 <a id='a1'>
28249 <b id='b1'>
28250 <c id='c1'/>
28251 <c id='c2'/>
28252 <d id='d1'>
28253 <e id='e1'/>
28254 </d>
28255 <c id='c3'/>
28256 <c id='c4'/>
28257 <d id='d2'>
28258 <e id='e2'/>
28259 </d>
28260 <c id='c5'/>
28261 <c id='c6'/>
28262 </b>
28263 </a>
28264 END
28265  
28266 ok $e->id eq "e1";
28267  
28268 ok $E->id eq "e2";
28269  
28270  
28271 ok $e->ordered($E); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28272  
28273  
28274  
28275 ok !$E->ordered($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28276  
28277  
28278  
28279 ok $e->ordered($e); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28280  
28281  
28282  
28283 ok $e->ordered; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28284  
28285  
28286  
28287 =head1 Patching
28288  
28289 Analyze two similar L<parse|/parse> trees and create a patch that transforms the first L<parse|/parse> tree into the second as long as each tree has the same tag and id structure with each id being unique.
28290  
28291 =head2 createPatch($a, $A)
28292  
28293 Create a patch that moves the source L<parse|/parse> tree to the target L<parse|/parse> tree node as long as they have the same tag and id structure with each id being unique.
28294  
28295 Parameter Description
28296 1 $a Source parse tree
28297 2 $A Target parse tree
28298  
28299 B<Example:>
28300  
28301  
28302 {my $a = Data::Edit::Xml::new(<<END);
28303 <a>Aaaaa
28304 <b b1="b1" b2="b2">Bbbbb
28305 <c c1="c1" />Ccccc
28306 <d d1="d1" >Ddddd
28307 <e e1="e1" />
28308 Eeeee
28309 <f f1="f1" />
28310 Fffff
28311 </d>
28312 Ggggg
28313 </b>
28314 Hhhhhh
28315 </a>
28316 END
28317  
28318 my $A = Data::Edit::Xml::new(<<END);
28319 <a>AaaAaaA
28320 <b b1="b1" b3="B3">BbbBbbB
28321 <c c1="C1" />Ccccc
28322 <d d2="D2" >DddDddD
28323 <e e3="E3" />
28324 EeeEeeE
28325 <f f1="F1" />
28326 FffFffF
28327 </d>
28328 GggGggG
28329 </b>
28330 Hhhhhh
28331 </a>
28332 END
28333  
28334 $a->numberTreesJustIds(q(a));
28335  
28336 $A->numberTreesJustIds(q(a));
28337  
28338  
28339 my $patches = $a->createPatch($A); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28340  
28341  
28342 $patches->install($a);
28343  
28344 ok !$a->diff ($A);
28345  
28346 ok $a->equals($A);
28347  
28348  
28349 =head2 Data::Edit::Xml::Patch::install($patches, $a)
28350  
28351 Replay a patch created by L<createPatch|/createPatch> against a L<parse|/parse> tree that has the same tag and id structure with each id being unique.
28352  
28353 Parameter Description
28354 1 $patches Patch
28355 2 $a Parse tree
28356  
28357 B<Example:>
28358  
28359  
28360 {my $a = Data::Edit::Xml::new(<<END);
28361 <a>Aaaaa
28362 <b b1="b1" b2="b2">Bbbbb
28363 <c c1="c1" />Ccccc
28364 <d d1="d1" >Ddddd
28365 <e e1="e1" />
28366 Eeeee
28367 <f f1="f1" />
28368 Fffff
28369 </d>
28370 Ggggg
28371 </b>
28372 Hhhhhh
28373 </a>
28374 END
28375  
28376 my $A = Data::Edit::Xml::new(<<END);
28377 <a>AaaAaaA
28378 <b b1="b1" b3="B3">BbbBbbB
28379 <c c1="C1" />Ccccc
28380 <d d2="D2" >DddDddD
28381 <e e3="E3" />
28382 EeeEeeE
28383 <f f1="F1" />
28384 FffFffF
28385 </d>
28386 GggGggG
28387 </b>
28388 Hhhhhh
28389 </a>
28390 END
28391  
28392 $a->numberTreesJustIds(q(a));
28393  
28394 $A->numberTreesJustIds(q(a));
28395  
28396 my $patches = $a->createPatch($A);
28397  
28398 $patches->install($a);
28399  
28400 ok !$a->diff ($A);
28401  
28402 ok $a->equals($A);
28403  
28404  
28405 =head1 Propogating
28406  
28407 Propagate parent node attributes through a parse tree.
28408  
28409 =head2 propagate($tree, $tag, @context)
28410  
28411 Propagate L<new attributes|/copyNewAttrs> from nodes that match the specified tag to all their child nodes, then L<unwrap|/unwrap> all the nodes that match the specified tag. Return the specified parse tree.
28412  
28413 Parameter Description
28414 1 $tree Parse tree
28415 2 $tag Tag of nodes whose attributes are to be propagated
28416 3 @context Optional context for parse tree
28417  
28418 Use the optional B<@context> parameter to test the context of the specified
28419 B<$node> as understood by method L<at|/at>. If the context is supplied and
28420 B<$node> is not in this context then this method returns B<undef> immediately.
28421  
28422  
28423  
28424 B<Example:>
28425  
28426  
28427 {my $a = Data::Edit::Xml::new(<<END);
28428 <a>
28429 <b b="B">
28430 <b c="C">
28431 <c/>
28432 <b d="D">
28433 <d/>
28434 <b e="E">
28435 <e/>
28436 </b>
28437 </b>
28438 </b>
28439 </b>
28440 </a>
28441 END
28442  
28443  
28444 $a->propagate(q(b)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28445  
28446  
28447 ok -p $a eq <<END;
28448 <a>
28449 <c b="B" c="C"/>
28450 <d b="B" c="C" d="D"/>
28451 <e b="B" c="C" d="D" e="E"/>
28452 </a>
28453 END
28454  
28455  
28456 =head1 Table of Contents
28457  
28458 Analyze and generate tables of contents.
28459  
28460 =head2 tocNumbers($node, @match)
28461  
28462 Table of Contents number the nodes in a L<parse|/parse> tree.
28463  
28464 Parameter Description
28465 1 $node Node
28466 2 @match Optional list of tags to descend into else all tags will be descended into
28467  
28468 B<Example:>
28469  
28470  
28471 ok $a->prettyStringNumbered eq <<END;
28472 <a id="1">
28473 <b id="2">
28474 <A id="3"/>
28475 <B id="4"/>
28476 </b>
28477 <c id="5">
28478 <C id="6"/>
28479 <D id="7"/>
28480 </c>
28481 </a>
28482 END
28483  
28484  
28485 my $t = $a->tocNumbers(); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28486  
28487  
28488 is_deeply {map {$_=>$t->{$_}->tag} keys %$t},
28489  
28490 {"1" =>"b",
28491  
28492 "1 1"=>"A",
28493  
28494 "1 2"=>"B",
28495  
28496 "2" =>"c",
28497  
28498 "2 1"=> "C",
28499  
28500 "2 2"=>"D"
28501  
28502 }
28503  
28504  
28505 =head1 Labels
28506  
28507 Label nodes so that they can be cross referenced and linked by L<Data::Edit::Xml::Lint>
28508  
28509 =head2 addLabels($node, @labels)
28510  
28511 Add the named labels to the specified B<$node> and return the number of labels added. Labels that are not L<defined|https://perldoc.perl.org/functions/defined.html> will be ignored.
28512  
28513 Parameter Description
28514 1 $node Node in parse tree
28515 2 @labels Names of labels to add.
28516  
28517 B<Example:>
28518  
28519  
28520 ok $x->stringReplacingIdsWithLabels eq '<a><b><c/></b></a>';
28521  
28522 my $b = $x->go(q(b));
28523  
28524 ok $b->countLabels == 0;
28525  
28526  
28527 $b->addLabels(1..2); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28528  
28529  
28530  
28531 $b->addLabels(3..4); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28532  
28533  
28534 ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c/></b></a>';
28535  
28536  
28537 =head2 countLabels($node)
28538  
28539 Return the count of the number of labels at a node.
28540  
28541 Parameter Description
28542 1 $node Node in parse tree.
28543  
28544 B<Example:>
28545  
28546  
28547 ok $x->stringReplacingIdsWithLabels eq '<a><b><c/></b></a>';
28548  
28549 my $b = $x->go(q(b));
28550  
28551  
28552 ok $b->countLabels == 0; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28553  
28554  
28555 $b->addLabels(1..2);
28556  
28557 $b->addLabels(3..4);
28558  
28559 ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c/></b></a>';
28560  
28561  
28562 ok $b->countLabels == 4; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28563  
28564  
28565  
28566 =head2 labelsInTree($tree)
28567  
28568 Return a hash of all the labels in a tree
28569  
28570 Parameter Description
28571 1 $tree Parse tree.
28572  
28573 B<Example:>
28574  
28575  
28576 ok -p (new $A->stringExtendingIdsWithLabels) eq <<END;
28577 <a id="aa, a, a5">
28578 <b id="bb, b, b2">
28579 <c id="cc, c, c1"/>
28580 </b>
28581 <b id="B, b4">
28582 <c id="C, c3"/>
28583 </b>
28584 </a>
28585 END
28586  
28587  
28588 is_deeply [sort keys %{$A->labelsInTree}], # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28589  
28590  
28591 ["B", "C", "a", "a5", "b", "b2", "b4", "c", "c1", "c3"];
28592  
28593  
28594 =head2 getLabels($node)
28595  
28596 Return the names of all the labels set on a node.
28597  
28598 Parameter Description
28599 1 $node Node in parse tree.
28600  
28601 B<Example:>
28602  
28603  
28604 ok $x->stringReplacingIdsWithLabels eq '<a><b><c/></b></a>';
28605  
28606 my $b = $x->go(q(b));
28607  
28608 ok $b->countLabels == 0;
28609  
28610 $b->addLabels(1..2);
28611  
28612 $b->addLabels(3..4);
28613  
28614 ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c/></b></a>';
28615  
28616  
28617 is_deeply [1..4], [$b->getLabels]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28618  
28619  
28620  
28621 =head2 deleteLabels($node, @labels)
28622  
28623 Delete the specified labels in the specified B<$node> or all labels if no labels have are specified and return that node.
28624  
28625 Parameter Description
28626 1 $node Node in parse tree
28627 2 @labels Names of the labels to be deleted
28628  
28629 B<Example:>
28630  
28631  
28632 ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c id="1, 2, 3, 4"/></b></a>';
28633  
28634  
28635 $b->deleteLabels(1,4) for 1..2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28636  
28637  
28638 ok $x->stringReplacingIdsWithLabels eq '<a><b id="2, 3"><c id="1, 2, 3, 4"/></b></a>';
28639  
28640  
28641 =head2 copyLabels($source, $target)
28642  
28643 Copy all the labels from the source node to the target node and return the source node.
28644  
28645 Parameter Description
28646 1 $source Source node
28647 2 $target Target node.
28648  
28649 B<Example:>
28650  
28651  
28652 ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c/></b></a>';
28653  
28654  
28655 $b->copyLabels($c) for 1..2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28656  
28657  
28658 ok $x->stringReplacingIdsWithLabels eq '<a><b id="1, 2, 3, 4"><c id="1, 2, 3, 4"/></b></a>';
28659  
28660  
28661 =head2 moveLabels($source, $target)
28662  
28663 Move all the labels from the source node to the target node and return the source node.
28664  
28665 Parameter Description
28666 1 $source Source node
28667 2 $target Target node.
28668  
28669 B<Example:>
28670  
28671  
28672 ok $x->stringReplacingIdsWithLabels eq '<a><b id="2, 3"><c id="1, 2, 3, 4"/></b></a>';
28673  
28674  
28675 $b->moveLabels($c) for 1..2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28676  
28677  
28678 ok $x->stringReplacingIdsWithLabels eq '<a><b><c id="1, 2, 3, 4"/></b></a>';
28679  
28680  
28681 =head2 copyLabelsAndIdsInTree($source, $target)
28682  
28683 Copy all the labels and ids in the source parse tree to the matching nodes in the target parse tree. Nodes are matched via L<path|/path>. Return the number of labels and ids copied.
28684  
28685 Parameter Description
28686 1 $source Source node
28687 2 $target Target node.
28688  
28689 B<Example:>
28690  
28691  
28692 ok -p (new $a->stringExtendingIdsWithLabels) eq <<END;
28693 <a id="a, a5">
28694 <b id="b, b2">
28695 <c id="c, c1"/>
28696 </b>
28697 <b id="B, b4">
28698 <c id="C, c3"/>
28699 </b>
28700 </a>
28701 END
28702  
28703 ok -p (new $A->stringExtendingIdsWithLabels) eq <<END;
28704 <a id="aa">
28705 <b id="bb">
28706 <c id="cc"/>
28707 </b>
28708 <b>
28709 <c/>
28710 </b>
28711 </a>
28712 END
28713  
28714  
28715 ok $a->copyLabelsAndIdsInTree($A) == 10; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28716  
28717  
28718 ok -p (new $A->stringExtendingIdsWithLabels) eq <<END;
28719 <a id="aa, a, a5">
28720 <b id="bb, b, b2">
28721 <c id="cc, c, c1"/>
28722 </b>
28723 <b id="B, b4">
28724 <c id="C, c3"/>
28725 </b>
28726 </a>
28727 END
28728  
28729  
28730 =head2 giveEveryIdAGuid($tree, $genGuid)
28731  
28732 Give a guid to every node in the specified B<$tree> that has an id attribute, saving any existing id attribute as a label, and return the count of the number of such replacements made.
28733  
28734 Parameter Description
28735 1 $tree Tree
28736 2 $genGuid A sub that accepts a number and a node and returns a new Guid each time it is called
28737  
28738 B<Example:>
28739  
28740  
28741 if (1)
28742 {my $a = Data::Edit::Xml::new(<<END);
28743 <a id="a">
28744 <b id="b">
28745 <c id="c"/>
28746 </b>
28747 <d/>
28748 </a>
28749 END
28750 my $n =0;
28751  
28752 $a->giveEveryIdAGuid(sub # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28753  
28754 {my ($n, $o) = @_;
28755 qq(GUID-$n)
28756 });
28757  
28758 ok -p $a eq <<END;
28759 <a id="GUID-3">
28760 <b id="GUID-2">
28761 <c id="GUID-1"/>
28762 </b>
28763 <d/>
28764 </a>
28765 END
28766  
28767 ok $a->stringReplacingIdsWithLabels eq q(<a id="a"><b id="b"><c id="c"/></b><d/></a>);
28768 ok $a->stringExtendingIdsWithLabels eq q(<a id="GUID-3, a"><b id="GUID-2, b"><c id="GUID-1, c"/></b><d/></a>);
28769  
28770 }
28771  
28772  
28773 =head2 createGuidId($node, @context)
28774  
28775 Create an id for the specified B<$node> in the optional B<@context> from the md5Sum of its content moving any existing id to the labels associated with the B<$node> and return the existing B<$node>.
28776  
28777 Parameter Description
28778 1 $node Node
28779 2 @context Optional context
28780  
28781 Use the optional B<@context> parameter to test the context of the specified
28782 B<$node> as understood by method L<at|/at>. If the context is supplied and
28783 B<$node> is not in this context then this method returns B<undef> immediately.
28784  
28785  
28786  
28787 B<Example:>
28788  
28789  
28790 my $a = Data::Edit::Xml::new(<<END);
28791 <a>
28792 <b>
28793 c
28794 </b>
28795 </a>
28796 END
28797  
28798  
28799 ok $a->createGuidId->id eq q(GUID-390bf05d-8f56-71cc-6a47-71834840d695); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
28800  
28801  
28802  
28803 =head1 Operators
28804  
28805 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.
28806  
28807 =head2 opString($node, $op)
28808  
28809 -A: L<printNode|/printNode>
28810  
28811 -B: L<bitsNodeTextBlank|/bitsNodeTextBlank>
28812  
28813 -b: L<isAllBlankText|/isAllBlankText>
28814  
28815 -C: L<stringContent|/stringContent>
28816  
28817 -c: L<context|/context>
28818  
28819 -d: L<depth|/depth>
28820  
28821 -e: L<prettyStringEnd|/prettyStringEnd>
28822  
28823 -f: L<first node|/first>
28824  
28825 -g: L<createGuidId|/createGuidId>
28826  
28827 -k: L<createGuidId|/createGuidId>
28828  
28829 -l: L<last node|/last>
28830  
28831 -M: L<stringAsMd5Sum|/stringAsMd5Sum>
28832  
28833 -O: L<contentAsTags2|/contentAsTags2>
28834  
28835 -o: L<contentAsTags|/contentAsTags>
28836  
28837 -p: L<prettyString|/prettyString>
28838  
28839 -R: L<requiredCleanup|/requiredCleanup>
28840  
28841 -r: L<stringTagsAndText|/stringTagsAndText>
28842  
28843 -S: L<printStack|/printStack>
28844  
28845 -s: L<string|/string>
28846  
28847 -T: L<isText|/isText>
28848  
28849 -t: L<tag|/tag>
28850  
28851 -u: L<unwrap|/unwrap>
28852  
28853 -W: L<id|/id>
28854  
28855 -w: L<stringQuoted|/stringQuoted>
28856  
28857 -X: L<prettyStringDitaHeaders|/prettyStringDitaHeaders>
28858  
28859 -x: L<cut|/cut>
28860  
28861 -z: L<prettyStringNumbered|/prettyStringNumbered>.
28862  
28863 Parameter Description
28864 1 $node Node
28865 2 $op Monadic operator.
28866  
28867 B<Example:>
28868  
28869  
28870 my $a = Data::Edit::Xml::new(<<END);
28871 <a>
28872 <b><c>ccc</c></b>
28873 <d><e>eee</e></d>
28874 </a>
28875 END
28876  
28877 my $a = Data::Edit::Xml::new(<<END);
28878 <a>
28879 <b>
28880 <c id="42" match="mm"/>
28881 </b>
28882 <d>
28883 <e/>
28884 </d>
28885 </a>
28886 END
28887  
28888 my ($c, $b, $e, $d) = $a->byList;
28889  
28890 ok $c->printNode eq q(c id="42" match="mm");
28891  
28892 ok -A $c eq q(c id="42" match="mm");
28893  
28894 ok -b $e;
28895  
28896 ok -c $e eq q(e d a);
28897  
28898 ok -f $b eq $c;
28899  
28900 ok -l $a eq $d;
28901  
28902 ok -O $a, q( b d );
28903  
28904 ok -o $a, q(b d);
28905  
28906 ok -w $a eq q('<a><b><c id="42" match="mm"/></b><d><e/></d></a>');
28907  
28908 ok -p $a eq <<END;
28909 <a>
28910 <b>
28911 <c id="42" match="mm"/>
28912 </b>
28913 <d>
28914 <e/>
28915 </d>
28916 </a>
28917 END
28918  
28919 ok -s $a eq '<a><b><c id="42" match="mm"/></b><d><e/></d></a>';
28920  
28921 ok -t $a eq 'a';
28922  
28923 $a->numberTree;
28924  
28925 ok -z $a eq <<END;
28926 <a id="1">
28927 <b id="2">
28928 <c id="42" match="mm"/>
28929 </b>
28930 <d id="4">
28931 <e id="5"/>
28932 </d>
28933 </a>
28934 END
28935  
28936 if (1)
28937 {my $a = Data::Edit::Xml::new(<<END);
28938 <concept/>
28939 END
28940  
28941 ok $a->ditaPrettyPrintWithHeaders eq <<END;
28942 <?xml version="1.0" encoding="UTF-8"?>
28943 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd" []>
28944 <concept/>
28945 END
28946  
28947 }
28948  
28949  
28950 =head2 opContents($node)
28951  
28952 @{} : nodes immediately below a node.
28953  
28954 Parameter Description
28955 1 $node Node.
28956  
28957 B<Example:>
28958  
28959  
28960 my $a = Data::Edit::Xml::new(<<END);
28961 <a>
28962 <b><c>ccc</c></b>
28963 <d><e>eee</e></d>
28964 </a>
28965 END
28966  
28967 my ($b, $d) = @$a;
28968  
28969 ok -c $b eq q(b a);
28970  
28971 my ($c) = @$b;
28972  
28973 ok -c $c eq q(c b a);
28974  
28975  
28976 =head2 opAt($node, $context)
28977  
28978 <= : Check that a node is in the context specified by the referenced array of words.
28979  
28980 Parameter Description
28981 1 $node Node
28982 2 $context Reference to array of words specifying the parents of the desired node.
28983  
28984 B<Example:>
28985  
28986  
28987 ok -p $a eq <<END;
28988 <a>
28989 <b>
28990 <c id="42" match="mm"/>
28991 </b>
28992 <d>
28993 <e/>
28994 </d>
28995 </a>
28996 END
28997  
28998 ok (($a >= [qw(d e)]) <= [qw(e d a)]);
28999  
29000  
29001 =head2 opNew($node, $text)
29002  
29003 ** : 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
29004  
29005 Parameter Description
29006 1 $node Node
29007 2 $text Name node of node to create or text of new text element
29008  
29009 B<Example:>
29010  
29011  
29012 my $a = Data::Edit::Xml::new("<a/>");
29013  
29014 my $b = $a ** q(b);
29015  
29016 ok -s $b eq "<b/>";
29017  
29018  
29019 =head2 opPutFirst($node, $text)
29020  
29021 >> : put a node or string first under a node and return the new node.
29022  
29023 Parameter Description
29024 1 $node Node
29025 2 $text Node or text to place first under the node.
29026  
29027 B<Example:>
29028  
29029  
29030 ok -p $a eq <<END;
29031 <a/>
29032 END
29033  
29034 my $f = $a >> qq(first);
29035  
29036 ok -p $a eq <<END;
29037 <a>
29038 <first/>
29039 </a>
29040 END
29041  
29042  
29043 =head2 opPutFirstAssign($node, $text)
29044  
29045 >>= : put a node or string first under a node.
29046  
29047 Parameter Description
29048 1 $node Node
29049 2 $text Node or text to place first under the node.
29050  
29051 B<Example:>
29052  
29053  
29054 ok -p $a eq <<END;
29055 <a/>
29056 END
29057  
29058 $a >>= qq(first);
29059  
29060 ok -p $a eq <<END;
29061 <a>
29062 <first/>
29063 </a>
29064 END
29065  
29066  
29067 =head2 opPutLast($node, $text)
29068  
29069 << : put a node or string last under a node and return the new node.
29070  
29071 Parameter Description
29072 1 $node Node
29073 2 $text Node or text to place last under the node.
29074  
29075 B<Example:>
29076  
29077  
29078 ok -p $a eq <<END;
29079 <a>
29080 <first/>
29081 </a>
29082 END
29083  
29084 my $l = $a << qq(last);
29085  
29086 ok -p $a eq <<END;
29087 <a>
29088 <first/>
29089 <last/>
29090 </a>
29091 END
29092  
29093  
29094 =head2 opPutLastAssign($node, $text)
29095  
29096 <<= : put a node or string last under a node.
29097  
29098 Parameter Description
29099 1 $node Node
29100 2 $text Node or text to place last under the node.
29101  
29102 B<Example:>
29103  
29104  
29105 ok -p $a eq <<END;
29106 <a>
29107 <first/>
29108 </a>
29109 END
29110  
29111 $a <<= qq(last);
29112  
29113 ok -p $a eq <<END;
29114 <a>
29115 <first/>
29116 <last/>
29117 </a>
29118 END
29119  
29120  
29121 =head2 opPutNext($node, $text)
29122  
29123 > + : put a node or string after the specified B<$node> and return the new node.
29124  
29125 Parameter Description
29126 1 $node Node
29127 2 $text Node or text to place after the first node.
29128  
29129 B<Example:>
29130  
29131  
29132 ok -p $a eq <<END;
29133 <a>
29134 <first/>
29135 <last/>
29136 </a>
29137 END
29138  
29139 $f += qq(next);
29140  
29141 ok -p $a eq <<END;
29142 <a>
29143 <first/>
29144 <next/>
29145 <last/>
29146 </a>
29147 END
29148  
29149  
29150 =head2 opPutNextAssign($node, $text)
29151  
29152 += : put a node or string after the specified B<$node>.
29153  
29154 Parameter Description
29155 1 $node Node
29156 2 $text Node or text to place after the first node.
29157  
29158 B<Example:>
29159  
29160  
29161 ok -p $a eq <<END;
29162 <a>
29163 <first/>
29164 <last/>
29165 </a>
29166 END
29167  
29168 my $f = -f $a;
29169  
29170 $f += qq(next);
29171  
29172 ok -p $a eq <<END;
29173 <a>
29174 <first/>
29175 <next/>
29176 <last/>
29177 </a>
29178 END
29179  
29180  
29181 =head2 opPutPrev($node, $text)
29182  
29183 < - : put a node or string before the specified B<$node> and return the new node.
29184  
29185 Parameter Description
29186 1 $node Node
29187 2 $text Node or text to place before the first node.
29188  
29189 B<Example:>
29190  
29191  
29192 ok -p $a eq <<END;
29193 <a>
29194 <first/>
29195 <next/>
29196 <last/>
29197 </a>
29198 END
29199  
29200 $l -= qq(prev);
29201  
29202 ok -p $a eq <<END;
29203 <a>
29204 <first/>
29205 <next/>
29206 <prev/>
29207 <last/>
29208 </a>
29209 END
29210  
29211  
29212 =head2 opPutPrevAssign($node, $text)
29213  
29214 -= : put a node or string before the specified B<$node>,
29215  
29216 Parameter Description
29217 1 $node Node
29218 2 $text Node or text to place before the first node.
29219  
29220 B<Example:>
29221  
29222  
29223 ok -p $a eq <<END;
29224 <a>
29225 <first/>
29226 <next/>
29227 <last/>
29228 </a>
29229 END
29230  
29231 my $l = -l $a;
29232  
29233 $l -= qq(prev);
29234  
29235 ok -p $a eq <<END;
29236 <a>
29237 <first/>
29238 <next/>
29239 <prev/>
29240 <last/>
29241 </a>
29242 END
29243  
29244  
29245 =head2 opBy($node, $code)
29246  
29247 x= : Traverse a L<parse|/parse> tree in post-order.
29248  
29249 Parameter Description
29250 1 $node Parse tree
29251 2 $code Code to execute against each node.
29252  
29253 B<Example:>
29254  
29255  
29256 ok -p $a eq <<END;
29257 <a>
29258 <b>
29259 <c id="42" match="mm"/>
29260 </b>
29261 <d>
29262 <e/>
29263 </d>
29264 </a>
29265 END
29266  
29267 {my $s; $a x= sub{$s .= -t $_}; ok $s eq "cbeda"
29268  
29269  
29270 =head2 opGo($node, $go)
29271  
29272 >= : 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.
29273  
29274 Parameter Description
29275 1 $node Node
29276 2 $go Reference to an array of search parameters.
29277  
29278 B<Example:>
29279  
29280  
29281 ok -p $a eq <<END;
29282 <a>
29283 <b>
29284 <c id="42" match="mm"/>
29285 </b>
29286 <d>
29287 <e/>
29288 </d>
29289 </a>
29290 END
29291  
29292 ok (($a >= [qw(d e)]) <= [qw(e d a)]);
29293  
29294  
29295 =head2 opAttr($node, $attr)
29296  
29297 % : Get the value of an attribute of the specified B<$node>.
29298  
29299 Parameter Description
29300 1 $node Node
29301 2 $attr Reference to an array of words and numbers specifying the node to search for.
29302  
29303 B<Example:>
29304  
29305  
29306 my $a = Data::Edit::Xml::new('<a number="1"/>');
29307  
29308 ok $a % qq(number) == 1;
29309  
29310  
29311 =head2 opWrapWith($node, $tag)
29312  
29313 / : Wrap node with a tag, returning the wrapping node.
29314  
29315 Parameter Description
29316 1 $node Node
29317 2 $tag Tag.
29318  
29319 B<Example:>
29320  
29321  
29322 my $c = Data::Edit::Xml::new("<c/>");
29323  
29324 my $b = $c / qq(b);
29325  
29326 ok -s $b eq "<b><c/></b>";
29327  
29328 my $a = $b / qq(a);
29329  
29330 ok -s $a eq "<a><b><c/></b></a>";
29331  
29332  
29333 =head2 opWrapContentWith($node, $tag)
29334  
29335 * : Wrap content with a tag, returning the wrapping node.
29336  
29337 Parameter Description
29338 1 $node Node
29339 2 $tag Tag.
29340  
29341 B<Example:>
29342  
29343  
29344 {my $a = Data::Edit::Xml::new(<<END);
29345 <a>
29346 <b>
29347 <c/>
29348 <d/>
29349 </b>
29350 </a>
29351 END
29352  
29353 my ($c, $d, $b) = $a->byList;
29354  
29355 $b *= q(B);
29356  
29357 ok -p $a eq <<END;
29358 <a>
29359 <b>
29360 <B>
29361 <c/>
29362 <d/>
29363 </B>
29364 </b>
29365 </a>
29366 END
29367  
29368  
29369 =head2 opCut($node)
29370  
29371 -- : Cut out a node.
29372  
29373 Parameter Description
29374 1 $node Node.
29375  
29376 B<Example:>
29377  
29378  
29379 my $x = Data::Edit::Xml::new(<<END);
29380 <a>
29381 <b><c/></b>
29382 </a>
29383 END
29384  
29385 my $b = $x >= qq(b);
29386  
29387 --$b;
29388  
29389 ok -s $x eq "<a/>";
29390  
29391 ok -s $b eq "<b><c/></b>";
29392  
29393  
29394 =head2 opUnwrap($node)
29395  
29396 ++ : Unwrap a node.
29397  
29398 Parameter Description
29399 1 $node Node.
29400  
29401 B<Example:>
29402  
29403  
29404 {my $a = Data::Edit::Xml::new(<<END);
29405 <a>
29406 <b>
29407 <c/>
29408 <d/>
29409 </b>
29410 </a>
29411 END
29412  
29413 my ($c, $d, $b) = $a->byList;
29414  
29415 $b++;
29416  
29417 ok -p $a eq <<END;
29418 <a>
29419 <c/>
29420 <d/>
29421 </a>
29422 END
29423  
29424  
29425 =head1 Reuse
29426  
29427 Identify common components that can be reused
29428  
29429 =head2 subMd5Tree($node)
29430  
29431 Return the L<md5 sum|https://en.wikipedia.org/wiki/MD5> of the L<stringContent> of the parse tree.
29432  
29433 Parameter Description
29434 1 $node Node
29435  
29436 B<Example:>
29437  
29438  
29439 my $a = Data::Edit::Xml::new(<<END);
29440 <a>
29441 <b>bb</b>
29442 <b><c>bb</c></b>
29443 <d>dd</d>
29444 <d>dd</d>
29445 </a>
29446 END
29447  
29448  
29449 is_deeply [$a->first->subMd5Tree], [q(21ad0bd836b90d08f4cf640b4c298e7c), q(bb)]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29450  
29451  
29452 is_deeply subMd5($a, map {$_=>1} qw(b c)),
29453 {b => {"21ad0bd836b90d08f4cf640b4c298e7c" => { bb => 1},
29454 "95c1bde7f88ced04c1b1fbcab120ed96" => {"<c>bb</c>" => 1},
29455 },
29456 c => {"21ad0bd836b90d08f4cf640b4c298e7c" => { bb => 1}},
29457 };
29458 # owf(q(/home/phil/z/z/z/out.xml), dump(subMd5($a, map{$_=>1} qw(b c))));
29459  
29460  
29461 =head2 subMd5($node, %tags)
29462  
29463 Return a hash {L<md5 sum|https://en.wikipedia.org/wiki/MD5> of parse tree}{string representation of sub tree}++ to locate common parse trees under B<$node> that could be included via a conref. L<md5 sum|https://en.wikipedia.org/wiki/MD5>s are only calculated for nodes whose tags match the keys of the B<$tags> hash that have truthful values. The attributes of the root node of each sub tree are ignored in the computation as they can be supplied by the conreffing element.
29464  
29465 Parameter Description
29466 1 $node Node
29467 2 %tags Hash of acceptable tags.
29468  
29469 B<Example:>
29470  
29471  
29472 my $a = Data::Edit::Xml::new(<<END);
29473 <a>
29474 <b>bb</b>
29475 <b><c>bb</c></b>
29476 <d>dd</d>
29477 <d>dd</d>
29478 </a>
29479 END
29480  
29481 is_deeply [$a->first->subMd5Tree], [q(21ad0bd836b90d08f4cf640b4c298e7c), q(bb)];
29482  
29483  
29484 is_deeply subMd5($a, map {$_=>1} qw(b c)), # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29485  
29486 {b => {"21ad0bd836b90d08f4cf640b4c298e7c" => { bb => 1},
29487 "95c1bde7f88ced04c1b1fbcab120ed96" => {"<c>bb</c>" => 1},
29488 },
29489 c => {"21ad0bd836b90d08f4cf640b4c298e7c" => { bb => 1}},
29490 };
29491  
29492 # owf(q(/home/phil/z/z/z/out.xml), dump(subMd5($a, map{$_=>1} qw(b c)))); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29493  
29494  
29495  
29496 =head1 Statistics
29497  
29498 Statistics describing the L<parse|/parse> tree.
29499  
29500 =head2 count($node, @names)
29501  
29502 Return the count of the number of instances of the specified tags under the specified B<$node>, either by tag in array context or in total in scalar context.
29503  
29504 Parameter Description
29505 1 $node Node
29506 2 @names Possible tags immediately under the node.
29507  
29508 B<Example:>
29509  
29510  
29511 my $x = Data::Edit::Xml::new(<<END);
29512 <a>
29513  
29514 </a>
29515 END
29516  
29517  
29518 ok $x->count == 0; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29519  
29520  
29521  
29522 =head2 countTags($node)
29523  
29524 Count the number of tags in a L<parse|/parse> tree.
29525  
29526 Parameter Description
29527 1 $node Parse tree.
29528  
29529 B<Example:>
29530  
29531  
29532 ok -p $a eq <<END;
29533 <a id="aa">
29534 <b id="bb">
29535 <c id="cc"/>
29536 </b>
29537 </a>
29538 END
29539  
29540  
29541 ok $a->countTags == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29542  
29543  
29544  
29545 =head2 countTagNames($node, @exclude)
29546  
29547 Return a reference to a hash showing the number of instances of each tag on and below the specified B<$node> excluding any tags named in B<@exclude>.
29548  
29549 Parameter Description
29550 1 $node Node
29551 2 @exclude Tags to exclude from the count
29552  
29553 B<Example:>
29554  
29555  
29556 my $x = Data::Edit::Xml::new(<<END);
29557 <a A="A1" B="B1" C="C1">
29558 <b B="B1" C="C1">
29559 <c C="C1">
29560 </c>
29561 <c/>
29562 </b>
29563 <b B="B2">
29564 <c C="C2"/>
29565 </b>
29566 </a>
29567 END
29568  
29569  
29570 is_deeply $x->countTagNames, # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29571  
29572 {a => 1, b => 2, c => 3};
29573  
29574 is_deeply $x->countAttrNames,
29575 {A => 1, B => 3, C => 4};
29576  
29577 is_deeply $x->countAttrValues,
29578 {A1 => 1, B1 => 2, B2 => 1, C1 => 3, C2 => 1};
29579  
29580 is_deeply $x->countAttrNamesAndValues,
29581 {A => {A1 => 1}, B => {B1 => 2, B2 => 1}, C => {C1 => 3, C2 => 1}};
29582  
29583  
29584 =head2 countNonEmptyTags($node, @exclude)
29585  
29586 Return a reference to a hash showing the number of instances of each non empty tag on and below the specified B<$node> excluding any tags named in B<@exclude>.
29587  
29588 Parameter Description
29589 1 $node Node
29590 2 @exclude Tags to exclude from the count
29591  
29592 B<Example:>
29593  
29594  
29595 my $a = Data::Edit::Xml::new(<<END);
29596 <a>
29597 <b>
29598 <c>
29599 <d/>
29600 </c>
29601 </b>
29602 </a>
29603 END
29604  
29605  
29606 is_deeply $a->countNonEmptyTags(qw(c)), {a=>1, b=>1}; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29607  
29608  
29609 is_deeply $a->go_b->countNonEmptyTags, {b=>1, c=>1}; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29610  
29611  
29612  
29613 =head2 countTexts($node)
29614  
29615 Return a reference to a hash showing the incidence of texts on and below the specified B<$node>.
29616  
29617 Parameter Description
29618 1 $node Node
29619  
29620 B<Example:>
29621  
29622  
29623 my $a = Data::Edit::Xml::new(<<END);
29624 <concept>
29625 <title/>
29626 <conbody/>
29627 </concept>
29628 END
29629  
29630  
29631 is_deeply $a->countTexts, {}; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29632  
29633  
29634  
29635 =head2 countAttrNames($node, $count)
29636  
29637 Return a reference to a hash showing the number of instances of each attribute on and below the specified B<$node>.
29638  
29639 Parameter Description
29640 1 $node Node
29641 2 $count Attribute count so far
29642  
29643 B<Example:>
29644  
29645  
29646 my $x = Data::Edit::Xml::new(<<END);
29647 <a A="A1" B="B1" C="C1">
29648 <b B="B1" C="C1">
29649 <c C="C1">
29650 </c>
29651 <c/>
29652 </b>
29653 <b B="B2">
29654 <c C="C2"/>
29655 </b>
29656 </a>
29657 END
29658  
29659 is_deeply $x->countTagNames,
29660 {a => 1, b => 2, c => 3};
29661  
29662  
29663 is_deeply $x->countAttrNames, # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29664  
29665 {A => 1, B => 3, C => 4};
29666  
29667 is_deeply $x->countAttrValues,
29668 {A1 => 1, B1 => 2, B2 => 1, C1 => 3, C2 => 1};
29669  
29670 is_deeply $x->countAttrNamesAndValues,
29671 {A => {A1 => 1}, B => {B1 => 2, B2 => 1}, C => {C1 => 3, C2 => 1}};
29672  
29673  
29674 =head2 countAttrNamesOnTagExcluding($node, @attr)
29675  
29676 Count the number of attributes owned by the specified B<$node> that are not in the specified list.
29677  
29678 Parameter Description
29679 1 $node Node
29680 2 @attr Attributes to ignore
29681  
29682 B<Example:>
29683  
29684  
29685 {my $a = Data::Edit::Xml::new(q(<a a="1" b="2" c="3" d="4" e="5"/>));
29686  
29687  
29688 =head2 countAttrValues($node, $count)
29689  
29690 Return a reference to a hash showing the number of instances of each attribute value on and below the specified B<$node>.
29691  
29692 Parameter Description
29693 1 $node Node
29694 2 $count Count of attributes so far.
29695  
29696 B<Example:>
29697  
29698  
29699 my $x = Data::Edit::Xml::new(<<END);
29700 <a A="A1" B="B1" C="C1">
29701 <b B="B1" C="C1">
29702 <c C="C1">
29703 </c>
29704 <c/>
29705 </b>
29706 <b B="B2">
29707 <c C="C2"/>
29708 </b>
29709 </a>
29710 END
29711  
29712 is_deeply $x->countTagNames,
29713 {a => 1, b => 2, c => 3};
29714  
29715 is_deeply $x->countAttrNames,
29716 {A => 1, B => 3, C => 4};
29717  
29718  
29719 is_deeply $x->countAttrValues, # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29720  
29721 {A1 => 1, B1 => 2, B2 => 1, C1 => 3, C2 => 1};
29722  
29723 is_deeply $x->countAttrNamesAndValues,
29724 {A => {A1 => 1}, B => {B1 => 2, B2 => 1}, C => {C1 => 3, C2 => 1}};
29725  
29726  
29727 =head2 countAttrNamesAndValues($node, $count)
29728  
29729 Return a reference to a hash showing the number of instances of each attribute name and value on and below the specified B<$node>.
29730  
29731 Parameter Description
29732 1 $node Node
29733 2 $count Count of attributes so far.
29734  
29735 B<Example:>
29736  
29737  
29738 my $x = Data::Edit::Xml::new(<<END);
29739 <a A="A1" B="B1" C="C1">
29740 <b B="B1" C="C1">
29741 <c C="C1">
29742 </c>
29743 <c/>
29744 </b>
29745 <b B="B2">
29746 <c C="C2"/>
29747 </b>
29748 </a>
29749 END
29750  
29751 is_deeply $x->countTagNames,
29752 {a => 1, b => 2, c => 3};
29753  
29754 is_deeply $x->countAttrNames,
29755 {A => 1, B => 3, C => 4};
29756  
29757 is_deeply $x->countAttrValues,
29758 {A1 => 1, B1 => 2, B2 => 1, C1 => 3, C2 => 1};
29759  
29760  
29761 is_deeply $x->countAttrNamesAndValues, # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29762  
29763 {A => {A1 => 1}, B => {B1 => 2, B2 => 1}, C => {C1 => 3, C2 => 1}};
29764  
29765  
29766 =head2 countOutputClasses($node, $count)
29767  
29768 Count instances of outputclass attributes
29769  
29770 Parameter Description
29771 1 $node Node
29772 2 $count Count so far.
29773  
29774 B<Example:>
29775  
29776  
29777 my $a = Data::Edit::Xml::newTree("a", id=>1, class=>2, href=>3, outputclass=>4);
29778  
29779  
29780 is_deeply { 4 => 1 }, $a->countOutputClasses; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29781  
29782  
29783  
29784 =head2 countReport($node, @context)
29785  
29786 Count tags, attributes, words below the specified node
29787  
29788 Parameter Description
29789 1 $node Node to count from
29790 2 @context Optional context
29791  
29792 B<Example:>
29793  
29794  
29795 my $a = Data::Edit::Xml::new(<<END);
29796 <a>
29797 <b>aaa bbb ccc</b>
29798 <c>AAA BBB CCC</c>
29799 <c>aaa AAA</c>
29800 </a>
29801 END
29802  
29803  
29804 my $t = $a->countReport; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29805  
29806  
29807 ok $t eq <<END;
29808 Tag Count
29809 1 3 CDATA
29810 2 1 a
29811 3 1 b
29812 4 2 c
29813 END
29814  
29815  
29816 B<cr> is a synonym for L<countReport|/countReport>.
29817  
29818  
29819 =head2 changeReasonCommentSelectionSpecification()
29820  
29821 Provide a specification to select L<change reason comments|/crc> to be inserted as text into a L<parse|/parse> tree. A specification can be either:
29822  
29823 =over
29824  
29825 =item the name of a code to be accepted,
29826  
29827 =item a regular expression which matches the codes to be accepted,
29828  
29829 =item a hash whose keys are defined for the codes to be accepted or
29830  
29831 =item B<undef> (the default) to specify that no such comments should be accepted.
29832  
29833 =back
29834  
29835  
29836 B<Example:>
29837  
29838  
29839  
29840 changeReasonCommentSelectionSpecification = {ccc=>1, ddd=>1}; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29841  
29842  
29843  
29844 changeReasonCommentSelectionSpecification = undef; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29845  
29846  
29847  
29848 This is a static method and so should either be imported or invoked as:
29849  
29850 Data::Edit::Xml::changeReasonCommentSelectionSpecification
29851  
29852  
29853 =head2 crc($node, $code, $reason)
29854  
29855 Insert a comment consisting of a code and an optional reason as text into the L<parse|/parse> tree to indicate the location of changes to the L<parse|/parse> tree. As such comments tend to become very numerous, only comments whose codes matches the specification provided in L<changeReasonCommentSelectionSpecification|/changeReasonCommentSelectionSpecification> are accepted for insertion. Subsequently these comments can be easily located using:
29856  
29857 B<grep -nr "<!-->I<code>B<">
29858  
29859 on the file containing a printed version of the L<parse|/parse> tree. Please note that these comments will be removed if the output file is reparsed.
29860  
29861 Returns the specified B<$node>.
29862  
29863 Parameter Description
29864 1 $node Node being changed
29865 2 $code Reason code
29866 3 $reason Optional text description of change
29867  
29868 B<Example:>
29869  
29870  
29871 {my $a = Data::Edit::Xml::new("<a><b/></a>");
29872  
29873 my ($b) = $a->contents;
29874  
29875 changeReasonCommentSelectionSpecification = {ccc=>1, ddd=>1};
29876  
29877 $b->putFirst(my $c = $b->newTag(q(c)));
29878  
29879  
29880 $c->crc($_) for qw(aaa ccc); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29881  
29882  
29883 ok <<END eq -p $a;
29884 <a>
29885 <b><!--ccc-->
29886 <c/>
29887 </b>
29888 </a>
29889 END
29890  
29891 changeReasonCommentSelectionSpecification = undef;
29892  
29893 $c->putFirst(my $d = $c->newTag(q(d)));
29894  
29895  
29896 $d->crc($_) for qw(aaa ccc); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29897  
29898  
29899 ok <<END eq -p $a;
29900 <a>
29901 <b><!--ccc-->
29902 <c>
29903 <d/>
29904 </c>
29905 </b>
29906 </a>
29907 END
29908  
29909  
29910 =head2 howFirst($node)
29911  
29912 Return the depth to which the specified B<$node> is L<first|/isFirst> else B<0>.
29913  
29914 Parameter Description
29915 1 $node Node
29916  
29917 B<Example:>
29918  
29919  
29920 {my $a = Data::Edit::Xml::new(<<END);
29921 <a>
29922 <b>
29923 <c>
29924 <d/>
29925 </c>
29926 </b>
29927 <b>
29928 <c/>
29929 </b>
29930 <e>
29931 <f/>
29932 </e>
29933 </a>
29934 END
29935  
29936 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
29937  
29938  
29939 ok $d->howFirst == 4; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29940  
29941  
29942  
29943 =head2 howLast($node)
29944  
29945 Return the depth to which the specified B<$node> is L<last|/isLast> else B<0>.
29946  
29947 Parameter Description
29948 1 $node Node
29949  
29950 B<Example:>
29951  
29952  
29953 {my $a = Data::Edit::Xml::new(<<END);
29954 <a>
29955 <b>
29956 <c>
29957 <d/>
29958 </c>
29959 </b>
29960 <b>
29961 <c/>
29962 </b>
29963 <e>
29964 <f/>
29965 </e>
29966 </a>
29967 END
29968  
29969 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
29970  
29971  
29972 ok $f->howLast == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
29973  
29974  
29975  
29976 =head2 howOnlyChild($node)
29977  
29978 Return the depth to which the specified B<$node> is an L<only child|/isOnlyChild> else B<0>.
29979  
29980 Parameter Description
29981 1 $node Node
29982  
29983 B<Example:>
29984  
29985  
29986 {my $a = Data::Edit::Xml::new(<<END);
29987 <a>
29988 <b>
29989 <c>
29990 <d/>
29991 </c>
29992 </b>
29993 <b>
29994 <c/>
29995 </b>
29996 <e>
29997 <f/>
29998 </e>
29999 </a>
30000 END
30001  
30002 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
30003  
30004  
30005 ok $d->howOnlyChild == 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30006  
30007  
30008  
30009 =head2 howFar($first, $second)
30010  
30011 Return how far the first node is from the second node along a path through their common ancestor.
30012  
30013 Parameter Description
30014 1 $first First node
30015 2 $second Second node
30016  
30017 B<Example:>
30018  
30019  
30020 {my $a = Data::Edit::Xml::new(<<END);
30021 <a>
30022 <b>
30023 <c>
30024 <d/>
30025 </c>
30026 </b>
30027 <b>
30028 <c/>
30029 </b>
30030 <e>
30031 <f/>
30032 </e>
30033 </a>
30034 END
30035  
30036 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
30037  
30038 is_deeply [$d->commonAdjacentAncestors($C)], [$b, $B];
30039  
30040  
30041 ok $d->howFar($d) == 0; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30042  
30043  
30044  
30045 ok $d->howFar($a) == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30046  
30047  
30048  
30049 ok $b->howFar($B) == 1; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30050  
30051  
30052  
30053 ok $d->howFar($f) == 5; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30054  
30055  
30056  
30057 ok $d->howFar($C) == 4; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30058  
30059  
30060  
30061 =head2 howFarAbove($above, $below)
30062  
30063 Return how far the first node is L<above|/above> the second node is or B<0> if the first node is not strictly L<above|/above> the second node.
30064  
30065 Parameter Description
30066 1 $above First node above
30067 2 $below Second node below
30068  
30069 B<Example:>
30070  
30071  
30072 {my $a = Data::Edit::Xml::new(<<END);
30073 <a>
30074 <b>
30075 <c>
30076 <d/>
30077 </c>
30078 </b>
30079 <b>
30080 <c/>
30081 </b>
30082 <e>
30083 <f/>
30084 </e>
30085 </a>
30086 END
30087  
30088 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
30089  
30090  
30091 ok $a->howFarAbove($d) == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30092  
30093  
30094  
30095 ok !$d->howFarAbove($c); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30096  
30097  
30098  
30099 =head2 howFarBelow($below, $above)
30100  
30101 Return how far the first node is L<below|/below> the second node is or B<0> if the first node is not strictly L<below|/below> the second node.
30102  
30103 Parameter Description
30104 1 $below First node below
30105 2 $above Second node above
30106  
30107 B<Example:>
30108  
30109  
30110 {my $a = Data::Edit::Xml::new(<<END);
30111 <a>
30112 <b>
30113 <c>
30114 <d/>
30115 </c>
30116 </b>
30117 <b>
30118 <c/>
30119 </b>
30120 <e>
30121 <f/>
30122 </e>
30123 </a>
30124 END
30125  
30126 my ($d, $c, $b, $C, $B, $f, $e) = $a->byList;
30127  
30128  
30129 ok $d->howFarBelow($a) == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30130  
30131  
30132  
30133 ok !$c->howFarBelow($d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30134  
30135  
30136  
30137 =head1 Required clean up
30138  
30139 Insert required clean up tags.
30140  
30141 =head2 requiredCleanUp($node, $outputclass)
30142  
30143 Replace a B<$node> with a required cleanup node with special characters replaced by symbols and with the optional B<$outputclass>.
30144  
30145 Returns the specified B<$node>.
30146  
30147 Parameter Description
30148 1 $node Node
30149 2 $outputclass Optional outputclass attribute of required cleanup tag
30150  
30151 B<Example:>
30152  
30153  
30154 {my $a = Data::Edit::Xml::new(<<END);
30155 <a>
30156 <b>
30157 <c>
30158 ccc
30159 </c>
30160 </b>
30161 </a>
30162 END
30163  
30164 my ($b) = $a->contents;
30165  
30166  
30167 $b->requiredCleanUp(q(33)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30168  
30169  
30170 ok -p $a eq <<END;
30171 <a>
30172 <required-cleanup outputclass="33">&lt;b&gt;
30173 &lt;c&gt;
30174 ccc
30175 &lt;/c&gt;
30176 &lt;/b&gt;
30177 </required-cleanup>
30178 </a>
30179 END
30180  
30181  
30182 =head2 replaceWithRequiredCleanUp($node, @text)
30183  
30184 Replace a B<$node> with required cleanup B<@text> and return the new node
30185  
30186 Parameter Description
30187 1 $node Node to be replace
30188 2 @text Clean up message
30189  
30190 B<Example:>
30191  
30192  
30193 {my $a = Data::Edit::Xml::new(<<END);
30194 <a>
30195 <b/>
30196 </a>
30197 END
30198  
30199 my ($b) = $a->contents;
30200  
30201  
30202 $b->replaceWithRequiredCleanUp(q(bb)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30203  
30204  
30205 ok -p $a eq <<END;
30206 <a>
30207 <required-cleanup>bb</required-cleanup>
30208 </a>
30209 END
30210  
30211  
30212 =head2 putFirstRequiredCleanUp($node, @text)
30213  
30214 Place a required cleanup first under a specified B<$node> using the specified B<@text> and return the required clean up node.
30215  
30216 Parameter Description
30217 1 $node Node
30218 2 @text Clean up message
30219  
30220 B<Example:>
30221  
30222  
30223 {my $a = Data::Edit::Xml::new(<<END);
30224 <a>
30225 <b/>
30226 </a>
30227 END
30228  
30229  
30230 $a->putFirstRequiredCleanUp(qq(1111
30231 )); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30232  
30233  
30234 ok -p $a eq <<END;
30235 <a>
30236 <required-cleanup>1111
30237 </required-cleanup>
30238 <b/>
30239 </a>
30240 END
30241  
30242  
30243 =head2 putLastRequiredCleanUp($node, @text)
30244  
30245 Place a required cleanup last under a specified B<$node> using the specified B<@text> and return the required clean up node.
30246  
30247 Parameter Description
30248 1 $node Node
30249 2 @text Clean up message
30250  
30251 B<Example:>
30252  
30253  
30254 ok -p $a eq <<END;
30255 <a>
30256 <required-cleanup>1111
30257 </required-cleanup>
30258 <b/>
30259 </a>
30260 END
30261  
30262  
30263 $a->putLastRequiredCleanUp(qq(4444
30264 )); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30265  
30266  
30267 ok -p $a eq <<END;
30268 <a>
30269 <required-cleanup>1111
30270 </required-cleanup>
30271 <b/>
30272 <required-cleanup>4444
30273 </required-cleanup>
30274 </a>
30275 END
30276  
30277  
30278 =head2 putNextRequiredCleanUp($node, @text)
30279  
30280 Place a required cleanup next after a specified B<$node> using the specified B<@text> and return the required clean up node.
30281  
30282 Parameter Description
30283 1 $node Node
30284 2 @text Clean up message
30285  
30286 B<Example:>
30287  
30288  
30289 ok -p $a eq <<END;
30290 <a>
30291 <required-cleanup>1111
30292 </required-cleanup>
30293 <b/>
30294 <required-cleanup>4444
30295 </required-cleanup>
30296 </a>
30297 END
30298  
30299  
30300 $a->go(q(b))->putNextRequiredCleanUp(qq(3333
30301 )); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30302  
30303  
30304 ok -p $a eq <<END;
30305 <a>
30306 <required-cleanup>1111
30307 </required-cleanup>
30308 <b/>
30309 <required-cleanup>3333
30310 </required-cleanup>
30311 <required-cleanup>4444
30312 </required-cleanup>
30313 </a>
30314 END
30315  
30316  
30317 =head2 putPrevRequiredCleanUp($node, $text)
30318  
30319 Place a required cleanup before a specified B<$node> using the specified B<@text> and return the required clean up node.
30320  
30321 Parameter Description
30322 1 $node Node
30323 2 $text Clean up message
30324  
30325 B<Example:>
30326  
30327  
30328 ok -p $a eq <<END;
30329 <a>
30330 <required-cleanup>1111
30331 </required-cleanup>
30332 <b/>
30333 <required-cleanup>3333
30334 </required-cleanup>
30335 <required-cleanup>4444
30336 </required-cleanup>
30337 </a>
30338 END
30339  
30340  
30341 $a->go(q(b))->putPrevRequiredCleanUp(qq(2222
30342 )); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30343  
30344  
30345 ok -p $a eq <<END;
30346 <a>
30347 <required-cleanup>1111
30348 </required-cleanup>
30349 <required-cleanup>2222
30350 </required-cleanup>
30351 <b/>
30352 <required-cleanup>3333
30353 </required-cleanup>
30354 <required-cleanup>4444
30355 </required-cleanup>
30356 </a>
30357 END
30358  
30359  
30360 =head1 Conversions
30361  
30362 Methods useful for conversions from word, L<HTML|https://en.wikipedia.org/wiki/HTML> and L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> to L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html>.
30363  
30364 =head2 Dita Conversions
30365  
30366 Methods useful for enhancing L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html>.
30367  
30368 =head3 ditaGetConRef($ref, $sourceFile, $matchContext, $matchContextOnly)
30369  
30370 Get the value of a B<conref> attribute given a valid L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<$ref>erence found in the file named B<$sourceFile>. Optionally, if the regular expression B<$matchContext> is supplied then nodes whose context (single blank separated) tags match this regular expression will be considered first as a target of the conref, if such a search fails then any unique node with the matching id will be the considered next as a possible target unless the optional B<$matchContextOnly> parameter is true. Note: all the conrefs in the included content will also be expanded creating the possibility of endless circular expansions.
30371  
30372 Parameter Description
30373 1 $ref Dita ref value of conref
30374 2 $sourceFile Source file containing conref
30375 3 $matchContext Optional regular expression of acceptable context
30376 4 $matchContextOnly Confine search to acceptable context.
30377  
30378 B<Example:>
30379  
30380  
30381 my $dir = temporaryFolder;
30382 my $a = Data::Edit::Xml::new(<<END);
30383 <a>
30384 <b id="b">
30385 <c/>
30386 </b>
30387 </a>
30388 END
30389  
30390 my $target = fpe($dir, qw(target xml));
30391 owf($target, -p $a);
30392  
30393  
30394 my $b = ditaGetConRef("target.xml#a/b", $dir); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30395  
30396 ok -p $b eq <<END;
30397 <b id="b">
30398 <c/>
30399 </b>
30400 END
30401  
30402 my $A = Data::Edit::Xml::new(<<END);
30403 <a>
30404 <b id="B" conref="target.xml#a/b"/>
30405 </a>
30406 END
30407 my $target2 = fpe($dir, qw(target2 xml));
30408 owf($target2, -p $A);
30409  
30410 my $B = Data::Edit::Xml::new(<<END);
30411 <a>
30412 <b id="C" conref="target2.xml#a/B"/>
30413 </a>
30414 END
30415  
30416 $B->ditaExpandAllConRefs($dir);
30417 ok -p $B eq <<END;
30418 <a>
30419 <b id="C">
30420 <c/>
30421 </b>
30422 </a>
30423 END
30424  
30425 my $CF = owf(fpe($dir, qw(source xml)), <<END);
30426 <a>
30427 <b id="D" conref="target2.xml#a/B"/>
30428 </a>
30429 END
30430  
30431 my $C = Data::Edit::Xml::new($CF);
30432  
30433 $C->first__ditaReplaceAnyConref;
30434 ok -p $C eq <<END;
30435 <a>
30436 <b id="D">
30437 <c/>
30438 </b>
30439 </a>
30440 END
30441  
30442 my $DF = owf(fpe($dir, qw(source xml)), <<END);
30443 <a id="E" conref="target2.xml#a/B"/>
30444 END
30445  
30446 my $D = Data::Edit::Xml::new($DF);
30447  
30448 $D->ditaReplaceAnyConref;
30449 ok -p $D eq <<END;
30450 <b id="E">
30451 <c/>
30452 </b>
30453 END
30454  
30455 my $EF = owf(fpe($dir, qw(source xml)), <<END);
30456 <a id="F" conref="target2.xml"/>
30457 END
30458  
30459 my $E = Data::Edit::Xml::new($EF);
30460  
30461 $E->ditaReplaceAnyConref;
30462  
30463 ok -p $E eq <<END;
30464 <a id="F">
30465 <b id="B">
30466 <c/>
30467 </b>
30468 </a>
30469 END
30470  
30471 clearFolder($dir, 3);
30472  
30473  
30474 This is a static method and so should either be imported or invoked as:
30475  
30476 Data::Edit::Xml::ditaGetConRef
30477  
30478  
30479 =head3 ditaReplaceConref($node, $sourceFile)
30480  
30481 Replace a conref on the specified B<$node> in the specified source file B<$sourceFile> with the parse tree of the referenced content. Returns the referenced content. Confesses if there is no conref to replace on $node.
30482  
30483 Parameter Description
30484 1 $node Node with conref attribute
30485 2 $sourceFile Source file containing the node.
30486  
30487 B<Example:>
30488  
30489  
30490 my $dir = temporaryFolder;
30491 my $a = Data::Edit::Xml::new(<<END);
30492 <a>
30493 <b id="b">
30494 <c/>
30495 </b>
30496 </a>
30497 END
30498  
30499 my $target = fpe($dir, qw(target xml));
30500 owf($target, -p $a);
30501  
30502 my $b = ditaGetConRef("target.xml#a/b", $dir);
30503 ok -p $b eq <<END;
30504 <b id="b">
30505 <c/>
30506 </b>
30507 END
30508  
30509 my $A = Data::Edit::Xml::new(<<END);
30510 <a>
30511 <b id="B" conref="target.xml#a/b"/>
30512 </a>
30513 END
30514 my $target2 = fpe($dir, qw(target2 xml));
30515 owf($target2, -p $A);
30516  
30517 my $B = Data::Edit::Xml::new(<<END);
30518 <a>
30519 <b id="C" conref="target2.xml#a/B"/>
30520 </a>
30521 END
30522  
30523 $B->ditaExpandAllConRefs($dir);
30524 ok -p $B eq <<END;
30525 <a>
30526 <b id="C">
30527 <c/>
30528 </b>
30529 </a>
30530 END
30531  
30532 my $CF = owf(fpe($dir, qw(source xml)), <<END);
30533 <a>
30534 <b id="D" conref="target2.xml#a/B"/>
30535 </a>
30536 END
30537  
30538 my $C = Data::Edit::Xml::new($CF);
30539  
30540 $C->first__ditaReplaceAnyConref;
30541 ok -p $C eq <<END;
30542 <a>
30543 <b id="D">
30544 <c/>
30545 </b>
30546 </a>
30547 END
30548  
30549 my $DF = owf(fpe($dir, qw(source xml)), <<END);
30550 <a id="E" conref="target2.xml#a/B"/>
30551 END
30552  
30553 my $D = Data::Edit::Xml::new($DF);
30554  
30555 $D->ditaReplaceAnyConref;
30556 ok -p $D eq <<END;
30557 <b id="E">
30558 <c/>
30559 </b>
30560 END
30561  
30562 my $EF = owf(fpe($dir, qw(source xml)), <<END);
30563 <a id="F" conref="target2.xml"/>
30564 END
30565  
30566 my $E = Data::Edit::Xml::new($EF);
30567  
30568 $E->ditaReplaceAnyConref;
30569  
30570 ok -p $E eq <<END;
30571 <a id="F">
30572 <b id="B">
30573 <c/>
30574 </b>
30575 </a>
30576 END
30577  
30578 clearFolder($dir, 3);
30579  
30580  
30581 =head3 ditaReplaceAnyConref($node, @context)
30582  
30583 Replace a conref with the referenced content if we are in the optional context and the target of the conref can be located. Returns true regardless of any processing performed to allow L<Dita::Pcd|https://metacpan.org/pod/Dita::PCD> processing to continue.
30584  
30585 Parameter Description
30586 1 $node Node with conref attribute
30587 2 @context Optional context.
30588  
30589 B<Example:>
30590  
30591  
30592 my $dir = temporaryFolder;
30593 my $a = Data::Edit::Xml::new(<<END);
30594 <a>
30595 <b id="b">
30596 <c/>
30597 </b>
30598 </a>
30599 END
30600  
30601 my $target = fpe($dir, qw(target xml));
30602 owf($target, -p $a);
30603  
30604 my $b = ditaGetConRef("target.xml#a/b", $dir);
30605 ok -p $b eq <<END;
30606 <b id="b">
30607 <c/>
30608 </b>
30609 END
30610  
30611 my $A = Data::Edit::Xml::new(<<END);
30612 <a>
30613 <b id="B" conref="target.xml#a/b"/>
30614 </a>
30615 END
30616 my $target2 = fpe($dir, qw(target2 xml));
30617 owf($target2, -p $A);
30618  
30619 my $B = Data::Edit::Xml::new(<<END);
30620 <a>
30621 <b id="C" conref="target2.xml#a/B"/>
30622 </a>
30623 END
30624  
30625 $B->ditaExpandAllConRefs($dir);
30626 ok -p $B eq <<END;
30627 <a>
30628 <b id="C">
30629 <c/>
30630 </b>
30631 </a>
30632 END
30633  
30634 my $CF = owf(fpe($dir, qw(source xml)), <<END);
30635 <a>
30636 <b id="D" conref="target2.xml#a/B"/>
30637 </a>
30638 END
30639  
30640 my $C = Data::Edit::Xml::new($CF);
30641  
30642 $C->first__ditaReplaceAnyConref;
30643 ok -p $C eq <<END;
30644 <a>
30645 <b id="D">
30646 <c/>
30647 </b>
30648 </a>
30649 END
30650  
30651 my $DF = owf(fpe($dir, qw(source xml)), <<END);
30652 <a id="E" conref="target2.xml#a/B"/>
30653 END
30654  
30655 my $D = Data::Edit::Xml::new($DF);
30656  
30657  
30658 $D->ditaReplaceAnyConref; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30659  
30660 ok -p $D eq <<END;
30661 <b id="E">
30662 <c/>
30663 </b>
30664 END
30665  
30666 my $EF = owf(fpe($dir, qw(source xml)), <<END);
30667 <a id="F" conref="target2.xml"/>
30668 END
30669  
30670 my $E = Data::Edit::Xml::new($EF);
30671  
30672  
30673 $E->ditaReplaceAnyConref; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30674  
30675  
30676 ok -p $E eq <<END;
30677 <a id="F">
30678 <b id="B">
30679 <c/>
30680 </b>
30681 </a>
30682 END
30683  
30684 clearFolder($dir, 3);
30685  
30686  
30687 =head3 ditaReplaceAnyConrefIdeallyWithMatchingTag($node, @context)
30688  
30689 Replace a conref with the referenced content if we are in the optional context and the target of the conref can be located. If multiple possible targets exists, priority will be given to any that match the tag of $node. Returns the root of the parse tree containing the new content or B<undef> if no new content was located.
30690  
30691 Parameter Description
30692 1 $node Node with conref attribute
30693 2 @context Optional context.
30694  
30695 B<Example:>
30696  
30697  
30698 my $dir = temporaryFolder;
30699 my $target = Data::Edit::Xml::new(<<END);
30700 <a>
30701 <c id="b"/>
30702 <b id="b"/>
30703 </a>
30704 END
30705  
30706 owf(fpe($dir, qw(target xml)), -p $target);
30707  
30708 my $s = Data::Edit::Xml::new(q(<a conref="target.xml#a/b"/>));
30709 $s->inputFile = fpe($dir, qw(source xml));
30710  
30711 my $s1 = $s->clone->change_c;
30712  
30713 $s1->ditaReplaceAnyConrefIdeallyWithMatchingTag; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30714  
30715 ok -p $s1 eq <<END;
30716 <c id="b"/>
30717 END
30718  
30719 my $s2 = $s->clone->change_b;
30720 ok !$s2->ditaReplaceAnyConrefInContext(qr(\Ac A\Z));
30721 $s2->ditaReplaceAnyConrefInContext(qr(\Ac a\Z));
30722 ok -p $s2 eq <<END;
30723 <c id="b"/>
30724 END
30725  
30726 my $b = ditaGetConRef("target.xml#a/b", $dir, qr(\Ab\Z));
30727 ok -p $b eq <<END;
30728 <b id="b"/>
30729 END
30730  
30731 my $c = ditaGetConRef("target.xml#a/b", $dir, qr(\Ac a\Z));
30732 ok -p $c eq <<END;
30733 <c id="b"/>
30734 END
30735  
30736 my $d = ditaGetConRef("target.xml#a/b", $dir, qr(\Ad\Z));
30737 ok -p $c eq <<END;
30738 <c id="b"/>
30739 END
30740  
30741 ok !ditaGetConRef("target.xml#a/b", $dir, qr(\A(d|e)\Z), 1);
30742  
30743 clearFolder($dir, 3);
30744  
30745  
30746 =head3 ditaReplaceAnyConrefInContext($node, $context, @context)
30747  
30748 Replace a conref with the referenced content if we are in the optional context and the target of the conref can be located and the L<context> of the target node matches the regular expression B<$context>. Returns the root of the parse tree containing the new content or B<undef> if no new content was located.
30749  
30750 Parameter Description
30751 1 $node Node with conref attribute
30752 2 $context Tags to match
30753 3 @context Optional context.
30754  
30755 B<Example:>
30756  
30757  
30758 my $dir = temporaryFolder;
30759 my $target = Data::Edit::Xml::new(<<END);
30760 <a>
30761 <c id="b"/>
30762 <b id="b"/>
30763 </a>
30764 END
30765  
30766 owf(fpe($dir, qw(target xml)), -p $target);
30767  
30768 my $s = Data::Edit::Xml::new(q(<a conref="target.xml#a/b"/>));
30769 $s->inputFile = fpe($dir, qw(source xml));
30770  
30771 my $s1 = $s->clone->change_c;
30772 $s1->ditaReplaceAnyConrefIdeallyWithMatchingTag;
30773 ok -p $s1 eq <<END;
30774 <c id="b"/>
30775 END
30776  
30777 my $s2 = $s->clone->change_b;
30778  
30779 ok !$s2->ditaReplaceAnyConrefInContext(qr(\Ac A\Z)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30780  
30781  
30782 $s2->ditaReplaceAnyConrefInContext(qr(\Ac a\Z)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30783  
30784 ok -p $s2 eq <<END;
30785 <c id="b"/>
30786 END
30787  
30788 my $b = ditaGetConRef("target.xml#a/b", $dir, qr(\Ab\Z));
30789 ok -p $b eq <<END;
30790 <b id="b"/>
30791 END
30792  
30793 my $c = ditaGetConRef("target.xml#a/b", $dir, qr(\Ac a\Z));
30794 ok -p $c eq <<END;
30795 <c id="b"/>
30796 END
30797  
30798 my $d = ditaGetConRef("target.xml#a/b", $dir, qr(\Ad\Z));
30799 ok -p $c eq <<END;
30800 <c id="b"/>
30801 END
30802  
30803 ok !ditaGetConRef("target.xml#a/b", $dir, qr(\A(d|e)\Z), 1);
30804  
30805 clearFolder($dir, 3);
30806  
30807  
30808 =head3 ditaExpandAllConRefs($tree, $sourceFile)
30809  
30810 Expand all the conrefs in the specified B<$parseTree> relative to the specified B<$sourceFile>.
30811  
30812 Parameter Description
30813 1 $tree Parse tree
30814 2 $sourceFile Source file we are expanding in
30815  
30816 B<Example:>
30817  
30818  
30819 my $dir = temporaryFolder;
30820 my $a = Data::Edit::Xml::new(<<END);
30821 <a>
30822 <b id="b">
30823 <c/>
30824 </b>
30825 </a>
30826 END
30827  
30828 my $target = fpe($dir, qw(target xml));
30829 owf($target, -p $a);
30830  
30831 my $b = ditaGetConRef("target.xml#a/b", $dir);
30832 ok -p $b eq <<END;
30833 <b id="b">
30834 <c/>
30835 </b>
30836 END
30837  
30838 my $A = Data::Edit::Xml::new(<<END);
30839 <a>
30840 <b id="B" conref="target.xml#a/b"/>
30841 </a>
30842 END
30843 my $target2 = fpe($dir, qw(target2 xml));
30844 owf($target2, -p $A);
30845  
30846 my $B = Data::Edit::Xml::new(<<END);
30847 <a>
30848 <b id="C" conref="target2.xml#a/B"/>
30849 </a>
30850 END
30851  
30852  
30853 $B->ditaExpandAllConRefs($dir); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30854  
30855 ok -p $B eq <<END;
30856 <a>
30857 <b id="C">
30858 <c/>
30859 </b>
30860 </a>
30861 END
30862  
30863 my $CF = owf(fpe($dir, qw(source xml)), <<END);
30864 <a>
30865 <b id="D" conref="target2.xml#a/B"/>
30866 </a>
30867 END
30868  
30869 my $C = Data::Edit::Xml::new($CF);
30870  
30871 $C->first__ditaReplaceAnyConref;
30872 ok -p $C eq <<END;
30873 <a>
30874 <b id="D">
30875 <c/>
30876 </b>
30877 </a>
30878 END
30879  
30880 my $DF = owf(fpe($dir, qw(source xml)), <<END);
30881 <a id="E" conref="target2.xml#a/B"/>
30882 END
30883  
30884 my $D = Data::Edit::Xml::new($DF);
30885  
30886 $D->ditaReplaceAnyConref;
30887 ok -p $D eq <<END;
30888 <b id="E">
30889 <c/>
30890 </b>
30891 END
30892  
30893 my $EF = owf(fpe($dir, qw(source xml)), <<END);
30894 <a id="F" conref="target2.xml"/>
30895 END
30896  
30897 my $E = Data::Edit::Xml::new($EF);
30898  
30899 $E->ditaReplaceAnyConref;
30900  
30901 ok -p $E eq <<END;
30902 <a id="F">
30903 <b id="B">
30904 <c/>
30905 </b>
30906 </a>
30907 END
30908  
30909 clearFolder($dir, 3);
30910  
30911  
30912 =head3 ditaAbsoluteHref($node, $sourceFile)
30913  
30914 Return the absolute value of the href of a specified B<$node> relative to the specified B<$sourceFile> or B<undef> if the node has no B<href> attribute.
30915  
30916 Parameter Description
30917 1 $node Node containing href
30918 2 $sourceFile Source file
30919  
30920 B<Example:>
30921  
30922  
30923 my $a = Data::Edit::Xml::new(<<END);
30924 <a href="bbb.txt">
30925 </a>
30926 END
30927  
30928  
30929 ok $a->ditaAbsoluteHref(q(/home/aaa/)) eq q(/home/aaa/bbb.txt); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30930  
30931  
30932  
30933 =head3 ditaListToChoices($list, @context)
30934  
30935 Change the specified B<$list> to B<choices>.
30936  
30937 Parameter Description
30938 1 $list Node
30939 2 @context Optional context
30940  
30941 Use the optional B<@context> parameter to test the context of the specified
30942 B<$node> as understood by method L<at|/at>. If the context is supplied and
30943 B<$node> is not in this context then this method returns B<undef> immediately.
30944  
30945  
30946  
30947 B<Example:>
30948  
30949  
30950 my $a = Data::Edit::Xml::new(<<END);
30951 <ol>
30952 <li>
30953 <p/>
30954 </li>
30955 <li>
30956 <p/>
30957 </li>
30958 </ol>
30959 END
30960  
30961  
30962 $a->ditaListToChoices; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
30963  
30964 ok -p $a eq <<END;
30965 <choices>
30966 <choice>
30967 <p/>
30968 </choice>
30969 <choice>
30970 <p/>
30971 </choice>
30972 </choices>
30973 END
30974  
30975  
30976 =head3 ditaListToSteps($list, @context)
30977  
30978 Change the specified B<$node> to B<steps> and its contents to B<cmd\step> optionally only in the specified context.
30979  
30980 Parameter Description
30981 1 $list Node
30982 2 @context Optional context
30983  
30984 Use the optional B<@context> parameter to test the context of the specified
30985 B<$node> as understood by method L<at|/at>. If the context is supplied and
30986 B<$node> is not in this context then this method returns B<undef> immediately.
30987  
30988  
30989  
30990 B<Example:>
30991  
30992  
30993 ok -p $a eq <<END;
30994 <dita>
30995 <ol>
30996 <li>
30997 <p>aaa</p>
30998 </li>
30999 <li>
31000 <p>bbb</p>
31001 </li>
31002 </ol>
31003 </dita>
31004 END
31005  
31006  
31007 $a->first->ditaListToSteps; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31008  
31009  
31010 ok -p $a eq <<END;
31011 <dita>
31012 <steps>
31013 <step>
31014 <cmd>aaa</cmd>
31015 </step>
31016 <step>
31017 <cmd>bbb</cmd>
31018 </step>
31019 </steps>
31020 </dita>
31021 END
31022  
31023  
31024 =head3 ditaListToStepsUnordered($list, @context)
31025  
31026 Change the specified B<$node> to B<steps-unordered> and its contents to B<cmd\step> optionally only in the specified context.
31027  
31028 Parameter Description
31029 1 $list Node
31030 2 @context Optional context
31031  
31032 Use the optional B<@context> parameter to test the context of the specified
31033 B<$node> as understood by method L<at|/at>. If the context is supplied and
31034 B<$node> is not in this context then this method returns B<undef> immediately.
31035  
31036  
31037  
31038 B<Example:>
31039  
31040  
31041 ok -p $a eq <<END;
31042 <dita>
31043 <ol>
31044 <li>aaa</li>
31045 <li>bbb</li>
31046 </ol>
31047 </dita>
31048 END
31049  
31050  
31051 $a->first->ditaListToStepsUnordered; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31052  
31053  
31054 ok -p $a eq <<END;
31055 <dita>
31056 <steps-unordered>
31057 <step>
31058 <cmd>aaa</cmd>
31059 </step>
31060 <step>
31061 <cmd>bbb</cmd>
31062 </step>
31063 </steps-unordered>
31064 </dita>
31065 END
31066  
31067  
31068 =head3 ditaListToSubSteps($list, @context)
31069  
31070 Change the specified B<$node> to B<substeps> and its contents to B<cmd\step> optionally only in the specified context.
31071  
31072 Parameter Description
31073 1 $list Node
31074 2 @context Optional context
31075  
31076 Use the optional B<@context> parameter to test the context of the specified
31077 B<$node> as understood by method L<at|/at>. If the context is supplied and
31078 B<$node> is not in this context then this method returns B<undef> immediately.
31079  
31080  
31081  
31082 B<Example:>
31083  
31084  
31085 {my $a = Data::Edit::Xml::new(<<END);
31086 <dita>
31087 <ol>
31088 <li>aaa</li>
31089 <li>bbb</li>
31090 </ol>
31091 </dita>
31092 END
31093  
31094  
31095 $a->first->ditaListToSubSteps; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31096  
31097  
31098 ok -p $a eq <<END;
31099 <dita>
31100 <substeps>
31101 <substep>
31102 <cmd>aaa</cmd>
31103 </substep>
31104 <substep>
31105 <cmd>bbb</cmd>
31106 </substep>
31107 </substeps>
31108 </dita>
31109 END
31110  
31111  
31112 =head3 ditaStepsToList($steps, $tag, @context)
31113  
31114 Change the specified B<$node> to a node with name B<$tag> or to B<ol> if B<$tag> is not supplied and its B<cmd\step> content to B<li> to create a list optionally only in the specified context.
31115  
31116 Parameter Description
31117 1 $steps Node
31118 2 $tag New tag if not ol
31119 3 @context Optional context
31120  
31121 Use the optional B<@context> parameter to test the context of the specified
31122 B<$node> as understood by method L<at|/at>. If the context is supplied and
31123 B<$node> is not in this context then this method returns B<undef> immediately.
31124  
31125  
31126  
31127 B<Example:>
31128  
31129  
31130 ok -p $a eq <<END;
31131 <dita>
31132 <ol>
31133 <li>
31134 <p>aaa</p>
31135 </li>
31136 <li>
31137 <p>bbb</p>
31138 </li>
31139 </ol>
31140 </dita>
31141 END
31142  
31143  
31144 $a->first->ditaStepsToList; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31145  
31146  
31147 ok -p $a eq <<END;
31148 <dita>
31149 <ol>
31150 <li>aaa</li>
31151 <li>bbb</li>
31152 </ol>
31153 </dita>
31154 END
31155  
31156  
31157 =head3 ditaStepsToChoices($steps, @context)
31158  
31159 Change the specified B<$node> to B<choices>.
31160  
31161 Parameter Description
31162 1 $steps Node
31163 2 @context Optional context
31164  
31165 Use the optional B<@context> parameter to test the context of the specified
31166 B<$node> as understood by method L<at|/at>. If the context is supplied and
31167 B<$node> is not in this context then this method returns B<undef> immediately.
31168  
31169  
31170  
31171 B<Example:>
31172  
31173  
31174 my $a = Data::Edit::Xml::new(<<END);
31175 <steps>
31176 <step>
31177 <cmd>Command</cmd>
31178 <stepresult>
31179 Step result
31180 </stepresult>
31181 <stepxmp>
31182 Step example
31183 </stepxmp>
31184 </step>
31185 <step>
31186 <cmd>Command</cmd>
31187 <stepresult>
31188 Step result
31189 </stepresult>
31190 <stepxmp>
31191 Step example
31192 </stepxmp>
31193 </step>
31194 </steps>
31195 END
31196  
31197  
31198 $a->ditaStepsToChoices; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31199  
31200  
31201 ok -p $a eq <<END;
31202 <choices>
31203 <choice>
31204 <p>Command</p>
31205 Step result
31206 Step example
31207 </choice>
31208 <choice>
31209 <p>Command</p>
31210 Step result
31211 Step example
31212 </choice>
31213 </choices>
31214 END
31215  
31216  
31217 =head3 ditaConvertSubStepsToSteps($substeps, @context)
31218  
31219 Change the B<$substeps> to B<steps> and return the B<steps> on success or B<undef> on failure.
31220  
31221 Parameter Description
31222 1 $substeps Substeps
31223 2 @context Optional context
31224  
31225 Use the optional B<@context> parameter to test the context of the specified
31226 B<$node> as understood by method L<at|/at>. If the context is supplied and
31227 B<$node> is not in this context then this method returns B<undef> immediately.
31228  
31229  
31230  
31231 B<Example:>
31232  
31233  
31234 my $a = Data::Edit::Xml::new(<<END);
31235 <substeps>
31236 <substep>
31237 <cmd>C1</cmd>
31238 </substep>
31239 <substep>
31240 <cmd>C2</cmd>
31241 </substep>
31242 </substeps>
31243 END
31244  
31245  
31246 $a->ditaConvertSubStepsToSteps; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31247  
31248  
31249 ok -p $a eq <<END;
31250 <steps>
31251 <step>
31252 <cmd>C1</cmd>
31253 </step>
31254 <step>
31255 <cmd>C2</cmd>
31256 </step>
31257 </steps>
31258 END
31259  
31260  
31261 =head3 ditaListToTable($node, @context)
31262  
31263 Convert a list to a table in situ - as designed by MiM.
31264  
31265 Parameter Description
31266 1 $node List node
31267 2 @context Optional context
31268  
31269 Use the optional B<@context> parameter to test the context of the specified
31270 B<$node> as understood by method L<at|/at>. If the context is supplied and
31271 B<$node> is not in this context then this method returns B<undef> immediately.
31272  
31273  
31274  
31275 B<Example:>
31276  
31277  
31278 if (1)
31279 {my $a = Data::Edit::Xml::new(<<END);
31280 <ul id="Table3" outputclass="fcRowList">
31281 <li>
31282 <p id="1">1111</p>
31283 <p id="2">2222</p>
31284 <p id="3">3333</p>
31285 <p id="4">4444</p>
31286 </li>
31287 <li>
31288 <p id="tableToListA1" outputclass="1">aaaa1111</p>
31289 <p id="tableToListA2" outputclass="1">aaaa2222</p>
31290 <p id="tableToListA3" outputclass="1">aaaa3333</p>
31291 <p id="tableToListA4" outputclass="1">aaaa4444</p>
31292 </li>
31293 <li>
31294 <p id="tableToListB1" outputclass="1">bbbb1111</p>
31295 <p id="tableToListB2" outputclass="1">bbbb2222</p>
31296 <p id="tableToListB3" outputclass="1">bbbb3333</p>
31297 </li>
31298 <li>
31299 <p id="tableToListC1" outputclass="1">cccc1111</p>
31300 <p id="tableToListC2" outputclass="1">cccc2222</p>
31301 <p id="tableToListC3" outputclass="1">cccc3333</p>
31302 <p id="tableToListC4" outputclass="1">cccc4444</p>
31303 <p id="tableToListC5" outputclass="1">cccc5555</p>
31304 </li>
31305 </ul>
31306 END
31307  
31308 $a->ditaListToTable; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31309  
31310 ok nws(-p $a) eq nws(<<END)
31311 <table id="Table3" outputclass="fcRowList">
31312 <tgroup cols="5">
31313 <colspec colname="c1" colnum="1" colwidth="1*"/>
31314 <colspec colname="c2" colnum="2" colwidth="1*"/>
31315 <colspec colname="c3" colnum="3" colwidth="1*"/>
31316 <colspec colname="c4" colnum="4" colwidth="1*"/>
31317 <colspec colname="c5" colnum="5" colwidth="1*"/>
31318 <thead>
31319 <row>
31320 <entry/>
31321 <entry/>
31322 <entry/>
31323 <entry/>
31324 <entry/>
31325 </row>
31326 </thead>
31327 <tbody>
31328 <row>
31329 <entry id="1">1111</entry>
31330 <entry id="2">2222</entry>
31331 <entry id="3">3333</entry>
31332 <entry id="4">4444</entry>
31333 </row>
31334 <row>
31335 <entry id="tableToListA1" outputclass="1">aaaa1111</entry>
31336 <entry id="tableToListA2" outputclass="1">aaaa2222</entry>
31337 <entry id="tableToListA3" outputclass="1">aaaa3333</entry>
31338 <entry id="tableToListA4" outputclass="1">aaaa4444</entry>
31339 </row>
31340 <row>
31341 <entry id="tableToListB1" outputclass="1">bbbb1111</entry>
31342 <entry id="tableToListB2" outputclass="1">bbbb2222</entry>
31343 <entry id="tableToListB3" outputclass="1">bbbb3333</entry>
31344 </row>
31345 <row>
31346 <entry id="tableToListC1" outputclass="1">cccc1111</entry>
31347 <entry id="tableToListC2" outputclass="1">cccc2222</entry>
31348 <entry id="tableToListC3" outputclass="1">cccc3333</entry>
31349 <entry id="tableToListC4" outputclass="1">cccc4444</entry>
31350 <entry id="tableToListC5" outputclass="1">cccc5555</entry>
31351 </row>
31352 </tbody>
31353 </tgroup>
31354 </table>
31355 END
31356 }
31357  
31358  
31359 =head3 ditaMergeLists($node, @context)
31360  
31361 Merge the specified B<$node> with the preceding or following list or steps or substeps if possible and return the specified B<$node> regardless.
31362  
31363 Parameter Description
31364 1 $node Node
31365 2 @context Optional context
31366  
31367 Use the optional B<@context> parameter to test the context of the specified
31368 B<$node> as understood by method L<at|/at>. If the context is supplied and
31369 B<$node> is not in this context then this method returns B<undef> immediately.
31370  
31371  
31372  
31373 B<Example:>
31374  
31375  
31376 {my $a = Data::Edit::Xml::new(<<END);
31377 <a>
31378 <li id="1"/>
31379 <ol/>
31380 <ol>
31381 <li id="2"/>
31382 <li id="3"/>
31383 </ol>
31384 </a>
31385 END
31386  
31387  
31388 $a x= sub{$_->ditaMergeLists}; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31389  
31390  
31391 ok -p $a eq <<END;
31392 <a>
31393 <ol>
31394 <li id="1"/>
31395 <li id="2"/>
31396 <li id="3"/>
31397 </ol>
31398 </a>
31399 END
31400  
31401  
31402 =head3 mergeLikeElements($node, @context)
31403  
31404 Merge two of the same elements into one, retaining the order of any children. Return the original B<$node> if the request succeeds, else return B<undef>.
31405  
31406 Parameter Description
31407 1 $node Node
31408 2 @context Optional context
31409  
31410 Use the optional B<@context> parameter to test the context of the specified
31411 B<$node> as understood by method L<at|/at>. If the context is supplied and
31412 B<$node> is not in this context then this method returns B<undef> immediately.
31413  
31414  
31415  
31416 B<Example:>
31417  
31418  
31419 my $a = Data::Edit::Xml::new(<<END);
31420 <x><a>aa</a><b>bb</b><b>cc</b><b>dd</b><b>ee</b></x>
31421 END
31422  
31423 ok -p $a eq <<END;
31424 <x>
31425 <a>aa</a>
31426 <b>bb</b>
31427 <b>cc</b>
31428 <b>dd</b>
31429 <b>ee</b>
31430 </x>
31431 END
31432  
31433  
31434 $a->by(sub{$_->mergeLikeElements}); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31435  
31436 ok -p $a eq <<END;
31437 <x>
31438 <a>aa</a>
31439 <b>bb cc dd ee</b>
31440 </x>
31441 END
31442  
31443  
31444  
31445 =head3 mergeLikeNext($node, @context)
31446  
31447 Merge a B<$node> in an optional context with the next node if the two have the same tag by placing the next node first in the current B<$node> and unwrapping the next node. Return B<undef> if the request fails else the current B<$node>. Identical to L<mergeLikeElements|/mergeLikeElements>
31448  
31449 Parameter Description
31450 1 $node Node
31451 2 @context Optional context
31452  
31453 Use the optional B<@context> parameter to test the context of the specified
31454 B<$node> as understood by method L<at|/at>. If the context is supplied and
31455 B<$node> is not in this context then this method returns B<undef> immediately.
31456  
31457  
31458  
31459 B<Example:>
31460  
31461  
31462 my $a = Data::Edit::Xml::new(<<END);
31463 <a>
31464 <b>bb</b>
31465 <b>dd</b>
31466 </a>
31467 END
31468  
31469  
31470 $a->first->mergeLikeNext; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31471  
31472  
31473 ok -p $a eq <<END;
31474 <a>
31475 <b>bb dd</b>
31476 </a>
31477 END
31478  
31479  
31480 B<mln> is a synonym for L<mergeLikeNext|/mergeLikeNext>.
31481  
31482  
31483 =head3 mergeLikePrev($node, @context)
31484  
31485 Merge a B<$node> in an optional context with the previous node if the two have the same tag by placing the previous node first in the current B<$node> and unwrapping the previous node. Return B<undef> if the request fails else return the specified B<$node>.
31486  
31487 Parameter Description
31488 1 $node Node
31489 2 @context Optional context
31490  
31491 Use the optional B<@context> parameter to test the context of the specified
31492 B<$node> as understood by method L<at|/at>. If the context is supplied and
31493 B<$node> is not in this context then this method returns B<undef> immediately.
31494  
31495  
31496  
31497 B<Example:>
31498  
31499  
31500 my $a = Data::Edit::Xml::new(<<END);
31501 <a>
31502 <b>bb</b>
31503 <b>dd</b>
31504 </a>
31505 END
31506  
31507  
31508 $a->last->mergeLikePrev; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31509  
31510  
31511 ok -p $a eq <<END;
31512 <a>
31513 <b>bb dd</b>
31514 </a>
31515 END
31516  
31517  
31518 B<mlp> is a synonym for L<mergeLikePrev|/mergeLikePrev>.
31519  
31520  
31521 =head3 mergeOnlyChildLikeNext($node, @context)
31522  
31523 Merge a B<$node> if it is the only child of its parent with a preceding node of the same name that is also the only child of its parent and return the specified B<$node> or B<undef> if the request fails.
31524  
31525 Parameter Description
31526 1 $node Node
31527 2 @context Optional context
31528  
31529 Use the optional B<@context> parameter to test the context of the specified
31530 B<$node> as understood by method L<at|/at>. If the context is supplied and
31531 B<$node> is not in this context then this method returns B<undef> immediately.
31532  
31533  
31534  
31535 B<Example:>
31536  
31537  
31538 my $a = Data::Edit::Xml::new(<<END);
31539 <a>
31540 <b id="1">
31541 <c/>
31542 </b>
31543 <b id="2">
31544 <c/>
31545 </b>
31546 </a>
31547 END
31548  
31549 $a->go_b_c__mergeOnlyChildLikeNext;
31550 ok -p $a eq <<END;
31551 <a>
31552 <b id="1">
31553 <c/>
31554 </b>
31555 </a>
31556 END
31557  
31558  
31559 B<mocln> is a synonym for L<mergeOnlyChildLikeNext|/mergeOnlyChildLikeNext>.
31560  
31561  
31562 =head3 mergeOnlyChildLikePrev($node, @context)
31563  
31564 Merge a B<$node> if it is the only child of its parent with a preceding node of the same name that is also the only child of its parent and return the specified B<$node> or B<undef> if the request fails.
31565  
31566 Parameter Description
31567 1 $node Node
31568 2 @context Optional context
31569  
31570 Use the optional B<@context> parameter to test the context of the specified
31571 B<$node> as understood by method L<at|/at>. If the context is supplied and
31572 B<$node> is not in this context then this method returns B<undef> immediately.
31573  
31574  
31575  
31576 B<Example:>
31577  
31578  
31579 my $a = Data::Edit::Xml::new(<<END);
31580 <a>
31581 <b id="1">
31582 <c/>
31583 </b>
31584 <b id="2">
31585 <c/>
31586 </b>
31587 </a>
31588 END
31589  
31590 $a->go_b_1_c__mergeOnlyChildLikePrev;
31591 ok -p $a eq <<END;
31592 <a>
31593 <b id="2">
31594 <c/>
31595 </b>
31596 </a>
31597 END
31598  
31599  
31600 B<moclp> is a synonym for L<mergeOnlyChildLikePrev|/mergeOnlyChildLikePrev>.
31601  
31602  
31603 =head3 mergeOnlyChildLikePrevLast($node, @context)
31604  
31605 Merge a B<$node> if it is the only child of its parent with a preceding node with the same tag that is the last child of its parent and return the previous B<$node> or B<undef> if the request fails.
31606  
31607 Parameter Description
31608 1 $node Node
31609 2 @context Optional context
31610  
31611 Use the optional B<@context> parameter to test the context of the specified
31612 B<$node> as understood by method L<at|/at>. If the context is supplied and
31613 B<$node> is not in this context then this method returns B<undef> immediately.
31614  
31615  
31616  
31617 B<Example:>
31618  
31619  
31620 my $a = Data::Edit::Xml::new(<<END);
31621 <a>
31622 <b><c/><d>1</d></b>
31623 <b> <d>2</d></b>
31624 </a>
31625 END
31626  
31627 my $c = $a->last__last__mergeOnlyChildLikePrevLast;
31628 ok -p $a eq <<END;
31629 <a>
31630 <b>
31631 <c/>
31632 <d>1 2</d>
31633 </b>
31634 </a>
31635 END
31636  
31637 ok -p $c eq <<END
31638 <d>1 2</d>
31639 END
31640  
31641  
31642 =head3 ditaMaximumNumberOfEntriesInATGroupRow($tgroup)
31643  
31644 Return the maximum number of entries in the rows of the specified B<$table> or B<undef> if not a table.
31645  
31646 Parameter Description
31647 1 $tgroup TGroup node
31648  
31649 B<Example:>
31650  
31651  
31652 my $a = Data::Edit::Xml::new(<<END);
31653 <table>
31654 <tgroup cols="1">
31655 <colspec/>
31656 <thead>
31657 <row>
31658 <entry>aaaa</entry>
31659 <entry/>
31660 </row>
31661 <row>
31662 <entry>bbbb</entry>
31663 </row>
31664 </thead>
31665 <tbody>
31666 <row>
31667 <entry>cccc</entry>
31668 <entry/>
31669 <entry/>
31670 </row>
31671 <row>
31672 <entry>dddd</entry>
31673 </row>
31674 </tbody>
31675 </tgroup>
31676 </table>
31677 END
31678  
31679 my $g = $a->go_tgroup;
31680  
31681  
31682 ok $g->ditaMaximumNumberOfEntriesInATGroupRow == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31683  
31684  
31685 is_deeply $g->ditaTGroupStatistics,
31686 bless({
31687 colsAttribute => 1,
31688 colSpec => 1,
31689 maxBody => 3,
31690 maxBodyMinusPadding => 3,
31691 maxHead => 2,
31692 maxHeadMinusPadding => 2,
31693 minBody => 1,
31694 minHead => 1,
31695 rows => 4,
31696 }, "Data::Edit::Xml::Table::Statistics");
31697  
31698 $g->ditaRemoveTGroupTrailingEmptyEntries;
31699  
31700 ok -p $a eq <<END;
31701 <table>
31702 <tgroup cols="1">
31703 <colspec/>
31704 <thead>
31705 <row>
31706 <entry>aaaa</entry>
31707 </row>
31708 <row>
31709 <entry>bbbb</entry>
31710 </row>
31711 </thead>
31712 <tbody>
31713 <row>
31714 <entry>cccc</entry>
31715 </row>
31716 <row>
31717 <entry>dddd</entry>
31718 </row>
31719 </tbody>
31720 </tgroup>
31721 </table>
31722 END
31723  
31724  
31725 =head3 ditaTGroupStatistics($tgroup)
31726  
31727 Return statistics about the rows in a given table
31728  
31729 Parameter Description
31730 1 $tgroup Table group node
31731  
31732 B<Example:>
31733  
31734  
31735 my $a = Data::Edit::Xml::new(<<END);
31736 <table>
31737 <tgroup cols="1">
31738 <colspec/>
31739 <thead>
31740 <row>
31741 <entry>aaaa</entry>
31742 <entry/>
31743 </row>
31744 <row>
31745 <entry>bbbb</entry>
31746 </row>
31747 </thead>
31748 <tbody>
31749 <row>
31750 <entry>cccc</entry>
31751 <entry/>
31752 <entry/>
31753 </row>
31754 <row>
31755 <entry>dddd</entry>
31756 </row>
31757 </tbody>
31758 </tgroup>
31759 </table>
31760 END
31761  
31762 my $g = $a->go_tgroup;
31763  
31764 ok $g->ditaMaximumNumberOfEntriesInATGroupRow == 3;
31765  
31766  
31767 is_deeply $g->ditaTGroupStatistics, # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31768  
31769 bless({
31770 colsAttribute => 1,
31771 colSpec => 1,
31772 maxBody => 3,
31773 maxBodyMinusPadding => 3,
31774 maxHead => 2,
31775 maxHeadMinusPadding => 2,
31776 minBody => 1,
31777 minHead => 1,
31778 rows => 4,
31779 }, "Data::Edit::Xml::Table::Statistics");
31780  
31781 $g->ditaRemoveTGroupTrailingEmptyEntries;
31782  
31783 ok -p $a eq <<END;
31784 <table>
31785 <tgroup cols="1">
31786 <colspec/>
31787 <thead>
31788 <row>
31789 <entry>aaaa</entry>
31790 </row>
31791 <row>
31792 <entry>bbbb</entry>
31793 </row>
31794 </thead>
31795 <tbody>
31796 <row>
31797 <entry>cccc</entry>
31798 </row>
31799 <row>
31800 <entry>dddd</entry>
31801 </row>
31802 </tbody>
31803 </tgroup>
31804 </table>
31805 END
31806  
31807  
31808 =head3 ditaAddColSpecToTGroup($tgroup, $number)
31809  
31810 Add the specified B<$number> of column specification to a specified B<$tgroup> which does not have any already.
31811  
31812 Parameter Description
31813 1 $tgroup Tgroup node
31814 2 $number Number of colspecs to add
31815  
31816 B<Example:>
31817  
31818  
31819 if (1)
31820 {my $a = Data::Edit::Xml::new(<<END);
31821 <table>
31822 <tgroup>
31823 <tbody>
31824 <row><entry/></row>
31825 <row><entry/><entry/></row>
31826 <row><entry/><entry/><entry/></row>
31827 <row><entry/><entry/></row>
31828 <row/>
31829 </tbody>
31830 </tgroup>
31831 </table>
31832 END
31833  
31834 ok 3 == $a->go_tgroup->ditaMaximumNumberOfEntriesInATGroupRow;
31835  
31836 $a->first->ditaAddColSpecToTGroup(3); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31837  
31838  
31839 ok -p $a eq <<END
31840 <table>
31841 <tgroup cols="3">
31842 <colspec colname="c1" colnum="1" colwidth="1*"/>
31843 <colspec colname="c2" colnum="2" colwidth="1*"/>
31844 <colspec colname="c3" colnum="3" colwidth="1*"/>
31845 <tbody>
31846 <row>
31847 <entry/>
31848 </row>
31849 <row>
31850 <entry/>
31851 <entry/>
31852 </row>
31853 <row>
31854 <entry/>
31855 <entry/>
31856 <entry/>
31857 </row>
31858 <row>
31859 <entry/>
31860 <entry/>
31861 </row>
31862 <row/>
31863 </tbody>
31864 </tgroup>
31865 </table>
31866 END
31867 }
31868  
31869  
31870 =head3 ditaFixTGroupColSpec($tgroup)
31871  
31872 Fix the colspec attribute and colspec nodes of the specified B<$tgroup>.
31873  
31874 Parameter Description
31875 1 $tgroup Tgroup node
31876  
31877 B<Example:>
31878  
31879  
31880 if (1)
31881 {my $a = Data::Edit::Xml::new(<<END);
31882 <table>
31883 <tgroup>
31884 <tbody>
31885 <row><entry/></row>
31886 <row><entry/><entry/></row>
31887 <row><entry/><entry/><entry/></row>
31888 <row><entry/><entry/></row>
31889 <row>
31890 <entry>
31891 <table>
31892 <tbody>
31893 <row><entry/><entry/><entry/><entry/><entry/><entry/><entry/></row>
31894 </tbody>
31895 </table>
31896 </entry>
31897 </row>
31898 </tbody>
31899 </tgroup>
31900 </table>
31901 END
31902  
31903  
31904 $a->go_tgroup->ditaFixTGroupColSpec; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
31905  
31906  
31907 ok -p $a eq <<END
31908 <table>
31909 <tgroup cols="3">
31910 <colspec colname="c1" colnum="1" colwidth="1*"/>
31911 <colspec colname="c2" colnum="2" colwidth="1*"/>
31912 <colspec colname="c3" colnum="3" colwidth="1*"/>
31913 <tbody>
31914 <row>
31915 <entry/>
31916 </row>
31917 <row>
31918 <entry/>
31919 <entry/>
31920 </row>
31921 <row>
31922 <entry/>
31923 <entry/>
31924 <entry/>
31925 </row>
31926 <row>
31927 <entry/>
31928 <entry/>
31929 </row>
31930 <row>
31931 <entry>
31932 <table>
31933 <tbody>
31934 <row>
31935 <entry/>
31936 <entry/>
31937 <entry/>
31938 <entry/>
31939 <entry/>
31940 <entry/>
31941 <entry/>
31942 </row>
31943 </tbody>
31944 </table>
31945 </entry>
31946 </row>
31947 </tbody>
31948 </tgroup>
31949 </table>
31950 END
31951 }
31952  
31953  
31954 =head3 ditaRemoveTGroupTrailingEmptyEntries($tgroup)
31955  
31956 Remove empty trailing entry
31957  
31958 Parameter Description
31959 1 $tgroup Table node
31960  
31961 B<Example:>
31962  
31963  
31964 my $a = Data::Edit::Xml::new(<<END);
31965 <table>
31966 <tgroup cols="1">
31967 <colspec/>
31968 <thead>
31969 <row>
31970 <entry>aaaa</entry>
31971 <entry/>
31972 </row>
31973 <row>
31974 <entry>bbbb</entry>
31975 </row>
31976 </thead>
31977 <tbody>
31978 <row>
31979 <entry>cccc</entry>
31980 <entry/>
31981 <entry/>
31982 </row>
31983 <row>
31984 <entry>dddd</entry>
31985 </row>
31986 </tbody>
31987 </tgroup>
31988 </table>
31989 END
31990  
31991 my $g = $a->go_tgroup;
31992  
31993 ok $g->ditaMaximumNumberOfEntriesInATGroupRow == 3;
31994  
31995 is_deeply $g->ditaTGroupStatistics,
31996 bless({
31997 colsAttribute => 1,
31998 colSpec => 1,
31999 maxBody => 3,
32000 maxBodyMinusPadding => 3,
32001 maxHead => 2,
32002 maxHeadMinusPadding => 2,
32003 minBody => 1,
32004 minHead => 1,
32005 rows => 4,
32006 }, "Data::Edit::Xml::Table::Statistics");
32007  
32008  
32009 $g->ditaRemoveTGroupTrailingEmptyEntries; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32010  
32011  
32012 ok -p $a eq <<END;
32013 <table>
32014 <tgroup cols="1">
32015 <colspec/>
32016 <thead>
32017 <row>
32018 <entry>aaaa</entry>
32019 </row>
32020 <row>
32021 <entry>bbbb</entry>
32022 </row>
32023 </thead>
32024 <tbody>
32025 <row>
32026 <entry>cccc</entry>
32027 </row>
32028 <row>
32029 <entry>dddd</entry>
32030 </row>
32031 </tbody>
32032 </tgroup>
32033 </table>
32034 END
32035  
32036  
32037 =head3 fixTGroup($tgroup)
32038  
32039 Fix the specified B<$tgroup> so that each row has the same number of entries with this number reflected in the tgroup.cols= attribute and colspec nodes.
32040  
32041 Parameter Description
32042 1 $tgroup TGroup node
32043  
32044 Use the optional B<@context> parameter to test the context of the specified
32045 B<$node> as understood by method L<at|/at>. If the context is supplied and
32046 B<$node> is not in this context then this method returns B<undef> immediately.
32047  
32048  
32049  
32050 B<Example:>
32051  
32052  
32053 my $a = Data::Edit::Xml::new(<<END);
32054 <table>
32055 <tgroup cols="1">
32056 <colspec/>
32057 <thead>
32058 <row>
32059 <entry>aaaa</entry>
32060 </row>
32061 <row>
32062 <entry>bbbb</entry>
32063 </row>
32064 </thead>
32065 <tbody>
32066 <row>
32067 <entry>cccc</entry>
32068 </row>
32069 <row>
32070 <entry>dddd</entry>
32071 </row>
32072 </tbody>
32073 </tgroup>
32074 </table>
32075 END
32076  
32077 my $g = $a->go_tgroup;
32078  
32079 $g->ditaAddPadEntriesToTGroupRows(2);
32080  
32081 is_deeply $g->ditaTGroupStatistics,
32082 bless({
32083 colsAttribute => 1,
32084 colSpec => 1,
32085 maxBody => 2,
32086 maxBodyMinusPadding => 2,
32087 maxHead => 2,
32088 maxHeadMinusPadding => 2,
32089 minBody => 2,
32090 minHead => 2,
32091 rows => 4,
32092 }, "Data::Edit::Xml::Table::Statistics");
32093  
32094  
32095 $g->fixTGroup; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32096  
32097  
32098 ok -p $a eq <<END;
32099 <table>
32100 <tgroup cols="2">
32101 <colspec colname="c1" colnum="1" colwidth="1*"/>
32102 <colspec colname="c2" colnum="2" colwidth="1*"/>
32103 <thead>
32104 <row>
32105 <entry>aaaa</entry>
32106 <entry/>
32107 </row>
32108 <row>
32109 <entry>bbbb</entry>
32110 <entry/>
32111 </row>
32112 </thead>
32113 <tbody>
32114 <row>
32115 <entry>cccc</entry>
32116 <entry/>
32117 </row>
32118 <row>
32119 <entry>dddd</entry>
32120 <entry/>
32121 </row>
32122 </tbody>
32123 </tgroup>
32124 </table>
32125 END
32126  
32127 is_deeply $g->ditaTGroupStatistics,
32128 bless({
32129 colsAttribute => 2,
32130 colSpec => 2,
32131 maxBody => 2,
32132 maxBodyMinusPadding => 2,
32133 maxHead => 2,
32134 maxHeadMinusPadding => 2,
32135 minBody => 2,
32136 minHead => 2,
32137 rows => 4,
32138  
32139 }, "Data::Edit::Xml::Table::Statistics");
32140  
32141 $a->fixTable;
32142 is_deeply $g->ditaTGroupStatistics,
32143 bless({
32144 colsAttribute => 2,
32145 colSpec => 2,
32146 maxBody => 2,
32147 maxBodyMinusPadding => 2,
32148 maxHead => 2,
32149 maxHeadMinusPadding => 2,
32150 minBody => 2,
32151 minHead => 2,
32152 rows => 4,
32153 }, "Data::Edit::Xml::Table::Statistics");
32154  
32155  
32156  
32157 =head3 fixTable($table)
32158  
32159 Fix the specified B<$table> so that each row has the same number of entries with this number reflected in the tgroup.cols= attribute and colspec nodes.
32160  
32161 Parameter Description
32162 1 $table Table node
32163  
32164 B<Example:>
32165  
32166  
32167 my $a = Data::Edit::Xml::new(<<END);
32168 <table>
32169 <tgroup cols="1">
32170 <colspec/>
32171 <thead>
32172 <row>
32173 <entry>aaaa</entry>
32174 </row>
32175 <row>
32176 <entry>bbbb</entry>
32177 </row>
32178 </thead>
32179 <tbody>
32180 <row>
32181 <entry>cccc</entry>
32182 </row>
32183 <row>
32184 <entry>dddd</entry>
32185 </row>
32186 </tbody>
32187 </tgroup>
32188 </table>
32189 END
32190  
32191 my $g = $a->go_tgroup;
32192  
32193 $g->ditaAddPadEntriesToTGroupRows(2);
32194  
32195 is_deeply $g->ditaTGroupStatistics,
32196 bless({
32197 colsAttribute => 1,
32198 colSpec => 1,
32199 maxBody => 2,
32200 maxBodyMinusPadding => 2,
32201 maxHead => 2,
32202 maxHeadMinusPadding => 2,
32203 minBody => 2,
32204 minHead => 2,
32205 rows => 4,
32206 }, "Data::Edit::Xml::Table::Statistics");
32207  
32208 $g->fixTGroup;
32209  
32210 ok -p $a eq <<END;
32211 <table>
32212 <tgroup cols="2">
32213 <colspec colname="c1" colnum="1" colwidth="1*"/>
32214 <colspec colname="c2" colnum="2" colwidth="1*"/>
32215 <thead>
32216 <row>
32217 <entry>aaaa</entry>
32218 <entry/>
32219 </row>
32220 <row>
32221 <entry>bbbb</entry>
32222 <entry/>
32223 </row>
32224 </thead>
32225 <tbody>
32226 <row>
32227 <entry>cccc</entry>
32228 <entry/>
32229 </row>
32230 <row>
32231 <entry>dddd</entry>
32232 <entry/>
32233 </row>
32234 </tbody>
32235 </tgroup>
32236 </table>
32237 END
32238  
32239 is_deeply $g->ditaTGroupStatistics,
32240 bless({
32241 colsAttribute => 2,
32242 colSpec => 2,
32243 maxBody => 2,
32244 maxBodyMinusPadding => 2,
32245 maxHead => 2,
32246 maxHeadMinusPadding => 2,
32247 minBody => 2,
32248 minHead => 2,
32249 rows => 4,
32250  
32251 }, "Data::Edit::Xml::Table::Statistics");
32252  
32253  
32254 $a->fixTable; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32255  
32256 is_deeply $g->ditaTGroupStatistics,
32257 bless({
32258 colsAttribute => 2,
32259 colSpec => 2,
32260 maxBody => 2,
32261 maxBodyMinusPadding => 2,
32262 maxHead => 2,
32263 maxHeadMinusPadding => 2,
32264 minBody => 2,
32265 minHead => 2,
32266 rows => 4,
32267 }, "Data::Edit::Xml::Table::Statistics");
32268  
32269  
32270  
32271 =head3 fixEntryColSpan($entry)
32272  
32273 Fix the colspan on an entry assumed to be under row, tbody, tgroup with @cols and colspecs' set
32274  
32275 Parameter Description
32276 1 $entry Entry
32277  
32278 B<Example:>
32279  
32280  
32281 my $a = Data::Edit::Xml::new(<<END);
32282 <table>
32283 <tgroup cols="7">
32284 <colspec colname="a"/>
32285 <colspec colname="b"/>
32286 <colspec colname="c"/>
32287 <colspec colname="d"/>
32288 <colspec colname="e"/>
32289 <colspec colname="f"/>
32290 <colspec colname="g"/>
32291 <tbody>
32292 <row>
32293 <entry colspan="7"/>
32294 </row>
32295 <row>
32296 <entry colspan="2"/>
32297 <entry colspan="3"/>
32298 <entry colspan="2"/>
32299 </row>
32300 <row>
32301 <entry/>
32302 <entry rowspan="2"/>
32303 <entry colspan="2"/>
32304 <entry colspan="2"/>
32305 <entry/>
32306 </row>
32307 </tbody>
32308 </tgroup>
32309 </table>
32310 END
32311  
32312 $a->by(sub
32313 {my ($e) = @_;
32314 if ($e->at_entry)
32315  
32316 {$e->fixEntryColSpan; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32317  
32318 $e->fixEntryRowSpan;
32319 }
32320 });
32321  
32322 ok -p $a eq <<END;
32323 <table>
32324 <tgroup cols="7">
32325 <colspec colname="a"/>
32326 <colspec colname="b"/>
32327 <colspec colname="c"/>
32328 <colspec colname="d"/>
32329 <colspec colname="e"/>
32330 <colspec colname="f"/>
32331 <colspec colname="g"/>
32332 <tbody>
32333 <row>
32334 <entry nameend="g" namest="a"/>
32335 </row>
32336 <row>
32337 <entry nameend="b" namest="a"/>
32338 <entry nameend="e" namest="c"/>
32339 <entry nameend="g" namest="f"/>
32340 </row>
32341 <row>
32342 <entry/>
32343 <entry morerows="1"/>
32344 <entry nameend="d" namest="c"/>
32345 <entry nameend="f" namest="e"/>
32346 <entry/>
32347 </row>
32348 </tbody>
32349 </tgroup>
32350 </table>
32351 END
32352  
32353  
32354 =head3 fixEntryRowSpan($entry)
32355  
32356 Fix the rowspan on an entry
32357  
32358 Parameter Description
32359 1 $entry Entry
32360  
32361 B<Example:>
32362  
32363  
32364 my $a = Data::Edit::Xml::new(<<END);
32365 <table>
32366 <tgroup cols="7">
32367 <colspec colname="a"/>
32368 <colspec colname="b"/>
32369 <colspec colname="c"/>
32370 <colspec colname="d"/>
32371 <colspec colname="e"/>
32372 <colspec colname="f"/>
32373 <colspec colname="g"/>
32374 <tbody>
32375 <row>
32376 <entry colspan="7"/>
32377 </row>
32378 <row>
32379 <entry colspan="2"/>
32380 <entry colspan="3"/>
32381 <entry colspan="2"/>
32382 </row>
32383 <row>
32384 <entry/>
32385 <entry rowspan="2"/>
32386 <entry colspan="2"/>
32387 <entry colspan="2"/>
32388 <entry/>
32389 </row>
32390 </tbody>
32391 </tgroup>
32392 </table>
32393 END
32394  
32395 $a->by(sub
32396 {my ($e) = @_;
32397 if ($e->at_entry)
32398 {$e->fixEntryColSpan;
32399  
32400 $e->fixEntryRowSpan; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32401  
32402 }
32403 });
32404  
32405 ok -p $a eq <<END;
32406 <table>
32407 <tgroup cols="7">
32408 <colspec colname="a"/>
32409 <colspec colname="b"/>
32410 <colspec colname="c"/>
32411 <colspec colname="d"/>
32412 <colspec colname="e"/>
32413 <colspec colname="f"/>
32414 <colspec colname="g"/>
32415 <tbody>
32416 <row>
32417 <entry nameend="g" namest="a"/>
32418 </row>
32419 <row>
32420 <entry nameend="b" namest="a"/>
32421 <entry nameend="e" namest="c"/>
32422 <entry nameend="g" namest="f"/>
32423 </row>
32424 <row>
32425 <entry/>
32426 <entry morerows="1"/>
32427 <entry nameend="d" namest="c"/>
32428 <entry nameend="f" namest="e"/>
32429 <entry/>
32430 </row>
32431 </tbody>
32432 </tgroup>
32433 </table>
32434 END
32435  
32436  
32437 =head3 ditaConvertDlToUl($dl)
32438  
32439 Convert a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<$dl> to a B<ul> if each B<dlentry> has only B<dt> or B<dl> elements but not both. Return B<undef> if such a conversion is not possible else return the new B<ul> node.
32440  
32441 Parameter Description
32442 1 $dl Dl
32443  
32444 B<Example:>
32445  
32446  
32447  
32448 my $a = Data::Edit::Xml::new(<<END);
32449 <dl>
32450 <dlentry><dt>A</dt><dt>B</dt><dt>C</dt></dlentry>
32451 <dlentry><dd>a</dd><dd>b</dd><dd>b</dd></dlentry>
32452 </dl>
32453 END
32454  
32455  
32456 $a->ditaConvertDlToUl; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32457  
32458  
32459 ok -p $a eq <<END;
32460 <ul>
32461 <li>A</li>
32462 <li>B</li>
32463 <li>C</li>
32464 <li>a</li>
32465 <li>b</li>
32466 <li>b</li>
32467 </ul>
32468 END
32469  
32470 my $b = Data::Edit::Xml::new(<<END);
32471 <dl>
32472 <dlentry><dt>A</dt><dd>a</dd></dlentry>
32473 </dl>
32474 END
32475  
32476  
32477 ok !$a->ditaConvertDlToUl; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32478  
32479  
32480  
32481 =head3 ditaConvertOlToSubSteps($ol, @context)
32482  
32483 Convert a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<$ul> to B<substeps> else B<undef> if this is not possible.
32484  
32485 Parameter Description
32486 1 $ol Ul
32487 2 @context Context
32488  
32489 B<Example:>
32490  
32491  
32492 my $a = Data::Edit::Xml::new(<<END);
32493 <ol>
32494 <li>A</li>
32495 <li>B</li>
32496 <li>C</li>
32497 </ol>
32498 END
32499  
32500  
32501 $a->ditaConvertOlToSubSteps; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32502  
32503  
32504 ok -p $a eq <<END;
32505 <substeps>
32506 <substep>
32507 <cmd>A</cmd>
32508 </substep>
32509 <substep>
32510 <cmd>B</cmd>
32511 </substep>
32512 <substep>
32513 <cmd>C</cmd>
32514 </substep>
32515 </substeps>
32516 END
32517  
32518  
32519 =head3 ditaConvertUlToSubSteps($ul, @context)
32520  
32521 Convert a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<$ol> to B<substeps> else B<undef> if this is not possible.
32522  
32523 Parameter Description
32524 1 $ul Ul
32525 2 @context Context
32526  
32527 B<Example:>
32528  
32529  
32530 my $a = Data::Edit::Xml::new(<<END);
32531 <ul>
32532 <li>A</li>
32533 <li>B</li>
32534 <li>C</li>
32535 </ul>
32536 END
32537  
32538  
32539 $a->ditaConvertUlToSubSteps; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32540  
32541  
32542 ok -p $a eq <<END;
32543 <substeps>
32544 <substep>
32545 <cmd>A</cmd>
32546 </substep>
32547 <substep>
32548 <cmd>B</cmd>
32549 </substep>
32550 <substep>
32551 <cmd>C</cmd>
32552 </substep>
32553 </substeps>
32554 END
32555  
32556  
32557 =head3 ditaConvertFromHtmlDl($dl)
32558  
32559 Convert a B<Html> B<$dl> to a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<dl> or return B<undef> if this is not possible.
32560  
32561 Parameter Description
32562 1 $dl Dl
32563  
32564 B<Example:>
32565  
32566  
32567 my $a = Data::Edit::Xml::new(<<END);
32568 <dl>
32569 <dt>t11</dt>
32570 <dd>d11</dd>
32571 <dd>d12</dd>
32572 <dt>t21</dt>
32573 <dd>d21</dd>
32574 <dd>d22</dd>
32575 <dt>t31</dt>
32576 <dd>d31</dd>
32577 <dd>d32</dd>
32578 </dl>
32579 END
32580  
32581  
32582 $a->ditaConvertFromHtmlDl; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32583  
32584  
32585 ok -p $a eq <<END;
32586 <dl>
32587 <dlentry>
32588 <dt>t11</dt>
32589 <dd>d11</dd>
32590 <dd>d12</dd>
32591 </dlentry>
32592 <dlentry>
32593 <dt>t21</dt>
32594 <dd>d21</dd>
32595 <dd>d22</dd>
32596 </dlentry>
32597 <dlentry>
32598 <dt>t31</dt>
32599 <dd>d31</dd>
32600 <dd>d32</dd>
32601 </dlentry>
32602 </dl>
32603 END
32604  
32605  
32606 =head3 ditaConvertSimpleTableToTable($simpleTable)
32607  
32608 Convert a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<simpletable> to a B<table>.
32609  
32610 Parameter Description
32611 1 $simpleTable Simple table
32612  
32613 B<Example:>
32614  
32615  
32616 my $a = Data::Edit::Xml::new(<<END);
32617 <simpletable>
32618 <sthead>
32619 <stentry>Symbol</stentry>
32620 <stentry>Meaning</stentry>
32621 </sthead>
32622 <strow>
32623 <stentry>aaaa</stentry>
32624 <stentry>bbbb</stentry>
32625 </strow>
32626 </simpletable>
32627 END
32628  
32629  
32630 $a->ditaConvertSimpleTableToTable; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32631  
32632  
32633 ok -p $a eq <<END;
32634 <table>
32635 <tgroup cols="2">
32636 <colspec colname="c1" colnum="1" colwidth="1*"/>
32637 <colspec colname="c2" colnum="2" colwidth="1*"/>
32638 <thead>
32639 <row>
32640 <entry>Symbol</entry>
32641 <entry>Meaning</entry>
32642 </row>
32643 </thead>
32644 <tbody>
32645 <row>
32646 <entry>aaaa</entry>
32647 <entry>bbbb</entry>
32648 </row>
32649 </tbody>
32650 </tgroup>
32651 </table>
32652 END
32653  
32654  
32655 =head3 ditaCouldConvertConceptToTask($concept)
32656  
32657 Check whether a concept could be converted to a task
32658  
32659 Parameter Description
32660 1 $concept Concept to check
32661  
32662 B<Example:>
32663  
32664  
32665 my $c = Data::Edit::Xml::new(<<END);
32666 <concept id="c1">
32667 <title>Title Text</title>
32668 <conbody>
32669 <p>Concept 11</p>
32670 <section>
32671 <p>A section 11</p>
32672 </section>
32673 <section>
32674 <p>A section 22</p>
32675 </section>
32676 <p>Concept 222</p>
32677 </conbody>
32678 </concept>
32679 END
32680  
32681 my $r = $c->ditaConvertConceptToReference;
32682  
32683 ok -p $c eq <<END;
32684 <reference id="c1">
32685 <title>Title Text</title>
32686 <refbody>
32687 <section>
32688 <p>Concept 11</p>
32689 </section>
32690 <section>
32691 <p>A section 11</p>
32692 </section>
32693 <section>
32694 <p>A section 22</p>
32695 </section>
32696 <section>
32697 <p>Concept 222</p>
32698 </section>
32699 </refbody>
32700 </reference>
32701 END
32702  
32703 my $C = $c->ditaConvertReferenceToConcept;
32704 ok -p $C eq <<END;
32705 <concept id="c1">
32706 <title>Title Text</title>
32707 <conbody>
32708 <p>Concept 11</p>
32709 <p>A section 11</p>
32710 <p>A section 22</p>
32711 <p>Concept 222</p>
32712 </conbody>
32713 </concept>
32714 END
32715  
32716  
32717 ok !$C->ditaCouldConvertConceptToTask; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32718  
32719  
32720 my $ref = Data::Edit::Xml::new(<<END);
32721 <reference id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
32722 <title>Testing the S3 Feature for PM 4 1</title>
32723 <refbody>
32724 <section>
32725 <p>To test the S# feature:</p>
32726 <ol>
32727 <li>
32728 <p>Set the PCIe link state to L1.2.</p>
32729 </li>
32730 <li>
32731 <p>Issue the command: PM 4 1 command.</p>
32732 </li>
32733 </ol>
32734 </section>
32735 </refbody>
32736 </reference>
32737 END
32738  
32739 my $concept = $ref->ditaConvertReferenceToConcept;
32740  
32741 ok -p $concept eq <<END;
32742 <concept id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
32743 <title>Testing the S3 Feature for PM 4 1</title>
32744 <conbody>
32745 <p>To test the S# feature:</p>
32746 <ol>
32747 <li>
32748 <p>Set the PCIe link state to L1.2.</p>
32749 </li>
32750 <li>
32751 <p>Issue the command: PM 4 1 command.</p>
32752 </li>
32753 </ol>
32754 </conbody>
32755 </concept>
32756 END
32757  
32758  
32759 ok $concept->ditaCouldConvertConceptToTask; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32760  
32761 my $task = $concept->ditaConvertConceptToTask;
32762  
32763 ok -p $task eq <<END
32764 <task id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
32765 <title>Testing the S3 Feature for PM 4 1</title>
32766 <taskbody>
32767 <context>
32768 <p>To test the S# feature:</p>
32769 </context>
32770 <steps>
32771 <step>
32772 <cmd>Set the PCIe link state to L1.2.</cmd>
32773 </step>
32774 <step>
32775 <cmd>Issue the command: PM 4 1 command.</cmd>
32776 </step>
32777 </steps>
32778 <result/>
32779 </taskbody>
32780 </task>
32781 END
32782  
32783  
32784 =head3 ditaConvertConceptToTask($node, @context)
32785  
32786 Convert a Dita B<concept> to a B<task> by representing B<ol> as B<steps>. Return B<undef> if the conversion is not possible because there are no B<ol> else return the specified B<$concept> as as B<task>.
32787  
32788 Parameter Description
32789 1 $node Node
32790 2 @context Optional context
32791  
32792 B<Example:>
32793  
32794  
32795 my $a = Data::Edit::Xml::new(<<END);
32796 <concept id="x1">
32797 <title/>
32798 <conbody>
32799 <p>context</p>
32800 <ol>
32801 <li> <note>note</note><image/><fig/> <p>cmd</p> <p>info</p> </li>
32802 <li>cmd text<p>info</p> </li>
32803 </ol>
32804 <p>between</p>
32805 <ol>
32806 <li>
32807 <p>cmd <note>first in info</note><note>second in info</note></p>
32808 <p>info</p>
32809 </li>
32810 <li> cmd text <p>info</p> </li>
32811 <li>
32812 <ol> <li>substep 1</li> <li>substep 2</li> </ol>
32813 </li>
32814 </ol>
32815 <p>results</p>
32816 </conbody>
32817 </concept>
32818 END
32819  
32820  
32821 $a->ditaConvertConceptToTask; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32822  
32823  
32824 ok nws(-p $a) eq nws(<<END);
32825 <task id="x1">
32826 <title/>
32827 <taskbody>
32828 <context>
32829 <p>context</p>
32830 </context>
32831 <steps>
32832 <step>
32833 <note>note</note>
32834 <note>
32835 <image/>
32836 </note>
32837 <note>
32838 <fig/>
32839 </note>
32840 <cmd>cmd</cmd>
32841 <info>
32842 <p>info</p>
32843 </info>
32844 </step>
32845 <step>
32846 <cmd>cmd text</cmd>
32847 <info>
32848 <p>info</p>
32849 </info>
32850 </step>
32851 <stepsection>
32852 <p>between</p>
32853 </stepsection>
32854 <step>
32855 <cmd>cmd </cmd>
32856 <info>
32857 <note>first in info</note>
32858 <note>second in info</note>
32859 <p>info</p>
32860 </info>
32861 </step>
32862 <step>
32863 <cmd> cmd text </cmd>
32864 <info>
32865 <p>info</p>
32866 </info>
32867 </step>
32868 <step>
32869 <cmd>Choose one of the following:</cmd>
32870 <choices>
32871 <choice>substep 1</choice>
32872 <choice>substep 2</choice>
32873 </choices>
32874 </step>
32875 </steps>
32876 <result>
32877 <p>results</p>
32878 </result>
32879  
32880 </taskbody>
32881 </task>
32882 END
32883  
32884 my $ref = Data::Edit::Xml::new(<<END);
32885 <reference id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
32886 <title>Testing the S3 Feature for PM 4 1</title>
32887 <refbody>
32888 <section>
32889 <p>To test the S# feature:</p>
32890 <ol>
32891 <li>
32892 <p>Set the PCIe link state to L1.2.</p>
32893 </li>
32894 <li>
32895 <p>Issue the command: PM 4 1 command.</p>
32896 </li>
32897 </ol>
32898 </section>
32899 </refbody>
32900 </reference>
32901 END
32902  
32903 my $concept = $ref->ditaConvertReferenceToConcept;
32904  
32905 ok -p $concept eq <<END;
32906 <concept id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
32907 <title>Testing the S3 Feature for PM 4 1</title>
32908 <conbody>
32909 <p>To test the S# feature:</p>
32910 <ol>
32911 <li>
32912 <p>Set the PCIe link state to L1.2.</p>
32913 </li>
32914 <li>
32915 <p>Issue the command: PM 4 1 command.</p>
32916 </li>
32917 </ol>
32918 </conbody>
32919 </concept>
32920 END
32921  
32922 ok $concept->ditaCouldConvertConceptToTask;
32923  
32924 my $task = $concept->ditaConvertConceptToTask; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32925  
32926  
32927 ok -p $task eq <<END
32928 <task id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
32929 <title>Testing the S3 Feature for PM 4 1</title>
32930 <taskbody>
32931 <context>
32932 <p>To test the S# feature:</p>
32933 </context>
32934 <steps>
32935 <step>
32936 <cmd>Set the PCIe link state to L1.2.</cmd>
32937 </step>
32938 <step>
32939 <cmd>Issue the command: PM 4 1 command.</cmd>
32940 </step>
32941 </steps>
32942 <result/>
32943 </taskbody>
32944 </task>
32945 END
32946  
32947  
32948 B<ct> is a synonym for L<ditaConvertConceptToTask|/ditaConvertConceptToTask>.
32949  
32950  
32951 =head3 ditaConvertReferenceToConcept($reference)
32952  
32953 Convert a Dita B<reference> to a B<concept> by unwrapping sections. Return B<undef> if the conversion is not possible because there are no B<ol> else return the specified B<$reference> as as B<concept>.
32954  
32955 Parameter Description
32956 1 $reference Reference
32957  
32958 B<Example:>
32959  
32960  
32961 my $ref = Data::Edit::Xml::new(<<END);
32962 <reference id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
32963 <title>Testing the S3 Feature for PM 4 1</title>
32964 <refbody>
32965 <section>
32966 <p>To test the S# feature:</p>
32967 <ol>
32968 <li>
32969 <p>Set the PCIe link state to L1.2.</p>
32970 </li>
32971 <li>
32972 <p>Issue the command: PM 4 1 command.</p>
32973 </li>
32974 </ol>
32975 </section>
32976 </refbody>
32977 </reference>
32978 END
32979  
32980  
32981 my $concept = $ref->ditaConvertReferenceToConcept; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
32982  
32983  
32984 ok -p $concept eq <<END;
32985 <concept id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
32986 <title>Testing the S3 Feature for PM 4 1</title>
32987 <conbody>
32988 <p>To test the S# feature:</p>
32989 <ol>
32990 <li>
32991 <p>Set the PCIe link state to L1.2.</p>
32992 </li>
32993 <li>
32994 <p>Issue the command: PM 4 1 command.</p>
32995 </li>
32996 </ol>
32997 </conbody>
32998 </concept>
32999 END
33000  
33001 ok $concept->ditaCouldConvertConceptToTask;
33002 my $task = $concept->ditaConvertConceptToTask;
33003  
33004 ok -p $task eq <<END
33005 <task id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
33006 <title>Testing the S3 Feature for PM 4 1</title>
33007 <taskbody>
33008 <context>
33009 <p>To test the S# feature:</p>
33010 </context>
33011 <steps>
33012 <step>
33013 <cmd>Set the PCIe link state to L1.2.</cmd>
33014 </step>
33015 <step>
33016 <cmd>Issue the command: PM 4 1 command.</cmd>
33017 </step>
33018 </steps>
33019 <result/>
33020 </taskbody>
33021 </task>
33022 END
33023  
33024  
33025 =head3 ditaConvertReferenceToTask($reference)
33026  
33027 Convert a Dita B<reference> to a B<task> in situ by representing B<ol> as B<steps>. Return B<undef> if the conversion is not possible because there are no such B<ol> else return the specified B<$reference> as as B<task>.
33028  
33029 Parameter Description
33030 1 $reference Reference
33031  
33032 B<Example:>
33033  
33034  
33035 my $ref = Data::Edit::Xml::new(<<END);
33036 <reference id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
33037 <title>Testing the S3 Feature for PM 4 1</title>
33038 <refbody>
33039 <section>
33040 <p>To test the S# feature:</p>
33041 <ol>
33042 <li>
33043 <p>Set the PCIe link state to L1.2.</p>
33044 </li>
33045 <li>
33046 <p>Issue the command: PM 4 1 command.</p>
33047 </li>
33048 </ol>
33049 </section>
33050 </refbody>
33051 </reference>
33052 END
33053  
33054  
33055 my $task = $ref->ditaConvertReferenceToTask; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33056  
33057  
33058 ok -p $task eq <<END
33059 <task id="GUID-0cab6472-6f2a-e46a-9b6d-16649416ab53">
33060 <title>Testing the S3 Feature for PM 4 1</title>
33061 <taskbody>
33062 <context>
33063 <p>To test the S# feature:</p>
33064 </context>
33065 <steps>
33066 <step>
33067 <cmd>Set the PCIe link state to L1.2.</cmd>
33068 </step>
33069 <step>
33070 <cmd>Issue the command: PM 4 1 command.</cmd>
33071 </step>
33072 </steps>
33073 <result/>
33074 </taskbody>
33075 </task>
33076 END
33077  
33078  
33079 =head3 ditaConvertConceptToReference($concept)
33080  
33081 Convert a Dita B<concept> to a B<reference>. Return B<undef> if the conversion is not possible else return the specified B<$concept> as as B<reference>.
33082  
33083 Parameter Description
33084 1 $concept Concept
33085  
33086 B<Example:>
33087  
33088  
33089 my $c = Data::Edit::Xml::new(<<END);
33090 <concept id="c1">
33091 <title>Title Text</title>
33092 <conbody>
33093 <p>Concept 11</p>
33094 <section>
33095 <p>A section 11</p>
33096 </section>
33097 <section>
33098 <p>A section 22</p>
33099 </section>
33100 <p>Concept 222</p>
33101 </conbody>
33102 </concept>
33103 END
33104  
33105  
33106 my $r = $c->ditaConvertConceptToReference; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33107  
33108  
33109 ok -p $c eq <<END;
33110 <reference id="c1">
33111 <title>Title Text</title>
33112 <refbody>
33113 <section>
33114 <p>Concept 11</p>
33115 </section>
33116 <section>
33117 <p>A section 11</p>
33118 </section>
33119 <section>
33120 <p>A section 22</p>
33121 </section>
33122 <section>
33123 <p>Concept 222</p>
33124 </section>
33125 </refbody>
33126 </reference>
33127 END
33128  
33129 my $C = $c->ditaConvertReferenceToConcept;
33130 ok -p $C eq <<END;
33131 <concept id="c1">
33132 <title>Title Text</title>
33133 <conbody>
33134 <p>Concept 11</p>
33135 <p>A section 11</p>
33136 <p>A section 22</p>
33137 <p>Concept 222</p>
33138 </conbody>
33139 </concept>
33140 END
33141  
33142 ok !$C->ditaCouldConvertConceptToTask;
33143  
33144  
33145 =head3 ditaConvertTopicToTask($x)
33146  
33147 Convert a topic that is not already a task into a task
33148  
33149 Parameter Description
33150 1 $x Topic parse tree
33151  
33152 B<Example:>
33153  
33154  
33155 my $a = Data::Edit::Xml::new(<<END);
33156 <concept id="c1">
33157 <title/>
33158 <conbody>
33159 <p>results</p>
33160 <ol><li/>Click</ol>
33161 </conbody>
33162 </concept>
33163 END
33164  
33165  
33166 $a->ditaConvertTopicToTask; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33167  
33168  
33169 ok nws(-p $a) eq nws(<<END);
33170 <task id="c1">
33171 <title/>
33172 <taskbody>
33173 <context>
33174 <p>results</p>
33175 </context>
33176 <steps>
33177 <step>
33178 <cmd/>
33179 </step>
33180 Click
33181 </steps>
33182 <result/>
33183 </taskbody>
33184 </task>
33185 END
33186  
33187  
33188 =head3 ditaConvertSectionToConcept($section)
33189  
33190 Convert a Dita B<$section> to a B<concept>. Return B<undef> if the conversion is not possible else return the specified B<$section> as as B<concept>.
33191  
33192 Parameter Description
33193 1 $section Section
33194  
33195 B<Example:>
33196  
33197  
33198 my $a = Data::Edit::Xml::new(<<END);
33199 <section id="a">
33200 <title>title</title>
33201 <p>text</p>
33202 </section>
33203 END
33204  
33205  
33206 ok -p $a->ditaConvertSectionToConcept eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33207  
33208 <concept id="a">
33209 <title>title</title>
33210 <conbody>
33211 <p>text</p>
33212 </conbody>
33213 </concept>
33214 END
33215  
33216 ok -p $a->ditaConvertConceptToSection eq <<END;
33217 <section id="a">
33218 <title>title</title>
33219 <p>text</p>
33220 </section>
33221 END
33222  
33223  
33224 B<sc> is a synonym for L<ditaConvertSectionToConcept|/ditaConvertSectionToConcept>.
33225  
33226  
33227 =head3 ditaConvertConceptToSection($concept)
33228  
33229 Convert a Dita B<concept> to a B<$section> . Return B<undef> if the conversion is not possible else return the specified B<$section> as as B<concept>.
33230  
33231 Parameter Description
33232 1 $concept Section
33233  
33234 B<Example:>
33235  
33236  
33237 my $a = Data::Edit::Xml::new(<<END);
33238 <section id="a">
33239 <title>title</title>
33240 <p>text</p>
33241 </section>
33242 END
33243  
33244 ok -p $a->ditaConvertSectionToConcept eq <<END;
33245 <concept id="a">
33246 <title>title</title>
33247 <conbody>
33248 <p>text</p>
33249 </conbody>
33250 </concept>
33251 END
33252  
33253  
33254 ok -p $a->ditaConvertConceptToSection eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33255  
33256 <section id="a">
33257 <title>title</title>
33258 <p>text</p>
33259 </section>
33260 END
33261  
33262  
33263 B<cs> is a synonym for L<ditaConvertConceptToSection|/ditaConvertConceptToSection>.
33264  
33265  
33266 =head3 ditaConvertSectionToReference($section)
33267  
33268 Convert a Dita B<$section> to a B<reference>. Return B<undef> if the conversion is not possible else return the specified B<$section> as as B<reference>.
33269  
33270 Parameter Description
33271 1 $section Section
33272  
33273 B<Example:>
33274  
33275  
33276 my $a = Data::Edit::Xml::new(<<END);
33277 <section id="a">
33278 <title>title</title>
33279 <p>text</p>
33280 </section>
33281 END
33282  
33283  
33284 ok -p $a->ditaConvertSectionToReference eq <<END # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33285  
33286 <reference id="a">
33287 <title>title</title>
33288 <refbody>
33289 <section>
33290 <p>text</p>
33291 </section>
33292 </refbody>
33293 </reference>
33294 END
33295  
33296  
33297 =head3 ditaConvertSectionToTask($section)
33298  
33299 Convert a Dita B<$section> to a B<task>. Return B<undef> if the conversion is not possible else return the specified B<$section> as as B<task>.
33300  
33301 Parameter Description
33302 1 $section Section
33303  
33304 B<Example:>
33305  
33306  
33307 my $a = Data::Edit::Xml::new(<<END);
33308 <section id="a">
33309 <title>title</title>
33310 <ol>
33311 <li>step1</li>
33312 <li>step2</li>
33313 </ol>
33314 </section>
33315 END
33316  
33317  
33318 ok -p $a->ditaConvertSectionToTask eq <<END # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33319  
33320 <task id="a">
33321 <title>title</title>
33322 <taskbody>
33323 <context/>
33324 <steps>
33325 <step>
33326 <cmd>step1</cmd>
33327 </step>
33328 <step>
33329 <cmd>step2</cmd>
33330 </step>
33331 </steps>
33332 <result/>
33333 </taskbody>
33334 </task>
33335 END
33336  
33337  
33338 =head3 ditaObviousChanges($node)
33339  
33340 Make obvious changes to a L<parse|/parse> tree to make it look more like L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html>.
33341  
33342 Parameter Description
33343 1 $node Node
33344  
33345 B<Example:>
33346  
33347  
33348 {my $a = Data::Edit::Xml::new(<<END);
33349 <dita>
33350 <ol>
33351 <li><para>aaa</para></li>
33352 <li><para>bbb</para></li>
33353 </ol>
33354 </dita>
33355 END
33356  
33357  
33358 $a->ditaObviousChanges; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33359  
33360  
33361 ok -p $a eq <<END;
33362 <dita>
33363 <ol>
33364 <li>
33365 <p>aaa</p>
33366 </li>
33367 <li>
33368 <p>bbb</p>
33369 </li>
33370 </ol>
33371 </dita>
33372 END
33373  
33374  
33375 =head3 ditaXrefs($x)
33376  
33377 Make obvious changes to all the B<xref>s found in a L<parse|/parse> tree to make them more useful in L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html>.
33378  
33379 Parameter Description
33380 1 $x Parse tree
33381  
33382 B<Example:>
33383  
33384  
33385 my $a = Data::Edit::Xml::new(<<END);
33386 <body>
33387 <xref href="http://www.org">a</xref>
33388 </body>
33389 END
33390  
33391  
33392 $a->ditaXrefs; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33393  
33394  
33395 ok -p $a eq <<END;
33396 <body>
33397 <p>
33398 <xref format="html" href="http://www.org" scope="external">a</xref>
33399 </p>
33400 </body>
33401 END
33402  
33403  
33404 =head3 ditaSampleConcept(@options)
33405  
33406 Sample concept
33407  
33408 Parameter Description
33409 1 @options Options for concept
33410  
33411 B<Example:>
33412  
33413  
33414  
33415 ok Data::Edit::Xml::ditaSampleConcept # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33416  
33417 (title=>q(New Concept),
33418 )->prettyString eq <<END;
33419 <concept id="GUID-a5405560-67e7-0cd1-9188-9a2546d13a37">
33420 <title id="title">New Concept</title>
33421 <conbody>
33422 <p>Please provide the body of this concept using the body keyword</p>
33423 </conbody>
33424 </concept>
33425 END
33426  
33427  
33428 This is a static method and so should either be imported or invoked as:
33429  
33430 Data::Edit::Xml::ditaSampleConcept
33431  
33432  
33433 =head3 ditaSampleTask(@options)
33434  
33435 Sample task
33436  
33437 Parameter Description
33438 1 @options Options for task
33439  
33440 B<Example:>
33441  
33442  
33443  
33444 ok Data::Edit::Xml::ditaSampleTask # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33445  
33446 (title=>q(New Task),
33447 )->prettyString eq <<END;
33448 <task id="GUID-2ac5c2a6-2475-d5d4-4ce6-d68fdf2102e3">
33449 <title id="title">New Task</title>
33450 <taskbody>
33451 <context/>
33452 <steps/>
33453 <result/>
33454 </taskbody>
33455 </task>
33456 END
33457  
33458  
33459 This is a static method and so should either be imported or invoked as:
33460  
33461 Data::Edit::Xml::ditaSampleTask
33462  
33463  
33464 =head3 ditaSampleBookMap(@options)
33465  
33466 Sample bookmap
33467  
33468 Parameter Description
33469 1 @options Options for bookmap
33470  
33471 B<Example:>
33472  
33473  
33474  
33475  
33476 my $a = Data::Edit::Xml::ditaSampleBookMap # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33477  
33478 (author=>q(mim),
33479 chapters=>Data::Edit::Xml::new(<<END));
33480 <a>
33481 <b>
33482 <c/>
33483 </b>
33484 </a>
33485 END
33486  
33487 ok $a->isADitaMap;
33488 ok !$a->first->isADitaMap;
33489  
33490 ok -p $a eq <<END;
33491 <bookmap id="GUID-3b04e859-bc04-ac2d-e4bb-f0f99b2a8f90">
33492 <booktitle>
33493 <mainbooktitle/>
33494 </booktitle>
33495 <bookmeta>
33496 <shortdesc/>
33497 <author>mim</author>
33498 <source/>
33499 <category/>
33500 <keywords>
33501 <keyword/>
33502 </keywords>
33503 <prodinfo>
33504 <prodname product=""/>
33505 <vrmlist>
33506 <vrm version=""/>
33507 </vrmlist>
33508 <prognum/>
33509 <brand/>
33510 </prodinfo>
33511 <bookchangehistory>
33512 <approved>
33513 <revisionid/>
33514 </approved>
33515 </bookchangehistory>
33516 <bookrights>
33517 <copyrfirst>
33518 <year/>
33519 </copyrfirst>
33520 <bookowner/>
33521 </bookrights>
33522 </bookmeta>
33523 <frontmatter>
33524 <notices/>
33525 <booklists>
33526 <toc/>
33527 </booklists>
33528 <preface/>
33529 </frontmatter>
33530 <a>
33531 <b>
33532 <c/>
33533 </b>
33534 </a>
33535 <appendices/>
33536 <reltable>
33537 <relheader>
33538 <relcolspec/>
33539 <relcolspec/>
33540 </relheader>
33541 <relrow>
33542 <relcell/>
33543 <relcell/>
33544 </relrow>
33545 <relrow>
33546 <relcell/>
33547 <relcell/>
33548 </relrow>
33549 </reltable>
33550 </bookmap>
33551 END
33552  
33553  
33554 This is a static method and so should either be imported or invoked as:
33555  
33556 Data::Edit::Xml::ditaSampleBookMap
33557  
33558  
33559 =head3 isADitaMap($node)
33560  
33561 Return the specified B<$node> if this node is a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> map else return B<undef>
33562  
33563 Parameter Description
33564 1 $node Node to test
33565  
33566 B<Example:>
33567  
33568  
33569  
33570 my $a = Data::Edit::Xml::ditaSampleBookMap
33571 (author=>q(mim),
33572 chapters=>Data::Edit::Xml::new(<<END));
33573 <a>
33574 <b>
33575 <c/>
33576 </b>
33577 </a>
33578 END
33579  
33580  
33581 ok $a->isADitaMap; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33582  
33583  
33584 ok !$a->first->isADitaMap; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33585  
33586  
33587 ok -p $a eq <<END;
33588 <bookmap id="GUID-3b04e859-bc04-ac2d-e4bb-f0f99b2a8f90">
33589 <booktitle>
33590 <mainbooktitle/>
33591 </booktitle>
33592 <bookmeta>
33593 <shortdesc/>
33594 <author>mim</author>
33595 <source/>
33596 <category/>
33597 <keywords>
33598 <keyword/>
33599 </keywords>
33600 <prodinfo>
33601 <prodname product=""/>
33602 <vrmlist>
33603 <vrm version=""/>
33604 </vrmlist>
33605 <prognum/>
33606 <brand/>
33607 </prodinfo>
33608 <bookchangehistory>
33609 <approved>
33610 <revisionid/>
33611 </approved>
33612 </bookchangehistory>
33613 <bookrights>
33614 <copyrfirst>
33615 <year/>
33616 </copyrfirst>
33617 <bookowner/>
33618 </bookrights>
33619 </bookmeta>
33620 <frontmatter>
33621 <notices/>
33622 <booklists>
33623 <toc/>
33624 </booklists>
33625 <preface/>
33626 </frontmatter>
33627 <a>
33628 <b>
33629 <c/>
33630 </b>
33631 </a>
33632 <appendices/>
33633 <reltable>
33634 <relheader>
33635 <relcolspec/>
33636 <relcolspec/>
33637 </relheader>
33638 <relrow>
33639 <relcell/>
33640 <relcell/>
33641 </relrow>
33642 <relrow>
33643 <relcell/>
33644 <relcell/>
33645 </relrow>
33646 </reltable>
33647 </bookmap>
33648 END
33649  
33650  
33651 =head3 ditaRoot($node)
33652  
33653 Return the specified B<$node> if it a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> root node else return B<undef>.
33654  
33655 Parameter Description
33656 1 $node Node to check
33657  
33658 B<Example:>
33659  
33660  
33661 my $a = Data::Edit::Xml::new(q(<concept><a/></concept>));
33662  
33663 ok $a->ditaRoot; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33664  
33665  
33666 ok !$a->first->ditaRoot; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33667  
33668  
33669  
33670 =head3 ditaTopicHeaders($node, $String)
33671  
33672 Add L<Xml|https://en.wikipedia.org/wiki/XML> headers for the dita document type indicated by the specified L<parse|/parse> tree
33673  
33674 Parameter Description
33675 1 $node Node in parse tree
33676 2 $String Suffix string
33677  
33678 B<Example:>
33679  
33680  
33681  
33682 ok Data::Edit::Xml::new(q(<concept/>))->ditaTopicHeaders eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33683  
33684 <?xml version="1.0" encoding="UTF-8"?>
33685 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd" []>
33686 END
33687  
33688  
33689 =head3 ditaPrettyPrintWithHeaders($node)
33690  
33691 Add L<Xml|https://en.wikipedia.org/wiki/XML> headers for the dita document type indicated by the specified L<parse|/parse> tree to a pretty print of the parse tree.
33692  
33693 Parameter Description
33694 1 $node Node in parse tree
33695  
33696 B<Example:>
33697  
33698  
33699 if (1)
33700 {my $a = Data::Edit::Xml::new(q(<concept/>));
33701  
33702  
33703 ok $a->ditaPrettyPrintWithHeaders eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33704  
33705 <?xml version="1.0" encoding="UTF-8"?>
33706 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd" []>
33707 <concept/>
33708 END
33709 }
33710  
33711  
33712 =head3 ditaCutTopicmetaFromAClassificationMap($node, @context)
33713  
33714 Remove a topicmeta node from a classification map. Dita::Validate was built from conventional maps and so does not recognize all the situations where topicmeta is invalid in a classification map
33715  
33716 Parameter Description
33717 1 $node Node
33718 2 @context Optional context
33719  
33720 =head3 ditaAddTopicReport($tree, $report)
33721  
33722 Place a report into a dita topic using required clean up
33723  
33724 Parameter Description
33725 1 $tree Topic
33726 2 $report Report
33727  
33728 B<Example:>
33729  
33730  
33731 my $a = Data::Edit::Xml::new(<<END);
33732 <task id="c1">
33733 <title/>
33734 <taskbody>
33735 </taskbody>
33736 </task>
33737 END
33738  
33739  
33740 $a->ditaAddTopicReport(q(Please note the following discrepancies)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33741  
33742 ok -p $a eq <<END;
33743 <task id="c1">
33744 <title/>
33745 <taskbody>
33746 <context>
33747 <required-cleanup>Please note the following discrepancies</required-cleanup>
33748 </context>
33749 </taskbody>
33750 </task>
33751 END
33752  
33753  
33754 =head3 help($node)
33755  
33756 Get help for a node and the editor
33757  
33758 Parameter Description
33759 1 $node Node
33760  
33761 B<Example:>
33762  
33763  
33764 my $a = Data::Edit::Xml::new(<<END);
33765 <a>
33766 <steps/>
33767 <dd/>
33768 </a>
33769 END
33770  
33771  
33772 my $u = $a->go_dd->help; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33773  
33774 ok $u =~ m(\Ahttp://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/contentmodels/cmltd.html#cmltd__dd\Z);
33775  
33776  
33777 my $U = $a->go_steps->help; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33778  
33779 ok $U =~ m(\Ahttp://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/contentmodels/cmlts.html#cmlts__steps\Z);
33780  
33781  
33782 B<h> is a synonym for L<help|/help>.
33783  
33784  
33785 =head2 Html and word conversions
33786  
33787 Methods useful for converting Word and L<HTML|https://en.wikipedia.org/wiki/HTML> to L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html>
33788  
33789 =head3 htmlHeadersToSections($tree)
33790  
33791 Position sections just before html header tags so that subsequently the document can be divided into L<sections|/divideDocumentIntoSections>.
33792  
33793 Parameter Description
33794 1 $tree Parse tree
33795  
33796 B<Example:>
33797  
33798  
33799 {my $x = Data::Edit::Xml::new(<<END);
33800 <x>
33801 <h1>h1</h1>
33802 H1
33803 <h2>h2</h2>
33804 H2
33805 <h3>h3</h3>
33806 H3
33807 <h3>h3</h3>
33808 H3
33809 <h2>h2</h2>
33810 H2
33811 <h4>h4</h4>
33812 H4
33813 </x>
33814 END
33815  
33816  
33817 $x->htmlHeadersToSections; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33818  
33819  
33820 $x->divideDocumentIntoSections(sub
33821  
33822 {my ($topicref, $section) = @_;
33823  
33824 my $file = keys %file;
33825  
33826 $topicref->href = $file;
33827  
33828 $file{$file} = -p $section;
33829  
33830 $section->cut;
33831  
33832 });
33833  
33834 ok -p $x eq <<END;
33835 <x>
33836 <topicref href="0">
33837 <topicref href="1">
33838 <topicref href="2"/>
33839 <topicref href="3"/>
33840 </topicref>
33841 <topicref href="4">
33842 <topicref href="5"/>
33843 </topicref>
33844 </topicref>
33845 </x>
33846 END
33847  
33848  
33849 =head3 divideDocumentIntoSections($node, $cutSub)
33850  
33851 Divide a L<parse|/parse> tree into sections by moving non B<section> tags into their corresponding B<section> so that the B<section> tags expand until they are contiguous. The sections are then cut out by applying the specified sub to each B<section> tag in the L<parse|/parse> tree. The specified sub will receive the containing B<topicref> and the B<section> to be cut out as parameters allowing a reference to the cut out section to be inserted into the B<topicref>.
33852  
33853 Parameter Description
33854 1 $node Parse tree
33855 2 $cutSub Cut out sub
33856  
33857 B<Example:>
33858  
33859  
33860 {my $x = Data::Edit::Xml::new(<<END);
33861 <x>
33862 <h1>h1</h1>
33863 H1
33864 <h2>h2</h2>
33865 H2
33866 <h3>h3</h3>
33867 H3
33868 <h3>h3</h3>
33869 H3
33870 <h2>h2</h2>
33871 H2
33872 <h4>h4</h4>
33873 H4
33874 </x>
33875 END
33876  
33877 $x->htmlHeadersToSections;
33878  
33879  
33880 $x->divideDocumentIntoSections(sub # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33881  
33882  
33883 {my ($topicref, $section) = @_;
33884  
33885 my $file = keys %file;
33886  
33887 $topicref->href = $file;
33888  
33889 $file{$file} = -p $section;
33890  
33891 $section->cut;
33892  
33893 });
33894  
33895 ok -p $x eq <<END;
33896 <x>
33897 <topicref href="0">
33898 <topicref href="1">
33899 <topicref href="2"/>
33900 <topicref href="3"/>
33901 </topicref>
33902 <topicref href="4">
33903 <topicref href="5"/>
33904 </topicref>
33905 </topicref>
33906 </x>
33907 END
33908  
33909  
33910 =head3 divideHtmlDocumentIntoSections($tree)
33911  
33912 Divide a L<parse|/parse> tree representing an html document into sections based on the heading tags.
33913  
33914 Parameter Description
33915 1 $tree Parse tree
33916  
33917 B<Example:>
33918  
33919  
33920  
33921 my $a = Data::Edit::Xml::new(<<END);
33922 <a>
33923 <h1>HH11</h1> text1
33924 <h2>HH22</h2> text2
33925 <h2>HH22</h2> text3
33926 <h4>HH44</h4>text4
33927 <h1>HH11</h1> text5
33928 </a>
33929 END
33930  
33931  
33932 $a->divideHtmlDocumentIntoSections; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33933  
33934  
33935 ok nws(-p $a) eq nws(<<END);
33936 <a>
33937 <section outputclass="1">
33938 <title>HH11</title>
33939 text1
33940 <section outputclass="2">
33941 <title>HH22</title>
33942 text2
33943 </section>
33944 <section outputclass="2">
33945 <title>HH22</title>
33946 text3
33947 <section outputclass="4">
33948 <title>HH44</title>
33949 text4
33950 </section>
33951 </section>
33952 </section>
33953 <section outputclass="1">
33954 <title>HH11</title>
33955 text5
33956 </section>
33957 </a>
33958 END
33959  
33960  
33961 =head3 ditaParagraphToNote($node, $wrapNoteContentWithParagaph)
33962  
33963 Convert all <p> nodes to <note> if the paragraph starts with 'Note:', optionally wrapping the content of the <note> with a <p>
33964  
33965 Parameter Description
33966 1 $node Parse tree
33967 2 $wrapNoteContentWithParagaph Wrap the <note> content with a <p> if true
33968  
33969 B<Example:>
33970  
33971  
33972 {my $a = Data::Edit::Xml::new(<<END);
33973 <a>
33974 <p> Note: see over for details.</p>
33975 </a>
33976 END
33977  
33978  
33979 $a->ditaParagraphToNote(1); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
33980  
33981  
33982 ok -p $a eq <<END;
33983 <a>
33984 <note>
33985 <p>See over for details.</p>
33986 </note>
33987 </a>
33988 END
33989  
33990  
33991 =head3 wordStyles($x)
33992  
33993 Extract style information from a parse tree representing a word document.
33994  
33995 Parameter Description
33996 1 $x Parse tree
33997  
33998 B<Example:>
33999  
34000  
34001 {my $a = Data::Edit::Xml::new(<<END);
34002 <a>
34003 <text:list-style style:name="aa">
34004 <text:list-level-style-bullet text:level="2"/>
34005 </text:list-style>
34006 </a>
34007 END
34008  
34009  
34010 my $styles = $a->wordStyles; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34011  
34012  
34013 is_deeply $styles, {bulletedList=>{aa=>{2=>1}}};
34014  
34015  
34016 =head3 htmlTableToDita($table)
34017  
34018 Convert an L<html table> to a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> table.
34019  
34020 Parameter Description
34021 1 $table Html table node
34022  
34023 B<Example:>
34024  
34025  
34026 {my $a = Data::Edit::Xml::new(<<END);
34027 <table>
34028 <thead>
34029 <tr>
34030 <th>Month</th>
34031 <th>Savings</th>
34032 <th>Phone</th>
34033 <th>Comment</th>
34034 </tr>
34035 </thead>
34036 <tbody>
34037 <tr>
34038 <td>January</td>
34039 <td>100</td>
34040 <td>555-1212</td>
34041 </tr>
34042 <tr>
34043 <td>February</td>
34044 <td>80</td>
34045 </tr>
34046 </tbody>
34047 </table>
34048 END
34049  
34050  
34051 $a->htmlTableToDita; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34052  
34053  
34054 ok -p $a eq <<END;
34055 <table>
34056 <tgroup cols="4">
34057 <colspec colname="c1" colnum="1" colwidth="1*"/>
34058 <colspec colname="c2" colnum="2" colwidth="1*"/>
34059 <colspec colname="c3" colnum="3" colwidth="1*"/>
34060 <colspec colname="c4" colnum="4" colwidth="1*"/>
34061 <thead>
34062 <row>
34063 <entry>Month</entry>
34064 <entry>Savings</entry>
34065 <entry>Phone</entry>
34066 <entry>Comment</entry>
34067 </row>
34068 </thead>
34069 <tbody>
34070 <row>
34071 <entry>January</entry>
34072 <entry>100</entry>
34073 <entry nameend="c4" namest="c3">555-1212</entry>
34074 </row>
34075 <row>
34076 <entry>February</entry>
34077 <entry nameend="c4" namest="c2">80</entry>
34078 </row>
34079 </tbody>
34080 </tgroup>
34081 </table>
34082 END
34083  
34084  
34085 =head3 ditaSyntaxDiagramFromDocBookCmdSynopsis({package ditaSyntaxDiagramFromDocBookCmdSynopsis;)
34086  
34087 Convert doc book cmdsynopsis to Dita syntax diagram
34088  
34089 Parameter Description
34090 1 {package ditaSyntaxDiagramFromDocBookCmdSynopsis; Allows us to package the entire conversion as one method
34091  
34092 B<Example:>
34093  
34094  
34095 my $a = Data::Edit::Xml::new(<<END);
34096 <cmdsynopsis>
34097 <command>fs</command>
34098 <arg choice="plain">list</arg>
34099 <group choice="opt">
34100 <arg choice="plain">--pending</arg>
34101 <arg choice="plain">--running</arg>
34102 </group>
34103 <group choice="opt">
34104 <arg choice="plain">--online</arg>
34105 <arg choice="plain">
34106 --offline
34107 <group choice="req">
34108 <arg choice="plain">http</arg>
34109 <arg choice="plain">https</arg>
34110 <arg choice="plain">ftp</arg>
34111 <arg choice="plain">ssh</arg>
34112 </group>
34113 </arg>
34114 <arg choice="plain">--special</arg>
34115 <arg choice="plain">--snap</arg>
34116 </group>
34117 <group choice="opt">
34118 <arg choice="plain">--real</arg>
34119 <arg choice="plain">--virtual</arg>
34120 <arg choice="plain">--absolute</arg>
34121 </group>
34122 <arg choice="opt">--titled</arg>
34123 <group choice="opt">
34124 <arg choice="plain">--total</arg>
34125 <arg choice="plain">--space</arg>
34126 </group>
34127 <arg choice="opt">
34128 --rename
34129 <replaceable>new-name</replaceable>
34130 </arg>
34131 <arg choice="opt">
34132 --sort
34133 <replaceable>sort procedure</replaceable>
34134 </arg>
34135 <arg choice="opt">--raw</arg>
34136 <arg choice="opt">
34137 --limit
34138 <replaceable>limits</replaceable>
34139 </arg>
34140 <arg choice="opt">--page</arg>
34141 <arg choice="opt" rep="repeat">
34142 <replaceable>files</replaceable>
34143 </arg>
34144 </cmdsynopsis>
34145 END
34146  
34147  
34148 $a->ditaSyntaxDiagramFromDocBookCmdSynopsis; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34149  
34150  
34151 ok -p $a eq <<END;
34152 <syntaxdiagram>
34153 <groupseq>
34154 <kwd outputclass="command">fs</kwd>
34155 <kwd>list</kwd>
34156 <groupchoice importance="optional">
34157 <kwd>--pending</kwd>
34158 <kwd>--running</kwd>
34159 </groupchoice>
34160 <groupchoice importance="optional">
34161 <kwd>--online</kwd>
34162 <groupseq>
34163 <kwd>
34164 --offline
34165 </kwd>
34166 <groupchoice>
34167 <kwd>http</kwd>
34168 <kwd>https</kwd>
34169 <kwd>ftp</kwd>
34170 <kwd>ssh</kwd>
34171 </groupchoice>
34172 </groupseq>
34173 <kwd>--special</kwd>
34174 <kwd>--snap</kwd>
34175 </groupchoice>
34176 <groupchoice importance="optional">
34177 <kwd>--real</kwd>
34178 <kwd>--virtual</kwd>
34179 <kwd>--absolute</kwd>
34180 </groupchoice>
34181 <kwd importance="optional">--titled</kwd>
34182 <groupchoice importance="optional">
34183 <kwd>--total</kwd>
34184 <kwd>--space</kwd>
34185 </groupchoice>
34186 <groupseq importance="optional">
34187 <kwd>
34188 --rename
34189 </kwd>
34190 <var>new-name</var>
34191 </groupseq>
34192 <groupseq importance="optional">
34193 <kwd>
34194 --sort
34195 </kwd>
34196 <var>sort procedure</var>
34197 </groupseq>
34198 <kwd importance="optional">--raw</kwd>
34199 <groupseq importance="optional">
34200 <kwd>
34201 --limit
34202 </kwd>
34203 <var>limits</var>
34204 </groupseq>
34205 <kwd importance="optional">--page</kwd>
34206 <groupseq importance="optional">
34207 <var>files</var>
34208 <sep>…</sep>
34209 </groupseq>
34210 </groupseq>
34211 </syntaxdiagram>
34212 END
34213  
34214 $a->ditaSyntaxDiagramToBasicRepresentation;
34215  
34216 ok nws(-p $a) eq nws(<<END);
34217 <p>
34218 <cmdname>fs</cmdname>
34219 <codeph>list</codeph>
34220  
34221 [ <codeph>--pending</codeph> | <codeph>--running</codeph> ]
34222  
34223 [ <codeph>--online</codeph> |
34224 <codeph> --offline </codeph> { <codeph>http</codeph> | <codeph>https</codeph> | <codeph>ftp</codeph> | <codeph>ssh</codeph> } |
34225 <codeph>--special</codeph> |
34226 <codeph>--snap</codeph>
34227 ]
34228  
34229 [ <codeph>--real</codeph> |
34230 <codeph>--virtual</codeph> |
34231 <codeph>--absolute</codeph>
34232 ]
34233  
34234 [ <codeph>--titled</codeph> ]
34235 [ <codeph>--total</codeph> | <codeph>--space</codeph> ]
34236 [ <codeph> --rename </codeph> <userinput>new-name</userinput> ]
34237 [ <codeph> --sort </codeph> <userinput>sort procedure</userinput> ]
34238 [ <codeph>--raw</codeph> ]
34239 [ <codeph> --limit </codeph> <userinput>limits</userinput> ]
34240 [ <codeph>--page</codeph> ]
34241 [ <userinput>files</userinput> <codeph>…</codeph> ]
34242 </p>
34243 END
34244  
34245  
34246 =head3 ditaSyntaxDiagramToBasicRepresentation($x)
34247  
34248 Convert Dita syntax diagrams into Micaela's Basic Version.
34249  
34250 Parameter Description
34251 1 $x Parse tree
34252  
34253 B<Example:>
34254  
34255  
34256 my $a = Data::Edit::Xml::new(<<END);
34257 <cmdsynopsis>
34258 <command>fs</command>
34259 <arg choice="plain">list</arg>
34260 <group choice="opt">
34261 <arg choice="plain">--pending</arg>
34262 <arg choice="plain">--running</arg>
34263 </group>
34264 <group choice="opt">
34265 <arg choice="plain">--online</arg>
34266 <arg choice="plain">
34267 --offline
34268 <group choice="req">
34269 <arg choice="plain">http</arg>
34270 <arg choice="plain">https</arg>
34271 <arg choice="plain">ftp</arg>
34272 <arg choice="plain">ssh</arg>
34273 </group>
34274 </arg>
34275 <arg choice="plain">--special</arg>
34276 <arg choice="plain">--snap</arg>
34277 </group>
34278 <group choice="opt">
34279 <arg choice="plain">--real</arg>
34280 <arg choice="plain">--virtual</arg>
34281 <arg choice="plain">--absolute</arg>
34282 </group>
34283 <arg choice="opt">--titled</arg>
34284 <group choice="opt">
34285 <arg choice="plain">--total</arg>
34286 <arg choice="plain">--space</arg>
34287 </group>
34288 <arg choice="opt">
34289 --rename
34290 <replaceable>new-name</replaceable>
34291 </arg>
34292 <arg choice="opt">
34293 --sort
34294 <replaceable>sort procedure</replaceable>
34295 </arg>
34296 <arg choice="opt">--raw</arg>
34297 <arg choice="opt">
34298 --limit
34299 <replaceable>limits</replaceable>
34300 </arg>
34301 <arg choice="opt">--page</arg>
34302 <arg choice="opt" rep="repeat">
34303 <replaceable>files</replaceable>
34304 </arg>
34305 </cmdsynopsis>
34306 END
34307  
34308 $a->ditaSyntaxDiagramFromDocBookCmdSynopsis;
34309  
34310 ok -p $a eq <<END;
34311 <syntaxdiagram>
34312 <groupseq>
34313 <kwd outputclass="command">fs</kwd>
34314 <kwd>list</kwd>
34315 <groupchoice importance="optional">
34316 <kwd>--pending</kwd>
34317 <kwd>--running</kwd>
34318 </groupchoice>
34319 <groupchoice importance="optional">
34320 <kwd>--online</kwd>
34321 <groupseq>
34322 <kwd>
34323 --offline
34324 </kwd>
34325 <groupchoice>
34326 <kwd>http</kwd>
34327 <kwd>https</kwd>
34328 <kwd>ftp</kwd>
34329 <kwd>ssh</kwd>
34330 </groupchoice>
34331 </groupseq>
34332 <kwd>--special</kwd>
34333 <kwd>--snap</kwd>
34334 </groupchoice>
34335 <groupchoice importance="optional">
34336 <kwd>--real</kwd>
34337 <kwd>--virtual</kwd>
34338 <kwd>--absolute</kwd>
34339 </groupchoice>
34340 <kwd importance="optional">--titled</kwd>
34341 <groupchoice importance="optional">
34342 <kwd>--total</kwd>
34343 <kwd>--space</kwd>
34344 </groupchoice>
34345 <groupseq importance="optional">
34346 <kwd>
34347 --rename
34348 </kwd>
34349 <var>new-name</var>
34350 </groupseq>
34351 <groupseq importance="optional">
34352 <kwd>
34353 --sort
34354 </kwd>
34355 <var>sort procedure</var>
34356 </groupseq>
34357 <kwd importance="optional">--raw</kwd>
34358 <groupseq importance="optional">
34359 <kwd>
34360 --limit
34361 </kwd>
34362 <var>limits</var>
34363 </groupseq>
34364 <kwd importance="optional">--page</kwd>
34365 <groupseq importance="optional">
34366 <var>files</var>
34367 <sep>…</sep>
34368 </groupseq>
34369 </groupseq>
34370 </syntaxdiagram>
34371 END
34372  
34373  
34374 $a->ditaSyntaxDiagramToBasicRepresentation; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34375  
34376  
34377 ok nws(-p $a) eq nws(<<END);
34378 <p>
34379 <cmdname>fs</cmdname>
34380 <codeph>list</codeph>
34381  
34382 [ <codeph>--pending</codeph> | <codeph>--running</codeph> ]
34383  
34384 [ <codeph>--online</codeph> |
34385 <codeph> --offline </codeph> { <codeph>http</codeph> | <codeph>https</codeph> | <codeph>ftp</codeph> | <codeph>ssh</codeph> } |
34386 <codeph>--special</codeph> |
34387 <codeph>--snap</codeph>
34388 ]
34389  
34390 [ <codeph>--real</codeph> |
34391 <codeph>--virtual</codeph> |
34392 <codeph>--absolute</codeph>
34393 ]
34394  
34395 [ <codeph>--titled</codeph> ]
34396 [ <codeph>--total</codeph> | <codeph>--space</codeph> ]
34397 [ <codeph> --rename </codeph> <userinput>new-name</userinput> ]
34398 [ <codeph> --sort </codeph> <userinput>sort procedure</userinput> ]
34399 [ <codeph>--raw</codeph> ]
34400 [ <codeph> --limit </codeph> <userinput>limits</userinput> ]
34401 [ <codeph>--page</codeph> ]
34402 [ <userinput>files</userinput> <codeph>…</codeph> ]
34403 </p>
34404 END
34405  
34406  
34407 =head3 ditaWrapWithPUnderConbody($conbody)
34408  
34409 Wrap items immediately under L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<conbody> with B<p> or merge with any previous B<p> if the item in question does not fit under B<conbody> but does fit under B<p>. Return the current node if it is B<conbody> else return B<undef>.
34410  
34411 Parameter Description
34412 1 $conbody Section
34413  
34414 B<Example:>
34415  
34416  
34417 my $a = Data::Edit::Xml::new(<<END);
34418 <conbody>text<q>quote</q><p>new paragraph</p>
34419 more text</conbody>
34420 END
34421  
34422  
34423 $a->ditaWrapWithPUnderConbody; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34424  
34425  
34426 my $b = new(<<END);
34427 <conbody><p>text<q>quote</q></p><p>new paragraph
34428 more text</p></conbody>
34429 END
34430  
34431 ok $a->equals($b);
34432  
34433  
34434 =head1 PCD
34435  
34436 Please Change Dita Language Features
34437  
34438 =head2 putNodeAs($node, $name, @context)
34439  
34440 Return the specified B<$node> after saving it under the specified B<$name> if we are in the optional B<@context>.
34441  
34442 Parameter Description
34443 1 $node Node
34444 2 $name Save name
34445 3 @context Optional context
34446  
34447 Use the optional B<@context> parameter to test the context of the specified
34448 B<$node> as understood by method L<at|/at>. If the context is supplied and
34449 B<$node> is not in this context then this method returns B<undef> immediately.
34450  
34451  
34452  
34453 B<Example:>
34454  
34455  
34456 my $a = Data::Edit::Xml::new(<<END);
34457 <a>
34458 <b>
34459 <c>
34460 <d id="d"/>
34461 </c>
34462 </b>
34463 </a>
34464 END
34465  
34466 my ($d, $c, $b) = $a->byList;
34467  
34468  
34469 $d->putNodeAs(q(D)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34470  
34471 ok $a->getNodeAs(q(D)) == $d;
34472 %Data::Edit::Xml::savedNodes = ();
34473 ok $a->getNodeAs(q(D)) == $a;
34474  
34475 ok $a->reportNode_AAAA eq <<END;
34476 AAAA
34477 <a>
34478 <b>
34479 <c>
34480 <d id="d"/>
34481 </c>
34482 </b>
34483 </a>
34484 END
34485 ok $d->reportNodeAttributes_BBBB eq q(BBBB id="d");
34486 ok $d->reportNodeAttributes_CCCC eq q(CCCC id="d");
34487 ok $d->reportNodeContext_DDDD eq q(DDDD d c b a);
34488  
34489  
34490 B<put> is a synonym for L<putNodeAs|/putNodeAs>.
34491  
34492  
34493 =head2 getNodeAs($node, $name, @context)
34494  
34495 Return the specified B<$node> unless it is possible to return the node saved with L<putNodeAs> under the specified B<name> and we are optionally in the specified B<@context>.
34496  
34497 Parameter Description
34498 1 $node Default node
34499 2 $name Name of saved node
34500 3 @context Optional context
34501  
34502 Use the optional B<@context> parameter to test the context of the specified
34503 B<$node> as understood by method L<at|/at>. If the context is supplied and
34504 B<$node> is not in this context then this method returns B<undef> immediately.
34505  
34506  
34507  
34508 B<Example:>
34509  
34510  
34511 my $a = Data::Edit::Xml::new(<<END);
34512 <a>
34513 <b>
34514 <c>
34515 <d id="d"/>
34516 </c>
34517 </b>
34518 </a>
34519 END
34520  
34521 my ($d, $c, $b) = $a->byList;
34522  
34523 $d->putNodeAs(q(D));
34524  
34525 ok $a->getNodeAs(q(D)) == $d; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34526  
34527 %Data::Edit::Xml::savedNodes = ();
34528  
34529 ok $a->getNodeAs(q(D)) == $a; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34530  
34531  
34532 ok $a->reportNode_AAAA eq <<END;
34533 AAAA
34534 <a>
34535 <b>
34536 <c>
34537 <d id="d"/>
34538 </c>
34539 </b>
34540 </a>
34541 END
34542 ok $d->reportNodeAttributes_BBBB eq q(BBBB id="d");
34543 ok $d->reportNodeAttributes_CCCC eq q(CCCC id="d");
34544 ok $d->reportNodeContext_DDDD eq q(DDDD d c b a);
34545  
34546  
34547 B<get> is a synonym for L<getNodeAs|/getNodeAs>.
34548  
34549  
34550 =head2 reportNodeAttributes($node, $label, @context)
34551  
34552 Print the attributes of the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
34553  
34554 Parameter Description
34555 1 $node Node node
34556 2 $label Label
34557 3 @context Optional context
34558  
34559 Use the optional B<@context> parameter to test the context of the specified
34560 B<$node> as understood by method L<at|/at>. If the context is supplied and
34561 B<$node> is not in this context then this method returns B<undef> immediately.
34562  
34563  
34564  
34565 B<Example:>
34566  
34567  
34568 my $a = Data::Edit::Xml::new(<<END);
34569 <a>
34570 <b>
34571 <c>
34572 <d id="d"/>
34573 </c>
34574 </b>
34575 </a>
34576 END
34577  
34578 my ($d, $c, $b) = $a->byList;
34579  
34580 $d->putNodeAs(q(D));
34581 ok $a->getNodeAs(q(D)) == $d;
34582 %Data::Edit::Xml::savedNodes = ();
34583 ok $a->getNodeAs(q(D)) == $a;
34584  
34585 ok $a->reportNode_AAAA eq <<END;
34586 AAAA
34587 <a>
34588 <b>
34589 <c>
34590 <d id="d"/>
34591 </c>
34592 </b>
34593 </a>
34594 END
34595 ok $d->reportNodeAttributes_BBBB eq q(BBBB id="d");
34596 ok $d->reportNodeAttributes_CCCC eq q(CCCC id="d");
34597 ok $d->reportNodeContext_DDDD eq q(DDDD d c b a);
34598  
34599  
34600 B<rna> is a synonym for L<reportNodeAttributes|/reportNodeAttributes>.
34601  
34602  
34603 =head2 reportNodeContext($node, $label, @context)
34604  
34605 Print the context of the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
34606  
34607 Parameter Description
34608 1 $node Node node
34609 2 $label Label
34610 3 @context Optional context
34611  
34612 Use the optional B<@context> parameter to test the context of the specified
34613 B<$node> as understood by method L<at|/at>. If the context is supplied and
34614 B<$node> is not in this context then this method returns B<undef> immediately.
34615  
34616  
34617  
34618 B<Example:>
34619  
34620  
34621 my $a = Data::Edit::Xml::new(<<END);
34622 <a>
34623 <b>
34624 <c>
34625 <d id="d"/>
34626 </c>
34627 </b>
34628 </a>
34629 END
34630  
34631 my ($d, $c, $b) = $a->byList;
34632  
34633 $d->putNodeAs(q(D));
34634 ok $a->getNodeAs(q(D)) == $d;
34635 %Data::Edit::Xml::savedNodes = ();
34636 ok $a->getNodeAs(q(D)) == $a;
34637  
34638 ok $a->reportNode_AAAA eq <<END;
34639 AAAA
34640 <a>
34641 <b>
34642 <c>
34643 <d id="d"/>
34644 </c>
34645 </b>
34646 </a>
34647 END
34648 ok $d->reportNodeAttributes_BBBB eq q(BBBB id="d");
34649 ok $d->reportNodeAttributes_CCCC eq q(CCCC id="d");
34650 ok $d->reportNodeContext_DDDD eq q(DDDD d c b a);
34651  
34652  
34653 B<rnc> is a synonym for L<reportNodeContext|/reportNodeContext>.
34654  
34655  
34656 =head2 reportNode($node, $label, @context)
34657  
34658 Print the parse tree starting at the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
34659  
34660 Parameter Description
34661 1 $node Node node
34662 2 $label Label
34663 3 @context Optional context
34664  
34665 Use the optional B<@context> parameter to test the context of the specified
34666 B<$node> as understood by method L<at|/at>. If the context is supplied and
34667 B<$node> is not in this context then this method returns B<undef> immediately.
34668  
34669  
34670  
34671 B<Example:>
34672  
34673  
34674 my $a = Data::Edit::Xml::new(<<END);
34675 <a>
34676 <b>
34677 <c>
34678 <d id="d"/>
34679 </c>
34680 </b>
34681 </a>
34682 END
34683  
34684 my ($d, $c, $b) = $a->byList;
34685  
34686 $d->putNodeAs(q(D));
34687 ok $a->getNodeAs(q(D)) == $d;
34688 %Data::Edit::Xml::savedNodes = ();
34689 ok $a->getNodeAs(q(D)) == $a;
34690  
34691 ok $a->reportNode_AAAA eq <<END;
34692 AAAA
34693 <a>
34694 <b>
34695 <c>
34696 <d id="d"/>
34697 </c>
34698 </b>
34699 </a>
34700 END
34701 ok $d->reportNodeAttributes_BBBB eq q(BBBB id="d");
34702 ok $d->reportNodeAttributes_CCCC eq q(CCCC id="d");
34703 ok $d->reportNodeContext_DDDD eq q(DDDD d c b a);
34704  
34705  
34706 B<rn> is a synonym for L<reportNode|/reportNode>.
34707  
34708  
34709 =head1 Debug
34710  
34711 Debugging methods
34712  
34713 =head2 sss($node, @text)
34714  
34715 Put, after the current B<$node>, the specified B<@text> and return the current $node.
34716  
34717 Parameter Description
34718 1 $node Node
34719 2 @text Text
34720  
34721 B<Example:>
34722  
34723  
34724 my $a = Data::Edit::Xml::new(q(<a><b><c/></b></a>));
34725  
34726 $a->go_b_c__sss_aa_bb_cc;
34727  
34728 ok -p $a eq <<END;
34729 <a>
34730 <b>
34731 <c/>
34732 aa bb cc
34733 </b>
34734 </a>
34735 END
34736  
34737  
34738 =head2 printAttributes($node)
34739  
34740 Print the attributes of a node.
34741  
34742 Parameter Description
34743 1 $node Node whose attributes are to be printed.
34744  
34745 B<Example:>
34746  
34747  
34748 my $x = Data::Edit::Xml::new(my $s = <<END);
34749 <a no="1" word="first"/>
34750 END
34751  
34752  
34753 ok $x->printAttributes eq qq( no="1" word="first"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34754  
34755  
34756  
34757 =head2 printAttributesHtml($node)
34758  
34759 Print the attributes of a node as html.
34760  
34761 Parameter Description
34762 1 $node Node whose attributes are to be printed.
34763  
34764 B<Example:>
34765  
34766  
34767 my $a = Data::Edit::Xml::new(<<END);
34768 <a id="1">
34769 <b id="2" b="B">
34770 <c/>
34771 </b>
34772 <d id="3" d="D">
34773 Some text
34774 </d>
34775 </a>
34776 END
34777  
34778 ok $a->prettyStringHtml eq <<END;
34779 <div class="xmlLine"><span class="xmlLineStartTag"></span><span class="xmlLt">&lt;</span><span class="xmlTag">a</span> <span class="xmlAttr">id</span><span class="xmlEquals">=</span><span class="xmlValue">"1"</span><span class="xmlGt">&gt;</span></div>
34780 <div class="xmlLine"><span class="xmlLineStartTag">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xmlLt">&lt;</span><span class="xmlTag">b</span> <span class="xmlAttr">b</span><span class="xmlEquals">=</span><span class="xmlValue">"B"</span> <span class="xmlAttr">id</span><span class="xmlEquals">=</span><span class="xmlValue">"2"</span><span class="xmlGt">&gt;</span></div>
34781 <div class="xmlLine"><span class="xmlLineStartTag">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xmlLt">&lt;</span><span class="xmlTag">c</span><span class="xmlSlashGt">/&gt;</span></div>
34782 <div class="xmlLine"><span class="xmlLineStartTag">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xmlLtSlash">&lt;/</span><span class="xmlTag">b</span><span class="xmlGt">&gt;</span></div>
34783 <div class="xmlLine"><span class="xmlLineStartTag">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xmlLt">&lt;</span><span class="xmlTag">d</span> <span class="xmlAttr">d</span><span class="xmlEquals">=</span><span class="xmlValue">"D"</span> <span class="xmlAttr">id</span><span class="xmlEquals">=</span><span class="xmlValue">"3"</span><span class="xmlGt">&gt;</span><span class="xmlText">Some text</span><span class="xmlLtSlash">&lt;/</span><span class="xmlTag">d</span><span class="xmlGt">&gt;</span></div>
34784 <div class="xmlLine"><span class="xmlLineStartTag"></span><span class="xmlLtSlash">&lt;/</span><span class="xmlTag">a</span><span class="xmlGt">&gt;</span></div>
34785 END
34786  
34787  
34788 =head2 printStack($node, @context)
34789  
34790 Print the attributes of a node and each of its parents
34791  
34792 Parameter Description
34793 1 $node Node whose attributes are to be printed
34794 2 @context Optional context.
34795  
34796 Use the optional B<@context> parameter to test the context of the specified
34797 B<$node> as understood by method L<at|/at>. If the context is supplied and
34798 B<$node> is not in this context then this method returns B<undef> immediately.
34799  
34800  
34801  
34802 B<Example:>
34803  
34804  
34805 my $a = Data::Edit::Xml::new(<<END);
34806 <a id="a">
34807 <b id="b">
34808 <c>
34809 <d id="d"/>
34810 </c>
34811 </b>
34812 </a>
34813 END
34814  
34815 my $d = $a->firstUntil_d;
34816  
34817 ok $d->printStack eq <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34818  
34819 a id="a"
34820 b id="b"
34821 c
34822 d id="d"
34823 END
34824 ok -S $d eq <<END;
34825 a id="a"
34826 b id="b"
34827 c
34828 d id="d"
34829 END
34830  
34831  
34832 =head2 printNode($node, @context)
34833  
34834 Print the tag and attributes of a node.
34835  
34836 Parameter Description
34837 1 $node Node whose attributes are to be printed
34838 2 @context Optional context.
34839  
34840 Use the optional B<@context> parameter to test the context of the specified
34841 B<$node> as understood by method L<at|/at>. If the context is supplied and
34842 B<$node> is not in this context then this method returns B<undef> immediately.
34843  
34844  
34845  
34846 B<Example:>
34847  
34848  
34849 my $a = Data::Edit::Xml::new(<<END);
34850 <a>
34851 <b>
34852 <c id="42" match="mm"/>
34853 </b>
34854 <d>
34855 <e/>
34856 </d>
34857 </a>
34858 END
34859  
34860  
34861 ok $c->printNode eq q(c id="42" match="mm"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34862  
34863  
34864  
34865 =head2 printNodeAsSingleton($node, @context)
34866  
34867 Print the tag and attributes of a node as if it were a single node regardless of any child nodes it might have
34868  
34869 Parameter Description
34870 1 $node Node whose attributes are to be printed
34871 2 @context Optional context.
34872  
34873 Use the optional B<@context> parameter to test the context of the specified
34874 B<$node> as understood by method L<at|/at>. If the context is supplied and
34875 B<$node> is not in this context then this method returns B<undef> immediately.
34876  
34877  
34878  
34879 B<Example:>
34880  
34881  
34882 my $a = Data::Edit::Xml::new(<<END);
34883 <a id="a" outputclass="aa">
34884 <b/>
34885 </a>
34886 END
34887  
34888  
34889 ok $a->printNodeAsSingleton eq q(<a id="a" outputclass="aa"/>); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34890  
34891  
34892  
34893 =head2 goFish($node, @path)
34894  
34895 A debug version of L<go|/go> that returns additional information explaining any failure to reach the node identified by the L<path|/path>.
34896  
34897 Returns ([B<reachable tag>...], B<failing tag>, [B<possible tag>...]) where:
34898  
34899 =over
34900  
34901 =item B<reachable tag>
34902  
34903 the path elements successfully traversed;
34904  
34905 =item B<failing tag>
34906  
34907 the failing element;
34908  
34909 =item B<possible tag>
34910  
34911 the possibilities at the point where the path failed if it failed else B<undef>.
34912  
34913 =back
34914  
34915 Parameters:
34916  
34917 Parameter Description
34918 1 $node Node
34919 2 @path Search specification.
34920  
34921 B<Example:>
34922  
34923  
34924 {my $a = Data::Edit::Xml::new(<<END);
34925 <a>
34926 <b>
34927 <c>
34928 <d/>
34929 </c>
34930 <c/>
34931 </b>
34932 <b/>
34933 </a>
34934 END
34935  
34936  
34937 my ($good, $fail, $possible) = $a->goFish(qw(b c D)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34938  
34939  
34940 ok $fail eq q(D);
34941  
34942 is_deeply $good, [qw(b c)];
34943  
34944 is_deeply $possible, [q(d)];
34945  
34946  
34947 =head1 Validation
34948  
34949 Validate Xml
34950  
34951 =head2 checkAllPaths($valid)
34952  
34953 Create a representation of all the paths permitted in a block of L<Xml|https://en.wikipedia.org/wiki/XML>. The syntax of each line is a word representing an L<Xml|https://en.wikipedia.org/wiki/XML> tag followed by one of: tag B<1 * + ? -> with B<1> being the default and meaning that exactly one instance of this tag is required under its parent, B<*> meaning that zero or more such tags are permitted under its parent, B<+> meaning that one or more such tags are required under its parent, B<?> meaning that no more than one such tag is permitted under its parent, B<-> meaning that this is a leaf tag that can be missing or present just once under its parent. The remaining words on the line being treated as a comment describing the purpose of the tag. Tags that are not marked with B<-> are required to have either text under them if they are leaf tags. Tags marked with B<-> are boolean leafs and may not have any text or child tags under them. The children of a tag are listed on following lines with exactly two more spaces of indentation. This enables the validation of a block of non recursive L<Xml|https://en.wikipedia.org/wiki/XML> without having to resort to writing a complex L<DTD|https://en.wikipedia.org/wiki/Document_type_definition>.
34954  
34955 Parameter Description
34956 1 $valid Path descriptions
34957  
34958 B<Example:>
34959  
34960  
34961 my $paths = <<'END';
34962 database The database to be used for the table
34963 name The name of the database
34964 table + The table to be created
34965 name The name of the table
34966 hide - Hide this table if present
34967 column + Columns in this table
34968 name The name of the column
34969 type The type of the column
34970 description A description of the purpose of the column
34971 edit ? A regular expression to edit the column data
34972  
34973 reference * References from this table
34974 name The name of the reference
34975 table The name of the referenced table
34976 description A description of the reference
34977 row * Row of data to be loaded inot the table
34978 col + Column value
34979 END
34980  
34981 is_deeply checkAllPaths($paths), # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
34982  
34983 {"name" => [1, "name of the database"],
34984 "table" => ["+", "The table to be created"],
34985 "table column" => ["+", "Columns in this table"],
34986 "table column description" => [1, "description of the purpose of the column"],
34987 "table column edit" => ["?", "A regular expression to edit the column data"],
34988 "table column name" => [1, "name of the column"],
34989 "table column type" => [1, "type of the column"],
34990 "table hide" => ["-", "Hide this table if present"],
34991 "table name" => [1, "name of the table"],
34992 "table reference" => ["*", "References from this table"],
34993 "table reference description" => [1, "description of the reference"],
34994 "table reference name" => [1, "name of the reference"],
34995 "table reference table" => [1, "name of the referenced table"],
34996 "table row" => ["*", "Row of data to be loaded inot the table"],
34997 "table row col" => ["+", "Column value"]
34998 };
34999  
35000 my $xml = <<'END';
35001 <database>
35002 <name>test</name>
35003 <table>
35004 <name>team</name>
35005 <column> <name>name </name> <type>varchar(255)</type> <description>Name of the team </description></column>
35006 <column> <name>age </name> <type>varchar(8) </type> <description>Junior or Senior team </description><edit>qr(\A(junior|senior)\Z)i</edit></column>
35007 <column> <name>gender</name> <type>varchar(8) </type> <description>Female or Male </description><edit>qr(\A(female|male)\Z)i </edit></column>
35008 <column> <name>school</name> <type>varchar(255)</type> <description>School attended by team </description></column>
35009 <column> <name>region</name> <type>varchar(255)</type> <description>Region team is located in </description></column>
35010 <column> <name>coach </name> <type>varchar(255)</type> <description>Email address of the coach of this team</description></column>
35011 <row><col>Lubbock Lions </col><col>junior</col><col>Female</col><col>Lubbock High </col><col>North</col><col>ll@coaches.com</col></row>
35012 <row><col>Titan Tigers </col><col>junior</col><col>Female</col><col>Titan Senior High </col><col>East </col><col>tt@coaches.com</col></row>
35013 <row><col>Saturn Samurai </col><col>junior</col><col>Male </col><col>Saturn University </col><col>West </col><col>ss@coaches.com</col></row>
35014 <row><col>Jovial Journeymen</col><col>junior</col><col>Male </col><col>University of Jupiter</col><col>South</col><col>jj@coaches.com</col></row>
35015 </table>
35016  
35017 <table>
35018 <name>field</name>
35019 <column> <name>name </name> <type>varchar(255)</type> <description>Name of the field </description></column>
35020 <column> <name>street</name> <type>varchar(255)</type> <description>Street address of the field </description></column>
35021 <column> <name>city </name> <type>varchar(255)</type> <description>City containing the field </description></column>
35022 <column> <name>zip </name> <type>char(9) </type> <description>Zip code of field </description></column>
35023 <column> <name>school</name> <type>varchar(255)</type> <description>Email address of the owner of the field </description></column>
35024 <row><col>Big Circle </col><col>1 Elm Street </col><col>Treeville </col><col>76754</col><col>Lubbock High </col></row>
35025 <row><col>Large Field </col><col>2 Oak Street </col><col>TitusCity </col><col>76224</col><col>Titan Senior High </col></row>
35026 <row><col>Small Diamond</col><col>3 Ash Street </col><col>Ioville </col><col>72754</col><col>Saturn University </col></row>
35027 <row><col>Large Oval </col><col>4 Pine Street</col><col>GanymedeCity</col><col>76334</col><col>University of Jupiter</col></row>
35028 </table>
35029  
35030 <table>
35031 <name>matches</name>
35032 <column> <name>date </name> <type>date </type> <description>Time of match </description></column>
35033 <column> <name>score1 </name> <type>int </type> <description>Goals scored by home team </description></column>
35034 <column> <name>score2 </name> <type>int </type> <description>Goals scored by away team </description></column>
35035 <column> <name>adminAgree </name> <type>boolean </type> <description>true - Admin will allow the match, false - Admin will not allow the match, null - no decision yet</description></column>
35036 <column> <name>coachAgree </name> <type>boolean </type> <description>true - away coach will allow the match, false - away coach will not allow the match, null - no decision yet</description></column>
35037 <reference><name>team1 </name> <table>team </table> <description>The home team</description></reference>
35038 <reference><name>team2 </name> <table>team </table> <description>The away team</description></reference>
35039 <reference><name>field </name> <table>field </table> <description>The field on which the match will be played</description></reference>
35040 <row><col>2020-03-08</col><col>1</col><col>22</col><col>0</col><col>0</col><col>1</col><col>2</col><col>1</col></row>
35041 <row><col>2020-04-18</col><col>1</col><col>13</col><col>0</col><col>0</col><col>1</col><col>3</col><col>1</col></row>
35042 <row><col>2020-04-22</col><col>1</col><col>13</col><col>0</col><col>0</col><col>1</col><col>3</col><col>2</col></row>
35043 <row><col>2020-04-25</col><col>1</col><col>13</col><col>0</col><col>0</col><col>1</col><col>3</col><col>2</col></row>
35044 </table>
35045  
35046 <table>
35047 <name>auth</name> <hide/>
35048 <column> <name>state </name> <type>varchar(16) </type> <description>The unique state number which connects a random number on the browser to a unique github userid on the server </description></column>
35049 <column> <name>token </name> <type>varchar(64) </type> <description>The token from github </description></column>
35050 <column> <name>scope </name> <type>varchar(255)</type> <description>The scope from github </description></column>
35051 <column> <name>tokenType </name> <type>varchar(16) </type> <description>The type of token we got from github </description></column>
35052 <column> <name>avatar_url</name> <type>varchar(255)</type> <description>https://avatars1.githubusercontent.com/u/7548378?v=4 </description></column>
35053 <column> <name>bio </name> <type>varchar(255)</type> <description>Biography </description></column>
35054 <column> <name>blog </name> <type>varchar(255)</type> <description>http://www.appaapps.com </description></column>
35055 <column> <name>company </name> <type>varchar(255)</type> <description>Appa Apps Ltd Inc </description></column>
35056 <column> <name>created_at</name> <type>varchar(255)</type> <description>2014-05-11T11:19:04Z </description></column>
35057 <column> <name>email </name> <type>varchar(255)</type> <description>philiprbrenan\@gmail.com </description></column>
35058 <column> <name>location </name> <type>varchar(255)</type> <description>Terra </description></column>
35059 <column> <name>login </name> <type>varchar(255)</type> <description>philiprbrenan </description></column>
35060 <column> <name>name </name> <type>varchar(255)</type> <description>philip r brenan </description></column>
35061 </table>
35062 </database>
35063 END
35064  
35065 my $dd = xmlToPerl($xml, $paths);
35066 my %table = map {$_->name => $_} $dd->table->@*;
35067 my %column = map {$_->name => {map {$_->name => $_} $_->column->@*}} $dd->table->@*;
35068  
35069 ok $table{auth}->hide;
35070 ok $column{matches}{coachAgree}{type} eq q(boolean);
35071 is_deeply $column{field}{street},
35072 bless({description => "Street address of the field",
35073 name => "street",
35074 type => "varchar(255)",
35075 }, "database::table::column");
35076  
35077  
35078 This is a static method and so should either be imported or invoked as:
35079  
35080 Data::Edit::Xml::checkAllPaths
35081  
35082  
35083 =head2 xmlToPerl($xml, $valid)
35084  
35085 Parse some L<Xml|https://en.wikipedia.org/wiki/XML>, validate using a description recognized by L<checkAllPaths> and return the corresponding L<Perl|http://www.perl.org/> structure. Valid fields in the returned structure can be referenced via methods with the same names as their corresponding L<Xml|https://en.wikipedia.org/wiki/XML> tags. Tags marked with B<*> or B<+> in the description processed by L<checkAllPaths> result in arrays of children, whilst tags marked with B<1> or B<?> can be referenced directly.
35086  
35087 Parameter Description
35088 1 $xml Xml represented as a string
35089 2 $valid Xml validator represented as a string
35090  
35091 B<Example:>
35092  
35093  
35094 my $paths = <<'END';
35095 database The database to be used for the table
35096 name The name of the database
35097 table + The table to be created
35098 name The name of the table
35099 hide - Hide this table if present
35100 column + Columns in this table
35101 name The name of the column
35102 type The type of the column
35103 description A description of the purpose of the column
35104 edit ? A regular expression to edit the column data
35105  
35106 reference * References from this table
35107 name The name of the reference
35108 table The name of the referenced table
35109 description A description of the reference
35110 row * Row of data to be loaded inot the table
35111 col + Column value
35112 END
35113 is_deeply checkAllPaths($paths),
35114 {"name" => [1, "name of the database"],
35115 "table" => ["+", "The table to be created"],
35116 "table column" => ["+", "Columns in this table"],
35117 "table column description" => [1, "description of the purpose of the column"],
35118 "table column edit" => ["?", "A regular expression to edit the column data"],
35119 "table column name" => [1, "name of the column"],
35120 "table column type" => [1, "type of the column"],
35121 "table hide" => ["-", "Hide this table if present"],
35122 "table name" => [1, "name of the table"],
35123 "table reference" => ["*", "References from this table"],
35124 "table reference description" => [1, "description of the reference"],
35125 "table reference name" => [1, "name of the reference"],
35126 "table reference table" => [1, "name of the referenced table"],
35127 "table row" => ["*", "Row of data to be loaded inot the table"],
35128 "table row col" => ["+", "Column value"]
35129 };
35130  
35131 my $xml = <<'END';
35132 <database>
35133 <name>test</name>
35134 <table>
35135 <name>team</name>
35136 <column> <name>name </name> <type>varchar(255)</type> <description>Name of the team </description></column>
35137 <column> <name>age </name> <type>varchar(8) </type> <description>Junior or Senior team </description><edit>qr(\A(junior|senior)\Z)i</edit></column>
35138 <column> <name>gender</name> <type>varchar(8) </type> <description>Female or Male </description><edit>qr(\A(female|male)\Z)i </edit></column>
35139 <column> <name>school</name> <type>varchar(255)</type> <description>School attended by team </description></column>
35140 <column> <name>region</name> <type>varchar(255)</type> <description>Region team is located in </description></column>
35141 <column> <name>coach </name> <type>varchar(255)</type> <description>Email address of the coach of this team</description></column>
35142 <row><col>Lubbock Lions </col><col>junior</col><col>Female</col><col>Lubbock High </col><col>North</col><col>ll@coaches.com</col></row>
35143 <row><col>Titan Tigers </col><col>junior</col><col>Female</col><col>Titan Senior High </col><col>East </col><col>tt@coaches.com</col></row>
35144 <row><col>Saturn Samurai </col><col>junior</col><col>Male </col><col>Saturn University </col><col>West </col><col>ss@coaches.com</col></row>
35145 <row><col>Jovial Journeymen</col><col>junior</col><col>Male </col><col>University of Jupiter</col><col>South</col><col>jj@coaches.com</col></row>
35146 </table>
35147  
35148 <table>
35149 <name>field</name>
35150 <column> <name>name </name> <type>varchar(255)</type> <description>Name of the field </description></column>
35151 <column> <name>street</name> <type>varchar(255)</type> <description>Street address of the field </description></column>
35152 <column> <name>city </name> <type>varchar(255)</type> <description>City containing the field </description></column>
35153 <column> <name>zip </name> <type>char(9) </type> <description>Zip code of field </description></column>
35154 <column> <name>school</name> <type>varchar(255)</type> <description>Email address of the owner of the field </description></column>
35155 <row><col>Big Circle </col><col>1 Elm Street </col><col>Treeville </col><col>76754</col><col>Lubbock High </col></row>
35156 <row><col>Large Field </col><col>2 Oak Street </col><col>TitusCity </col><col>76224</col><col>Titan Senior High </col></row>
35157 <row><col>Small Diamond</col><col>3 Ash Street </col><col>Ioville </col><col>72754</col><col>Saturn University </col></row>
35158 <row><col>Large Oval </col><col>4 Pine Street</col><col>GanymedeCity</col><col>76334</col><col>University of Jupiter</col></row>
35159 </table>
35160  
35161 <table>
35162 <name>matches</name>
35163 <column> <name>date </name> <type>date </type> <description>Time of match </description></column>
35164 <column> <name>score1 </name> <type>int </type> <description>Goals scored by home team </description></column>
35165 <column> <name>score2 </name> <type>int </type> <description>Goals scored by away team </description></column>
35166 <column> <name>adminAgree </name> <type>boolean </type> <description>true - Admin will allow the match, false - Admin will not allow the match, null - no decision yet</description></column>
35167 <column> <name>coachAgree </name> <type>boolean </type> <description>true - away coach will allow the match, false - away coach will not allow the match, null - no decision yet</description></column>
35168 <reference><name>team1 </name> <table>team </table> <description>The home team</description></reference>
35169 <reference><name>team2 </name> <table>team </table> <description>The away team</description></reference>
35170 <reference><name>field </name> <table>field </table> <description>The field on which the match will be played</description></reference>
35171 <row><col>2020-03-08</col><col>1</col><col>22</col><col>0</col><col>0</col><col>1</col><col>2</col><col>1</col></row>
35172 <row><col>2020-04-18</col><col>1</col><col>13</col><col>0</col><col>0</col><col>1</col><col>3</col><col>1</col></row>
35173 <row><col>2020-04-22</col><col>1</col><col>13</col><col>0</col><col>0</col><col>1</col><col>3</col><col>2</col></row>
35174 <row><col>2020-04-25</col><col>1</col><col>13</col><col>0</col><col>0</col><col>1</col><col>3</col><col>2</col></row>
35175 </table>
35176  
35177 <table>
35178 <name>auth</name> <hide/>
35179 <column> <name>state </name> <type>varchar(16) </type> <description>The unique state number which connects a random number on the browser to a unique github userid on the server </description></column>
35180 <column> <name>token </name> <type>varchar(64) </type> <description>The token from github </description></column>
35181 <column> <name>scope </name> <type>varchar(255)</type> <description>The scope from github </description></column>
35182 <column> <name>tokenType </name> <type>varchar(16) </type> <description>The type of token we got from github </description></column>
35183 <column> <name>avatar_url</name> <type>varchar(255)</type> <description>https://avatars1.githubusercontent.com/u/7548378?v=4 </description></column>
35184 <column> <name>bio </name> <type>varchar(255)</type> <description>Biography </description></column>
35185 <column> <name>blog </name> <type>varchar(255)</type> <description>http://www.appaapps.com </description></column>
35186 <column> <name>company </name> <type>varchar(255)</type> <description>Appa Apps Ltd Inc </description></column>
35187 <column> <name>created_at</name> <type>varchar(255)</type> <description>2014-05-11T11:19:04Z </description></column>
35188 <column> <name>email </name> <type>varchar(255)</type> <description>philiprbrenan\@gmail.com </description></column>
35189 <column> <name>location </name> <type>varchar(255)</type> <description>Terra </description></column>
35190 <column> <name>login </name> <type>varchar(255)</type> <description>philiprbrenan </description></column>
35191 <column> <name>name </name> <type>varchar(255)</type> <description>philip r brenan </description></column>
35192 </table>
35193 </database>
35194 END
35195  
35196  
35197 my $dd = xmlToPerl($xml, $paths); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
35198  
35199 my %table = map {$_->name => $_} $dd->table->@*;
35200 my %column = map {$_->name => {map {$_->name => $_} $_->column->@*}} $dd->table->@*;
35201  
35202 ok $table{auth}->hide;
35203 ok $column{matches}{coachAgree}{type} eq q(boolean);
35204 is_deeply $column{field}{street},
35205 bless({description => "Street address of the field",
35206 name => "street",
35207 type => "varchar(255)",
35208 }, "database::table::column");
35209  
35210  
35211 This is a static method and so should either be imported or invoked as:
35212  
35213 Data::Edit::Xml::xmlToPerl
35214  
35215  
35216 =head1 Documentation
35217  
35218 Update documentation describing this module
35219  
35220 =head1 Compression
35221  
35222 Read and write files of compressed xml. These methods provide a compact, efficient way to store and retrieve parse trees to/from files.
35223  
35224 =head2 writeCompressedFile($node, $file)
35225  
35226 Write the parse tree starting at B<$node> as compressed L<Xml|https://en.wikipedia.org/wiki/XML> to the specified B<$file>. Use L<readCompressedFile|/readCompressedFile> to read the B<$file>.
35227  
35228 Parameter Description
35229 1 $node Parse tree node
35230 2 $file File to write to.
35231  
35232 B<Example:>
35233  
35234  
35235 my $a = Data::Edit::Xml::new(q(<a>).(q(<b>𝝱</b>)x1e3).q(</a>));
35236  
35237  
35238 my $file = $a->writeCompressedFile(q(zzz.xml.zip)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
35239  
35240  
35241 my $A = readCompressedFile($file);
35242  
35243 ok $a->equals($A);
35244  
35245  
35246 =head2 readCompressedFile($file)
35247  
35248 Read the specified B<$file> containing compressed L<Xml|https://en.wikipedia.org/wiki/XML> and return the root node. Use L<writeCompressedFile|/writeCompressedFile> to write the B<$file>.
35249  
35250 Parameter Description
35251 1 $file File to read.
35252  
35253 B<Example:>
35254  
35255  
35256 my $a = Data::Edit::Xml::new(q(<a>).(q(<b>𝝱</b>)x1e3).q(</a>));
35257  
35258 my $file = $a->writeCompressedFile(q(zzz.xml.zip));
35259  
35260  
35261 my $A = readCompressedFile($file); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
35262  
35263  
35264 ok $a->equals($A);
35265  
35266  
35267 This is a static method and so should either be imported or invoked as:
35268  
35269 Data::Edit::Xml::readCompressedFile
35270  
35271  
35272 =head1 Autoload
35273  
35274 Allow methods with constant parameters to be called as B<method_p1_p2>...(variable parameters) whenever it is easier to type underscores than (qw()).
35275  
35276 =head2 AUTOLOAD()
35277  
35278 Allow methods with constant parameters to be called as B<method_p1_p2>...(variable parameters) whenever it is easier to type underscores than (qw()).
35279  
35280  
35281 B<Example:>
35282  
35283  
35284 {my $a = Data::Edit::Xml::new(<<END);
35285 <a>
35286 <b>
35287 <c/>
35288 </b>
35289 </a>
35290 END
35291  
35292 my ($c, $b) = $a->byList;
35293  
35294 ok $c->at_c_b_a;
35295  
35296 ok !$c->at_b;
35297  
35298 ok -t $c->change_d_c_b eq q(d);
35299  
35300 ok ! $c->change_d_b;
35301  
35302 if (1)
35303 {my $a = Data::Edit::Xml::new(<<END);
35304 <a><b><c/><d/><e/><f/></b></a>
35305 END
35306  
35307 ok -t $a->first_b__first_c__next__next_e__next eq q(f);
35308 ok !$a->first_b__first_c__next__next_f;
35309 }
35310  
35311  
35312  
35313 =head2 Data::Edit::Xml Definition
35314  
35315  
35316 Well known attributes useful in respect to L<Xml|https://en.wikipedia.org/wiki/XML> that conforms to the L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> standard.
35317  
35318  
35319  
35320  
35321 =head3 Output fields
35322  
35323  
35324 =head4 attributes
35325  
35326 The attributes of the specified B<$node>, see also: L</Attributes>. The frequently used attributes: class, id, href, outputclass can be accessed by an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> method as in: $node->id = 'c1'.
35327  
35328 =head4 audience
35329  
35330 Attribute B<audience> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<audienceX()> to return B<q()> rather than B<undef>.
35331  
35332 =head4 class
35333  
35334 Attribute B<class> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<classX()> to return B<q()> rather than B<undef>.
35335  
35336 =head4 conditions
35337  
35338 Conditional strings attached to a node, see L</Conditions>.
35339  
35340 =head4 content
35341  
35342 Content of command: the nodes immediately below the specified B<$node> in the order in which they appeared in the source text, see also L</Contents>.
35343  
35344 =head4 data
35345  
35346 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 L<printed|/Print> methods and so can be used to add data to the L<parse|/parse> tree that will not be seen in any output L<Xml|https://en.wikipedia.org/wiki/XML> produced from the L<parse|/parse> tree.
35347  
35348 =head4 depthProfileLast
35349  
35350 The last known depth profile for this node as set by L<setDepthProfiles|/setDepthProfiles>.
35351  
35352 =head4 errorsFile
35353  
35354 Error listing file. Use this parameter to explicitly set the name of the file that will be used to write any L<parse|/parse> errors to. By default this file is named: B<zzzParseErrors/out.data>.
35355  
35356 =head4 forestNumbers
35357  
35358 Index to node by forest number as set by L<numberForest|/numberForest>.
35359  
35360 =head4 guid
35361  
35362 Attribute B<guid> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<guidX()> to return B<q()> rather than B<undef>.
35363  
35364 =head4 href
35365  
35366 Attribute B<href> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<hrefX()> to return B<q()> rather than B<undef>.
35367  
35368 =head4 id
35369  
35370 Attribute B<id> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<idX()> to return B<q()> rather than B<undef>.
35371  
35372 =head4 indexes
35373  
35374 Indexes to sub commands by tag in the order in which they appeared in the source text.
35375  
35376 =head4 input
35377  
35378 Source of the L<parse|/parse> if this is the L<parser|/parse> root node. Use this parameter to specify some input either as a string or as a file name for the L<parser|/parse> to convert into a L<parse|/parse> tree.
35379  
35380 =head4 inputFile
35381  
35382 Source file of the L<parse|/parse> if this is the L<parser|/parse> root node. Use this parameter to explicitly set the file to be L<parsed|/parse>.
35383  
35384 =head4 inputString
35385  
35386 Source string of the L<parse|/parse> if this is the L<parser|/parse> root node. Use this parameter to explicitly set the string to be L<parsed|/parse>.
35387  
35388 =head4 labels
35389  
35390 The labels attached to a node to provide addressability from other nodes, see: L</Labels>.
35391  
35392 =head4 lang
35393  
35394 Attribute B<lang> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<langX()> to return B<q()> rather than B<undef>.
35395  
35396 =head4 lineNumbers
35397  
35398 If true then save the line number.column number at which tag starts and ends on the xtrf attribute of each node.
35399  
35400 =head4 navtitle
35401  
35402 Attribute B<navtitle> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<navtitleX()> to return B<q()> rather than B<undef>.
35403  
35404 =head4 number
35405  
35406 Number of the specified B<$node>, see L<findByNumber|/findByNumber>.
35407  
35408 =head4 numbering
35409  
35410 Last number used to number a node in this L<parse|/parse> tree.
35411  
35412 =head4 numbers
35413  
35414 Nodes by number.
35415  
35416 =head4 otherprops
35417  
35418 Attribute B<otherprops> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<otherpropsX()> to return B<q()> rather than B<undef>.
35419  
35420 =head4 outputclass
35421  
35422 Attribute B<outputclass> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<outputclassX()> to return B<q()> rather than B<undef>.
35423  
35424 =head4 parent
35425  
35426 Parent node of the specified B<$node> or B<undef> if the L<parser|/parse> root node. See also L</Traversal> and L</Navigation>. Consider as read only.
35427  
35428 =head4 parser
35429  
35430 L<Parser|/parse> details: the root node of a tree is the L<parser|/parse> node for that tree. Consider as read only.
35431  
35432 =head4 props
35433  
35434 Attribute B<props> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<propsX()> to return B<q()> rather than B<undef>.
35435  
35436 =head4 representationLast
35437  
35438 The last representation set for this node by one of: L<setRepresentationAsTagsAndText|/setRepresentationAsTagsAndText>.
35439  
35440 =head4 style
35441  
35442 Attribute B<style> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<styleX()> to return B<q()> rather than B<undef>.
35443  
35444 =head4 tag
35445  
35446 Tag name for the specified B<$node>, see also L</Traversal> and L</Navigation>. Consider as read only.
35447  
35448 =head4 text
35449  
35450 Text of the specified B<$node> but only if it is a text node otherwise B<undef>, i.e. the tag is cdata() <=> L</isText> is true.
35451  
35452 =head4 type
35453  
35454 Attribute B<type> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<typeX()> to return B<q()> rather than B<undef>.
35455  
35456 =head4 xtrc
35457  
35458 Attribute B<xtrc> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<classX()> to return B<q()> rather than B<undef>.
35459  
35460 =head4 xtrf
35461  
35462 Attribute B<xtrf> for a node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>. Use B<classX()> to return B<q()> rather than B<undef>.
35463  
35464  
35465  
35466 =head2 Data::Edit::Xml::Example Definition
35467  
35468  
35469 Description of a pcd method
35470  
35471  
35472  
35473  
35474 =head3 Output fields
35475  
35476  
35477 =head4 also
35478  
35479 See also
35480  
35481 =head4 before
35482  
35483 Before file content minus root tag which will be added as <a>
35484  
35485 =head4 code
35486  
35487 Pcd code
35488  
35489 =head4 doc
35490  
35491 One line summary
35492  
35493 =head4 method
35494  
35495 Method
35496  
35497  
35498  
35499 =head2 Data::Edit::Xml::Table::Statistics Definition
35500  
35501  
35502 Statistics about a table
35503  
35504  
35505  
35506  
35507 =head3 Output fields
35508  
35509  
35510 =head4 colSpec
35511  
35512 Number of colspec entries
35513  
35514 =head4 colsAttribute
35515  
35516 Column attribute
35517  
35518 =head4 maxBody
35519  
35520 Maximum number of entries in a body row regardless of padding rows
35521  
35522 =head4 maxBodyMinusPadding
35523  
35524 Maximum number of entries in a body row after an padding entries have been removed
35525  
35526 =head4 maxHead
35527  
35528 Maximum number of entries in a head row regardless of padding rows
35529  
35530 =head4 maxHeadMinusPadding
35531  
35532 Maximum number of entries in a head row after an padding entries have been removed
35533  
35534 =head4 minBody
35535  
35536 Maximum number of entries in a body row regardless of padding rows
35537  
35538 =head4 minHead
35539  
35540 Maximum number of entries in a head row regardless of padding rows
35541  
35542 =head4 rows
35543  
35544 Number of rows
35545  
35546  
35547  
35548 =head1 Attributes
35549  
35550  
35551 The following is a list of all the attributes in this package. A method coded
35552 with the same name in your package will over ride the method of the same name
35553 in this package and thus provide your value for the attribute in place of the
35554 default value supplied for this attribute by this package.
35555  
35556 =head2 Replaceable Attribute List
35557  
35558  
35559 DESTROY
35560  
35561  
35562 =head2 DESTROY
35563  
35564 TO avoid seeing it in AUTOLOAD
35565  
35566  
35567  
35568  
35569 =head1 Private Methods
35570  
35571 =head2 reduceParseErroMessage($e)
35572  
35573 Reduce the parse failure message to the bare essentials.
35574  
35575 Parameter Description
35576 1 $e Error message
35577  
35578 =head2 tree($parent, $parse)
35579  
35580 Build a tree representation of the parsed L<Xml|https://en.wikipedia.org/wiki/XML> which can be easily traversed to look for things.
35581  
35582 Parameter Description
35583 1 $parent The parent node
35584 2 $parse The remaining parse
35585  
35586 =head2 addLineNumbers($string)
35587  
35588 Add line numbers to the source
35589  
35590 Parameter Description
35591 1 $string Source string
35592  
35593 =head2 disconnectLeafNode($node)
35594  
35595 Remove a leaf node from the parse tree and make it into its own parse tree.
35596  
35597 Parameter Description
35598 1 $node Leaf node to disconnect.
35599  
35600 =head2 reindexNode($node)
35601  
35602 Index the children of a node so that we can access them by tag and number.
35603  
35604 Parameter Description
35605 1 $node Node to index.
35606  
35607 =head2 indexNode($node)
35608  
35609 Merge multiple text segments and set parent and parser after changes to a node
35610  
35611 Parameter Description
35612 1 $node Node to index.
35613  
35614 =head2 normalizeWhiteSpace($string)
35615  
35616 Normalize white space, remove comments DOCTYPE and L<Xml|https://en.wikipedia.org/wiki/XML> processors from a string
35617  
35618 Parameter Description
35619 1 $string String to normalize
35620  
35621 This is a static method and so should either be imported or invoked as:
35622  
35623 Data::Edit::Xml::normalizeWhiteSpace
35624  
35625  
35626 =head2 prettyStringHtml2($node, $depth)
35627  
35628 Return a string of html representing a node of a L<parse|/parse> tree and all the nodes below it. Or use L<-p|/opString> $node
35629  
35630 Parameter Description
35631 1 $node Start node
35632 2 $depth Optional depth.
35633  
35634 =head2 prettyStringEnd($node)
35635  
35636 Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it as a here document
35637  
35638 Parameter Description
35639 1 $node Start node
35640  
35641 =head2 jsonString2($node)
35642  
35643 Return a Json representation of a parse tree
35644  
35645 Parameter Description
35646 1 $node Start node of parse tree
35647  
35648 =head2 jsonToXml2($node)
35649  
35650 Convert a json string to an L<Xml|https://en.wikipedia.org/wiki/XML> parse tree
35651  
35652 Parameter Description
35653 1 $node Start node of parse tree
35654  
35655 =head2 by2($node, $sub, @context)
35656  
35657 Post-order traversal of a L<parse|/parse> tree
35658  
35659 Parameter Description
35660 1 $node Starting node
35661 2 $sub Sub to call for each sub node
35662 3 @context Accumulated context.
35663  
35664 =head2 By22($node, $sub)
35665  
35666 Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. A reference to the current node is also made available via L<$_>. This is equivalent to the L<x=|/opBy> operator.
35667  
35668 Parameter Description
35669 1 $node Starting node
35670 2 $sub Sub to call for each sub node
35671  
35672 =head2 byX2($node, $sub, @context)
35673  
35674 Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval|http://perldoc.perl.org/functions/eval.html>B<{}> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
35675  
35676 Parameter Description
35677 1 $node Starting node
35678 2 $sub Sub to call
35679 3 @context Accumulated context.
35680  
35681 =head2 byX22($node, $sub, @context)
35682  
35683 Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval|http://perldoc.perl.org/functions/eval.html>B<{}> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
35684  
35685 Parameter Description
35686 1 $node Starting node
35687 2 $sub Sub to call
35688 3 @context Accumulated context.
35689  
35690 =head2 downX2($node, $sub, @context)
35691  
35692 Pre-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval|http://perldoc.perl.org/functions/eval.html>B<{}> at each node and returning the specified starting node. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry>. The value of the current node is also made available via L<$_>.
35693  
35694 Parameter Description
35695 1 $node Starting node
35696 2 $sub Sub to call
35697 3 @context Accumulated context.
35698  
35699 =head2 downToDie2($node, $sub, @context)
35700  
35701 Pre-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die|http://perldoc.perl.org/functions/die.html>. The traversal of the current sub tree is halted and continue with the next sibling or parent if the called sub does L<die|http://perldoc.perl.org/functions/die.html>. The B<sub> is passed references to the current node and all of its L<ancestors|/ancestry> up to the node on which this sub was called. A reference to the current node is also made available via L<$_>.
35702  
35703 Returns the start node regardless of the outcome of calling B<sub>.
35704  
35705 Parameter Description
35706 1 $node Starting node
35707 2 $sub Sub to call
35708 3 @context Accumulated context.
35709  
35710 =head2 parseLineLocation($loc)
35711  
35712 Parse a line location
35713  
35714 Parameter Description
35715 1 $loc Location
35716  
35717 This is a static method and so should either be imported or invoked as:
35718  
35719 Data::Edit::Xml::parseLineLocation
35720  
35721  
35722 =head2 atPositionMatch($tag, $match)
35723  
35724 Confirm that a string matches a match expression.
35725  
35726 Parameter Description
35727 1 $tag Starting node
35728 2 $match Ancestry.
35729  
35730 =head2 numberNode($node)
35731  
35732 Ensure that the specified B<$node> has a number.
35733  
35734 Parameter Description
35735 1 $node Node
35736  
35737 =head2 countTagNames2($node, $count)
35738  
35739 Return a reference to a hash showing the number of instances of each tag on and below the specified B<$node>.
35740  
35741 Parameter Description
35742 1 $node Node
35743 2 $count Count of tags so far.
35744  
35745 =head2 countNonEmptyTags2($node, $count)
35746  
35747 Count the instances of non empty tags on and below the specified B<$node>.
35748  
35749 Parameter Description
35750 1 $node Node
35751 2 $count Count of tags so far.
35752  
35753 =head2 countTexts2($node, $count)
35754  
35755 Count the instances of non empty texts on and below the specified B<$node>.
35756  
35757 Parameter Description
35758 1 $node Node
35759 2 $count Texts so far
35760  
35761 =head2 countWords($node)
35762  
35763 Count instances of words in texts
35764  
35765 Parameter Description
35766 1 $node Node
35767  
35768 B<Example:>
35769  
35770  
35771 my $a = Data::Edit::Xml::new(<<END);
35772 <a>
35773 <b>aaa bbb ccc</b>
35774 <c>AAA BBB CCC</c>
35775 <c>aaa AAA</c>
35776 </a>
35777 END
35778  
35779  
35780 my $t = $a->countWords; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
35781  
35782  
35783 is_deeply $t, { AAA => 2, aaa => 2, bbb => 1, BBB => 1, CCC => 1, ccc => 1 };
35784  
35785  
35786 =head2 createRequiredCleanUp($node, @text)
35787  
35788 Create a required clean up $node with the specified B<@text>
35789  
35790 Parameter Description
35791 1 $node Node
35792 2 @text Clean up messages
35793  
35794 =head2 ditaMergeListsOnce($node)
35795  
35796 Merge the specified B<$node> with the preceding or following list or steps or substeps if possible and return the specified B<$node> regardless.
35797  
35798 Parameter Description
35799 1 $node Node
35800  
35801 =head2 ditaNumberOfColumnsInRow($row)
35802  
35803 Return estimate of the number of columns in a row
35804  
35805 Parameter Description
35806 1 $row Row
35807  
35808 =head2 ditaAddPadEntriesToTGroupRows($tgroup, $nEntries)
35809  
35810 Adding padding entries to a tgroup to make sure every row has the same number of entries
35811  
35812 Parameter Description
35813 1 $tgroup TGroup node
35814 2 $nEntries Number of entries
35815  
35816 B<Example:>
35817  
35818  
35819 my $a = Data::Edit::Xml::new(<<END);
35820 <table>
35821 <tgroup cols="1">
35822 <colspec/>
35823 <thead>
35824 <row>
35825 <entry>aaaa</entry>
35826 </row>
35827 <row>
35828 <entry>bbbb</entry>
35829 </row>
35830 </thead>
35831 <tbody>
35832 <row>
35833 <entry>cccc</entry>
35834 </row>
35835 <row>
35836 <entry>dddd</entry>
35837 </row>
35838 </tbody>
35839 </tgroup>
35840 </table>
35841 END
35842  
35843 my $g = $a->go_tgroup;
35844  
35845  
35846 $g->ditaAddPadEntriesToTGroupRows(2); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
35847  
35848  
35849 is_deeply $g->ditaTGroupStatistics,
35850 bless({
35851 colsAttribute => 1,
35852 colSpec => 1,
35853 maxBody => 2,
35854 maxBodyMinusPadding => 2,
35855 maxHead => 2,
35856 maxHeadMinusPadding => 2,
35857 minBody => 2,
35858 minHead => 2,
35859 rows => 4,
35860 }, "Data::Edit::Xml::Table::Statistics");
35861  
35862 $g->fixTGroup;
35863  
35864 ok -p $a eq <<END;
35865 <table>
35866 <tgroup cols="2">
35867 <colspec colname="c1" colnum="1" colwidth="1*"/>
35868 <colspec colname="c2" colnum="2" colwidth="1*"/>
35869 <thead>
35870 <row>
35871 <entry>aaaa</entry>
35872 <entry/>
35873 </row>
35874 <row>
35875 <entry>bbbb</entry>
35876 <entry/>
35877 </row>
35878 </thead>
35879 <tbody>
35880 <row>
35881 <entry>cccc</entry>
35882 <entry/>
35883 </row>
35884 <row>
35885 <entry>dddd</entry>
35886 <entry/>
35887 </row>
35888 </tbody>
35889 </tgroup>
35890 </table>
35891 END
35892  
35893 is_deeply $g->ditaTGroupStatistics,
35894 bless({
35895 colsAttribute => 2,
35896 colSpec => 2,
35897 maxBody => 2,
35898 maxBodyMinusPadding => 2,
35899 maxHead => 2,
35900 maxHeadMinusPadding => 2,
35901 minBody => 2,
35902 minHead => 2,
35903 rows => 4,
35904  
35905 }, "Data::Edit::Xml::Table::Statistics");
35906  
35907 $a->fixTable;
35908 is_deeply $g->ditaTGroupStatistics,
35909 bless({
35910 colsAttribute => 2,
35911 colSpec => 2,
35912 maxBody => 2,
35913 maxBodyMinusPadding => 2,
35914 maxHead => 2,
35915 maxHeadMinusPadding => 2,
35916 minBody => 2,
35917 minHead => 2,
35918 rows => 4,
35919 }, "Data::Edit::Xml::Table::Statistics");
35920  
35921  
35922  
35923 =head2 topicTypeAndBody($type)
35924  
35925 Topic type and corresponding body.
35926  
35927 Parameter Description
35928 1 $type Type from qw(bookmap concept reference task)
35929  
35930 =head2 getSectionHeadingLevel($o)
35931  
35932 Get the heading level from a section tag.
35933  
35934 Parameter Description
35935 1 $o Node
35936  
35937 =head2 unwrapSingleParentsOfSection($tree)
35938  
35939 Unwrap single parents of section: in word documents the header is often buried in a list to gain a section number - here we remove these unnecessary items
35940  
35941 Parameter Description
35942 1 $tree Parse tree
35943  
35944 =head2 extendSectionToNextSection($tree)
35945  
35946 Extend a section tag until it meets the next section tag
35947  
35948 Parameter Description
35949 1 $tree Parse tree
35950  
35951 =head2 structureAdjacentSectionsByLevel($tree)
35952  
35953 Structure adjacent sections by level
35954  
35955 Parameter Description
35956 1 $tree Parse tree
35957  
35958 =head2 ditaUnderPNotConbody()
35959  
35960 Return a hash of items that L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> permits under B<p> but not directly under B<conbody>
35961  
35962  
35963 =head2 printAttributesReplacingIdsWithLabels($node)
35964  
35965 Print the attributes of a node replacing the id with the labels.
35966  
35967 Parameter Description
35968 1 $node Node whose attributes are to be printed.
35969  
35970 =head2 printAttributesExtendingIdsWithLabels($node)
35971  
35972 Print the attributes of a node extending the id with the labels.
35973  
35974 Parameter Description
35975 1 $node Node whose attributes are to be printed.
35976  
35977 =head2 checkParentage($x)
35978  
35979 Check the parent pointers are correct in a L<parse|/parse> tree.
35980  
35981 Parameter Description
35982 1 $x Parse tree.
35983  
35984 =head2 checkParser($x)
35985  
35986 Check that every node has a L<parse|/parse>r.
35987  
35988 Parameter Description
35989 1 $x Parse tree.
35990  
35991 =head2 nn($s)
35992  
35993 Replace new lines in a string with N to make testing easier.
35994  
35995 Parameter Description
35996 1 $s String.
35997  
35998 =head2 extractDocumentationFlags($flags, $method)
35999  
36000 Generate documentation for a method with a user flag.
36001  
36002 Parameter Description
36003 1 $flags Flags
36004 2 $method Method name.
36005  
36006 =head2 writeContentToGitHub($file, $content)
36007  
36008 Upload the contents of a string to a file on github
36009  
36010 Parameter Description
36011 1 $file File on github
36012 2 $content File contents
36013  
36014 =head2 writeFileToGitHub($file, $localFile)
36015  
36016 Upload the contents of the specified local file to a file on github
36017  
36018 Parameter Description
36019 1 $file File name on github
36020 2 $localFile Local file name
36021  
36022 =head2 processModuleDescription($d)
36023  
36024 Process module description to write a description of editing Xml to GitHub
36025  
36026 Parameter Description
36027 1 $d Module description
36028  
36029  
36030 =head1 Synonyms
36031  
36032 B<ca> is a synonym for L<contentAfter|/contentAfter> - Return a list of all the sibling nodes following the specified B<$node> or an empty list if the specified B<$node> is last or not in the optional B<@context>.
36033  
36034 B<cb> is a synonym for L<contentBefore|/contentBefore> - Return a list of all the sibling nodes preceding the specified B<$node> (in the normal sibling order) or an empty list if the specified B<$node> is last or not in the optional B<@context>.
36035  
36036 B<cc> is a synonym for L<change|/change> - Change the name of the specified B<$node>, optionally confirming that the B<$node> is in a specified context and return the B<$node>.
36037  
36038 B<ck> is a synonym for L<change|/change> - Change the name of the specified B<$node>, optionally confirming that the B<$node> is in a specified context and return the B<$node>.
36039  
36040 B<cr> is a synonym for L<countReport|/countReport> - Count tags, attributes, words below the specified node
36041  
36042 B<cs> is a synonym for L<ditaConvertConceptToSection|/ditaConvertConceptToSection> - Convert a Dita B<concept> to a B<$section> .
36043  
36044 B<ct> is a synonym for L<ditaConvertConceptToTask|/ditaConvertConceptToTask> - Convert a Dita B<concept> to a B<task> by representing B<ol> as B<steps>.
36045  
36046 B<firstLeaf> is a synonym for L<downWhileFirst|/downWhileFirst> - Move down from the specified B<$node> as long as each lower node is a first node.
36047  
36048 B<get> is a synonym for L<getNodeAs|/getNodeAs> - Return the specified B<$node> unless it is possible to return the node saved with L<putNodeAs> under the specified B<name> and we are optionally in the specified B<@context>.
36049  
36050 B<h> is a synonym for L<help|/help> - Get help for a node and the editor
36051  
36052 B<lastLeaf> is a synonym for L<downWhileLast|/downWhileLast> - Move down from the specified B<$node> as long as each lower node is a last node.
36053  
36054 B<ma> is a synonym for L<moveSelectionAfter|/moveSelectionAfter> - Move the current selection (if there is one) after the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
36055  
36056 B<mb> is a synonym for L<moveSelectionBefore|/moveSelectionBefore> - Move the current selection (if there is one) before the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
36057  
36058 B<mf> is a synonym for L<moveSelectionFirst|/moveSelectionFirst> - Move the current selection (if there is one) so that it is first under the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
36059  
36060 B<ml> is a synonym for L<moveSelectionLast|/moveSelectionLast> - Move the current selection (if there is one) so that it is last under the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
36061  
36062 B<mln> is a synonym for L<mergeLikeNext|/mergeLikeNext> - Merge a B<$node> in an optional context with the next node if the two have the same tag by placing the next node first in the current B<$node> and unwrapping the next node.
36063  
36064 B<mlp> is a synonym for L<mergeLikePrev|/mergeLikePrev> - Merge a B<$node> in an optional context with the previous node if the two have the same tag by placing the previous node first in the current B<$node> and unwrapping the previous node.
36065  
36066 B<mocln> is a synonym for L<mergeOnlyChildLikeNext|/mergeOnlyChildLikeNext> - Merge a B<$node> if it is the only child of its parent with a preceding node of the same name that is also the only child of its parent and return the specified B<$node> or B<undef> if the request fails.
36067  
36068 B<moclp> is a synonym for L<mergeOnlyChildLikePrev|/mergeOnlyChildLikePrev> - Merge a B<$node> if it is the only child of its parent with a preceding node of the same name that is also the only child of its parent and return the specified B<$node> or B<undef> if the request fails.
36069  
36070 B<oat> is a synonym for L<overAllTags|/overAllTags> - Return the specified b<$node> if all of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
36071  
36072 B<oft> is a synonym for L<overFirstTags|/overFirstTags> - Return the specified b<$node> if the first of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
36073  
36074 B<olt> is a synonym for L<overLastTags|/overLastTags> - Return the specified b<$node> if the last of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
36075  
36076 B<p> is a synonym for L<parentage|/parentage> - Return a reference to an array of the nodes along the path from the root to the specified B<$Node> inclusive.
36077  
36078 B<put> is a synonym for L<putNodeAs|/putNodeAs> - Return the specified B<$node> after saving it under the specified B<$name> if we are in the optional B<@context>.
36079  
36080 B<r> is a synonym for L<dupPutNext|/dupPutNext> - Duplicate the specified B<$tree> in the optional B<@context>, place the new tree next after $tree and return the root of the new tree on success else B<undef>.
36081  
36082 B<rN> is a synonym for L<dupPutNextN|/dupPutNextN> - Duplicate the specified B<$tree> B<$N> times in the optional B<@context>, placing each copy after $tree and return the last new node created on success else B<undef>.
36083  
36084 B<rn> is a synonym for L<reportNode|/reportNode> - Print the parse tree starting at the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
36085  
36086 B<rna> is a synonym for L<reportNodeAttributes|/reportNodeAttributes> - Print the attributes of the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
36087  
36088 B<rnc> is a synonym for L<reportNodeContext|/reportNodeContext> - Print the context of the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
36089  
36090 B<sc> is a synonym for L<ditaConvertSectionToConcept|/ditaConvertSectionToConcept> - Convert a Dita B<$section> to a B<concept>.
36091  
36092 B<se> is a synonym for L<setSelectionEnd|/setSelectionEnd> - Set the selection to end at the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
36093  
36094 B<sfs> is a synonym for L<swapFirstSibling|/swapFirstSibling> - Swap B<$node> with its first sibling node and return B<$node>.
36095  
36096 B<sls> is a synonym for L<swapLastSibling|/swapLastSibling> - Swap B<$node> with its last sibling node and return B<$node>.
36097  
36098 B<sn> is a synonym for L<swapNext|/swapNext> - Swap B<$node> with its following node if $B<$node> matches the first element of the specified context and the next node matches the rest.
36099  
36100 B<sp> is a synonym for L<swapPrev|/swapPrev> - Swap B<$node> with its preceding node if $B<$node> matches the first element of the specified context and the previous node matches the rest.
36101  
36102 B<spa> is a synonym for L<splitParentAfter|/splitParentAfter> - Finish and restart the parent of the specified B<$node> just after the specified B<$node> and return the newly created parent node on success or B<undef> on failure.
36103  
36104 B<spb> is a synonym for L<splitParentBefore|/splitParentBefore> - Finish and restart the parent of the specified B<$node> just before the specified B<$node> and return the newly created parent node on success or B<undef> on failure.
36105  
36106 B<ss> is a synonym for L<setSelectionStart|/setSelectionStart> - Set the selection to start at the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
36107  
36108 B<u> is a synonym for L<unwrap|/unwrap> - Unwrap the specified B<$node> if in the optional B<@context> by replacing the node with its contents.
36109  
36110 B<wcw> is a synonym for L<wrapContentWith|/wrapContentWith> - Wrap the content of the specified B<$node> in a new node created from the specified B<$tag> and B<%attributes>: the specified B<$node> then contains just the new node which, in turn, contains all the content of the specified B<$node>.
36111  
36112 B<ww> is a synonym for L<wrapWithAll|/wrapWithAll> - Wrap this B<$node> wrapped with the specified B<@tags> and return the last wrapping node.
36113  
36114 B<x> is a synonym for L<cut|/cut> - Cut out and return the specified B<$node> so that it can be reinserted else where in the L<parse|/parse> tree.
36115  
36116  
36117  
36118 =head1 Index
36119  
36120  
36121 1 L<above|/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 B<undef>
36122  
36123 2 L<abovePath|/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 B<()>.
36124  
36125 3 L<addAttr|/addAttr> - Check the specified B<$node> for the specified B<%attributes> and add any that are not already set.
36126  
36127 4 L<addConditions|/addConditions> - Given a B<$node> add the specified B<@conditions> and return the node.
36128  
36129 5 L<addFirst|/addFirst> - Add a new node L<first|/first> below the specified B<$node> with the specified B<$tag> unless a node with that tag already exists in that position.
36130  
36131 6 L<addFirstAsText|/addFirstAsText> - Add a new text node first below the specified B<$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 B<$node>.
36132  
36133 7 L<addLabels|/addLabels> - Add the named labels to the specified B<$node> and return the number of labels added.
36134  
36135 8 L<addLast|/addLast> - Add a new node L<last|/last> below the specified B<$node> with the specified B<$tag> unless a node with that tag already exists in that position.
36136  
36137 9 L<addLastAsText|/addLastAsText> - Add a new text node last below the specified B<$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 B<$node>.
36138  
36139 10 L<addLineNumbers|/addLineNumbers> - Add line numbers to the source
36140  
36141 11 L<addNext|/addNext> - Add a new node L<next|/next> the specified B<$node> and return the new node unless a node with that tag already exists in which case return the existing B<$node>.
36142  
36143 12 L<addNextAsText|/addNextAsText> - Add a new text node after the specified B<$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 B<$node>.
36144  
36145 13 L<addPrev|/addPrev> - Add a new node L<before|/prev> the specified B<$node> with the specified B<$tag> unless a node with that tag already exists in that position.
36146  
36147 14 L<addPrevAsText|/addPrevAsText> - Add a new text node before the specified B<$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 B<$node>.
36148  
36149 15 L<addSingleChild|/addSingleChild> - Wrap the content of a specified B<$node> in a new node with the specified B<$tag> unless the content is already wrapped in a single child with the specified B<$tag>.
36150  
36151 16 L<addWrapWith|/addWrapWith> - L<Wrap|/wrap> the specified B<$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 B<$node>.
36152  
36153 17 L<adjacent|/adjacent> - Return the first node if it is adjacent to the second node else B<undef>.
36154  
36155 18 L<adoptChild|/adoptChild> - Lift the specified B<$child> node up until it is an immediate child of the specified B<$parent> node by splitting any intervening nodes.
36156  
36157 19 L<after|/after> - Return the first node if it occurs after the second node in the L<parse|/parse> tree optionally checking that the first node is in the specified context or else B<undef> if the node is L<above|/above>, L<below|/below> or L<before|/before> the target.
36158  
36159 20 L<allConditions|/allConditions> - Return the B<$node> if it has all of the specified B<@conditions>, else return B<undef>
36160  
36161 21 L<an|/an> - Return the next node if the specified B<$node> has the tag specified by B<$current> and the next node is in the specified B<@context>.
36162  
36163 22 L<ancestry|/ancestry> - Return a list containing: (the specified B<$node>, its parent, its parent's parent etc.
36164  
36165 23 L<anyCondition|/anyCondition> - Return the B<$node> if it has any of the specified B<@conditions>, else return B<undef>
36166  
36167 24 L<ap|/ap> - Return the previous node if the specified B<$node> has the tag specified by B<$current> and the previous node is in the specified B<@context>.
36168  
36169 25 L<apn|/apn> - Return (previous node, next node) if the B<$previous> and B<$current> nodes have the specified tags and the next node is in the specified B<@context> else return B<()>.
36170  
36171 26 L<approxLocation|/approxLocation> - Return the line number.
36172  
36173 27 L<at|/at> - Confirm that the specified B<$node> has the specified L<ancestry|/ancestry>.
36174  
36175 28 L<atOrBelow|/atOrBelow> - Confirm that the node or one of its ancestors has the specified context as recognized by L<at|/at> and return the first node that matches the context or B<undef> if none do.
36176  
36177 29 L<atPositionMatch|/atPositionMatch> - Confirm that a string matches a match expression.
36178  
36179 30 L<atStringContentMatches|/atStringContentMatches> - Confirm that we are on a B<$node> whose contents, represented as a string, matches the specified regular expression B<$re> in the optional B<@context>.
36180  
36181 31 L<atText|/atText> - Confirm that we are on a text node whose text value matches a regular expression in the optional B<@context>.
36182  
36183 32 L<atTop|/atTop> - Return the current node if it is the root == top of a parse tree else return B<undef>.
36184  
36185 33 L<attr|/attr> - Return the value of an attribute of the current node as an L<lvalue method|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines> B<sub>.
36186  
36187 34 L<attrAt|/attrAt> - Return the specified B<$node> if it has the specified B<$attribute> and the $node is in the optional B<@context> else return B<undef>.
36188  
36189 35 L<attrCount|/attrCount> - Return the number of attributes in the specified B<$node>, optionally ignoring the specified names from the count.
36190  
36191 36 L<attrs|/attrs> - Return the values of the specified attributes of the current node as a list
36192  
36193 37 L<attrsNone|/attrsNone> - Check that the specified B<$node> has no attributes.
36194  
36195 38 L<attrValueAt|/attrValueAt> - Return the specified B<$node> if it has the specified B<$attribute> with the specified B<$value> and the $node is in the optional B<@context> else return B<undef>.
36196  
36197 39 L<attrX|/attrX> - Return the value of the specified B<$attribute> of the specified B<$node> or B<q()> if the B<$node> does not have such an attribute.
36198  
36199 40 L<AUTOLOAD|/AUTOLOAD> - Allow methods with constant parameters to be called as B<method_p1_p2>.
36200  
36201 41 L<before|/before> - Return the first node if it occurs before the second node in the L<parse|/parse> tree optionally checking that the first node is in the specified context or else B<undef> if the node is L<above|/above>, L<below|/below> or L<before|/before> the target.
36202  
36203 42 L<below|/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 B<undef>
36204  
36205 43 L<belowPath|/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 B<()>.
36206  
36207 44 L<bitsNodeTextBlank|/bitsNodeTextBlank> - Return a bit string that shows if there are any non text nodes, text nodes or blank text nodes under a node.
36208  
36209 45 L<breakIn|/breakIn> - Concatenate the nodes following and preceding the start node, unwrapping nodes whose tag matches the start node and return the start node.
36210  
36211 46 L<breakInBackwards|/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 L<breakIn|/breakIn>.
36212  
36213 47 L<breakInForwards|/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 L<breakIn|/breakIn>.
36214  
36215 48 L<breakOut|/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.
36216  
36217 49 L<breakOutChild|/breakOutChild> - Lift the specified B<$node> up one level splitting its parent.
36218  
36219 50 L<by|/by> - Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node.
36220  
36221 51 L<by2|/by2> - Post-order traversal of a L<parse|/parse> tree
36222  
36223 52 L<By22|/By22> - Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node.
36224  
36225 53 L<byList|/byList> - Return a list of all the nodes at and below a specified B<$node> in post-order or the empty list if the B<$node> is not in the optional B<@context>.
36226  
36227 54 L<byReverse|/byReverse> - Reverse post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting B<$node>.
36228  
36229 55 L<byReverseList|/byReverseList> - Return a list of all the nodes at and below a specified B<$node> in reverse preorder or the empty list if the specified B<$node> is not in the optional B<@context>.
36230  
36231 56 L<byReverseX|/byReverseX> - Reverse post-order traversal of a L<parse|/parse> tree or sub tree below the specified B<$node> calling the specified B<sub> within L<eval|http://perldoc.perl.org/functions/eval.html>B<{}> at each node and returning the specified starting B<$node>.
36232  
36233 57 L<byX|/byX> - Post-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die|http://perldoc.perl.org/functions/die.html>.
36234  
36235 58 L<byX2|/byX2> - Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval|http://perldoc.perl.org/functions/eval.html>B<{}> at each node and returning the specified starting node.
36236  
36237 59 L<byX22|/byX22> - Post-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval|http://perldoc.perl.org/functions/eval.html>B<{}> at each node and returning the specified starting node.
36238  
36239 60 L<c|/c> - Return an array of all the nodes with the specified tag below the specified B<$node>.
36240  
36241 61 L<cdata|/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 L<confess|http://perldoc.perl.org/Carp.html#SYNOPSIS/>.
36242  
36243 62 L<change|/change> - Change the name of the specified B<$node>, optionally confirming that the B<$node> is in a specified context and return the B<$node>.
36244  
36245 63 L<changeAttr|/changeAttr> - Rename attribute B<$old> to B<$new> in the specified B<$node> with optional context B<@context> unless attribute B<$new> is already set and return the B<$node>.
36246  
36247 64 L<changeAttributeValue|/changeAttributeValue> - Apply a sub to the value of an attribute of the specified B<$node>.
36248  
36249 65 L<changeAttrValue|/changeAttrValue> - Rename attribute B<$old> to B<$new> with new value B<$newValue> on the specified B<$node> in the optional B<@context> unless attribute B<$new> is already set or the value of the B<$old> attribute is not B<$oldValue>.
36250  
36251 66 L<changeKids|/changeKids> - Change the names of all the immediate children of the specified B<$node>, if they match the optional B<@context>, to the specified B<$tag> and return the B<$node>.
36252  
36253 67 L<changeOrDeleteAttr|/changeOrDeleteAttr> - Rename attribute B<$old> to B<$new> in the specified B<$node> in the optional B<@context> unless attribute B<$new> is already set in which case delete attribute B<$old>.
36254  
36255 68 L<changeOrDeleteAttrValue|/changeOrDeleteAttrValue> - Rename attribute B<$old> to B<$new> with new value B<$newValue> on the specified B<$node> in the optional B<@context> unless attribute B<$new> is already set or the value of the B<$old> attribute is not B<$oldValue> in which cases the B<$old> attribute is deleted.
36256  
36257 69 L<changeReasonCommentSelectionSpecification|/changeReasonCommentSelectionSpecification> - Provide a specification to select L<change reason comments|/crc> to be inserted as text into a L<parse|/parse> tree.
36258  
36259 70 L<changeText|/changeText> - Change the content of the specified text B<$node> that matches a regular expression B<$rf> presented as a string to a string B<$rt> in the optional B<@context> and return the specified $node else return B<undef>.
36260  
36261 71 L<changeTextToSpace|/changeTextToSpace> - Change each instance of the content of the specified text B<$node> that matches a regular expression B<$re> to one space and return the specified $node else return B<undef>.
36262  
36263 72 L<checkAllPaths|/checkAllPaths> - Create a representation of all the paths permitted in a block of L<Xml|https://en.wikipedia.org/wiki/XML>.
36264  
36265 73 L<checkParentage|/checkParentage> - Check the parent pointers are correct in a L<parse|/parse> tree.
36266  
36267 74 L<checkParser|/checkParser> - Check that every node has a L<parse|/parse>r.
36268  
36269 75 L<childOf|/childOf> - Returns the specified B<$child> node if it is a child of the specified B<$parent> node and the B<$child> node is in the specified optional context.
36270  
36271 76 L<clone|/clone> - Return a clone of the entire L<parse|/parse> tree which is created using the fast L<Storable::dclone> method.
36272  
36273 77 L<closestLocation|/closestLocation> - Return the nearest node with line number.
36274  
36275 78 L<commonAdjacentAncestors|/commonAdjacentAncestors> - Given two nodes, find a pair of adjacent ancestral siblings if such a pair exists else return B<()>.
36276  
36277 79 L<commonAncestor|/commonAncestor> - Find the most recent common ancestor of the specified nodes or B<undef> if there is no common ancestor.
36278  
36279 80 L<concatenate|/concatenate> - Concatenate two successive nodes and return the B<$target> node.
36280  
36281 81 L<concatenateSiblings|/concatenateSiblings> - Concatenate the nodes that precede and follow the specified B<$node> in the optioonal B<@context> as long as they have the same tag as the specified B<$node> and return the specified B<$node>.
36282  
36283 82 L<condition|/condition> - Return the B<$node> if it has the specified B<$condition> and is in the optional B<@context>, else return B<undef>
36284  
36285 83 L<containsSingleText|/containsSingleText> - Return the single text element below the specified B<$node> else return B<undef>.
36286  
36287 84 L<contentAfter|/contentAfter> - Return a list of all the sibling nodes following the specified B<$node> or an empty list if the specified B<$node> is last or not in the optional B<@context>.
36288  
36289 85 L<contentAfterAsTags|/contentAfterAsTags> - Return a string containing the tags of all the sibling nodes following the specified B<$node> separated by single spaces or the empty string if the node is empty or B<undef> if the node does not match the optional context.
36290  
36291 86 L<contentAfterAsTags2|/contentAfterAsTags2> - Return a string containing the tags of all the sibling nodes following the specified B<$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 B<undef> if the node does not match the optional context.
36292  
36293 87 L<contentAsTags|/contentAsTags> - Return a string containing the tags of all the child nodes of the specified B<$node> separated by single spaces or the empty string if the node is empty or B<undef> if the node does not match the optional context.
36294  
36295 88 L<contentAsTags2|/contentAsTags2> - Return a string containing the tags of all the child nodes of the specified B<$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 B<undef> if the node does not match the optional context.
36296  
36297 89 L<contentBefore|/contentBefore> - Return a list of all the sibling nodes preceding the specified B<$node> (in the normal sibling order) or an empty list if the specified B<$node> is last or not in the optional B<@context>.
36298  
36299 90 L<contentBeforeAsTags|/contentBeforeAsTags> - Return a string containing the tags of all the sibling nodes preceding the specified B<$node> separated by single spaces or the empty string if the node is empty or B<undef> if the node does not match the optional context.
36300  
36301 91 L<contentBeforeAsTags2|/contentBeforeAsTags2> - Return a string containing the tags of all the sibling nodes preceding the specified B<$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 B<undef> if the node does not match the optional context.
36302  
36303 92 L<contents|/contents> - Return a list of all the nodes contained by the specified B<$node> or an empty list if the node is empty or not in the optional B<@context>.
36304  
36305 93 L<context|/context> - Return a string containing the tag of the starting node and the tags of all its ancestors separated by single spaces.
36306  
36307 94 L<copyAttrs|/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.
36308  
36309 95 L<copyAttrsFromParent|/copyAttrsFromParent> - Copy all the attributes from the parent (if there is one) of the current B<$node> to $node or just the named B<@attributes> and return $node.
36310  
36311 96 L<copyAttrsToParent|/copyAttrsToParent> - Copy all the attributes of the specified B<$node> to its parent (if there is one) or just the named B<@attributes> and return $node.
36312  
36313 97 L<copyLabels|/copyLabels> - Copy all the labels from the source node to the target node and return the source node.
36314  
36315 98 L<copyLabelsAndIdsInTree|/copyLabelsAndIdsInTree> - Copy all the labels and ids in the source parse tree to the matching nodes in the target parse tree.
36316  
36317 99 L<copyNewAttrs|/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.
36318  
36319 100 L<count|/count> - Return the count of the number of instances of the specified tags under the specified B<$node>, either by tag in array context or in total in scalar context.
36320  
36321 101 L<countAttrNames|/countAttrNames> - Return a reference to a hash showing the number of instances of each attribute on and below the specified B<$node>.
36322  
36323 102 L<countAttrNamesAndValues|/countAttrNamesAndValues> - Return a reference to a hash showing the number of instances of each attribute name and value on and below the specified B<$node>.
36324  
36325 103 L<countAttrNamesOnTagExcluding|/countAttrNamesOnTagExcluding> - Count the number of attributes owned by the specified B<$node> that are not in the specified list.
36326  
36327 104 L<countAttrValues|/countAttrValues> - Return a reference to a hash showing the number of instances of each attribute value on and below the specified B<$node>.
36328  
36329 105 L<countLabels|/countLabels> - Return the count of the number of labels at a node.
36330  
36331 106 L<countNonEmptyTags|/countNonEmptyTags> - Return a reference to a hash showing the number of instances of each non empty tag on and below the specified B<$node> excluding any tags named in B<@exclude>.
36332  
36333 107 L<countNonEmptyTags2|/countNonEmptyTags2> - Count the instances of non empty tags on and below the specified B<$node>.
36334  
36335 108 L<countOutputClasses|/countOutputClasses> - Count instances of outputclass attributes
36336  
36337 109 L<countReport|/countReport> - Count tags, attributes, words below the specified node
36338  
36339 110 L<countTagNames|/countTagNames> - Return a reference to a hash showing the number of instances of each tag on and below the specified B<$node> excluding any tags named in B<@exclude>.
36340  
36341 111 L<countTagNames2|/countTagNames2> - Return a reference to a hash showing the number of instances of each tag on and below the specified B<$node>.
36342  
36343 112 L<countTags|/countTags> - Count the number of tags in a L<parse|/parse> tree.
36344  
36345 113 L<countTexts|/countTexts> - Return a reference to a hash showing the incidence of texts on and below the specified B<$node>.
36346  
36347 114 L<countTexts2|/countTexts2> - Count the instances of non empty texts on and below the specified B<$node>.
36348  
36349 115 L<countWords|/countWords> - Count instances of words in texts
36350  
36351 116 L<crc|/crc> - Insert a comment consisting of a code and an optional reason as text into the L<parse|/parse> tree to indicate the location of changes to the L<parse|/parse> tree.
36352  
36353 117 L<createGuidId|/createGuidId> - Create an id for the specified B<$node> in the optional B<@context> from the md5Sum of its content moving any existing id to the labels associated with the B<$node> and return the existing B<$node>.
36354  
36355 118 L<createPatch|/createPatch> - Create a patch that moves the source L<parse|/parse> tree to the target L<parse|/parse> tree node as long as they have the same tag and id structure with each id being unique.
36356  
36357 119 L<createRequiredCleanUp|/createRequiredCleanUp> - Create a required clean up $node with the specified B<@text>
36358  
36359 120 L<cText|/cText> - Return an array of all the text nodes immediately below the specified B<$node>.
36360  
36361 121 L<cut|/cut> - Cut out and return the specified B<$node> so that it can be reinserted else where in the L<parse|/parse> tree.
36362  
36363 122 L<cutFirst|/cutFirst> - Cut out the first node below the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack.
36364  
36365 123 L<cutIfEmpty|/cutIfEmpty> - Cut out and return the specified B<$node> so that it can be reinserted else where in the L<parse|/parse> tree if it is empty.
36366  
36367 124 L<cutLast|/cutLast> - Cut out the last node below the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack.
36368  
36369 125 L<cutNext|/cutNext> - Cut out the next node beyond the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack.
36370  
36371 126 L<cutPrev|/cutPrev> - Cut out the previous node before the specified B<$node> if it is in the optional B<@context> and push it on the cut out stack.
36372  
36373 127 L<Data::Edit::Xml::Patch::install|/Data::Edit::Xml::Patch::install> - Replay a patch created by L<createPatch|/createPatch> against a L<parse|/parse> tree that has the same tag and id structure with each id being unique.
36374  
36375 128 L<deleteAttr|/deleteAttr> - Delete the named attribute in the specified B<$node>, optionally check its value first, returning the value of the attribute or B<undef> if the attribute does not exist on this node.
36376  
36377 129 L<deleteAttrs|/deleteAttrs> - Delete the specified attributes of the specified B<$node> without checking their values and return the node.
36378  
36379 130 L<deleteAttrsInTree|/deleteAttrsInTree> - Delete the specified attributes of the specified B<$node> and all the nodes under it and return the specified B<$node>.
36380  
36381 131 L<deleteAttrValueAtInTree|/deleteAttrValueAtInTree> - Delete all instances of the specified B<$attribute> with the specified B<$value> in the specified B<@context> in the specified B<$tree> and return the modified B<$tree>.
36382  
36383 132 L<deleteConditions|/deleteConditions> - Given a B<$node> delete any B<@conditions> applied to the $node and return the $node.
36384  
36385 133 L<deleteContent|/deleteContent> - Delete the content of the specified B<$node>.
36386  
36387 134 L<deleteLabels|/deleteLabels> - Delete the specified labels in the specified B<$node> or all labels if no labels have are specified and return that node.
36388  
36389 135 L<depth|/depth> - Returns the depth of the specified B<$node>, the depth of a root node is zero.
36390  
36391 136 L<depthProfile|/depthProfile> - Returns the depth profile of the tree rooted at the specified B<$node>.
36392  
36393 137 L<diff|/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.
36394  
36395 138 L<disconnectLeafNode|/disconnectLeafNode> - Remove a leaf node from the parse tree and make it into its own parse tree.
36396  
36397 139 L<disordered|/disordered> - Return the first node that is out of the specified order when performing a pre-ordered traversal of the L<parse|/parse> tree.
36398  
36399 140 L<ditaAbsoluteHref|/ditaAbsoluteHref> - Return the absolute value of the href of a specified B<$node> relative to the specified B<$sourceFile> or B<undef> if the node has no B<href> attribute.
36400  
36401 141 L<ditaAddColSpecToTGroup|/ditaAddColSpecToTGroup> - Add the specified B<$number> of column specification to a specified B<$tgroup> which does not have any already.
36402  
36403 142 L<ditaAddPadEntriesToTGroupRows|/ditaAddPadEntriesToTGroupRows> - Adding padding entries to a tgroup to make sure every row has the same number of entries
36404  
36405 143 L<ditaAddTopicReport|/ditaAddTopicReport> - Place a report into a dita topic using required clean up
36406  
36407 144 L<ditaConvertConceptToReference|/ditaConvertConceptToReference> - Convert a Dita B<concept> to a B<reference>.
36408  
36409 145 L<ditaConvertConceptToSection|/ditaConvertConceptToSection> - Convert a Dita B<concept> to a B<$section> .
36410  
36411 146 L<ditaConvertConceptToTask|/ditaConvertConceptToTask> - Convert a Dita B<concept> to a B<task> by representing B<ol> as B<steps>.
36412  
36413 147 L<ditaConvertDlToUl|/ditaConvertDlToUl> - Convert a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<$dl> to a B<ul> if each B<dlentry> has only B<dt> or B<dl> elements but not both.
36414  
36415 148 L<ditaConvertFromHtmlDl|/ditaConvertFromHtmlDl> - Convert a B<Html> B<$dl> to a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<dl> or return B<undef> if this is not possible.
36416  
36417 149 L<ditaConvertOlToSubSteps|/ditaConvertOlToSubSteps> - Convert a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<$ul> to B<substeps> else B<undef> if this is not possible.
36418  
36419 150 L<ditaConvertReferenceToConcept|/ditaConvertReferenceToConcept> - Convert a Dita B<reference> to a B<concept> by unwrapping sections.
36420  
36421 151 L<ditaConvertReferenceToTask|/ditaConvertReferenceToTask> - Convert a Dita B<reference> to a B<task> in situ by representing B<ol> as B<steps>.
36422  
36423 152 L<ditaConvertSectionToConcept|/ditaConvertSectionToConcept> - Convert a Dita B<$section> to a B<concept>.
36424  
36425 153 L<ditaConvertSectionToReference|/ditaConvertSectionToReference> - Convert a Dita B<$section> to a B<reference>.
36426  
36427 154 L<ditaConvertSectionToTask|/ditaConvertSectionToTask> - Convert a Dita B<$section> to a B<task>.
36428  
36429 155 L<ditaConvertSimpleTableToTable|/ditaConvertSimpleTableToTable> - Convert a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<simpletable> to a B<table>.
36430  
36431 156 L<ditaConvertSubStepsToSteps|/ditaConvertSubStepsToSteps> - Change the B<$substeps> to B<steps> and return the B<steps> on success or B<undef> on failure.
36432  
36433 157 L<ditaConvertTopicToTask|/ditaConvertTopicToTask> - Convert a topic that is not already a task into a task
36434  
36435 158 L<ditaConvertUlToSubSteps|/ditaConvertUlToSubSteps> - Convert a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<$ol> to B<substeps> else B<undef> if this is not possible.
36436  
36437 159 L<ditaCouldConvertConceptToTask|/ditaCouldConvertConceptToTask> - Check whether a concept could be converted to a task
36438  
36439 160 L<ditaCutTopicmetaFromAClassificationMap|/ditaCutTopicmetaFromAClassificationMap> - Remove a topicmeta node from a classification map.
36440  
36441 161 L<ditaExpandAllConRefs|/ditaExpandAllConRefs> - Expand all the conrefs in the specified B<$parseTree> relative to the specified B<$sourceFile>.
36442  
36443 162 L<ditaFixTGroupColSpec|/ditaFixTGroupColSpec> - Fix the colspec attribute and colspec nodes of the specified B<$tgroup>.
36444  
36445 163 L<ditaGetConRef|/ditaGetConRef> - Get the value of a B<conref> attribute given a valid L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<$ref>erence found in the file named B<$sourceFile>.
36446  
36447 164 L<ditaListToChoices|/ditaListToChoices> - Change the specified B<$list> to B<choices>.
36448  
36449 165 L<ditaListToSteps|/ditaListToSteps> - Change the specified B<$node> to B<steps> and its contents to B<cmd\step> optionally only in the specified context.
36450  
36451 166 L<ditaListToStepsUnordered|/ditaListToStepsUnordered> - Change the specified B<$node> to B<steps-unordered> and its contents to B<cmd\step> optionally only in the specified context.
36452  
36453 167 L<ditaListToSubSteps|/ditaListToSubSteps> - Change the specified B<$node> to B<substeps> and its contents to B<cmd\step> optionally only in the specified context.
36454  
36455 168 L<ditaListToTable|/ditaListToTable> - Convert a list to a table in situ - as designed by MiM.
36456  
36457 169 L<ditaMaximumNumberOfEntriesInATGroupRow|/ditaMaximumNumberOfEntriesInATGroupRow> - Return the maximum number of entries in the rows of the specified B<$table> or B<undef> if not a table.
36458  
36459 170 L<ditaMergeLists|/ditaMergeLists> - Merge the specified B<$node> with the preceding or following list or steps or substeps if possible and return the specified B<$node> regardless.
36460  
36461 171 L<ditaMergeListsOnce|/ditaMergeListsOnce> - Merge the specified B<$node> with the preceding or following list or steps or substeps if possible and return the specified B<$node> regardless.
36462  
36463 172 L<ditaNumberOfColumnsInRow|/ditaNumberOfColumnsInRow> - Return estimate of the number of columns in a row
36464  
36465 173 L<ditaObviousChanges|/ditaObviousChanges> - Make obvious changes to a L<parse|/parse> tree to make it look more like L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html>.
36466  
36467 174 L<ditaParagraphToNote|/ditaParagraphToNote> - Convert all <p> nodes to <note> if the paragraph starts with 'Note:', optionally wrapping the content of the <note> with a <p>
36468  
36469 175 L<ditaPrettyPrintWithHeaders|/ditaPrettyPrintWithHeaders> - Add L<Xml|https://en.wikipedia.org/wiki/XML> headers for the dita document type indicated by the specified L<parse|/parse> tree to a pretty print of the parse tree.
36470  
36471 176 L<ditaRemoveTGroupTrailingEmptyEntries|/ditaRemoveTGroupTrailingEmptyEntries> - Remove empty trailing entry
36472  
36473 177 L<ditaReplaceAnyConref|/ditaReplaceAnyConref> - Replace a conref with the referenced content if we are in the optional context and the target of the conref can be located.
36474  
36475 178 L<ditaReplaceAnyConrefIdeallyWithMatchingTag|/ditaReplaceAnyConrefIdeallyWithMatchingTag> - Replace a conref with the referenced content if we are in the optional context and the target of the conref can be located.
36476  
36477 179 L<ditaReplaceAnyConrefInContext|/ditaReplaceAnyConrefInContext> - Replace a conref with the referenced content if we are in the optional context and the target of the conref can be located and the L<context> of the target node matches the regular expression B<$context>.
36478  
36479 180 L<ditaReplaceConref|/ditaReplaceConref> - Replace a conref on the specified B<$node> in the specified source file B<$sourceFile> with the parse tree of the referenced content.
36480  
36481 181 L<ditaRoot|/ditaRoot> - Return the specified B<$node> if it a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> root node else return B<undef>.
36482  
36483 182 L<ditaSampleBookMap|/ditaSampleBookMap> - Sample bookmap
36484  
36485 183 L<ditaSampleConcept|/ditaSampleConcept> - Sample concept
36486  
36487 184 L<ditaSampleTask|/ditaSampleTask> - Sample task
36488  
36489 185 L<ditaStepsToChoices|/ditaStepsToChoices> - Change the specified B<$node> to B<choices>.
36490  
36491 186 L<ditaStepsToList|/ditaStepsToList> - Change the specified B<$node> to a node with name B<$tag> or to B<ol> if B<$tag> is not supplied and its B<cmd\step> content to B<li> to create a list optionally only in the specified context.
36492  
36493 187 L<ditaSyntaxDiagramFromDocBookCmdSynopsis|/ditaSyntaxDiagramFromDocBookCmdSynopsis> - Convert doc book cmdsynopsis to Dita syntax diagram
36494  
36495 188 L<ditaSyntaxDiagramToBasicRepresentation|/ditaSyntaxDiagramToBasicRepresentation> - Convert Dita syntax diagrams into Micaela's Basic Version.
36496  
36497 189 L<ditaTGroupStatistics|/ditaTGroupStatistics> - Return statistics about the rows in a given table
36498  
36499 190 L<ditaTopicHeaders|/ditaTopicHeaders> - Add L<Xml|https://en.wikipedia.org/wiki/XML> headers for the dita document type indicated by the specified L<parse|/parse> tree
36500  
36501 191 L<ditaUnderPNotConbody|/ditaUnderPNotConbody> - Return a hash of items that L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> permits under B<p> but not directly under B<conbody>
36502  
36503 192 L<ditaWrapWithPUnderConbody|/ditaWrapWithPUnderConbody> - Wrap items immediately under L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> B<conbody> with B<p> or merge with any previous B<p> if the item in question does not fit under B<conbody> but does fit under B<p>.
36504  
36505 193 L<ditaXrefs|/ditaXrefs> - Make obvious changes to all the B<xref>s found in a L<parse|/parse> tree to make them more useful in L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html>.
36506  
36507 194 L<divideDocumentIntoSections|/divideDocumentIntoSections> - Divide a L<parse|/parse> tree into sections by moving non B<section> tags into their corresponding B<section> so that the B<section> tags expand until they are contiguous.
36508  
36509 195 L<divideHtmlDocumentIntoSections|/divideHtmlDocumentIntoSections> - Divide a L<parse|/parse> tree representing an html document into sections based on the heading tags.
36510  
36511 196 L<down|/down> - Pre-order traversal down through a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node.
36512  
36513 197 L<downList|/downList> - Return a list of all the nodes at and below a specified B<$node> in pre-order or the empty list if the B<$node> is not in the optional B<@context>.
36514  
36515 198 L<downReverse|/downReverse> - Reverse pre-order traversal down through a L<parse|/parse> tree or sub tree calling the specified B<sub> at each node and returning the specified starting node.
36516  
36517 199 L<downReverseList|/downReverseList> - Return a list of all the nodes at and below a specified B<$node> in reverse pre-order or the empty list if the B<$node> is not in the optional B<@context>.
36518  
36519 200 L<downReverseX|/downReverseX> - Reverse pre-order traversal down through a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval|http://perldoc.perl.org/functions/eval.html>B<{}> at each node and returning the specified starting node.
36520  
36521 201 L<downToDie|/downToDie> - Pre-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die|http://perldoc.perl.org/functions/die.html>.
36522  
36523 202 L<downToDie2|/downToDie2> - Pre-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die|http://perldoc.perl.org/functions/die.html>.
36524  
36525 203 L<downWhileFirst|/downWhileFirst> - Move down from the specified B<$node> as long as each lower node is a first node.
36526  
36527 204 L<downWhileHasSingleChild|/downWhileHasSingleChild> - Move down from the specified B<$node> as long as it has a single child else return undef.
36528  
36529 205 L<downWhileLast|/downWhileLast> - Move down from the specified B<$node> as long as each lower node is a last node.
36530  
36531 206 L<downX|/downX> - Pre-order traversal of a L<parse|/parse> tree calling the specified B<sub> at each node as long as this sub does not L<die|http://perldoc.perl.org/functions/die.html>.
36532  
36533 207 L<downX2|/downX2> - Pre-order traversal of a L<parse|/parse> tree or sub tree calling the specified B<sub> within L<eval|http://perldoc.perl.org/functions/eval.html>B<{}> at each node and returning the specified starting node.
36534  
36535 208 L<dupPutNext|/dupPutNext> - Duplicate the specified B<$tree> in the optional B<@context>, place the new tree next after $tree and return the root of the new tree on success else B<undef>.
36536  
36537 209 L<dupPutNextN|/dupPutNextN> - Duplicate the specified B<$tree> B<$N> times in the optional B<@context>, placing each copy after $tree and return the last new node created on success else B<undef>.
36538  
36539 210 L<dupPutPrev|/dupPutPrev> - Duplicate the specified B<$tree> in the optional B<@context>, place the new tree before $tree and return the root of the new tree on success else B<undef>.
36540  
36541 211 L<dupTag|/dupTag> - Create a new non text node by duplicating the tag of an existing node.
36542  
36543 212 L<editText|/editText> - Return the text of a text B<$node> as an lvalue string reference that can be modified by a regular expression, else as a reference to a dummy string that will be ignored.
36544  
36545 213 L<equals|/equals> - Return the first node if the two L<parse|/parse> trees have identical representations via L<string|/string>, else B<undef>.
36546  
36547 214 L<equalsIgnoringAttributes|/equalsIgnoringAttributes> - Return the first node if the two L<parse|/parse> trees have identical representations via L<string|/string> if the specified attributes are ignored, else B<undef>.
36548  
36549 215 L<expandIncludes|/expandIncludes> - Expand the includes mentioned in a L<parse|/parse> tree: any tag that ends in B<include> is assumed to be an include directive.
36550  
36551 216 L<extendSectionToNextSection|/extendSectionToNextSection> - Extend a section tag until it meets the next section tag
36552  
36553 217 L<extractDocumentationFlags|/extractDocumentationFlags> - Generate documentation for a method with a user flag.
36554  
36555 218 L<findByForestNumber|/findByForestNumber> - Find the node with the specified L<forest number|/forestNumberTrees> as made visible on the id attribute by L<prettyStringNumbered|/prettyStringNumbered> in the L<parse|/parse> tree containing the specified B<$node> and return the found node or B<undef> if no such node exists.
36556  
36557 219 L<findById|/findById> - Find a node in the parse tree under the specified B<$node> with the specified B<$id>.
36558  
36559 220 L<findByNumber|/findByNumber> - Find the node with the specified number as made visible by L<prettyStringNumbered|/prettyStringNumbered> in the L<parse|/parse> tree containing the specified B<$node> and return the found node or B<undef> if no such node exists.
36560  
36561 221 L<findByNumbers|/findByNumbers> - Find the nodes with the specified numbers as made visible by L<prettyStringNumbered|/prettyStringNumbered> in the L<parse|/parse> tree containing the specified B<$node> and return the found nodes in a list with B<undef> for nodes that do not exist.
36562  
36563 222 L<findMatchingSubTrees|/findMatchingSubTrees> - Find nodes in the parse tree whose sub tree matches the specified B<$subTree> excluding any of the specified B<$attributes>.
36564  
36565 223 L<first|/first> - Return the first node below the specified B<$node> optionally checking the first node's context.
36566  
36567 224 L<firstBy|/firstBy> - Return a list of the first instance of each specified tag encountered in a post-order traversal from the specified B<$node> or a hash of all first instances if no tags are specified.
36568  
36569 225 L<firstContextOf|/firstContextOf> - Return the first node encountered in the specified context in a depth first post-order traversal of the L<parse|/parse> tree.
36570  
36571 226 L<firstDown|/firstDown> - Return a list of the first instance of each specified tag encountered in a pre-order traversal from the specified B<$node> or a hash of all first instances if no tags are specified.
36572  
36573 227 L<firstIn|/firstIn> - Return the first child node matching one of the named tags under the specified parent node.
36574  
36575 228 L<firstInIndex|/firstInIndex> - Return the specified B<$node> if it is first in its index and optionally L<at|/at> the specified context else B<undef>
36576  
36577 229 L<firstIs|/firstIs> - Return the specified B<$node> if it has one or more child nodes and the first child node has the specified B<@context> otherwise B<undef>.
36578  
36579 230 L<firstn|/firstn> - Return the B<$n>'th first node below the specified B<$node> optionally checking its context or B<undef> if there is no such node.
36580  
36581 231 L<firstNot|/firstNot> - Return the first child node that does not match any of the named B<@tags> under the specified parent B<$node>.
36582  
36583 232 L<firstOf|/firstOf> - Return an array of the nodes that are continuously first under their specified parent node and that match the specified list of tags.
36584  
36585 233 L<firstSibling|/firstSibling> - Return the first sibling of the specified B<$node> in the optional B<@context> else B<undef>
36586  
36587 234 L<firstText|/firstText> - Return the first node under the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
36588  
36589 235 L<firstTextMatches|/firstTextMatches> - Return the first node under the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context.
36590  
36591 236 L<firstUntil|/firstUntil> - Go first from the specified B<$node> and continue deeper firstly until a first child node matches the specified B<@context> or return B<undef> if there is no such node.
36592  
36593 237 L<firstUntilText|/firstUntilText> - Go first from the specified B<$node> and continue deeper firstly until a text node is encountered whose parent matches the specified B<@context> or return B<undef> if there is no such node.
36594  
36595 238 L<firstWhile|/firstWhile> - Go first from the specified B<$node> and continue deeper firstly as long as each first child node matches one of the specified B<@tags>.
36596  
36597 239 L<fixEntryColSpan|/fixEntryColSpan> - Fix the colspan on an entry assumed to be under row, tbody, tgroup with @cols and colspecs' set
36598  
36599 240 L<fixEntryRowSpan|/fixEntryRowSpan> - Fix the rowspan on an entry
36600  
36601 241 L<fixTable|/fixTable> - Fix the specified B<$table> so that each row has the same number of entries with this number reflected in the tgroup.
36602  
36603 242 L<fixTGroup|/fixTGroup> - Fix the specified B<$tgroup> so that each row has the same number of entries with this number reflected in the tgroup.
36604  
36605 243 L<forestNumberTrees|/forestNumberTrees> - Number the ids of the nodes in a L<parse|/parse> tree in pre-order so they are numbered in the same sequence that they appear in the source.
36606  
36607 244 L<formatOxygenMessage|/formatOxygenMessage> - Write an error message in Oxygen format
36608  
36609 245 L<from|/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.
36610  
36611 246 L<fromTo|/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.
36612  
36613 247 L<getAttrs|/getAttrs> - Return a sorted list of all the attributes on the specified B<$node>.
36614  
36615 248 L<getLabels|/getLabels> - Return the names of all the labels set on a node.
36616  
36617 249 L<getNodeAs|/getNodeAs> - Return the specified B<$node> unless it is possible to return the node saved with L<putNodeAs> under the specified B<name> and we are optionally in the specified B<@context>.
36618  
36619 250 L<getSectionHeadingLevel|/getSectionHeadingLevel> - Get the heading level from a section tag.
36620  
36621 251 L<giveEveryIdAGuid|/giveEveryIdAGuid> - Give a guid to every node in the specified B<$tree> that has an id attribute, saving any existing id attribute as a label, and return the count of the number of such replacements made.
36622  
36623 252 L<go|/go> - Return the node reached from the specified B<$node> via the specified L<path|/path>: (index positionB<?>)B<*> 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.
36624  
36625 253 L<goFish|/goFish> - A debug version of L<go|/go> that returns additional information explaining any failure to reach the node identified by the L<path|/path>.
36626  
36627 254 L<hasContent|/hasContent> - Confirm that the specified B<$node> has content.
36628  
36629 255 L<hasSingleChild|/hasSingleChild> - Return the only child of the specified B<$node> if the child is the only node under its parent ignoring any surrounding blank text and has the optional specified context, else return B<undef>.
36630  
36631 256 L<hasSingleChildText|/hasSingleChildText> - Return the only child of the specified B<$node> if the child is a text node and the child is the only node under its parent ignoring any surrounding blank text and the child has the optional specified context, else return B<undef>.
36632  
36633 257 L<hasSingleChildToDepth|/hasSingleChildToDepth> - Return the descendant of the specified B<$node> if it has single children to the specified depth in the specified optional B<@context> else return B<undef>.
36634  
36635 258 L<height|/height> - Returns the height of the tree rooted at the specified B<$node>.
36636  
36637 259 L<help|/help> - Get help for a node and the editor
36638  
36639 260 L<howFar|/howFar> - Return how far the first node is from the second node along a path through their common ancestor.
36640  
36641 261 L<howFarAbove|/howFarAbove> - Return how far the first node is L<above|/above> the second node is or B<0> if the first node is not strictly L<above|/above> the second node.
36642  
36643 262 L<howFarBelow|/howFarBelow> - Return how far the first node is L<below|/below> the second node is or B<0> if the first node is not strictly L<below|/below> the second node.
36644  
36645 263 L<howFirst|/howFirst> - Return the depth to which the specified B<$node> is L<first|/isFirst> else B<0>.
36646  
36647 264 L<howLast|/howLast> - Return the depth to which the specified B<$node> is L<last|/isLast> else B<0>.
36648  
36649 265 L<howOnlyChild|/howOnlyChild> - Return the depth to which the specified B<$node> is an L<only child|/isOnlyChild> else B<0>.
36650  
36651 266 L<htmlHeadersToSections|/htmlHeadersToSections> - Position sections just before html header tags so that subsequently the document can be divided into L<sections|/divideDocumentIntoSections>.
36652  
36653 267 L<htmlTables|/htmlTables> - Return a string of html representing a L<parse|/parse> tree.
36654  
36655 268 L<htmlTableToDita|/htmlTableToDita> - Convert an L<html table> to a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> table.
36656  
36657 269 L<index|/index> - Return the index of the specified B<$node> in its parent index.
36658  
36659 270 L<indexIds|/indexIds> - Return a map of the ids at and below the specified B<$node>.
36660  
36661 271 L<indexNode|/indexNode> - Merge multiple text segments and set parent and parser after changes to a node
36662  
36663 272 L<invert|/invert> - Swap a parent and child node where the child is the only child of the parent and return the parent.
36664  
36665 273 L<invertFirst|/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.
36666  
36667 274 L<invertLast|/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.
36668  
36669 275 L<isADitaMap|/isADitaMap> - Return the specified B<$node> if this node is a L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> map else return B<undef>
36670  
36671 276 L<isAllBlankText|/isAllBlankText> - Return the specified B<$node> if the specified B<$node>, optionally in the specified context, does not contain anything or if it does contain something it is all white space else return B<undef>.
36672  
36673 277 L<isBlankText|/isBlankText> - Return the specified B<$node> if the specified B<$node> is a text node, optionally in the specified context, and contains nothing other than white space else return B<undef>.
36674  
36675 278 L<isEmpty|/isEmpty> - Confirm that the specified B<$node> is empty, that is: the specified B<$node> has no content, not even a blank string of text.
36676  
36677 279 L<isFirst|/isFirst> - Return the specified B<$node> if it is first under its parent and optionally has the specified context, else return B<undef>
36678  
36679 280 L<isFirstN|/isFirstN> - Return the first B<$N> nodes as an array if the first B<$N> tags of the parent of B<$node> finish at the specified B<$node> and have the specified tags in the sequence specified by B<@context>.
36680  
36681 281 L<isFirstText|/isFirstText> - Return the specified B<$node> if the specified B<$node> is a text node, the first node under its parent and that the parent is optionally in the specified context, else return B<undef>.
36682  
36683 282 L<isFirstToDepth|/isFirstToDepth> - Return the specified B<$node> if it is first to the specified depth else return B<undef>
36684  
36685 283 L<isLast|/isLast> - Return the specified B<$node> if it is last under its parent and optionally has the specified context, else return B<undef>
36686  
36687 284 L<isLastN|/isLastN> - Return the last B<$N> nodes as an array if the last B<$N> tags of the parent of B<$node> start at the specified B<$node> and have the specified tags in the sequence specified by B<@context>.
36688  
36689 285 L<isLastText|/isLastText> - Return the specified B<$node> if the specified B<$node> is a text node, the last node under its parent and that the parent is optionally in the specified context, else return B<undef>.
36690  
36691 286 L<isLastToDepth|/isLastToDepth> - Return the specified B<$node> if it is last to the specified depth else return B<undef>
36692  
36693 287 L<isNotFirst|/isNotFirst> - Return the specified B<$node> if it is not first under its parent and optionally has the specified context, else return B<undef>
36694  
36695 288 L<isNotLast|/isNotLast> - Return the specified B<$node> if it is not last under its parent and optionally has the specified context, else return B<undef>
36696  
36697 289 L<isOnlyChild|/isOnlyChild> - Return the specified B<$node> if it is the only node under its parent ignoring any surrounding blank text.
36698  
36699 290 L<isOnlyChildBlankText|/isOnlyChildBlankText> - Return the specified B<$node> if it is a blank text node and an only child else return B<undef>.
36700  
36701 291 L<isOnlyChildN|/isOnlyChildN> - Return the specified B<$node> if it is an only child of B<$depth> ancestors with L<only children|/hasSingleChild> in the opptional B<@context> else return B<undef>.
36702  
36703 292 L<isOnlyChildText|/isOnlyChildText> - Return the specified B<$node> if it is a text node and it is an only child else and its parent is in the specified optional context else return B<undef>.
36704  
36705 293 L<isOnlyChildToDepth|/isOnlyChildToDepth> - Return the specified B<$node> if it and its ancestors are L<only children|/isOnlyChild> to the specified depth else return B<undef>.
36706  
36707 294 L<isText|/isText> - Return the specified B<$node> if the specified B<$node> is a text node, optionally in the specified context, else return B<undef>.
36708  
36709 295 L<joinWithText|/joinWithText> - Insert some text between the children of the current B<$node> as specified by B<$text> between all the children of the current $node as long as they all have a tag of B<$over>.
36710  
36711 296 L<jsonString|/jsonString> - Return a Json representation of a parse tree
36712  
36713 297 L<jsonString2|/jsonString2> - Return a Json representation of a parse tree
36714  
36715 298 L<jsonToXml|/jsonToXml> - Convert a json string representing an L<Xml|https://en.wikipedia.org/wiki/XML> parse tree into an L<Xml|https://en.wikipedia.org/wiki/XML> parse tree
36716  
36717 299 L<jsonToXml2|/jsonToXml2> - Convert a json string to an L<Xml|https://en.wikipedia.org/wiki/XML> parse tree
36718  
36719 300 L<labelsInTree|/labelsInTree> - Return a hash of all the labels in a tree
36720  
36721 301 L<last|/last> - Return the last node below the specified B<$node> optionally checking the last node's context.
36722  
36723 302 L<lastBy|/lastBy> - Return a list of the last instance of each specified tag encountered in a post-order traversal from the specified B<$node> or a hash of all last instances if no tags are specified.
36724  
36725 303 L<lastContextOf|/lastContextOf> - Return the last node encountered in the specified context in a depth first reverse pre-order traversal of the L<parse|/parse> tree.
36726  
36727 304 L<lastDown|/lastDown> - Return a list of the last instance of each specified tag encountered in a pre-order traversal from the specified B<$node> or a hash of all last instances if no tags are specified.
36728  
36729 305 L<lastIn|/lastIn> - Return the last child node matching one of the named tags under the specified parent node.
36730  
36731 306 L<lastInIndex|/lastInIndex> - Return the specified B<$node> if it is last in its index and optionally L<at|/at> the specified context else B<undef>
36732  
36733 307 L<lastIs|/lastIs> - Return the specified B<$node> if it has one or more child nodes and the last child node has the specified B<@context> otherwise B<undef>.
36734  
36735 308 L<lastn|/lastn> - Return the B<$n>'th last node below the specified B<$node> optionally checking its context or B<undef> if there is no such node.
36736  
36737 309 L<lastNot|/lastNot> - Return the last child node that does not match any of the named B<@tags> under the specified parent B<$node>.
36738  
36739 310 L<lastOf|/lastOf> - Return an array of the nodes that are continuously last under their specified parent node and that match the specified list of tags.
36740  
36741 311 L<lastSibling|/lastSibling> - Return the last sibling of the specified B<$node> in the optional B<@context> else B<undef>
36742  
36743 312 L<lastText|/lastText> - Return the last node under the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
36744  
36745 313 L<lastTextMatches|/lastTextMatches> - Return the last node under the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context.
36746  
36747 314 L<lastUntil|/lastUntil> - Go last from the specified B<$node> and continue deeper lastly until a last child node matches the specified B<@context> or return B<undef> if there is no such node.
36748  
36749 315 L<lastUntilText|/lastUntilText> - Go last from the specified B<$node> and continue deeper lastly until a last child text node matches the specified B<@context> or return B<undef> if there is no such node.
36750  
36751 316 L<lastWhile|/lastWhile> - Go last from the specified B<$node> and continue deeper lastly as long as each last child node matches one of the specified B<@tags>.
36752  
36753 317 L<lineLocation|/lineLocation> - Return the line number.
36754  
36755 318 L<listConditions|/listConditions> - Return a list of conditions applied to a B<$node>.
36756  
36757 319 L<location|/location> - Return the line number.
36758  
36759 320 L<matchAfter|/matchAfter> - Confirm that the string representing the tags following the specified B<$node> matches a regular expression where each pair of tags is separated by a single space.
36760  
36761 321 L<matchAfter2|/matchAfter2> - Confirm that the string representing the tags following the specified B<$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.
36762  
36763 322 L<matchBefore|/matchBefore> - Confirm that the string representing the tags preceding the specified B<$node> matches a regular expression where each pair of tags is separated by a single space.
36764  
36765 323 L<matchBefore2|/matchBefore2> - Confirm that the string representing the tags preceding the specified B<$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.
36766  
36767 324 L<matchesFirst|/matchesFirst> - Return the specified B<$node> if its children L<match|/atPositionMatch> the specified <@sequence> forwards from the first child else return B<undef>.
36768  
36769 325 L<matchesLast|/matchesLast> - Return the specified B<$node> if its children L<match|/atPositionMatch> the specified <@sequence> backwards from the last child else return B<undef>.
36770  
36771 326 L<matchesNext|/matchesNext> - Return the specified B<$node> if its following siblings L<match|/atPositionMatch> the specified <@sequence> else return B<undef>.
36772  
36773 327 L<matchesNode|/matchesNode> - Return the B<$first> node if it matches the B<$second> node's tag and the specified B<@attributes> else return B<undef>.
36774  
36775 328 L<matchesPrev|/matchesPrev> - Return the specified B<$node> if the siblings before $node L<match|/atPositionMatch> the specified <@sequence> with the first element of @sequence nearest to $node and the last element furthest else return B<undef>.
36776  
36777 329 L<matchesSubTree|/matchesSubTree> - Return the B<$first> node if it L<matches|/matchesNode> the B<$second> node and the nodes under the first node match the corresponding nodes under the second node, else return B<undef>.
36778  
36779 330 L<matchesText|/matchesText> - Returns an array of regular expression matches in the text of the specified B<$node> if it is text node and it matches the specified regular expression and optionally has the specified context otherwise returns an empty array.
36780  
36781 331 L<matchNodesByRepresentation|/matchNodesByRepresentation> - Creates a hash of arrays of nodes that have the same representation in the specified B<$tree>.
36782  
36783 332 L<matchTree|/matchTree> - Return a list of nodes that match the specified tree of match expressions, else B<()> if one or more match expressions fail to match nodes in the tree below the specified start node.
36784  
36785 333 L<mergeDuplicateChildWithParent|/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.
36786  
36787 334 L<mergeLikeElements|/mergeLikeElements> - Merge two of the same elements into one, retaining the order of any children.
36788  
36789 335 L<mergeLikeNext|/mergeLikeNext> - Merge a B<$node> in an optional context with the next node if the two have the same tag by placing the next node first in the current B<$node> and unwrapping the next node.
36790  
36791 336 L<mergeLikePrev|/mergeLikePrev> - Merge a B<$node> in an optional context with the previous node if the two have the same tag by placing the previous node first in the current B<$node> and unwrapping the previous node.
36792  
36793 337 L<mergeOnlyChildLikeNext|/mergeOnlyChildLikeNext> - Merge a B<$node> if it is the only child of its parent with a preceding node of the same name that is also the only child of its parent and return the specified B<$node> or B<undef> if the request fails.
36794  
36795 338 L<mergeOnlyChildLikePrev|/mergeOnlyChildLikePrev> - Merge a B<$node> if it is the only child of its parent with a preceding node of the same name that is also the only child of its parent and return the specified B<$node> or B<undef> if the request fails.
36796  
36797 339 L<mergeOnlyChildLikePrevLast|/mergeOnlyChildLikePrevLast> - Merge a B<$node> if it is the only child of its parent with a preceding node with the same tag that is the last child of its parent and return the previous B<$node> or B<undef> if the request fails.
36798  
36799 340 L<moveAttrs|/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.
36800  
36801 341 L<moveBlockAfter|/moveBlockAfter> - Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> after the specified B<$after> node.
36802  
36803 342 L<moveBlockBefore|/moveBlockBefore> - Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> before the specified B<$after> node.
36804  
36805 343 L<moveBlockFirst|/moveBlockFirst> - Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> first under the specified B<$parent> node.
36806  
36807 344 L<moveBlockFromFirstAfter|/moveBlockFromFirstAfter> - Move the block of siblings starting with B<$start> in the optional context after the specified B<$after> node.
36808  
36809 345 L<moveBlockFromFirstBefore|/moveBlockFromFirstBefore> - Move the block of siblings starting with B<$start> in the optional context before the specified B<$after> node.
36810  
36811 346 L<moveBlockFromFirstFirst|/moveBlockFromFirstFirst> - Move the siblings starting with B<$start> in the optional context first under the specified B<$parent> node.
36812  
36813 347 L<moveBlockFromFirstLast|/moveBlockFromFirstLast> - Move the block of siblings starting with B<$start> in the optional context last under the specified B<$parent> node.
36814  
36815 348 L<moveBlockLast|/moveBlockLast> - Move the block of siblings starting with B<$start> in the optional context and ending with B<$end> last under the specified B<$parent> node.
36816  
36817 349 L<moveBlockToLastAfter|/moveBlockToLastAfter> - Move the block of siblings starting with B<$start> in the optional context after the specified B<$after> node.
36818  
36819 350 L<moveBlockToLastBefore|/moveBlockToLastBefore> - Move the block of siblings starting with B<$start> in the optional context before the specified B<$after> node.
36820  
36821 351 L<moveBlockToLastFirst|/moveBlockToLastFirst> - Move the siblings starting with B<$start> in the optional context first under the specified B<$parent> node.
36822  
36823 352 L<moveBlockToLastLast|/moveBlockToLastLast> - Move the block of siblings starting with B<$start> in the optional context last under the specified B<$parent> node.
36824  
36825 353 L<moveEndAfter|/moveEndAfter> - Move the end of a B<$node> to just after the specified B<$target> node assuming that the B<$target> node is either a subsequent sibling or a child of B<$node>.
36826  
36827 354 L<moveEndBefore|/moveEndBefore> - Move the end of a B<$node> to just before the specified B<$target> node assuming that the B<$target> node is either a subsequent sibling or a child of B<$node>.
36828  
36829 355 L<moveEndLast|/moveEndLast> - Move the end of a B<$node> to contain all of its following siblings as children.
36830  
36831 356 L<moveFirst|/moveFirst> - Move the specified node so that is is the first sibling under its parent.
36832  
36833 357 L<moveLabels|/moveLabels> - Move all the labels from the source node to the target node and return the source node.
36834  
36835 358 L<moveLast|/moveLast> - Move the specified node so that is is the last sibling under its parent.
36836  
36837 359 L<moveNewAttrs|/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.
36838  
36839 360 L<moveSelectionAfter|/moveSelectionAfter> - Move the current selection (if there is one) after the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
36840  
36841 361 L<moveSelectionBefore|/moveSelectionBefore> - Move the current selection (if there is one) before the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
36842  
36843 362 L<moveSelectionFirst|/moveSelectionFirst> - Move the current selection (if there is one) so that it is first under the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
36844  
36845 363 L<moveSelectionLast|/moveSelectionLast> - Move the current selection (if there is one) so that it is last under the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
36846  
36847 364 L<moveStartAfter|/moveStartAfter> - Move the start end of a B<$node> to just after the specified B<$target> node assuming that the B<$target> node is either a preceding sibling or a child of B<$node>.
36848  
36849 365 L<moveStartBefore|/moveStartBefore> - Move the start of a B<$node> to just before the specified B<$target> node assuming that the B<$target> node is either a preceding sibling or a child of B<$node>.
36850  
36851 366 L<moveStartFirst|/moveStartFirst> - Move the start of a B<$node> to contain all of its preceding siblings as children.
36852  
36853 367 L<new|/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 B<or> with no parameters and then use L</input>, L</inputFile>, L</inputString>, L</errorFile> to provide specific parameters for the parse, then call L</parse> to perform the parse and return the parse tree.
36854  
36855 368 L<newTag|/newTag> - Create a new non text node.
36856  
36857 369 L<newText|/newText> - Create a new text node.
36858  
36859 370 L<newTree|/newTree> - Create a new tree.
36860  
36861 371 L<next|/next> - Return the node next to the specified B<$node>, optionally checking the next node's context.
36862  
36863 372 L<nextIn|/nextIn> - Return the nearest sibling after the specified B<$node> that matches one of the named tags or B<undef> if there is no such sibling node.
36864  
36865 373 L<nextIs|/nextIs> - Return the specified B<$node> if there is a following node with the specified B<@context>.
36866  
36867 374 L<nextN|/nextN> - Return B<$N> nodes as an array starting at B<$node> inclusive if they match the first B<$N> tags of B<@context>.
36868  
36869 375 L<nextn|/nextn> - Return the B<$n>'th next node after the specified B<$node> optionally checking its context or B<undef> if there is no such node.
36870  
36871 376 L<nextOn|/nextOn> - Step forwards as far as possible from the specified B<$node> while remaining on nodes with the specified tags.
36872  
36873 377 L<nextText|/nextText> - Return the node after the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
36874  
36875 378 L<nextTextMatches|/nextTextMatches> - Return the next node to the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context.
36876  
36877 379 L<nextUntil|/nextUntil> - Go to the next sibling of the specified B<$node> and continue forwards until the tag of a sibling node matches one of the specified B<@tags>.
36878  
36879 380 L<nextWhile|/nextWhile> - Go to the next sibling of the specified B<$node> and continue forwards while the tag of each sibling node matches one of the specified B<@tags>.
36880  
36881 381 L<nn|/nn> - Replace new lines in a string with N to make testing easier.
36882  
36883 382 L<normalizeWhiteSpace|/normalizeWhiteSpace> - Normalize white space, remove comments DOCTYPE and L<Xml|https://en.wikipedia.org/wiki/XML> processors from a string
36884  
36885 383 L<not|/not> - Return the specified B<$node> if it does not match any of the specified tags, else B<undef>
36886  
36887 384 L<numberNode|/numberNode> - Ensure that the specified B<$node> has a number.
36888  
36889 385 L<numberTree|/numberTree> - Number the nodes in a L<parse|/parse> tree in pre-order so they are numbered in the same sequence that they appear in the source.
36890  
36891 386 L<numberTreesJustIds|/numberTreesJustIds> - Number the ids of the nodes in a L<parse|/parse> tree in pre-order so they are numbered in the same sequence that they appear in the source.
36892  
36893 387 L<opAt|/opAt> - <= : Check that a node is in the context specified by the referenced array of words.
36894  
36895 388 L<opAttr|/opAttr> - % : Get the value of an attribute of the specified B<$node>.
36896  
36897 389 L<opBy|/opBy> - x= : Traverse a L<parse|/parse> tree in post-order.
36898  
36899 390 L<opContents|/opContents> - @{} : nodes immediately below a node.
36900  
36901 391 L<opCut|/opCut> - -- : Cut out a node.
36902  
36903 392 L<opGo|/opGo> - >= : Search for a node via a specification provided as a reference to an array of words each number.
36904  
36905 393 L<opNew|/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
36906  
36907 394 L<opPutFirst|/opPutFirst> - >> : put a node or string first under a node and return the new node.
36908  
36909 395 L<opPutFirstAssign|/opPutFirstAssign> - >>= : put a node or string first under a node.
36910  
36911 396 L<opPutLast|/opPutLast> - << : put a node or string last under a node and return the new node.
36912  
36913 397 L<opPutLastAssign|/opPutLastAssign> - <<= : put a node or string last under a node.
36914  
36915 398 L<opPutNext|/opPutNext> - > + : put a node or string after the specified B<$node> and return the new node.
36916  
36917 399 L<opPutNextAssign|/opPutNextAssign> - += : put a node or string after the specified B<$node>.
36918  
36919 400 L<opPutPrev|/opPutPrev> - < - : put a node or string before the specified B<$node> and return the new node.
36920  
36921 401 L<opPutPrevAssign|/opPutPrevAssign> - -= : put a node or string before the specified B<$node>,
36922  
36923 402 L<opString|/opString> - -A: L<printNode|/printNode>
36924  
36925 -B: L<bitsNodeTextBlank|/bitsNodeTextBlank>
36926  
36927 -b: L<isAllBlankText|/isAllBlankText>
36928  
36929 -C: L<stringContent|/stringContent>
36930  
36931 -c: L<context|/context>
36932  
36933 -d: L<depth|/depth>
36934  
36935 -e: L<prettyStringEnd|/prettyStringEnd>
36936  
36937 -f: L<first node|/first>
36938  
36939 -g: L<createGuidId|/createGuidId>
36940  
36941 -k: L<createGuidId|/createGuidId>
36942  
36943 -l: L<last node|/last>
36944  
36945 -M: L<stringAsMd5Sum|/stringAsMd5Sum>
36946  
36947 -O: L<contentAsTags2|/contentAsTags2>
36948  
36949 -o: L<contentAsTags|/contentAsTags>
36950  
36951 -p: L<prettyString|/prettyString>
36952  
36953 -R: L<requiredCleanup|/requiredCleanup>
36954  
36955 -r: L<stringTagsAndText|/stringTagsAndText>
36956  
36957 -S: L<printStack|/printStack>
36958  
36959 -s: L<string|/string>
36960  
36961 -T: L<isText|/isText>
36962  
36963 -t: L<tag|/tag>
36964  
36965 -u: L<unwrap|/unwrap>
36966  
36967 -W: L<id|/id>
36968  
36969 -w: L<stringQuoted|/stringQuoted>
36970  
36971 -X: L<prettyStringDitaHeaders|/prettyStringDitaHeaders>
36972  
36973 -x: L<cut|/cut>
36974  
36975 -z: L<prettyStringNumbered|/prettyStringNumbered>.
36976  
36977 403 L<opUnwrap|/opUnwrap> - ++ : Unwrap a node.
36978  
36979 404 L<opWrapContentWith|/opWrapContentWith> - * : Wrap content with a tag, returning the wrapping node.
36980  
36981 405 L<opWrapWith|/opWrapWith> - / : Wrap node with a tag, returning the wrapping node.
36982  
36983 406 L<ordered|/ordered> - Return the first node if the specified nodes are all in order when performing a pre-ordered traversal of the L<parse|/parse> tree else return B<undef>.
36984  
36985 407 L<over|/over> - Confirm that the string representing the tags at the level below the specified B<$node> match a regular expression where each pair of tags is separated by a single space.
36986  
36987 408 L<over2|/over2> - Confirm that the string representing the tags at the level below the specified B<$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.
36988  
36989 409 L<overAllTags|/overAllTags> - Return the specified b<$node> if all of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
36990  
36991 410 L<overFirstTags|/overFirstTags> - Return the specified b<$node> if the first of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
36992  
36993 411 L<overLastTags|/overLastTags> - Return the specified b<$node> if the last of it's child nodes L<match|/atPositionMatch> the specified <@tags> else return B<undef>.
36994  
36995 412 L<parentage|/parentage> - Return a reference to an array of the nodes along the path from the root to the specified B<$Node> inclusive.
36996  
36997 413 L<parentOf|/parentOf> - Returns the specified B<$parent> node if it is the parent of the specified B<$child> node and the B<$parent> node is in the specified optional context.
36998  
36999 414 L<parse|/parse> - Parse input L<Xml|https://en.wikipedia.org/wiki/XML> specified via: L<inputFile|/inputFile>, L<input|/input> or L<inputString|/inputString>.
37000  
37001 415 L<parseLineLocation|/parseLineLocation> - Parse a line location
37002  
37003 416 L<path|/path> - Return a list of strings representing the path to a node from the root of the parse tree which can then be reused by L<go|/go> to retrieve the node as long as the structure of the L<parse|/parse> tree has not changed along the path.
37004  
37005 417 L<pathString|/pathString> - Return a string representing the L<path|/path> to the specified B<$node> from the root of the parse tree.
37006  
37007 418 L<position|/position> - Return the index of the specified B<$node> in the content of the parent of the B<$node>.
37008  
37009 419 L<precedingSiblingOf|/precedingSiblingOf> - Returns the specified B<$child> node if it has the same parent as B<$sibling> and occurs before B<$sibling> and has the optionally specified context else returns B<undef>.
37010  
37011 420 L<present|/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.
37012  
37013 421 L<prettyString|/prettyString> - Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it.
37014  
37015 422 L<prettyStringCDATA|/prettyStringCDATA> - Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it with the text fields wrapped with <CDATA>.
37016  
37017 423 L<prettyStringContent|/prettyStringContent> - Return a readable string representing all the nodes below a node of a L<parse|/parse> tree.
37018  
37019 424 L<prettyStringContentNumbered|/prettyStringContentNumbered> - Return a readable string representing all the nodes below a node of a L<parse|/parse> tree with numbering added.
37020  
37021 425 L<prettyStringDitaHeaders|/prettyStringDitaHeaders> - Return a readable string representing the L<parse|/parse> tree below the specified B<$node> with appropriate headers.
37022  
37023 426 L<prettyStringEnd|/prettyStringEnd> - Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it as a here document
37024  
37025 427 L<prettyStringHtml|/prettyStringHtml> - Return a string of L<HTML|https://en.wikipedia.org/wiki/HTML> representing a node of a L<parse|/parse> tree and all the nodes below it if the node is in the specified context.
37026  
37027 428 L<prettyStringHtml2|/prettyStringHtml2> - Return a string of html representing a node of a L<parse|/parse> tree and all the nodes below it.
37028  
37029 429 L<prettyStringNumbered|/prettyStringNumbered> - Return a readable string representing a node of a L<parse|/parse> tree and all the nodes below it with a L<number|/number> attached to each tag.
37030  
37031 430 L<prev|/prev> - Return the node before the specified B<$node>, optionally checking the previous node's context.
37032  
37033 431 L<prevIn|/prevIn> - Return the nearest sibling node before the specified B<$node> which matches one of the named tags or B<undef> if there is no such sibling node.
37034  
37035 432 L<prevIs|/prevIs> - Return the specified B<$node> if there is a previous node with the specified B<@context>.
37036  
37037 433 L<prevN|/prevN> - Return B<$N> nodes as an array ending at B<$node> inclusive if they match the first B<$N> tags of B<@context>.
37038  
37039 434 L<prevn|/prevn> - Return the B<$n>'th previous node after the specified B<$node> optionally checking its context or B<undef> if there is no such node.
37040  
37041 435 L<prevOn|/prevOn> - Step backwards as far as possible while remaining on nodes with the specified tags.
37042  
37043 436 L<prevText|/prevText> - Return the node before the specified B<$node> if it is in the optional and it is a text node otherwise B<undef>.
37044  
37045 437 L<prevTextMatches|/prevTextMatches> - Return the previous node to the specified B<$node> if: it is a text mode; its text matches the specified regular expression; the specified B<$node> is in the optional specified context.
37046  
37047 438 L<prevUntil|/prevUntil> - Go to the previous sibling of the specified B<$node> and continue backwards until the tag of a sibling node matches one of the specified B<@tags>.
37048  
37049 439 L<prevWhile|/prevWhile> - Go to the previous sibling of the specified B<$node> and continue backwards while the tag of each sibling node matches one of the specified B<@tags>.
37050  
37051 440 L<printAttributes|/printAttributes> - Print the attributes of a node.
37052  
37053 441 L<printAttributesExtendingIdsWithLabels|/printAttributesExtendingIdsWithLabels> - Print the attributes of a node extending the id with the labels.
37054  
37055 442 L<printAttributesHtml|/printAttributesHtml> - Print the attributes of a node as html.
37056  
37057 443 L<printAttributesReplacingIdsWithLabels|/printAttributesReplacingIdsWithLabels> - Print the attributes of a node replacing the id with the labels.
37058  
37059 444 L<printNode|/printNode> - Print the tag and attributes of a node.
37060  
37061 445 L<printNodeAsSingleton|/printNodeAsSingleton> - Print the tag and attributes of a node as if it were a single node regardless of any child nodes it might have
37062  
37063 446 L<printStack|/printStack> - Print the attributes of a node and each of its parents
37064  
37065 447 L<processModuleDescription|/processModuleDescription> - Process module description to write a description of editing Xml to GitHub
37066  
37067 448 L<propagate|/propagate> - Propagate L<new attributes|/copyNewAttrs> from nodes that match the specified tag to all their child nodes, then L<unwrap|/unwrap> all the nodes that match the specified tag.
37068  
37069 449 L<putContentAfter|/putContentAfter> - Move the content of the specified B<$node> and place it after that node if that node is in the optional B<@context>.
37070  
37071 450 L<putContentBefore|/putContentBefore> - Move the content of the specified B<$node> and place it before that node if that node is in the optional B<@context>.
37072  
37073 451 L<putCutOutFirst|/putCutOutFirst> - Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it first under the specified B<$node> if $node is in the optional B<@context>.
37074  
37075 452 L<putCutOutLast|/putCutOutLast> - Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it last under the specified B<$node> if $node is in the optional B<@context>.
37076  
37077 453 L<putCutOutNext|/putCutOutNext> - Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it next after the specified B<$node> if $node is in the optional B<@context>.
37078  
37079 454 L<putCutOutPrev|/putCutOutPrev> - Pop the last node placed on the cut out stack by one of the cut(First|Last|Next|Prev) methods and place it before the specified B<$node> if $node is in the optional B<@context>.
37080  
37081 455 L<putFirst|/putFirst> - Place a L<cut out|/cut> or L<new|/new> node at the front of the content of the specified B<$node> and return the new node.
37082  
37083 456 L<putFirstAsComment|/putFirstAsComment> - Put a comment first under the specified B<$node> and return the specified B<$node>.
37084  
37085 457 L<putFirstAsText|/putFirstAsText> - Add a new text node first under a parent and return the new text node.
37086  
37087 458 L<putFirstAsTree|/putFirstAsTree> - Put parsed text first under the specified B<$node> parent and return a reference to the parsed tree.
37088  
37089 459 L<putFirstCut|/putFirstCut> - Cut out the B<$second> node, place it first under the B<$first> node and return the B<$second> node.
37090  
37091 460 L<putFirstRequiredCleanUp|/putFirstRequiredCleanUp> - Place a required cleanup first under a specified B<$node> using the specified B<@text> and return the required clean up node.
37092  
37093 461 L<putLast|/putLast> - Place a L<cut out|/cut> or L<new|/new> node last in the content of the specified B<$node> and return the new node.
37094  
37095 462 L<putLastAsComment|/putLastAsComment> - Put a comment last under the specified B<$node> and return the specified B<$node>.
37096  
37097 463 L<putLastAsText|/putLastAsText> - Add a new text node last under a parent and return the new text node.
37098  
37099 464 L<putLastAsTree|/putLastAsTree> - Put parsed text last under the specified B<$node> parent and return a reference to the parsed tree.
37100  
37101 465 L<putLastCut|/putLastCut> - Cut out the B<$second> node, place it last under the B<$first> node and return the B<$second> node.
37102  
37103 466 L<putLastRequiredCleanUp|/putLastRequiredCleanUp> - Place a required cleanup last under a specified B<$node> using the specified B<@text> and return the required clean up node.
37104  
37105 467 L<putNext|/putNext> - Place a L<cut out|/cut> or L<new|/new> node just after the specified B<$node> and return the new node.
37106  
37107 468 L<putNextAsComment|/putNextAsComment> - Put a comment after the specified B<$node> and return the specified B<$node>
37108  
37109 469 L<putNextAsText|/putNextAsText> - Add a new text node following the specified B<$node> and return the new text node.
37110  
37111 470 L<putNextAsTree|/putNextAsTree> - Put parsed text after the specified B<$node> parent and return a reference to the parsed tree.
37112  
37113 471 L<putNextCut|/putNextCut> - Cut out the B<$second> node, place it after the B<$first> node and return the B<$second> node.
37114  
37115 472 L<putNextFirstCut|/putNextFirstCut> - Move the specified B<$node> so it is first in the next node with the optional context.
37116  
37117 473 L<putNextFirstCut2|/putNextFirstCut2> - Move the specified B<$node> so it is first in the first node with the specified optional B<@context> of the next node.
37118  
37119 474 L<putNextRequiredCleanUp|/putNextRequiredCleanUp> - Place a required cleanup next after a specified B<$node> using the specified B<@text> and return the required clean up node.
37120  
37121 475 L<putNodeAs|/putNodeAs> - Return the specified B<$node> after saving it under the specified B<$name> if we are in the optional B<@context>.
37122  
37123 476 L<putPrev|/putPrev> - Place a L<cut out|/cut> or L<new|/new> node just before the specified B<$node> and return the new node.
37124  
37125 477 L<putPrevAsComment|/putPrevAsComment> - Put a comment before the specified B<$parent> parentand return the specified B<$node>
37126  
37127 478 L<putPrevAsText|/putPrevAsText> - Add a new text node following the specified B<$node> and return the new text node
37128  
37129 479 L<putPrevAsTree|/putPrevAsTree> - Put parsed text before the specified B<$parent> parent and return a reference to the parsed tree.
37130  
37131 480 L<putPrevCut|/putPrevCut> - Cut out the B<$second> node, place it before the B<$first> node and return the B<$second> node.
37132  
37133 481 L<putPrevLastCut|/putPrevLastCut> - Move the specified B<$node> so it is last in the preceding node with the optional context.
37134  
37135 482 L<putPrevLastCut2|/putPrevLastCut2> - Move the specified B<$node> so it is last in the last node with the specified optional context of the preceding node.
37136  
37137 483 L<putPrevRequiredCleanUp|/putPrevRequiredCleanUp> - Place a required cleanup before a specified B<$node> using the specified B<@text> and return the required clean up node.
37138  
37139 484 L<putSiblingsAfterParent|/putSiblingsAfterParent> - Move the specified B<$node> and its following siblings up one level and place them after the parent of the specified B<$node> if the specified B<$node> is in the optional B<@context>.
37140  
37141 485 L<putSiblingsBeforeParent|/putSiblingsBeforeParent> - Move the specified B<$node> and its preceding siblings up one level and place them before the parent of the specified B<$node> if the specified B<$node> is in the optional B<@context>.
37142  
37143 486 L<putSiblingsFirst|/putSiblingsFirst> - Move the siblings preceding the specified B<$node> in the optional B<@context> down one level and place them first under the specified B<$node> preceding any existing content.
37144  
37145 487 L<putSiblingsLast|/putSiblingsLast> - Move the siblings following the specified B<$node> in the optional B<@context> down one level so that they are last under the specified B<$node> following any existing content.
37146  
37147 488 L<putTextFirst|/putTextFirst> - Given a B<$node> place some B<@text> first under the $node and return the new text node else return B<undef> if this is not possible.
37148  
37149 489 L<putTextLast|/putTextLast> - Given a B<$node> place some B<@text> last under the $node and return the new text node else return B<undef> if this is not possible.
37150  
37151 490 L<putTextNext|/putTextNext> - Given a B<$node> place some B<@text> next to the $node and return the new text node else return B<undef> if this is not possible.
37152  
37153 491 L<putTextPrev|/putTextPrev> - Given a B<$node> place some B<@text> prior to the $node and return the new text node else return B<undef> if this is not possible.
37154  
37155 492 L<putUpNextCut|/putUpNextCut> - Move the specified B<$node>, in the optional B<@context>, which must be last under its parent, so that it is next after its parent.
37156  
37157 493 L<putUpNextCut2|/putUpNextCut2> - Move the specified B<$node>, in the optional B<@context>, if $node is last after its parent which must also be last under its parent, so that $node is next after its grandparent.
37158  
37159 494 L<putUpPrevCut|/putUpPrevCut> - Move the specified B<$node> in the optional B<@context>, if $node is first under its parent, so that it is prior to its parent.
37160  
37161 495 L<putUpPrevCut2|/putUpPrevCut2> - Move the specified B<$node>, in the optional B<@context>, if $node is first under its parent which must also be first under its parent, so that $node is prior to its grandparent.
37162  
37163 496 L<readCompressedFile|/readCompressedFile> - Read the specified B<$file> containing compressed L<Xml|https://en.wikipedia.org/wiki/XML> and return the root node.
37164  
37165 497 L<reduceParseErroMessage|/reduceParseErroMessage> - Reduce the parse failure message to the bare essentials.
37166  
37167 498 L<reindexNode|/reindexNode> - Index the children of a node so that we can access them by tag and number.
37168  
37169 499 L<renameAttr|/renameAttr> - Rename attribute B<$old> to B<$new> in the specified B<$node> with optional context B<@context> regardless of whether attribute B<$new> already exists or not and return the B<$node>.
37170  
37171 500 L<renameAttrValue|/renameAttrValue> - Rename attribute B<$old> to B<$new> with new value B<$newValue> in the specified B<$node> in the optional B<@context> regardless of whether attribute B<$new> already exists or not as long as the attribute B<$old> has the value B<$oldValue>.
37172  
37173 501 L<renameAttrXtr|/renameAttrXtr> - Rename the attributes B<@attr> as far as possible to xtrc or xtrf.
37174  
37175 502 L<renew|/renew> - Returns a renewed copy of the L<parse|/parse> tree by first printing it and then reparsing it, optionally checking that the starting node is in a specified context: use this method if you have added nodes via the L</"Put as text"> methods and wish to traverse their L<parse|/parse> tree.
37176  
37177 503 L<reorder|/reorder> - If the current B<$node> has a context of (B<$first>, @context) and the preceding node has a context of (B<$second>, B<@context>), then swap the current node with the previous node.
37178  
37179 504 L<replaceContentWith|/replaceContentWith> - Replace the content of a node with the specified nodes and return the replaced content
37180  
37181 505 L<replaceContentWithMovedContent|/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.
37182  
37183 506 L<replaceContentWithText|/replaceContentWithText> - Replace the content of a node with the specified texts and return the replaced content
37184  
37185 507 L<replaceSpecialChars|/replaceSpecialChars> - Replace < > " & with &lt; &gt; &quot; &amp; Larry Wall's excellent L<Xml parser> unfortunately replaces &lt; &gt; &quot; &amp; etc.
37186  
37187 508 L<replaceWith|/replaceWith> - Replace a node (and all its content) with a L<new node|/newTag> (and all its content) and return the new node.
37188  
37189 509 L<replaceWithBlank|/replaceWithBlank> - Replace a node (and all its content) with a new blank text node and return the new node.
37190  
37191 510 L<replaceWithRequiredCleanUp|/replaceWithRequiredCleanUp> - Replace a B<$node> with required cleanup B<@text> and return the new node
37192  
37193 511 L<replaceWithText|/replaceWithText> - Replace a node (and all its content) with a new text node and return the new node.
37194  
37195 512 L<reportNode|/reportNode> - Print the parse tree starting at the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
37196  
37197 513 L<reportNodeAttributes|/reportNodeAttributes> - Print the attributes of the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
37198  
37199 514 L<reportNodeContext|/reportNodeContext> - Print the context of the specified B<$node> identified by the specified B<$label> if we are in the optional B<@context>.
37200  
37201 515 L<requiredCleanUp|/requiredCleanUp> - Replace a B<$node> with a required cleanup node with special characters replaced by symbols and with the optional B<$outputclass>.
37202  
37203 516 L<restore|/restore> - Return a L<parse|/parse> tree from a copy saved in a file by L<save|/save>.
37204  
37205 517 L<save|/save> - Save a copy of the L<parse|/parse> tree to a file which can be L<restored|/restore> and return the saved node.
37206  
37207 518 L<set|/set> - Set the values of some attributes in a node and return the node.
37208  
37209 519 L<setAttr|/setAttr> - Set the values of some attributes in a node and return the node.
37210  
37211 520 L<setDepthProfile|/setDepthProfile> - Sets the L<depthProfile|/depthProfile> for every node in the specified B<$tree>.
37212  
37213 521 L<setRepresentationAsTagsAndText|/setRepresentationAsTagsAndText> - Sets the L<representationLast|/representationLast> for every node in the specified B<$tree> via L<stringTagsAndText|/stringTagsAndText>.
37214  
37215 522 L<setRepresentationAsText|/setRepresentationAsText> - Sets the L<representationLast|/representationLast> for every node in the specified B<$tree> via L<stringText|/stringText>.
37216  
37217 523 L<setSelectionEnd|/setSelectionEnd> - Set the selection to end at the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
37218  
37219 524 L<setSelectionStart|/setSelectionStart> - Set the selection to start at the specified B<$node> in the optional B<@context> and return the specified B<$node> on success else B<undef>.
37220  
37221 525 L<splitAfter|/splitAfter> - Split the parent node into two identical nodes except all the siblings after the specified B<$node> are retained by the existing parent while any preceding siblings become siblings of the new parent node which is placed before the existing parent.
37222  
37223 526 L<splitAndWrapFromStart|/splitAndWrapFromStart> - Split the child nodes of B<$parent> on the child nodes with a tag of B<$split> wrapping the splitting node and all preceding nodes from the previous splitting node or the start with the specified B<$wrap>ping node with optional B<%attributes>.
37224  
37225 527 L<splitAndWrapToEnd|/splitAndWrapToEnd> - Split the sequence of child nodes under the specified B<$parent> node on those child nodes whose tag value is B<$split> wrapping the splitting node and all following nodes up until the next splitting node or the end of the sequence with newly created nodes whose tag is B<$wrap> with optional attributes B<%attributes>.
37226  
37227 528 L<splitBefore|/splitBefore> - Split the parent node into two identical nodes except all the siblings before the specified B<$node> are retained by the existing parent while any following siblings become siblings of the new parent node which is placed after the existing parent.
37228  
37229 529 L<splitParentAfter|/splitParentAfter> - Finish and restart the parent of the specified B<$node> just after the specified B<$node> and return the newly created parent node on success or B<undef> on failure.
37230  
37231 530 L<splitParentBefore|/splitParentBefore> - Finish and restart the parent of the specified B<$node> just before the specified B<$node> and return the newly created parent node on success or B<undef> on failure.
37232  
37233 531 L<splitTo|/splitTo> - Lift the specified B<$node> up until it splits the specified B<$parent> node.
37234  
37235 532 L<sss|/sss> - Put, after the current B<$node>, the specified B<@text> and return the current $node.
37236  
37237 533 L<string|/string> - Return a dense string representing a node of a L<parse|/parse> tree and all the nodes below it.
37238  
37239 534 L<stringAsMd5Sum|/stringAsMd5Sum> - Return the L<md5 sum|https://en.wikipedia.org/wiki/MD5> of the dense L<string|/string> representing a node of a L<parse|/parse> tree minus its L<id> and all the nodes below it.
37240  
37241 535 L<stringContent|/stringContent> - Return a string representing all the nodes below a node of a L<parse|/parse> tree.
37242  
37243 536 L<stringContentOrText|/stringContentOrText> - Return a string representing all the nodes below a node of a L<parse|/parse> tree or the text of the current node if it is a text node.
37244  
37245 537 L<stringExtendingIdsWithLabels|/stringExtendingIdsWithLabels> - Return a string representing the specified L<parse|/parse> tree with the id attribute of each node extended by the L<Labels|/Labels> attached to each node.
37246  
37247 538 L<stringNode|/stringNode> - Return a string representing the specified B<$node> showing the attributes, labels and node number.
37248  
37249 539 L<stringQuoted|/stringQuoted> - Return a quoted string representing a L<parse|/parse> tree a node of a L<parse|/parse> tree and all the nodes below it.
37250  
37251 540 L<stringReplacingIdsWithLabels|/stringReplacingIdsWithLabels> - Return a string representing the specified L<parse|/parse> tree with the id attribute of each node set to the L<Labels|/Labels> attached to each node.
37252  
37253 541 L<stringTagsAndText|/stringTagsAndText> - Return a string showing just the tags and text at and below a specified B<$node>.
37254  
37255 542 L<stringText|/stringText> - Return a string showing just the text of the text nodes (separated by blanks) at and below a specified B<$node>.
37256  
37257 543 L<stringWithConditions|/stringWithConditions> - Return a string representing the specified B<$node> of a L<parse|/parse> tree and all the nodes below it subject to conditions to select or reject some nodes.
37258  
37259 544 L<structureAdjacentSectionsByLevel|/structureAdjacentSectionsByLevel> - Structure adjacent sections by level
37260  
37261 545 L<subMd5|/subMd5> - Return a hash {L<md5 sum|https://en.wikipedia.org/wiki/MD5> of parse tree}{string representation of sub tree}++ to locate common parse trees under B<$node> that could be included via a conref.
37262  
37263 546 L<subMd5Tree|/subMd5Tree> - Return the L<md5 sum|https://en.wikipedia.org/wiki/MD5> of the L<stringContent> of the parse tree.
37264  
37265 547 L<succeedingSiblingOf|/succeedingSiblingOf> - Returns the specified B<$child> node if it has the same parent as B<$sibling> and occurs after B<$sibling> and has the optionally specified context else returns B<undef>.
37266  
37267 548 L<swap|/swap> - Swap two nodes optionally checking that the first node is in the specified context and return the first node.
37268  
37269 549 L<swapFirstSibling|/swapFirstSibling> - Swap B<$node> with its first sibling node and return B<$node>.
37270  
37271 550 L<swapLastSibling|/swapLastSibling> - Swap B<$node> with its last sibling node and return B<$node>.
37272  
37273 551 L<swapNext|/swapNext> - Swap B<$node> with its following node if $B<$node> matches the first element of the specified context and the next node matches the rest.
37274  
37275 552 L<swapPrev|/swapPrev> - Swap B<$node> with its preceding node if $B<$node> matches the first element of the specified context and the previous node matches the rest.
37276  
37277 553 L<swapTags|/swapTags> - Swap the tags of two nodes optionally checking that the first node is in the specified context and return (B<$first>, B<$second>) nodes.
37278  
37279 554 L<swapTagWithParent|/swapTagWithParent> - Swap the tags of the specified B<$node> and its parent optionally checking that the B<$node> is in the specified context and return (parent of B<$node>, B<$node>) or () if there is no such parent node.
37280  
37281 555 L<through|/through> - Traverse L<parse|/parse> tree visiting each node twice calling the specified sub B<$before> as we go down past the node and sub B<$after> as we go up past the node, finally return the specified starting node.
37282  
37283 556 L<throughX|/throughX> - Identical to L<through|/through> except the B<$before, $after> subs are called in an L<eval|http://perldoc.perl.org/functions/eval.html> block to prevent L<die|http://perldoc.perl.org/functions/die.html> terminating the traversal of the full tree.
37284  
37285 557 L<to|/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.
37286  
37287 558 L<tocNumbers|/tocNumbers> - Table of Contents number the nodes in a L<parse|/parse> tree.
37288  
37289 559 L<top|/top> - Return the top of the parse tree containing the current B<$node> after optionally checking that the $node is in the optional B<@context>.
37290  
37291 560 L<topicTypeAndBody|/topicTypeAndBody> - Topic type and corresponding body.
37292  
37293 561 L<tree|/tree> - Build a tree representation of the parsed L<Xml|https://en.wikipedia.org/wiki/XML> which can be easily traversed to look for things.
37294  
37295 562 L<undoSpecialChars|/undoSpecialChars> - Reverse the results of calling L<replaceSpecialChars|/replaceSpecialChars>.
37296  
37297 563 L<unwrap|/unwrap> - Unwrap the specified B<$node> if in the optional B<@context> by replacing the node with its contents.
37298  
37299 564 L<unwrapContentsKeepingText|/unwrapContentsKeepingText> - Unwrap all the non text nodes below the specified B<$node> adding a leading and a trailing space to prevent unwrapped content from being elided and return the specified B<$node> else B<undef> if not in the optional B<@context>.
37300  
37301 565 L<unwrapOnlyChild|/unwrapOnlyChild> - Unwrap the specified B<$node> in the optional B<@context> when the B<$node> is the only child of its parent.
37302  
37303 566 L<unwrapParentOfOnlyChild|/unwrapParentOfOnlyChild> - Unwrap the parent of the specified B<$node> in the optional B<@context> when the B<$node> is the only child of its parent.
37304  
37305 567 L<unwrapParentsWithSingleChild|/unwrapParentsWithSingleChild> - Unwrap any immediate ancestors of the specified B<$node> in the optional B<@context> which have only a single child and return the specified B<$node> regardless unless the node is not in the optional context in which case return B<undef>.
37306  
37307 568 L<unwrapSingleParentsOfSection|/unwrapSingleParentsOfSection> - Unwrap single parents of section: in word documents the header is often buried in a list to gain a section number - here we remove these unnecessary items
37308  
37309 569 L<up|/up> - Return the parent of the current node optionally checking the parent node's context or return B<undef> if the specified B<$node> is the root of the L<parse|/parse> tree.
37310  
37311 570 L<upn|/upn> - Go up the specified number of levels from the specified B<$node> and return the node reached optionally checking the parent node's context or B<undef> if there is no such node.
37312  
37313 571 L<upThru|/upThru> - Go up the specified path from the specified B<$node> returning the node at the top or B<undef> if no such node exists.
37314  
37315 572 L<upUntil|/upUntil> - Find the first node going up from B<$node> that matches the specified B<@context>.
37316  
37317 573 L<upUntilFirst|/upUntilFirst> - Move up from the specified B<$node> until we reach the root or a first node.
37318  
37319 574 L<upUntilIsOnlyChild|/upUntilIsOnlyChild> - Move up from the specified B<$node> until we reach the root or another only child.
37320  
37321 575 L<upUntilLast|/upUntilLast> - Move up from the specified B<$node> until we reach the root or a last node.
37322  
37323 576 L<upWhile|/upWhile> - Go up one level from the specified B<$node> and then continue up while each node matches on of the specified <@tags>.
37324  
37325 577 L<upWhileFirst|/upWhileFirst> - Move up from the specified B<$node> as long as each node is a first node or return B<undef> if the specified B<$node> is not a first node.
37326  
37327 578 L<upWhileIsOnlyChild|/upWhileIsOnlyChild> - Move up from the specified B<$node> as long as each node is an only child or return B<undef> if the specified B<$node> is not an only child.
37328  
37329 579 L<upWhileLast|/upWhileLast> - Move up from the specified B<$node> as long as each node is a last node or return B<undef> if the specified B<$node> is not a last node.
37330  
37331 580 L<wordStyles|/wordStyles> - Extract style information from a parse tree representing a word document.
37332  
37333 581 L<wrapContentWith|/wrapContentWith> - Wrap the content of the specified B<$node> in a new node created from the specified B<$tag> and B<%attributes>: the specified B<$node> then contains just the new node which, in turn, contains all the content of the specified B<$node>.
37334  
37335 582 L<wrapContentWithDup|/wrapContentWithDup> - Wrap the content if the specified B<$node> in a new node with the same tag as $node in the optional B<@context> making the new node an L<only child|/isOnlyChild> of $node.
37336  
37337 583 L<wrapDown|/wrapDown> - Wrap the content of the specified B<$node> in a sequence of new nodes forcing the original node up - deepening the L<parse|/parse> tree - return the array of wrapping nodes if want array else the last wrapping node.
37338  
37339 584 L<wrapFirstN|/wrapFirstN> - Wrap the first B<$N> nodes under this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
37340  
37341 585 L<wrapFrom|/wrapFrom> - Wrap all the nodes from the B<$start> node to the B<$end> node with a new node created from the specified B<$tag> and B<%attributes> and return the new node.
37342  
37343 586 L<wrapFromFirst|/wrapFromFirst> - Wrap this B<$node> and any preceding siblings with a new node created from the specified B<$tag> and B<%attributes> and return the wrapping node.
37344  
37345 587 L<wrapFromFirstOrLastIn|/wrapFromFirstOrLastIn> - Wrap inclusively from the first sibling node to the specified B<$node> or from the last prior sibling node whose tag matches one of the tags in B<@targets> to the specified B<$node> using B<$tag> as the tag of the wrapping node and return the wrapping node.
37346  
37347 588 L<wrapLastN|/wrapLastN> - Wrap the last B<$N> nodes under this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
37348  
37349 589 L<wrapNext|/wrapNext> - Wrap this B<$node> and the following sibling with a new node created from the specified B<$tag>.
37350  
37351 590 L<wrapNextN|/wrapNextN> - Wrap this B<$node>and the next B<$N>-1 nodes following this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
37352  
37353 591 L<wrapPrev|/wrapPrev> - Wrap this B<$node> and the preceding sibling with a new node created from the specified B<$tag>.
37354  
37355 592 L<wrapPrevN|/wrapPrevN> - Wrap this B<$node>and the previous B<$N>-1 nodes following this B<$node> in the optional B<@context> with the specified B<$tag> and return the new node or B<undef> if there are no such nodes to wrap.
37356  
37357 593 L<wrapRuns|/wrapRuns> - Wrap consecutive runs of children under the specified parent B<$node> that are not already wrapped with B<$wrap>.
37358  
37359 594 L<wrapSiblingsAfter|/wrapSiblingsAfter> - If there are any siblings after the specified B<$node>, wrap them with a new node created from the specified B<$tag> and B<%attributes> and return the newly created node.
37360  
37361 595 L<wrapSiblingsBefore|/wrapSiblingsBefore> - If there are any siblings before the specified B<$node>, wrap them with a new node created from the specified B<$tag> and B<%attributes> and return the newly created node.
37362  
37363 596 L<wrapSiblingsBetween|/wrapSiblingsBetween> - If there are any siblings between the specified B<$node>s, wrap them with a new node created from the specified B<$tag> and B<%attributes>.
37364  
37365 597 L<wrapTo|/wrapTo> - Wrap all the nodes from the B<$start> node to the B<$end> node inclusive with a new node created from the specified B<$tag> and B<%attributes> and return the new node.
37366  
37367 598 L<wrapToLast|/wrapToLast> - Wrap this B<$node> and any following siblings with a new node created from the specified B<$tag> and B<%attributes> and return the wrapping node.
37368  
37369 599 L<wrapToLastOrFirstIn|/wrapToLastOrFirstIn> - Wrap this B<$node> and any following siblings, up to and including the first sibling that matches one of the specified B<@find> nodes or all following siblings if no such match occurs, with a new node created from the specified B<$tag> and return the new wrapping node.
37370  
37371 600 L<wrapUp|/wrapUp> - Wrap the specified B<$node> in a sequence of new nodes created from the specified B<@tags> forcing the original node down - deepening the L<parse|/parse> tree - return the array of wrapping nodes if want array else the last wrapping node.
37372  
37373 601 L<wrapWith|/wrapWith> - Wrap the specified B<$node> in a new node created from the specified B<$tag> in the optional B<@context> forcing the specified $node down to deepen the L<parse|/parse> tree - return the new wrapping node or B<undef> if this is not possible.
37374  
37375 602 L<wrapWithAll|/wrapWithAll> - Wrap this B<$node> wrapped with the specified B<@tags> and return the last wrapping node.
37376  
37377 603 L<wrapWithDup|/wrapWithDup> - Wrap the specified B<$node> in a new node with the same tag as $node in the optional B<@context> making $node an L<only child|/isOnlyChild> of the new node.
37378  
37379 604 L<wrapWithN|/wrapWithN> - Wrap this B<$node> with the first B<$N> elements of B<@context>.
37380  
37381 605 L<writeCompressedFile|/writeCompressedFile> - Write the parse tree starting at B<$node> as compressed L<Xml|https://en.wikipedia.org/wiki/XML> to the specified B<$file>.
37382  
37383 606 L<writeContentToGitHub|/writeContentToGitHub> - Upload the contents of a string to a file on github
37384  
37385 607 L<writeFileToGitHub|/writeFileToGitHub> - Upload the contents of the specified local file to a file on github
37386  
37387 608 L<xmlHeader|/xmlHeader> - Add the standard L<Xml|https://en.wikipedia.org/wiki/XML> header to a string
37388  
37389 609 L<xmlToJson|/xmlToJson> - Return a Json string representing valid L<Xml|https://en.wikipedia.org/wiki/XML> contained in a file or string, optionally double escaping escape characters.
37390  
37391 610 L<xmlToPerl|/xmlToPerl> - Parse some L<Xml|https://en.wikipedia.org/wiki/XML>, validate using a description recognized by L<checkAllPaths> and return the corresponding L<Perl|http://www.perl.org/> structure.
37392  
37393 611 L<zipDown|/zipDown> - Push a node down as many levels as possible by making it a child of a node formed by merging the preceding and following siblings if they have the same tag.
37394  
37395 612 L<zipDownOnce|/zipDownOnce> - Push a node down one level by making it a child of a node formed by merging the preceding and following siblings if they have the same tag.
37396  
37397 =head1 Installation
37398  
37399 This module is written in 100% Pure Perl and, thus, it is easy to read,
37400 comprehend, use, modify and install via B<cpan>:
37401  
37402 sudo cpan install Data::Edit::Xml
37403  
37404 =head1 Author
37405  
37406 L<philiprbrenan@gmail.com|mailto:philiprbrenan@gmail.com>
37407  
37408 L<http://www.appaapps.com|http://www.appaapps.com>
37409  
37410 =head1 Copyright
37411  
37412 Copyright (c) 2016-2019 Philip R Brenan.
37413  
37414 This module is free software. It may be used, redistributed and/or modified
37415 under the same terms as Perl itself.
37416  
37417 =cut
37418  
37419  
37420 sub firstNonBlank
37421 {my $r = &first($_[0]);
37422 return undef unless $r;
37423 if ($r->isBlankText)
37424 {shift @_;
37425 return &next($r, @_)
37426 }
37427 else
37428 {return &next(@_);
37429 }
37430 }
37431  
37432 sub firstNonBlankX
37433 {my $r = &firstNonBlank(@_);
37434 die 'first' unless defined($r);
37435 $r
37436 }
37437  
37438 sub isFirstNonBlank
37439 {my $r = &isFirst($_[0]);
37440 return undef unless $r;
37441 if ($r->isBlankText)
37442 {shift @_;
37443 return &isFirst($r, @_)
37444 }
37445 else
37446 {return &isFirst(@_);
37447 }
37448 }
37449  
37450 sub isFirstNonBlankX
37451 {my $r = &isFirstNonBlank(@_);
37452 die 'isFirst' unless defined($r);
37453 $r
37454 }
37455  
37456 sub isLastNonBlank
37457 {my $r = &isLast($_[0]);
37458 return undef unless $r;
37459 if ($r->isBlankText)
37460 {shift @_;
37461 return &isLast($r, @_)
37462 }
37463 else
37464 {return &isLast(@_);
37465 }
37466 }
37467  
37468 sub isLastNonBlankX
37469 {my $r = &isLastNonBlank(@_);
37470 die 'isLast' unless defined($r);
37471 $r
37472 }
37473  
37474 sub lastNonBlank
37475 {my $r = &last($_[0]);
37476 return undef unless $r;
37477 if ($r->isBlankText)
37478 {shift @_;
37479 return &prev($r, @_)
37480 }
37481 else
37482 {return &prev(@_);
37483 }
37484 }
37485  
37486 sub lastNonBlankX
37487 {my $r = &lastNonBlank(@_);
37488 die 'last' unless defined($r);
37489 $r
37490 }
37491  
37492 sub nextNonBlank
37493 {my $r = &next($_[0]);
37494 return undef unless $r;
37495 if ($r->isBlankText)
37496 {shift @_;
37497 return &next($r, @_)
37498 }
37499 else
37500 {return &next(@_);
37501 }
37502 }
37503  
37504 sub nextNonBlankX
37505 {my $r = &nextNonBlank(@_);
37506 die 'next' unless defined($r);
37507 $r
37508 }
37509  
37510 sub prevNonBlank
37511 {my $r = &prev($_[0]);
37512 return undef unless $r;
37513 if ($r->isBlankText)
37514 {shift @_;
37515 return &prev($r, @_)
37516 }
37517 else
37518 {return &prev(@_);
37519 }
37520 }
37521  
37522 sub prevNonBlankX
37523 {my $r = &prevNonBlank(@_);
37524 die 'prev' unless defined($r);
37525 $r
37526 }
37527  
37528  
37529 # Tests and documentation
37530  
37531 sub test
37532 {my $p = __PACKAGE__;
37533 binmode($_, ":utf8") for *STDOUT, *STDERR;
37534 return if eval "eof(${p}::DATA)";
37535 my $s = eval "join('', <${p}::DATA>)";
37536 $@ and die $@;
37537 eval $s;
37538 $@ and die $@;
37539 1
37540 }
37541  
37542 test unless caller;
37543  
37544 1;
37545 # podDocumentation
37546 __DATA__
↑ Summary