Term::CLI::Tutorial - tips, tricks, and examples for Term::CLI
version 0.04007
use Term::CLI;
This manual shows how to use Term::CLI to build a working CLI application with command-line editing capabilities, command history, command completion, and more.
For an introduction in the object class structure, see Term::CLI::Intro(3p).
If you have ever found yourself needing to write a command-line (shell-like) interface to your program, then Term::CLI may be for you.
Term::CLI provides a readline-based command line interface, including history, completion and input verification.
The most notable features are:
syntax checking, including option parsing
command, filename, and parameter completion
command and parameter abbreviation
command callbacks
Input syntax is specified by combining Term::CLI::Command and Term::CLI::Argument objects, together with Getopt::Long-like option specifications, and providing callback functions for command execution.
In the following sections, we will embark on the journey to building a simple shell with a few basic commands, but one that looks quite polished.
The tutorial directory in the module's source tree has source code for all examples (example_01_basic_repl.pl, example_02.pl, etc.), that progressively build the final application.
The Basically Simple SHell (BS Shell), is a command-line interpreter with a few simple commands:
Copy src to dst.
Print arguments to STDOUT and terminate with a newline.
Exit with code code (0 if not given).
See ls(1).
A silly command for illustration purposes.
Sleep for seconds seconds.
Do something during another activity.
Turn interface iface up or down.
That's it. Now, let's start building something.
The basic design of an interactive interface follows the well-established REPL (Read, Evaluate, Print, Loop) principle:
LOOP input = read_a_line output = evaluate_line( input ) print_result( output ) END-LOOP
Term::CLI provides a framework to make this happen:
use 5.014_001; use Term::CLI; my $term = Term::CLI->new( name => 'bssh', # A basically simple shell. ); say "\n[Welcome to BSSH]"; while (defined (my $line = $term->readline)) { $term->execute($line); } say "\nexit"; exit 0;
This example is pretty much non-functional, since the Term::CLI object is not aware of any command syntax yet: everything you type will result in an error, even empty lines and comments (i.e. lines starting with # as the first non-blank character).
#
bash$ perl tutorial/example_01_basic_repl.pl [Welcome to BSSH] ~> ERROR: missing command ~> # This is a comment! ERROR: unknown command '#' ~> exit ERROR: unknown command 'exit' ~> ^D -- exit
Let's first make sure that empty lines and comments are ignored. We could add a line to the while loop:
while
while (my $line = $term->readline) { next if /^\s*(?:#.*)?$/; # Skip comments and empty lines. $term->execute($line); }
But it's actually nicer to let Term::CLI handle this for us:
my $term = Term::CLI->new( name => 'bssh', # A basically simple shell. skip => qr/^\s*(?:#.*)?$/, # Skip comments and empty lines. );
Now we get:
bash$ perl tutorial/example_02_ignore_blank.pl [Welcome to BSSH] ~> ~> # This is a comment! ~> exit ERROR: unknown command 'exit' ~> ^D -- exit
The default prompt for Term::CLI is ~>. To change this, we can call the prompt method, or just specify it as an argument to the constructor:
~>
my $term = Term::CLI->new( name => 'bssh', # A basically simple shell. skip => qr/^\s*(?:#.*)?$/, # Skip comments and empty lines. prompt => 'bssh> ', # A more descriptive prompt. );
This gives us:
bash$ perl tutorial/example_03_setting_prompt.pl [Welcome to BSSH] bssh> bssh> # This is a comment! bssh> exit ERROR: unknown command 'exit' bssh> -- exit
Adding a command to a Term::CLI object is a matter of creating an array of Term::CLI::Command instances and passing it to the Term::CLI's add_command method.
add_command
my $term = Term::CLI->new( name => 'bssh', # A basically simple shell. skip => qr/^\s*(?:#.*)?$/, # Skip comments and empty lines. prompt => 'bssh> ', # A more descriptive prompt. ); $term->add_command, Term::CLI::Command->new( ... );
It is also possible to build the commands list inside the constructor call:
commands
my $term = Term::CLI->new( ... commands => [ Term::CLI::Command->new( ... ), ... ] );
However, the code quickly becomes unwieldy when a large number of commands and options are added.
You can also build a list first, and then call add_command:
my $term = Term::CLI->new( ... ); my @commands; push @commands, Term::CLI::Command->new( ... ); ... $term->add_command(@commands);
This is the method we'll use for this tutorial, and comes in handy further down the line.
So, now that we have the basic mechanism out of the way, let's add our first command, the highly useful exit.
exit
From THE BSSH CONCEPT section above:
exit [ code ]
This illustrates the use of a single, optional argument. Here's the code:
push @commands, Term::CLI::Command->new( name => 'exit', callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; execute_exit($cmd->name, @{$args{arguments}}); return %args; }, arguments => [ Term::CLI::Argument::Number::Int->new( # Integer name => 'excode', min => 0, # non-negative inclusive => 1, # "0" is allowed min_occur => 0, # occurrence is optional max_occur => 1, # no more than once ), ], );
Let's unpack that, shall we?
The Term::CLI::Command constructor takes three attributes:
The name of the command. This is a mandatory attribute.
The function to call when the command is executed.
A list of arguments that the command takes.
callback
The callback function is called when the command is executed.
callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; execute_exit($cmd->name, @{$args{arguments}}); return %args; },
In this case, we also have to define execute_exit:
execute_exit
sub execute_exit { my ($cmd, $excode) = @_; $excode //= 0; say "-- $cmd: $excode"; exit $excode; }
The callback function (see callback in Term::CLI::Role::CommandSet) is called with a reference to the command object that owns the callback, along with a number of (key, value) pairs. It is expected to return a similar structure (while possibly modifying the status and/or error values).
status
error
Since the callback function is called even in the face of parse errors, it is important to check the status flag. A negative value indicates a parse error, so we don't do anything in that case (the Term::CLI default callback will print the error for us).
The command arguments are found under the arguments key, as an ArrayRef of scalars. The exit code is the only (optional) argument, so that is found as the first element of the list: $args{arguments}->[0]. If it is not given, we default to 0.
arguments
$args{arguments}->[0]
0
The arguments attribute is an ArrayRef made up of Term::CLI::Argument instances, or more precisely, object classes derived from that. At this moment, we have a number of pre-defined sub-classes: Term::CLI::Argument::Enum, Term::CLI::Argument::Number::Float. Term::CLI::Argument::Number::Int, Term::CLI::Argument::Filename, Term::CLI::Argument::String. In our case, we need an optional, non-negative integer, so:
Term::CLI::Argument::Number::Int->new( # Integer name => 'excode', min => 0, # non-negative inclusive => 1, # "0" is allowed min_occur => 0, # occurrence is optional max_occur => 1, # no more than once ),
The inclusive and max_occur can be left out in this case, as their defaults are 1 anyway.
inclusive
max_occur
1
bash$ perl tutorial/example_04.pl [Welcome to BSSH] bssh> exit ok ERROR: arg#1, 'ok': not a valid number for excode bssh> exit 0 1 ERROR: arg#1, excode: too many arguments bssh> exit 2 -- exit: 2
Note that command abbreviation also works, i.e. you can type:
e ex exi exit
Before adding more commands to our application, it's perhaps a good moment to look at the built-in help features of Term::CLI.
By default, there is no help available in a Term::CLI application:
bss> help ERROR: unknown command 'help'
However, there is a special Term::CLI::Command::Help class (derived from Term::CLI::Command) that implements a help command, including command line completion:
help
push @commands, Term::CLI::Command::Help->new();
If you add this to the application, you'll get:
bash$ perl tutorial/example_05_add_help.pl [Welcome to BSSH] bssh> help Commands: exit [excode] help [cmd ...] show help bssh> help exit Usage: exit [excode] bssh> help h Usage: help [--pod] [-p] [cmd ...] Description: Show help for any given command sequence. The "--pod" option (or "-p") will cause raw POD to be shown.
Note that we don't have to specify the full command to get help on: command abbreviation works here as well (help h). Also, if you'd type help h, then hit the TAB key, it would autocomplete to help help.
help h
help help
The --pod option is handy if you want to copy the help text into a manual page:
--pod
bssh> help --pod help =head2 Usage: B<help> [B<--pod>] [B<-p>] [I<cmd> ...] =head2 Description: Show help for any given command sequence. The C<--pod> option (or C<-p>) will cause raw POD to be shown.
As you may have already seen, the help text for the exit command is rather sparse (unlike that of the help command itself): it only shows a "usage" line.
The Term::CLI::Command::Help class is smart enough to construct a usage line from the given command (including its options, parameters and sub-commands), but it cannot magically describe what a command is all about. You'll have to specify that yourself, using the summary and description attributes in the exit command definition:
summary
description
push @commands, Term::CLI::Command->new( name => 'exit', summary => 'exit B<bssh>', description => "Exit B<bssh> with code I<excode>,\n" ."or C<0> if no exit code is given.", callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; execute_exit($cmd->name, @{$args{arguments}}); return %args; }, arguments => [ Term::CLI::Argument::Number::Int->new( # Integer name => 'excode', min => 0, # non-negative inclusive => 1, # "0" is allowed min_occur => 0, # occurrence is optional max_occur => 1, # no more than once ), ], );
The summary text is what is displayed in the command summary, the description text is shown in the full help for the command:
bash $perl tutorial/example_06_add_help_text.pl [Welcome to BSSH] bssh> help Commands: exit [excode] exit bssh help [cmd ...] show help bssh> help exit Usage: exit [excode] Description: Exit bssh with code excode, or 0 if no exit code is given.
The help text is in POD format, translated for the screen using Pod::Text::Termcap(3p), and piped through an appropriate pager (see Term::CLI::Command::Help for more details).
The following examples will show various types and combination of arguments:
The echo command takes zero or more arbitrary string arguments (M6::CLI::Argument::String).
echo
The make command takes two string arguments, each from a set of pre-defined values. (M6::CLI::Argument::Enum).
make
The ls command demonstrates the use of file name arguments (M6::CLI::Argument::Filename).
ls
The cp command demonstrates how to set up a variable number of arguments (M6::CLI::Argument::Filename).
cp
The sleep command demonstrates a numerical argument (M6::CLI::Argument::Int).
sleep
Next up, the echo command. From THE BSSH CONCEPT section above:
echo [ arg ... ]
That is, the echo command takes zero or more arbitrary string arguments.
The implementation is straightforward:
push @commands, Term::CLI::Command->new( name => 'echo', summary => 'print arguments to F<stdout>', description => "The C<echo> command prints its arguments\n" . "to F<stdout>, separated by spaces, and\n" . "terminated by a newline.\n", arguments => [ Term::CLI::Argument::String->new( name => 'arg', occur => 0 ), ], callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; say "@{$args{arguments}}"; return %args; } );
However, the echo and exit commands both start with the same prefix (e), so let's see what happens with the abbreviations:
e
bash$ perl tutorial/example_07_echo_command.pl [Welcome to BSSH] bssh> e hello, world ERROR: ambiguous command 'e' (matches: echo exit) bssh> ec hello, world hello, world bssh> ex -- exit: 0
make {love|money} {now|later|never|forever}
Arguments with fixed set of values can be specified with Term::CLI::Argument::Enum objects:
push @commands, Term::CLI::Command->new( name => 'make', summary => 'make I<target> at time I<when>', description => "Make I<target> at time I<when>.\n" . "Possible values for I<target> are:\n" . "C<love>, C<money>.\n" . "Possible values for I<when> are:\n" . "C<now>, C<never>, C<later>, or C<forever>.", arguments => [ Term::CLI::Argument::Enum->new( name => 'target', value_list => [qw( love money)], ), Term::CLI::Argument::Enum->new( name => 'when', value_list => [qw( now later never forever )], ), ], callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; my @args = @{$args{arguments}}; say "making $args[0] $args[1]"; return %args; } );
The "enum" parameters support completion, as well as abbreviations. Thus, m m l will expand to make money later, and make l n will fail because n is ambiguous:
m m l
make money later
make l n
n
bash$ perl tutorial/example_08_make_command.pl [Welcome to BSSH] bssh> m m l making money later bssh> m l n ERROR: arg#2, 'n': ambiguous value (matches: now never) for when
m<TAB> make m l<TAB> m love m l l<TAB> m l later m l n<TAB> m l n m l n<TAB><TAB> (displays "never" and "now" as completions)
The ls command takes zero or more file name arguments. From THE BSSH CONCEPT section above:
ls [ path ... ]
The code for this:
push @commands, Term::CLI::Command->new( name => 'ls', summary => 'list file(s)', description => "List file(s) given by the arguments.\n" . "If no arguments are given, the command\n" . "will list the current directory.", arguments => [ Term::CLI::Argument::Filename->new( name => 'arg', occur => 0 ), ], callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; my @args = @{$args{arguments}}; system('ls', @args); $args{status} = $?; return %args; } );
Output should look like:
bash$ perl tutorial/example_07.pl [Welcome to BSSH] bssh> ls blib lib MANIFEST t Copying Makefile MYMETA.json Term-CLI-0.01.tar.gz cover_db Makefile.old MYMETA.yml TODO examples Makefile.PL pm_to_blib tutorial bssh> _
Options are passed directly to the ls(1) command. This is because we didn't specify any options in the command definition, so everything is assumed to be an argument, and the Term::CLI::Argument::Filename class is not particularly picky about the arguments it gets, juost so long as they are not empty:
bssh> ls -F lib/Term CLI/ CLI.pm bssh> _
ls t<TAB><TAB> (lists "t/" and "tutorial/" as completions) ls tu<TAB> ls tutorial ls tutorial e<TAB> ls tutorial examples
cp src-path ... dst-path
Ideally, we would like to specify this as:
Term::CLI::Command->new( name => 'cp', arguments => [ Term::CLI::Argument::Filename->new( name => 'src-path', min_occur => 1, max_occur => 0 ), Term::CLI::Argument::Filename->new( name => 'dst-path', min_occur => 1, max_occur => 1 ), ], ... )
Unfortunately, that will not work. Term::CLI::Command can work with a variable number of arguments, but only if that variable number is at the end of the list.
To see why this is the case, it is important to realise that Term::CLI parses an input line strictly from left to right, without any backtracking (which proper recursive descent parsers typically do). So, suppose you enter cp foo bar<TAB>. The completion code now has to decide what this bar is that needs to be completed. Since the first argument to cp can be one or more file names, this bar can be a src-path, but it can also be meant to be a dst-path. There is no way to tell for certain, so the code will be "greedy", in the sense that it will classify all arguments as src-path arguments.
cp foo bar<TAB>
bar
There's no way around this, except by using options, but that's a separate topic.
For now, there's no other way than to specify a single Term::CLI::Argument::Filename, with a minimum occurrence of 2, and no maximum. De distinction between src-path and dst-path needs to be made in the callback code.
push @commands, Term::CLI::Command->new( name => 'cp', summary => 'copy files', description => "Copy files. The last argument in the\n" . "list is the destination.\n", arguments => [ Term::CLI::Argument::Filename->new( name => 'path', min_occur => 2, max_occur => 0 ), ], callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; my @src = @{$args{arguments}}; my $dst = pop @src; say "command: ".$cmd->name; say "source: ".join(', ', @src); say "destination: ".$dst; return %args; } );
Example:
bash$ perl tutorial/example_10_cp_command.pl [Welcome to BSSH] bssh> cp ERROR: need at least 2 'path' arguments bssh> cp foo bar baz command: cp source: foo, bar destination: baz bssh> cp -r foo command: cp source: -r destination: foo bssh> ^D -- exit: 0
Note that this setup does not recognise options, so all options will be passed as regular arguments.
sleep seconds
This is an almost trivial implementation:
push @commands, Term::CLI::Command->new( name => 'sleep', summary => 'sleep for I<time> seconds', description => "Sleep for I<time> seconds.\n" . "Report the actual time spent sleeping.\n" . "This number can be smaller than I<time>\n" . "in case of an interruption (e.g. INT signal).", arguments => [ Term::CLI::Argument::Number::Int->new( name => 'time', min => 1, inclusive => 1 ), ], callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; my $time = $args{arguments}->[0]; say "-- sleep: $time"; my %oldsig = %::SIG; # Save signals; # Make sure we can interrupt the sleep() call. $::SIG{INT} = $::SIG{QUIT} = sub { say STDERR "(interrupted by $_[0])"; }; my $slept = sleep($time); %::SIG = %oldsig; # Restore signal handlers. say "-- woke up after $slept sec", $slept == 1 ? '' : 's'; return %args; } );
The Term::CLI::Argument::Number::Int allows us to set a minimum and maximum value (and whether or not the boundaries are included in the allowed range). Our time to sleep should obviously be a positive integer.
See it in action:
bash$ perl tutorial/example_11_sleep_command.pl [Welcome to BSSH] bssh> help sleep Usage: sleep time Description: Sleep for time seconds. Report the actual time spent sleeping. This number can be smaller than time in case of an interruption (e.g. INT signal). bssh> sleep 3 -- sleep: 3 -- woke up after 3 secs bssh> sleep 30 -- sleep: 30 ^C(interrupted by INT) -- woke up after 5 secs bssh> ^D -- exit: 0
You may have noticed that so far, we've only added commands with arguments. But what if we want to implement something like:
show { load|clock }
Well, as it turns out, Term::CLI::Command(3p) can handle that as well: instead of specifying arguments in the constructor, you can specify commands. Just like for Term::CLI, the commands attribute takes a reference to an array of Term::CLI::Command objects.
show
The code for the show command looks almost trivial:
push @commands, Term::CLI::Command->new( name => 'show', summary => 'show system properties', description => "Show some system-related information,\n" . "such as the system clock or load average.", commands => [ Term::CLI::Command->new( name => 'clock', summary => 'show system time', description => 'Show system time and date.', callback => sub { my ($self, %args) = @_; return %args if $args{status} < 0; say scalar(localtime); return %args; }, ), Term::CLI::Command->new( name => 'load', summary => 'show system load', description => 'Show system load averages.', callback => sub { my ($self, %args) = @_; return %args if $args{status} < 0; system('uptime'); $args{status} = $?; return %args; }, ), ], );
Adding this to our ever-growing bssh code, we get:
bssh
bash$ perl tutorial/example_12_show_command.pl [Welcome to BSSH] bssh> help show Usage: show {clock|load} Description: Show some system-related information, such as the system clock or load average. Sub-Commands: show clock show system time show load show system load bssh> show clock Wed Feb 21 14:21:56 2018 bssh> show load 14:21:59 up 1 day, 15:30, 1 user, load average: 0.19, 0.33, 0.40 bssh> ^D -- exit: 0
A Term::CLI::Command object can have both arguments and (sub-)commands as well. If this is the case, the parser expects the arguments before the sub-commands, and there can be no variable number of arguments.
This technique can be used to specify arguments that are common to sub-commands (the interface command), or to create syntactic sugar (the do command).
interface
do
The specification says:
do {something|nothing} while {working|sleeping}
Code:
push @commands, Term::CLI::Command->new( name => 'do', summary => 'Do I<action> while I<activity>', description => "Do I<action> while I<activity>.\n" . "Possible values for I<action> are:\n" . "C<nothing>, C<something>.\n" . "Possible values for I<activity> are:\n" . "C<sleeping>, C<working>.", arguments => [ Term::CLI::Argument::Enum->new( name => 'action', value_list => [qw( something nothing )], ), ], commands => [ Term::CLI::Command->new( name => 'while', arguments => [ Term::CLI::Argument::Enum->new( name => 'activity', value_list => [qw( eating sleeping )], ), ], ), ], callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; my @args = @{$args{arguments}}; say "doing $args[0] while $args[1]"; return %args; } );
interface iface {up|down}
The iface argument is used by both sub-commands.
push @commands, Term::CLI::Command->new( name => 'interface', summary => 'Turn I<iface> up or down', description => "Turn the I<iface> interface up or down.", arguments => [ Term::CLI::Argument::String->new( name => 'iface' ) ], commands => [ Term::CLI::Command->new( name => 'up', summary => 'Bring I<iface> up', description => 'Bring the I<iface> interface up.', callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; my @args = @{$args{arguments}}; say "bringing up $args[0]"; return %args; } ), Term::CLI::Command->new( name => 'down', summary => 'Shut down I<iface>', description => 'Shut down the I<iface> interface.', callback => sub { my ($cmd, %args) = @_; return %args if $args{status} < 0; my @args = @{$args{arguments}}; say "shutting down $args[0]"; return %args; } ), ], );
With the above two additions, we have:
bash$ perl tutorial/example_13_sub_cmd_and_args.pl [Welcome to BSSH] bssh> help Commands: cp path1 path2 ... copy files do action while activity do action while activity echo arg ... print arguments to stdout exit excode exit bssh help cmd ... show help interface iface {up|down} turn iface up or down ls arg ... list file(s) make target when make target at time when show {clock|load} show system properties sleep time sleep for time seconds bssh> do something wh s doing something while sleeping bssh> i eth0 u bringing up eth0 bssh> i eth0 d shutting down eth0 bssh> ^D -- exit: 0
debug
The fun thing of nesting commands is that we can easily implement this:
use Data::Dumper; push @commands, Term::CLI::Command->new( name => 'debug', usage => 'B<debug> I<cmd> ...', summary => 'debug commands', description => "Print some debugging information regarding\n" . "the execution of a command.", commands => [ @commands ], callback => sub { my ($cmd, %args) = @_; my @args = @{$args{arguments}}; say "# --- DEBUG ---"; my $d = Data::Dumper->new([\%args], [qw(args)]); print $d->Maxdepth(2)->Indent(1)->Terse(1)->Dump; say "# --- DEBUG ---"; return %args; } );
Here, we basically added a debug command that takes any other command structure as a sub-command and, after the sub-command has executed, will print some status information.
bash$ perl tutorial/example_10.pl [Welcome to BSSH] bssh> debug <TAB><TAB> cp echo exit ls make show sleep bssh> debug echo hi hi # --- DEBUG --- { 'error' => '', 'status' => 0, 'arguments' => [ 'hi' ], 'command_path' => [ 'Term::CLI=HASH(0x55e95ae02e20)', 'Term::CLI::Command=HASH(0x55e95b0c3998)', 'Term::CLI::Command=HASH(0x55e95b03f780)' ], 'options' => {} } # --- DEBUG --- bssh> exit -- exit: 0
Note the addition of the static usage line, because the autogenerated usage line is too long (it lists every possible sub-command):
usage
bash$ perl tutorial/example_14_debug_command.pl [Welcome to BSSH] bssh> help Commands: cp path1 path2 ... copy files debug cmd ... debug commands [...] bssh> help debug Usage: debug cmd ... Description: Print some debugging information regarding the execution of cmd. Sub-Commands: debug cp path1 path2 ... copy files debug do action while activity Do action while activity debug echo arg ... print arguments to stdout debug exit excode exit bssh debug help cmd ... show help debug interface iface {down|up} Turn iface up or down debug ls arg ... list file(s) debug make target when make target at time when debug show {clock|load} show system properties debug sleep time sleep for time seconds
parent
Note that this construction is not entirely without consequences, though: adding a Term::CLI::Command to another Term::CLI::Command or a Term::CLI object (or any object that consumes the Term::CLI::Role::CommandSet role) will cause the Term::CLI::Command object's parent attribute to be set.
At this moment, the parent attribute is only used to find the root_node, but this may change in the future.
To ensure the hierarchy still makes sense then, add the @commands to the debug command before adding them to the Term::CLI object.
@commands
And, yes, you can in principle do this:
my $debug = Term::CLI::Command->new( name => 'debug', ... ); push @commands, $debug; $debug->add_command(@commands); $term->add_command(@commands);
This would give you a debug command that can debug itself: debug debug debug ... (but why would you want that!?).
debug debug debug ...
You may have noticed that the output of the debug command above showed an options key that points to a HashRef. This contains valid command line options from the input. To have the parsing and completion code recognise command line options, simply pass an options parameter to the Term::CLI::Command constructor call:
options
push @commands, Term::CLI::Command->new( name => 'show', options => [ 'verbose|v' ], commands => [ Term::CLI::Command->new( name => 'clock', options => [ 'timezone|tz|t=s' ], callback => \&do_show_clock, ), Term::CLI::Command->new( name => 'load', callback => \&do_show_uptime, ), ], ); sub do_show_clock { my ($self, %args) = @_; return %args if $args{status} < 0; my $opt = $args{options}; local($::ENV{TZ}); if ($opt->{timezone}) { $::ENV{TZ} = $opt->{timezone}; } say scalar(localtime); return %args; } sub do_show_uptime { my ($self, %args) = @_; return %args if $args{status} < 0; system('uptime'); $args{status} = $?; return %args; }
The value should be an ArrayRef with the allowed options in Getopt::Long(3p) format. The Term::CLI code will turn on bundling (allow grouping of single letter options, i.e. -a nd -b can be written as -ab) and require_order (no mixing of options and arguments).
bundling
-a
-b
-ab
require_order
Above, we've added a --verbose option to the show command, and a specific --timezone option to the clock sub-command.
--verbose
--timezone
clock
The following commands should be allowed now:
bash$ perl tutorial/example_15_options.pl [Welcome to BSSH] bssh> help show clock Usage: show clock [--timezone=s] [--tz=s] [-ts] Description: Show system time and date. bssh> show clock Wed Feb 21 15:40:46 2018 bssh> show --verbose clock --tz=UTC Wed Feb 21 14:41:02 2018 bssh> show clock -t UTC Wed Feb 21 14:41:05 2018
However, the --verbose option cannot be specified after clock:
bssh> show clock --verbose --tz=UTC ERROR: Unknown option: verbose
Note, though, that the --verbose option after show is recorded in the options hash when do_show_clock is called:
do_show_clock
bssh> debug show --verbose clock --tz CET Tue Feb 21 14:41:45 2018 # --- DEBUG --- { 'options' => { 'verbose' => 1, 'timezone' => 'CET' }, 'error' => '', 'arguments' => [], 'command_path' => [ 'Term::CLI=HASH(0x55efdbf10bc8)', 'Term::CLI::Command=HASH(0x55efdc040a28)', 'Term::CLI::Command=HASH(0x55efdc040fe0)', 'Term::CLI::Command=HASH(0x55efdc041070)' ], 'status' => 0 } # --- DEBUG ---
If you want --verbose to be valid after clock, you'll need to specify it explicitly in its options:
Term::CLI::Command->new( name => 'clock', options => [ 'verbose|v', 'timezone|tz|t=s' ], ... ),
By default, the Term::CLI objects do not try to read or write to history files, so you will have to tell the application to do so explicitly. Fortunately, that's not hard:
$cli->read_history(); while (defined (my $l = $cli->readline)) { ... } $cli->write_history() or warn "cannot write history: ".$cli->error."\n";
(Note that we don't raise a warning if we cannot read the history file: you don't want to get a warning if you run the application for the first time.)
By default, if the application is named bssh, the history will be read/written to/from ~/.bssh_history, and Term::CLI will remember 1000 lines of input history.
~/.bssh_history
See the HISTORY CONTROL section in the Term::CLI documentation for more information on how to change the defaults.
Here are some examples of how you might go about it without Term::CLI. We've only decided to imlement a few of the simpler commands.
The "naive" implementation uses no fancy modules, just a loop reading from STDIN and some explicit if statements matching the commands:
if
use Modern::Perl; use Text::ParseWords qw( shellwords ); use Term::ReadLine; print "bssh> "; while (<>) { next if /^\s*(?:#.*)?$/; # Skip comments and empty lines. evaluate_input($_); } continue { print "bssh> "; } print "\n"; execute_exit('exit', 0); sub evaluate_input { my $cmd_line = shift; my @cmd_line = shellwords($cmd_line); if (!@cmd_line) { say STDERR "cannot parse input (unbalanced quote?)"; return; } return execute_cp(@cmd_line) if $cmd_line[0] eq 'cp'; return execute_echo(@cmd_line) if $cmd_line[0] eq 'echo'; return execute_exit(@cmd_line) if $cmd_line[0] eq 'exit'; return execute_ls(@cmd_line) if $cmd_line[0] eq 'ls'; return execute_make(@cmd_line) if $cmd_line[0] eq 'make'; return execute_sleep(@cmd_line) if $cmd_line[0] eq 'sleep'; say STDERR "unknown command: '$cmd_line[0]'"; } sub execute_cp { ... } sub execute_ls { ... } sub execute_echo { ... } sub execute_exit { ... } sub execute_sleep { ... } sub execute_make { my ($cmd, @args) = @_; if (@args != 2) { say STDERR "$cmd: need exactly two arguments"; return; } if ($args[0] !~ /^(love|money)$/) { say STDERR "$cmd: unknown target '$args[0]'"; return; } elsif ($args[1] !~ /^(now|later|never|forever)$/) { say STDERR "$cmd: unknown period '$args[0]'"; return; } say "making $args[0] $args[1]"; }
(This full script can be found in as examples/simple_cli.pl in the source distribution.)
This performs the basic actions, but does not offer anything else.
Replacing the REPL above by a Term::ReadLine(3p) construction, we get:
use Modern::Perl; use Text::ParseWords qw( shellwords ); use Term::ReadLine; my $term = Term::ReadLine->new('bssh'); while (defined(my $cmd_line = $term->readline('bssh> '))) { evaluate_input($_); } execute_exit('exit', 0);
(This script can be found as examples/readline_cli.pl in the source distribution.)
This adds a few nice features:
Input editing
History
But lacks some others:
Command line completion
By default Term::ReadLine performs file name completion, so e.g. the make command will show file name completions, not the valid targets.
It's possible to set up custom completion routines, but it's not trivial.
Command and parameter abbreviation
You can't write ex 0, or m l a.
ex 0
m l a
To support abbreviations, you'd have to add prefix matching in the evaluate_input and various execute_* routines, making sure to do something sensible with ambiguous prefixes (e.g. throwing an error). You'd have to do that for every sub-command/parameter, though.
evaluate_input
execute_*
Built-in help
Term::CLI::Intro(3p).
Getopt::Long(3p), Term::CLI(3p), Term::CLI::Argument(3p), Term::CLI::Argument::Enum(3p), Term::CLI::Argument::FileName(3p), Term::CLI::Argument::Number(3p), Term::CLI::Argument::Number::Float(3p), Term::CLI::Argument::Number::Int(3p), Term::CLI::Argument::String(3p), Term::CLI::Command(3p), Term::CLI::Role::CommandSet(3p), Term::ReadLine(3p).
The following files in the source distribution illustrate the examples above:
The "naive" implementation with a simple read loop.
The simple Term::ReadLine implementation that adds command line editing, filename completion, and command history.
The full-blown Term::CLI implementation with all of the features of tutorial/readline_cli.pl, adding all the goodness.
The tutorial code.
Steven Bakker <sbakker@cpan.org>
Copyright (c) 2018 Steven Bakker
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See "perldoc perlartistic."
This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
To install Term::CLI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Term::CLI
CPAN shell
perl -MCPAN -e shell install Term::CLI
For more information on module installation, please visit the detailed CPAN module installation guide.