diff options
Diffstat (limited to 'doc/history.info')
| -rw-r--r-- | doc/history.info | 304 |
1 files changed, 161 insertions, 143 deletions
diff --git a/doc/history.info b/doc/history.info index a6799c3..b4ffe9a 100644 --- a/doc/history.info +++ b/doc/history.info @@ -1,11 +1,11 @@ -This is history.info, produced by makeinfo version 6.8 from +This is history.info, produced by makeinfo version 7.1 from history.texi. -This document describes the GNU History library (version 8.2, 19 -September 2022), a programming tool that provides a consistent user -interface for recalling lines of previously typed input. +This document describes the GNU History library (version 8.3, 19 January +2024), a programming tool that provides a consistent user interface for +recalling lines of previously typed input. - Copyright (C) 1988-2022 Free Software Foundation, Inc. + Copyright © 1988-2023 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -60,7 +60,7 @@ File: history.info, Node: History Interaction, Up: Using History Interactively ===================== The History library provides a history expansion feature that is similar -to the history expansion provided by 'csh'. This section describes the +to the history expansion provided by ‘csh’. This section describes the syntax used to manipulate the history information. History expansions introduce words from the history list into the @@ -71,13 +71,19 @@ previous commands quickly. History expansion takes place in two parts. The first is to determine which line from the history list should be used during substitution. The second is to select portions of that line for -inclusion into the current one. The line selected from the history is -called the "event", and the portions of that line that are acted upon -are called "words". Various "modifiers" are available to manipulate the -selected words. The line is broken into words in the same fashion 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 '!' by default. +inclusion into the current one. + + The line selected from the history is called the “event”, and the +portions of that line that are acted upon are called “words”. The line +is broken into words in the same fashion that Bash does, so that several +words surrounded by quotes are considered one word. The “event +designator” selects the event, the optional “word designator” selects +words from the event, and various optional “modifiers” are available to +manipulate the selected words. + + History expansions are introduced by the appearance of the history +expansion character, which is ‘!’ by default. History expansions may +appear anywhere in the input, but do not nest. History expansion implements shell-like quoting conventions: a backslash can be used to remove the special handling for the next @@ -87,6 +93,14 @@ 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. + There is a special abbreviation for substitution, active when the +QUICK SUBSTITUTION character (default ‘^’) is the first character on the +line. It selects the previous history list entry, using an event +designator equivalent to ‘!!’, and substitutes one string for another in +that line. It is described below (*note Event Designators::). This is +the only history expansion that does not begin with the history +expansion character. + * Menu: * Event Designators:: How to specify which history line to use. @@ -101,37 +115,40 @@ File: history.info, Node: Event Designators, Next: Word Designators, Up: Hist An event designator is a reference to a command line entry in the history list. Unless the reference is absolute, events are relative to -the current position in the history list. +the current position in the history list. The event designator consists +of the portion of the word beginning with the history expansion +character, and ending with the word designator if one is present, or the +end of the word. -'!' +‘!’ Start a history substitution, except when followed by a space, tab, - the end of the line, or '='. + the end of the line, or ‘=’. -'!N' +‘!N’ Refer to command line N. -'!-N' +‘!-N’ Refer to the command N lines back. -'!!' - Refer to the previous command. This is a synonym for '!-1'. +‘!!’ + Refer to the previous command. This is a synonym for ‘!-1’. -'!STRING' +‘!STRING’ Refer to the most recent command preceding the current position in the history list starting with STRING. -'!?STRING[?]' +‘!?STRING[?]’ Refer to the most recent command preceding the current position in - the history list containing STRING. The trailing '?' may be + the history list containing STRING. The trailing ‘?’ may be omitted if the STRING is followed immediately by a newline. If STRING is missing, the string from the most recent search is used; it is an error if there is no previous search string. -'^STRING1^STRING2^' +‘^STRING1^STRING2^’ Quick Substitution. Repeat the last command, replacing STRING1 - with STRING2. Equivalent to '!!:s^STRING1^STRING2^'. + with STRING2. Equivalent to ‘!!:s^STRING1^STRING2^’. -'!#' +‘!#’ The entire command line typed so far. @@ -140,58 +157,60 @@ File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Desi 1.1.2 Word Designators ---------------------- -Word designators are used to select desired words from the event. A ':' -separates the event specification from the word designator. It may be -omitted if the word designator begins with a '^', '$', '*', '-', or '%'. -Words are numbered from the beginning of the line, with the first word -being denoted by 0 (zero). Words are inserted into the current line -separated by single spaces. +Word designators are used to select desired words from the event. They +are optional; if the word designator isn't supplied, the history +expansion uses the entire event. A ‘:’ separates the event +specification from the word designator. It may be omitted if the word +designator begins with a ‘^’, ‘$’, ‘*’, ‘-’, or ‘%’. Words are numbered +from the beginning of the line, with the first word being denoted by 0 +(zero). Words are inserted into the current line separated by single +spaces. For example, -'!!' +‘!!’ designates the preceding command. When you type this, the preceding command is repeated in toto. -'!!:$' +‘!!:$’ designates the last argument of the preceding command. This may be - shortened to '!$'. + shortened to ‘!$’. -'!fi:2' +‘!fi:2’ designates the second argument of the most recent command starting - with the letters 'fi'. + with the letters ‘fi’. Here are the word designators: -'0 (zero)' - The '0'th word. For many applications, this is the command word. +‘0 (zero)’ + The ‘0’th word. For many applications, this is the command word. -'N' +‘N’ The Nth word. -'^' +‘^’ The first argument; that is, word 1. -'$' +‘$’ The last argument. -'%' - The first word matched by the most recent '?STRING?' search, if the +‘%’ + The first word matched by the most recent ‘?STRING?’ search, if the search string begins with a character that is part of a word. -'X-Y' - A range of words; '-Y' abbreviates '0-Y'. +‘X-Y’ + A range of words; ‘-Y’ abbreviates ‘0-Y’. -'*' - All of the words, except the '0'th. This is a synonym for '1-$'. - It is not an error to use '*' if there is just one word in the +‘*’ + All of the words, except the ‘0’th. This is a synonym for ‘1-$’. + It is not an error to use ‘*’ if there is just one word in the event; the empty string is returned in that case. -'X*' - Abbreviates 'X-$' +‘X*’ + Abbreviates ‘X-$’ -'X-' - Abbreviates 'X-$' like 'X*', but omits the last word. If 'x' is +‘X-’ + Abbreviates ‘X-$’ like ‘X*’, but omits the last word. If ‘x’ is missing, it defaults to 0. If a word designator is supplied without an event specification, the @@ -204,46 +223,46 @@ File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Inte --------------- After the optional word designator, you can add a sequence of one or -more of the following modifiers, each preceded by a ':'. These modify, +more of the following modifiers, each preceded by a ‘:’. These modify, or edit, the word or words selected from the history event. -'h' +‘h’ Remove a trailing pathname component, leaving only the head. -'t' +‘t’ Remove all leading pathname components, leaving the tail. -'r' - Remove a trailing suffix of the form '.SUFFIX', leaving the +‘r’ + Remove a trailing suffix of the form ‘.SUFFIX’, leaving the basename. -'e' +‘e’ Remove all but the trailing suffix. -'p' +‘p’ Print the new command but do not execute it. -'s/OLD/NEW/' +‘s/OLD/NEW/’ Substitute NEW for the first occurrence of OLD in the event line. - Any character may be used as the delimiter in place of '/'. The + Any character may be used as the delimiter in place of ‘/’. The delimiter may be quoted in OLD and NEW with a single backslash. If - '&' appears in NEW, it is replaced by OLD. A single backslash will - quote the '&'. If OLD is null, it is set to the last OLD + ‘&’ appears in NEW, it is replaced by OLD. A single backslash will + quote the ‘&’. If OLD is null, it is set to the last OLD substituted, or, if no previous history substitutions took place, - the last STRING in a !?STRING'[?]' search. If NEW is null, each + the last STRING in a !?STRING‘[?]’ search. If NEW is null, each matching OLD is deleted. The final delimiter is optional if it is the last character on the input line. -'&' +‘&’ Repeat the previous substitution. -'g' -'a' +‘g’ +‘a’ Cause changes to be applied over the entire event line. Used in - conjunction with 's', as in 'gs/OLD/NEW/', or with '&'. + conjunction with ‘s’, as in ‘gs/OLD/NEW/’, or with ‘&’. -'G' - Apply the following 's' or '&' modifier once to each word in the +‘G’ + Apply the following ‘s’ or ‘&’ modifier once to each word in the event. @@ -280,7 +299,7 @@ lines in composing new ones. remembering lines on a history list, associating arbitrary data with a line, removing lines from the list, searching through the list for a line containing an arbitrary text string, and referencing any line in -the list directly. In addition, a history "expansion" function is +the list directly. In addition, a history “expansion” function is available which provides for a consistent user interface across different programs. @@ -288,7 +307,7 @@ different programs. benefit of a consistent user interface with a set of well-known commands for manipulating the text of previous lines and using that text in new commands. The basic history manipulation commands are similar to the -history substitution provided by 'csh'. +history substitution provided by ‘csh’. The programmer can also use the Readline library, which includes some history manipulation by default, and has the added advantage of command @@ -296,7 +315,7 @@ line editing. Before declaring any functions using any functionality the History library provides in other code, an application writer should include the -file '<readline/history.h>' in any file that uses the History library's +file ‘<readline/history.h>’ in any file that uses the History library's features. It supplies extern declarations for all of the library's public functions and variables, and declares all of the public data structures. @@ -336,7 +355,7 @@ structure: int flags; } HISTORY_STATE; - If the flags member includes 'HS_STIFLED', the history has been + If the flags member includes ‘HS_STIFLED’, the history has been stifled. @@ -398,8 +417,8 @@ parameters managing the list itself. -- Function: void add_history (const char *string) Place STRING at the end of the history list. The associated data - field (if any) is set to 'NULL'. If the maximum number of history - entries has been set using 'stifle_history()', and the new number + field (if any) is set to ‘NULL’. If the maximum number of history + entries has been set using ‘stifle_history()’, and the new number of history entries would exceed that maximum, the oldest history entry is removed. @@ -422,7 +441,7 @@ parameters managing the list itself. Make the history entry at offset WHICH have LINE and DATA. This returns the old entry so the caller can dispose of any application-specific data. In the case of an invalid WHICH, a - 'NULL' pointer is returned. + ‘NULL’ pointer is returned. -- Function: void clear_history (void) Clear the history list by deleting all the entries. @@ -433,7 +452,7 @@ parameters managing the list itself. -- Function: int unstifle_history (void) Stop stifling the history. This returns the previously-set maximum - number of history entries (as set by 'stifle_history()'). The + number of history entries (as set by ‘stifle_history()’). The value is positive if the history was stifled, negative if it wasn't. @@ -450,24 +469,24 @@ These functions return information about the entire history list or individual list entries. -- Function: HIST_ENTRY ** history_list (void) - Return a 'NULL' terminated array of 'HIST_ENTRY *' which is the + Return a ‘NULL’ terminated array of ‘HIST_ENTRY *’ which is the current input history. Element 0 of this list is the beginning of - time. If there is no history, return 'NULL'. + time. If there is no history, return ‘NULL’. -- Function: int where_history (void) Returns the offset of the current history element. -- Function: HIST_ENTRY * current_history (void) Return the history entry at the current position, as determined by - 'where_history()'. If there is no entry there, return a 'NULL' + ‘where_history()’. If there is no entry there, return a ‘NULL’ pointer. -- Function: HIST_ENTRY * history_get (int offset) Return the history entry at position OFFSET. The range of valid - values of OFFSET starts at 'history_base' and ends at + values of OFFSET starts at ‘history_base’ and ends at HISTORY_LENGTH - 1 (*note History Variables::). If there is no entry there, or if OFFSET is outside the valid range, return a - 'NULL' pointer. + ‘NULL’ pointer. -- Function: time_t history_get_time (HIST_ENTRY *entry) Return the time stamp associated with the history entry ENTRY. If @@ -495,13 +514,13 @@ or changed. -- Function: HIST_ENTRY * previous_history (void) Back up the current history offset to the previous history entry, and return a pointer to that entry. If there is no previous entry, - return a 'NULL' pointer. + return a ‘NULL’ pointer. -- Function: HIST_ENTRY * next_history (void) If the current history offset refers to a valid history entry, increment the current history offset. If the possibly-incremented history offset refers to a valid history entry, return a pointer to - that entry; otherwise, return a 'BNULL' pointer. + that entry; otherwise, return a ‘BNULL’ pointer. File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions @@ -512,7 +531,7 @@ File: history.info, Node: Searching the History List, Next: Managing the Histo These functions allow searching of the history list for entries containing a specific string. Searching may be performed both forward and backward from the current history position. The search may be -"anchored", meaning that the string must match at the beginning of the +“anchored”, meaning that the string must match at the beginning of the history entry. -- Function: int history_search (const char *string, int direction) @@ -552,33 +571,33 @@ This section documents the functions for managing a history file. -- Function: int read_history (const char *filename) Add the contents of FILENAME to the history list, a line at a time. - If FILENAME is 'NULL', then read from '~/.history'. Returns 0 if - successful, or 'errno' if not. + If FILENAME is ‘NULL’, then read from ‘~/.history’. Returns 0 if + successful, or ‘errno’ if not. -- Function: int read_history_range (const char *filename, int from, int to) Read a range of lines from FILENAME, adding them to the history list. Start reading at line FROM and end at TO. If FROM is zero, start at the beginning. If TO is less than FROM, then read until - the end of the file. If FILENAME is 'NULL', then read from - '~/.history'. Returns 0 if successful, or 'errno' if not. + the end of the file. If FILENAME is ‘NULL’, then read from + ‘~/.history’. Returns 0 if successful, or ‘errno’ if not. -- Function: int write_history (const char *filename) Write the current history to FILENAME, overwriting FILENAME if - necessary. If FILENAME is 'NULL', then write the history list to - '~/.history'. Returns 0 on success, or 'errno' on a read or write + necessary. If FILENAME is ‘NULL’, then write the history list to + ‘~/.history’. Returns 0 on success, or ‘errno’ on a read or write error. -- Function: int append_history (int nelements, const char *filename) Append the last NELEMENTS of the history list to FILENAME. If - FILENAME is 'NULL', then append to '~/.history'. Returns 0 on - success, or 'errno' on a read or write error. + FILENAME is ‘NULL’, then append to ‘~/.history’. Returns 0 on + success, or ‘errno’ on a read or write error. -- Function: int history_truncate_file (const char *filename, int nlines) Truncate the history file FILENAME, leaving only the last NLINES - lines. If FILENAME is 'NULL', then '~/.history' is truncated. - Returns 0 on success, or 'errno' on failure. + lines. If FILENAME is ‘NULL’, then ‘~/.history’ is truncated. + Returns 0 on success, or ‘errno’ on failure. File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions @@ -588,20 +607,20 @@ File: history.info, Node: History Expansion, Prev: Managing the History File, These functions implement history expansion. - -- Function: int history_expand (char *string, char **output) + -- Function: int history_expand (const char *string, char **output) Expand STRING, placing the result into OUTPUT, a pointer to a string (*note History Interaction::). Returns: - '0' + ‘0’ If no expansions took place (or, if the only change in the text was the removal of escape characters preceding the history expansion character); - '1' + ‘1’ if expansions did take place; - '-1' + ‘-1’ if there was an error in expansion; - '2' + ‘2’ if the returned line should be displayed, but not executed, as - with the ':p' modifier (*note Modifiers::). + with the ‘:p’ modifier (*note Modifiers::). If an error occurred in expansion, then OUTPUT contains a descriptive error message. @@ -625,7 +644,7 @@ These functions implement history expansion. char *string) Extract a string segment consisting of the FIRST through LAST arguments present in STRING. Arguments are split using - 'history_tokenize'. + ‘history_tokenize’. File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History @@ -644,7 +663,7 @@ GNU History Library. -- Variable: int history_max_entries The maximum number of history entries. This must be changed using - 'stifle_history()'. + ‘stifle_history()’. -- Variable: int history_write_timestamps If non-zero, timestamps are written to the history file, so they @@ -657,12 +676,12 @@ GNU History Library. written. -- Variable: char history_expansion_char - The character that introduces a history event. The default is '!'. + The character that introduces a history event. The default is ‘!’. Setting this to 0 inhibits history expansion. -- Variable: char history_subst_char The character that invokes word substitution if found at the start - of a line. The default is '^'. + of a line. The default is ‘^’. -- Variable: char history_comment_char During tokenization, if this character is seen as the first @@ -671,18 +690,18 @@ GNU History Library. remainder of the line. This is disabled by default. -- Variable: char * history_word_delimiters - The characters that separate tokens for 'history_tokenize()'. The - default value is '" \t\n()<>;&|"'. + The characters that separate tokens for ‘history_tokenize()’. The + default value is ‘" \t\n()<>;&|"’. -- Variable: char * history_search_delimiter_chars The list of additional characters which can delimit a history - search string, in addition to space, TAB, ':' and '?' in the case + search string, in addition to space, TAB, ‘:’ and ‘?’ in the case of a substring search. The default is empty. -- Variable: char * history_no_expand_chars The list of characters which inhibit history expansion if found immediately following HISTORY_EXPANSION_CHAR. The default is - space, tab, newline, carriage return, and '='. + space, tab, newline, carriage return, and ‘=’. -- Variable: int history_quotes_inhibit_expansion If non-zero, the history expansion code implements shell-like @@ -694,10 +713,10 @@ GNU History Library. -- Variable: 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 ''', + line being expanded is subject to existing quoting. If set to ‘'’, 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 '"', history expansion will assume + closing single quote; if set to ‘"’, 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 @@ -706,12 +725,12 @@ GNU History Library. -- Variable: rl_linebuf_func_t * history_inhibit_expansion_function This should be set to the address of a function that takes two - arguments: a 'char *' (STRING) and an 'int' index into that string + arguments: a ‘char *’ (STRING) and an ‘int’ index into that string (I). It should return a non-zero value if the history expansion starting at STRING[I] should not be performed; zero if the expansion should be done. It is intended for use by applications like Bash that use the history expansion character for additional - purposes. By default, this variable is set to 'NULL'. + purposes. By default, this variable is set to ‘NULL’. File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History @@ -725,9 +744,8 @@ Library. #include <stdio.h> #include <readline/history.h> - main (argc, argv) - int argc; - char **argv; + int + main (int argc, char **argv) { char line[1024], *t; int len, done = 0; @@ -816,7 +834,7 @@ Appendix A GNU Free Documentation License Version 1.3, 3 November 2008 - Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. <http://fsf.org/> Everyone is permitted to copy and distribute verbatim copies @@ -825,7 +843,7 @@ Appendix A GNU Free Documentation License 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to + functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the @@ -1302,7 +1320,7 @@ Appendix B Concept Index * anchored search: Searching the History List. (line 10) * event designators: Event Designators. (line 6) -* history events: Event Designators. (line 8) +* history events: Event Designators. (line 11) * history expansion: History Interaction. (line 6) * History Searching: Searching the History List. (line 6) @@ -1395,28 +1413,28 @@ Appendix C Function and Variable Index Tag Table: -Node: Top850 -Node: Using History Interactively1495 -Node: History Interaction2003 -Node: Event Designators3901 -Node: Word Designators5175 -Node: Modifiers6935 -Node: Programming with GNU History8477 -Node: Introduction to History9221 -Node: History Storage10899 -Node: History Functions12034 -Node: Initializing History and State Management13023 -Node: History List Management13835 -Node: Information About the History List16129 -Node: Moving Around the History List17743 -Node: Searching the History List18836 -Node: Managing the History File20761 -Node: History Expansion22581 -Node: History Variables24510 -Node: History Programming Example28490 -Node: GNU Free Documentation License31167 -Node: Concept Index56339 -Node: Function and Variable Index57044 +Node: Top847 +Node: Using History Interactively1492 +Node: History Interaction2000 +Node: Event Designators4566 +Node: Word Designators6073 +Node: Modifiers8062 +Node: Programming with GNU History9688 +Node: Introduction to History10432 +Node: History Storage12122 +Node: History Functions13261 +Node: Initializing History and State Management14250 +Node: History List Management15062 +Node: Information About the History List17372 +Node: Moving Around the History List19014 +Node: Searching the History List20115 +Node: Managing the History File22044 +Node: History Expansion23924 +Node: History Variables25883 +Node: History Programming Example29915 +Node: GNU Free Documentation License32569 +Node: Concept Index57744 +Node: Function and Variable Index58449 End Tag Table |