data::walker(3)

NAME

Data::Walker - A tool for navigating through Perl data structures

SYNOPSIS

Without any explicit objects:
  use Data::Walker;
  Data::Walker->cli( $data_structure );
Object-style invocation:
  use Data::Walker;
  my $w = new Data::Walker;
  $w->walk( $data_structure );
  $w->ls("-al");
  $w->pwd;
  $w->cli;
Importing methods into the current package:
  use Data::Walker qw(:direct);
  walk $data_structure;
  ls "-al";
  pwd;
  cli;

DESCRIPTION

This module allows you to "walk" an arbitrary Perl data
structure in the same way that you can walk a directory
tree from a UNIX command line. It reuses familiar unix
commands (such as "ls", "cd", "pwd") and applies these to
data structures.

It has a command-line interface which behaves like a UNIX
shell. You can also use object-style sytax to invoke the
CLI commands from outside the CLI. Data::Walker objects
are encapsulated, so that you can hop into and out of a
CLI without losing state, and you can have several
Data::Walker objects pointing at different structures.

The main functions can also be imported and used directly
from within the Perl debugger's CLI.

INSTALLATION

To install this package, just into 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 );

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();

You can also import most of the functions directly into
the current package. This is especially useful from
within the debugger (see the example below).

use Data::Walker qw(:direct);
walk $data_structure;
ls "-al";
pwd;
cli;

When you use the :direct pragma and invoke the walk()
function, a Data::Walker object is implicitly created, and
is available as $Data::Walker::WALKER.

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!0; },
d => 80,
};
$s->{e} = ->{d};

Here is a sample CLI 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
/> ! $cur->{d} += 3
eval--> $cur->{d} += 3
retv--> 83
/> ls -al
.. HASH (5)
. HASH (5)
a ARRAY (3)
b HASH (4)
c CODE
d scalar 83
e SCALAR 83
/>

Below is a sample debugger session examining this struc
ture.

Note that the walk() function returns a reference to the
"cursor", which is itself a reference to whatever is the
"current directory," so to speak. The actual Data::Walker
object iself is managed implicitly, and is available as
$Data::Walker::WALKER. When you are finished, you can
undef this object directly, or use the unwalk() function, which does this for you. But if you saved a copy of the
cursor, then you will need to undef this on your own.

(violet) ~/perl/walker/Data-Walker-0.18 > perl -d

sample_db

Loading DB routines from perl5db.pl version 1.0401
Emacs support available.

Enter h or `h h' for help.

main::(sample:19): d => 80,

DB<1> n

main::(sample:22): $s->{e} = ->{d};

DB<1> n

main::(sample:30): 1;

DB<1> use Data::Walker qw(:direct)

DB<2> $cur = walk $s

DB<3> pwd

/

DB<4> ls

a b c d e

DB<5> lal

.. HASH (5)
. HASH (5)
a ARRAY (3)
b HASH (4)
c CODE
d scalar 80
e SCALAR 80

DB<6> cd a

/->{a}

DB<7> ll

0 scalar 10
1 scalar 20
2 scalar 'thirty'

DB<8> cd '../b'

/->{b}

DB<9> lal

.. HASH (5)
. HASH (4)
w scalar 'forty'
x scalar 'fifty'
y scalar 60
z SCALAR 70

DB<10> cd '..'

/

DB<11> dump b

dump--> 'b'
$b = {

'x' => 'fifty',
'y' => 60,
'z' => 70,
'w' => 'forty'

};

DB<12> ll

a ARRAY (3)
b HASH (4)
c CODE
d scalar 80
e SCALAR 80

DB<13> $$cur->{d} += 3

DB<14> ll

a ARRAY (3)
b HASH (4)
c CODE
d scalar 83
e SCALAR 83

DB<15>
DB<16> pwd

/

DB<17> cli

/> cd b
/->{b}> ls -l
w scalar 'forty'
x scalar 'fifty'
y scalar 60
z SCALAR 70
/->{b}> print y
60
/->{b}> print x
fifty
/->{b}> exit

DB<18> pwd

/->{b}

DB<19> ll

w scalar 'forty'
x scalar 'fifty'
y scalar 60
z SCALAR 70

DB<20> unwalk

DB<21> undef $cur

DB<22>

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 (care

ful!)
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 em

bedded refs
scalarname (default: 'scalar') displays sim

ple scalars
undefname (default: 'undef' ) displays un

defined 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 num

bers 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
autoprint (default: 1 ) print directory

after chdir when not in CLI

promptchar (default: '>') customize the

session prompt
arrowshaft (default: '-') ('-' in '->')
arrowhead (default: '>') ('>' in '->')

curname (default: 'cur' ) how to refer

to the cursor for evals
parname (default: 'par' ) how to refer

to the parent ref for evals

CHANGES

· Version 1.02-1.04

Minor changes to installer tests.

· Version 1.01

Minor changes to the documentation.
Added walker_http.pl, which is a library for

using
Data::Walker together with HTTP::Daemon to

view objects
with a Web browser. Two example scripts are

also included.

· Version 0.21

Minor changes to the documentation

· Version 0.19-0.20

Added new tests and updated the documentation.

· Version 0.18

Completely separated the CLI loop, command

parsing regexes,
and the functions which implement the com

mands. AUTOLOAD is now
set up to handle any commands that the CLI can

parse (except
for eval() ).

By using the :direct pragma, you can now im

port AUTOLOADed functions
into the current package, so that you can eas

ily invoke them
from the perl debugger.

· Version 0.16-0.17

The Data::Walker objects are now fully encap

sulated.

NOTE: The walk() function has been separated

into two functions,
namely walk() and cli(). The usage instruc

tions 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

Moved some functionality from the CLI-loop
into distinct functions.

· Version 0.12

Blessed references to non-hashes are now han

dled correctly.
Modified the output of "ls" commands (looks

different).
Added new options:

showids, lscol2width, scalarname, undef

name,
skipwarning

Numerous internal changes.

· Version 0.11

Fixed some misspellings in the help informa

tion.
Modified the pretty-print format of scalars.
Added some new comments to the source code.
Various other small updates.

THANKS

Thanks to Gurusamy Sarathy for writing Data::Dumper, and
to Dominique Dumont for writing Tk::ObjScanner.

Thanks to Matthew Persico for sending some ideas on how
this module might be useful in the debugger.

Thanks to Scott Lindsey for pointing out that this module
is useful for reading files created with the Storable mod
ule, and for sending a sample script to do this.

AUTHOR

John Nolan jpnolan@sonic.net 1999,2000. A copyright
statment is contained within the source code itself.

perl v5.8.0 2000-05-27 Data::Walker(3)