=head1 NAME

pshcomplete - TAB completion in Perl Shell

=for README
Please read the perlpod manpage! Pay particular attention to the markup
sequences (B<>, C<>, I<>, etc.).

=head1 SYNOPSIS

TAB completion strategies in Perl Shell

=head1 DESCRIPTION

B<psh> supports built-in completion support as well as a largely B<bash>
compatible user-programmable completion.

Whenever a user presses the TAB key, B<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:

=over 4

=item Perl Hash Keys

If the current expression looks like an attempt to enter the key of a
Perl Hash ( C<$var{$keypart> or C<$var->{$keypart> ), B<psh> will examine
the Perl symbol table to try to complete the entered key.

=item Perl Methods

Afterwards B<psh> will try to complete method calls which look like
C<$obj->methodpart>.

=item Perl Variables

An attempt is then made to complete any perl variable names starting with
one the most usual context signifiers ( C<@$%&> or C<$#> ).

=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), B<psh> attempts
to find an executable in the current path matching the expression.

=item Filenames

If no completions could be generated so far, B<psh> will attempt to complete
the word as a filename.

=item Built-ins

Afterwards, B<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.

=back 

=head1 PROGRAMMABLE COMPLETIONS

=head2 DESCRIPTION

This C<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.

=head2 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 B<complete> builtin (See L<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
B<-f> or B<-d> option is used for filename or directory name
completion, the shell variable B<FIGNORE> is used to filter the
matches.  See L<ENVIRONMENT VARIABLES> for a description of
B<FIGNORE>.

Any completions specified by a filename expansion pattern to the B<-G>
option are generated next.  The words generated by the pattern need
not match the word being completed.  The B<GLOBIGNORE> shell variable
is not used to filter the matches, but the B<FIGNORE> shell variable
is used.

Next, the string specified as the argument to the B<-W> option is
considered.  The string is first split using the characters in the
B<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 B<-F> and B<-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 B<-F> is invoked first.  The function may
use any of the shell facilities, including the B<compgen> builtin
described below (See L<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 B<-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 B<-X> option is applied to the list.  The filter is
a pattern as used for pathname expansion; a C<&> in the pattern is
replaced with the text of the word being completed.  A literal C<&>
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 C<!> negates the pattern; in this
case any completion not matching the pattern will be removed.

Finally, any prefix and suffix specified with the B<-P> and B<-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.

=head2 Programmable Completion Builtins

A builtin commands B<complete> and a builtin Perl function B<compgen>
are available to manipulate the programmable completion facilities.

=over 4

=item B<compgen>

	compgen [OPTION] [WORD]

Generate possible completion matches for I<WORD> according to the
I<OPTION>s, which may be any option accepted by the B<complete> builtin
with the exception of B<-p> and B<-r>, and write the matches to the
standard output.  When using the B<-F> or B<-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 I<WORD> is specified, only
those completions matching I<WORD> will be displayed.

The return value is true unless an invalid option is supplied, or no
matches were generated.

=item B<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 I<NAME> should be completed.  If the
B<-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 B<-r> option removes a completion specification
for each I<NAME>, or, if no I<NAME>s are supplied, all completion
specifications.

The process of applying these completion specifications when word
completion is attempted is described above (See L<Programmable
Completion>.).

Other options, if specified, have the following meanings.  The
arguments to the B<-G>, B<-W>, and B<-X> options (and, if necessary,
the B<-P> and B<-S> options) should be quoted to protect them from
expansion before the B<complete> builtin is invoked.

=over 4

=item B<-A> I<ACTION>

The I<ACTION> may be one of the following to generate a list of
possible completions:

=over 4

=item B<alias>

Alias names.  May also be specified as B<-a>.

=item B<arrayvar>

Names of Perl array variable names.

=item B<binding>

Readline key binding names.

=item B<builtin>

Names of shell builtin commands.  May also be specified as B<-b>.

=item B<command>

Command names.  May also be specified as B<-c>.

=item B<directory>

Directory names.  May also be specified as B<-d>.

=item B<disabled>

Names of disabled shell builtins (not implemented yet.).

=item B<enabled>

Names of enabled shell builtins (not implemented yet.).

=item B<export>

Names of exported shell variables.  May also be specified as B<-e>.

=item B<file>

File names.  May also be specified as B<-f>.

=item B<function>

Names of Perl functions.

=item B<hashvar>

Names of Perl hash variable names.

=item B<helptopic>

Help topics as accepted by the `help' builtin.

=item B<hostname>

Hostnames.

=item B<job>

Job names, if job control is active.  May also be specified as B<-j>.

=item B<keyword>

Shell reserved words.  May also be specified as B<-k>.

=item B<running>

Names of running jobs, if job control is active.

=item B<setopt>

Valid arguments for the B<-o> option to the B<set> builtin (not
implemented yet.).

=item B<shopt>

Shell option names as accepted by the B<shopt> builtin (not
implemented yet.).

=item B<signal>

Signal names.

=item B<stopped>

Names of stopped jobs, if job control is active.

=item B<user>

User names.  May also be specified as B<-u>.

=item B<variable>

Names of all Perl variables.  May also be specified as B<-v>.

=back

=item B<-G> I<GLOBPAT>

The filename expansion pattern I<GLOBPAT> is expanded to generate the
possible completions.

=item B<-W> I<WORDLIST>

The I<WORDLIST> is split using the characters in the B<IFS> special
variable as delimiters, and each resultant word is expanded.  The
possible completions are the resultant list.

=item B<-C> I<COMMAND>

I<COMMAND> is executed in a subshell environment, and its output is
used as the possible completions.

=item B<-F> I<FUNCTION>

The shell function I<FUNCTION> is executed in the current Perl shell
environment.  When it finishes, the possible completions are retrieved
from the array which the function returns.

=item B<-X> I<FILTERPAT>

I<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 I<FILTERPAT> is
removed from the list.  A leading C<!> in I<FILTERPAT> negates the
pattern; in this case, any completion not matching I<FILTERPAT> is
removed.

=item B<-x> I<FILTERPAT>

Similar to the B<-X> option above, except it is applied to only
filenames not to directory names etc.

=item B<-P> I<PREFIX>

I<PREFIX> is added at the beginning of each possible completion after
all other options have been applied.

=item B<-S> I<SUFFIX>

I<SUFFIX> is appended to each possible completion after all other
options have been applied.

=back

The return value is true unless an invalid option is supplied, an
option other than B<-p> or B<-r> is supplied without a I<NAME>
argument, an attempt is made to remove a completion specification for
a I<NAME> for which no specification exists, or an error occurs adding
a completion specification.

=back

=head2 AUTHOR

Hiroo Hayashi, hiroo.hayashi@computer.org

=head2 SEE ALSO

info manual of bash-2.04 and/or later

=head2 EXAMPLES

F<complete_example> in the Psh distribution shows you many examples of
the usage of programmable completion.

	source complete-examples


=head1 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.


=cut
