Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Term::ShellUI(3)      User Contributed Perl Documentation     Term::ShellUI(3)

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>

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 866:
	   alternative text '/"exit_requested(exitflag)"' contains non-escaped
	   | or	/

perl v5.32.1			  2012-02-03		      Term::ShellUI(3)

NAME | SYNOPSIS | DESCRIPTION | COMMAND SET | COMMAND | CATEGORIES | CALLBACKS | METHODS | OVERRIDES | WRITING A COMPLETION ROUTINE | INTERNALS | LICENSE | AUTHORS | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Term::ShellUI&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help