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

