Annotation of embedaddon/readline/doc/hsuser.texi, revision 1.1
1.1 ! misho 1: @ignore
! 2: This file documents the user interface to the GNU History library.
! 3:
! 4: Copyright (C) 1988--2014 Free Software Foundation, Inc.
! 5: Authored by Brian Fox and Chet Ramey.
! 6:
! 7: Permission is granted to make and distribute verbatim copies of this manual
! 8: provided the copyright notice and this permission notice are preserved on
! 9: all copies.
! 10:
! 11: Permission is granted to process this file through Tex and print the
! 12: results, provided the printed document carries copying permission notice
! 13: identical to this one except for the removal of this paragraph (this
! 14: paragraph not being relevant to the printed manual).
! 15:
! 16: Permission is granted to copy and distribute modified versions of this
! 17: manual under the conditions for verbatim copying, provided also that the
! 18: GNU Copyright statement is available to the distributee, and provided that
! 19: the entire resulting derived work is distributed under the terms of a
! 20: permission notice identical to this one.
! 21:
! 22: Permission is granted to copy and distribute translations of this manual
! 23: into another language, under the above conditions for modified versions.
! 24: @end ignore
! 25:
! 26: @node Using History Interactively
! 27: @chapter Using History Interactively
! 28:
! 29: @ifclear BashFeatures
! 30: @defcodeindex bt
! 31: @end ifclear
! 32:
! 33: @ifset BashFeatures
! 34: This chapter describes how to use the @sc{gnu} History Library
! 35: interactively, from a user's standpoint.
! 36: It should be considered a user's guide.
! 37: For information on using the @sc{gnu} History Library in other programs,
! 38: see the @sc{gnu} Readline Library Manual.
! 39: @end ifset
! 40: @ifclear BashFeatures
! 41: This chapter describes how to use the @sc{gnu} History Library interactively,
! 42: from a user's standpoint. It should be considered a user's guide. For
! 43: information on using the @sc{gnu} History Library in your own programs,
! 44: @pxref{Programming with GNU History}.
! 45: @end ifclear
! 46:
! 47: @ifset BashFeatures
! 48: @menu
! 49: * Bash History Facilities:: How Bash lets you manipulate your command
! 50: history.
! 51: * Bash History Builtins:: The Bash builtin commands that manipulate
! 52: the command history.
! 53: * History Interaction:: What it feels like using History as a user.
! 54: @end menu
! 55: @end ifset
! 56: @ifclear BashFeatures
! 57: @menu
! 58: * History Interaction:: What it feels like using History as a user.
! 59: @end menu
! 60: @end ifclear
! 61:
! 62: @ifset BashFeatures
! 63: @node Bash History Facilities
! 64: @section Bash History Facilities
! 65: @cindex command history
! 66: @cindex history list
! 67:
! 68: When the @option{-o history} option to the @code{set} builtin
! 69: is enabled (@pxref{The Set Builtin}),
! 70: the shell provides access to the @dfn{command history},
! 71: the list of commands previously typed.
! 72: The value of the @env{HISTSIZE} shell variable is used as the
! 73: number of commands to save in a history list.
! 74: The text of the last @env{$HISTSIZE}
! 75: commands (default 500) is saved.
! 76: The shell stores each command in the history list prior to
! 77: parameter and variable expansion
! 78: but after history expansion is performed, subject to the
! 79: values of the shell variables
! 80: @env{HISTIGNORE} and @env{HISTCONTROL}.
! 81:
! 82: When the shell starts up, the history is initialized from the
! 83: file named by the @env{HISTFILE} variable (default @file{~/.bash_history}).
! 84: The file named by the value of @env{HISTFILE} is truncated, if
! 85: necessary, to contain no more than the number of lines specified by
! 86: the value of the @env{HISTFILESIZE} variable.
! 87: When a shell with history enabled exits, the last
! 88: @env{$HISTSIZE} lines are copied from the history list to the file
! 89: named by @env{$HISTFILE}.
! 90: If the @code{histappend} shell option is set (@pxref{Bash Builtins}),
! 91: the lines are appended to the history file,
! 92: otherwise the history file is overwritten.
! 93: If @env{HISTFILE}
! 94: is unset, or if the history file is unwritable, the history is not saved.
! 95: After saving the history, the history file is truncated
! 96: to contain no more than @env{$HISTFILESIZE} lines.
! 97: If @env{HISTFILESIZE} is unset, or set to null, a non-numeric value, or
! 98: a numeric value less than zero, the history file is not truncated.
! 99:
! 100: If the @env{HISTTIMEFORMAT} is set, the time stamp information
! 101: associated with each history entry is written to the history file,
! 102: marked with the history comment character.
! 103: When the history file is read, lines beginning with the history
! 104: comment character followed immediately by a digit are interpreted
! 105: as timestamps for the previous history line.
! 106:
! 107: The builtin command @code{fc} may be used to list or edit and re-execute
! 108: a portion of the history list.
! 109: The @code{history} builtin may be used to display or modify the history
! 110: list and manipulate the history file.
! 111: When using command-line editing, search commands
! 112: are available in each editing mode that provide access to the
! 113: history list (@pxref{Commands For History}).
! 114:
! 115: The shell allows control over which commands are saved on the history
! 116: list. The @env{HISTCONTROL} and @env{HISTIGNORE}
! 117: variables may be set to cause the shell to save only a subset of the
! 118: commands entered.
! 119: The @code{cmdhist}
! 120: shell option, if enabled, causes the shell to attempt to save each
! 121: line of a multi-line command in the same history entry, adding
! 122: semicolons where necessary to preserve syntactic correctness.
! 123: The @code{lithist}
! 124: shell option causes the shell to save the command with embedded newlines
! 125: instead of semicolons.
! 126: The @code{shopt} builtin is used to set these options.
! 127: @xref{Bash Builtins}, for a description of @code{shopt}.
! 128:
! 129: @node Bash History Builtins
! 130: @section Bash History Builtins
! 131: @cindex history builtins
! 132:
! 133: Bash provides two builtin commands which manipulate the
! 134: history list and history file.
! 135:
! 136: @table @code
! 137:
! 138: @item fc
! 139: @btindex fc
! 140: @example
! 141: @code{fc [-e @var{ename}] [-lnr] [@var{first}] [@var{last}]}
! 142: @code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
! 143: @end example
! 144:
! 145: The first form selects a range of commands from @var{first} to
! 146: @var{last} from the history list and displays or edits and re-executes
! 147: them.
! 148: Both @var{first} and
! 149: @var{last} may be specified as a string (to locate the most recent
! 150: command beginning with that string) or as a number (an index into the
! 151: history list, where a negative number is used as an offset from the
! 152: current command number). If @var{last} is not specified it is set to
! 153: @var{first}. If @var{first} is not specified it is set to the previous
! 154: command for editing and @minus{}16 for listing. If the @option{-l} flag is
! 155: given, the commands are listed on standard output. The @option{-n} flag
! 156: suppresses the command numbers when listing. The @option{-r} flag
! 157: reverses the order of the listing. Otherwise, the editor given by
! 158: @var{ename} is invoked on a file containing those commands. If
! 159: @var{ename} is not given, the value of the following variable expansion
! 160: is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the
! 161: value of the @env{FCEDIT} variable if set, or the value of the
! 162: @env{EDITOR} variable if that is set, or @code{vi} if neither is set.
! 163: When editing is complete, the edited commands are echoed and executed.
! 164:
! 165: In the second form, @var{command} is re-executed after each instance
! 166: of @var{pat} in the selected command is replaced by @var{rep}.
! 167: @var{command} is intepreted the same as @var{first} above.
! 168:
! 169: A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
! 170: that typing @samp{r cc} runs the last command beginning with @code{cc}
! 171: and typing @samp{r} re-executes the last command (@pxref{Aliases}).
! 172:
! 173: @item history
! 174: @btindex history
! 175: @example
! 176: history [@var{n}]
! 177: history -c
! 178: history -d @var{offset}
! 179: history [-anrw] [@var{filename}]
! 180: history -ps @var{arg}
! 181: @end example
! 182:
! 183: With no options, display the history list with line numbers.
! 184: Lines prefixed with a @samp{*} have been modified.
! 185: An argument of @var{n} lists only the last @var{n} lines.
! 186: If the shell variable @env{HISTTIMEFORMAT} is set and not null,
! 187: it is used as a format string for @var{strftime} to display
! 188: the time stamp associated with each displayed history entry.
! 189: No intervening blank is printed between the formatted time stamp
! 190: and the history line.
! 191:
! 192: Options, if supplied, have the following meanings:
! 193:
! 194: @table @code
! 195: @item -c
! 196: Clear the history list. This may be combined
! 197: with the other options to replace the history list completely.
! 198:
! 199: @item -d @var{offset}
! 200: Delete the history entry at position @var{offset}.
! 201: @var{offset} should be specified as it appears when the history is
! 202: displayed.
! 203:
! 204: @item -a
! 205: Append the new
! 206: history lines (history lines entered since the beginning of the
! 207: current Bash session) to the history file.
! 208:
! 209: @item -n
! 210: Append the history lines not already read from the history file
! 211: to the current history list. These are lines appended to the history
! 212: file since the beginning of the current Bash session.
! 213:
! 214: @item -r
! 215: Read the history file and append its contents to
! 216: the history list.
! 217:
! 218: @item -w
! 219: Write out the current history list to the history file.
! 220:
! 221: @item -p
! 222: Perform history substitution on the @var{arg}s and display the result
! 223: on the standard output, without storing the results in the history list.
! 224:
! 225: @item -s
! 226: The @var{arg}s are added to the end of
! 227: the history list as a single entry.
! 228:
! 229: @end table
! 230:
! 231: When any of the @option{-w}, @option{-r}, @option{-a}, or @option{-n} options is
! 232: used, if @var{filename}
! 233: is given, then it is used as the history file. If not, then
! 234: the value of the @env{HISTFILE} variable is used.
! 235:
! 236: @end table
! 237: @end ifset
! 238:
! 239: @node History Interaction
! 240: @section History Expansion
! 241: @cindex history expansion
! 242:
! 243: The History library provides a history expansion feature that is similar
! 244: to the history expansion provided by @code{csh}. This section
! 245: describes the syntax used to manipulate the history information.
! 246:
! 247: History expansions introduce words from the history list into
! 248: the input stream, making it easy to repeat commands, insert the
! 249: arguments to a previous command into the current input line, or
! 250: fix errors in previous commands quickly.
! 251:
! 252: History expansion takes place in two parts. The first is to determine
! 253: which line from the history list should be used during substitution.
! 254: The second is to select portions of that line for inclusion into the
! 255: current one. The line selected from the history is called the
! 256: @dfn{event}, and the portions of that line that are acted upon are
! 257: called @dfn{words}. Various @dfn{modifiers} are available to manipulate
! 258: the selected words. The line is broken into words in the same fashion
! 259: that Bash does, so that several words
! 260: surrounded by quotes are considered one word.
! 261: History expansions are introduced by the appearance of the
! 262: history expansion character, which is @samp{!} by default.
! 263: @ifset BashFeatures
! 264: Only @samp{\} and @samp{'} may be used to escape the history expansion
! 265: character.
! 266: @end ifset
! 267:
! 268: @ifset BashFeatures
! 269: Several shell options settable with the @code{shopt}
! 270: builtin (@pxref{Bash Builtins}) may be used to tailor
! 271: the behavior of history expansion. If the
! 272: @code{histverify} shell option is enabled, and Readline
! 273: is being used, history substitutions are not immediately passed to
! 274: the shell parser.
! 275: Instead, the expanded line is reloaded into the Readline
! 276: editing buffer for further modification.
! 277: If Readline is being used, and the @code{histreedit}
! 278: shell option is enabled, a failed history expansion will be
! 279: reloaded into the Readline editing buffer for correction.
! 280: The @option{-p} option to the @code{history} builtin command
! 281: may be used to see what a history expansion will do before using it.
! 282: The @option{-s} option to the @code{history} builtin may be used to
! 283: add commands to the end of the history list without actually executing
! 284: them, so that they are available for subsequent recall.
! 285: This is most useful in conjunction with Readline.
! 286:
! 287: The shell allows control of the various characters used by the
! 288: history expansion mechanism with the @code{histchars} variable,
! 289: as explained above (@pxref{Bash Variables}). The shell uses
! 290: the history comment character to mark history timestamps when
! 291: writing the history file.
! 292: @end ifset
! 293:
! 294: @menu
! 295: * Event Designators:: How to specify which history line to use.
! 296: * Word Designators:: Specifying which words are of interest.
! 297: * Modifiers:: Modifying the results of substitution.
! 298: @end menu
! 299:
! 300: @node Event Designators
! 301: @subsection Event Designators
! 302: @cindex event designators
! 303:
! 304: An event designator is a reference to a command line entry in the
! 305: history list.
! 306: Unless the reference is absolute, events are relative to the current
! 307: position in the history list.
! 308: @cindex history events
! 309:
! 310: @table @asis
! 311:
! 312: @item @code{!}
! 313: @ifset BashFeatures
! 314: Start a history substitution, except when followed by a space, tab,
! 315: the end of the line, @samp{=} or @samp{(} (when the
! 316: @code{extglob} shell option is enabled using the @code{shopt} builtin).
! 317: @end ifset
! 318: @ifclear BashFeatures
! 319: Start a history substitution, except when followed by a space, tab,
! 320: the end of the line, or @samp{=}.
! 321: @end ifclear
! 322:
! 323: @item @code{!@var{n}}
! 324: Refer to command line @var{n}.
! 325:
! 326: @item @code{!-@var{n}}
! 327: Refer to the command @var{n} lines back.
! 328:
! 329: @item @code{!!}
! 330: Refer to the previous command. This is a synonym for @samp{!-1}.
! 331:
! 332: @item @code{!@var{string}}
! 333: Refer to the most recent command
! 334: preceding the current position in the history list
! 335: starting with @var{string}.
! 336:
! 337: @item @code{!?@var{string}[?]}
! 338: Refer to the most recent command
! 339: preceding the current position in the history list
! 340: containing @var{string}.
! 341: The trailing
! 342: @samp{?} may be omitted if the @var{string} is followed immediately by
! 343: a newline.
! 344:
! 345: @item @code{^@var{string1}^@var{string2}^}
! 346: Quick Substitution. Repeat the last command, replacing @var{string1}
! 347: with @var{string2}. Equivalent to
! 348: @code{!!:s/@var{string1}/@var{string2}/}.
! 349:
! 350: @item @code{!#}
! 351: The entire command line typed so far.
! 352:
! 353: @end table
! 354:
! 355: @node Word Designators
! 356: @subsection Word Designators
! 357:
! 358: Word designators are used to select desired words from the event.
! 359: A @samp{:} separates the event specification from the word designator. It
! 360: may be omitted if the word designator begins with a @samp{^}, @samp{$},
! 361: @samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning
! 362: of the line, with the first word being denoted by 0 (zero). Words are
! 363: inserted into the current line separated by single spaces.
! 364:
! 365: @need 0.75
! 366: For example,
! 367:
! 368: @table @code
! 369: @item !!
! 370: designates the preceding command. When you type this, the preceding
! 371: command is repeated in toto.
! 372:
! 373: @item !!:$
! 374: designates the last argument of the preceding command. This may be
! 375: shortened to @code{!$}.
! 376:
! 377: @item !fi:2
! 378: designates the second argument of the most recent command starting with
! 379: the letters @code{fi}.
! 380: @end table
! 381:
! 382: @need 0.75
! 383: Here are the word designators:
! 384:
! 385: @table @code
! 386:
! 387: @item 0 (zero)
! 388: The @code{0}th word. For many applications, this is the command word.
! 389:
! 390: @item @var{n}
! 391: The @var{n}th word.
! 392:
! 393: @item ^
! 394: The first argument; that is, word 1.
! 395:
! 396: @item $
! 397: The last argument.
! 398:
! 399: @item %
! 400: The word matched by the most recent @samp{?@var{string}?} search.
! 401:
! 402: @item @var{x}-@var{y}
! 403: A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}.
! 404:
! 405: @item *
! 406: All of the words, except the @code{0}th. This is a synonym for @samp{1-$}.
! 407: It is not an error to use @samp{*} if there is just one word in the event;
! 408: the empty string is returned in that case.
! 409:
! 410: @item @var{x}*
! 411: Abbreviates @samp{@var{x}-$}
! 412:
! 413: @item @var{x}-
! 414: Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word.
! 415:
! 416: @end table
! 417:
! 418: If a word designator is supplied without an event specification, the
! 419: previous command is used as the event.
! 420:
! 421: @node Modifiers
! 422: @subsection Modifiers
! 423:
! 424: After the optional word designator, you can add a sequence of one or more
! 425: of the following modifiers, each preceded by a @samp{:}.
! 426:
! 427: @table @code
! 428:
! 429: @item h
! 430: Remove a trailing pathname component, leaving only the head.
! 431:
! 432: @item t
! 433: Remove all leading pathname components, leaving the tail.
! 434:
! 435: @item r
! 436: Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving
! 437: the basename.
! 438:
! 439: @item e
! 440: Remove all but the trailing suffix.
! 441:
! 442: @item p
! 443: Print the new command but do not execute it.
! 444:
! 445: @ifset BashFeatures
! 446: @item q
! 447: Quote the substituted words, escaping further substitutions.
! 448:
! 449: @item x
! 450: Quote the substituted words as with @samp{q},
! 451: but break into words at spaces, tabs, and newlines.
! 452: @end ifset
! 453:
! 454: @item s/@var{old}/@var{new}/
! 455: Substitute @var{new} for the first occurrence of @var{old} in the
! 456: event line. Any delimiter may be used in place of @samp{/}.
! 457: The delimiter may be quoted in @var{old} and @var{new}
! 458: with a single backslash. If @samp{&} appears in @var{new},
! 459: it is replaced by @var{old}. A single backslash will quote
! 460: the @samp{&}. The final delimiter is optional if it is the last
! 461: character on the input line.
! 462:
! 463: @item &
! 464: Repeat the previous substitution.
! 465:
! 466: @item g
! 467: @itemx a
! 468: Cause changes to be applied over the entire event line. Used in
! 469: conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/},
! 470: or with @samp{&}.
! 471:
! 472: @item G
! 473: Apply the following @samp{s} modifier once to each word in the event.
! 474:
! 475: @end table
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to hsuser.texi CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc