diff options
Diffstat (limited to 'readline/doc')
| -rw-r--r-- | readline/doc/history.3 | 21 | ||||
| -rw-r--r-- | readline/doc/hstech.texi | 36 | ||||
| -rw-r--r-- | readline/doc/hsuser.texi | 42 | ||||
| -rw-r--r-- | readline/doc/readline.3 | 92 | ||||
| -rw-r--r-- | readline/doc/rltech.texi | 54 | ||||
| -rw-r--r-- | readline/doc/rluser.texi | 143 | ||||
| -rw-r--r-- | readline/doc/version.texi | 12 |
7 files changed, 314 insertions, 86 deletions
diff --git a/readline/doc/history.3 b/readline/doc/history.3 index 7ddc26a..8de64f6 100644 --- a/readline/doc/history.3 +++ b/readline/doc/history.3 @@ -6,9 +6,9 @@ .\" Case Western Reserve University .\" chet.ramey@case.edu .\" -.\" Last Change: Sun May 24 18:01:17 EDT 2015 +.\" Last Change: Sun Oct 8 11:43:43 EDT 2017 .\" -.TH HISTORY 3 "2015 May 24" "GNU History 6.3" +.TH HISTORY 3 "2017 October 8" "GNU History 6.3" .\" .\" File Name macro. This used to be `.PN', for Path Name, .\" but Sun doesn't seem to like that very much. @@ -40,8 +40,8 @@ .SH NAME history \- GNU History Library .SH COPYRIGHT -.if t The GNU History Library is Copyright \(co 1989-2014 by the Free Software Foundation, Inc. -.if n The GNU History Library is Copyright (C) 1989-2014 by the Free Software Foundation, Inc. +.if t The GNU History Library is Copyright \(co 1989-2017 by the Free Software Foundation, Inc. +.if n The GNU History Library is Copyright (C) 1989-2017 by the Free Software Foundation, Inc. .SH DESCRIPTION Many programs read input from the user a line at a time. The GNU History library is able to keep track of those lines, associate arbitrary @@ -356,6 +356,9 @@ parameters managing the list itself. .Fn1 void add_history "const char *string" Place \fIstring\fP at the end of the history list. The associated data field (if any) is set to \fBNULL\fP. +If the maximum number of history entries has been set using +\fBstifle_history()\fP, and the new number of history entries would exceed +that maximum, the oldest history entry is removed. .Fn1 void add_history_time "const char *string" Change the time stamp associated with the most recent history entry to @@ -382,6 +385,7 @@ Clear the history list by deleting all the entries. .Fn1 void stifle_history "int max" Stifle the history list, remembering only the last \fImax\fP entries. +The history list will contain only \fImax\fP entries at a time. .Fn1 int unstifle_history "void" Stop stifling the history. This returns the previously-set @@ -411,10 +415,11 @@ Return the history entry at the current position, as determined by pointer. .Fn1 "HIST_ENTRY *" history_get "int offset" -Return the history entry at position \fIoffset\fP, starting from -\fBhistory_base\fP. -If there is no entry there, or if \fIoffset\fP -is greater than the history length, return a \fBNULL\fP pointer. +Return the history entry at position \fIoffset\fP. +The range of valid values of \fIoffset\fP starts at \fBhistory_base\fP +and ends at \fBhistory_length\fP \- 1. +If there is no entry there, or if \fIoffset\fP is outside the valid +range, return a \fBNULL\fP pointer. .Fn1 "time_t" history_get_time "HIST_ENTRY *" Return the time stamp associated with the history entry passed as the argument. diff --git a/readline/doc/hstech.texi b/readline/doc/hstech.texi index bba7b59..dbc21c1 100644 --- a/readline/doc/hstech.texi +++ b/readline/doc/hstech.texi @@ -166,6 +166,9 @@ parameters managing the list itself. @deftypefun void add_history (const char *string) Place @var{string} at the end of the history list. The associated data field (if any) is set to @code{NULL}. +If the maximum number of history entries has been set using +@code{stifle_history()}, and the new number of history entries would exceed +that maximum, the oldest history entry is removed. @end deftypefun @deftypefun void add_history_time (const char *string) @@ -198,6 +201,7 @@ Clear the history list by deleting all the entries. @deftypefun void stifle_history (int max) Stifle the history list, remembering only the last @var{max} entries. +The history list will contain only @var{max} entries at a time. @end deftypefun @deftypefun int unstifle_history (void) @@ -234,10 +238,12 @@ pointer. @end deftypefun @deftypefun {HIST_ENTRY *} history_get (int offset) -Return the history entry at position @var{offset}, starting from -@code{history_base} (@pxref{History Variables}). -If there is no entry there, or if @var{offset} -is greater than the history length, return a @code{NULL} pointer. +Return the history entry at position @var{offset}. +The range of valid +values of @var{offset} starts at @code{history_base} and ends at +@var{history_length} - 1 (@pxref{History Variables}). +If there is no entry there, or if @var{offset} is outside the valid +range, return a @code{NULL} pointer. @end deftypefun @deftypefun time_t history_get_time (HIST_ENTRY *entry) @@ -397,7 +403,7 @@ to the ``normal'' terminating characters. Return an array of tokens parsed out of @var{string}, much as the shell might. The tokens are split on the characters in the @var{history_word_delimiters} variable, -and shell quoting conventions are obeyed. +and shell quoting conventions are obeyed as described below. @end deftypefun @deftypefun {char *} history_arg_extract (int first, int last, const char *string) @@ -470,8 +476,24 @@ carriage return, and @samp{=}. @end deftypevar @deftypevar int history_quotes_inhibit_expansion -If non-zero, double-quoted words are not scanned for the history expansion -character or the history comment character. The default value is 0. +If non-zero, the history expansion code implements shell-like quoting: +single-quoted words are not scanned for the history expansion +character or the history comment character, and double-quoted words may +have history expansion performed, since single quotes are not special +within double quotes. +The default value is 0. +@end deftypevar + +@deftypevar int history_quoting_state +An application may set this variable to indicate that the current line +being expanded is subject to existing quoting. If set to @samp{'}, the +history expansion function will assume that the line is single-quoted and +inhibit expansion until it reads an unquoted closing single quote; if set +to @samp{"}, history expansion will assume the line is double quoted until +it reads an unquoted closing double quote. If set to zero, the default, +the history expansion function will assume the line is not quoted and +treat quote characters within the line as described above. +This is only effective if @var{history_quotes_inhibit_expansion} is set. @end deftypevar @deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function diff --git a/readline/doc/hsuser.texi b/readline/doc/hsuser.texi index 311933a..e92c794 100644 --- a/readline/doc/hsuser.texi +++ b/readline/doc/hsuser.texi @@ -1,7 +1,7 @@ @ignore This file documents the user interface to the GNU History library. -Copyright (C) 1988--2016 Free Software Foundation, Inc. +Copyright (C) 1988--2018 Free Software Foundation, Inc. Authored by Brian Fox and Chet Ramey. Permission is granted to make and distribute verbatim copies of this manual @@ -126,7 +126,7 @@ The @code{lithist} shell option causes the shell to save the command with embedded newlines instead of semicolons. The @code{shopt} builtin is used to set these options. -@xref{Bash Builtins}, for a description of @code{shopt}. +@xref{The Shopt Builtin}, for a description of @code{shopt}. @node Bash History Builtins @section Bash History Builtins @@ -151,8 +151,8 @@ Both @var{first} and @var{last} may be specified as a string (to locate the most recent command beginning with that string) or as a number (an index into the history list, where a negative number is used as an offset from the -current command number). If @var{last} is not specified it is set to -@var{first}. If @var{first} is not specified it is set to the previous +current command number). If @var{last} is not specified, it is set to +@var{first}. If @var{first} is not specified, it is set to the previous command for editing and @minus{}16 for listing. If the @option{-l} flag is given, the commands are listed on standard output. The @option{-n} flag suppresses the command numbers when listing. The @option{-r} flag @@ -178,6 +178,7 @@ and typing @samp{r} re-executes the last command (@pxref{Aliases}). history [@var{n}] history -c history -d @var{offset} +history -d @var{start}-@var{end} history [-anrw] [@var{filename}] history -ps @var{arg} @end example @@ -200,8 +201,17 @@ with the other options to replace the history list completely. @item -d @var{offset} Delete the history entry at position @var{offset}. -@var{offset} should be specified as it appears when the history is -displayed. +If @var{offset} is positive, it should be specified as it appears when +the history is displayed. +If @var{offset} is negative, it is interpreted as relative to one greater +than the last history position, so negative indices count back from the +end of the history, and an index of @samp{-1} refers to the current +@code{history -d} command. + +@item -d @var{start}-@var{end} +Delete the history entries between positions @var{start} and @var{end}, +inclusive. Positive and negative values for @var{start} and @var{end} +are interpreted as described above. @item -a Append the new history lines to the history file. @@ -253,7 +263,9 @@ fix errors in previous commands quickly. @ifset BashFeatures History expansion is performed immediately after a complete line -is read, before the shell breaks it into words. +is read, before the shell breaks it into words, and is performed +on each line individually. Bash attempts to inform the history +expansion functions about quoting still in effect from previous lines. @end ifset History expansion takes place in two parts. The first is to determine @@ -267,16 +279,26 @@ that Bash does, so that several words surrounded by quotes are considered one word. History expansions are introduced by the appearance of the history expansion character, which is @samp{!} by default. + +History expansion implements shell-like quoting conventions: +a backslash can be used to remove the special handling for the next character; +single quotes enclose verbatim sequences of characters, and can be used to +inhibit history expansion; +and characters enclosed within double quotes may be subject to history +expansion, since backslash can escape the history expansion character, +but single quotes may not, since they are not treated specially within +double quotes. + @ifset BashFeatures -Only @samp{\} and @samp{'} may be used to escape the history expansion -character, but the history expansion character is +When using the shell, only @samp{\} and @samp{'} may be used to escape the +history expansion character, but the history expansion character is also treated as quoted if it immediately precedes the closing double quote in a double-quoted string. @end ifset @ifset BashFeatures Several shell options settable with the @code{shopt} -builtin (@pxref{Bash Builtins}) may be used to tailor +builtin (@pxref{The Shopt Builtin}) may be used to tailor the behavior of history expansion. If the @code{histverify} shell option is enabled, and Readline is being used, history substitutions are not immediately passed to diff --git a/readline/doc/readline.3 b/readline/doc/readline.3 index b57f00b..be89c2d 100644 --- a/readline/doc/readline.3 +++ b/readline/doc/readline.3 @@ -6,9 +6,9 @@ .\" Case Western Reserve University .\" chet.ramey@case.edu .\" -.\" Last Change: Sun Feb 28 15:42:34 EST 2016 +.\" Last Change: Thu Dec 28 14:49:51 EST 2017 .\" -.TH READLINE 3 "2016 February 28" "GNU Readline 7.0" +.TH READLINE 3 "2017 December 28" "GNU Readline 7.0" .\" .\" File Name macro. This used to be `.PN', for Path Name, .\" but Sun doesn't seem to like that very much. @@ -378,13 +378,13 @@ in emacs mode and to .B # in vi command mode. .TP -.B completion\-display\-width (-1) +.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. +The default value is \-1. .TP .B completion\-ignore\-case (Off) If set to \fBOn\fP, readline performs filename matching and completion @@ -438,6 +438,16 @@ can be set to either or .BR vi . .TP +.B emacs\-mode\-string (@) +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when emacs editing mode is active. The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the \e1 and \e2 escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +.TP .B enable\-bracketed\-paste (Off) When set to \fBOn\fP, readline will configure the terminal in a way that will enable it to insert each paste into the editing buffer as a @@ -506,15 +516,6 @@ The value of .B editing\-mode also affects the default keymap. .TP -.B emacs\-mode\-string (@) -This string is displayed immediately before the last line of the primary -prompt when emacs editing mode is active. The value is expanded like a -key binding, so the standard set of meta- and control prefixes and -backslash escape sequences is available. -Use the \e1 and \e2 escapes to begin and end sequences of -non-printing characters, which can be used to embed a terminal control -sequence into the mode string. -.TP .B keyseq\-timeout (500) Specifies the duration \fIreadline\fP will wait for a character when reading an ambiguous key sequence (one that can form a complete key sequence using @@ -592,9 +593,9 @@ a common prefix) cause the matches to be listed immediately instead of ringing the bell. .TP .B show\-mode\-in\-prompt (Off) -If set to \fBOn\fP, add a character to the beginning of the prompt +If set to \fBOn\fP, add a string to the beginning of the prompt indicating the editing mode: emacs, vi command, or vi insertion. -The mode strings are user-settable. +The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP). .TP .B skip\-completed\-text (Off) If set to \fBOn\fP, this alters the default completion behavior when @@ -605,7 +606,8 @@ after point in the word being completed, so portions of the word following the cursor are not duplicated. .TP .B vi\-cmd\-mode\-string ((cmd)) -This string is displayed immediately before the last line of the primary +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary prompt when vi editing mode is active and in command mode. The value is expanded like a key binding, so the standard set of meta- and control prefixes and @@ -615,7 +617,8 @@ non-printing characters, which can be used to embed a terminal control sequence into the mode string. .TP .B vi\-ins\-mode\-string ((ins)) -This string is displayed immediately before the last line of the primary +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary prompt when vi editing mode is active and in insertion mode. The value is expanded like a key binding, so the standard set of meta- and control prefixes and @@ -640,8 +643,9 @@ The .B $if construct allows bindings to be made based on the editing mode, the terminal being used, or the application using -readline. The text of the test extends to the end of the line; -no characters are required to isolate it. +readline. The text of the test, after any comparison operator, +extends to the end of the line; +unless otherwise noted, no characters are required to isolate it. .RS .IP \fBmode\fP The \fBmode=\fP form of the \fB$if\fP directive is used to test @@ -663,6 +667,26 @@ to match both and .IR sun\-cmd , for instance. +.IP \fBversion\fP +The \fBversion\fP test may be used to perform comparisons against +specific readline versions. +The \fBversion\fP expands to the current readline version. +The set of comparison operators includes +.BR = , +(and +.BR == ), +.BR != , +.BR <= , +.BR >= , +.BR < , +and +.BR > . +The version number supplied on the right side of the operator consists +of a major version number, an optional decimal point, and an optional +minor version (e.g., \fB7.1\fP). If the minor version is omitted, it +is assumed to be \fB0\fP. +The operator may be separated from the string \fBversion\fP +and from the version number argument by whitespace. .IP \fBapplication\fP The \fBapplication\fP construct is used to include application-specific settings. Each program using the readline @@ -680,6 +704,15 @@ key sequence that quotes the current or previous word in \fBbash\fP: \fB$endif\fP .fi .RE +.IP \fIvariable\fP +The \fIvariable\fP construct provides simple equality tests for readline +variables and values. +The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP. +The variable name must be separated from the comparison operator by +whitespace; the operator may be separated from the value on the right hand +side by whitespace. +Both string and boolean variables may be tested. Boolean variables must be +tested against the values \fIon\fP and \fIoff\fP. .RE .IP \fB$endif\fP This command, as seen in the previous example, terminates an @@ -771,6 +804,19 @@ alphanumeric characters (letters and digits). Move back to the start of the current or previous word. Words are composed of alphanumeric characters (letters and digits). .TP +.B previous\-screen\-line +Attempt to move point to the same physical screen column on the previous +physical screen line. This will not have the desired effect if the current +Readline line does not take up more than one physical line or if point is not +greater than the length of the prompt plus the screen width. +.TP +.B next\-screen\-line +Attempt to move point to the same physical screen column on the next +physical screen line. This will not have the desired effect if the current +Readline line does not take up more than one physical line or if the length +of the current Readline line is not greater than the length of the prompt +plus the screen width. +.TP .B clear\-screen (C\-l) Clear the screen leaving the current line at the top of the screen. With an argument, refresh the current line without clearing the @@ -1103,6 +1149,7 @@ and store the definition. .B call\-last\-kbd\-macro (C\-x e) Re-execute the last keyboard macro defined, by making the characters in the macro appear as if typed at the keyboard. +.TP .B print\-last\-kbd\-macro () Print the last keyboard macro defined in a format suitable for the \fIinputrc\fP file. @@ -1120,9 +1167,10 @@ Abort the current editing command and ring the terminal's bell (subject to the setting of .BR bell\-style ). .TP -.B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...) -If the metafied character \fIx\fP is lowercase, run the command -that is bound to the corresponding uppercase character. +.B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, ...) +If the metafied character \fIx\fP is uppercase, run the command +that is bound to the corresponding metafied lowercase character. +The behavior is undefined if \fIx\fP is already lowercase. .TP .B prefix\-meta (ESC) Metafy the next character typed. diff --git a/readline/doc/rltech.texi b/readline/doc/rltech.texi index b8ce90f..28a02d9 100644 --- a/readline/doc/rltech.texi +++ b/readline/doc/rltech.texi @@ -90,6 +90,12 @@ If @code{readline} encounters an @code{EOF} while reading the line, and the line is empty at that point, then @code{(char *)NULL} is returned. Otherwise, the line is ended just as if a newline had been typed. +Readline performs some expansion on the @var{prompt} before it is +displayed on the screen. See the description of @code{rl_expand_prompt} +(@pxref{Redisplay}) for additional details, especially if @var{prompt} +will contain characters that do not consume physical screen space when +displayed. + If you want the user to be able to get at the line later, (with @key{C-p} for example), you must call @code{add_history()} to save the line away in a @dfn{history} list of such lines. @@ -688,6 +694,11 @@ Free all storage associated with @var{keymap}. This calls @code{rl_discard_keymap} to free subordindate keymaps and macros. @end deftypefun +@deftypefun int rl_empty_keymap (Keymap keymap) +Return non-zero if there are no keys bound to functions in @var{keymap}; +zero if there are any keys bound. +@end deftypefun + Readline has several internal keymaps. These functions allow you to change which keymap is active. @@ -709,6 +720,24 @@ Return the name matching @var{keymap}. @var{name} is one which would be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}). @end deftypefun +@deftypefun int rl_set_keymap_name (const char *name, Keymap keymap) +Set the name of @var{keymap}. This name will then be "registered" and +available for use in a @code{set keymap} inputrc directive +@pxref{Readline Init File}). +The @var{name} may not be one of Readline's builtin keymap names; +you may not add a different name for one of Readline's builtin keymaps. +You may replace the name associated with a given keymap by calling this +function more than once with the same @var{keymap} argument. +You may associate a registered @var{name} with a new keymap by calling this +function more than once with the same @var{name} argument. +There is no way to remove a named keymap once the name has been +registered. +Readline will make a copy of @var{name}. +The return value is greater than zero unless @var{name} is one of +Readline's builtin keymap names or @var{keymap} is one of Readline's +builtin keymaps. +@end deftypefun + @node Binding Keys @subsection Binding Keys @@ -835,6 +864,16 @@ Return the function invoked by @var{keyseq} in keymap @var{map}. If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is not @code{NULL}, the type of the object is returned in the @code{int} variable it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}). +It takes a "translated" key sequence and should not be used if the key sequence +can include NUL. +@end deftypefun + +@deftypefun {rl_command_func_t *} rl_function_of_keyseq_len (const char *keyseq, size_t len, Keymap map, int *type) +Return the function invoked by @var{keyseq} of length @var{len} +in keymap @var{map}. Equivalent to @code{rl_function_of_keyseq} with the +addition of the @var{len} parameter. +It takes a "translated" key sequence and should be used if the key sequence +can include NUL. @end deftypefun @deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function) @@ -1679,6 +1718,19 @@ handlers, depending on the values of @code{rl_catch_signals} and @code{rl_catch_sigwinch}. @end deftypefun +If an application wants to force Readline to handle any signals that +have arrived while it has been executing, @code{rl_check_signals()} +will call Readline's internal signal handler if there are any pending +signals. This is primarily intended for those applications that use +a custom @code{rl_getc_function} (@pxref{Readline Variables}) and wish +to handle signals received while waiting for input. + +@deftypefun void rl_check_signals (void) +If there are any pending signals, call Readline's internal signal handling +functions to process them. @code{rl_pending_signal()} can be used independently +to determine whether or not there are any pending signals. +@end deftypefun + If an application does not wish Readline to catch @code{SIGWINCH}, it may call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force Readline to update its idea of the terminal size when a @code{SIGWINCH} @@ -2094,6 +2146,8 @@ character (@samp{\0}) prevents anything being appended automatically. This can be changed in application-specific completion functions to provide the ``most sensible word separator character'' according to an application-specific command line syntax specification. +It is set to the default before any application-specific completion function +is called, and may only be changed within such a function. @end deftypevar @deftypevar int rl_completion_suppress_append diff --git a/readline/doc/rluser.texi b/readline/doc/rluser.texi index 4c094c8..a59bd14 100644 --- a/readline/doc/rluser.texi +++ b/readline/doc/rluser.texi @@ -475,6 +475,7 @@ The default value is @samp{off}. 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. +The default value is @samp{off}. @item completion-prefix-display-length @vindex completion-prefix-display-length @@ -524,7 +525,8 @@ set to either @samp{emacs} or @samp{vi}. @item emacs-mode-string @vindex emacs-mode-string -This string is displayed immediately before the last line of the primary +If the @var{show-mode-in-prompt} variable is enabled, +this string is displayed immediately before the last line of the primary prompt when emacs editing mode is active. The value is expanded like a key binding, so the standard set of meta- and control prefixes and backslash escape sequences is available. @@ -604,7 +606,7 @@ If this variable has not been given a value, the characters @key{ESC} and @item keymap @vindex keymap Sets Readline's idea of the current keymap for key binding commands. -Acceptable @code{keymap} names are +Built-in @code{keymap} names are @code{emacs}, @code{emacs-standard}, @code{emacs-meta}, @@ -615,6 +617,7 @@ Acceptable @code{keymap} names are @code{vi-insert}. @code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a synonym); @code{emacs} is equivalent to @code{emacs-standard}. +Applications may add additional names. The default value is @code{emacs}. The value of the @code{editing-mode} variable also affects the default keymap. @@ -714,9 +717,9 @@ The default value is @samp{off}. @item show-mode-in-prompt @vindex show-mode-in-prompt -If set to @samp{on}, add a character to the beginning of the prompt +If set to @samp{on}, add a string to the beginning of the prompt indicating the editing mode: emacs, vi command, or vi insertion. -The mode strings are user-settable. +The mode strings are user-settable (e.g., @var{emacs-mode-string}). The default value is @samp{off}. @item skip-completed-text @@ -735,7 +738,8 @@ The default value is @samp{off}. @item vi-cmd-mode-string @vindex vi-cmd-mode-string -This string is displayed immediately before the last line of the primary +If the @var{show-mode-in-prompt} variable is enabled, +this string is displayed immediately before the last line of the primary prompt when vi editing mode is active and in command mode. The value is expanded like a key binding, so the standard set of meta- and control prefixes and @@ -747,7 +751,8 @@ The default is @samp{(cmd)}. @item vi-ins-mode-string @vindex vi-ins-mode-string -This string is displayed immediately before the last line of the primary +If the @var{show-mode-in-prompt} variable is enabled, +this string is displayed immediately before the last line of the primary prompt when vi editing mode is active and in insertion mode. The value is expanded like a key binding, so the standard set of meta- and control prefixes and @@ -799,7 +804,7 @@ Meta-Rubout: backward-kill-word Control-o: "> output" @end example -In the above example, @kbd{C-u} is bound to the function +In the example above, @kbd{C-u} is bound to the function @code{universal-argument}, @kbd{M-DEL} is bound to the function @code{backward-kill-word}, and @kbd{C-o} is bound to run the macro @@ -914,8 +919,9 @@ of tests. There are four parser directives used. @item $if The @code{$if} construct allows bindings to be made based on the editing mode, the terminal being used, or the application using -Readline. The text of the test extends to the end of the line; -no characters are required to isolate it. +Readline. The text of the test, after any comparison operator, +extends to the end of the line; +unless otherwise noted, no characters are required to isolate it. @table @code @item mode @@ -935,6 +941,27 @@ the portion of the terminal name before the first @samp{-}. This allows @code{sun} to match both @code{sun} and @code{sun-cmd}, for instance. +@item version +The @code{version} test may be used to perform comparisons against +specific Readline versions. +The @code{version} expands to the current Readline version. +The set of comparison operators includes +@samp{=} (and @samp{==}), @samp{!=}, @samp{<=}, @samp{>=}, @samp{<}, +and @samp{>}. +The version number supplied on the right side of the operator consists +of a major version number, an optional decimal point, and an optional +minor version (e.g., @samp{7.1}). If the minor version is omitted, it +is assumed to be @samp{0}. +The operator may be separated from the string @code{version} and +from the version number argument by whitespace. +The following example sets a variable if the Readline version being used +is 7.0 or newer: +@example +$if version >= 7.0 +set show-mode-in-prompt on +$endif +@end example + @item application The @var{application} construct is used to include application-specific settings. Each program using the Readline @@ -949,6 +976,23 @@ $if Bash "\C-xq": "\eb\"\ef\"" $endif @end example + +@item variable +The @var{variable} construct provides simple equality tests for Readline +variables and values. +The permitted comparison operators are @samp{=}, @samp{==}, and @samp{!=}. +The variable name must be separated from the comparison operator by +whitespace; the operator may be separated from the value on the right hand +side by whitespace. +Both string and boolean variables may be tested. Boolean variables must be +tested against the values @var{on} and @var{off}. +The following example is equivalent to the @code{mode=emacs} test described +above: +@example +$if editing-mode == emacs +set show-mode-in-prompt on +$endif +@end example @end table @item $endif @@ -1138,6 +1182,19 @@ Move back to the start of the current or previous word. Words are delimited by non-quoted shell metacharacters. @end ifset +@item previous-screen-line () +Attempt to move point to the same physical screen column on the previous +physical screen line. This will not have the desired effect if the current +Readline line does not take up more than one physical line or if point is not +greater than the length of the prompt plus the screen width. + +@item next-screen-line () +Attempt to move point to the same physical screen column on the next +physical screen line. This will not have the desired effect if the current +Readline line does not take up more than one physical line or if the length +of the current Readline line is not greater than the length of the prompt +plus the screen width. + @item clear-screen (C-l) Clear the screen and redraw the current line, leaving the current line at the top of the screen. @@ -1216,14 +1273,14 @@ The search string must match at the beginning of a history line. This is a non-incremental search. By default, this command is unbound. -@item history-substr-search-forward () +@item history-substring-search-forward () Search forward through the history for the string of characters between the start of the current line and the point. The search string may match anywhere in a history line. This is a non-incremental search. By default, this command is unbound. -@item history-substr-search-backward () +@item history-substring-search-backward () Search backward through the history for the string of characters between the start of the current line and the point. The search string may match anywhere in a history line. @@ -1297,7 +1354,7 @@ This function is intended to be bound to the "bracketed paste" escape sequence sent by some terminals, and such a binding is assigned by default. It allows Readline to insert the pasted text as a single unit without treating each character as if it had been read from the keyboard. The characters -are inserted as if each one was bound to @code{self-insert}) instead of +are inserted as if each one was bound to @code{self-insert} instead of executing any editing commands. @item transpose-chars (C-t) @@ -1590,9 +1647,10 @@ Abort the current editing command and ring the terminal's bell (subject to the setting of @code{bell-style}). -@item do-uppercase-version (M-a, M-b, M-@var{x}, @dots{}) -If the metafied character @var{x} is lowercase, run the command -that is bound to the corresponding uppercase character. +@item do-lowercase-version (M-A, M-B, M-@var{x}, @dots{}) +If the metafied character @var{x} is upper case, run the command +that is bound to the corresponding metafied lower case character. +The behavior is undefined if @var{x} is already lower case. @item prefix-meta (@key{ESC}) Metafy the next character typed. This is for keyboards @@ -1718,10 +1776,11 @@ A synonym for @code{yank-last-arg}. @item operate-and-get-next (C-o) Accept the current line for execution and fetch the next line -relative to the current line from the history for editing. Any -argument is ignored. +relative to the current line from the history for editing. +A numeric argument, if supplied, specifies the history entry to use instead +of the current line. -@item edit-and-execute-command (C-xC-e) +@item edit-and-execute-command (C-x C-e) Invoke an editor on the current command line, and execute the result as shell commands. Bash attempts to invoke @@ -1792,6 +1851,9 @@ 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. +If there is no default compspec, Bash attempts alias expansion +on the command word as a final resort, and attempts to find a compspec +for the command word from any successful expansion Once a compspec has been found, it is used to generate the list of matching words. @@ -1816,7 +1878,9 @@ Next, the string specified as the argument to the @option{-W} option is considered. The string is first split using the characters in the @env{IFS} special variable as delimiters. -Shell quoting is honored. +Shell quoting is honored within the string, in order to provide a +mechanism for the words to contain shell metacharacters or characters +in the value of @env{IFS}. Each word is then expanded using brace expansion, tilde expansion, parameter and variable expansion, command substitution, and arithmetic expansion, @@ -1960,10 +2024,10 @@ matches were generated. @item complete @btindex complete @example -@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}] +@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DEI] [-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{}]} +@code{complete -pr [-DEI] [@var{name} @dots{}]} @end example Specify how arguments to each @var{name} should be completed. @@ -1973,16 +2037,24 @@ 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 +The @option{-D} option indicates that other supplied 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 +The @option{-E} option indicates that other supplied options and actions should apply to ``empty'' command completion; that is, completion attempted on a blank line. +The @option{-I} option indicates that other supplied options and actions should +apply to completion on the inital non-assignment word on the line, or after a +command delimiter such as @samp{;} or @samp{|}, which is usually command +name completion. +If multiple options are supplied, the @option{-D} option takes precedence +over @option{-E}, and both take precedence over @option{-I}. +If any of @option{-D}, @option{-E}, or @option{-I} are supplied, any other +@var{name} arguments are ignored; these completions only apply to the case +specified by the option. The process of applying these completion specifications when word completion -is attempted is described above (@pxref{Programmable Completion}). The -@option{-D} option takes precedence over @option{-E}. +is attempted is described above (@pxref{Programmable Completion}). Other options, if specified, have the following meanings. The arguments to the @option{-G}, @option{-W}, and @option{-X} options @@ -2012,7 +2084,7 @@ 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 +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}. @@ -2167,7 +2239,7 @@ an error occurs adding a completion specification. @item compopt @btindex compopt @example -@code{compopt} [-o @var{option}] [-DE] [+o @var{option}] [@var{name}] +@code{compopt} [-o @var{option}] [-DEI] [+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 @@ -2176,14 +2248,19 @@ 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 +The @option{-D} option indicates that other supplied 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 +The @option{-E} option indicates that other supplied options should apply to ``empty'' command completion; that is, completion attempted on a blank line. +The @option{-I} option indicates that other supplied options should +apply to completion on the inital non-assignment word on the line, or after a +command delimiter such as @samp{;} or @samp{|}, which is usually command +name completion. -The @option{-D} option takes precedence over @option{-E}. +If multiple options are supplied, the @option{-D} option takes precedence +over @option{-E}, and both take precedence over @option{-I} 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 @@ -2200,7 +2277,7 @@ a shell function and bind it to a particular command using @code{complete -F}. The following function provides completions for the @code{cd} builtin. It is a reasonably good example of what shell functions must do when -used for completion. This function uses the word passsed as @code{$2} +used for completion. This function uses the word passed as @code{$2} to determine the directory name to complete. You can also use the @code{COMP_WORDS} array variable; the current word is indexed by the @code{COMP_CWORD} variable. @@ -2230,7 +2307,7 @@ _comp_cd() local cur _skipdot _cdpath local i j k - # Tilde expansion, with side effect of expanding tilde to full pathname + # Tilde expansion, which also expands tilde to full pathname case "$2" in \~*) eval cur="$2" ;; *) cur=$2 ;; diff --git a/readline/doc/version.texi b/readline/doc/version.texi index 9dc2998..576c35c 100644 --- a/readline/doc/version.texi +++ b/readline/doc/version.texi @@ -1,10 +1,10 @@ @ignore -Copyright (C) 1988-2016 Free Software Foundation, Inc. +Copyright (C) 1988-2018 Free Software Foundation, Inc. @end ignore -@set EDITION 7.0 -@set VERSION 7.0 -@set UPDATED 16 July 2016 -@set UPDATED-MONTH July 2016 +@set EDITION 8.0 +@set VERSION 8.0 +@set UPDATED 30 November 2018 +@set UPDATED-MONTH November 2018 -@set LASTCHANGE Sat Jul 16 13:43:15 EDT 2016 +@set LASTCHANGE Fri Nov 30 22:50:53 EST 2018 |