(bash.info.gz) Programmable Completion

Info Catalog

(bash.info.gz) Readline vi Mode

(bash.info.gz) Command Line Editing

(bash.info.gz) Programmable Completion Builtins

 
 8.6 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 ( 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 the empty
 string (completion attempted at the beginning of an empty line), any
 compspec defined with the '-E' option to 'complete' is used.  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.  If those searches do not result in a compspec, any compspec
 defined with the '-D' option to 'complete' is used as the default.
 
    Once a compspec has been found, it is used to generate the list of
 matching words.  If a compspec is not found, the default Bash completion
 described above ( Commands For Completion) 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.   Bash
 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, and arithmetic expansion, as
 described above ( Shell Expansions).  The results are split using
 the rules described above ( Word Splitting).  The results of the
 expansion are prefix-matched against the word being completed, and the
 matching words become the possible completions.
 
    After these matches have been generated, any shell function or
 command specified with the '-F' and '-C' options is invoked.  When the
 command or function is invoked, the 'COMP_LINE', 'COMP_POINT',
 'COMP_KEY', and 'COMP_TYPE' variables are assigned values as described
 above ( Bash Variables).  If a shell function is being invoked,
 the 'COMP_WORDS' and 'COMP_CWORD' variables are also set.  When the
 function or command is invoked, the first argument is the name of the
 command whose arguments are being completed, the second argument is the
 word being completed, and the third argument is the word preceding the
 word being completed on the current command line.  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' and 'compopt'
 builtins described below ( Programmable Completion Builtins), to
 generate the matches.  It must put the possible completions in the
 'COMPREPLY' array variable.
 
    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 the previously-applied actions do not generate any matches, and
 the '-o dirnames' option was supplied to 'complete' when the compspec
 was defined, directory name completion is attempted.
 
    If the '-o plusdirs' option was supplied to 'complete' when the
 compspec was defined, directory name completion is attempted and any
 matches are added to the results of the other actions.
 
    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 are not attempted, and the Readline default of
 filename completion is disabled.  If the '-o bashdefault' option was
 supplied to 'complete' when the compspec was defined, the default Bash
 completions are attempted if the compspec generates no matches.  If the
 '-o default' option was supplied to 'complete' when the compspec was
 defined, Readline's default completion will be performed if the compspec
 (and, if attempted, the default Bash completions) generate no matches.
 
    When a compspec indicates that directory name completion is desired,
 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
 handlers 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 allows a set of
 completions to be built dynamically as completion is attempted, rather
 than being loaded 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
 

Info Catalog

(bash.info.gz) Readline vi Mode

(bash.info.gz) Command Line Editing

(bash.info.gz) Programmable Completion Builtins