1Term::ShellUI(3)      User Contributed Perl Documentation     Term::ShellUI(3)
2
3
4

NAME

6       Term::ShellUI - A fully-featured shell-like command line environment
7

SYNOPSIS

9         use Term::ShellUI;
10         my $term = new Term::ShellUI(
11             commands => {
12                     "cd" => {
13                         desc => "Change to directory DIR",
14                         maxargs => 1, args => sub { shift->complete_onlydirs(@_); },
15                         proc => sub { chdir($_[0] || $ENV{HOME} || $ENV{LOGDIR}); },
16                     },
17                     "chdir" => { alias => 'cd' },
18                     "pwd" => {
19                         desc => "Print the current working directory",
20                         maxargs => 0, proc => sub { system('pwd'); },
21                     },
22                     "quit" => {
23                         desc => "Quit this program", maxargs => 0,
24                         method => sub { shift->exit_requested(1); },
25                     }},
26                 history_file => '~/.shellui-synopsis-history',
27             );
28         print 'Using '.$term->{term}->ReadLine."\n";
29         $term->run();
30

DESCRIPTION

32       Term::ShellUI uses the history and autocompletion features of
33       Term::ReadLine to present a sophisticated command-line interface to the
34       user.  It tries to make every feature that one would expect to see in a
35       fully interactive shell trivial to implement.  You simply declare your
36       command set and let ShellUI take care of the heavy lifting.
37
38       This module was previously called Term::GDBUI.
39

COMMAND SET

41       A command set is the data structure that describes your application's
42       entire user interface.  It's easiest to illustrate with a working
43       example.  We shall implement the following 6 "COMMAND"s:
44
45       help
46           Prints the help for the given command.  With no arguments, prints a
47           list and short summary of all available commands.
48
49       h   This is just a synonym for "help".  We don't want to list it in the
50           possible completions.  Of course, pressing "h<tab><return>" will
51           autocomplete to "help" and then execute the help command.
52           Including this command allows you to simply type "h<return>".
53
54           The 'alias' directive used to be called 'syn' (for synonym).
55           Either term works.
56
57       exists
58           This command shows how to use the "complete_files" routines to
59           complete on file names, and how to provide more comprehensive help.
60
61       show
62           Demonstrates subcommands (like GDB's show command).  This makes it
63           easy to implement commands like "show warranty" and "show args".
64
65       show args
66           This shows more advanced argument processing.  First, it uses cusom
67           argument completion: a static completion for the first argument
68           (either "create" or "delete") and the standard file completion for
69           the second.  When executed, it echoes its own command name followed
70           by its arguments.
71
72       quit
73           How to nicely quit.  Term::ShellUI also follows Term::ReadLine's
74           default of quitting when Control-D is pressed.
75
76       This code is fairly comprehensive because it attempts to demonstrate
77       most of Term::ShellUI's many features.  You can find a working version
78       of this exact code titled "synopsis" in the examples directory.  For a
79       more real-world example, see the fileman-example in the same directory.
80
81        sub get_commands
82        {
83            return {
84                "help" => {
85                    desc => "Print helpful information",
86                    args => sub { shift->help_args(undef, @_); },
87                    method => sub { shift->help_call(undef, @_); }
88                },
89                "h" =>      { alias => "help", exclude_from_completion=>1},
90                "exists" => {
91                    desc => "List whether files exist",
92                    args => sub { shift->complete_files(@_); },
93                    proc => sub {
94                        print "exists: " .
95                            join(", ", map {-e($_) ? "<$_>":$_} @_) .
96                            "\n";
97                    },
98                    doc => <<EOL,
99        Comprehensive documentation for our ls command.
100        If a file exists, it is printed in <angle brackets>.
101        The help can\nspan\nmany\nlines
102        EOL
103                },
104                "show" => {
105                    desc => "An example of using subcommands",
106                    cmds => {
107                        "warranty" => { proc => "You have no warranty!\n" },
108                        "args" => {
109                            minargs => 2, maxargs => 2,
110                            args => [ sub {qw(create delete)},
111                                      \&Term::ShellUI::complete_files ],
112                            desc => "Demonstrate method calling",
113                            method => sub {
114                                my $self = shift;
115                                my $parms = shift;
116                                print $self->get_cname($parms->{cname}) .
117                                    ": " . join(" ",@_), "\n";
118                            },
119                        },
120                    },
121                },
122                "quit" => {
123                    desc => "Quit using Fileman",
124                    maxargs => 0,
125                    method => sub { shift->exit_requested(1); }
126                },
127                "q" => { alias => 'quit', exclude_from_completion => 1 },
128            };
129        }
130

COMMAND

132       This data structure describes a single command implemented by your
133       application.  "help", "exit", etc.  All fields are optional.  Commands
134       are passed to Term::ShellUI using a "COMMAND SET".
135
136       desc
137           A short, one-line description for the command.  Normally this is a
138           simple string, but it may also be a subroutine that will be called
139           every time the description is printed.  The subroutine takes two
140           arguments, $self (the Term::ShellUI object), and $cmd (the command
141           hash for the command), and returns the command's description as a
142           string.
143
144       doc A comprehensive, many-line description for the command.  Like desc,
145           this is normally a string but if you store a reference to a
146           subroutine in this field, it will be called to calculate the
147           documentation.  Your subroutine should accept three arguments: self
148           (the Term::ShellUI object), cmd (the command hash for the command),
149           and the command's name.  It should return a string containing the
150           command's documentation.  See examples/xmlexer to see how to read
151           the doc for a command out of the pod.
152
153       minargs
154       maxargs
155           These set the minimum and maximum number of arguments that this
156           command will accept.
157
158       proc
159           This contains a reference to the subroutine that should be executed
160           when this command is called.  Arguments are those passed on the
161           command line and the return value is the value returned by call_cmd
162           and process_a_cmd (i.e. it is ignored unless your application makes
163           use of it).
164
165           If this field is a string instead of a subroutine ref, the string
166           is printed when the command is executed (good for things like "Not
167           implemented yet").  Examples of both subroutine and string procs
168           can be seen in the example above.
169
170       method
171           Similar to proc, but passes more arguments.  Where proc simply
172           passes the arguments for the command, method also passes the
173           Term::ShellUI object and the command's parms object (see "call_cmd"
174           for more on parms).  Most commands can be implemented entirely
175           using a simple proc procedure, but sometimes they require addtional
176           information supplied to the method.  Like proc, method may also be
177           a string.
178
179       args
180           This tells how to complete the command's arguments.  It is usually
181           a subroutine.  See "complete_files" for an reasonably simple
182           example, and the "complete" routine for a description of the
183           arguments and cmpl data structure.
184
185           Args can also be an arrayref.  Each position in the array will be
186           used as the corresponding argument.  See "show args" in
187           get_commands above for an example.  The last argument is repeated
188           indefinitely (see "maxargs" for how to limit this).
189
190           Finally, args can also be a string.  The string is intended to be a
191           reminder and is printed whenever the user types tab twice (i.e. "a
192           number between 0 and 65536").  It does not affect completion at
193           all.
194
195       cmds
196           Command sets can be recursive.  This allows a command to have
197           subcommands (like GDB's info and show commands, and the show
198           command in the example above).  A command that has subcommands
199           should only have two fields: cmds (of course), and desc (briefly
200           describe this collection of subcommands).  It may also implement
201           doc, but ShellUI's default behavior of printing a summary of the
202           command's subcommands is usually sufficient.  Any other fields
203           (args, method, maxargs, etc) will be taken from the subcommand.
204
205       exclude_from_completion
206           If this field exists, then the command will be excluded from
207           command-line completion.  This is useful for one-letter
208           abbreviations, such as "h"->"help": including "h" in the
209           completions just clutters up the screen.
210
211       exclude_from_history
212           If this field exists, the command will never be stored in history.
213           This is useful for commands like help and quit.
214
215   Default Command
216       If your command set includes a command named '' (the empty string),
217       this pseudo-command will be called any time the actual command cannot
218       be found.  Here's an example:
219
220         '' => {
221           proc => "HA ha.  No command here by that name\n",
222           desc => "HA ha.  No help for unknown commands.",
223           doc => "Yet more taunting...\n",
224         },
225
226       Note that minargs and maxargs for the default command are ignored.
227       method and proc will be called no matter how many arguments the user
228       entered.
229

CATEGORIES

231       Normally, when the user types 'help', she receives a short summary of
232       all the commands in the command set.  However, if your application has
233       30 or more commands, this can result in information overload.  To
234       manage this, you can organize your commands into help categories
235
236       All help categories are assembled into a hash and passed to the the
237       default help_call and "help_args" methods.  If you don't want to use
238       help categories, simply pass undef for the categories.
239
240       Here is an example of how to declare a collection of help categories:
241
242         my $helpcats = {
243             breakpoints => {
244                 desc => "Commands to halt the program",
245                 cmds => qw(break tbreak delete disable enable),
246             },
247             data => {
248                 desc => "Commands to examine data",
249                 cmds => ['info', 'show warranty', 'show args'],
250             }
251         };
252
253       "show warranty" and "show args" on the last line above are examples of
254       how to include subcommands in a help category: separate the command and
255       subcommands with whitespace.
256

CALLBACKS

258       Callbacks are functions supplied by ShellUI but intended to be called
259       by your application.  They implement common functions like 'help' and
260       'history'.
261
262       help_call(cats, parms, topic)
263           Call this routine to implement your help routine.  Pass the help
264           categories or undef, followed by the command-line arguments:
265
266             "help" =>   { desc => "Print helpful information",
267                           args => sub { shift->help_args($helpcats, @_); },
268                           method => sub { shift->help_call($helpcats, @_); } },
269
270       help_args
271           This provides argument completion for help commands.  See the
272           example above for how to call it.
273
274       complete_files
275           Completes on filesystem objects (files, directories, etc).  Use
276           either
277
278             args => sub { shift->complete_files(@_) },
279
280           or
281
282             args => \&complete_files,
283
284           Starts in the current directory.
285
286       complete_onlyfiles
287           Like "complete_files"" but excludes directories, device nodes, etc.
288           It returns regular files only.
289
290       complete_onlydirs
291           Like "complete_files"", but excludes files, device nodes, etc.  It
292           returns only directories.  It does return the . and .. special
293           directories so you'll need to remove those manually if you don't
294           want to see them:
295
296             args = sub { grep { !/^\.?\.$/ } complete_onlydirs(@_) },
297
298       history_call
299           You can use this callback to implement the standard bash history
300           command.  This command supports:
301
302               NUM       display last N history items
303                         (displays all history if N is omitted)
304               -c        clear all history
305               -d NUM    delete an item from the history
306
307           Add it to your command set using something like this:
308
309             "history" => { desc => "Prints the command history",
310                doc => "Specify a number to list the last N lines of history" .
311                       "Pass -c to clear the command history, " .
312                       "-d NUM to delete a single item\n",
313                args => "[-c] [-d] [number]",
314                method => sub { shift->history_call(@_) },
315             },
316

METHODS

318       These are the routines that your application calls to create and use a
319       Term::ShellUI object.  Usually you simply call new() and then run() --
320       everything else is handled automatically.  You only need to read this
321       section if you wanted to do something out of the ordinary.
322
323       new Term::ShellUI("named args...")
324           Creates a new ShellUI object.
325
326           It accepts the following named parameters:
327
328           app
329              The name of this application (will be passed to "new" in
330              Term::ReadLine).  Defaults to $0, the name of the current
331              executable.
332
333           term
334              Usually Term::ShellUI uses its own Term::ReadLine object
335              (created with "new Term::ReadLine $args{'app'}").  However, if
336              you can create a new Term::ReadLine object yourself and supply
337              it using the term argument.
338
339           blank_repeats_cmd
340              This tells Term::ShellUI what to do when the user enters a blank
341              line.  Pass 0 (the default) to have it do nothing (like Bash),
342              or 1 to have it repeat the last command (like GDB).
343
344           commands
345              A hashref containing all the commands that ShellUI will respond
346              to.  The format of this data structure can be found below in the
347              command set documentation.  If you do not supply any commands to
348              the constructor, you must call the "commands" method to provide
349              at least a minimal command set before using many of the
350              following calls.  You may add or delete commands or even change
351              the entire command set at any time.
352
353           history_file
354              If defined then the command history is saved to this file on
355              exit.  It should probably specify a dotfile in the user's home
356              directory.  Tilde expansion is performed, so something like
357              "~/.myprog-history" is perfectly acceptable.
358
359           history_max = 500
360              This tells how many items to save to the history file.  The
361              default is 500.
362
363              Note that this parameter does not affect in-memory history.
364              Term::ShellUI makes no attemt to cull history so you're at the
365              mercy of the default of whatever ReadLine library you are using.
366              See "StifleHistory" in Term::ReadLine::Gnu for one way to change
367              this.
368
369           keep_quotes
370              Normally all unescaped, unnecessary quote marks are stripped.
371              If you specify "keep_quotes=>1", however, they are preserved.
372              This is useful if your application uses quotes to delimit, say,
373              Perl-style strings.
374
375           backslash_continues_command
376              Normally commands don't respect backslash continuation.  If you
377              pass backslash_continues_command=>1 to "new", then whenever a
378              line ends with a backslash, Term::ShellUI will continue reading.
379              The backslash is replaced with a space, so
380                  $ abc \
381                  > def
382
383              Will produce the command string 'abc  def'.
384
385           prompt
386              This is the prompt that should be displayed for every request.
387              It can be changed at any time using the "prompt" method.  The
388              default is <"$0 ">> (see app above).
389
390              If you specify a code reference, then the coderef is executed
391              and its return value is set as the prompt.  Two arguments are
392              passed to the coderef: the Term::ShellUI object, and the raw
393              command.  The raw command is always "" unless you're using
394              command completion, where the raw command is the command line
395              entered so far.
396
397              For example, the following line sets the prompt to "## > " where
398              ## is the current number of history items.
399
400                  $term->prompt(sub { $term->{term}->GetHistory() . " > " });
401
402              If you specify an arrayref, then the first item is the normal
403              prompt and the second item is the prompt when the command is
404              being continued.  For instance, this would emulate Bash's
405              behavior ($ is the normal prompt, but > is the prompt when
406              continuing).
407
408                  $term->prompt(['$', '>']);
409
410              Of course, you specify backslash_continues_command=>1 to to
411              "new" to cause commands to continue.
412
413              And, of course, you can use an array of procs too.
414
415                  $term->prompt([sub {'$'}, sub {'<'}]);
416
417           token_chars
418              This argument specifies the characters that should be considered
419              tokens all by themselves.  For instance, if I pass
420              token_chars=>'=', then 'ab=123' would be parsed to ('ab', '=',
421              '123').  Without token_chars, 'ab=123' remains a single string.
422
423              NOTE: you cannot change token_chars after the constructor has
424              been called!  The regexps that use it are compiled once (m//o).
425
426           display_summary_in_help
427              Usually it's easier to have the command's summary (desc) printed
428              first, then follow it with the documentation (doc).  However, if
429              the doc already contains its description (for instance, if
430              you're reading it from a podfile), you don't want the summary up
431              there too.  Pass 0 to prevent printing the desc above the doc.
432              Defaults to 1.
433
434       process_a_cmd([cmd])
435           Runs the specified command or prompts for it if no arguments are
436           supplied.  Returns the result or undef if no command was called.
437
438       run()
439           The main loop.  Processes all commands until someone calls
440           "/"exit_requested(exitflag)"(true)".
441
442           If you pass arguments, they are joined and run once.  For instance,
443           $term->run(@ARGV) allows your program to be run interactively or
444           noninteractively:
445
446           myshell help
447               Runs the help command and exits.
448
449           myshell
450               Invokes an interactive Term::ShellUI.
451
452       prompt(newprompt)
453           If supplied with an argument, this method sets the command-line
454           prompt.  Returns the old prompt.
455
456       commands(newcmds)
457           If supplied with an argument, it sets the current command set.
458           This can be used to change the command set at any time.  Returns
459           the old command set.
460
461       add_commands(newcmds)
462           Takes a command set as its first argument.  Adds all the commands
463           in it the current command set.  It silently replaces any commands
464           that have the same name.
465
466       exit_requested(exitflag)
467           If supplied with an argument, sets Term::ShellUI's finished flag to
468           the argument (1=exit, 0=don't exit).  So, to get the interpreter to
469           exit at the end of processing the current command, call
470           "$self->exit_requested(1)".  To cancel an exit request before the
471           command is finished, "$self->exit_requested(0)".  Returns the old
472           state of the flag.
473
474       add_eof_exit_hook(subroutine_reference)
475           Call this method to add a subroutine as a hook into Term::ShellUI's
476           "exit on EOF" (Ctrl-D) functionality. When a user enters Ctrl-D,
477           Term::ShellUI will call each function in this hook list, in order,
478           and will exit only if all of them return 0. The first function to
479           return a non-zero value will stop further processing of these hooks
480           and prevent the program from exiting.
481
482           The return value of this method is the placement of the hook
483           routine in the hook list (1 is first) or 0 (zero) on failure.
484
485       get_cname(cname)
486           This is a tiny utility function that turns the cname (array ref of
487           names for this command as returned by "get_deep_command") into a
488           human-readable string.  This function exists only to ensure that we
489           do this consistently.
490

OVERRIDES

492       These are routines that probably already do the right thing.  If not,
493       however, they are designed to be overridden.
494
495       blank_line()
496           This routine is called when the user inputs a blank line.  It
497           returns a string specifying the command to run or undef if nothing
498           should happen.
499
500           By default, ShellUI simply presents another command line.  Pass
501           "blank_repeats_cmd=>1" to the constructor to get ShellUI to repeat
502           the previous command.  Override this method to supply your own
503           behavior.
504
505       error(msg)
506           Called when an error occurrs.  By default, the routine simply
507           prints the msg to stderr.  Override it to change this behavior.  It
508           takes any number of arguments, cocatenates them together and prints
509           them to stderr.
510

WRITING A COMPLETION ROUTINE

512       Term::ReadLine makes writing a completion routine a notoriously
513       difficult task.  Term::ShellUI goes out of its way to make it as easy
514       as possible.  The best way to write a completion routine is to start
515       with one that already does something similar to what you want (see the
516       "CALLBACKS" section for the completion routines that come with
517       ShellUI).
518
519       Your routine returns an arrayref of possible completions, a string
520       conaining a short but helpful note, or undef if an error prevented any
521       completions from being generated.  Return an empty array if there are
522       simply no applicable competions.  Be careful; the distinction between
523       no completions and an error can be significant.
524
525       Your routine takes two arguments: a reference to the ShellUI object and
526       cmpl, a data structure that contains all the information you need to
527       calculate the completions.  Set $term->{debug_complete}=5 to see the
528       contents of cmpl:
529
530       str
531          The exact string that needs completion.  Often, for simple
532          completions, you don't need anything more than this.
533
534          NOTE: str does not respect token_chars!  It is supplied unchanged
535          from Readline and so uses whatever tokenizing it implements.
536          Unfortunately, if you've changed token_chars, this will often be
537          different from how Term::ShellUI would tokenize the same string.
538
539       cset
540          Command set for the deepest command found (see "get_deep_command").
541          If no command was found then cset is set to the topmost command set
542          ($self->commands()).
543
544       cmd
545          The command hash for deepest command found or undef if no command
546          was found (see "get_deep_command").  cset is the command set that
547          contains cmd.
548
549       cname
550          The full name of deepest command found as an array of tokens (see
551          "get_deep_command").  Use "get_cname" to convert this into a human-
552          readable string.
553
554       args
555          The arguments (as a list of tokens) that should be passed to the
556          command (see "get_deep_command").  Valid only if cmd is non-null.
557          Undef if no args were passed.
558
559       argno
560          The index of the argument (in args) containing the cursor.  If the
561          user is trying to complete on the command name, then argno is
562          negative (because the cursor comes before the arguments).
563
564       tokens
565          The tokenized command-line.
566
567       tokno
568          The index of the token containing the cursor.
569
570       tokoff
571          The character offset of the cursor in the token.
572
573          For instance, if the cursor is on the first character of the third
574          token, tokno will be 2 and tokoff will be 0.
575
576       twice
577          True if user has hit tab twice in a row.  This usually means that
578          you should print a message explaining the possible completions.
579
580          If you return your completions as a list, then $twice is handled for
581          you automatically.  You could use it, for instance, to display an
582          error message (using completemsg) telling why no completions could
583          be found.
584
585       rawline
586          The command line as a string, exactly as entered by the user.
587
588       rawstart
589          The character position of the cursor in rawline.
590
591       The following are utility routines that your completion function can
592       call.
593
594       completemsg(msg)
595           Allows your completion routine to print to the screen while
596           completing (i.e. to offer suggestions or print debugging info --
597           see debug_complete).  If it just blindly calls print, the prompt
598           will be corrupted and things will be confusing until the user
599           redraws the screen (probably by hitting Control-L).
600
601               $self->completemsg("You cannot complete here!\n");
602
603           Note that Term::ReadLine::Perl doesn't support this so the user
604           will always have to hit Control-L after printing.  If your
605           completion routine returns a string rather than calling
606           completemsg() then it should work everywhere.
607
608       suppress_completion_append_character()
609           When the ReadLine library finds a unique match among the list that
610           you returned, it automatically appends a space.  Normally this is
611           what you want (i.e. when completing a command name, in help, etc.)
612           However, if you're navigating the filesystem, this is definitely
613           not desirable (picture having to hit backspace after completing
614           each directory).
615
616           Your completion function needs to call this routine every time it
617           runs if it doesn't want a space automatically appended to the
618           completions that it returns.
619
620       suppress_completion_escape()
621           Normally everything returned by your completion routine is escaped
622           so that it doesn't get destroyed by shell metacharacter
623           interpretation (quotes, backslashes, etc).  To avoid escaping twice
624           (disastrous), a completion routine that does its own escaping
625           (perhaps using Text::Shellwords::Cursorparse_escape) must call
626           suppress_completion_escape every time is called.
627
628       force_to_string(cmpl, commmpletions, default_quote)
629           If all the completions returned by your completion routine should
630           be enclosed in single or double quotes, call force_to_string on
631           them.  You will most likely need this routine if keep_quotes is 1.
632           This is useful when completing a construct that you know must
633           always be quoted.
634
635           force_to_string surrounds all completions with the quotes supplied
636           by the user or, if the user didn't supply any quotes, the quote
637           passed in default_quote.  If the programmer didn't supply a
638           default_quote and the user didn't start the token with an open
639           quote, then force_to_string won't change anything.
640
641           Here's how to use it to force strings on two possible completions,
642           aaa and bbb.  If the user doesn't supply any quotes, the
643           completions will be surrounded by double quotes.
644
645                args => sub { shift->force_to_string(@_,['aaa','bbb'],'"') },
646
647           Calling force_to_string escapes your completions (unless your
648           callback calls suppress_completion_escape itself), then calls
649           suppress_completion_escape to ensure the final quote isn't mangled.
650

INTERNALS

652       These commands are internal to ShellUI.  They are documented here only
653       for completeness -- you should never need to call them.
654
655       get_deep_command
656           Looks up the supplied command line in a command hash.  Follows all
657           synonyms and subcommands.  Returns undef if the command could not
658           be found.
659
660               my($cset, $cmd, $cname, $args) =
661                   $self->get_deep_command($self->commands(), $tokens);
662
663           This call takes two arguments:
664
665           cset
666              This is the command set to use.  Pass $self->commands() unless
667              you know exactly what you're doing.
668
669           tokens
670              This is the command line that the command should be read from.
671              It is a reference to an array that has already been split on
672              whitespace using Text::Shellwords::Cursor::parse_line.
673
674           and it returns a list of 4 values:
675
676           1. cset: the deepest command set found.  Always returned.
677
678           2. cmd: the command hash for the command.  Undef if no command was
679              found.
680
681           3. cname: the full name of the command.  This is an array of
682              tokens, i.e. ('show', 'info').  Returns as deep as it could find
683              commands even if the final command was not found.
684
685           4. args: the command's arguments (all remaining tokens after the
686              command is found).
687
688       get_cset_completions(cset)
689           Returns a list of commands from the passed command set that are
690           suitable for completing.
691
692       call_args
693           Given a command set, does the correct thing at this stage in the
694           completion (a surprisingly nontrivial task thanks to ShellUI's
695           flexibility).  Called by complete().
696
697       complete
698           This routine figures out the command set of the completion routine
699           that needs to be called, then calls call_args().  It is called by
700           completion_function.
701
702           You should override this routine if your application has custom
703           completion needs (like non-trivial tokenizing, where you'll need to
704           modify the cmpl data structure).  If you override this routine, you
705           will probably need to override call_cmd as well.
706
707       completion_function
708           This is the entrypoint to the ReadLine completion callback.  It
709           sets up a bunch of data, then calls complete to calculate the
710           actual completion.
711
712           To watch and debug the completion process, you can set
713           $self->{debug_complete} to 2 (print tokenizing), 3 (print
714           tokenizing and results) or 4 (print everything including the cmpl
715           data structure).
716
717           Youu should never need to call or override this function.  If you
718           do (but, trust me, you don't), set
719           $self->{term}->Attribs->{completion_function} to point to your own
720           routine.
721
722           See the Term::ReadLine documentation for a description of the
723           arguments.
724
725       get_cmd_summary(tokens, cset)
726           Prints a one-line summary for the given command.  Uses
727           self->commands() if cset is not specified.
728
729       get_cmd_help(tokens, cset)
730           Prints the full help text for the given command.  Uses
731           self->commands() if cset is not specified.
732
733       get_category_summary(name, cats)
734           Prints a one-line summary for the named category in the category
735           hash specified in cats.
736
737       get_category_help(cat, cset)
738           Returns a summary of the commands listed in cat.  You must pass the
739           command set that contains those commands in cset.
740
741       get_all_cmd_summaries(cset)
742           Pass it a command set, and it will return a string containing the
743           summaries for each command in the set.
744
745       load_history()
746           If $self->{history_file} is set (see "new"), this will load all
747           history from that file.  Called by run on startup.  If you don't
748           use run, you will need to call this command manually.
749
750       save_history()
751           If $self->{history_file} is set (see "new"), this will save all
752           history to that file.  Called by run on shutdown.  If you don't use
753           run, you will need to call this command manually.
754
755           The history routines don't use ReadHistory and WriteHistory so they
756           can be used even if other ReadLine libs are being used.
757           save_history requires that the ReadLine lib supply a GetHistory
758           call.
759
760       call_command(parms)
761           Executes a command and returns the result.  It takes a single
762           argument: the parms data structure.
763
764           parms is a subset of the cmpl data structure (see the
765           "complete(cmpl)" in complete routine for more).  Briefly, it
766           contains: cset, cmd, cname, args (see "get_deep_command"), tokens
767           and rawline (the tokenized and untokenized command lines).  See
768           complete for full descriptions of these fields.
769
770           This call should be overridden if you have exotic command
771           processing needs.  If you override this routine, you will probably
772           need to override the complete routine too.
773

LICENSE

775       Copyright (c) 2003-2011 Scott Bronson, all rights reserved.  This
776       program is free software released under the MIT license.
777

AUTHORS

779       Scott Bronson <bronson@rinspin.com> Lester Hightower
780       <hightowe@cpan.org> Ryan Gies <ryan@livesite.net> Martin Kluge
781       <mk@elxsi.de>
782

POD ERRORS

784       Hey! The above document had some coding errors, which are explained
785       below:
786
787       Around line 866:
788           alternative text '/"exit_requested(exitflag)"' contains non-escaped
789           | or /
790
791
792
793perl v5.32.0                      2020-07-28                  Term::ShellUI(3)
Impressum