2.4.5 Commands for Manipulating the History

Octave normally keeps track of the commands you type so that you can recall previous commands to edit or execute them again. When you exit Octave, the most recent commands you have typed, up to the number specified by the variable history_size, are saved in a file. When Octave starts, it loads an initial list of commands from the file named by the variable history_file.

Here are the commands for simple browsing and searching the history list.

LFD

RET

Accept the current line regardless of where the cursor is. If the line is non-empty, add it to the history list. If the line was a history line, then restore the history line to its original state.

C-p

Move ‘up’ through the history list.

C-n

Move ‘down’ through the history list.

M-<

Move to the first line in the history.

M->

Move to the end of the input history, i.e., the line you are entering!

C-r

Search backward starting at the current line and moving ‘up’ through the history as necessary. This is an incremental search.

C-s

Search forward starting at the current line and moving ‘down’ through the history as necessary.

On most terminals, you can also use the up and down arrow keys in place of C-p and C-n to move through the history list.

In addition to the keyboard commands for moving through the history list, Octave provides three functions for viewing, editing, and re-running chunks of commands from the history list.

: history

: history opt1 …

: h = history ()

: h = history (opt1, …)

If invoked with no arguments, history displays a list of commands that you have executed.

Valid options are:

n

-n

Display only the most recent n lines of history.

-c

Clear the history list.

-q

Don’t number the displayed lines of history. This is useful for cutting and pasting commands using the X Window System.

-r file

Read the file file, appending its contents to the current history list. If the name is omitted, use the default history file (normally ~/.octave_hist).

-w file

Write the current history to the file file. If the name is omitted, use the default history file (normally ~/.octave_hist).

For example, to display the five most recent commands that you have typed without displaying line numbers, use the command history -q 5.

If invoked with a single output argument, the history will be saved to that argument as a cell string and will not be output to screen.

See also: edit_history, run_history.

: edit_history

: edit_history cmd_number

: edit_history first last

Edit the history list using the editor named by the variable EDITOR.

The commands to be edited are first copied to a temporary file. When you exit the editor, Octave executes the commands that remain in the file. It is often more convenient to use edit_history to define functions rather than attempting to enter them directly on the command line. The block of commands is executed as soon as you exit the editor. To avoid executing any commands, simply delete all the lines from the buffer before leaving the editor.

When invoked with no arguments, edit the previously executed command; With one argument, edit the specified command cmd_number; With two arguments, edit the list of commands between first and last. Command number specifiers may also be negative where -1 refers to the most recently executed command. The following are equivalent and edit the most recently executed command.

edit_history
edit_history -1

When using ranges, specifying a larger number for the first command than the last command reverses the list of commands before they are placed in the buffer to be edited.

See also: run_history, history.

: run_history

: run_history cmd_number

: run_history first last

Run commands from the history list.

When invoked with no arguments, run the previously executed command;

With one argument, run the specified command cmd_number;

With two arguments, run the list of commands between first and last. Command number specifiers may also be negative where -1 refers to the most recently executed command. For example, the command

run_history
     OR
run_history -1

executes the most recent command again. The command

run_history 13 169

executes commands 13 through 169.

Specifying a larger number for the first command than the last command reverses the list of commands before executing them. For example:

disp (1)
disp (2)
run_history -1 -2
⇒
 2
 1

See also: edit_history, history.

Octave also allows you customize the details of when, where, and how history is saved.

: val = history_save ()

: old_val = history_save (new_val)

: history_save (new_val, "local")

Query or set the internal variable that controls whether commands entered on the command line are saved in the history file.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: history_control, history_file, history_size, history_timestamp_format_string.

: val = history_control ()

: old_val = history_control (new_val)

Query or set the internal variable that specifies how commands are saved to the history list.

The default value is an empty character string, but may be overridden by the environment variable OCTAVE_HISTCONTROL.

The value of history_control is a colon-separated list of values controlling how commands are saved on the history list. If the list of values includes ignorespace, lines which begin with a space character are not saved in the history list. A value of ignoredups causes lines matching the previous history entry to not be saved. A value of ignoreboth is shorthand for ignorespace and ignoredups. A value of erasedups causes all previous lines matching the current line to be removed from the history list before that line is saved. Any value not in the above list is ignored. If history_control is the empty string, all commands are saved on the history list, subject to the value of history_save.

See also: history_file, history_size, history_timestamp_format_string, history_save.

: val = history_file ()

: old_val = history_file (new_val)

Query or set the internal variable that specifies the name of the file used to store command history.

All future commands issued during the current Octave session will be written to this new file (if the current setting of history_save allows for this).

The default value is ~/.octave_hist, but may be overridden by the environment variable OCTAVE_HISTFILE.

Programming Notes:

If you want to permanently change the location of Octave’s history file you need to issue the history_file command in every new Octave session. This can be achieved by using Octave’s .octaverc startup file.

If you also want to read the saved history commands of past Octave sessions from this different history file, then you need to use the additional command history -r after setting the new value of the history file. Example code in Octave’s startup file to do this might look like this:

history_file ("~/new/.octave_hist");
if (exist (history_file ()))
  history ("-r", history_file());
endif

See also: history, history_control, history_save, history_size, history_timestamp_format_string.

: val = history_size ()

: old_val = history_size (new_val)

Query or set the internal variable that specifies how many entries to store in the history file.

The default value is 1000, but may be overridden by the environment variable OCTAVE_HISTSIZE.

See also: history_file, history_timestamp_format_string, history_save.

: val = history_timestamp_format_string ()

: old_val = history_timestamp_format_string (new_val)

: history_timestamp_format_string (new_val, "local")

Query or set the internal variable that specifies the format string for the comment line that is written to the history file when Octave exits.

The format string is passed to strftime. The default value is

"# Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@HOST>"

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: strftime, history_file, history_size, history_save.

: val = EDITOR ()

: old_val = EDITOR (new_val)

: EDITOR (new_val, "local")

Query or set the internal variable that specifies the default text editor.

The default value is taken from the environment variable EDITOR when Octave starts. If the environment variable is not initialized, EDITOR will be set to "emacs".

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: edit, edit_history.