NAME Data::Walker - A tool for navigating through Perl data structures SYNOPSIS use Data::Walker; Data::Walker->walk( $data_structure ); # see below for details DESCRIPTION This module allows you to "walk" an arbitrary Perl data structure in the same way that you can walk a directory tree from the command line. It is meant to be used interactively with a live user, as a command-line interface. INSTALLATION To install this package, just change to the directory which you created by untarring the package, and type the following: perl Makefile.PL make test make make install This will copy Walker.pm to your perl library directory for use by all perl scripts. You probably must be root to do this, unless you have installed a personal copy of perl or you have write access to a Perl lib directory. USAGE You open a command-line interface by invoking the cli() function. use Data::Walker; Data::Walker->cli( $data_structure ); use Data::Walker; Data::Walker->cli( $data_structure ); You can customize certain features, like so: use Data::Walker; $Data::Walker::Config{'skipdoublerefs'} = 0; Data::Walker->cli( $data_structure ); If you prefer to use object-style notation, then you can use this syntax to customize the settings. You can invoke the walk() method directly, our you can let the cli() method call walk() implicitly: use Data::Walker; my $w1 = new Data::Walker; $w1->walk( $data_structure ); $w1->cli; my $w2 = new Data::Walker; $w2->cli( $data_structure ); my $w3 = new Data::Walker( 'skipdoublerefs' => 0 ); $w3->walk( $data_structure ); $w3->cli(); $w3->showrecursion(0); $w3->cli(); Imagine a data structure like so: my $s = { a => [ 10, 20, "thirty" ], b => { "w" => "forty", "x" => "fifty", "y" => 60, "z" => \70, }, c => sub { print "I'm a data structure!\n"; }, d => 80, }; $s->{e} = \$s->{d}; Here is a sample interactive session examining this structure ('/>' is the prompt): /> /> ls -l a ARRAY (3) b HASH (4) c CODE d scalar 80 e SCALAR 80 /> cd a /->{a}> ls -al .. HASH (5) . ARRAY (3) 0 scalar 10 1 scalar 20 2 scalar 'thirty' /->{a}> cd ../b /->{b}> ls -al .. HASH (5) . HASH (4) w scalar 'forty' x scalar 'fifty' y scalar 60 z SCALAR 70 /->{b}> cd .. /> dump b dump--> 'b' $b = { 'x' => 'fifty', 'y' => 60, 'z' => \70, 'w' => 'forty' }; /> ls -al .. HASH (5) . HASH (5) a ARRAY (3) b HASH (4) c CODE d scalar 80 e SCALAR 80 /> ! $ref->{d} += 3 eval--> $ref->{d} += 3 83 /> ls -al .. HASH (5) . HASH (5) a ARRAY (3) b HASH (4) c CODE d scalar 83 e SCALAR 83 /> The following commands are available from within the CLI. With these commands, you can navigate around the data structure as if it were a directory tree. cd like UNIX cd ls like UNIX ls (also respects options -a, -l) print prints the item as a scalar dump invokes Data::Dumper set set configuration variables show show configuration variables ! or eval eval arbitrary perl (careful!) help this help message help set lists the available config variables For each session (or object) the following items can be configured: rootname (default: '/' ) displays the root node refname (default: 'ref' ) displays embedded refs scalarname (default: 'scalar') displays simple scalars undefname (default: 'undef' ) displays undefined scalars maxdepth (default: 1 ) maximum dump-depth (Data::Dumper) indent (default: 1 ) amount of indent (Data::Dumper) lscol1width (default: 15 ) column widths for 'ls' displays lscol2width (default: 25 ) column widths for 'ls' displays showrecursion (default: 1 ) note recursion in the prompt showids (default: 0 ) show ref id numbers in ls lists skipdoublerefs (default: 1 ) hop over ref-to-refs during walks skipwarning (default: 1 ) warn when hopping over ref-to-refs truncatescalars (default: 37 ) truncate scalars in 'ls' displays promptchar (default: '>') customize the session prompt arrowshaft (default: '-') ('-' in '->') arrowhead (default: '>') ('>' in '->') This is an alpha release of this module. CHANGES Version 0.16-0.17 The module is now fully object oriented. This will make it easier to use the module outside of the CLI. In the next version, I will completely separate out the CLI loop, command-parsing regexes, and the functions which implement the commands. After that, AUTOLOAD can be set up to parse any commands that the CLI can parse. This will make it more convenient to use the module from the perl debugger. NOTE: The walk() function has been separated into two functions, namely walk() and cli(). The usage instructions have changed. Please have a look. Version 0.15 Reorganized the installation tests. A few minor changes to the module itself. Version 0.13-0.14 Numerous internal changes: Moved functionality from the CLI-loop into distinct functions. Version 0.12 Blessed references to non-hashes are now handled correctly. Modified the output of "ls" commands (looks different). Added new options: showids, lscol2width, scalarname, undefname, skipwarning Numerous internal changes. Version 0.11 Fixed some misspellings in the help information. Modified the pretty-print format of scalars. Added some new comments to the source code. Various other small updates. AUTHOR John Nolan jpnolan@op.net August-December 1999. A copyright statment is contained within the source code itself.