NAME
       history - Manipulate the history list

SYNOPSIS
       history ?option? ?arg arg ...?


DESCRIPTION
       The  history  command  performs  one of several operations
       related to recently-executed commands recorded in  a  his-
       tory list.  Each of these recorded commands is referred to
       as an ``event''.  When specifying an event to the  history
       command, the following forms may be used:

       [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  (-1  refers  to  the
              previous  event,  -2 to the one before that, and so
              on).

       [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 string
              match command.

       The history command can take any of the following forms:

       history
              Same as history info, described below.

       history add command ?exec?
              Adds  the command argument to the history list as a
              new event.  If exec is specified  (or  abbreviated)
              then the command is also executed and its result is
              returned.  If exec isn't specified  then  an  empty
              string is returned as result.

       history change newValue ?event?
              Replaces  the value recorded for an event with new-
              Value.  Event specifies the event to  replace,  and
              defaults to the current event (not event -1).  This
              command is intended for use in commands that imple-
              ment  new forms of history substitution and wish to
              replace the current event (which invokes  the  sub-
              stitution) with the command created through substi-
              tution.  The return value is an empty string.

       history event ?event?
              Returns the value of  the  event  given  by  event.
              Event  defaults to -1.  This command causes history
              revision to occur: see below for details.
       history info ?count?
              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  cur-
              rent  event.   If  count is specified then only the
              most recent count events are returned.

       history keep count
              This command may be used to change the size of  the
              history list to count events.  Initially, 20 events
              are retained in the  history  list.   This  command
              returns an empty string.

       history nextid
              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.

       history redo ?event?
              Re-executes the  command  indicated  by  event  and
              return  its  result.   Event  defaults to -1.  This
              command results in history revision:  see below for
              details.

       history substitute old new ?event?
              Retrieves   the  command  given  by  event  (-1  by
              default), replace any occurrences of old by new  in
              the command (only simple character equality is sup-
              ported; no wild cards), execute the resulting  com-
              mand,  and  return  the  result  of that execution.
              This command  results  in  history  revision:   see
              below for details.

       history words selector ?event?
              Retrieves  from  the  command given by event (-1 by
              default) the words given by  selector,  and  return
              those  words  in a string separated by spaces.  The
              selector argument has three forms.  If it is a sin-
              gle  number  then it selects the word given by that
              number (0 for the command name,  1  for  its  first
              argument,  and  so on).  If it consists of two num-
              bers separated by a dash, then it selects  all  the
              arguments between those two.  Otherwise selector is
              treated as a pattern; all words matching that  pat-
              tern  (in  the sense of string match) are returned.
              In the numeric forms $ may be used  to  select  the
              last  word  of a command.  For example, suppose the
              most recent command in the history list is

                     format  {%s is %d years old} Alice [expr $ageInMonths/12]
              Below are some history  commands  and  the  results
              they would produce:
                     history words $ [expr $ageInMonths/12]
                     history words 1-2{%s is %d years  old} Alice
                     history words *a*o*{%s is %d years old} [expr $ageInMonths/12]
              History  words  results  in  history revision:  see
              below for details.

HISTORY REVISION
       The history options event,  redo,  substitute,  and  words
       result in ``history revision''.  When one of these options
       is invoked then the current event is modified to eliminate
       the  history command and replace it with the result of the
       history command.   For  example,  suppose  that  the  most
       recent command in the history list is

              set a [expr $b+2]
       and  suppose  that  the next command invoked is one of the
       ones on the left side of the  table  below.   The  command
       actually  recorded in the history event will be the corre-
       sponding one on the right side of the table.


              history redo    set a [expr $b+2]
              history s a b   set b [expr $b+2]
              set c [history w 2]set c [expr $b+2]
       History revision is needed because event  specifiers  like
       -1  are only valid at a particular time:  once more events
       have been added to the  history  list  a  different  event
       specifier  would  be needed.  History revision occurs even
       when history is invoked indirectly from the current  event
       (e.g.  a user types a command that invokes a Tcl procedure
       that invokes history):  the top-level command whose execu-
       tion eventually resulted in a history command is replaced.
       If you wish to invoke commands like history words  without
       history  revision,  you  can use history event to save the
       current history event  and  then  use  history  change  to
       restore it later.


KEYWORDS
       event, history, record, revision
