XML::TreePP::Editor - An editor for an XML::TreePP parsed XML document
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>} );
This module is used for editing a XML::TreePP parsed XML Document.
XML::TreePP
The following perl modules are depended on by this module:
XML::TreePP::XMLPath >= version 0.61
The identification of XML document nodes for modification is handled by the XML::TreePP::XMLPath module.
XML::TreePP::XMLPath
The idenfication of attributes in XML nodes is via the attr_prefix property in the XML::TreePP module.
attr_prefix
The idenfication of XML text (or CDATA) nodes is via the text_node_key property in the XML::TreePP module.
text_node_key
Please review the XMLPath PHILOSOPHY section in it's POD for further information.
The XML::TreePP::XMLPath module has a dependence on XML::TreePP When XML::TreePP::Editor::tpp() and XML::TreePP::Editor::tppx() methods are called without parameters, this module checks to see if either of these objects have been previously created, and links them together.
XML::TreePP::Editor::tpp()
XML::TreePP::Editor::tppx()
If you provide your own XML::TreePP or XML::TreePP::XMLPath objects, this module does not attempt to link them together. Instead you would want to do it yourself in the following fashion.
my $tpp = new XML::TreePP; my $tppx = new XML::TreePP::XMLPath; $tppx->tpp($tpp); my $tppe = new XML::TreePP::Editor( tpp => $tpp, tppx => $tppx );
This is essentially similar to how the XML::TreePP::Editor::tpp() and XML::TreePP::Editor::tppx() methods associate the objects.
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.
XML::TreePP module
set()
get()
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 providing it to this method.
Additionally, this module's loaded instance of XML::TreePP can be directly accessed or retrieved through this method.
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
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.
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 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 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 the result of setting the value of the property, or the result of deleting the property.
$tppe->set( 'property_name' ); # deletes the property property_name $tppe->set( 'property_name' => 'val' ); # sets the value of property_name
Retrieve the value set for a property in this object instance. This method can only be accessed in object oriented style.
The property to get the value for
Returns the value of the property requested
$tppe->get( 'property_name' );
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.
An object instance of this module.
my $cfg = new XML::TreePP::Editor();
Set the debug level
val - optional
A value that is >= 0
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( 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 XMLPath
\%node
replace => \%node - replace the node at XMLPath with this new node
delete => undef - delete the node at the XMLPath
undef
mergeadd => \%node - merge this node into the node at XMLPath, only adding elements and attributes that do not exist
mergereplace => \%node - merge this node into the node at XMLPath, replacing elements and attributes, and adding them if they do not exist
mergedelete => \%node - merge this node into the node at XMLPath, deleting elements and attributes that exist in both nodes
mergeappend => \%node - merge this node into the node at XMLPath, appending the values of text elements
note: This method uses the values retrieved from $self->tpp()->get('attr_prefix') and $self->tpp()->get('text_node_key') to define how to interpret how to identify attributes and text (CDATA) nodes.
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( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, insert => $value )
mergeadd( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, mergeadd => $value )
mergereplace( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, mergereplace => $value )
mergeappend( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, mergeappend => $value )
mergedelete( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, mergedelete => $value )
replace( XMLTree, XMLPath, $value )
This is the same as modify( XMLTree, XMLPath, replace => $value )
delete( XMLTree, XMLPath )
This is the same as modify( XMLTree, XMLPath, delete => undef )
#!/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>
Russell E Glaue, http://russ.glaue.org
XML::TreePP::Editor on Codepin: http://www.codepin.org/project/perlmod/XML-TreePP-Editor
Copyright (c) 2009-2013 Russell E Glaue, Center for the Application of Information Technologies, Western Illinois University. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install XML::TreePP::Editor, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::TreePP::Editor
CPAN shell
perl -MCPAN -e shell install XML::TreePP::Editor
For more information on module installation, please visit the detailed CPAN module installation guide.