PSHCOMPLETE(1)

NAME
pshcomplete - 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.