The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Data-Leaf-Walker-0.01
River stage zero No dependents
/ Data::Leaf::Walker

NAME

Data::Leaf::Walker - Walk the leaves of arbitrarily deep nested data structures.

VERSION

Version 0.01

SYNOPSIS

   $data   = {
      a    => 'hash',
      or   => [ 'array', 'ref' ],
      with => { arbitrary => 'nesting' },
      };

   $walker = Data::Leaf::Walker->new( $data );
   
   while ( my ( $k, $v ) = $walker->each )
      {
      print "@{ $k } : $v\n";
      }
      
   ## output might be
   ## a : hash
   ## or 0 : array
   ## or 1 : ref
   ## with arbitrary : nesting

DESCRIPTION

Data::Leaf::Walker provides simplified access to nested data structures. It operates on key paths in place of keys. A key path is a list of HASH and ARRAY indexes which define a path through your data structure. For example, in the following data structure, the value corresponding to key path [ 0, 'foo' ] is 'bar':

   $aoh = [ { foo => 'bar' } ];

You can get and set that value like so:

   $walker = Data::Leaf::Walker->new( $aoh );      ## create the walker
   $bar    = $walker->fetch( [ 0, 'foo' ] );       ## get the value 'bar'
   $walker->store( [ 0, 'foo'], 'baz' );           ## change value to 'baz'

FUNCTIONS

new( $data )

Construct a new Data::Leaf::Walker instance.

   $data   = {
      a    => 'hash',
      or   => [ 'array', 'ref' ],
      with => { arbitrary => 'nesting' },
      };

   $walker = Data::Leaf::Walker->new( $data );

each()

Iterates over the leaf values of the nested HASH or ARRAY structures. Much like the built-in each %hash function, the iterators for individual structures are global and the caller should be careful about what state they are in. Invoking the keys() or values() methods will reset the iterators.

   while ( my ( $key_path, $value ) = $walker->each )
      {
      ## do something
      }

keys()

Returns the list of all key paths.

   @key_paths = $walker->keys;

values()

Returns the list of all leaf values.

   @leaf_values = $walker->values;

fetch( $key_path )

Lookup the value corresponding to the given key path. If an individual key attempts to fetch from an invalid the fetch method dies.

   $leaf = $walker->fetch( [ $key1, $index1, $index2, $key2 ] );

store( $key_path, $value )

Set the value for the corresponding key path.

   $walker->store( [ $key1, $index1, $index2, $key2 ], $value );

delete( $key_path )

Delete the leaf key in the corresponding key path. Only works for a HASH leaf, dies otherwise. Returns the deleted value.

   $walker->delete( [ $key1, $index1, $index2, $key2 ] );

exists( $key_path )

Returns true if the corresponding key path exists.

   $walker->exists( [ $key1, $index1, $index2, $key2 ] );

AUTHOR

Dan Boorstein, <danboo at cpan.org>

BUGS

Please report any bugs or feature requests to bug-Data-Leaf-Walker at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Leaf-Walker. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

PLANS

  • add max_depth, min_depth, type and twig limiters for each, keys, values

  • optional autovivification (Data::Peek, Scalar::Util, String::Numeric)

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Data::Leaf::Walker

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 Dan Boorstein.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.