Provided by: libterm-shellui-perl_0.92-2_all 
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 "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(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>