diff options
Diffstat (limited to 'lib/readline/doc')
| -rw-r--r-- | lib/readline/doc/history.texi | 26 | ||||
| -rw-r--r-- | lib/readline/doc/hstech.texi | 4 | ||||
| -rw-r--r-- | lib/readline/doc/hsuser.texi | 24 | ||||
| -rw-r--r-- | lib/readline/doc/rlman.texi | 27 | ||||
| -rw-r--r-- | lib/readline/doc/rltech.texi | 210 | ||||
| -rw-r--r-- | lib/readline/doc/rluser.texi | 228 | ||||
| -rw-r--r-- | lib/readline/doc/rluserman.texi | 27 | ||||
| -rw-r--r-- | lib/readline/doc/version.texi | 12 |
8 files changed, 442 insertions, 116 deletions
diff --git a/lib/readline/doc/history.texi b/lib/readline/doc/history.texi index 64945d86..a991fe5b 100644 --- a/lib/readline/doc/history.texi +++ b/lib/readline/doc/history.texi @@ -2,33 +2,25 @@ @c %**start of header (This is for running Texinfo on a region.) @setfilename history.info @settitle GNU History Library -@c %**end of header (This is for running Texinfo on a region.) - @include version.texi +@c %**end of header (This is for running Texinfo on a region.) + @copying This document describes the GNU History library (version @value{VERSION}, @value{UPDATED}), a programming tool that provides a consistent user interface for recalling lines of previously typed input. -Copyright @copyright{} 1988--2011 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +Copyright @copyright{} 1988--2014 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license is -included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: You are free to copy and modify -this GNU manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled +``GNU Free Documentation License''. @end quotation @end copying @@ -50,12 +42,6 @@ developing GNU and promoting software freedom.'' @vskip 0pt plus 1filll @insertcopying -@sp 1 -Published by the Free Software Foundation @* -59 Temple Place, Suite 330, @* -Boston, MA 02111-1307 @* -USA @* - @end titlepage @contents diff --git a/lib/readline/doc/hstech.texi b/lib/readline/doc/hstech.texi index 4fc9e8ef..6487f20b 100644 --- a/lib/readline/doc/hstech.texi +++ b/lib/readline/doc/hstech.texi @@ -1,7 +1,7 @@ @ignore This file documents the user interface to the GNU History library. -Copyright (C) 1988-2011 Free Software Foundation, Inc. +Copyright (C) 1988-2014 Free Software Foundation, Inc. Authored by Brian Fox and Chet Ramey. Permission is granted to make and distribute verbatim copies of this manual @@ -377,7 +377,7 @@ if the returned line should be displayed, but not executed, as with the @code{:p} modifier (@pxref{Modifiers}). @end table -If an error ocurred in expansion, then @var{output} contains a descriptive +If an error occurred in expansion, then @var{output} contains a descriptive error message. @end deftypefun diff --git a/lib/readline/doc/hsuser.texi b/lib/readline/doc/hsuser.texi index 75df3ee4..69a50163 100644 --- a/lib/readline/doc/hsuser.texi +++ b/lib/readline/doc/hsuser.texi @@ -1,7 +1,7 @@ @ignore This file documents the user interface to the GNU History library. -Copyright (C) 1988--2011 Free Software Foundation, Inc. +Copyright (C) 1988--2014 Free Software Foundation, Inc. Authored by Brian Fox and Chet Ramey. Permission is granted to make and distribute verbatim copies of this manual @@ -84,17 +84,18 @@ file named by the @env{HISTFILE} variable (default @file{~/.bash_history}). The file named by the value of @env{HISTFILE} is truncated, if necessary, to contain no more than the number of lines specified by the value of the @env{HISTFILESIZE} variable. -When an interactive shell exits, the last +When a shell with history enabled exits, the last @env{$HISTSIZE} lines are copied from the history list to the file named by @env{$HISTFILE}. If the @code{histappend} shell option is set (@pxref{Bash Builtins}), the lines are appended to the history file, otherwise the history file is overwritten. If @env{HISTFILE} -is unset, or if the history file is unwritable, the history is -not saved. After saving the history, the history file is truncated -to contain no more than @env{$HISTFILESIZE} -lines. If @env{HISTFILESIZE} is not set, no truncation is performed. +is unset, or if the history file is unwritable, the history is not saved. +After saving the history, the history file is truncated +to contain no more than @env{$HISTFILESIZE} lines. +If @env{HISTFILESIZE} is unset, or set to null, a non-numeric value, or +a numeric value less than zero, the history file is not truncated. If the @env{HISTTIMEFORMAT} is set, the time stamp information associated with each history entry is written to the history file, @@ -141,8 +142,10 @@ history list and history file. @code{fc -s [@var{pat}=@var{rep}] [@var{command}]} @end example -Fix Command. In the first form, a range of commands from @var{first} to -@var{last} is selected from the history list. Both @var{first} and +The first form selects a range of commands from @var{first} to +@var{last} from the history list and displays or edits and re-executes +them. +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 @@ -161,6 +164,7 @@ When editing is complete, the edited commands are echoed and executed. In the second form, @var{command} is re-executed after each instance of @var{pat} in the selected command is replaced by @var{rep}. +@var{command} is intepreted the same as @var{first} above. A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so that typing @samp{r cc} runs the last command beginning with @code{cc} @@ -208,11 +212,11 @@ to the current history list. These are lines appended to the history file since the beginning of the current Bash session. @item -r -Read the current history file and append its contents to +Read the history file and append its contents to the history list. @item -w -Write out the current history to the history file. +Write out the current history list to the history file. @item -p Perform history substitution on the @var{arg}s and display the result diff --git a/lib/readline/doc/rlman.texi b/lib/readline/doc/rlman.texi index 1c9ac133..17a8292b 100644 --- a/lib/readline/doc/rlman.texi +++ b/lib/readline/doc/rlman.texi @@ -2,34 +2,26 @@ @comment %**start of header (This is for running Texinfo on a region.) @setfilename readline.info @settitle GNU Readline Library +@include version.texi + @comment %**end of header (This is for running Texinfo on a region.) @synindex vr fn -@include version.texi - @copying This manual describes the GNU Readline Library (version @value{VERSION}, @value{UPDATED}), a library which aids in the consistency of user interface across discrete programs which provide a command line interface. -Copyright @copyright{} 1988--2011 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +Copyright @copyright{} 1988--2014 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license is -included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: You are free to copy and modify -this GNU manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled +``GNU Free Documentation License''. @end quotation @end copying @@ -50,12 +42,6 @@ developing GNU and promoting software freedom.'' @vskip 0pt plus 1filll @insertcopying -@sp 1 -Published by the Free Software Foundation @* -59 Temple Place, Suite 330, @* -Boston, MA 02111-1307 @* -USA @* - @end titlepage @contents @@ -67,6 +53,7 @@ USA @* This document describes the GNU Readline Library, a utility which aids in the consistency of user interface across discrete programs which provide a command line interface. +The Readline home page is @url{http://www.gnu.org/software/readline/}. @menu * Command Line Editing:: GNU Readline User's Manual. diff --git a/lib/readline/doc/rltech.texi b/lib/readline/doc/rltech.texi index dc272a21..40de49c4 100644 --- a/lib/readline/doc/rltech.texi +++ b/lib/readline/doc/rltech.texi @@ -7,7 +7,7 @@ This document describes the GNU Readline Library, a utility for aiding in the consistency of user interface across discrete programs that need to provide a command line interface. -Copyright (C) 1988--2011 Free Software Foundation, Inc. +Copyright (C) 1988--2014 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -195,7 +195,7 @@ For Readline 4.2, for example, the value of @node Readline Typedefs @subsection Readline Typedefs -For readabilty, we declare a number of new object types, all pointers +For readability, we declare a number of new object types, all pointers to functions. The reason for declaring these new types is to make it easier to write @@ -440,6 +440,35 @@ If non-zero, Readline will call indirectly through this pointer to get a character from the input stream. By default, it is set to @code{rl_getc}, the default Readline character input function (@pxref{Character Input}). +In general, an application that sets @var{rl_getc_function} should consider +setting @var{rl_input_available_hook} as well. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_signal_event_hook +If non-zero, this is the address of a function to call if a read system +call is interrupted when Readline is reading terminal input. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_input_available_hook +If non-zero, Readline will use this function's return value when it needs +to determine whether or not there is available input on the current input +source. +The default hook checks @code{rl_instream}; if an application is using a +different input source, it should set the hook appropriately. +Readline queries for available input when implementing intra-key-sequence +timeouts during input and incremental searches. +This may use an application-specific timeout before returning a value; +Readline uses the value passed to @code{rl_set_keyboard_input_timeout()} +or the value of the user-settable @var{keyseq-timeout} variable. +This is designed for use by applications using Readline's callback interface +(@pxref{Alternate Interface}), which may not use the traditional +@code{read(2)} and file descriptor interface, or other applications using +a different input mechanism. +If an application uses an input mechanism or hook that can potentially exceed +the value of @var{keyseq-timeout}, it should increase the timeout or set +this hook appropriately even when not using the callback interface. +In general, an application that sets @var{rl_getc_function} should consider +setting @var{rl_input_available_hook} as well. @end deftypevar @deftypevar {rl_voidfunc_t *} rl_redisplay_function @@ -479,6 +508,19 @@ last key binding occurred. This variable is set to the text of any currently-executing macro. @end deftypevar +@deftypevar int rl_executing_key +The key that caused the dispatch to the currently-executing Readline function. +@end deftypevar + +@deftypevar {char *} rl_executing_keyseq +The full key sequence that caused the dispatch to the currently-executing +Readline function. +@end deftypevar + +@deftypevar int rl_key_sequence_length +The number of characters in @var{rl_executing_keyseq}. +@end deftypevar + @deftypevar {int} rl_readline_state A variable with bit values that encapsulate the current Readline state. A bit is set with the @code{RL_SETSTATE} macro, and unset with the @@ -487,7 +529,7 @@ whether a particular state bit is set. Current state bits include: @table @code @item RL_STATE_NONE -Readline has not yet been called, nor has it begun to intialize. +Readline has not yet been called, nor has it begun to initialize. @item RL_STATE_INITIALIZING Readline is initializing its internal data structures. @item RL_STATE_INITIALIZED @@ -580,6 +622,7 @@ means that vi mode is active. * Miscellaneous Functions:: Functions that don't fall into any category. * Alternate Interface:: Using Readline in a `callback' fashion. * A Readline Example:: An example Readline function. +* Alternate Interface Example:: An example program using the alternate interface. @end menu @node Function Naming @@ -908,7 +951,7 @@ Readline thinks the screen display is correct. @deftypefun int rl_on_new_line (void) Tell the update functions that we have moved onto a new (empty) line, -usually after ouputting a newline. +usually after outputting a newline. @end deftypefun @deftypefun int rl_on_new_line_with_prompt (void) @@ -1241,21 +1284,29 @@ use all of a terminal's capabilities, and this function will return values for only those capabilities Readline uses. @end deftypefun +@deftypefun {void} rl_clear_history (void) +Clear the history list by deleting all of the entries, in the same manner +as the History library's @code{clear_history()} function. +This differs from @code{clear_history} because it frees private data +Readline saves in the history list. +@end deftypefun + @node Alternate Interface @subsection Alternate Interface An alternate interface is available to plain @code{readline()}. Some applications need to interleave keyboard I/O with file, device, or window system I/O, typically by using a main loop to @code{select()} -on various file descriptors. To accomodate this need, readline can +on various file descriptors. To accommodate this need, readline can also be invoked as a `callback' function from an event loop. There are functions available to make this easy. @deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler) Set up the terminal for readline I/O and display the initial expanded value of @var{prompt}. Save the value of @var{lhandler} to -use as a function to call when a complete line of input has been entered. -The function takes the text of the line as an argument. +use as a handler function to call when a complete line of input has been +entered. +The handler function receives the text of the line as an argument. @end deftypefun @deftypefun void rl_callback_read_char (void) @@ -1263,14 +1314,15 @@ Whenever an application determines that keyboard input is available, it should call @code{rl_callback_read_char()}, which will read the next character from the current input source. If that character completes the line, @code{rl_callback_read_char} will -invoke the @var{lhandler} function saved by @code{rl_callback_handler_install} -to process the line. +invoke the @var{lhandler} function installed by +@code{rl_callback_handler_install} to process the line. Before calling the @var{lhandler} function, the terminal settings are reset to the values they had before calling @code{rl_callback_handler_install}. If the @var{lhandler} function returns, +and the line handler remains installed, the terminal settings are modified for Readline's use again. -@code{EOF} is indicated by calling @var{lhandler} with a +@code{EOF} is indicated by calling @var{lhandler} with a @code{NULL} line. @end deftypefun @@ -1350,6 +1402,98 @@ invert_case_line (count, key) @} @end example +@node Alternate Interface Example +@subsection Alternate Interface Example + +Here is a complete program that illustrates Readline's alternate interface. +It reads lines from the terminal and displays them, providing the +standard history and TAB completion functions. +It understands the EOF character or "exit" to exit the program. + +@example +/* Standard include files. stdio.h is required. */ +#include <stdlib.h> +#include <unistd.h> + +/* Used for select(2) */ +#include <sys/types.h> +#include <sys/select.h> + +#include <stdio.h> + +/* Standard readline include files. */ +#include <readline/readline.h> +#include <readline/history.h> + +static void cb_linehandler (char *); + +int running; +const char *prompt = "rltest$ "; + +/* Callback function called for each line when accept-line executed, EOF + seen, or EOF character read. This sets a flag and returns; it could + also call exit(3). */ +static void +cb_linehandler (char *line) +@{ + /* Can use ^D (stty eof) or `exit' to exit. */ + if (line == NULL || strcmp (line, "exit") == 0) + @{ + if (line == 0) + printf ("\n"); + printf ("exit\n"); + /* This function needs to be called to reset the terminal settings, + and calling it from the line handler keeps one extra prompt from + being displayed. */ + rl_callback_handler_remove (); + + running = 0; + @} + else + @{ + if (*line) + add_history (line); + printf ("input line: %s\n", line); + free (line); + @} +@} + +int +main (int c, char **v) +@{ + fd_set fds; + int r; + + /* Install the line handler. */ + rl_callback_handler_install (prompt, cb_linehandler); + + /* Enter a simple event loop. This waits until something is available + to read on readline's input stream (defaults to standard input) and + calls the builtin character read callback to read it. It does not + have to modify the user's terminal settings. */ + running = 1; + while (running) + @{ + FD_ZERO (&fds); + FD_SET (fileno (rl_instream), &fds); + + r = select (FD_SETSIZE, &fds, NULL, NULL, NULL); + if (r < 0) + @{ + perror ("rltest: select"); + rl_callback_handler_remove (); + break; + @} + + if (FD_ISSET (fileno (rl_instream), &fds)) + rl_callback_read_char (); + @} + + printf ("rltest: Event loop has exited\n"); + return 0; +@} +@end example + @node Readline Signal Handling @section Readline Signal Handling @@ -1365,6 +1509,7 @@ functions to do so manually. Readline contains an internal signal handler that is installed for a number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, +@code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}). When one of these signals is received, the signal handler will reset the terminal attributes to those that were in effect before @@ -1397,19 +1542,28 @@ a signal handler, so Readline's internal signal state is not corrupted. @deftypevar int rl_catch_signals If this variable is non-zero, Readline will install signal handlers for -@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGALRM}, +@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}. The default value of @code{rl_catch_signals} is 1. @end deftypevar @deftypevar int rl_catch_sigwinch -If this variable is non-zero, Readline will install a signal handler for -@code{SIGWINCH}. +If this variable is set to a non-zero value, +Readline will install a signal handler for @code{SIGWINCH}. The default value of @code{rl_catch_sigwinch} is 1. @end deftypevar +@deftypevar int rl_change_environment +If this variable is set to a non-zero value, +and Readline is handling @code{SIGWINCH}, Readline will modify the +@var{LINES} and @var{COLUMNS} environment variables upon receipt of a +@code{SIGWINCH} + +The default value of @code{rl_change_environment} is 1. +@end deftypevar + If an application does not wish to have Readline catch any signals, or to handle signals other than those Readline catches (@code{SIGHUP}, for example), @@ -1477,7 +1631,7 @@ The following functions install and remove Readline's signal handlers. @deftypefun int rl_set_signals (void) Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT}, -@code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, +@code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of @code{rl_catch_signals} and @code{rl_catch_sigwinch}. @end deftypefun @@ -1611,7 +1765,7 @@ This calls @code{rl_complete_internal()} with an argument of @samp{*}. @end deftypefun @deftypefun int rl_completion_mode (rl_command_func_t *cfunc) -Returns the apppriate value to pass to @code{rl_complete_internal()} +Returns the appropriate value to pass to @code{rl_complete_internal()} depending on whether @var{cfunc} was called twice in succession and the values of the @code{show-all-if-ambiguous} and @code{show-all-if-unmodified} variables. @@ -1728,29 +1882,45 @@ the directory portion of the pathname the user typed. At the least, even if no other expansion is performed, this function should remove any quote characters from the directory name, because its result will be passed directly to @code{opendir()}. + The directory completion hook returns an integer that should be non-zero if the function modifies its directory argument. The function should not modify the directory argument if it returns 0. @end deftypevar -@ignore -@deftypevar extern rl_icppfunc_t *rl_directory_rewrite_hook; +@deftypevar {rl_icppfunc_t *} rl_directory_rewrite_hook; If non-zero, this is the address of a function to call when completing a directory name. This function takes the address of the directory name to be modified as an argument. Unlike @code{rl_directory_completion_hook}, it only modifies the directory name used in @code{opendir}, not what is displayed when the possible completions are printed or inserted. It is called before rl_directory_completion_hook. +At the least, even if no other expansion is performed, this function should +remove any quote characters from the directory name, because its result will +be passed directly to @code{opendir()}. -I'm not happy with how this works yet, so it's undocumented. +The directory rewrite hook returns an integer that should be non-zero if +the function modfies its directory argument. +The function should not modify the directory argument if it returns 0. +@end deftypevar + +@deftypevar {rl_icppfunc_t *} rl_filename_stat_hook +If non-zero, this is the address of a function for the completer to +call before deciding which character to append to a completed name. +This function modifies its filename name argument, and the modified value +is passed to @code{stat()} to determine the file's type and characteristics. +This function does not need to remove quote characters from the filename. + +The stat hook returns an integer that should be non-zero if +the function modfies its directory argument. +The function should not modify the directory argument if it returns 0. @end deftypevar -@end ignore @deftypevar {rl_dequote_func_t *} rl_filename_rewrite_hook If non-zero, this is the address of a function called when reading directory entries from the filesystem for completion and comparing them to the partial word to be completed. The function should -perform any necesary application or system-specific conversion on +perform any necessary application or system-specific conversion on the filename, such as converting between character sets or converting from a filesystem format to a character input format. The function takes two arguments: @var{fname}, the filename to be converted, diff --git a/lib/readline/doc/rluser.texi b/lib/readline/doc/rluser.texi index 8a69c993..0af6c02e 100644 --- a/lib/readline/doc/rluser.texi +++ b/lib/readline/doc/rluser.texi @@ -9,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--2011 Free Software Foundation, Inc. +Copyright (C) 1988--2014 Free Software Foundation, Inc. Authored by Brian Fox and Chet Ramey. @@ -72,6 +72,8 @@ Line editing can be enabled at any time using the @option{-o emacs} or a specific command. * Programmable Completion Builtins:: Builtin commands to specify how to complete arguments for a particular command. +* A Programmable Completion Example:: An example shell function for + generating possible completions. @end ifset @end menu @@ -425,6 +427,14 @@ If set to @samp{on}, Readline attempts to bind the control characters treated specially by the kernel's terminal driver to their Readline equivalents. +@item colored-stats +@vindex colored-stats +If set to @samp{on}, Readline displays possible completions using different +colors to indicate their file type. +The color definitions are taken from the value of the @env{LS_COLORS} +environment variable. +The default is @samp{off}. + @item comment-begin @vindex comment-begin The string to insert at the beginning of the line when the @@ -521,8 +531,12 @@ 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. +Set the maximum number of history entries saved in the history list. +If set to zero, any existing history entries are deleted and no new entries +are saved. +If set to a value less than zero, the number of history entries is not +limited. +By default, the number of history entries is not limited. @item horizontal-scroll-mode @vindex horizontal-scroll-mode @@ -565,6 +579,22 @@ equivalent to @code{emacs-standard}. The default value is @code{emacs}. The value of the @code{editing-mode} variable also affects the default keymap. +@item keyseq-timeout +Specifies the duration Readline will wait for a character when reading an +ambiguous key sequence (one that can form a complete key sequence using +the input read so far, or can take additional input to complete a longer +key sequence). +If no input is received within the timeout, Readline will use the shorter +but complete key sequence. +Readline uses this value to determine whether or not input is +available on the current input source (@code{rl_instream} by default). +The value is specified in milliseconds, so a value of 1000 means that +Readline will wait one second for additional input. +If this variable is set to a value less than or equal to zero, or to a +non-numeric value, Readline will wait until another key is pressed to +decide which key sequence to complete. +The default value is @code{500}. + @item mark-directories If set to @samp{on}, completed directory names have a slash appended. The default is @samp{on}. @@ -640,6 +670,13 @@ a common prefix) cause the matches to be listed immediately instead of ringing the bell. 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 +indicating the editing mode: emacs (@samp{@@}), vi command (@samp{:}), +or vi insertion (@samp{+}). +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 @@ -880,7 +917,7 @@ binding, variable assignment, and conditional syntax. # You can re-read the inputrc file with C-x C-r. # Lines beginning with '#' are comments. # -# First, include any systemwide bindings and variable +# First, include any system-wide bindings and variable # assignments from /etc/Inputrc $include /etc/Inputrc @@ -1100,13 +1137,30 @@ for a string supplied by the user. @item history-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 must match at the beginning of a history line. This is a non-incremental search. By default, this command is unbound. @item history-search-backward () Search backward through the history for the string of characters -between the start of the current line and the point. This -is a non-incremental search. By default, this command is unbound. +between the start of the current line and the point. +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 () +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 () +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. +This is a non-incremental search. +By default, this command is unbound. @item yank-nth-arg (M-C-y) Insert the first argument to the previous command (usually @@ -1137,11 +1191,17 @@ as if the @samp{!$} history expansion had been specified. @subsection Commands For Changing Text @ftable @code + +@item @i{end-of-file} (usually C-d) +The character indicating end-of-file as set, for example, by +@code{stty}. If this character is read when there are no characters +on the line, and point is at the beginning of the line, Readline +interprets it as the end of input and returns @sc{eof}. + @item delete-char (C-d) -Delete the character at point. If point is at the -beginning of the line, there are no characters in the line, and -the last character typed was not bound to @code{delete-char}, then -return @sc{eof}. +Delete the character at point. If this function is bound to the +same character as the tty @sc{eof} character, as @kbd{C-d} +commonly is, see above for the effects. @item backward-delete-char (Rubout) Delete the character behind the cursor. A numeric argument means @@ -1435,6 +1495,10 @@ and save the definition. Re-execute the last keyboard macro defined, by making the characters in the macro appear as if typed at the keyboard. +@item print-last-kbd-macro () +Print the last keboard macro defined in a format suitable for the +@var{inputrc} file. + @end ftable @node Miscellaneous Commands @@ -1693,10 +1757,11 @@ When the command or function is invoked, the @env{COMP_LINE}, 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 +When the function or command is invoked, the first argument ($1) is the name of the command whose arguments are being completed, the -second argument is the word being completed, and the third argument -is the word preceding the word being completed on the current command line. +second argument ($2) is the word being completed, and the third argument +($3) is the word preceding the word being completed on the current command +line. No filtering of the generated completions against the word being completed is performed; the function or command has complete freedom in generating the matches. @@ -1706,7 +1771,7 @@ The function may use any of the shell facilities, including the @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. +variable, one per array element. Next, any command specified with the @option{-C} option is invoked in an environment equivalent to command substitution. @@ -1774,17 +1839,18 @@ completion function would load completions dynamically: @example _completion_loader() @{ - . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 + . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 @} -complete -D -F _completion_loader +complete -D -F _completion_loader -o bashdefault -o default @end example @node Programmable Completion Builtins @section Programmable Completion Builtins @cindex completion builtins -Two builtin commands are available to manipulate the programmable completion -facilities. +Three builtin commands are available to manipulate the programmable completion +facilities: one to specify how the arguments to a particular command are to +be completed, and two to modify the completion as it is happening. @table @code @item compgen @@ -1871,6 +1937,10 @@ quoting special characters, or suppressing trailing spaces). This option is intended to be used with shell functions specified with @option{-F}. +@item noquote +Tell Readline not to quote the completed words if they are filenames +(quoting filenames is the default). + @item nospace Tell Readline not to append a space (the default) to words completed at the end of the line. @@ -1970,6 +2040,10 @@ used as the possible completions. @item -F @var{function} The shell function @var{function} is executed in the current shell environment. +When it is executed, $1 is the name of the command whose arguments are +being completed, $2 is the word being completed, and $3 is the word +preceding the word being completed, as described above +(@pxref{Programmable Completion}). When it finishes, the possible completions are retrieved from the value of the @env{COMPREPLY} array variable. @@ -2034,4 +2108,122 @@ specification exists, or an output error occurs. @end table +@node A Programmable Completion Example +@section A Programmable Completion Example + +The most common way to obtain additional completion functionality beyond +the default actions @code{complete} and @code{compgen} provide is to use +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} +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. + +The function relies on the @code{complete} and @code{compgen} builtins +to do much of the work, adding only the things that the Bash @code{cd} +does beyond accepting basic directory names: +tilde expansion (@pxref{Tilde Expansion}), +searching directories in @var{$CDPATH}, which is described above +(@pxref{Bourne Shell Builtins}), +and basic support for the @code{cdable_vars} shell option +(@pxref{The Shopt Builtin}). +@code{_comp_cd} modifies the value of @var{IFS} so that it contains only +a newline to accommodate file names containing spaces and tabs -- +@code{compgen} prints the possible completions it generates one per line. + +Possible completions go into the @var{COMPREPLY} array variable, one +completion per array element. The programmable completion system retrieves +the completions from there when the function returns. + +@example +# A completion function for the cd builtin +# based on the cd completion function from the bash_completion package +_comp_cd() +@{ + local IFS=$' \t\n' # normalize IFS + local cur _skipdot _cdpath + local i j k + + # Tilde expansion, with side effect of expanding tilde to full pathname + case "$2" in + \~*) eval cur="$2" ;; + *) cur=$2 ;; + esac + + # no cdpath or absolute pathname -- straight directory completion + if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then + # compgen prints paths one per line; could also use while loop + IFS=$'\n' + COMPREPLY=( $(compgen -d -- "$cur") ) + IFS=$' \t\n' + # CDPATH+directories in the current directory if not in CDPATH + else + IFS=$'\n' + _skipdot=false + # preprocess CDPATH to convert null directory names to . + _cdpath=$@{CDPATH/#:/.:@} + _cdpath=$@{_cdpath//::/:.:@} + _cdpath=$@{_cdpath/%:/:.@} + for i in $@{_cdpath//:/$'\n'@}; do + if [[ $i -ef . ]]; then _skipdot=true; fi + k="$@{#COMPREPLY[@@]@}" + for j in $( compgen -d -- "$i/$cur" ); do + COMPREPLY[k++]=$@{j#$i/@} # cut off directory + done + done + $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") ) + IFS=$' \t\n' + fi + + # variable names if appropriate shell option set and no completions + if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then + COMPREPLY=( $(compgen -v -- "$cur") ) + fi + + return 0 +@} +@end example + +We install the completion function using the @option{-F} option to +@code{complete}: + +@example +# Tell readline to quote appropriate and append slashes to directories; +# use the bash default completion for other arguments +complete -o filenames -o nospace -o bashdefault -F _comp_cd cd +@end example + +@noindent +Since we'd like Bash and Readline to take care of some +of the other details for us, we use several other options to tell Bash +and Readline what to do. The @option{-o filenames} option tells Readline +that the possible completions should be treated as filenames, and quoted +appropriately. That option will also cause Readline to append a slash to +filenames it can determine are directories (which is why we might want to +extend @code{_comp_cd} to append a slash if we're using directories found +via @var{CDPATH}: Readline can't tell those completions are directories). +The @option{-o nospace} option tells Readline to not append a space +character to the directory name, in case we want to append to it. +The @option{-o bashdefault} option brings in the rest of the "Bash default" +completions -- possible completion that Bash adds to the default Readline +set. These include things like command name completion, variable completion +for words beginning with @samp{@{}, completions containing pathname +expansion patterns (@pxref{Filename Expansion}), and so on. + +Once installed using @code{complete}, @code{_comp_cd} will be called every +time we attempt word completion for a @code{cd} command. + +Many more examples -- an extensive collection of completions for most of +the common GNU, Unix, and Linux commands -- are available as part of the +bash_completion project. This is installed by default on many GNU/Linux +distributions. Originally written by Ian Macdonald, the project now lives +at @url{http://bash-completion.alioth.debian.org/}. There are ports for +other systems such as Solaris and Mac OS X. + +An older version of the bash_completion package is distributed with bash +in the @file{examples/complete} subdirectory. + @end ifset diff --git a/lib/readline/doc/rluserman.texi b/lib/readline/doc/rluserman.texi index 3d545204..ba6b0ad8 100644 --- a/lib/readline/doc/rluserman.texi +++ b/lib/readline/doc/rluserman.texi @@ -2,33 +2,25 @@ @comment %**start of header (This is for running Texinfo on a region.) @setfilename rluserman.info @settitle GNU Readline Library -@comment %**end of header (This is for running Texinfo on a region.) - @include version.texi +@comment %**end of header (This is for running Texinfo on a region.) + @copying This manual describes the end user interface of the GNU Readline Library (version @value{VERSION}, @value{UPDATED}), a library which aids in the consistency of user interface across discrete programs which provide a command line interface. -Copyright @copyright{} 1988--2011 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +Copyright @copyright{} 1988--2014 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license is -included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: You are free to copy and modify -this GNU manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled +``GNU Free Documentation License''. @end quotation @end copying @@ -49,12 +41,6 @@ developing GNU and promoting software freedom.'' @vskip 0pt plus 1filll @insertcopying -@sp 1 -Published by the Free Software Foundation @* -59 Temple Place, Suite 330, @* -Boston, MA 02111-1307 @* -USA @* - @end titlepage @contents @@ -66,6 +52,7 @@ USA @* This document describes the end user interface of the GNU Readline Library, a utility which aids in the consistency of user interface across discrete programs which provide a command line interface. +The Readline home page is @url{http://www.gnu.org/software/readline/}. @menu * Command Line Editing:: GNU Readline User's Manual. diff --git a/lib/readline/doc/version.texi b/lib/readline/doc/version.texi index 3ee1c10e..70b66582 100644 --- a/lib/readline/doc/version.texi +++ b/lib/readline/doc/version.texi @@ -1,10 +1,10 @@ @ignore -Copyright (C) 1988-2011 Free Software Foundation, Inc. +Copyright (C) 1988-2014 Free Software Foundation, Inc. @end ignore -@set EDITION 6.2 -@set VERSION 6.2 -@set UPDATED September 6 2010 -@set UPDATED-MONTH September 2010 +@set EDITION 6.3 +@set VERSION 6.3 +@set UPDATED 6 January 2014 +@set UPDATED-MONTH January 2014 -@set LASTCHANGE Mon Sep 6 22:07:10 EDT 2010 +@set LASTCHANGE Mon Jan 6 16:26:51 EST 2014 |