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
Editor PHILOSOPHY
XML Node and Attribute Identification
The identification of XML document nodes for modification is handled by the XML::TreePP::XMLPath
module.
The idenfication of attributes in XML nodes is via the attr_prefix
property in the XML::TreePP
module.
The idenfication of XML text (or CDATA) nodes is via the text_node_key
property in the XML::TreePP
module.
Please review the XMLPath PHILOSOPHY section in it's POD for further information.
XML::TreePP::XMLPath
dependency on XML::TreePP
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.
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.
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 providing 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 ofXML::TreePP
. Or loads a new instance ofXML::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 ofXML::TreePP::XMLPath
. Or loads a new instance ofXML::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( 'property_name' ); # deletes the property property_name
$tppe->set( 'property_name' => 'val' ); # sets the value of property_name
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( 'property_name' );
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
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
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-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.