| 1 | '\" |
|---|
| 2 | '\" Copyright (c) 1993 The Regents of the University of California. |
|---|
| 3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
|---|
| 4 | '\" |
|---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
|---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
|---|
| 7 | '\" |
|---|
| 8 | '\" RCS: @(#) $Id: history.n,v 1.8 2007/12/13 15:22:32 dgp Exp $ |
|---|
| 9 | '\" |
|---|
| 10 | .so man.macros |
|---|
| 11 | .TH history n "" Tcl "Tcl Built-In Commands" |
|---|
| 12 | .BS |
|---|
| 13 | '\" Note: do not modify the .SH NAME line immediately below! |
|---|
| 14 | .SH NAME |
|---|
| 15 | history \- Manipulate the history list |
|---|
| 16 | .SH SYNOPSIS |
|---|
| 17 | \fBhistory \fR?\fIoption\fR? ?\fIarg arg ...\fR? |
|---|
| 18 | .BE |
|---|
| 19 | .SH DESCRIPTION |
|---|
| 20 | .PP |
|---|
| 21 | The \fBhistory\fR command performs one of several operations related to |
|---|
| 22 | recently-executed commands recorded in a history list. Each of |
|---|
| 23 | these recorded commands is referred to as an |
|---|
| 24 | .QW event . |
|---|
| 25 | When specifying an event to the \fBhistory\fR command, the following |
|---|
| 26 | forms may be used: |
|---|
| 27 | .IP [1] |
|---|
| 28 | A number: if positive, it refers to the event with |
|---|
| 29 | that number (all events are numbered starting at 1). If the number |
|---|
| 30 | is negative, it selects an event relative to the current event |
|---|
| 31 | (\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and |
|---|
| 32 | so on). Event \fB0\fR refers to the current event. |
|---|
| 33 | .IP [2] |
|---|
| 34 | A string: selects the most recent event that matches the string. |
|---|
| 35 | An event is considered to match the string either if the string is |
|---|
| 36 | the same as the first characters of the event, or if the string |
|---|
| 37 | matches the event in the sense of the \fBstring match\fR command. |
|---|
| 38 | .PP |
|---|
| 39 | The \fBhistory\fR command can take any of the following forms: |
|---|
| 40 | .TP |
|---|
| 41 | \fBhistory\fR |
|---|
| 42 | Same |
|---|
| 43 | as \fBhistory info\fR, described below. |
|---|
| 44 | .TP |
|---|
| 45 | \fBhistory add\fI command \fR?\fBexec\fR? |
|---|
| 46 | Adds the \fIcommand\fR argument to the history list as a new event. If |
|---|
| 47 | \fBexec\fR is specified (or abbreviated) then the command is also |
|---|
| 48 | executed and its result is returned. If \fBexec\fR is not specified |
|---|
| 49 | then an empty string is returned as result. |
|---|
| 50 | .TP |
|---|
| 51 | \fBhistory change\fI newValue\fR ?\fIevent\fR? |
|---|
| 52 | Replaces the value recorded for an event with \fInewValue\fR. \fIEvent\fR |
|---|
| 53 | specifies the event to replace, and |
|---|
| 54 | defaults to the \fIcurrent\fR event (not event \fB\-1\fR). This command |
|---|
| 55 | is intended for use in commands that implement new forms of history |
|---|
| 56 | substitution and wish to replace the current event (which invokes the |
|---|
| 57 | substitution) with the command created through substitution. The return |
|---|
| 58 | value is an empty string. |
|---|
| 59 | .TP |
|---|
| 60 | \fBhistory clear\fR |
|---|
| 61 | Erase the history list. The current keep limit is retained. |
|---|
| 62 | The history event numbers are reset. |
|---|
| 63 | .TP |
|---|
| 64 | \fBhistory event\fR ?\fIevent\fR? |
|---|
| 65 | Returns the value of the event given by \fIevent\fR. \fIEvent\fR |
|---|
| 66 | defaults to \fB\-1\fR. |
|---|
| 67 | .TP |
|---|
| 68 | \fBhistory info \fR?\fIcount\fR? |
|---|
| 69 | Returns a formatted string (intended for humans to read) giving |
|---|
| 70 | the event number and contents for each of the events in the history |
|---|
| 71 | list except the current event. If \fIcount\fR is specified |
|---|
| 72 | then only the most recent \fIcount\fR events are returned. |
|---|
| 73 | .TP |
|---|
| 74 | \fBhistory keep \fR?\fIcount\fR? |
|---|
| 75 | This command may be used to change the size of the history list to |
|---|
| 76 | \fIcount\fR events. Initially, 20 events are retained in the history |
|---|
| 77 | list. If \fIcount\fR is not specified, the current keep limit is returned. |
|---|
| 78 | .TP |
|---|
| 79 | \fBhistory nextid\fR |
|---|
| 80 | Returns the number of the next event to be recorded |
|---|
| 81 | in the history list. It is useful for things like printing the |
|---|
| 82 | event number in command-line prompts. |
|---|
| 83 | .TP |
|---|
| 84 | \fBhistory redo \fR?\fIevent\fR? |
|---|
| 85 | Re-executes the command indicated by \fIevent\fR and returns its result. |
|---|
| 86 | \fIEvent\fR defaults to \fB\-1\fR. This command results in history |
|---|
| 87 | revision: see below for details. |
|---|
| 88 | .SH "HISTORY REVISION" |
|---|
| 89 | .PP |
|---|
| 90 | Pre-8.0 Tcl had a complex history revision mechanism. |
|---|
| 91 | The current mechanism is more limited, and the old |
|---|
| 92 | history operations \fBsubstitute\fR and \fBwords\fR have been removed. |
|---|
| 93 | (As a consolation, the \fBclear\fR operation was added.) |
|---|
| 94 | .PP |
|---|
| 95 | The history option \fBredo\fR results in much simpler |
|---|
| 96 | .QW "history revision" . |
|---|
| 97 | When this option is invoked then the most recent event |
|---|
| 98 | is modified to eliminate the history command and replace it with |
|---|
| 99 | the result of the history command. |
|---|
| 100 | If you want to redo an event without modifying history, then use |
|---|
| 101 | the \fBevent\fR operation to retrieve some event, |
|---|
| 102 | and the \fBadd\fR operation to add it to history and execute it. |
|---|
| 103 | .SH KEYWORDS |
|---|
| 104 | event, history, record |
|---|
