The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

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.

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 location

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

complete

  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

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.