/ 
Data-Walker-0.15
River stage zero No dependents
/ Data::Walker

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 walk function.

use Data::Walker;
Data::Walker->walk( $data_structure );

You can customize certain features, like so:

use Data::Walker;
$Data::Walker::Config{'skipdoublerefs'} = 0;
Data::Walker->walk( $data_structure );

If you prefer to use object-style notation, then you can use this syntax to customize the settings:

use Data::Walker;
my $w1 = new Data::Walker;
$w1->walk( $data_structure );

my $w2 = new Data::Walker( 'skipdoublerefs' => 0 );
$w2->walk( $data_structure );

$w2->showrecursion(0);
$w2->walk( $data_structure );

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 <target>          like UNIX cd
ls                   like UNIX ls (also respects options -a, -l)
print <target>       prints the item as a scalar
dump <target>        invokes Data::Dumper
set <key> <value>    set configuration variables
show <key>           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.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.