NAME
Term::Shell::MultiCmd - Nested Commands Tree in Shell Interface
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 = new Term::Shell::MultiCmd ( -prompt => 'myprompt') ; - or - my $cli = mew Term::Shell::MultiCmd ( -prompt => \&myprompt) ;Overwrite the default prompt 'shell'. Rules are:
If prompt is a CODE reference, call it in each loop cycle and display the results. if it ends with a non-word character, display it as is. Else, display it with the root-path (if exists) and '> ' characters.-help_cmd
Overwrite the default 'help' command, empty string would disable this command.
-quit_cmd
Overwrite the default 'quit' command, empty string would disable this command.
-root_cmd
my $cli = new Term::Shell::MultiCmd ( -root_cmd => 'root' ) ;This would enable the root command and set it to root.
Unlike 'quit' and 'help', the 'root' command is a little unexpected. Therefore it is disabled by default. I strongly recommend enabling this command when implementing a big, deep command tree. This allows the user rooting in a node, then referring to this node thereafter. After enabling, use 'help root' (or whatever names you've chosen) for usage manual.
-history_file
my $cli = new 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 an 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 the history_file exists, try to load this data from the file during initialization, and save it at loop end. 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.
-pager
As pager's value, this module would expect a string or a sub that returns a FileHandle. If the value is a string, it would be converted to:
sub { use FileHandle ; new FileHandle "| $value_of_pager" }When appropriate, the returned file handle would be selected before user's command execution, the old one would be restored afterward. The next example should work on most posix system:
my $cli = new Term::Shell::MultiCmd ( -pager => 'less -rX', ...The default pager's value is empty string, which means no pager manipulations.
-pager_re
Taking after perldb, the default value is '^\|' (i.e. a regular expression that matches '|' prefix, as in the user's command "| help"). If the value is set to an empty string, every command would trigger the pager.
The next example would print any output to a given filehandle:
my $ret_value ; my $cli = new Term::Shell::MultiCmd ( -pager => sub { open my $fh, '>', \$ret_value or die "can't open FileHandle to string (no PerlIO?)\n" ; $fh }, -pager_re => '', ) ; # ... $cli -> cmd ('help -t') ; print "ret_value is:\n $ret_value" ;-record_cmd
If it's a function ref, call it with an echo of the user's command
my $cli = new Term::Shell::MultiCmd ( -record_cmd => sub { my $user_cmd = shift; system "echo '$user_cmd' >> /tmp/history" } ) ;-empty_cmd
Function ref only, call it when user hits 'Return' with no command or args (not even spaces)
my $cli = new Term::Shell::MultiCmd ( -empty_cmd => sub { # Assuming some commands are recorded in $last_repeatable_cmd if ( $last_repeatable_cmd ) { # repeat it } } ) ;
add_exec
$cli -> add_exec ( -path => 'full command path',
-exec => \&my_command,
-help => 'some help',
-opts => 'options',
-comp => \&my_completion_function,
) ;This 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, or HASH ref. If Array, when the user hits tab completion for this command, try to complete his input with words from this list. If Hash, using the hash keys as array, following the rule above. 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 locationThis code should return a list of strings. Term::ReadLine would complete user's line to the longest common part, and display the list (unless unique). 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@'This would populating the previously described %p hash, correspond to user command:
shell> user command -name="Some String" -flag 2 -flag 3 -flag 4 -forceFor 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. When omitted, a default function would be called and ask the user for input. For example:
-opts => [ 'verbose' => 'file=s' => \&my_filename_completion, 'level=i' => [qw/1 2 3 4/], 'type=s' => \%my_hash_of_types, ],
add_help
Although help string can set in 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 an 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 testing.
command
$cli -> command ( "help -tree") ;
Is the same as cmd, but echos the command before executioncomplete
my ($base_line, @word_list) = $cli -> complete ($a_line) ;given a line, this function would return a base line (i.e. truncated to the beginning of the last word), and a list of potential completions. Added to the 'cmd' command, this might be useful when module user implements his own 'loop' command in a non-terminal application
prompt
my $prompt = $cli -> prompt() ;accepts no parameters, return current prompt.
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 historyALSO 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::MultiCmdYou can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
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.