/ 
Term-Shell-MultiCmd-1.03
River stage zero No dependents
/ Term::Shell::MultiCmd

NAME

Term::Shell::MultiCmd - Nested Commands Tree in Shell Interface

VERSION

Version 1.03

SYNOPSIS

  # Examples are available with the distribution, under directory 'examples/'
  # This one is named examples/synopsis.pl

  use Term::Shell::MultiCmd;
  my @command_tree =
   ( 'multi word command' =>
           { help => "Help title.",
             opts => 'force repeat=i',
             exec => sub {
                 my ($o, %p) = @_ ;
                 print "$p{ARG0} was called with force=$p{force} and repeat=$p{repeat}\n"
             },
           },
     'multi word another command' =>
           { help => 'Another help title.
Help my have multi lines, the top one
would be used when one linear needed.',
             comp => sub {
                 # this function would be called when use hits tab completion at arguments
                 my ($o, $word, $line, $start, $op, $opts) = @_ ;
                 # .. do something, then
                 return qw/a list of completion words/ ;
             },
             exec => sub { my ($o, %p) = @_ ; print "$p{ARG0} was called\n"},
           },
     'multi word third command' =>
           { help => 'same idea',
             comp => [qw/a list of words/], # this is also possible
             exec => sub { my ($o, %p) = @_ ; print "$p{ARG0} was called. Isn't that fun?\n"},
           },
     'multi word' => 'You can add general help title to a path',
   ) ;

   Term::Shell::MultiCmd
    -> new()
    -> populate( @command_tree )
    -> loop ;

  print "All done, see you later\n" ;

NOTE

To get the most from a command line, it might be a good idea to get the latest versions of Term::ReadLine and Term::ReadKey. There are numberless ways of doing it, one of them is running 'cpan update Bundle::CPAN' (with a proper write permission).

SUBROUTINES/METHODS

new

 my $cli = new Term::Shell::MultiCmd ;
- or -
 my $cli = Term::Shell::MultiCmd->new( [optional parameters ...] ) ;

The parameters to the constructor are passed in hash form, preceding dash is optional.

Optional Parameters for the new command:

  • -prompt

    my $cli = Term::Shell::MultiCmd ( -prompt => 'myprompt> ') ;

    Overwrite the default prompt 'shell> '.

  • -help_cmd

    Overwrite the default 'help' command, empty string would skip adding this command.

  • -quit_cmd

    Overwrite the default 'quit' command, empty string would skip adding this command.

  • -history_file

    my $cli = Term::Shell::MultiCmd ( -history_file => "$ENV{HOME}/.my_progarms_data" ) ;

    This is the history file name. If present, try to load history from this file just before the loop command, and try saving history in this file after the loop command. Default is empty string (i.e. no history preserved between sessions). Please note that things might get tricky if that if multiple sessions are running at the same time.

  • -history_size

    Overwrite the default 100 history entries to save in hisotry_file (if exists).

  • -history_more

    If history_file exists, try to load this data from the file before the loop starts, and save it after. For Example:

    my %user_defaults ;
my $cli = new Term::Shell::MultiCmd ( -history_file => "$ENV{HOME}/.my_saved_data",
                                      -history_size => 200,
                                      -history_more => \%user_defaults,
                                     ) ;
# ....
$cli -> loop ;

    This would load shell's history and %user_defaults from the file .my_saved_data before the loop, and store 200 history entries and %user_defaults in the file after the loop.

    Note that the value of history_more must be a reference for HASH, ARRAY, or SCALAR. And no warnings would be provided if any of the operations fail. It wouldn't be a good idea to use it for sensitive data.

add_exec

$cli -> add_exec ( -path => 'full command path',
                   -exec => \&my_command,
                   -help => 'some help',
                   -opts => 'options',
                   -comp => \&my_completion_function,
                 ) ;

This is function adds an command item to the command tree. It is a little complicated, but useful (or so I hope).

  • -path

    Mandatory. Expecting a string. This string would be parsed as multi-words command.

    Note: by default, this module expects whitespaces delimiter. If you'll read the module's code, you can find an easy way to change it - in unlikely case you'll find it useful.

  • -exec

    Mandatory. Expecting a function ref. This code would be called when the user types a unique path for this command (with optional options and arguments). Parameters sent to this code are:

    my ($cli, %p) = @_ ;
#  where:
# $cli     - self object.
# $p{ARG0} - the command's full path (user might have used partial but unique path. This is the explicit path)
# $p{ARGV} - all user arguments, in order (ARRAY ref)
# %p       - contains other options (see 'opts' below)

  • -help

    Expecting a multi line string. The top line would be presented when a one line title is needed (for example, when 'help -tree' is called), the whole string would be presented as the full help for this item.

  • -comp

    Expecting CODE, or ARRAY ref. If Array, when user hits tab completion for this command, try to complete his input with words from this list. If Code, call this function with the next parameters:

    my ($cli, $word, $line, $start) = @_ ;
#  where:
# $cli is the Term::Shell::MultiCmd object.
# $word is the curent word
# $line is the whole line
# $start is the current location

    This code should return a list of strings. Term::ReadLine would display those words (unless a single one) and complete user's line to the longest common part. In other words - it would do what you expect.

    For more information, see Term::ReadLine.

  • -opts

    Expecting a string, or ARRAY ref. If a string, split it to words by whitespaces. Those words are parsed as standard Getopt::Long options. For example:

    -opts => 'force name=s flag=i@'

    Would populating the previously described %p hash, correspond to user command:

    shell> user command -name="Some String" -flag 2 -flag 3 -flag 4 -force

    For more information, see Getopt::Long. Also see examples/multi_option.pl in distribution.

    As ARRAY ref, caller can also add a complete 'instruction' after each non-flag option (i.e. an option that expects parameters). Like the 'comp' above, this 'instruction' must be an ARRAY or CODE ref, and follow the same roles. If omitted, a default function would be called and ask user for input. For example:

    -opts => [ 'verbose' =>
           'file=s'  => \&my_filename_completion,
           'level=i' => [qw/1 2 3 4/],
         ],

add_help

Although caller can set help via the add_exec, this command is useful when he wishes to add title (or hint) to a part of the command path. For example:

# assume $cli with commands 'feature set', 'feature get', etc.
$cli -> add_help ( -path => 'feature' ,
                   -help => 'This feature is about something') ;

populate

A convenient way to define a chain of add_exec and add_help commands. This function expects hash, where the key is the command path and the value might be HASH ref (calling add_exec), or a string (calling add_help). For example:

$cli -> populate
   ( 'feature' => 'This feature is a secret',
     'feature set' => { help => 'help for feature set',
                        exec => \&my_feature_set,
                        opts => 'level=i',
                        comp => \&my_feature_set_completion_function,
                      },
     'feature get' => { help => 'help for feature get',
                        exec => \&my_feature_get
                      },
   ) ;

# Note:
# - Since the key is the path, '-path' is omitted from parameters.
# - This function returns the self object, for easy chaining (as the synopsis demonstrates).

loop

$cli -> loop ;

Prompt, parse, and invoke in endless loop

('endless loop' should never be taken literally. Users quit, systems crash, universes collapse - and the loop reaches its last cycle)

cmd

$cli -> cmd ( "help -tree" ) ;

Execute the given string parameter, similarly to user input. This one might be useful to execute commands in a script, or testings.

history

set/get history

my @hist = $cli -> history() ;            # get history
$cli -> history( @alternative_history ) ; # set history
$cli -> history([@alternative_history]) ; # the very same, by ptr
$cli -> history([]) ;                     # clear history

ALSO SEE

Term::ReadLine, Term::ReadKey, Getopt::Long

AUTHOR

Josef Ezra, <jezra at sign cpan.org>

BUGS

Please report any bugs or feature requests to me, or to bug-term-cli at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Term-CLI. I am grateful for your feedback.

TODO list

nImplement pager.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Term::Shell::MultiCmd

You can also look for information at:

ACKNOWLEDGMENTS

This module was inspired by the excellent modules Term::Shell, CPAN, and CPANPLUS::Shell.

LICENSE AND COPYRIGHT

Copyright 2010 Josef Ezra.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.