diff options
Diffstat (limited to 'doc/rluser.texi')
| -rw-r--r-- | doc/rluser.texi | 88 |
1 files changed, 84 insertions, 4 deletions
diff --git a/doc/rluser.texi b/doc/rluser.texi index 4a367ed..519c0de 100644 --- a/doc/rluser.texi +++ b/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 |