NAME

XML::Simple::Tree - Tree object extension for XML::Simple data structures

SYNOPSIS

  ## script 1 
  ## create XML::Simple::Tree object and do a preorder traversal

  ## create XML::Simple::Tree object from an xml document ($xml_file) 
  my $xml_obj = XML::Simple::Tree->new(file => 'directory.xml',
                                       node_key => 'dir',
                                       target_key => 'name');

  ## sub set_do_node() method takes subroutine reference to be executed at current node
  $xml_obj->set_do_node(
    sub {
      my $self = $xml_obj;

      my $cnode = $self->get_cnode();
      my $level = $self->get_level();
      my $padding = '* ' x ($level + 1); 

      print "$padding$cnode->{name}[0]\n";
    }
  );

  ## sub set_do_leaf() method takes subroutine reference to be executed at leaf node
  $xml_obj->set_do_leaf(
      sub {
        my $self = $xml_obj;

        print "\n";
      }
    );

  ## Tree pre order traversal method that executes do_node() at each node and do_leaf() at each leaf
  $xml_obj->traverse();


  ## script 2
  ## find a node and retrieve a parameter.

  my $xml_obj = 
    XML::Simple::Tree->new( 
      file => $xml_file,
      node_key => 'directory',
      target_key => 'name'
    );

  my $want_node = $xmlObj->find_node($target_directory);
  my $mtime = $want_node->{mtime}[0];

  ## script 3 
  ## find a node and cut (remove) it from tree.

  my $cut_name = 'bin'; 

  my $mainXml =
    XML::Simple::Tree->new( file => $xml_file,
                            node_key => 'directory',
                            target_key => 'name');

  $mainXml->cut_node($cut_name);

  ## script 4 
  ## take XML::Simple::Tree object and paste it into a target node of another
  ## convert it back to xml

  my $target_dir = 'xxx';

  my $cut_tree = 
     XML::Simple::Tree->new(file => $cut_xml_file,
                            node_key => 'directory',
                            target_key => 'name');

  $config_tree->paste_node($target_dir, $cut_tree->get_cnode()->{directory}[0]);

  ## convert to xml
  my $xml = $config_tree->toXML();

  ## Additional examples can be found in the included tests.

DESCRIPTION

This module extends XML::Simple by taking the data structure returned by XML::Simple::XMLin($xml_file, forcearray => 1) and putting it in a class complete with tree manipulation and traversal methods. Important to know is that XMLin is called with the option ForceArray => 1. This option forces nested elements to be represented as arrays even when there is only one.

METHODS

new([file=>$xml_file | string => $xml_string], node_key=>$node_key, target_key=>$target_key); constructor returns an object of type XML::Simple::Tree with one of its data members being a reference to a XML::Simple datastructure.

required parameters

Either 'file' or 'string' must be supplied with 'file' taking precedence if both are provided.

• file - xml document filename
• string - xml document in string form
• node_key - xml element name which defines a node.
• target_key - name of xml element used as identifier field in find() operations.

find_node($name)

finds and returns node where $name matches 'target_node'

children( )

returns list of child node[s] of current node. Current node is defined in paramater 'cnode'

siblings( )

returns list of sibling nodes relative to current node ('cnode'). List includes current node. Once again current node is stored in 'cnode'. Simply iterates through children of 'pnode', parent node of cnode.!

cut_node($name)

finds and splices away specified node

move_node($name, $direction)

finds node specified by $name and swaps adjacent node (up -> -1, down -> +1) useful for reordering children

copy_node($name)

finds copies( dclone() ) and returns wanted node

paste_node($destination, $paste_node)

finds destination node and pastes (push()) paste_node in place

traverse( )

pre-order traversal which walks tree executing do_node() and do_leaf where appropriate

post_traversal( )

post-order traversal which walks tree executing do_node() and do_leaf where appropriate

set_do_node($sub_ref)

sets subroutine reference executed at each node

set_do_leaf($sub_ref)

sets subroutine reference executed at each leaf

is_leaf( )

returns true if current node has no children, and false otherwise.

toXML([$node_ref])

Returns XML representation of object instance tree. By default it returns XML for the root node (rnode). The default behavior can be overridden by supplying another node reference as an argument. This method is implemented as a wrapper method for XML::Simple::XMLout(), so any options for that subroutine should carry over. See XML::Simple documentation for more information.

Autoloaded accessors/mutators via Class::MethodMaker

Private methods

• _set_pnode($node_ref)

  sets parent node field

• _set_wnode($node_ref)

  sets wanted node field

• _set_cnode($node_ref)

  sets current node field

• _set_level($level)

  sets current level field

• _set_pos($pos)

  sets position of node in pnode

Public methods

• get_cnode( )

  gets current node field

• get_target_key

  gets target_key field

• get_node_key( )

  gets node_key field

• get_pnode( )

  gets parent node field

• get_rnode( )

  gets root node field

• get_level( )

  returns level field

• get_pos( )

  returns node position in pnode

• get_file( )

  returns xml filename. Field 'file' is set only if passed to new as new(file => $xmlfile)

• get_string( )

  returns xml in string form. Field 'string' is set only if passed to new as new(string => $xmlstr)

AUTHOR

Aaron Dancygier, <aaron@dancygier.com>

COPYRIGHT AND LICENSE

Copyright 2005 by Aaron Dancygier

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.