.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PSHCOMPLETE 1"
.TH PSHCOMPLETE 1 "2003-01-02" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
pshcomplete \- TAB completion in Perl Shell
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\s-1TAB\s0 completion strategies in Perl Shell
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBpsh\fR supports built-in completion support as well as a largely \fBbash\fR
compatible user-programmable completion.
.PP
Whenever a user presses the \s-1TAB\s0 key, \fBpsh\fR 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.
.PP
If there are no user-programmed completions, following default completion
strategies are checked in the specified order:
.IP "Perl Hash Keys" 4
.IX Item "Perl Hash Keys"
If the current expression looks like an attempt to enter the key of a
Perl Hash ( \f(CW\*(C`$var{$keypart\*(C'\fR or \f(CW\*(C`$var\-\*(C'\fR{$keypart> ), \fBpsh\fR will examine
the Perl symbol table to try to complete the entered key.
.IP "Perl Methods" 4
.IX Item "Perl Methods"
Afterwards \fBpsh\fR will try to complete method calls which look like
\&\f(CW\*(C`$obj\-\*(C'\fRmethodpart>.
.IP "Perl Variables" 4
.IX Item "Perl Variables"
An attempt is then made to complete any perl variable names starting with
one the most usual context signifiers ( \f(CW\*(C`@$%&\*(C'\fR or \f(CW$#\fR ).
.IP "Executables" 4
.IX Item "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), \fBpsh\fR attempts
to find an executable in the current path matching the expression.
.IP "Filenames" 4
.IX Item "Filenames"
If no completions could be generated so far, \fBpsh\fR will attempt to complete
the word as a filename.
.IP "Built-ins" 4
.IX Item "Built-ins"
Afterwards, \fBpsh\fR 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.
.SH "PROGRAMMABLE COMPLETIONS"
.IX Header "PROGRAMMABLE COMPLETIONS"
.Sh "\s-1DESCRIPTION\s0"
.IX Subsection "DESCRIPTION"
This \f(CW\*(C`Psh::PCompletion\*(C'\fR 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.
.Sh "Programmable Completion"
.IX Subsection "Programmable Completion"
When word completion is attempted for an argument to a command for
which a completion specification (a \s-1COMPSPEC\s0) has been defined using
the \fBcomplete\fR builtin (See \*(L"Programmable Completion Builtins\*(R".),
the programmable completion facilities are invoked.
.PP
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.
.PP
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.
.PP
First, the actions specified by the compspec are used.  Only matches
which are prefixed by the word being completed are returned.  When the
\&\fB\-f\fR or \fB\-d\fR option is used for filename or directory name
completion, the shell variable \fB\s-1FIGNORE\s0\fR is used to filter the
matches.  See \*(L"\s-1ENVIRONMENT\s0 \s-1VARIABLES\s0\*(R" for a description of
\&\fB\s-1FIGNORE\s0\fR.
.PP
Any completions specified by a filename expansion pattern to the \fB\-G\fR
option are generated next.  The words generated by the pattern need
not match the word being completed.  The \fB\s-1GLOBIGNORE\s0\fR shell variable
is not used to filter the matches, but the \fB\s-1FIGNORE\s0\fR shell variable
is used.
.PP
Next, the string specified as the argument to the \fB\-W\fR option is
considered.  The string is first split using the characters in the
\&\fB\s-1IFS\s0\fR 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.
.PP
After these matches have been generated, any shell function or command
specified with the \fB\-F\fR and \fB\-C\fR 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.
.PP
No filtering of the generated completions against the word being
completed is performed; the function or command has complete freedom
in generating the matches.
.PP
Any function specified with \fB\-F\fR is invoked first.  The function may
use any of the shell facilities, including the \fBcompgen\fR builtin
described below (See \*(L"Programmable Completion Builtins\*(R".), to
generate the matches.  It returns a array including the possible
completions.  For example;
.PP
.Vb 6
\&        sub _foo_func {
\&            my ($cur, $line, $start, $cmd) = @_;
\&            ...
\&            return @possible_completions;
\&        }
\&        complete -F _foo_func bar
.Ve
.PP
Next, any command specified with the \fB\-C\fR 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.
.PP
After all of the possible completions are generated, any filter
specified with the \fB\-X\fR option is applied to the list.  The filter is
a pattern as used for pathname expansion; a \f(CW\*(C`&\*(C'\fR in the pattern is
replaced with the text of the word being completed.  A literal \f(CW\*(C`&\*(C'\fR
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 \f(CW\*(C`!\*(C'\fR negates the pattern; in this
case any completion not matching the pattern will be removed.
.PP
Finally, any prefix and suffix specified with the \fB\-P\fR and \fB\-S\fR
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.
.PP
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.
.Sh "Programmable Completion Builtins"
.IX Subsection "Programmable Completion Builtins"
A builtin commands \fBcomplete\fR and a builtin Perl function \fBcompgen\fR
are available to manipulate the programmable completion facilities.
.IP "\fBcompgen\fR" 4
.IX Item "compgen"
.Vb 1
\&        compgen [OPTION] [WORD]
.Ve
.Sp
Generate possible completion matches for \fI\s-1WORD\s0\fR according to the
\&\fI\s-1OPTION\s0\fRs, which may be any option accepted by the \fBcomplete\fR builtin
with the exception of \fB\-p\fR and \fB\-r\fR, and write the matches to the
standard output.  When using the \fB\-F\fR or \fB\-C\fR options, the various
shell variables set by the programmable completion facilities, while
available, will not have useful values.
.Sp
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 \fI\s-1WORD\s0\fR is specified, only
those completions matching \fI\s-1WORD\s0\fR will be displayed.
.Sp
The return value is true unless an invalid option is supplied, or no
matches were generated.
.IP "\fBcomplete\fR" 4
.IX Item "complete"
.Vb 4
\&        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 ...]
.Ve
.Sp
Specify how arguments to each \fI\s-1NAME\s0\fR should be completed.  If the
\&\fB\-p\fR 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 \fB\-r\fR option removes a completion specification
for each \fI\s-1NAME\s0\fR, or, if no \fI\s-1NAME\s0\fRs are supplied, all completion
specifications.
.Sp
The process of applying these completion specifications when word
completion is attempted is described above (See \*(L"Programmable Completion\*(R".).
.Sp
Other options, if specified, have the following meanings.  The
arguments to the \fB\-G\fR, \fB\-W\fR, and \fB\-X\fR options (and, if necessary,
the \fB\-P\fR and \fB\-S\fR options) should be quoted to protect them from
expansion before the \fBcomplete\fR builtin is invoked.
.RS 4
.IP "\fB\-A\fR \fI\s-1ACTION\s0\fR" 4
.IX Item "-A ACTION"
The \fI\s-1ACTION\s0\fR may be one of the following to generate a list of
possible completions:
.RS 4
.IP "\fBalias\fR" 4
.IX Item "alias"
Alias names.  May also be specified as \fB\-a\fR.
.IP "\fBarrayvar\fR" 4
.IX Item "arrayvar"
Names of Perl array variable names.
.IP "\fBbinding\fR" 4
.IX Item "binding"
Readline key binding names.
.IP "\fBbuiltin\fR" 4
.IX Item "builtin"
Names of shell builtin commands.  May also be specified as \fB\-b\fR.
.IP "\fBcommand\fR" 4
.IX Item "command"
Command names.  May also be specified as \fB\-c\fR.
.IP "\fBdirectory\fR" 4
.IX Item "directory"
Directory names.  May also be specified as \fB\-d\fR.
.IP "\fBdisabled\fR" 4
.IX Item "disabled"
Names of disabled shell builtins (not implemented yet.).
.IP "\fBenabled\fR" 4
.IX Item "enabled"
Names of enabled shell builtins (not implemented yet.).
.IP "\fBexport\fR" 4
.IX Item "export"
Names of exported shell variables.  May also be specified as \fB\-e\fR.
.IP "\fBfile\fR" 4
.IX Item "file"
File names.  May also be specified as \fB\-f\fR.
.IP "\fBfunction\fR" 4
.IX Item "function"
Names of Perl functions.
.IP "\fBhashvar\fR" 4
.IX Item "hashvar"
Names of Perl hash variable names.
.IP "\fBhelptopic\fR" 4
.IX Item "helptopic"
Help topics as accepted by the `help' builtin.
.IP "\fBhostname\fR" 4
.IX Item "hostname"
Hostnames.
.IP "\fBjob\fR" 4
.IX Item "job"
Job names, if job control is active.  May also be specified as \fB\-j\fR.
.IP "\fBkeyword\fR" 4
.IX Item "keyword"
Shell reserved words.  May also be specified as \fB\-k\fR.
.IP "\fBrunning\fR" 4
.IX Item "running"
Names of running jobs, if job control is active.
.IP "\fBsetopt\fR" 4
.IX Item "setopt"
Valid arguments for the \fB\-o\fR option to the \fBset\fR builtin (not
implemented yet.).
.IP "\fBshopt\fR" 4
.IX Item "shopt"
Shell option names as accepted by the \fBshopt\fR builtin (not
implemented yet.).
.IP "\fBsignal\fR" 4
.IX Item "signal"
Signal names.
.IP "\fBstopped\fR" 4
.IX Item "stopped"
Names of stopped jobs, if job control is active.
.IP "\fBuser\fR" 4
.IX Item "user"
User names.  May also be specified as \fB\-u\fR.
.IP "\fBvariable\fR" 4
.IX Item "variable"
Names of all Perl variables.  May also be specified as \fB\-v\fR.
.RE
.RS 4
.RE
.IP "\fB\-G\fR \fI\s-1GLOBPAT\s0\fR" 4
.IX Item "-G GLOBPAT"
The filename expansion pattern \fI\s-1GLOBPAT\s0\fR is expanded to generate the
possible completions.
.IP "\fB\-W\fR \fI\s-1WORDLIST\s0\fR" 4
.IX Item "-W WORDLIST"
The \fI\s-1WORDLIST\s0\fR is split using the characters in the \fB\s-1IFS\s0\fR special
variable as delimiters, and each resultant word is expanded.  The
possible completions are the resultant list.
.IP "\fB\-C\fR \fI\s-1COMMAND\s0\fR" 4
.IX Item "-C COMMAND"
\&\fI\s-1COMMAND\s0\fR is executed in a subshell environment, and its output is
used as the possible completions.
.IP "\fB\-F\fR \fI\s-1FUNCTION\s0\fR" 4
.IX Item "-F FUNCTION"
The shell function \fI\s-1FUNCTION\s0\fR is executed in the current Perl shell
environment.  When it finishes, the possible completions are retrieved
from the array which the function returns.
.IP "\fB\-X\fR \fI\s-1FILTERPAT\s0\fR" 4
.IX Item "-X FILTERPAT"
\&\fI\s-1FILTERPAT\s0\fR 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 \fI\s-1FILTERPAT\s0\fR is
removed from the list.  A leading \f(CW\*(C`!\*(C'\fR in \fI\s-1FILTERPAT\s0\fR negates the
pattern; in this case, any completion not matching \fI\s-1FILTERPAT\s0\fR is
removed.
.IP "\fB\-x\fR \fI\s-1FILTERPAT\s0\fR" 4
.IX Item "-x FILTERPAT"
Similar to the \fB\-X\fR option above, except it is applied to only
filenames not to directory names etc.
.IP "\fB\-P\fR \fI\s-1PREFIX\s0\fR" 4
.IX Item "-P PREFIX"
\&\fI\s-1PREFIX\s0\fR is added at the beginning of each possible completion after
all other options have been applied.
.IP "\fB\-S\fR \fI\s-1SUFFIX\s0\fR" 4
.IX Item "-S SUFFIX"
\&\fI\s-1SUFFIX\s0\fR is appended to each possible completion after all other
options have been applied.
.RE
.RS 4
.Sp
The return value is true unless an invalid option is supplied, an
option other than \fB\-p\fR or \fB\-r\fR is supplied without a \fI\s-1NAME\s0\fR
argument, an attempt is made to remove a completion specification for
a \fI\s-1NAME\s0\fR for which no specification exists, or an error occurs adding
a completion specification.
.RE
.Sh "\s-1AUTHOR\s0"
.IX Subsection "AUTHOR"
Hiroo Hayashi, hiroo.hayashi@computer.org
.Sh "\s-1SEE\s0 \s-1ALSO\s0"
.IX Subsection "SEE ALSO"
info manual of bash\-2.04 and/or later
.Sh "\s-1EXAMPLES\s0"
.IX Subsection "EXAMPLES"
\&\fIcomplete_example\fR in the Psh distribution shows you many examples of
the usage of programmable completion.
.PP
.Vb 1
\&        source complete-examples
.Ve
.SH "COPYRIGHT"
.IX Header "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.