commit bash-20090806 snapshot

lib/readline/doc/rluser.texi

@@ -1579,10 +1579,15 @@ 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 @option{-E} option to @code{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 @option{-D} option to @code{complete} is used as the default.
 
 Once a compspec has been found, it is used to generate the list of
 matching words.
@@ -1686,6 +1691,28 @@ to completed names which are symbolic links to directories, subject to
 the value of the @var{mark-directories} Readline variable, regardless
 of the setting of the @var{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 @option{-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 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
+
 @node Programmable Completion Builtins
 @section Programmable Completion Builtins
 @cindex completion builtins
@@ -1721,10 +1748,10 @@ matches were generated.
 @item complete
 @btindex complete
 @example
-@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-E] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
+@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DE] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
 [-F @var{function}] [-C @var{command}] [-X @var{filterpat}]
 [-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]}
-@code{complete -pr [-E] [@var{name} @dots{}]}
+@code{complete -pr [-DE] [@var{name} @dots{}]}
 @end example
 
 Specify how arguments to each @var{name} should be completed.
@@ -1734,12 +1761,16 @@ reused as input.
 The @option{-r} option removes a completion specification for
 each @var{name}, or, if no @var{name}s are supplied, all
 completion specifications.
+The @option{-D} option indicates that the remaining options and actions should
+apply to the ``default'' command completion; that is, completion attempted
+on a command for which no completion has previously been defined.
 The @option{-E} option indicates that the remaining options and actions should
 apply to ``empty'' command completion; that is, completion attempted on a 
 blank line.
 
 The process of applying these completion specifications when word completion
-is attempted is described above (@pxref{Programmable Completion}).
+is attempted is described above (@pxref{Programmable Completion}).  The
+@option{-D} option takes precedence over @option{-E}.
 
 Other options, if specified, have the following meanings.
 The arguments to the @option{-G}, @option{-W}, and @option{-X} options
@@ -1913,7 +1944,7 @@ an error occurs adding a completion specification.
 @item compopt
 @btindex compopt
 @example
-@code{compopt} [-o @var{option}] [+o @var{option}] [@var{name}]
+@code{compopt} [-o @var{option}] [-DE] [+o @var{option}] [@var{name}]
 @end example
 Modify completion options for each @var{name} according to the
 @var{option}s, or for the currently-execution completion if no @var{name}s
@@ -1922,6 +1953,14 @@ If no @var{option}s are given, display the completion options for each
 @var{name} or the current completion.
 The possible values of @var{option} are those valid for the @code{complete}
 builtin described above.
+The @option{-D} option indicates that the remaining options should
+apply to the ``default'' command completion; that is, completion attempted
+on a command for which no completion has previously been defined.
+The @option{-E} option indicates that the remaining options should
+apply to ``empty'' command completion; that is, completion attempted on a 
+blank line.
+
+The @option{-D} option takes precedence over @option{-E}.
 
 The return value is true unless an invalid option is supplied, an attempt
 is made to modify the options for a @var{name} for which no completion