raw/mann/history.n

   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.1 2003/12/20 03:31:54 bbbush Exp $
   9 '\"
  10 '\" The definitions below are for supplemental macros used in Tcl/Tk
  11 '\" manual entries.
  12 '\"
  13 '\" .AP type name in/out ?indent?
  14 '\"     Start paragraph describing an argument to a library procedure.
  15 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  16 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  17 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  18 '\"     needed;  use .AS below instead)
  19 '\"
  20 '\" .AS ?type? ?name?
  21 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  22 '\"     name are examples of largest possible arguments that will be passed
  23 '\"     to .AP later.  If args are omitted, default tab stops are used.
  24 '\"
  25 '\" .BS
  26 '\"     Start box enclosure.  From here until next .BE, everything will be
  27 '\"     enclosed in one large box.
  28 '\"
  29 '\" .BE
  30 '\"     End of box enclosure.
  31 '\"
  32 '\" .CS
  33 '\"     Begin code excerpt.
  34 '\"
  35 '\" .CE
  36 '\"     End code excerpt.
  37 '\"
  38 '\" .VS ?version? ?br?
  39 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  40 '\"     of man pages.  The first argument is ignored and used for recording
  41 '\"     the version when the .VS was added, so that the sidebars can be
  42 '\"     found and removed when they reach a certain age.  If another argument
  43 '\"     is present, then a line break is forced before starting the sidebar.
  44 '\"
  45 '\" .VE
  46 '\"     End of vertical sidebar.
  47 '\"
  48 '\" .DS
  49 '\"     Begin an indented unfilled display.
  50 '\"
  51 '\" .DE
  52 '\"     End of indented unfilled display.
  53 '\"
  54 '\" .SO
  55 '\"     Start of list of standard options for a Tk widget.  The
  56 '\"     options follow on successive lines, in four columns separated
  57 '\"     by tabs.
  58 '\"
  59 '\" .SE
  60 '\"     End of list of standard options for a Tk widget.
  61 '\"
  62 '\" .OP cmdName dbName dbClass
  63 '\"     Start of description of a specific option.  cmdName gives the
  64 '\"     option's name as specified in the class command, dbName gives
  65 '\"     the option's name in the option database, and dbClass gives
  66 '\"     the option's class in the option database.
  67 '\"
  68 '\" .UL arg1 arg2
  69 '\"     Print arg1 underlined, then print arg2 normally.
  70 '\"
  71 '\" RCS: @(#) $Id: history.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
  72 '\"
  73 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  74 .if t .wh -1.3i ^B
  75 .nr ^l \n(.l
  76 .ad b
  77 '\"     # Start an argument description
  78 .de AP
  79 .ie !"\\$4"" .TP \\$4
  80 .el \{\
  81 .   ie !"\\$2"" .TP \\n()Cu
  82 .   el          .TP 15
  83 .\}
  84 .ta \\n()Au \\n()Bu
  85 .ie !"\\$3"" \{\
  86 \&\\$1  \\fI\\$2\\fP    (\\$3)
  87 .\".b
  88 .\}
  89 .el \{\
  90 .br
  91 .ie !"\\$2"" \{\
  92 \&\\$1  \\fI\\$2\\fP
  93 .\}
  94 .el \{\
  95 \&\\fI\\$1\\fP
  96 .\}
  97 .\}
  98 ..
  99 '\"     # define tabbing values for .AP
 100 .de AS
 101 .nr )A 10n
 102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 103 .nr )B \\n()Au+15n
 104 .\"
 105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 107 ..
 108 .AS Tcl_Interp Tcl_CreateInterp in/out
 109 '\"     # BS - start boxed text
 110 '\"     # ^y = starting y location
 111 '\"     # ^b = 1
 112 .de BS
 113 .br
 114 .mk ^y
 115 .nr ^b 1u
 116 .if n .nf
 117 .if n .ti 0
 118 .if n \l'\\n(.lu\(ul'
 119 .if n .fi
 120 ..
 121 '\"     # BE - end boxed text (draw box now)
 122 .de BE
 123 .nf
 124 .ti 0
 125 .mk ^t
 126 .ie n \l'\\n(^lu\(ul'
 127 .el \{\
 128 .\"     Draw four-sided box normally, but don't draw top of
 129 .\"     box if the box started on an earlier page.
 130 .ie !\\n(^b-1 \{\
 131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 132 .\}
 133 .el \}\
 134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 135 .\}
 136 .\}
 137 .fi
 138 .br
 139 .nr ^b 0
 140 ..
 141 '\"     # VS - start vertical sidebar
 142 '\"     # ^Y = starting y location
 143 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 144 .de VS
 145 .if !"\\$2"" .br
 146 .mk ^Y
 147 .ie n 'mc \s12\(br\s0
 148 .el .nr ^v 1u
 149 ..
 150 '\"     # VE - end of vertical sidebar
 151 .de VE
 152 .ie n 'mc
 153 .el \{\
 154 .ev 2
 155 .nf
 156 .ti 0
 157 .mk ^t
 158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 159 .sp -1
 160 .fi
 161 .ev
 162 .\}
 163 .nr ^v 0
 164 ..
 165 '\"     # Special macro to handle page bottom:  finish off current
 166 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 167 '\"     # page bottom macro.
 168 .de ^B
 169 .ev 2
 170 'ti 0
 171 'nf
 172 .mk ^t
 173 .if \\n(^b \{\
 174 .\"     Draw three-sided box if this is the box's first page,
 175 .\"     draw two sides but no top otherwise.
 176 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 178 .\}
 179 .if \\n(^v \{\
 180 .nr ^x \\n(^tu+1v-\\n(^Yu
 181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 182 .\}
 183 .bp
 184 'fi
 185 .ev
 186 .if \\n(^b \{\
 187 .mk ^y
 188 .nr ^b 2
 189 .\}
 190 .if \\n(^v \{\
 191 .mk ^Y
 192 .\}
 193 ..
 194 '\"     # DS - begin display
 195 .de DS
 196 .RS
 197 .nf
 198 .sp
 199 ..
 200 '\"     # DE - end display
 201 .de DE
 202 .fi
 203 .RE
 204 .sp
 205 ..
 206 '\"     # SO - start of list of standard options
 207 .de SO
 208 .SH "STANDARD OPTIONS"
 209 .LP
 210 .nf
 211 .ta 5.5c 11c
 212 .ft B
 213 ..
 214 '\"     # SE - end of list of standard options
 215 .de SE
 216 .fi
 217 .ft R
 218 .LP
 219 See the \\fBoptions\\fR manual entry for details on the standard options.
 220 ..
 221 '\"     # OP - start of full description for a single option
 222 .de OP
 223 .LP
 224 .nf
 225 .ta 4c
 226 Command-Line Name:      \\fB\\$1\\fR
 227 Database Name:  \\fB\\$2\\fR
 228 Database Class: \\fB\\$3\\fR
 229 .fi
 230 .IP
 231 ..
 232 '\"     # CS - begin code excerpt
 233 .de CS
 234 .RS
 235 .nf
 236 .ta .25i .5i .75i 1i
 237 ..
 238 '\"     # CE - end code excerpt
 239 .de CE
 240 .fi
 241 .RE
 242 ..
 243 .de UL
 244 \\$1\l'|0\(ul'\\$2
 245 ..
 246 .TH history n "" Tcl "Tcl Built-In Commands"
 247 .BS
 248 '\" Note:  do not modify the .SH NAME line immediately below!
 249 .SH NAME
 250 history \- Manipulate the history list
 251 .SH SYNOPSIS
 252 \fBhistory \fR?\fIoption\fR? ?\fIarg arg ...\fR?
 253 .BE
 254
 255 .SH DESCRIPTION
 256 .PP
 257 The \fBhistory\fR command performs one of several operations related to
 258 recently-executed commands recorded in a history list.  Each of
 259 these recorded commands is referred to as an ``event''.  When
 260 specifying an event to the \fBhistory\fR command, the following
 261 forms may be used:
 262 .IP [1]
 263 A number:  if positive, it refers to the event with
 264 that number (all events are numbered starting at 1).  If the number
 265 is negative, it selects an event relative to the current event
 266 (\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and
 267 so on).  Event \fB0\fP refers to the current event.
 268 .IP [2]
 269 A string:  selects the most recent event that matches the string.
 270 An event is considered to match the string either if the string is
 271 the same as the first characters of the event, or if the string
 272 matches the event in the sense of the \fBstring match\fR command.
 273 .PP
 274 The \fBhistory\fR command can take any of the following forms:
 275 .TP
 276 \fBhistory\fR
 277 Same
 278 as \fBhistory info\fR, described below.
 279 .TP
 280 \fBhistory add\fI command \fR?\fBexec\fR?
 281 Adds the \fIcommand\fR argument to the history list as a new event.  If
 282 \fBexec\fR is specified (or abbreviated) then the command is also
 283 executed and its result is returned.  If \fBexec\fR isn't specified
 284 then an empty string is returned as result.
 285 .TP
 286 \fBhistory change\fI newValue\fR ?\fIevent\fR?
 287 Replaces the value recorded for an event with \fInewValue\fR.  \fIEvent\fR
 288 specifies the event to replace, and
 289 defaults to the \fIcurrent\fR event (not event \fB\-1\fR).  This command
 290 is intended for use in commands that implement new forms of history
 291 substitution and wish to replace the current event (which invokes the
 292 substitution) with the command created through substitution.  The return
 293 value is an empty string.
 294 .TP
 295 \fBhistory clear\fR
 296 Erase the history list.  The current keep limit is retained.
 297 The history event numbers are reset.
 298 .TP
 299 \fBhistory event\fR ?\fIevent\fR?
 300 Returns the value of the event given by \fIevent\fR.  \fIEvent\fR
 301 defaults to \fB\-1\fR.
 302 .TP
 303 \fBhistory info \fR?\fIcount\fR?
 304 Returns a formatted string (intended for humans to read) giving
 305 the event number and contents for each of the events in the history
 306 list except the current event.  If \fIcount\fR is specified
 307 then only the most recent \fIcount\fR events are returned.
 308 .TP
 309 \fBhistory keep \fR?\fIcount\fR?
 310 This command may be used to change the size of the history list to
 311 \fIcount\fR events.  Initially, 20 events are retained in the history
 312 list.  If \fIcount\fR is not specified, the current keep limit is returned.
 313 .TP
 314 \fBhistory nextid\fR
 315 Returns the number of the next event to be recorded
 316 in the history list.  It is useful for things like printing the
 317 event number in command-line prompts.
 318 .TP
 319 \fBhistory redo \fR?\fIevent\fR?
 320 Re-executes the command indicated by \fIevent\fR and return its result.
 321 \fIEvent\fR defaults to \fB\-1\fR.  This command results in history
 322 revision:  see below for details.
 323 .SH "HISTORY REVISION"
 324 .PP
 325 Pre-8.0 Tcl had a complex history revision mechanism.
 326 The current mechanism is more limited, and the old
 327 history operations \fBsubstitute\fP and \fBwords\fP have been removed.
 328 (As a consolation, the \fBclear\fP operation was added.)
 329 .PP
 330 The history option \fBredo\fR results in much simpler ``history revision''.
 331 When this option is invoked then the most recent event
 332 is modified to eliminate the history command and replace it with
 333 the result of the history command.
 334 If you want to redo an event without modifying history, then use
 335 the \fBevent\fP operation to retrieve some event,
 336 and the \fBadd\fP operation to add it to history and execute it.
 337
 338 .SH KEYWORDS
 339 event, history, record