View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Josef Ezra > Term-Shell-MultiCmd-3.01 > Term::Shell::MultiCmd



Annotate this POD

View/Report Bugs
Module Version: 3.01   Source  


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


    # Examples are available with the distribution, under directory 'examples/'
    # This one is named 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',
     ) ;

      -> new()
      -> populate( @command_tree )
      -> loop ;

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


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).



    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:


   $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).


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') ;


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).


  $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)


 $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.


 $cli -> command ( "help -tree") ;
Is the same as cmd, but echos the command before execution


  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


  my $prompt = $cli -> prompt() ;

accepts no parameters, return current prompt.


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


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


Josef Ezra, <jezra at sign>


Please report any bugs or feature requests to me, or to bug-term-cli at, or through the web interface at I am grateful for your feedback.

TODO list

nImplement pager.


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

    perldoc Term::Shell::MultiCmd

You can also look for information at:


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


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 for more information.

syntax highlighting: