/ 
Data-Interactive-Inspect-0.07
River stage one • 1 direct dependent • 1 total dependent
/ Data::Interactive::Inspect

NAME

Data::Interactive::Inspect - Inspect and manipulate perl data structures interactively

SYNOPSIS

use Data::Interactive::Inspect;
my $data = foo(); # get a hash ref from somewhere

# new shell object, the simple way
my $shell = Data::Interactive::Inspect->new($data);

# or
my $shell = Data::Interactive::Inspect->new(
  struct      => $data,
  name        => 'verkehrswege',
  begin       => sub { .. },
  commit      => sub { .. },
  rollback    => sub { .. },
  serialize   => sub { .. },
  deserialize => sub { .. },
  editor      => 'emacs',
  more        => 'less'
);

$data = $shell->inspect(); # opens a shell and returns modified hash ref on quit

DESCRIPTION

This module provides an interactive shell which can be used to inspect and modify a perl data structure.

You can browse the structure like a directory, display the contents, add and remove items, whatever you like. It is possible to include complete perl data structures.

The module works with hash and array references.

METHODS

new

The new() function takes either one parameter (a reference to a hash or array) or a hash reference with parameters. The following parameters are supported:

struct

The hash or array reference to inspect.

name

Will be displayed on the prompt of the shell.

editor

By default Data::Interactive::Inspect opens vi if the user issues the edit command. Use this parameter to instruct it otherwise.

more

By default Data::Interactive::Inspect uses more to display data which doesn't fit the terminal window. Use this parameter to instruct it otherwise.

begin, commit, rollback

If your data is tied to some backend which supports transactions, you can provide functions to implement this. If all three are defined, the user can use transaction commands in the shell.

Look at DBM::Deep::Manager for an example implementation.

serialize, deserialize

By default Data::Interactive::Inspect uses YAML for serialization, which is used in the edit and dump commands. You can change this by assigning code refs to these parameters.

serialize will be called with the structure to be serialized as its sole parameter and is expected to return a string.

deserialize will be called with a string as parameter and is expected to return a structure.

inspect

The inspect method starts the shell. Ii does return if the user leaves it, otherwise it runs forever.

The shell runs on a terminal and with STDIN.

The interactive shell supports command line editing, history and completion (for commands and hash keys), if Term::ReadLine::GNU or Term::ReadLine::Perl is installed.

INTERACTIVE COMMANDS

DISPLAY COMMANDS

list

Lists the keys of the current level of the structure.

Shortcut: l.

show

Does nearly the same as list but also shows the content of the keys. If a key points to a structure (like a hash or an array), show whill not display anything of it, but instead indicate, that there'e more behind that key.

For arrays the array indices are displayed as well.

Shortcut: sh.

dump

Dumps out everything of the current level of the structure.

Shortcut: d.

get key | /regex/>

Displays the value of key. If you specify a regex, the values of all matching keys will be shown.

If the current structure is an array you can specify the array index as the parameter.

search regex | /<regex>

Search for regex through the current structure. Looks for keys an values.

Beware that this make take some time depending on the size of the structure.

enter key

You can use this command to enter a sub hash of the current hash. It works like browsing a directory structure. You can only enter keys which point to sub hashes.

Shortcuts: cd

If the key you want to enter doesn't collide with a command, then you can also just directly enter the key without 'enter' or 'cd' in front of it, eg:

my.db> list
subhash
my.db> subhash
my.db subhash> dump
my.db subhash> ..
my.db>^D

If the current structure is an array you can use the array index to enter a specific array item.

If you specify .. as parameter (or as its own command like in the example below), you go one level up and leave the current sub hash.

EDIT COMMANDS

set key value

Use the set command to add a new key or to modify the value of a key. value may be a valid perl structure, which you can use to create sub hashes or arrays. Example:

my.db> set users [ { name => 'max'}, { name => 'joe' } ]
ok
mydb> get users
users =>
{
  'name' => 'max'
},
{
  'name' => 'joe'
}

Please note that the set command overwrites existing values without asking.

edit key

You can edit a whole structure pointed at by key with the edit command. It opens an editor with the structure converted to YAML. Modify whatever you wish, save, and the structure will be saved to the database.

append key value

This command can be used to append a value to an array. As with the set command, value can be any valid perl structure.

If you are currently inside an array, leave the key parameter.

drop key

Delete a key.

Again, note that all commands are executed without further asking or warning!

If you are currently inside an array, the key parameter must be an array index.

pop key

Remove the last element of the array pointed at by key.

If you are currently inside an array, leave the key parameter.

shift key

Remove the first element of the array pointed at by key.

If you are currently inside an array, leave the key parameter.

TRANSACTION COMMANDS

Only available if transaction support has been enabled, see below.

begin

Start a transaction.

commit

Save all changes made since the transaction began.

rollback

Discard all changes of the transaction.

MISC COMMANDS

help

Display a short command help.

Shortcuts: h or ?.

CTRL-D

Quit the interactive shell

Shortcuts: quit.

LIMITATIONS

The data structure you are inspecting with Data::Interactive::Inspect may contain code refs. That's not a problem as long as you don't touch them.

Sample:

my $c = {
    opt => 'value',
    hook => sub { return 1; },
   };
my $shell = Data::Interactive::Inspect->new($c);
$shell->inspect();

Execute:

data@0x80140a468> dump
---
hook: !!perl/code '{ "DUMMY" }'
opt: value
data@0x80140a468> set hook blah
data@0x80140a468> edit hook

Both commands would destroy the code ref. The first one would just overwrite it while the other one would remove the code (in fact it remains a code ref but it will contain dummy code only).

TODO

Add some kind of select command

Example:

struct:

{
  users => [
             { login => 'max', uid => 1 },
             { login => 'leo', uid => 2 },
           ]
}

> select login from users where uid = 1

which should return 'max'.

(may require a real world parser)

Add some kind of schema support

Given the same structure as above:

> update users set uid = 4 where login = 'max'

AUTHOR

T.v.Dein <tlinden@cpan.org>

BUGS

Report bugs to http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data::Interactive::Inspect

COPYRIGHT

Copyright (c) 2015-2017 by T.v.Dein <tlinden@cpan.org>. All rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This is the manual page for Data::Interactive::Inspect Version 0.07.