## `history` -- access an entry of the history table

#### Introduction

`history(`n`)` returns the `n`th entry of the history table.

`history(``)` returns the index of the most recent entry in the history table.

#### Call(s)

`history(n)`
`history()`

#### Parameters

`n` | - | a positive integer

#### Returns

`history(`n`)` returns a list with two elements, and `history(``)` returns a nonnegative integer.

#### Related Functions

`fread`, `HISTORY`, `last`, `read`

#### Details

- The commands that are entered interactively in a MuPAD session, executed in a procedure, or read from a file, as well as the resulting MuPAD outputs are stored in an internal data structure, the history table. `history(``)` returns the index of the most recent entry in the history table. At interactive level, this is the number of commands that have been entered since the start of the session or the last restart.

- `history(`n`)` returns the `n`th entry in the history table in form of a list with two elements. The first element of this list is a MuPAD command, and the second element is the result of this command returned by MuPAD. The order of the entries in the history table is such that larger indices correspond to more recent entries.

- The command `last` accesses the result entries from the history table. The call `last(n)` is equivalent to ``history(``history(``)` - n + 1`)`[2]` at interactive level.

- The environment variable `HISTORY` determines the maximal number of history entries that are stored at interactive level. The default value is `20`. Only the most recent entries are kept in memory. Thus valid arguments for `history` are all integers between ``history(``)` - HISTORY + 1` and `history(``)`. All other integers lead to an error message.

- The result returned by `history` is not evaluated again (see example 2). Use the function `eval` to force a subsequent evaluation.
- Commands and their results are stored in the history table even if the output is suppressed by a colon. See example 1.

- Compound statements, such as `for`, `repeat`, and `while` loops, `if` and `case` branching instructions, and procedure definitions via `proc` are stored in the history table as a whole at interactive level. See the help page of `last` for examples.

- Commands appearing on the same input line lead to separate entries in the history table if they are separated by a colon or a semicolon. In contrast, a statement sequence is regarded as a single command (see example 3).
- Commands that are read from a file via `fread` or `read` are stored in the history table, and at last the `fread` or `read` command is stored in the history table (because the `fread` or `read` command is finished foremost after reading the file). However, if the option Plain is used, then a separate history table is in effect within the file, and the commands from the file do not appear in the history table of the enclosing context.
- Note that every call of `history` modifies the history table and possibly erases the earliest history entry.

- Every procedure has its own local history table. However, the entries of this table cannot be accessed via `history` (see `last`); the command `history` always refers to the history table at interactive level .
- `history` is a function of the system kernel.

#### Example 1

The index of the most recent entry in the history table increases by one for each entered command, also by `history(``)`. Note that every command is stored in the history table, whether its output is suppressed by a colon or not:

    >> history(); sqrt(1764); history(): history()

                                         3

                                        42

                                         6

`history(``history(``)``)` returns a list with two elements. The first element is the last command, and the second element is the result returned by MuPAD, which is equal to `last(1)` or `%`:

    >> int(2*x*exp(x^2), x);
       history(history()), last(1)

                                           2
                                      exp(x )

                                    2            2         2
                      [int(2 x exp(x ), x), exp(x )], exp(x )

The following command returns the next to last command and its result:

    >> history(history() - 1)

                                        2            2
                          [int(2 x exp(x ), x), exp(x )]

A restart cleans up the history table:

    >> reset():
       history()

                                         4

The output of the command `history(``)` above depends on the number of commands in your MuPAD startup file `userinit.mu`.

#### Example 2

First `a` should be `0`:

    >> a := 0:
       a

                                         0

Now `1` is assigned to `a`:

    >> a := 1:
       a

                                         1

The command `history(``history(``)`-2`)` refers to the command `a` after assigning `0` to `a`, the return value of `history` is not the new value of `a`, because the result returned by `history` is not evaluated again:

    >> history(history() - 2)

                                      [a, 0]

#### Example 3

The both commands leads to two entries in the history table. The command `history(``history(``)`-1`)` returns only the last command `b:=a`, not both commands:

    >> a := 0: b := a:
       history(history() - 1)

                                   [(a := 0), 0]

If the commands are entered as an statement sequence (enclosed in `( )`), they leads to one entry. `history(``history(``)``)` picks out the last command, that is the statement sequence:

    >> (a := 0; b := a;):
       history(history())

                                    [(a := 0;
                                    b := a), 0]

The last input

    >> type(op(%, 1))

                                    "_stmtseq"

#### Changes

- The argument may be either empty or a nonnegative integer.
- `history` returns the current history index or a list with two elements.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000