diff options
Diffstat (limited to 'readline/doc/rluser.texi')
| -rw-r--r-- | readline/doc/rluser.texi | 283 |
1 files changed, 237 insertions, 46 deletions
diff --git a/readline/doc/rluser.texi b/readline/doc/rluser.texi index 478b41fac3c..8a69c99313a 100644 --- a/readline/doc/rluser.texi +++ b/readline/doc/rluser.texi @@ -1,7 +1,6 @@ @comment %**start of header (This is for running Texinfo on a region.) @setfilename rluser.info @comment %**end of header (This is for running Texinfo on a region.) -@setchapternewpage odd @ignore This file documents the end user interface to the GNU command line @@ -10,7 +9,7 @@ use these features. There is a document entitled "readline.texinfo" which contains both end-user and programmer documentation for the GNU Readline Library. -Copyright (C) 1988-2005 Free Software Foundation, Inc. +Copyright (C) 1988--2011 Free Software Foundation, Inc. Authored by Brian Fox and Chet Ramey. @@ -48,6 +47,16 @@ command line editing interface. @ifset BashFeatures Command line editing is provided by the Readline library, which is used by several different programs, including Bash. +Command line editing is enabled by default when using an interactive shell, +unless the @option{--noediting} option is supplied at shell invocation. +Line editing is also used when using the @option{-e} option to the +@code{read} builtin command (@pxref{Bash Builtins}). +By default, the line editing commands are similar to those of Emacs. +A vi-style line editing interface is also available. +Line editing can be enabled at any time using the @option{-o emacs} or +@option{-o vi} options to the @code{set} builtin command +(@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or +@option{+o vi} options to @code{set}. @end ifset @menu @@ -336,7 +345,9 @@ file is taken from the value of the shell variable @env{INPUTRC}. If @ifclear BashFeatures file is taken from the value of the environment variable @env{INPUTRC}. If @end ifclear -that variable is unset, the default is @file{~/.inputrc}. +that variable is unset, the default is @file{~/.inputrc}. If that +file does not exist or cannot be read, the ultimate default is +@file{/etc/inputrc}. When a program which uses the Readline library starts up, the init file is read, and the key bindings are set. @@ -420,11 +431,34 @@ The string to insert at the beginning of the line when the @code{insert-comment} command is executed. The default value is @code{"#"}. +@item completion-display-width +@vindex completion-display-width +The number of screen columns used to display possible matches +when performing completion. +The value is ignored if it is less than 0 or greater than the terminal +screen width. +A value of 0 will cause matches to be displayed one per line. +The default value is -1. + @item completion-ignore-case +@vindex completion-ignore-case If set to @samp{on}, Readline performs filename matching and completion in a case-insensitive fashion. The default value is @samp{off}. +@item completion-map-case +@vindex completion-map-case +If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline +treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when +performing case-insensitive filename matching and completion. + +@item completion-prefix-display-length +@vindex completion-prefix-display-length +The length in characters of the common prefix of a list of possible +completions that is displayed without modification. When set to a +value greater than zero, common prefixes longer than this value are +replaced with an ellipsis when displaying possible completions. + @item completion-query-items @vindex completion-query-items The number of possible completions that determines when the user is @@ -456,12 +490,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 @@ -469,10 +514,16 @@ attempts word completion. The default is @samp{off}. @item history-preserve-point @vindex history-preserve-point -If set to @samp{on}, the history code attempts to place point at the +If set to @samp{on}, the history code attempts to place the point (the +current cursor position) at the same location on each history line retrieved with @code{previous-history} or @code{next-history}. The default is @samp{off}. +@item history-size +@vindex history-size +Set the maximum number of history entries saved in the history list. If +set to zero, the number of entries in the history list is not limited. + @item horizontal-scroll-mode @vindex horizontal-scroll-mode This variable can be set to either @samp{on} or @samp{off}. Setting it @@ -535,10 +586,17 @@ The default is @samp{off}. @vindex match-hidden-files This variable, when set to @samp{on}, causes Readline to match files whose names begin with a @samp{.} (hidden files) when performing filename -completion, unless the leading @samp{.} is +completion. +If set to @samp{off}, the leading @samp{.} must be supplied by the user in the filename to be completed. This variable is @samp{on} by default. +@item menu-complete-display-prefix +@vindex menu-complete-display-prefix +If set to @samp{on}, menu completion displays the common prefix of the +list of possible completions (which may be empty) before cycling through +the list. The default is @samp{off}. + @item output-meta @vindex output-meta If set to @samp{on}, Readline will display characters with the @@ -556,6 +614,13 @@ If set to @samp{on}, Readline will display completions with matches sorted horizontally in alphabetical order, rather than down the screen. The default is @samp{off}. +@item revert-all-at-newline +@vindex revert-all-at-newline +If set to @samp{on}, Readline will undo all changes to history lines +before returning when @code{accept-line} is executed. By default, +history lines may be modified and retain individual undo lists across +calls to @code{readline}. The default is @samp{off}. + @item show-all-if-ambiguous @vindex show-all-if-ambiguous This alters the default behavior of the completion functions. If @@ -575,6 +640,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 @@ -593,9 +672,11 @@ the command does. Once you know the name of the command, simply place on a line in the init file the name of the key you wish to bind the command to, a colon, and then the name of the -command. The name of the key -can be expressed in different ways, depending on what you find most -comfortable. +command. +There can be no space between the key name and the colon -- that will be +interpreted as part of the key name. +The name of the key can be expressed in different ways, depending on +what you find most comfortable. In addition to command names, readline allows keys to be bound to a string that is inserted when the key is pressed (a @var{macro}). @@ -937,12 +1018,22 @@ Move forward a character. Move back a character. @item forward-word (M-f) -Move forward to the end of the next word. Words are composed of -letters and digits. +Move forward to the end of the next word. +Words are composed of letters and digits. @item backward-word (M-b) -Move back to the start of the current or previous word. Words are -composed of letters and digits. +Move back to the start of the current or previous word. +Words are composed of letters and digits. + +@ifset BashFeatures +@item shell-forward-word () +Move forward to the end of the next word. +Words are delimited by non-quoted shell metacharacters. + +@item shell-backward-word () +Move back to the start of the current or previous word. +Words are delimited by non-quoted shell metacharacters. +@end ifset @item clear-screen (C-l) Clear the screen and redraw the current line, @@ -1029,10 +1120,14 @@ as if the @samp{!@var{n}} history expansion had been specified. @item yank-last-arg (M-. or M-_) Insert last argument to the previous command (the last word of the -previous history entry). With an -argument, behave exactly like @code{yank-nth-arg}. +previous history entry). +With a numeric argument, behave exactly like @code{yank-nth-arg}. Successive calls to @code{yank-last-arg} move back through the history -list, inserting the last argument of each line in turn. +list, inserting the last word (or the word specified by the argument to +the first call) of each line in turn. +Any numeric argument supplied to these successive calls determines +the direction to move through the history. A negative argument switches +the direction through the history (back or forward). The history expansion facilities are used to extract the last argument, as if the @samp{!$} history expansion had been specified. @@ -1138,6 +1233,17 @@ Word boundaries are the same as @code{forward-word}. Kill the word behind point. Word boundaries are the same as @code{backward-word}. +@ifset BashFeatures +@item shell-kill-word () +Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as @code{shell-forward-word}. + +@item shell-backward-kill-word () +Kill the word behind point. +Word boundaries are the same as @code{shell-backward-word}. +@end ifset + @item unix-word-rubout (C-w) Kill the word behind point, using white space as a word boundary. The killed text is saved on the kill-ring. @@ -1219,6 +1325,9 @@ The default is filename completion. @item possible-completions (M-?) List the possible completions of the text before point. +When displaying completions, Readline sets the number of columns used +for display to the value of @code{completion-display-width}, the value of +the environment variable @env{COLUMNS}, or the screen width, in that order. @item insert-completions (M-*) Insert all completions of the text before point that would have @@ -1238,6 +1347,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}). @@ -1293,6 +1407,11 @@ Attempt completion on the text before point, comparing the text against lines from the history list for possible completion matches. +@item dabbrev-expand () +Attempt menu completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. + @item complete-into-braces (M-@{) Perform filename completion and insert the list of possible completions enclosed within braces so the list is available to the shell @@ -1372,6 +1491,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. @@ -1481,7 +1609,7 @@ editing mode. While the Readline library does not have a full set of @code{vi} editing functions, it does contain enough to allow simple editing of the line. The Readline @code{vi} mode behaves as specified in -the @sc{posix} 1003.2 standard. +the @sc{posix} standard. @ifset BashFeatures In order to switch interactively between @code{emacs} and @code{vi} @@ -1515,10 +1643,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. @@ -1555,9 +1688,9 @@ completed, and the matching words become the possible completions. After these matches have been generated, any shell function or command specified with the @option{-F} and @option{-C} options is invoked. -When the command or function is invoked, the @env{COMP_LINE} and -@env{COMP_POINT} variables are assigned values as described above -(@pxref{Bash Variables}). +When the command or function is invoked, the @env{COMP_LINE}, +@env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are +assigned values as described above (@pxref{Bash Variables}). If a shell function is being invoked, the @env{COMP_WORDS} and @env{COMP_CWORD} variables are also set. When the function or command is invoked, the first argument is the @@ -1570,7 +1703,7 @@ the matches. Any function specified with @option{-F} is invoked first. The function may use any of the shell facilities, including the -@code{compgen} builtin described below +@code{compgen} and @code{compopt} builtins described below (@pxref{Programmable Completion Builtins}), to generate the matches. It must put the possible completions in the @env{COMPREPLY} array variable. @@ -1622,6 +1755,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 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: + +@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 @@ -1657,10 +1814,10 @@ matches were generated. @item complete @btindex complete @example -@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}] -[-P @var{prefix}] [-S @var{suffix}] [-X @var{filterpat}] [-F @var{function}] -[-C @var{command}] @var{name} [@var{name} @dots{}]} -@code{complete -pr [@var{name} @dots{}]} +@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 [-DE] [@var{name} @dots{}]} @end example Specify how arguments to each @var{name} should be completed. @@ -1670,9 +1827,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 @@ -1702,9 +1866,10 @@ Perform directory name completion if the compspec generates no matches. @item filenames Tell Readline that the compspec generates filenames, so it can perform any -filename-specific processing (like adding a slash to directory names or -suppressing trailing spaces). This option is intended to be used with -shell functions specified with @option{-F}. +filename-specific processing (like adding a slash to directory names +quoting special characters, or suppressing trailing spaces). +This option is intended to be used with shell functions specified +with @option{-F}. @item nospace Tell Readline not to append a space (the default) to words completed at @@ -1798,17 +1963,6 @@ User names. May also be specified as @option{-u}. Names of all shell variables. May also be specified as @option{-v}. @end table -@item -G @var{globpat} -The filename expansion pattern @var{globpat} is expanded to generate -the possible completions. - -@item -W @var{wordlist} -The @var{wordlist} is split using the characters in the -@env{IFS} special variable as delimiters, and each resultant word -is expanded. -The possible completions are the members of the resultant list which -match the word being completed. - @item -C @var{command} @var{command} is executed in a subshell environment, and its output is used as the possible completions. @@ -1819,13 +1973,9 @@ environment. When it finishes, the possible completions are retrieved from the value of the @env{COMPREPLY} array variable. -@item -X @var{filterpat} -@var{filterpat} is a pattern as used for filename expansion. -It is applied to the list of possible completions generated by the -preceding options and arguments, and each completion matching -@var{filterpat} is removed from the list. -A leading @samp{!} in @var{filterpat} negates the pattern; in this -case, any completion not matching @var{filterpat} is removed. +@item -G @var{globpat} +The filename expansion pattern @var{globpat} is expanded to generate +the possible completions. @item -P @var{prefix} @var{prefix} is added at the beginning of each possible completion @@ -1834,6 +1984,21 @@ after all other options have been applied. @item -S @var{suffix} @var{suffix} is appended to each possible completion after all other options have been applied. + +@item -W @var{wordlist} +The @var{wordlist} is split using the characters in the +@env{IFS} special variable as delimiters, and each resultant word +is expanded. +The possible completions are the members of the resultant list which +match the word being completed. + +@item -X @var{filterpat} +@var{filterpat} is a pattern as used for filename expansion. +It is applied to the list of possible completions generated by the +preceding options and arguments, and each completion matching +@var{filterpat} is removed from the list. +A leading @samp{!} in @var{filterpat} negates the pattern; in this +case, any completion not matching @var{filterpat} is removed. @end table The return value is true unless an invalid option is supplied, an option @@ -1842,5 +2007,31 @@ argument, an attempt is made to remove a completion specification for a @var{name} for which no specification exists, or an error occurs adding a completion specification. +@item compopt +@btindex compopt +@example +@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-executing completion if no @var{name}s +are supplied. +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 +specification exists, or an output error occurs. + @end table + @end ifset |