NAME
XML::TreePP::Editor - An editor for an XML::TreePP parsed XML document
SYNOPSIS
To use stand-alone:
use strict;
use XML::TreePP;
use XML::TreePP::Editor;
my $tpp = XML::TreePP->new();
my $tree = $tpp->parse('file.xml');
my $tppe = new XML::TreePP::Editor();
$tppe->replace( $tree, '/path[2]/element[2]/node', { '-myattribute' => "new value" } );
$tppe->insert( $tree, '.', \%{<new_root_node>} );
DESCRIPTION
This module is used for editing a XML::TreePP parsed XML Document.
REQUIREMENTS
The following perl modules are depended on by this module:
XML::TreePP
XML::TreePP::XMLPath >= version 0.61
METHODS
tpp
This module is an extension of the XML::TreePP module. As such, it uses the module in many different methods to parse XML Docuements, and when the user calls the set()
and get()
methods to set and get properties specific to the module.
The XML::TreePP module, is loaded upon requesting a new object.
The caller can override the loaded instance of XML::TreePP in favor of another instance the caller posses, by proving it to this method.
Additionally, this module's loaded instance of XML::TreePP can be directly accessed or retrieved through this method.
XML::TreePP
An instance of XML::TreePP that this object should use instead of, when needed, loading its own copy. If not provided, the currently loaded instance is returned. If an instance is not loaded, an instance is loaded and then returned.
returns
Returns the result of setting an instance of XML::TreePP in this object. Or returns the internally loaded instance of XML::TreePP. Or loads a new instance of XML::TreePP and returns it.
$tppe->tpp( new XML::TreePP ); # Sets the XML::TreePP instance to be used by this object
my $tppobj = $tppe->tpp(); # Retrieve the currently loaded XML::TreePP instance
tppx
This module is an extension of the XML::TreePP::XMLPath module. As such, it uses the module in many different methods to access XML::TreePP parsed XML Documents, and when the user calls the set()
and get()
methods to set and get properties specific to the module.
The XML::TreePP::XMLPath module, is loaded upon requesting a new object.
The caller can override the loaded instance of XML::TreePP::XMLPath in favor of another instance the caller posses, by proving it to this method.
Additionally, this module's loaded instance of XML::TreePP::XMLPath can be directly accessed or retrieved through this method.
XML::TreePP::XMLPath
An instance of XML::TreePP::XMLPath that this object should use instead of, when needed, loading its own copy. If not provided, the currently loaded instance is returned. If an instance is not already loaded, a new instance is loaded and then returned.
returns
Returns the result of setting an instance of XML::TreePP::XMLPath in this object. Or returns the internally loaded instance of XML::TreePP::XMLPath. Or loads a new instance of XML::TreePP::XMLPath and returns it.
$tppe->tppx( new XML::TreePP::XMLPath ); # Sets the XML::TreePP instance to be used by this object
my $tppxobj = $tppe->tppx(); # Retrieve the currently loaded XML::TreePP instance
set
Set the value for a property in this object instance. This method can only be accessed in object oriented style.
propertyname
The property to set the value for.
propertyvalue
The value of the property to set. If no value is given, the property is deleted.
returns
Returns the result of setting the value of the property, or the result of deleting the property.
$tppe->set( 'attr_prefix' ); # deletes the property attr_prefix
$tppe->set( 'attr_prefix' => '-' ); # sets the value of attr_prefix
$tppe->set( 'text_node_key' => '#text' ); # sets the value of text_node_key
get
Retrieve the value set for a property in this object instance. This method can only be accessed in object oriented style.
propertyname
The property to get the value for
returns
Returns the value of the property requested
$tppe->get( 'attr_prefix' );
new
Create a new object instances of this module.
tpp
An instance of XML::TreePP to be used instead of letting this module load its own.
tppx
An instance of XML::TreePP::XMLPath to be used instead of letting this module load its own.
debug
The debug level to set on this object.
returns
An object instance of this module.
my $cfg = new XML::TreePP::Editor();
debug
Set the debug level
val - optional
A value that is >= 0
returns
If passing in val, then the result of setting that value to the object's debug variable.
If not passing in val, then the current set value of the object's debug variable.
$tppe->debug(0); # turn off debug
$tppe->debug(9); # turn on debug with value of 9
my $debuglevel = $tppe->debug();
modify
modify( XMLTree, XMLPath, %OPTIONS )
where %options = ( action => %value )
and action is one of ( insert, replace, delete, mergeadd, mergereplace, mergedelete, mergeappend )
and %value is a XML Node Hash, either a partial node or full node
XML::TreePP parsed tree
The parsed XML Document.
XML::TreePP::XMLPath path
The XML Path to the node, attribute or element to modify
options
The options for modifying the node.
insert =>
\%node
- insert the new node at XMLPathreplace =>
\%node
- replace the node at XMLPath with this new nodedelete =>
undef
- delete the node at the XMLPathmergeadd =>
\%node
- merge this node into the node at XMLPath, only adding elements and attributes that do not existmergereplace =>
\%node
- merge this node into the node at XMLPath, replacing elements and attributes, and adding them if they do not existmergedelete =>
\%node
- merge this node into the node at XMLPath, deleting elements and attributes that exist in both nodesmergeappend =>
\%node
- merge this node into the node at XMLPath, appending the values of text elements
Example:
my $xmltree => { path => { to => { node => "Brown bears" } } };
$tppe->modify( $xmltree, '/path/to/node', mergeappend => { '#text' => " with blue shoes." } )
# or: $tppe->modify( $xmltree, '/path/to/node/#text', mergeappend => { '#text' => " with blue shoes." } )
# or: $tppe->modify( $xmltree, '/path/to/node/#text', mergeappend => " with blue shoes." )
print $xmltree->{'path'}->{'to'}->{'node'};
output:
Brown bears with blue shoes.
insert
insert( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, insert => $value )
mergeadd
mergeadd( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, mergeadd => $value )
mergereplace
mergereplace( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, mergereplace => $value )
mergeappend
mergeappend( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, mergeappend => $value )
mergedelete
mergedelete( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, mergedelete => $value )
replace
replace( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, replace => $value )
delete
delete( XMLTree, XMLPath )
This is the same as modify( XMLTree, XMLPath, delete => undef )
EXAMPLES
#!/usr/bin/perl
use XML::TreePP;
use XML::TreePP::XMLPath;
use XML::TreePP::Editor;
# Parse the XML document.
my $tpp = new XML::TreePP;
my $tppx = new XML::TreePP::XMLPath;
my $tppe = new XML::TreePP::Editor;
$tpp->set( indent => 4 );
my $xmldoc = $tpp->parse(<<XMLEND
<paragraph>
<sentence language="german">
<words>Do red cats eat yellow food</words>
<punctuation>?</punctuation>
</sentence>
<sentence language="english">
<words>Brown cows eat green grass</words>
<punctuation>.</punctuation>
</sentence>
</paragraph>
XMLEND
);
print $tpp->write($xmldoc);
print "="x20,"\n";
my $sentence_node = { 'words' => "No, cats eat green food",
'-language' => "spanish",
'punctuation' => '!' };
$tppe->insert( $xmldoc, '/paragraph/sentence', $sentence_node );
print $tpp->write($xmldoc);
print "="x20,"\n";
my $wordsnode = { '#text' => "Do cats really eat green food" };
$tppe->mergereplace( $xmldoc, '/paragraph/sentence[@language="german"]/words', $wordsnode );
print $tpp->write($xmldoc);
Output:
<?xml version="1.0" encoding="UTF-8" ?>
<paragraph>
<sentence language="german">
<punctuation>?</punctuation>
<words>Do red cats eat yellow food</words>
</sentence>
<sentence language="english">
<punctuation>.</punctuation>
<words>Brown cows eat green grass</words>
</sentence>
</paragraph>
====================
<?xml version="1.0" encoding="UTF-8" ?>
<paragraph>
<sentence language="german">
<punctuation>?</punctuation>
<words>Do red cats eat yellow food</words>
</sentence>
<sentence language="spanish">
<punctuation>!</punctuation>
<words>No, cats eat green food</words>
</sentence>
<sentence language="english">
<punctuation>.</punctuation>
<words>Brown cows eat green grass</words>
</sentence>
</paragraph>
====================
<?xml version="1.0" encoding="UTF-8" ?>
<paragraph>
<sentence language="german">
<punctuation>?</punctuation>
<words>Do cats really eat green food</words>
</sentence>
<sentence language="spanish">
<punctuation>!</punctuation>
<words>No, cats eat green food</words>
</sentence>
<sentence language="english">
<punctuation>.</punctuation>
<words>Brown cows eat green grass</words>
</sentence>
</paragraph>
AUTHOR
Russell E Glaue, http://russ.glaue.org
SEE ALSO
XML::TreePP
XML::TreePP::XMLPath
XML::TreePP::Editor on Codepin: http://www.codepin.org/project/perlmod/XML-TreePP-Editor
COPYRIGHT AND LICENSE
Copyright (c) 2009 Center for the Application of Information Technologies. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.