diff options
Diffstat (limited to 'readline/doc/readline.3')
| -rw-r--r-- | readline/doc/readline.3 | 111 |
1 files changed, 96 insertions, 15 deletions
diff --git a/readline/doc/readline.3 b/readline/doc/readline.3 index 90cd9971e8e..f79f4bbef21 100644 --- a/readline/doc/readline.3 +++ b/readline/doc/readline.3 @@ -6,9 +6,9 @@ .\" Case Western Reserve University .\" chet@ins.CWRU.Edu .\" -.\" Last Change: Tue Sep 13 12:07:26 EDT 2005 +.\" Last Change: Sat Aug 28 18:56:32 EDT 2010 .\" -.TH READLINE 3 "2005 Sep 13" "GNU Readline 5.1-beta1" +.TH READLINE 3 "2010 August 28" "GNU Readline 6.2" .\" .\" File Name macro. This used to be `.PN', for Path Name, .\" but Sun doesn't seem to like that very much. @@ -34,8 +34,8 @@ readline \- get a line from a user with editing \fBreadline\fP (\fIconst char *prompt\fP); .fi .SH COPYRIGHT -.if n Readline is Copyright (C) 1989\-2004 by the Free Software Foundation, Inc. -.if t Readline is Copyright \(co 1989\-2004 by the Free Software Foundation, Inc. +.if n Readline is Copyright (C) 1989\-2011 Free Software Foundation, Inc. +.if t Readline is Copyright \(co 1989\-2011 Free Software Foundation, Inc. .SH DESCRIPTION .LP .B readline @@ -76,7 +76,7 @@ is read with a non\-empty line, it is treated as a newline. .SH NOTATION .LP -An emacs-style notation is used to denote +An Emacs-style notation is used to denote keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n means Control\-N. Similarly, .I meta @@ -116,6 +116,8 @@ The name of this file is taken from the value of the .B INPUTRC environment variable. If that variable is unset, the default is .IR ~/.inputrc . +If that file does not exist or cannot be read, the ultimate default is +.IR /etc/inputrc . When a program which uses the readline library starts up, the init file is read, and the key bindings and variables are set. There are only a few basic constructs allowed in the @@ -168,6 +170,8 @@ command or the text of a macro and a key sequence to which it should be bound. The name may be specified in one of two ways: as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP prefixes, or as a key sequence. +The name and key sequence are separated by a colon. There can be no +whitespace between the name and the colon. .PP When using the form \fBkeyname\fP:\^\fIfunction-name\fP or \fImacro\fP, .I keyname @@ -356,11 +360,30 @@ This command is bound to in emacs mode and to .B # in vi command mode. +.TP +.B completion\-display\-width (-1) +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. .TP .B completion\-ignore\-case (Off) If set to \fBOn\fP, readline performs filename matching and completion in a case\-insensitive fashion. .TP +.B completion\-map\-case (Off) +If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline +treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when +performing case\-insensitive filename matching and completion. +.TP +.B completion\-prefix\-display\-length (0) +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. +.TP .B completion\-query\-items (100) This determines when the user is queried about viewing the number of possible completions @@ -384,27 +407,41 @@ mapped to \fBself-insert\fP. .TP .B editing\-mode (emacs) Controls whether readline begins with a set of key bindings similar -to emacs or vi. +to \fIEmacs\fP or \fIvi\fP. .B editing\-mode can be set to either .B emacs or .BR vi . .TP +.B echo\-control\-characters (On) +When set to \fBOn\fP, on operating systems that indicate they support it, +readline echoes a character corresponding to a signal generated from the +keyboard. +.TP .B enable\-keypad (Off) When set to \fBOn\fP, readline will try to enable the application keypad when it is called. Some systems need this to enable the arrow keys. .TP +.B enable\-meta\-key (On) +When set to \fBOn\fP, 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. +.TP .B expand\-tilde (Off) -If set to \fBon\fP, tilde expansion is performed when readline +If set to \fBOn\fP, tilde expansion is performed when readline attempts word completion. .TP .B history\-preserve\-point (Off) -If set to \fBon\fP, the history code attempts to place point at the +If set to \fBOn\fP, the history code attempts to place point at the same location on each history line retrieved with \fBprevious-history\fP or \fBnext-history\fP. .TP +.B history\-size (0) +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. +.TP .B horizontal\-scroll\-mode (Off) When set to \fBOn\fP, makes readline use a single line for display, scrolling the input horizontally on a single screen line when it @@ -451,9 +488,15 @@ have a slash appended (subject to the value of .B match\-hidden\-files (On) This variable, when set to \fBOn\fP, causes readline to match files whose names begin with a `.' (hidden files) when performing filename -completion, unless the leading `.' is +completion. +If set to \fBOff\fP, the leading `.' must be supplied by the user in the filename to be completed. .TP +.B menu\-complete\-display\-prefix (Off) +If set to \fBOn\fP, menu completion displays the common prefix of the +list of possible completions (which may be empty) before cycling through +the list. +.TP .B output\-meta (Off) If set to \fBOn\fP, readline will display characters with the eighth bit set directly rather than as a meta-prefixed escape @@ -467,10 +510,16 @@ to display a screenful of possible completions at a time. If set to \fBOn\fP, readline will display completions with matches sorted horizontally in alphabetical order, rather than down the screen. .TP +.B revert\-all\-at\-newline (Off) +If set to \fBOn\fP, readline will undo all changes to history lines +before returning when \fBaccept\-line\fP is executed. By default, +history lines may be modified and retain individual undo lists across +calls to \fBreadline\fP. +.TP .B show\-all\-if\-ambiguous (Off) This alters the default behavior of the completion functions. If set to -.BR on , +.BR On , words which have more than one possible completion cause the matches to be listed immediately instead of ringing the bell. .TP @@ -478,12 +527,20 @@ matches to be listed immediately instead of ringing the bell. This alters the default behavior of the completion functions in a fashion similar to \fBshow\-all\-if\-ambiguous\fP. If set to -.BR on , +.BR On , words which have more than one possible completion without any possible partial completion (the possible completions don't share a common prefix) cause the matches to be listed immediately instead of ringing the bell. .TP +.B skip\-completed\-text (Off) +If set to \fBOn\fP, 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. +.TP .B visible\-stats (Off) If set to \fBOn\fP, a character denoting a file's type as reported by \fIstat\fP(2) is appended to the filename when listing possible @@ -530,7 +587,7 @@ library sets the \fIapplication name\fP, and an initialization file can test for a particular value. This could be used to bind key sequences to functions useful for a specific program. For instance, the following command adds a -key sequence that quotes the current or previous word in Bash: +key sequence that quotes the current or previous word in \fBbash\fP: .sp 1 .RS .nf @@ -706,10 +763,14 @@ as if the "!\fIn\fP" history expansion had been specified. .B yank\-last\-arg (M\-.\^, M\-_\^) Insert the last argument to the previous command (the last word of -the previous history entry). With an argument, -behave exactly like \fByank\-nth\-arg\fP. +the previous history entry). +With a numeric argument, behave exactly like \fByank\-nth\-arg\fP. Successive calls to \fByank\-last\-arg\fP 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 "!$" history expansion had been specified. .PD @@ -884,6 +945,12 @@ only attempts filename completion under certain circumstances. .TP .B 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 \fBcompletion-display-width\fP, the value of +the environment variable +.SM +.BR COLUMNS , +or the screen width, in that order. .TP .B insert\-completions (M\-*) Insert all completions of the text before point @@ -904,6 +971,11 @@ through the list. This command is intended to be bound to \fBTAB\fP, but is unbound by default. .TP +.B menu\-complete\-backward +Identical to \fBmenu\-complete\fP, but moves backward through the list +of possible completions, as if \fBmenu\-complete\fP had been given a +negative argument. This command is unbound by default. +.TP .B delete\-char\-or\-list Deletes the character under the cursor if not at the beginning or end of the line (like \fBdelete-char\fP). @@ -977,6 +1049,15 @@ character. A negative count searches for previous occurrences. A character is read and point is moved to the previous occurrence of that character. A negative count searches for subsequent occurrences. .TP +.B 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\-[. +.TP .B insert\-comment (M\-#) Without a numeric argument, the value of the readline .B comment\-begin |