Next: Programmable Completion Builtins, Previous: Readline vi Mode, Up: Command Line Editing [Contents][Index]
8.6 Programmable Completion ¶When the user attempts word completion for a command or an argument to a command for which a completion specification (a compspec) has been defined using the complete builtin (see Programmable Completion Builtins), Readline invokes the programmable completion facilities.
First, Bash identifies the command name. 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 the empty string (completion attempted at the beginning of an empty line), Bash uses any compspec defined with the -E option to complete. The -I option to complete indicates that the command word is the first non-assignment word on the line, or after a command delimiter such as ‘;’ or ‘|’. This usually indicates command name completion.
If the command word is a full pathname, Bash searches for a compspec for the full pathname first. If there is no compspec for the full pathname, Bash attempts to find a compspec for the portion following the final slash. If those searches do not result in a compspec, or if there is no compspec for the command word, Bash uses any compspec defined with the -D option to complete as the default. If there is no default compspec, Bash performs alias expansion on the command word as a final resort, and attempts to find a compspec for the command word resulting from any successful expansion.
If a compspec is not found, Bash performs its default completion described above (see Letting Readline Type For You). Otherwise, once a compspec has been found, Bash uses it to generate the list of matching words.
First, Bash performs the actions specified by the compspec. This only returns matches which are prefixes of the word being completed. When the -f or -d option is used for filename or directory name completion, Bash uses shell the variable FIGNORE to filter the matches. See Bash Variables, for a description of FIGNORE.
Next, programmable completion generates matches specified by a pathname expansion pattern supplied as an argument to the -G option. The words generated by the pattern need not match the word being completed. Bash uses the FIGNORE variable to filter the matches, but does not use the GLOBIGNORE shell variable.
Next, completion considers the string specified as the argument to the -W option. The string is first split using the characters in the IFS special variable as delimiters. This honors shell quoting within the string, in order to provide a mechanism for the words to contain shell metacharacters or characters in the value of IFS. Each word is then expanded using brace expansion, tilde expansion, parameter and variable expansion, command substitution, and arithmetic expansion, as described above (see Shell Expansions). The results are split using the rules described above (see Word Splitting). The results of the expansion are prefix-matched against the word being completed, and the matching words become possible completions.
After these matches have been generated, Bash executes any shell function or command specified with the -F and -C options. When the command or function is invoked, Bash assigns values to the COMP_LINE, COMP_POINT, COMP_KEY, and COMP_TYPE variables as described above (see Bash Variables). If a shell function is being invoked, Bash also sets the COMP_WORDS and COMP_CWORD variables. When the function or command is invoked, the first argument ($1) is the name of the command whose arguments are being completed, the second argument ($2) is the word being completed, and the third argument ($3) is the word preceding the word being completed on the current command line. There is no filtering of the generated completions against the word being completed; the function or command has complete freedom in generating the matches and they do not need to match a prefix of the word.
Any function specified with -F is invoked first. The function may use any of the shell facilities, including the compgen and compopt builtins described below (see Programmable Completion Builtins), to generate the matches. It must put the possible completions in the COMPREPLY array variable, one per array element.
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 will escape a newline, if necessary. These are added to the set of possible completions.
After generating all of the possible completions, Bash applies any filter specified with the -X option to the completions in 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 is removed from the list. A leading ‘!’ negates the pattern; in this case Bash removes any completion that does not match the pattern. If the nocasematch shell option is enabled (see the description of shopt in The Shopt Builtin), Bash performs the match without regard to the case of alphabetic characters.
Finally, programmable completion adds any prefix and suffix specified with the -P and -S options, respectively, to each completion, and returns the result to Readline as the list of possible completions.
If the previously-applied actions do not generate any matches, and the -o dirnames option was supplied to complete when the compspec was defined, Bash attempts directory name completion.
If the -o plusdirs option was supplied to complete when the compspec was defined, Bash attempts directory name completion and adds any matches to the set of possible completions.
By default, 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 and the Readline default of filename completion are disabled. If the -o bashdefault option was supplied to complete when the compspec was defined, and the compspec generates no matches, Bash attempts its default completions. If the compspec and, if attempted, the default Bash completions generate no matches, and the -o default option was supplied to complete when the compspec was defined, programmable completion performs Readline’s default completion.
The options supplied to complete and compopt can control how Readline treats the completions. For instance, the -o fullquote option tells Readline to quote the matches as if they were filenames. See the description of complete (see Programmable Completion Builtins) for details.
When a compspec indicates that it wants directory name completion, the programmable completion functions force Readline to append a slash to completed names which are symbolic links to directories, subject to the value of the mark-directories Readline variable, regardless of the setting of the mark-symlinked-directories Readline variable.
There is some support for dynamically modifying completions. This is most useful when used in combination with a default completion specified with -D. It’s possible for shell functions executed as completion functions to indicate that completion should be retried by returning an exit status of 124. If a shell function returns 124, and changes the compspec associated with the command on which completion is being attempted (supplied as the first argument when the function is executed), programmable completion restarts from the beginning, with an attempt to find a new compspec for that command. This can be used to build a set of completions dynamically as completion is attempted, rather than loading them all at once.
For instance, assuming that there is a library of compspecs, each kept in a file corresponding to the name of the command, the following default completion function would load completions dynamically:
_completion_loader()
{
. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
}
complete -D -F _completion_loader -o bashdefault -o default
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4