| 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+);)) (&)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 < > " & Larry Wall's excellent L<Xml parser> unfortunately replaces < > " & etc. with their expansions in text by default and does not seem to provide an obvious way to stop this behavior, so we have to put them back again using this method. | ||
| 304 | {my ($string) = @_; # String to be edited. | ||
| 305 | $string =~ s/\&/&/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 & | ||
| 306 | $string =~ s/\</</gr =~ s/\>/>/gr =~ s/\"/"/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/&/\&/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 & | ||
| 312 | $string =~ s/</\</gr =~ s/>/\>/gr =~ s/"/\"/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 | .(" "x(4*($depth//0))) | ||
| 491 | .qq(</span>); | ||
| 492 | |||
| 493 | return $space # No sub nodes | ||
| 494 | .q(<span class="xmlLt"><</span>) | ||
| 495 | .$t | ||
| 496 | .$node->printAttributesHtml | ||
| 497 | .q(<span class="xmlSlashGt">/></span>) | ||
| 498 | ."\n" if !@$content; | ||
| 499 | |||
| 500 | my $s = $space # Has sub nodes | ||
| 501 | .q(<span class="xmlLt"><</span>) | ||
| 502 | .$t | ||
| 503 | .$node->printAttributesHtml | ||
| 504 | .q(<span class="xmlGt">></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"></</span>) | ||
| 514 | .$t | ||
| 515 | .q(<span class="xmlGt">></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>…</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>$bb or | ||
| 8547 | $b>$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<$3>)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 < > " & Larry Wall's excellent L<Xml parser> unfortunately replaces < > " & etc. with their expansions in text by default and does not seem to provide an obvious way to stop this behavior, so we have to put them back again using this method. | ||
| 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(<">); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲 | ||
| 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(<">)) 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"><</span><span class="xmlTag">a</span> <span class="xmlAttr">id</span><span class="xmlEquals">=</span><span class="xmlValue">"1"</span><span class="xmlGt">></span></div> | ||
| 9558 | <div class="xmlLine"><span class="xmlLineStartTag"> </span><span class="xmlLt"><</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">></span></div> | ||
| 9559 | <div class="xmlLine"><span class="xmlLineStartTag"> </span><span class="xmlLt"><</span><span class="xmlTag">c</span><span class="xmlSlashGt">/></span></div> | ||
| 9560 | <div class="xmlLine"><span class="xmlLineStartTag"> </span><span class="xmlLtSlash"></</span><span class="xmlTag">b</span><span class="xmlGt">></span></div> | ||
| 9561 | <div class="xmlLine"><span class="xmlLineStartTag"> </span><span class="xmlLt"><</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">></span><span class="xmlText">Some text</span><span class="xmlLtSlash"></</span><span class="xmlTag">d</span><span class="xmlGt">></span></div> | ||
| 9562 | <div class="xmlLine"><span class="xmlLineStartTag"></span><span class="xmlLtSlash"></</span><span class="xmlTag">a</span><span class="xmlGt">></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"><b> | ||
| 30173 | <c> | ||
| 30174 | ccc | ||
| 30175 | </c> | ||
| 30176 | </b> | ||
| 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"><</span><span class="xmlTag">a</span> <span class="xmlAttr">id</span><span class="xmlEquals">=</span><span class="xmlValue">"1"</span><span class="xmlGt">></span></div> | ||
| 34780 | <div class="xmlLine"><span class="xmlLineStartTag"> </span><span class="xmlLt"><</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">></span></div> | ||
| 34781 | <div class="xmlLine"><span class="xmlLineStartTag"> </span><span class="xmlLt"><</span><span class="xmlTag">c</span><span class="xmlSlashGt">/></span></div> | ||
| 34782 | <div class="xmlLine"><span class="xmlLineStartTag"> </span><span class="xmlLtSlash"></</span><span class="xmlTag">b</span><span class="xmlGt">></span></div> | ||
| 34783 | <div class="xmlLine"><span class="xmlLineStartTag"> </span><span class="xmlLt"><</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">></span><span class="xmlText">Some text</span><span class="xmlLtSlash"></</span><span class="xmlTag">d</span><span class="xmlGt">></span></div> | ||
| 34784 | <div class="xmlLine"><span class="xmlLineStartTag"></span><span class="xmlLtSlash"></</span><span class="xmlTag">a</span><span class="xmlGt">></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 < > " & Larry Wall's excellent L<Xml parser> unfortunately replaces < > " & 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__ | ||