OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [branches/] [oc/] [gdb-5.0/] [readline/] [doc/] [hsuser.texinfo] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 106 markom
@ignore
2
This file documents the user interface to the GNU History library.
3
 
4
Copyright (C) 1988, 1991, 1996 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
@ifset BashFeatures
30
This chapter describes how to use the GNU History Library interactively,
31
from a user's standpoint.  It should be considered a user's guide.  For
32
information on using the GNU History Library in other programs,
33
see the GNU Readline Library Manual.
34
@end ifset
35
@ifclear BashFeatures
36
This chapter describes how to use the GNU History Library interactively,
37
from a user's standpoint.  It should be considered a user's guide.  For
38
information on using the GNU History Library in your own programs,
39
@pxref{Programming with GNU History}.
40
@end ifclear
41
 
42
@ifset BashFeatures
43
@menu
44
* Bash History Facilities::     How Bash lets you manipulate your command
45
                                history.
46
* Bash History Builtins::       The Bash builtin commands that manipulate
47
                                the command history.
48
* History Interaction::         What it feels like using History as a user.
49
@end menu
50
@end ifset
51
@ifclear BashFeatures
52
@menu
53
* History Interaction::         What it feels like using History as a user.
54
@end menu
55
@end ifclear
56
 
57
@ifset BashFeatures
58
@node Bash History Facilities
59
@section Bash History Facilities
60
@cindex command history
61
@cindex history list
62
 
63
When the @samp{-o history} option to the @code{set} builtin
64
is enabled (@pxref{The Set Builtin}),
65
the shell provides access to the @var{command history},
66
the list of commands previously typed.  The text of the last
67
@code{HISTSIZE}
68
commands (default 500) is saved in a history list.  The shell
69
stores each command in the history list prior to parameter and
70
variable expansion
71
but after history expansion is performed, subject to the
72
values of the shell variables
73
@code{HISTIGNORE} and @code{HISTCONTROL}.
74
When the shell starts up, the history is initialized from the
75
file named by the @code{HISTFILE} variable (default @file{~/.bash_history}).
76
@code{HISTFILE} is truncated, if necessary, to contain no more than
77
the number of lines specified by the value of the @code{HISTFILESIZE}
78
variable.  When an interactive shell exits, the last
79
@code{HISTSIZE} lines are copied from the history list to @code{HISTFILE}.
80
If the @code{histappend} shell option is set (@pxref{Bash Builtins}),
81
the lines are appended to the history file,
82
otherwise the history file is overwritten.
83
If @code{HISTFILE}
84
is unset, or if the history file is unwritable, the history is
85
not saved.  After saving the history, the history file is truncated
86
to contain no more than @code{$HISTFILESIZE}
87
lines.  If @code{HISTFILESIZE} is not set, no truncation is performed.
88
 
89
The builtin command @code{fc} may be used to list or edit and re-execute
90
a portion of the history list.
91
The @code{history} builtin can be used to display or modify the history
92
list and manipulate the history file.
93
When using the command-line editing, search commands
94
are available in each editing mode that provide access to the
95
history list.
96
 
97
The shell allows control over which commands are saved on the history
98
list.  The @code{HISTCONTROL} and @code{HISTIGNORE}
99
variables may be set to cause the shell to save only a subset of the
100
commands entered.
101
The @code{cmdhist}
102
shell option, if enabled, causes the shell to attempt to save each
103
line of a multi-line command in the same history entry, adding
104
semicolons where necessary to preserve syntactic correctness.
105
The @code{lithist}
106
shell option causes the shell to save the command with embedded newlines
107
instead of semicolons.
108
@xref{Bash Builtins}, for a description of @code{shopt}.
109
 
110
@node Bash History Builtins
111
@section Bash History Builtins
112
@cindex history builtins
113
 
114
Bash provides two builtin commands that allow you to manipulate the
115
history list and history file.
116
 
117
@table @code
118
 
119
@item fc
120
@comment btindex fc
121
@example
122
@code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]}
123
@code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
124
@end example
125
 
126
Fix Command.  In the first form, a range of commands from @var{first} to
127
@var{last} is selected from the history list.  Both @var{first} and
128
@var{last} may be specified as a string (to locate the most recent
129
command beginning with that string) or as a number (an index into the
130
history list, where a negative number is used as an offset from the
131
current command number).  If @var{last} is not specified it is set to
132
@var{first}.  If @var{first} is not specified it is set to the previous
133
command for editing and @minus{}16 for listing.  If the @samp{-l} flag is
134
given, the commands are listed on standard output.  The @samp{-n} flag
135
suppresses the command numbers when listing.  The @samp{-r} flag
136
reverses the order of the listing.  Otherwise, the editor given by
137
@var{ename} is invoked on a file containing those commands.  If
138
@var{ename} is not given, the value of the following variable expansion
139
is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}.  This says to use the
140
value of the @code{FCEDIT} variable if set, or the value of the
141
@code{EDITOR} variable if that is set, or @code{vi} if neither is set.
142
When editing is complete, the edited commands are echoed and executed.
143
 
144
In the second form, @var{command} is re-executed after each instance
145
of @var{pat} in the selected command is replaced by @var{rep}.
146
 
147
A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
148
that typing @samp{r cc} runs the last command beginning with @code{cc}
149
and typing @samp{r} re-executes the last command (@pxref{Aliases}).
150
 
151
@item history
152
@comment btindex history
153
@example
154
history [-c] [@var{n}]
155
history [-anrw] [@var{filename}]
156
history -ps @var{arg}
157
@end example
158
 
159
Display the history list with line numbers.  Lines prefixed with
160
with a @samp{*} have been modified.  An argument of @var{n} says
161
to list only the last @var{n} lines.  Options, if supplied, have
162
the following meanings:
163
 
164
@table @code
165
@item -w
166
Write out the current history to the history file.
167
 
168
@item -r
169
Read the current history file and append its contents to
170
the history list.
171
 
172
@item -a
173
Append the new
174
history lines (history lines entered since the beginning of the
175
current Bash session) to the history file.
176
 
177
@item -n
178
Append the history lines not already read from the history file
179
to the current history list.  These are lines appended to the history
180
file since the beginning of the current Bash session.
181
 
182
@item -c
183
Clear the history list.  This may be combined
184
with the other options to replace the history list completely.
185
 
186
@item -s
187
The @var{arg}s are added to the end of
188
the history list as a single entry.
189
 
190
@item -p
191
Perform history substitution on the @var{arg}s and display the result
192
on the standard output, without storing the results in the history list.
193
@end table
194
 
195
When the @samp{-w}, @samp{-r}, @samp{-a}, or @samp{-n} option is
196
used, if @var{filename}
197
is given, then it is used as the history file.  If not, then
198
the value of the @code{HISTFILE} variable is used.
199
 
200
@end table
201
@end ifset
202
 
203
@node History Interaction
204
@section History Expansion
205
@cindex history expansion
206
 
207
The History library provides a history expansion feature that is similar
208
to the history expansion provided by @code{csh}.  This section
209
describes the syntax used to manipulate the history information.
210
 
211
History expansions introduce words from the history list into
212
the input stream, making it easy to repeat commands, insert the
213
arguments to a previous command into the current input line, or
214
fix errors in previous commands quickly.
215
 
216
History expansion takes place in two parts.  The first is to determine
217
which line from the history list should be used during substitution.
218
The second is to select portions of that line for inclusion into the
219
current one.  The line selected from the history is called the
220
@dfn{event}, and the portions of that line that are acted upon are
221
called @dfn{words}.  Various @dfn{modifiers} are available to manipulate
222
the selected words.  The line is broken into words in the same fashion
223
that Bash does, so that several words
224
surrounded by quotes are considered one word.
225
History expansions are introduced by the appearance of the
226
history expansion character, which is @samp{!} by default.
227
@ifset BashFeatures
228
Only @samp{\} and @samp{'} may be used to escape the history expansion
229
character.
230
@end ifset
231
 
232
@ifset BashFeatures
233
Several shell options settable with the @code{shopt}
234
builtin (@pxref{Bash Builtins}) may be used to tailor
235
the behavior of history expansion.  If the
236
@code{histverify} shell option is enabled, and Readline
237
is being used, history substitutions are not immediately passed to
238
the shell parser.
239
Instead, the expanded line is reloaded into the Readline
240
editing buffer for further modification.
241
If Readline is being used, and the @code{histreedit}
242
shell option is enabled, a failed history expansion will be
243
reloaded into the Readline editing buffer for correction.
244
The @samp{-p} option to the @code{history} builtin command
245
may be used to see what a history expansion will do before using it.
246
The @samp{-s} option to the @code{history} builtin may be used to
247
add commands to the end of the history list without actually executing
248
them, so that they are available for subsequent recall.
249
This is most useful in conjunction with Readline.
250
 
251
The shell allows control of the various characters used by the
252
history expansion mechanism with the @code{histchars} variable.
253
@end ifset
254
 
255
@menu
256
* Event Designators::   How to specify which history line to use.
257
* Word Designators::    Specifying which words are of interest.
258
* Modifiers::           Modifying the results of substitution.
259
@end menu
260
 
261
@node Event Designators
262
@subsection Event Designators
263
@cindex event designators
264
 
265
An event designator is a reference to a command line entry in the
266
history list.
267
@cindex history events
268
 
269
@table @asis
270
 
271
@item @code{!}
272
Start a history substitution, except when followed by a space, tab,
273
the end of the line, @samp{=} or @samp{(}.
274
 
275
@item @code{!@var{n}}
276
Refer to command line @var{n}.
277
 
278
@item @code{!-@var{n}}
279
Refer to the command @var{n} lines back.
280
 
281
@item @code{!!}
282
Refer to the previous command.  This is a synonym for @samp{!-1}.
283
 
284
@item @code{!@var{string}}
285
Refer to the most recent command starting with @var{string}.
286
 
287
@item @code{!?@var{string}[?]}
288
Refer to the most recent command containing @var{string}.  The trailing
289
@samp{?} may be omitted if the @var{string} is followed immediately by
290
a newline.
291
 
292
@item @code{^@var{string1}^@var{string2}^}
293
Quick Substitution.  Repeat the last command, replacing @var{string1}
294
with @var{string2}.  Equivalent to
295
@code{!!:s/@var{string1}/@var{string2}/}.
296
 
297
@item @code{!#}
298
The entire command line typed so far.
299
 
300
@end table
301
 
302
@node Word Designators
303
@subsection Word Designators
304
 
305
Word designators are used to select desired words from the event.
306
A @samp{:} separates the event specification from the word designator.  It
307
may be omitted if the word designator begins with a @samp{^}, @samp{$},
308
@samp{*}, @samp{-}, or @samp{%}.  Words are numbered from the beginning
309
of the line, with the first word being denoted by 0 (zero).  Words are
310
inserted into the current line separated by single spaces.
311
 
312
@table @code
313
 
314
@item 0 (zero)
315
The @code{0}th word.  For many applications, this is the command word.
316
 
317
@item @var{n}
318
The @var{n}th word.
319
 
320
@item ^
321
The first argument; that is, word 1.
322
 
323
@item $
324
The last argument.
325
 
326
@item %
327
The word matched by the most recent @samp{?@var{string}?} search.
328
 
329
@item @var{x}-@var{y}
330
A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}.
331
 
332
@item *
333
All of the words, except the @code{0}th.  This is a synonym for @samp{1-$}.
334
It is not an error to use @samp{*} if there is just one word in the event;
335
the empty string is returned in that case.
336
 
337
@item @var{x}*
338
Abbreviates @samp{@var{x}-$}
339
 
340
@item @var{x}-
341
Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word.
342
 
343
@end table
344
 
345
If a word designator is supplied without an event specification, the
346
previous command is used as the event.
347
 
348
@node Modifiers
349
@subsection Modifiers
350
 
351
After the optional word designator, you can add a sequence of one or more
352
of the following modifiers, each preceded by a @samp{:}.
353
 
354
@table @code
355
 
356
@item h
357
Remove a trailing pathname component, leaving only the head.
358
 
359
@item t
360
Remove all leading  pathname  components, leaving the tail.
361
 
362
@item r
363
Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving
364
the basename.
365
 
366
@item e
367
Remove all but the trailing suffix.
368
 
369
@item p
370
Print the new command but do not execute it.
371
 
372
@ifset BashFeatures
373
@item q
374
Quote the substituted words, escaping further substitutions.
375
 
376
@item x
377
Quote the substituted words as with @samp{q},
378
but break into words at spaces, tabs, and newlines.
379
@end ifset
380
 
381
@item s/@var{old}/@var{new}/
382
Substitute @var{new} for the first occurrence of @var{old} in the
383
event line.  Any delimiter may be used in place of @samp{/}.
384
The delimiter may be quoted in @var{old} and @var{new}
385
with a single backslash.  If @samp{&} appears in @var{new},
386
it is replaced by @var{old}.  A single backslash will quote
387
the @samp{&}.  The final delimiter is optional if it is the last
388
character on the input line.
389
 
390
@item &
391
Repeat the previous substitution.
392
 
393
@item g
394
Cause changes to be applied over the entire event line.  Used in
395
conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/},
396
or with @samp{&}.
397
 
398
@end table

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.