John Nolan > Data-Walker-1.05 > Data::Walker

Download:
Data-Walker-1.05.tar.gz

Dependencies

Annotate this POD

Related Modules

Data::DRef
File::Find
Term::ReadLine
File::Find::Rule
Config::General
Data::Search
Data::Dumper
Data::Compare
more...
By perlmonks.org

CPAN RT

New  2
Open  0
View/Report Bugs
Module Version: 1.05   Source  

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!\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

CHANGES ^

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

syntax highlighting: