diff options
Diffstat (limited to 'doc/history.n')
| -rw-r--r-- | doc/history.n | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/doc/history.n b/doc/history.n new file mode 100644 index 0000000..e58ea3a --- /dev/null +++ b/doc/history.n @@ -0,0 +1,104 @@ +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) history.n 1.11 97/08/07 16:44:49 +'\" +.so man.macros +.TH history n "" Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +history \- Manipulate the history list +.SH SYNOPSIS +\fBhistory \fR?\fIoption\fR? ?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBhistory\fR command performs one of several operations related to +recently-executed commands recorded in a history list. Each of +these recorded commands is referred to as an ``event''. When +specifying an event to the \fBhistory\fR command, the following +forms may be used: +.IP [1] +A number: if positive, it refers to the event with +that number (all events are numbered starting at 1). If the number +is negative, it selects an event relative to the current event +(\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and +so on). Event \fB0\fP refers to the current event. +.IP [2] +A string: selects the most recent event that matches the string. +An event is considered to match the string either if the string is +the same as the first characters of the event, or if the string +matches the event in the sense of the \fBstring match\fR command. +.PP +The \fBhistory\fR command can take any of the following forms: +.TP +\fBhistory\fR +Same +as \fBhistory info\fR, described below. +.TP +\fBhistory add\fI command \fR?\fBexec\fR? +Adds the \fIcommand\fR argument to the history list as a new event. If +\fBexec\fR is specified (or abbreviated) then the command is also +executed and its result is returned. If \fBexec\fR isn't specified +then an empty string is returned as result. +.TP +\fBhistory change\fI newValue\fR ?\fIevent\fR? +Replaces the value recorded for an event with \fInewValue\fR. \fIEvent\fR +specifies the event to replace, and +defaults to the \fIcurrent\fR event (not event \fB\-1\fR). This command +is intended for use in commands that implement new forms of history +substitution and wish to replace the current event (which invokes the +substitution) with the command created through substitution. The return +value is an empty string. +.TP +\fBhistory clear\fR +Erase the history list. The current keep limit is retained. +The history event numbers are reset. +.TP +\fBhistory event\fR ?\fIevent\fR? +Returns the value of the event given by \fIevent\fR. \fIEvent\fR +defaults to \fB\-1\fR. +.TP +\fBhistory info \fR?\fIcount\fR? +Returns a formatted string (intended for humans to read) giving +the event number and contents for each of the events in the history +list except the current event. If \fIcount\fR is specified +then only the most recent \fIcount\fR events are returned. +.TP +\fBhistory keep \fR?\fIcount\fR? +This command may be used to change the size of the history list to +\fIcount\fR events. Initially, 20 events are retained in the history +list. If \fIcount\fR is not specified, the current keep limit is returned. +.TP +\fBhistory nextid\fR +Returns the number of the next event to be recorded +in the history list. It is useful for things like printing the +event number in command-line prompts. +.TP +\fBhistory redo \fR?\fIevent\fR? +Re-executes the command indicated by \fIevent\fR and return its result. +\fIEvent\fR defaults to \fB\-1\fR. This command results in history +revision: see below for details. +.SH "HISTORY REVISION" +.PP +Pre-8.0 Tcl had a complex history revision mechanism. +The current mechanism is more limited, and the old +history operations \fBsubstitute\fP and \fBwords\fP have been removed. +(As a consolation, the \fBclear\fP operation was added.) +.PP +The history option \fBredo\fR results in much simpler ``history revision''. +When this option is invoked then the most recent event +is modified to eliminate the history command and replace it with +the result of the history command. +If you want to redo an event without modifying history, then use +the \fBevent\fP operation to retrieve some event, +and the \fBadd\fP operation to add it to history and execute it. + +.SH KEYWORDS +event, history, record |