NAME
Term::Shell::MultiCmd - Shell Interface with nested commands tree
VERSION
Version 1.02
SYNOPSIS
# More examples available with the distribution, under directory 'examples/'
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> ') ;
Set prompt to myprompt> (including the bigger than sign). Default is '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
This is the history file name. If present, try to load history from this file at the 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).
-history_size
If history_file exists, set the number of history items to preserve. Default is 100.
-history_more
If history_file exists, try to load this data from the file before the loop, and try 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.Please note: - The value of history_more must be a reference for HASH, ARRAY, or SCALAR - No warnings would be provided if any of the operations fail. Use it on your own risk.
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. Its options are complected, 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. but this is the full explicit one) $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's man page.
-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
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/], ],
For more information, see Getopt::Long's man page. Also see examples/multi_option.pl in distribution.
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 a secret') ;
populate
A is 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' can (and should) be omitted from add_exec parameters.
loop
$cli -> loop ;Prompt, parse, and invoke in endless loop
('endless' shouldn't be taken literally. Eventually user quits, or system crashes, or universe collapses - They always do.)
cmd
$cli -> cmd ( "help -tree" ) ;Execute the given string parameter, similarly to user input.
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.
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.