The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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 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( '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 XMLPath

    • replace => \%node - replace the node at XMLPath with this new node

    • delete => undef - delete the node at the XMLPath

    • 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

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.