Bash-4.1 distribution source

lib/readline/doc/rluser.texi

@@ -474,12 +474,23 @@ key bindings is used.  By default, Readline starts up in Emacs editing
 mode, where the keystrokes are most similar to Emacs.  This variable can be
 set to either @samp{emacs} or @samp{vi}.
 
+@item echo-control-characters
+When set to @samp{on}, on operating systems that indicate they support it,
+readline echoes a character corresponding to a signal generated from the
+keyboard.  The default is @samp{on}.
+
 @item enable-keypad
 @vindex enable-keypad
 When set to @samp{on}, Readline will try to enable the application
 keypad when it is called.  Some systems need this to enable the
 arrow keys.  The default is @samp{off}.
 
+@item enable-meta-key
+When set to @samp{on}, Readline will try to enable any meta modifier
+key the terminal claims to support when it is called.  On many terminals,
+the meta key is used to send eight-bit characters.
+The default is @samp{on}.
+
 @item expand-tilde
 @vindex expand-tilde
 If set to @samp{on}, tilde expansion is performed when Readline
@@ -606,6 +617,20 @@ a common prefix) cause the matches to be listed immediately instead
 of ringing the bell.
 The default value is @samp{off}.
 
+@item skip-completed-text
+@vindex skip-completed-text
+If set to @samp{on}, this alters the default completion behavior when
+inserting a single match into the line.  It's only active when
+performing completion in the middle of a word.  If enabled, readline
+does not insert characters from the completion that match characters
+after point in the word being completed, so portions of the word
+following the cursor are not duplicated.
+For instance, if this is enabled, attempting completion when the cursor
+is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile}
+rather than @samp{Makefilefile}, assuming there is a single possible
+completion.
+The default value is @samp{off}.
+
 @item visible-stats
 @vindex visible-stats
 If set to @samp{on}, a character denoting a file's type
@@ -1292,6 +1317,11 @@ through the list.
 This command is intended to be bound to @key{TAB}, but is unbound
 by default.
 
+@item menu-complete-backward ()
+Identical to @code{menu-complete}, but moves backward through the list
+of possible completions, as if @code{menu-complete} had been given a
+negative argument.
+
 @item delete-char-or-list ()
 Deletes the character under the cursor if not at the beginning or
 end of the line (like @code{delete-char}).
@@ -1431,6 +1461,15 @@ A character is read and point is moved to the previous occurrence
 of that character.  A negative count searches for subsequent
 occurrences.
 
+@item skip-csi-sequence ()
+Read enough characters to consume a multi-key sequence such as those
+defined for keys like Home and End.  Such sequences begin with a
+Control Sequence Indicator (CSI), usually ESC-[.  If this sequence is
+bound to "\e[", keys producing such sequences will have no effect
+unless explicitly bound to a readline command, instead of inserting
+stray characters into the editing buffer.  This is unbound by default,
+but usually bound to ESC-[.
+
 @item insert-comment (M-#)
 Without a numeric argument, the value of the @code{comment-begin}
 variable is inserted at the beginning of the current line.
@@ -1574,10 +1613,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.
@@ -1681,6 +1725,30 @@ 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:
+
+@example
+_completion_loader()
+@{
+	. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
+@}
+complete -D -F _completion_loader
+@end example
+
 @node Programmable Completion Builtins
 @section Programmable Completion Builtins
 @cindex completion builtins
@@ -1716,10 +1784,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.
@@ -1729,12 +1797,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
@@ -1908,7 +1980,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
@@ -1917,6 +1989,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