bash: Programmable Completion

1 
1 8.6 Programmable Completion
1 ===========================
1 
1 When word completion is attempted for an argument to a command for which
1 a completion specification (a COMPSPEC) has been defined using the
1 'complete' builtin (⇒Programmable Completion Builtins), the
1 programmable completion facilities are invoked.
1 
1    First, the command name is identified.  If a compspec has been
1 defined for that command, the compspec is used to generate the list of
1 possible completions for the word.  If the command word is the empty
1 string (completion attempted at the beginning of an empty line), any
1 compspec defined with the '-E' option to 'complete' is used.  If the
1 command word is a full pathname, a compspec for the full pathname is
1 searched for first.  If no compspec is found for the full pathname, an
1 attempt is made to find a compspec for the portion following the final
1 slash.  If those searches do not result in a compspec, any compspec
1 defined with the '-D' option to 'complete' is used as the default.
1 
1    Once a compspec has been found, it is used to generate the list of
1 matching words.  If a compspec is not found, the default Bash completion
1 described above (⇒Commands For Completion) is performed.
1 
1    First, the actions specified by the compspec are used.  Only matches
1 which are prefixed by the word being completed are returned.  When the
1 '-f' or '-d' option is used for filename or directory name completion,
11 the shell variable 'FIGNORE' is used to filter the matches.  ⇒Bash
 Variables, for a description of 'FIGNORE'.
1 
1    Any completions specified by a filename expansion pattern to the '-G'
1 option are generated next.  The words generated by the pattern need not
1 match the word being completed.  The 'GLOBIGNORE' shell variable is not
1 used to filter the matches, but the 'FIGNORE' shell variable is used.
1 
1    Next, the string specified as the argument to the '-W' option is
1 considered.  The string is first split using the characters in the 'IFS'
1 special variable as delimiters.  Shell quoting is honored.  Each word is
1 then expanded using brace expansion, tilde expansion, parameter and
1 variable expansion, command substitution, and arithmetic expansion, as
1 described above (⇒Shell Expansions).  The results are split using
1 the rules described above (⇒Word Splitting).  The results of the
1 expansion are prefix-matched against the word being completed, and the
1 matching words become the possible completions.
1 
1    After these matches have been generated, any shell function or
1 command specified with the '-F' and '-C' options is invoked.  When the
1 command or function is invoked, the 'COMP_LINE', 'COMP_POINT',
1 'COMP_KEY', and 'COMP_TYPE' variables are assigned values as described
1 above (⇒Bash Variables).  If a shell function is being invoked,
1 the 'COMP_WORDS' and 'COMP_CWORD' variables are also set.  When the
1 function or command is invoked, the first argument ($1) is the name of
1 the command whose arguments are being completed, the second argument
1 ($2) is the word being completed, and the third argument ($3) is the
1 word preceding the word being completed on the current command line.  No
1 filtering of the generated completions against the word being completed
1 is performed; the function or command has complete freedom in generating
1 the matches.
1 
1    Any function specified with '-F' is invoked first.  The function may
1 use any of the shell facilities, including the 'compgen' and 'compopt'
1 builtins described below (⇒Programmable Completion Builtins), to
1 generate the matches.  It must put the possible completions in the
1 'COMPREPLY' array variable, one per array element.
1 
1    Next, any command specified with the '-C' option is invoked in an
1 environment equivalent to command substitution.  It should print a list
1 of completions, one per line, to the standard output.  Backslash may be
1 used to escape a newline, if necessary.
1 
1    After all of the possible completions are generated, any filter
1 specified with the '-X' option is applied to the list.  The filter is a
1 pattern as used for pathname expansion; a '&' in the pattern is replaced
1 with the text of the word being completed.  A literal '&' may be escaped
1 with a backslash; the backslash is removed before attempting a match.
1 Any completion that matches the pattern will be removed from the list.
1 A leading '!' negates the pattern; in this case any completion not
1 matching the pattern will be removed.  If the 'nocasematch' shell option
1 (see the description of 'shopt' in ⇒The Shopt Builtin) is
1 enabled, the match is performed without regard to the case of alphabetic
1 characters.
1 
1    Finally, any prefix and suffix specified with the '-P' and '-S'
1 options are added to each member of the completion list, and the result
1 is returned to the Readline completion code as the list of possible
1 completions.
1 
1    If the previously-applied actions do not generate any matches, and
1 the '-o dirnames' option was supplied to 'complete' when the compspec
1 was defined, directory name completion is attempted.
1 
1    If the '-o plusdirs' option was supplied to 'complete' when the
1 compspec was defined, directory name completion is attempted and any
1 matches are added to the results of the other actions.
1 
1    By default, if a compspec is found, whatever it generates is returned
1 to the completion code as the full set of possible completions.  The
1 default Bash completions are not attempted, and the Readline default of
1 filename completion is disabled.  If the '-o bashdefault' option was
1 supplied to 'complete' when the compspec was defined, the default Bash
1 completions are attempted if the compspec generates no matches.  If the
1 '-o default' option was supplied to 'complete' when the compspec was
1 defined, Readline's default completion will be performed if the compspec
1 (and, if attempted, the default Bash completions) generate no matches.
1 
1    When a compspec indicates that directory name completion is desired,
1 the programmable completion functions force Readline to append a slash
1 to completed names which are symbolic links to directories, subject to
1 the value of the MARK-DIRECTORIES Readline variable, regardless of the
1 setting of the MARK-SYMLINKED-DIRECTORIES Readline variable.
1 
1    There is some support for dynamically modifying completions.  This is
1 most useful when used in combination with a default completion specified
1 with '-D'.  It's possible for shell functions executed as completion
1 handlers to indicate that completion should be retried by returning an
1 exit status of 124.  If a shell function returns 124, and changes the
1 compspec associated with the command on which completion is being
1 attempted (supplied as the first argument when the function is
1 executed), programmable completion restarts from the beginning, with an
1 attempt to find a new compspec for that command.  This allows a set of
1 completions to be built dynamically as completion is attempted, rather
1 than being loaded all at once.
1 
1    For instance, assuming that there is a library of compspecs, each
1 kept in a file corresponding to the name of the command, the following
1 default completion function would load completions dynamically:
1 
1      _completion_loader()
1      {
1          . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
1      }
1      complete -D -F _completion_loader -o bashdefault -o default
1