README file for Data::Walker 0.20


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 exported 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!\n"; },
           d => 80,
           };
           $s->{e} = \$s->{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 structure.

   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}      = \$s->{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 (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
           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

   This is an alpha release of this module.

CHANGES
   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 commands.  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 import AUTOLOADed functions
           into the current package, so that you can easily invoke them
           from the perl debugger.

   Version 0.16-0.17

           The Data::Walker objects are now fully encapsulated.

           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

           Moved some 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.

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

AUTHOR
   John Nolan [email protected] August, 1999 - January 2000. A copyright
   statment is contained within the source code itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.