readline/history.texinfo

   1 \input texinfo.tex
   2 @setfilename history.info
   3
   4 @ifinfo
   5 This file documents the GNU History library.
   6
   7 Copyright (C) 1988 Free Software Foundation, Inc.
   8 Authored by Brian Fox.
   9
  10 Permission is granted to make and distribute verbatim copies of this manual
  11 provided the copyright notice and this permission notice are preserved on
  12 all copies.
  13
  14 @ignore
  15 Permission is granted to process this file through Tex and print the
  16 results, provided the printed document carries copying permission notice
  17 identical to this one except for the removal of this paragraph (this
  18 paragraph not being relevant to the printed manual).
  19 @end ignore
  20
  21 Permission is granted to copy and distribute modified versions of this
  22 manual under the conditions for verbatim copying, provided also that the
  23 GNU Copyright statement is available to the distributee, and provided that
  24 the entire resulting derived work is distributed under the terms of a
  25 permission notice identical to this one.
  26
  27 Permission is granted to copy and distribute translations of this manual
  28 into another language, under the above conditions for modified versions.
  29 @end ifinfo
  30
  31 @node Top, Introduction, , (DIR)
  32
  33 This document describes the GNU History library, a programming tool that
  34 provides a consistent user interface for recalling lines of previously
  35 typed input.
  36
  37 @menu
  38 * Introduction::        What is the GNU History library for?
  39 * Interactive Use::     What it feels like using History as a user.
  40 * Programming::         How to use History in your programs.
  41 @end menu
  42
  43 @node Introduction, Interactive Use, , Top
  44 @unnumbered Introduction
  45
  46 Many programs read input from the user a line at a time.  The GNU history
  47 library is able to keep track of those lines, associate arbitrary data with
  48 each line, and utilize information from previous lines in making up new
  49 ones.
  50
  51 The programmer using the History library has available to him functions for
  52 remembering lines on a history stack, associating arbitrary data with a
  53 line, removing lines from the stack, searching through the stack for a
  54 line containing an arbitrary text string, and referencing any line on the
  55 stack directly.  In addition, a history @dfn{expansion} function is
  56 available which provides for a consistent user interface across many
  57 different programs.
  58
  59 The end-user using programs written with the History library has the
  60 benifit of a consistent user interface, with a set of well-known commands
  61 for manipulating the text of previous lines and using that text in new
  62 commands.  The basic history manipulation commands are similar to the
  63 history substitution used by Csh.
  64
  65 If the programmer desires, he can use the Readline library, which includes
  66 history manipulation by default, and has the added advantage of Emacs style
  67 command line editing.
  68
  69 @node Interactive Use, Programming, Introduction, Top
  70 @chapter Interactive Use
  71
  72 @section History Expansion
  73 @cindex expansion
  74
  75 The History library provides a history expansion feature that is similar to
  76 the history expansion in Csh.  The following text describes what syntax
  77 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 called
  84 @dfn{words}.  The line is broken into words in the same fashion that the
  85 Bash shell does, so that several English (or Unix) words surrounded by
  86 quotes are considered as one 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, , Interactive Use
  95 @subsection Event Designators
  96 @cindex event designators
  97
  98 An event designator is a reference to a command line entry in the history
  99 list.
 100
 101 @table @var
 102
 103 @item !
 104 Start a history subsititution, except when followed by a @key{SPC},
 105 @key{TAB}, @key{RET}, @key{=} or @key{(}.
 106
 107 @item !!
 108 Refer to the previous command.  This is a synonym for @code{!-1}.
 109
 110 @item !n
 111 Refer to command line @var{n}.
 112
 113 @item !-n
 114 Refer to the current command line minus @var{n}.
 115
 116 @item !string
 117 Refer to the most recent command starting with @var{string}.
 118
 119 @item !?string[?]
 120 Refer to the most recent command containing @var{string}.
 121
 122 @end table
 123
 124 @node Word Designators, Modifiers, Event Designators, Interactive Use
 125 @subsection Word Designators
 126
 127 A @key{:} separates the event specification from the word designator.  It
 128 can be omitted if the word designator begins with a @key{^}, @key{$},
 129 @key{*} or @key{%}.  Words are numbered from the beginning of the line,
 130 with the first word being denoted by a 0 (zero).
 131
 132 @table @asis
 133
 134 @item @var{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 @var{^}
 141 The first argument.  that is, word 1.
 142
 143 @item @var{$}
 144 The last argument.
 145
 146 @item @var{%}
 147 The word matched by the most recent @code{?string?} search.
 148
 149 @item @var{x}-@var{y}
 150 A range of words; @code{-@var{y}} is equivalent to @code{0-@var{y}}.
 151
 152 @item @var{*}
 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, Interactive Use
 160 @subsection 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 @key{:}.
 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 ".xxx", leaving the basename (root).
 177
 178 @item e
 179 Remove all but the suffix (end).
 180
 181 @item t
 182 Remove all leading  pathname  components (before the last slash), leaving
 183 the tail.
 184
 185 @item p
 186 Print the new command but do not execute it.  This takes effect
 187 immediately, so it should be the last specifier on the line.
 188
 189 @end table
 190
 191 @node Programming, , Interactive Use, Top
 192 @chapter Programming
 193
 194 @bye