readline/inc-hist.texi

   1 @ifinfo
   2 This file documents the GNU History library.
   3
   4 Copyright (C) 1988 Free Software Foundation, Inc.
   5 Authored by Brian Fox.
   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 @end ifinfo
  11
  12 @ignore
  13 Permission is granted to process this file through Tex and print the
  14 results, provided the printed document carries copying permission notice
  15 identical to this one except for the removal of this paragraph (this
  16 paragraph not being relevant to the printed manual).
  17
  18 Permission is granted to copy and distribute modified versions of this
  19 manual under the conditions for verbatim copying, provided also that the
  20 GNU Copyright statement is available to the distributee, and provided that
  21 the entire resulting derived work is distributed under the terms of a
  22 permission notice identical to this one.
  23
  24 Permission is granted to copy and distribute translations of this manual
  25 into another language, under the above conditions for modified versions.
  26 @end ignore
  27
  28 @node History Top,,,
  29 @appendix Command Line History
  30 @ifinfo
  31 This file is meant to be an inclusion in the documentation of programs
  32 that use the history library features.  There is also a standalone
  33 document, entitled @file{history.texinfo}.
  34 @end ifinfo
  35
  36 This Appendix describes the GNU History library, a programming tool that
  37 provides a consistent user interface for recalling lines of previously
  38 typed input.
  39
  40 @menu
  41 * Introduction to History::     What is the GNU History library for?
  42 * History Interaction::         What it feels like using History as a user.
  43 @end menu
  44
  45 @node Introduction to History, History Interaction, History Top, Top
  46 @appendixsec Introduction to History
  47
  48 Many programs read input from the user a line at a time.  The GNU history
  49 library is able to keep track of those lines, associate arbitrary data with
  50 each line, and utilize information from previous lines in making up new
  51 ones.
  52
  53 The programmer using the History library has available to him functions
  54 for remembering lines on a history stack, associating arbitrary data
  55 with a line, removing lines from the stack, searching through the stack
  56 for a line containing an arbitrary text string, and referencing any line
  57 on the stack directly.  In addition, a history @dfn{expansion} function
  58 is available which provides for a consistent user interface across many
  59 different programs.
  60
  61 When you use programs written with the History library, you have the
  62 benefit of a consistent user interface, with a set of well-known
  63 commands for manipulating the text of previous lines and using that text
  64 in new commands.  The basic history manipulation commands are similar to
  65 the history substitution used by Csh.
  66
  67 GNU programs often also use the Readline library, which includes history
  68 manipulation by default, and has the added advantage of Emacs style
  69 command line editing.
  70
  71 @node History Interaction, , Introduction to History, Top
  72 @appendixsec History Interaction
  73 @cindex expansion
  74
  75 The History library provides a history expansion feature that is similar
  76 to the history expansion in Csh.  The following text describes what
  77 syntax features are available.
  78
  79 History expansion takes place in two parts.  The first is to determine
  80 which line from the previous history should be used during substitution.
  81 The second is to select portions of that line for inclusion into the
  82 current one.  The line selected from the previous history is called the
  83 @dfn{event}, and the portions of that line that are acted upon are
  84 called @dfn{words}.  The line is broken into words in the same fashion
  85 used by the Bash shell, so that several words surrounded by quotes are
  86 treated as if they were a single word.
  87
  88 @menu
  89 * Event Designators::   How to specify which history line to use.  *
  90 Word Designators::      Specifying which words are of interest.  *
  91 Modifiers::             Modifying the results of susbstitution.
  92 @end menu
  93
  94 @node Event Designators, Word Designators, , History Interaction
  95 @appendixsubsec Event Designators
  96 @cindex event designators
  97
  98 An event designator is a reference to a command line entry in the
  99 history list.
 100
 101 @table @asis
 102
 103 @item @code{!}
 104 Start a history subsititution, except when followed by a space, tab, or
 105 the end of the line; or by @samp{=} or @samp{(}.
 106
 107 @item @code{!!}
 108 Refer to the previous command.  This is a synonym for @code{!-1}.
 109
 110 @item @code{!@var{n}}
 111 Refer to command line @var{n}.
 112
 113 @item @code{!-@var{n}}
 114 Refer to the command line @var{n} lines back.
 115
 116 @item @code{!@var{string}}
 117 Refer to the most recent command starting with @var{string}.
 118
 119 @item @code{!?@var{string}}[@code{?}]
 120 Refer to the most recent command containing @var{string}.
 121
 122 @end table
 123
 124 @node Word Designators, Modifiers, Event Designators, History Interaction
 125 @appendixsubsec Word Designators
 126
 127 A @samp{:} separates the event specification from the word designator.  It
 128 can be omitted if the word designator begins with a @samp{^}, @samp{$},
 129 @samp{*} or @samp{%}.  Words are numbered from the beginning of the line,
 130 with the first word being denoted by a 0 (zero).
 131
 132 @table @code
 133
 134 @item 0 (zero)
 135 The zero'th word.  For many applications, this is the command word.
 136
 137 @item n
 138 The @var{n}'th word.
 139
 140 @item ^
 141 The first argument.  that is, word 1.
 142
 143 @item $
 144 The last argument.
 145
 146 @item %
 147 The word matched by the most recent @code{?@var{string}?} search.
 148
 149 @item @var{x}-@var{y}
 150 A range of words; @code{-@var{y}} abbreviates @code{0-@var{y}}.
 151
 152 @item *
 153 All of the words, excepting the zero'th.  This is a synonym for @samp{1-$}.
 154 It is not an error to use @samp{*} if there is just one word in the event.
 155 The empty string is returned in that case.
 156
 157 @end table
 158
 159 @node Modifiers, , Word Designators, History Interaction
 160 @appendixsubsec Modifiers
 161
 162 After the optional word designator, you can add a sequence of one or more
 163 of the following modifiers, each preceded by a @samp{:}.
 164
 165 @table @code
 166
 167 @item #
 168 The entire command line typed so far.  This means the current command,
 169 not the previous command, so it really isn't a word designator, and doesn't
 170 belong in this section.
 171
 172 @item h
 173 Remove a trailing pathname component, leaving only the head.
 174
 175 @item r
 176 Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving the basename.
 177
 178 @item e
 179 Remove all but the suffix.
 180
 181 @item t
 182 Remove all leading  pathname  components, leaving the tail.
 183
 184 @item p
 185 Print the new command but do not execute it.  This takes effect
 186 immediately, so it should be the last specifier on the line.
 187
 188 @end table