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

Name

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

Synopsis

Transform some DocBook xml into Dita:

use Data::Edit::Xml;

# Docbook

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

# Transform to Dita

->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) = @_;
  $o->change(qw(step))          if $o->at(qw(li sli));
  $o->change(qw(steps))         if $o->at(qw(sli));
  $o->id = 's'.($o->position+1) if $o->at(qw(step));
  $o->id = 'i'.($o->index+1)    if $o->at(qw(info));
  $o->wrapWith(qw(screen))      if $o->at(qw(CDATA stepresult));
 })

 # Print
 ->prettyString;

Produces:

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

Description

Constructor

new

New parse - call this method statically as in Data::Edit::Xml::new() with keyword parameters=> chosen from:

inputString a string of xml to be parsed
inputFile   a file 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
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, returns the root of the parse tree

cdata

The name of the tag used to represent text - this tag should not also be used as a command

newText

Create a new text node

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

newTag

Create a new non text node

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

newTree

Create a new tree - this is a static method

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

tags

Count the number of tags in a parse tree

   Parameter  Description
1  $node      Parse tree

Stringification

Print the parse tree

string

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

   Parameter  Description
1  $node      Start node

contentString

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

   Parameter  Description
1  $node      Start node

prettyString

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

   Parameter  Description
1  $node      Start node
2  $depth     Depth

PrettyContentString

Return a readable string representing all the nodes below a node of a parse tree - infrequent use and so capitialised to avoid being presented as an option by Geany

   Parameter  Description
1  $node      Start node

Conditions

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

stringWithConditions

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

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

addConditions

Add conditions to a node and return the node

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

deleteConditions

Delete conditions applied to a node and return the node

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

listConditions

Return a list of conditions applied to a node

   Parameter  Description
1  $node      Node

Attributes

Get or set attributes

attr :lvalue

Return the value of an attribute of the current node as an assignable value

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

attrs

Return the values of the specified attributes of the current node

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

attrCount

Return the number of attributes in the specified node

   Parameter  Description
1  $node      Node in parse tree

setAttr

Set the value of an attribute in a node and return the node

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

deleteAttr

Delete the attribute, optionally checking its value first and return the node

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

deleteAttrs

Delete any attributes mentioned in a list without checking their values and return the node

   Parameter  Description
1  $node      Node
2  @attrs     Attribute name

renameAttr

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

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

changeAttr

Change the name of an attribute unless it has already been set and return the node

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

renameAttrValue

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

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

changeAttrValue

Change the name and value of an attribute unless it has already been set and return the node

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

Traversal

Traverse the parse tree

by

Post-order traversal of a parse tree or sub tree and return the specified starting node

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

byReverse

Reverse post-order traversal of a parse tree or sub tree and return the specified starting node

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

down

Pre-order traversal down through a parse tree or sub tree and return the specified starting node

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

downReverse

Reverse pre-order traversal down through a parse tree or sub tree and return the specified starting node

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

through

Traverse parse tree visiting each node twice and return the specified starting node

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

at

Confirm that the node has the specified ancestry

   Parameter  Description
1  $node      Starting node
2  @context   Ancestry

Contents

Contents of the specified node

contents

Return all the nodes contained by this node either as an array or as a reference to such an array

   Parameter  Description
1  $node      Node

contentBeyond

Return all the nodes following this node at the level of this node

   Parameter  Description
1  $node      Node

contentBefore

Return all the nodes preceding this node at the level of this node

   Parameter  Description
1  $node      Node

contentAsTags

Return a string containing the tags of all the nodes contained by this node separated by single spaces

   Parameter  Description
1  $node      Node

contentBeyondAsTags

Return a string containing the tags of all the nodes following this node separated by single spaces

   Parameter  Description
1  $node      Node

position

Return the index of a node in its parent's content

   Parameter  Description
1  $node      Node

index

Return the index of a node in its parent index

   Parameter  Description
1  $node      Node

present

Return the count of the number of the specified tag types present immediately under a node

   Parameter  Description
1  $node      Node
2  @names     Possible tags immediately under the node

count

Return the count the number of instances of the specified tags under the specified node, either by tag in array context or in total in scalar context

   Parameter  Description
1  $node      Node
2  @names     Possible tags immediately under the node

isText

Confirm that this is a text node

   Parameter  Description
1  $node      Node to test

blankText

Confirm that this is a blank text node

   Parameter  Description
1  $node      Node

countNotBlank

Return the count of the number of instances of non blank text under the specified node

   Parameter  Description
1  $node      Node

Move around in the parse tree

get

Return a sub node under the specified 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 position?)* where position defaults to zero if not specified

c

Return an array of all the nodes with the specified tag below the specified node

   Parameter  Description
1  $node      Node
2  $tag       Tag

first

Return the first node below this node

   Parameter  Description
1  $node      Node

firstNotBlank

Return the first node below this node which is not blank text

   Parameter  Description
1  $node      Node

firstOf

Return the first instance of each of the specified tags under the specified node

   Parameter  Description
1  $node      Node
2  @names     Tags to find the first instance of

last

Return the last node below this node

   Parameter  Description
1  $node      Node

lastNotBlank

Return the last node below this node which is not blank text

   Parameter  Description
1  $node      Node

next

Return the node next to the specified node

   Parameter  Description
1  $node      Node

nextNotBlank

Return the next node following this node which is not blank text

   Parameter  Description
1  $node      Node

prev

Return the node previous to the specified node

   Parameter  Description
1  $node      Node

prevNotBlank

Return the previous node preceding this node which is not blank text

   Parameter  Description
1  $node      Node

Position

context

Return a string containing the tag of this node and its ancestors separated by single spaces

   Parameter  Description
1  $node      Node

isFirst

Confirm that this node is the first node under its parent

   Parameter  Description
1  $node      Node

isLast

Confirm that this node is the last node under its parent

   Parameter  Description
1  $node      Node

isOnlyChild

Confirm that this node is the only node under its parent

   Parameter  Description
1  $node      Node

isEmpty

Confirm that this node is empty, that is: this node has no content, not even a blank string of text

   Parameter  Description
1  $node      Node

over

Confirm that the string representing the tags at the level below this node match a regular expression

   Parameter  Description
1  $node      Node
2  $re        Regular expression

after

Confirm that the string representing the tags following this node match a regular expression

   Parameter  Description
1  $node      Node
2  $re        Regular expression

before

Confirm that the string representing the tags preceding this node match a regular expression

   Parameter  Description
1  $node      Node
2  $re        Regular expression

upto

Return the first ancestral node that matches the specified context

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

Editing

Edit the data in the parse tree

change

Change the name of a node in an optional tag context and return the node

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

Structure

Change the structure of the parse tree

wrapWith

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

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

wrapUp

Wrap the original node in a sequence of new nodes forcing the original node down deepening the parse tree; return the array of wrapping nodes

   Parameter  Description
1  $node      Node to wrap
2  @tags      Tags to wrap the node with - with the uppermost tag rightmost

wrapContentWith

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; returns the new wrapped node

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

unwrap

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

   Parameter  Description
1  $node      Node to unwrap

replaceWith

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

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

replaceWithText

Replace a node (and all its content) with a new text node and return the new node

   Parameter  Description
1  $old       Old node
2  $text      Text of new node

replaceWithBlank

Replace a node (and all its content) with a new blank text node and return the new node

   Parameter  Description
1  $old       Old node

Cut and Put

Move nodes around in the parse tree

cut

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

   Parameter  Description
1  $node      Node to  cut out

putNext

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

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

putPrev

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

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

putFirst

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

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

putLast

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

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

putFirstAsText

Add a new text node first under a parent and return the new text node

   Parameter  Description
1  $node      The parent node
2  $text      The string to be added which might contain unparsed xml as well as text

putLastAsText

Add a new text node last under a parent and return the new text node

   Parameter  Description
1  $node      The parent node
2  $text      The string to be added which might contain unparsed xml as well as text

putNextAsText

Add a new text node following this node and return the new text node

   Parameter  Description
1  $node      The parent node
2  $text      The string to be added which might contain unparsed xml as well as text

putPrevAsText

Add a new text node following this node and return the new text node

   Parameter  Description
1  $node      The parent node
2  $text      The string to be added which might contain unparsed xml as well as text

Index

addConditions

after

at

attr :lvalue

attrCount

attrs

before

blankText

by

byReverse

c

cdata

change

changeAttr

changeAttrValue

contentAsTags

contentBefore

contentBeyond

contentBeyondAsTags

contents

contentString

context

count

countNotBlank

cut

deleteAttr

deleteAttrs

deleteConditions

down

downReverse

first

firstNotBlank

firstOf

get

index

isEmpty

isFirst

isLast

isOnlyChild

isText

last

lastNotBlank

listConditions

new

newTag

newText

newTree

next

nextNotBlank

over

position

present

PrettyContentString

prettyString

prev

prevNotBlank

putFirst

putFirstAsText

putLast

putLastAsText

putNext

putNextAsText

putPrev

putPrevAsText

renameAttr

renameAttrValue

replaceWith

replaceWithBlank

replaceWithText

setAttr

string

stringWithConditions

tags

through

unwrap

upto

wrapContentWith

wrapUp

wrapWith

Installation

This module is written in 100% Pure Perl and is thus easy to read, use, modify and install.

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-2017 Philip R Brenan.

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

Installation

This module is written in 100% Pure Perl and is thus easy to read, use, modify and install.

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-2017 Philip R Brenan.

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