NAME¶
Term::ShellUI - A fully-featured shell-like command line environment
SYNOPSIS¶
use Term::ShellUI;
my $term = new Term::ShellUI(
commands => {
"cd" => {
desc => "Change to directory DIR",
maxargs => 1, args => sub { shift->complete_onlydirs(@_); },
proc => sub { chdir($_[0] || $ENV{HOME} || $ENV{LOGDIR}); },
},
"chdir" => { alias => 'cd' },
"pwd" => {
desc => "Print the current working directory",
maxargs => 0, proc => sub { system('pwd'); },
},
"quit" => {
desc => "Quit this program", maxargs => 0,
method => sub { shift->exit_requested(1); },
}},
history_file => '~/.shellui-synopsis-history',
);
print 'Using '.$term->{term}->ReadLine."\n";
$term->run();
DESCRIPTION¶
Term::ShellUI uses the history and autocompletion features of Term::ReadLine to
present a sophisticated command-line interface to the user. It tries to make
every feature that one would expect to see in a fully interactive shell
trivial to implement. You simply declare your command set and let ShellUI take
care of the heavy lifting.
This module was previously called Term::GDBUI.
COMMAND SET¶
A command set is the data structure that describes your application's entire
user interface. It's easiest to illustrate with a working example. We shall
implement the following 6 "COMMAND"s:
- help
- Prints the help for the given command. With no arguments,
prints a list and short summary of all available commands.
- h
- This is just a synonym for "help". We don't want
to list it in the possible completions. Of course, pressing
"h<tab><return>" will autocomplete to
"help" and then execute the help command. Including this command
allows you to simply type "h<return>".
The 'alias' directive used to be called 'syn' (for synonym). Either term
works.
- exists
- This command shows how to use the
"complete_files" routines to complete on file names, and how to
provide more comprehensive help.
- show
- Demonstrates subcommands (like GDB's show command). This
makes it easy to implement commands like "show warranty" and
"show args".
- show args
- This shows more advanced argument processing. First, it
uses cusom argument completion: a static completion for the first argument
(either "create" or "delete") and the standard file
completion for the second. When executed, it echoes its own command name
followed by its arguments.
- quit
- How to nicely quit. Term::ShellUI also follows
Term::ReadLine's default of quitting when Control-D is pressed.
This code is fairly comprehensive because it attempts to demonstrate most of
Term::ShellUI's many features. You can find a working version of this exact
code titled "synopsis" in the examples directory. For a more
real-world example, see the fileman-example in the same directory.
sub get_commands
{
return {
"help" => {
desc => "Print helpful information",
args => sub { shift->help_args(undef, @_); },
method => sub { shift->help_call(undef, @_); }
},
"h" => { alias => "help", exclude_from_completion=>1},
"exists" => {
desc => "List whether files exist",
args => sub { shift->complete_files(@_); },
proc => sub {
print "exists: " .
join(", ", map {-e($_) ? "<$_>":$_} @_) .
"\n";
},
doc => <<EOL,
Comprehensive documentation for our ls command.
If a file exists, it is printed in <angle brackets>.
The help can\nspan\nmany\nlines
EOL
},
"show" => {
desc => "An example of using subcommands",
cmds => {
"warranty" => { proc => "You have no warranty!\n" },
"args" => {
minargs => 2, maxargs => 2,
args => [ sub {qw(create delete)},
\&Term::ShellUI::complete_files ],
desc => "Demonstrate method calling",
method => sub {
my $self = shift;
my $parms = shift;
print $self->get_cname($parms->{cname}) .
": " . join(" ",@_), "\n";
},
},
},
},
"quit" => {
desc => "Quit using Fileman",
maxargs => 0,
method => sub { shift->exit_requested(1); }
},
"q" => { alias => 'quit', exclude_from_completion => 1 },
};
}
COMMAND¶
This data structure describes a single command implemented by your application.
"help", "exit", etc. All fields are optional. Commands are
passed to Term::ShellUI using a "COMMAND SET".
- desc
- A short, one-line description for the command. Normally
this is a simple string, but it may also be a subroutine that will be
called every time the description is printed. The subroutine takes two
arguments, $self (the Term::ShellUI object), and $cmd (the command hash
for the command), and returns the command's description as a string.
- doc
- A comprehensive, many-line description for the command.
Like desc, this is normally a string but if you store a reference to a
subroutine in this field, it will be called to calculate the
documentation. Your subroutine should accept three arguments: self (the
Term::ShellUI object), cmd (the command hash for the command), and the
command's name. It should return a string containing the command's
documentation. See examples/xmlexer to see how to read the doc for a
command out of the pod.
- minargs
- maxargs
- These set the minimum and maximum number of arguments that
this command will accept.
- proc
- This contains a reference to the subroutine that should be
executed when this command is called. Arguments are those passed on the
command line and the return value is the value returned by call_cmd and
process_a_cmd (i.e. it is ignored unless your application makes use of
it).
If this field is a string instead of a subroutine ref, the string is printed
when the command is executed (good for things like "Not implemented
yet"). Examples of both subroutine and string procs can be seen in
the example above.
- method
- Similar to proc, but passes more arguments. Where proc
simply passes the arguments for the command, method also passes the
Term::ShellUI object and the command's parms object (see
"call_cmd" for more on parms). Most commands can be implemented
entirely using a simple proc procedure, but sometimes they require
addtional information supplied to the method. Like proc, method may also
be a string.
- args
- This tells how to complete the command's arguments. It is
usually a subroutine. See "complete_files" for an reasonably
simple example, and the "complete" routine for a description of
the arguments and cmpl data structure.
Args can also be an arrayref. Each position in the array will be used as the
corresponding argument. See "show args" in get_commands above
for an example. The last argument is repeated indefinitely (see
"maxargs" for how to limit this).
Finally, args can also be a string. The string is intended to be a reminder
and is printed whenever the user types tab twice (i.e. "a number
between 0 and 65536"). It does not affect completion at all.
- cmds
- Command sets can be recursive. This allows a command to
have subcommands (like GDB's info and show commands, and the show command
in the example above). A command that has subcommands should only have two
fields: cmds (of course), and desc (briefly describe this collection of
subcommands). It may also implement doc, but ShellUI's default behavior of
printing a summary of the command's subcommands is usually sufficient. Any
other fields (args, method, maxargs, etc) will be taken from the
subcommand.
- exclude_from_completion
- If this field exists, then the command will be excluded
from command-line completion. This is useful for one-letter abbreviations,
such as "h"->"help": including "h" in the
completions just clutters up the screen.
- exclude_from_history
- If this field exists, the command will never be stored in
history. This is useful for commands like help and quit.
Default Command¶
If your command set includes a command named '' (the empty string), this
pseudo-command will be called any time the actual command cannot be found.
Here's an example:
'' => {
proc => "HA ha. No command here by that name\n",
desc => "HA ha. No help for unknown commands.",
doc => "Yet more taunting...\n",
},
Note that minargs and maxargs for the default command are ignored. method and
proc will be called no matter how many arguments the user entered.
CATEGORIES¶
Normally, when the user types 'help', she receives a short summary of all the
commands in the command set. However, if your application has 30 or more
commands, this can result in information overload. To manage this, you can
organize your commands into help categories
All help categories are assembled into a hash and passed to the the default
help_call and "help_args" methods. If you don't want to use help
categories, simply pass undef for the categories.
Here is an example of how to declare a collection of help categories:
my $helpcats = {
breakpoints => {
desc => "Commands to halt the program",
cmds => qw(break tbreak delete disable enable),
},
data => {
desc => "Commands to examine data",
cmds => ['info', 'show warranty', 'show args'],
}
};
"show warranty" and "show args" on the last line above are
examples of how to include subcommands in a help category: separate the
command and subcommands with whitespace.
CALLBACKS¶
Callbacks are functions supplied by ShellUI but intended to be called by your
application. They implement common functions like 'help' and 'history'.
- help_call(cats, parms, topic)
- Call this routine to implement your help routine. Pass the
help categories or undef, followed by the command-line arguments:
"help" => { desc => "Print helpful information",
args => sub { shift->help_args($helpcats, @_); },
method => sub { shift->help_call($helpcats, @_); } },
- help_args
- This provides argument completion for help commands. See
the example above for how to call it.
- complete_files
- Completes on filesystem objects (files, directories, etc).
Use either
args => sub { shift->complete_files(@_) },
or
args => \&complete_files,
Starts in the current directory.
- complete_onlyfiles
- Like "complete_files"" but excludes
directories, device nodes, etc. It returns regular files only.
- complete_onlydirs
- Like "complete_files"", but excludes files,
device nodes, etc. It returns only directories. It does return the
. and .. special directories so you'll need to remove those manually if
you don't want to see them:
args = sub { grep { !/^\.?\.$/ } complete_onlydirs(@_) },
- history_call
- You can use this callback to implement the standard bash
history command. This command supports:
NUM display last N history items
(displays all history if N is omitted)
-c clear all history
-d NUM delete an item from the history
Add it to your command set using something like this:
"history" => { desc => "Prints the command history",
doc => "Specify a number to list the last N lines of history" .
"Pass -c to clear the command history, " .
"-d NUM to delete a single item\n",
args => "[-c] [-d] [number]",
method => sub { shift->history_call(@_) },
},
METHODS¶
These are the routines that your application calls to create and use a
Term::ShellUI object. Usually you simply call
new() and then
run() -- everything else is handled automatically. You only need to
read this section if you wanted to do something out of the ordinary.
- new Term::ShellUI("named
args...")
- Creates a new ShellUI object.
It accepts the following named parameters:
- app
- The name of this application (will be passed to
"new" in Term::ReadLine). Defaults to $0, the name of the
current executable.
- term
- Usually Term::ShellUI uses its own Term::ReadLine object
(created with "new Term::ReadLine $args{'app'}"). However, if
you can create a new Term::ReadLine object yourself and supply it using
the term argument.
- blank_repeats_cmd
- This tells Term::ShellUI what to do when the user enters a
blank line. Pass 0 (the default) to have it do nothing (like Bash), or 1
to have it repeat the last command (like GDB).
- commands
- A hashref containing all the commands that ShellUI will
respond to. The format of this data structure can be found below in the
command set documentation. If you do not supply any commands to the
constructor, you must call the "commands" method to provide at
least a minimal command set before using many of the following calls. You
may add or delete commands or even change the entire command set at any
time.
- history_file
- If defined then the command history is saved to this file
on exit. It should probably specify a dotfile in the user's home
directory. Tilde expansion is performed, so something like
"~/.myprog-history" is perfectly acceptable.
- history_max = 500
- This tells how many items to save to the history file. The
default is 500.
Note that this parameter does not affect in-memory history. Term::ShellUI
makes no attemt to cull history so you're at the mercy of the default of
whatever ReadLine library you are using. See "StifleHistory" in
Term::ReadLine::Gnu for one way to change this.
- keep_quotes
- Normally all unescaped, unnecessary quote marks are
stripped. If you specify "keep_quotes=>1", however, they are
preserved. This is useful if your application uses quotes to delimit, say,
Perl-style strings.
- backslash_continues_command
- Normally commands don't respect backslash continuation. If
you pass backslash_continues_command=>1 to "new", then
whenever a line ends with a backslash, Term::ShellUI will continue
reading. The backslash is replaced with a space, so
$ abc \
> def
Will produce the command string 'abc def'.
- prompt
- This is the prompt that should be displayed for every
request. It can be changed at any time using the "prompt"
method. The default is <"$0 ">> (see app above).
If you specify a code reference, then the coderef is executed and its return
value is set as the prompt. Two arguments are passed to the coderef: the
Term::ShellUI object, and the raw command. The raw command is always
"" unless you're using command completion, where the raw command
is the command line entered so far.
For example, the following line sets the prompt to "## > "
where ## is the current number of history items.
$term->prompt(sub { $term->{term}->GetHistory() . " > " });
If you specify an arrayref, then the first item is the normal prompt and the
second item is the prompt when the command is being continued. For
instance, this would emulate Bash's behavior ($ is the normal prompt, but
> is the prompt when continuing).
$term->prompt(['$', '>']);
Of course, you specify backslash_continues_command=>1 to to
"new" to cause commands to continue.
And, of course, you can use an array of procs too.
$term->prompt([sub {'$'}, sub {'<'}]);
- token_chars
- This argument specifies the characters that should be
considered tokens all by themselves. For instance, if I pass
token_chars=>'=', then 'ab=123' would be parsed to ('ab', '=', '123').
Without token_chars, 'ab=123' remains a single string.
NOTE: you cannot change token_chars after the constructor has been called!
The regexps that use it are compiled once (m//o).
- display_summary_in_help
- Usually it's easier to have the command's summary (desc)
printed first, then follow it with the documentation (doc). However, if
the doc already contains its description (for instance, if you're reading
it from a podfile), you don't want the summary up there too. Pass 0 to
prevent printing the desc above the doc. Defaults to 1.
- process_a_cmd([cmd])
- Runs the specified command or prompts for it if no
arguments are supplied. Returns the result or undef if no command was
called.
- run()
- The main loop. Processes all commands until someone calls
"/"exit_requested(exitflag)"(true)".
If you pass arguments, they are joined and run once. For instance,
$term->run(@ARGV) allows your program to be run interactively or
noninteractively:
- myshell help
- Runs the help command and exits.
- myshell
- Invokes an interactive Term::ShellUI.
- prompt(newprompt)
- If supplied with an argument, this method sets the
command-line prompt. Returns the old prompt.
- commands(newcmds)
- If supplied with an argument, it sets the current command
set. This can be used to change the command set at any time. Returns the
old command set.
- add_commands(newcmds)
- Takes a command set as its first argument. Adds all the
commands in it the current command set. It silently replaces any commands
that have the same name.
- exit_requested(exitflag)
- If supplied with an argument, sets Term::ShellUI's finished
flag to the argument (1=exit, 0=don't exit). So, to get the interpreter to
exit at the end of processing the current command, call
"$self->exit_requested(1)". To cancel an exit request before
the command is finished, "$self->exit_requested(0)". Returns
the old state of the flag.
- add_eof_exit_hook(subroutine_reference)
- Call this method to add a subroutine as a hook into
Term::ShellUI's "exit on EOF" (Ctrl-D) functionality. When a
user enters Ctrl-D, Term::ShellUI will call each function in this hook
list, in order, and will exit only if all of them return 0. The first
function to return a non-zero value will stop further processing of these
hooks and prevent the program from exiting.
The return value of this method is the placement of the hook routine in the
hook list (1 is first) or 0 (zero) on failure.
- get_cname(cname)
- This is a tiny utility function that turns the cname (array
ref of names for this command as returned by "get_deep_command")
into a human-readable string. This function exists only to ensure that we
do this consistently.
OVERRIDES¶
These are routines that probably already do the right thing. If not, however,
they are designed to be overridden.
- blank_line()
- This routine is called when the user inputs a blank line.
It returns a string specifying the command to run or undef if nothing
should happen.
By default, ShellUI simply presents another command line. Pass
"blank_repeats_cmd=>1" to the constructor to get ShellUI to
repeat the previous command. Override this method to supply your own
behavior.
- error(msg)
- Called when an error occurrs. By default, the routine
simply prints the msg to stderr. Override it to change this behavior. It
takes any number of arguments, cocatenates them together and prints them
to stderr.
WRITING A COMPLETION ROUTINE¶
Term::ReadLine makes writing a completion routine a notoriously difficult task.
Term::ShellUI goes out of its way to make it as easy as possible. The best way
to write a completion routine is to start with one that already does something
similar to what you want (see the "CALLBACKS" section for the
completion routines that come with ShellUI).
Your routine returns an arrayref of possible completions, a string conaining a
short but helpful note, or undef if an error prevented any completions from
being generated. Return an empty array if there are simply no applicable
competions. Be careful; the distinction between no completions and an error
can be significant.
Your routine takes two arguments: a reference to the ShellUI object and cmpl, a
data structure that contains all the information you need to calculate the
completions. Set $term->{debug_complete}=5 to see the contents of cmpl:
- str
- The exact string that needs completion. Often, for simple
completions, you don't need anything more than this.
NOTE: str does not respect token_chars! It is supplied unchanged from
Readline and so uses whatever tokenizing it implements. Unfortunately, if
you've changed token_chars, this will often be different from how
Term::ShellUI would tokenize the same string.
- cset
- Command set for the deepest command found (see
"get_deep_command"). If no command was found then cset is set to
the topmost command set ($self-> commands()).
- cmd
- The command hash for deepest command found or undef if no
command was found (see "get_deep_command"). cset is the command
set that contains cmd.
- cname
- The full name of deepest command found as an array of
tokens (see "get_deep_command"). Use "get_cname" to
convert this into a human-readable string.
- args
- The arguments (as a list of tokens) that should be passed
to the command (see "get_deep_command"). Valid only if cmd is
non-null. Undef if no args were passed.
- argno
- The index of the argument (in args) containing the cursor.
If the user is trying to complete on the command name, then argno is
negative (because the cursor comes before the arguments).
- tokens
- The tokenized command-line.
- tokno
- The index of the token containing the cursor.
- tokoff
- The character offset of the cursor in the token.
For instance, if the cursor is on the first character of the third token,
tokno will be 2 and tokoff will be 0.
- twice
- True if user has hit tab twice in a row. This usually means
that you should print a message explaining the possible completions.
If you return your completions as a list, then $twice is handled for you
automatically. You could use it, for instance, to display an error message
(using completemsg) telling why no completions could be found.
- rawline
- The command line as a string, exactly as entered by the
user.
- rawstart
- The character position of the cursor in rawline.
The following are utility routines that your completion function can call.
- completemsg(msg)
- Allows your completion routine to print to the screen while
completing (i.e. to offer suggestions or print debugging info -- see
debug_complete). If it just blindly calls print, the prompt will be
corrupted and things will be confusing until the user redraws the screen
(probably by hitting Control-L).
$self->completemsg("You cannot complete here!\n");
Note that Term::ReadLine::Perl doesn't support this so the user will always
have to hit Control-L after printing. If your completion routine returns a
string rather than calling completemsg() then it should work
everywhere.
- suppress_completion_append_character()
- When the ReadLine library finds a unique match among the
list that you returned, it automatically appends a space. Normally this is
what you want (i.e. when completing a command name, in help, etc.)
However, if you're navigating the filesystem, this is definitely not
desirable (picture having to hit backspace after completing each
directory).
Your completion function needs to call this routine every time it runs if it
doesn't want a space automatically appended to the completions that it
returns.
- suppress_completion_escape()
- Normally everything returned by your completion routine is
escaped so that it doesn't get destroyed by shell metacharacter
interpretation (quotes, backslashes, etc). To avoid escaping twice
(disastrous), a completion routine that does its own escaping (perhaps
using Text::Shellwords::Cursorparse_escape) must call
suppress_completion_escape every time is called.
- force_to_string(cmpl, commmpletions, default_quote)
- If all the completions returned by your completion routine
should be enclosed in single or double quotes, call force_to_string on
them. You will most likely need this routine if keep_quotes is 1. This is
useful when completing a construct that you know must always be quoted.
force_to_string surrounds all completions with the quotes supplied by the
user or, if the user didn't supply any quotes, the quote passed in
default_quote. If the programmer didn't supply a default_quote and the
user didn't start the token with an open quote, then force_to_string won't
change anything.
Here's how to use it to force strings on two possible completions, aaa and
bbb. If the user doesn't supply any quotes, the completions will be
surrounded by double quotes.
args => sub { shift->force_to_string(@_,['aaa','bbb'],'"') },
Calling force_to_string escapes your completions (unless your callback calls
suppress_completion_escape itself), then calls suppress_completion_escape
to ensure the final quote isn't mangled.
INTERNALS¶
These commands are internal to ShellUI. They are documented here only for
completeness -- you should never need to call them.
- get_deep_command
- Looks up the supplied command line in a command hash.
Follows all synonyms and subcommands. Returns undef if the command could
not be found.
my($cset, $cmd, $cname, $args) =
$self->get_deep_command($self->commands(), $tokens);
This call takes two arguments:
- cset
- This is the command set to use. Pass
$self->commands() unless you know exactly what you're
doing.
- tokens
- This is the command line that the command should be read
from. It is a reference to an array that has already been split on
whitespace using Text::Shellwords::Cursor::parse_line.
and it returns a list of 4 values:
- 1.
- cset: the deepest command set found. Always returned.
- 2.
- cmd: the command hash for the command. Undef if no command
was found.
- 3.
- cname: the full name of the command. This is an array of
tokens, i.e. ('show', 'info'). Returns as deep as it could find commands
even if the final command was not found.
- 4.
- args: the command's arguments (all remaining tokens after
the command is found).
- get_cset_completions(cset)
- Returns a list of commands from the passed command set that
are suitable for completing.
- call_args
- Given a command set, does the correct thing at this stage
in the completion (a surprisingly nontrivial task thanks to ShellUI's
flexibility). Called by complete().
- complete
- This routine figures out the command set of the completion
routine that needs to be called, then calls call_args(). It is
called by completion_function.
You should override this routine if your application has custom completion
needs (like non-trivial tokenizing, where you'll need to modify the cmpl
data structure). If you override this routine, you will probably need to
override call_cmd as well.
- completion_function
- This is the entrypoint to the ReadLine completion callback.
It sets up a bunch of data, then calls complete to calculate the actual
completion.
To watch and debug the completion process, you can set
$self->{debug_complete} to 2 (print tokenizing), 3 (print tokenizing
and results) or 4 (print everything including the cmpl data structure).
Youu should never need to call or override this function. If you do (but,
trust me, you don't), set
$self->{term}->Attribs->{completion_function} to point to your
own routine.
See the Term::ReadLine documentation for a description of the
arguments.
- get_cmd_summary(tokens, cset)
- Prints a one-line summary for the given command. Uses
self-> commands() if cset is not specified.
- get_cmd_help(tokens, cset)
- Prints the full help text for the given command. Uses
self-> commands() if cset is not specified.
- get_category_summary(name, cats)
- Prints a one-line summary for the named category in the
category hash specified in cats.
- get_category_help(cat, cset)
- Returns a summary of the commands listed in cat. You must
pass the command set that contains those commands in cset.
- get_all_cmd_summaries(cset)
- Pass it a command set, and it will return a string
containing the summaries for each command in the set.
- load_history()
- If $self->{history_file} is set (see "new"),
this will load all history from that file. Called by run on startup. If
you don't use run, you will need to call this command manually.
- save_history()
- If $self->{history_file} is set (see "new"),
this will save all history to that file. Called by run on shutdown. If you
don't use run, you will need to call this command manually.
The history routines don't use ReadHistory and WriteHistory so they can be
used even if other ReadLine libs are being used. save_history requires
that the ReadLine lib supply a GetHistory call.
- call_command(parms)
- Executes a command and returns the result. It takes a
single argument: the parms data structure.
parms is a subset of the cmpl data structure (see the
"complete(cmpl)" in complete routine for more). Briefly, it
contains: cset, cmd, cname, args (see "get_deep_command"),
tokens and rawline (the tokenized and untokenized command lines). See
complete for full descriptions of these fields.
This call should be overridden if you have exotic command processing needs.
If you override this routine, you will probably need to override the
complete routine too.
LICENSE¶
Copyright (c) 2003-2011 Scott Bronson, all rights reserved. This program is free
software released under the MIT license.
AUTHORS¶
Scott Bronson <bronson@rinspin.com> Lester Hightower
<hightowe@cpan.org> Ryan Gies <ryan@livesite.net> Martin Kluge
<mk@elxsi.de>