gdb/readline/inc-history.texinfo

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