PSHCOMPLETE(1) User Contributed Perl Documentation PSHCOMPLETE(1)NAMEpshcomplete - TAB completion in Perl Shell
SYNOPSIS
TAB completion strategies in Perl Shell
DESCRIPTION
psh supports built-in completion support as well as a largely bash
compatible user-programmable completion.
Whenever a user presses the TAB key, psh first checks wether we're
trying to complete a command for which there's a user-programmed
completion. Please see below for further information about this
process.
If there are no user-programmed completions, following default
completion strategies are checked in the specified order:
Perl Hash Keys
If the current expression looks like an attempt to enter the key of
a Perl Hash ( "$var{$keypart" or "$var-"{$keypart> ), psh will
examine the Perl symbol table to try to complete the entered key.
Perl Methods
Afterwards psh will try to complete method calls which look like
"$obj-"methodpart>.
Perl Variables
An attempt is then made to complete any perl variable names
starting with one the most usual context signifiers ( "@$%&" or $#
).
Executables
If the user is currently working on the first word of the line or a
similar syntactic position (like the first word after a pipe sign),
psh attempts to find an executable in the current path matching the
expression.
Filenames
If no completions could be generated so far, psh will attempt to
complete the word as a filename.
Built-ins
Afterwards, psh will check wether the command to execute is a
builtin command. If yes, the builtin command is asked for a list of
completions. The list of completions supplied by the builtin may
or may not replace the list of so far gathered possible
completions, depending on the builtin.
PROGRAMMABLE COMPLETIONS
DESCRIPTION
This "Psh::PCompletion" module provides the programmable completion
function almost compatible with the one of bash-2.04 and/or later. The
following document is based on the texinfo file of bash-2.04-beta5.
Programmable Completion
When word completion is attempted for an argument to a command for
which a completion specification (a COMPSPEC) has been defined using
the complete builtin (See "Programmable Completion Builtins".), the
programmable completion facilities are invoked.
First, the command name is identified. If a compspec has been defined
for that command, the compspec is used to generate the list of possible
completions for the word. If the command word is a full pathname, a
compspec for the full pathname is searched for first. If no compspec
is found for the full pathname, an attempt is made to find a compspec
for the portion following the final slash.
Once a compspec has been found, it is used to generate the list of
matching words. If a compspec is not found, the default Psh completion
described above (Where is it described?) is performed.
First, the actions specified by the compspec are used. Only matches
which are prefixed by the word being completed are returned. When the
-f or -d option is used for filename or directory name completion, the
shell variable FIGNORE is used to filter the matches. See "ENVIRONMENT
VARIABLES" for a description of FIGNORE.
Any completions specified by a filename expansion pattern to the -G
option are generated next. The words generated by the pattern need not
match the word being completed. The GLOBIGNORE shell variable is not
used to filter the matches, but the FIGNORE shell variable is used.
Next, the string specified as the argument to the -W option is
considered. The string is first split using the characters in the IFS
special variable as delimiters. Shell quoting is honored. Each word
is then expanded using brace expansion, tilde expansion, parameter and
variable expansion, command substitution, arithmetic expansion, and
pathname expansion, as described above (Where is it described?). The
results are split using the rules described above (Where is it
described?). No filtering against the word being completed is
performed.
After these matches have been generated, any shell function or command
specified with the -F and -C options is invoked. When the function or
command is invoked, the first argument is the word being completed, the
second argument is the current command line, the third argument is the
index of the current cursor position relative to the beginning of the
current command line, and the fourth argument is the name of the
command whose arguments are being completed. If the current cursor
position is at the end of the current command, the value of the third
argument is equal to the length of the second argument string.
No filtering of the generated completions against the word being
completed is performed; the function or command has complete freedom in
generating the matches.
Any function specified with -F is invoked first. The function may use
any of the shell facilities, including the compgen builtin described
below (See "Programmable Completion Builtins".), to generate the
matches. It returns a array including the possible completions. For
example;
sub _foo_func {
my ($cur, $line, $start, $cmd) = @_;
...
return @possible_completions;
}
complete -F _foo_func bar
Next, any command specified with the -C option is invoked in an
environment equivalent to command substitution. It should print a list
of completions, one per line, to the standard output. Backslash may be
used to escape a newline, if necessary.
After all of the possible completions are generated, any filter
specified with the -X option is applied to the list. The filter is a
pattern as used for pathname expansion; a "&" in the pattern is
replaced with the text of the word being completed. A literal "&" may
be escaped with a backslash; the backslash is removed before attempting
a match. Any completion that matches the pattern will be removed from
the list. A leading "!" negates the pattern; in this case any
completion not matching the pattern will be removed.
Finally, any prefix and suffix specified with the -P and -S options are
added to each member of the completion list, and the result is returned
to the Readline completion code as the list of possible completions.
If a compspec is found, whatever it generates is returned to the
completion code as the full set of possible completions. The default
Bash completions are not attempted, and the Readline default of
filename completion is disabled.
Programmable Completion Builtins
A builtin commands complete and a builtin Perl function compgen are
available to manipulate the programmable completion facilities.
compgen
compgen [OPTION] [WORD]
Generate possible completion matches for WORD according to the
OPTIONs, which may be any option accepted by the complete builtin
with the exception of -p and -r, and write the matches to the
standard output. When using the -F or -C options, the various
shell variables set by the programmable completion facilities,
while available, will not have useful values.
The matches will be generated in the same way as if the
programmable completion code had generated them directly from a
completion specification with the same flags. If WORD is
specified, only those completions matching WORD will be displayed.
The return value is true unless an invalid option is supplied, or
no matches were generated.
complete
complete [-abcdefjkvu] [-A ACTION] [-G GLOBPAT] [-W WORDLIST]
[-P PREFIX] [-S SUFFIX] [-X FILTERPAT] [-x FILTERPAT]
[-F FUNCTION] [-C COMMAND] NAME [NAME ...]
complete -pr [NAME ...]
Specify how arguments to each NAME should be completed. If the -p
option is supplied, or if no options are supplied, existing
completion specifications are printed in a way that allows them to
be reused as input. The -r option removes a completion
specification for each NAME, or, if no NAMEs are supplied, all
completion specifications.
The process of applying these completion specifications when word
completion is attempted is described above (See Programmable
Completion.).
Other options, if specified, have the following meanings. The
arguments to the -G, -W, and -X options (and, if necessary, the -P
and -S options) should be quoted to protect them from expansion
before the complete builtin is invoked.
-A ACTION
The ACTION may be one of the following to generate a list of
possible completions:
alias
Alias names. May also be specified as -a.
arrayvar
Names of Perl array variable names.
binding
Readline key binding names.
builtin
Names of shell builtin commands. May also be specified as
-b.
command
Command names. May also be specified as -c.
directory
Directory names. May also be specified as -d.
disabled
Names of disabled shell builtins (not implemented yet.).
enabled
Names of enabled shell builtins (not implemented yet.).
export
Names of exported shell variables. May also be specified
as -e.
file
File names. May also be specified as -f.
function
Names of Perl functions.
hashvar
Names of Perl hash variable names.
helptopic
Help topics as accepted by the `help' builtin.
hostname
Hostnames.
job Job names, if job control is active. May also be specified
as -j.
keyword
Shell reserved words. May also be specified as -k.
running
Names of running jobs, if job control is active.
setopt
Valid arguments for the -o option to the set builtin (not
implemented yet.).
shopt
Shell option names as accepted by the shopt builtin (not
implemented yet.).
signal
Signal names.
stopped
Names of stopped jobs, if job control is active.
user
User names. May also be specified as -u.
variable
Names of all Perl variables. May also be specified as -v.
-G GLOBPAT
The filename expansion pattern GLOBPAT is expanded to generate
the possible completions.
-W WORDLIST
The WORDLIST is split using the characters in the IFS special
variable as delimiters, and each resultant word is expanded.
The possible completions are the resultant list.
-C COMMAND
COMMAND is executed in a subshell environment, and its output
is used as the possible completions.
-F FUNCTION
The shell function FUNCTION is executed in the current Perl
shell environment. When it finishes, the possible completions
are retrieved from the array which the function returns.
-X FILTERPAT
FILTERPAT is a pattern as used for filename expansion. It is
applied to the list of possible completions generated by the
preceding options and arguments, and each completion matching
FILTERPAT is removed from the list. A leading "!" in FILTERPAT
negates the pattern; in this case, any completion not matching
FILTERPAT is removed.
-x FILTERPAT
Similar to the -X option above, except it is applied to only
filenames not to directory names etc.
-P PREFIX
PREFIX is added at the beginning of each possible completion
after all other options have been applied.
-S SUFFIX
SUFFIX is appended to each possible completion after all other
options have been applied.
The return value is true unless an invalid option is supplied, an
option other than -p or -r is supplied without a NAME argument, an
attempt is made to remove a completion specification for a NAME for
which no specification exists, or an error occurs adding a
completion specification.
AUTHOR
Hiroo Hayashi, hiroo.hayashi@computer.org
SEE ALSO
info manual of bash-2.04 and/or later
EXAMPLES
complete_example in the Psh distribution shows you many examples of the
usage of programmable completion.
source complete-examples
COPYRIGHT
Copyright (C) 1999-2003 Gregor N. Purdy. All rights reserved. This
script is free software. It may be copied or modified according to the
same terms as Perl itself.
perl v5.20.2 2007-07-06 PSHCOMPLETE(1)
