/ 
Data-Edit-Xml-1.001
River stage one • 5 direct dependents • 6 total dependents
/ Data::Edit::Xml

Name

Data::Edit::Xml - Edit data held in Xml format

Synopsis

use Data::Edit::Xml;

say STDERR Data::Edit::Xml::new(inputString=><<END)->                          # Docbook to Dita example
<sli>
 <li>
   <p>Diagnose the problem</p>
   <p>This can be quite difficult</p>
   <p>Sometimes impossible</p>
 </li>
 <li>
 <p><pre>ls -la</pre></p>
 <p><pre>
drwxr-xr-x  2 phil phil   4096 Jun 15  2016 Desktop
drwxr-xr-x  2 phil phil   4096 Nov  9 20:26 Downloads
</pre></p>
 </li>
</sli>
END

by(sub
 {my ($o, $p) = @_;
  if ($o->at(qw(pre p li sli)) and $o->isOnlyChild)
   {$o->change($p->isFirst ? qw(cmd) : qw(stepresult));
    $p->unwrap;
   }
  elsif ($o->at(qw(li sli)) and $o->over(qr(\Ap( p)+\Z)))
   {$_->change($_->isFirst ? qw(cmd) : qw(info)) for $o->contents;
   }
 })->by(sub
 {my ($o) = @_;
  if    ($o->at(qw(li sli))) {$o->change(qw(step))}
  elsif ($o->at(qw(sli)))    {$o->change(qw(steps))}
  $o->id = 's'.($o->position+1) if $o->at(qw(step));
  $o->id = 'i'.($o->index+1)    if $o->at(qw(info));
  $o->wrapWith(qw(screen))      if $o->at(qw(CDATA stepresult));
 })->string =~ s/></>\n</gr;

Prints (after being formatted for easier reading):

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

Constructor

new({my $x = {@_};)

New parse - call this method statically as in Data::Edit::Xml::new()

    Parameter       Description
 1  {my $x = {@_};  Parameters chosen from user settable parameters listed below:

 errors       a sub directory of 'output' into which to write a copy of the string to be parsed in the event that an xml parse error is encountered while parsing this string
 inputFile    a file of xml to be parsed
 inputString  a string of xml to be parsed
 name         a symbolic name for this parse used in messages about this parse and to name output files generated by this parse
 output       a directory into which to write output files

badParseOutputFileName($p)

Output file name for file holding details of a failed parse

    Parameter  Description
 1  $p         Parser details

tree($parent, $parse)

Build a tree representation of the parsed xml which can be easily traversed to look for things

    Parameter  Description
 1  $parent    The parent node
 2  $parse     the remaining parse

indexNode($node)

Index the children of a node so that we can access them by tag and number

    Parameter  Description
 1  $node      Node to index

replaceSpecialChars($s)

Replace < and > with &lt; and &gt; in a string

    Parameter  Description
 1  $s         String

Stringification

string($node)

Build string from a node of a parse tree

    Parameter  Description
 1  $node      Start node

stringWithCondition($node, @conditions)

Build string from a node of a parse tree applying conditions to skip some nodes

    Parameter    Description
 1  $node        Start node
 2  @conditions  conditions in effect

isText($node)

Is this a text node?

    Parameter  Description
 1  $node      Node to test

printAttributes($node)

Print the attributes of a node

    Parameter  Description
 1  $node      Node whose attributes are to be printed

Access to attributes and sub-commands

attr :lvalue($node, $attribute)

Value of attribute in current command

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

setAttr($node, %values)

Set the value of an attribute in a command

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

contents($node)

Get all the nodes contained by this node as an array (not an array reference)

    Parameter  Description
 1  $node      Node

contentBeyond($node)

Get all the nodes beyond this node at the level of this node

    Parameter  Description
 1  $node      Node

contentBefore($node)

Get all the nodes before this node at the level of this node

    Parameter  Description
 1  $node      Node

contentAsTags($node)

Get the tags of all the nodes contained by this node as a string

    Parameter  Description
 1  $node      Node

contentBeyondAsTags($node)

Get the tags of all the nodes beyond this node as a string

    Parameter  Description
 1  $node      Node

contentBeforeAsTags($node)

Get the tags of all the nodes before this node as a string

    Parameter  Description
 1  $node      Node

position($node)

Find the position of a node in its parent's content

    Parameter  Description
 1  $node      Node

index($node)

Find the position of a node in its parent's index

    Parameter  Description
 1  $node      Node

context($node)

Tags of this node and its ancestors

    Parameter  Description
 1  $node      Node

get($node, @position)

Get a sub node under the current node by its position in each index with position zero assumed if no position is supplied

    Parameter  Description
 1  $node      Node
 2  @position  position specification: (index

c($node, $tag, $position)

Get all the nodes with the tag of the specified name below the current node

    Parameter  Description
 1  $node      Node
 2  $tag       tag
 3  $position  optional position

first($node)

Get the first node below this node

    Parameter  Description
 1  $node      Node

last($node)

Get the last node below this node

    Parameter  Description
 1  $node      Node

isFirst($node)

Is this node first under its parent?

    Parameter  Description
 1  $node      Node

isLast($node)

Is this node last under its parent?

    Parameter  Description
 1  $node      Node

isOnlyChild($node)

Is this the only child of its parent?

    Parameter  Description
 1  $node      Node

next($node)

Get the node next to the current node

    Parameter  Description
 1  $node      Node

prev($node)

Get the node previous to the current node

    Parameter  Description
 1  $node      Node

by($node, $sub, @context)

Post-order traversal of a parse tree or sub tree - based on experience this is the most useful way to process xml documents

    Parameter  Description
 1  $node      Starting node
 2  $sub       sub to call for each sub node
 3  @context   accumulated context

at({for(my $x = shift @_; $x; $x = $x->parent))

Check the node is in the context specified by the array of tags from the ancestors going up the parse tree from the node

    Parameter                                    Description
 1  {for(my $x = shift @_; $x; $x = $x->parent)  Up through parents

over($node, $re)

Match tags under a node against a regular expression

    Parameter  Description
 1  $node      Node
 2  $re        regular expression

leads($node, $re)

Match tags beyond a node against a regular expression

    Parameter  Description
 1  $node      Node
 2  $re        regular expression

follows($node, $re)

Match tags before a node against a regular expression

    Parameter  Description
 1  $node      Node
 2  $re        regular expression

up($node, @tags)

Go up to a specified context

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

Editing

change($node, $name, @tags)

Change the name of a node in an optional tag context

    Parameter  Description
 1  $node      Node
 2  $name      new name
 3  @tags      tags defining the context

deleteAttr($node, $attr, $value)

Delete the attribute, optionally checking its value first

    Parameter  Description
 1  $node      Node
 2  $attr      attribute name
 3  $value     optional attribute value to check first

renameAttr($node, $old, $new)

Change the name of an attribute regardless of whether the new attribute already exists

    Parameter  Description
 1  $node      Node
 2  $old       existing attribute name
 3  $new       new attribute name

changeAttr($node, $old, $new)

Change the name of an attribute unless it is already there

    Parameter  Description
 1  $node      Node
 2  $old       existing attribute name
 3  $new       new attribute name

renameAttrValue($node, $old, $oldValue, $new, $newValue)

Change the name and value of an attribute regardless of whether the new attribute already exists

    Parameter  Description
 1  $node      Node
 2  $old       existing attribute name and value
 3  $oldValue  new attribute name and value
 4  $new
 5  $newValue

changeAttrValue($node, $old, $oldValue, $new, $newValue)

Change the name and value of an attribute unless it is already there

    Parameter  Description
 1  $node      Node
 2  $old       existing attribute name and value
 3  $oldValue  new attribute name and value
 4  $new
 5  $newValue

Structure

wrapWith($old, $tag)

Wrap the original node in a new node forcing the original node down deepening the parse tree

    Parameter  Description
 1  $old       Node
 2  $tag       tag for new node

wrapContentWith($old, $tag)

Wrap the content of a node in a new node, the original content then contains the new node which contains the original node's content

    Parameter  Description
 1  $old       Node
 2  $tag       tag for new node

unwrap($node)

Unwrap a node by inserting its content into its parent at the point containing the node

    Parameter  Description
 1  $node      Node to unwrap

replaceWith($old, $new)

Replace a node (and all its content) with a new node (and all its content)

    Parameter  Description
 1  $old       Old node
 2  $new       new node

Cut and Put

cut($node)

Cut out a node - remove the node from the parse tree and return it so that it can be put else where

    Parameter  Description
 1  $node      Node to  cut out

putNext($old, $new)

Place the new node just after the original node in the content of the parent

    Parameter  Description
 1  $old       Original node
 2  $new       new node

putPrev($old, $new)

Place the new node just before the original node in the content of the parent

    Parameter  Description
 1  $old       Original node
 2  $new       new node

putFirst($old, $new)

Place the new node at the front of the content of the original node

    Parameter  Description
 1  $old       Original node
 2  $new       new node

putLast($old, $new)

Place the new node at the end of the content of the original node

    Parameter  Description
 1  $old       Original node
 2  $new       new node

Index of methods by name "at" "attr :lvalue" "badParseOutputFileName" "by" "c" "change" "changeAttr" "changeAttrValue" "contentAsTags" "contentBefore" "contentBeforeAsTags" "contentBeyond" "contentBeyondAsTags" "contents" "context" "cut" "deleteAttr" "first" "follows" "get" "index" "indexNode" "isFirst" "isLast" "isOnlyChild" "isText" "last" "leads" "new" "next" "over" "position" "prev" "printAttributes" "putFirst" "putLast" "putNext" "putPrev" "renameAttr" "renameAttrValue" "replaceSpecialChars" "replaceWith" "setAttr" "string" "stringWithCondition" "tree" "unwrap" "up" "wrapContentWith" "wrapWith"

Installation

Standard Module::Build process for building and installing modules:

perl Build.PL
./Build
./Build test
./Build install

Author

philiprbrenan@gmail.com

http://www.appaapps.com

Copyright

Copyright (c) 2016 Philip R Brenan.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.