2.4 Command Line Editing

Octave uses the GNU readline library to provide an extensive set of command-line editing and history features. Only the most common features are described in this manual. Please see The GNU Readline Library manual for more information.

To insert printing characters (letters, digits, symbols, etc.), simply type the character. Octave will insert the character at the cursor and advance the cursor forward.

Many of the command-line editing functions operate using control characters. For example, the character Control-a moves the cursor to the beginning of the line. To type C-a, hold down CTRL and then press a. In the following sections, control characters such as Control-a are written as C-a.

Another set of command-line editing functions use Meta characters. On some terminals, you type M-u by holding down META and pressing u. If your terminal does not have a META key, you can still type Meta characters using two-character sequences starting with ESC. Thus, to enter M-u, you could type ESCu. The ESC character sequences are also allowed on terminals with real Meta keys. In the following sections, Meta characters such as Meta-u are written as M-u.

2.4.1 Cursor Motion

The following commands allow you to position the cursor.

C-b

Move back one character.

C-f

Move forward one character.

DEL

Delete the character to the left of the cursor.

C-d

Delete the character underneath the cursor.

M-f

Move forward a word.

M-b

Move backward a word.

C-a

Move to the start of the line.

C-e

Move to the end of the line.

C-l

Clear the screen, reprinting the current line at the top.

C-_

C-/

Undo the last thing that you did. You can undo all the way back to an empty line.

M-r

Undo all changes made to this line. This is like typing the `undo' command enough times to get back to the beginning.

The above table describes the most basic possible keystrokes that you need in order to do editing of the input line. On most terminals, you can also use the arrow keys in place of C-f and C-b to move forward and backward.

Notice how C-f moves forward a character, while M-f moves forward a word. It is a loose convention that control keystrokes operate on characters while meta keystrokes operate on words.

The function clc will allow you to clear the screen from within Octave programs.

2.4.2 Killing and Yanking

Killing text means to delete the text from the line, but to save it away for later use, usually by yanking it back into the line. If the description for a command says that it `kills' text, then you can be sure that you can get the text back in a different (or the same) place later.

Here is the list of commands for killing text.

C-k

Kill the text from the current cursor position to the end of the line.

M-d

Kill from the cursor to the end of the current word, or if between words, to the end of the next word.

M-DEL

Kill from the cursor to the start of the previous word, or if between words, to the start of the previous word.

C-w

Kill from the cursor to the previous whitespace. This is different than M-DEL because the word boundaries differ.

And, here is how to yank the text back into the line. Yanking means to copy the most-recently-killed text from the kill buffer.

C-y

Yank the most recently killed text back into the buffer at the cursor.

M-y

Rotate the kill-ring, and yank the new top. You can only do this if the prior command is C-y or M-y.

When you use a kill command, the text is saved in a kill-ring. Any number of consecutive kills save all of the killed text together, so that when you yank it back, you get it in one clean sweep. The kill ring is not line specific; the text that you killed on a previously typed line is available to be yanked back later, when you are typing another line.

2.4.3 Commands For Changing Text

The following commands can be used for entering characters that would otherwise have a special meaning (e.g., TAB, C-q, etc.), or for quickly correcting typing mistakes.

C-q

C-v

Add the next character that you type to the line verbatim. This is how to insert things like C-q for example.

M-TAB

Insert a tab character.

C-t

Drag the character before the cursor forward over the character at the cursor, also moving the cursor forward. If the cursor is at the end of the line, then transpose the two characters before it.

M-t

Drag the word behind the cursor past the word in front of the cursor moving the cursor over that word as well.

M-u

Uppercase the characters following the cursor to the end of the current (or following) word, moving the cursor to the end of the word.

M-l

Lowercase the characters following the cursor to the end of the current (or following) word, moving the cursor to the end of the word.

M-c

Uppercase the character following the cursor (or the beginning of the next word if the cursor is between words), moving the cursor to the end of the word.

2.4.4 Letting Readline Type For You

The following commands allow Octave to complete command and variable names for you.

TAB

Attempt to do completion on the text before the cursor. Octave can complete the names of commands and variables.

M-?

List the possible completions of the text before the cursor.

Built-in Function: val = completion_append_char ()

Built-in Function: old_val = completion_append_char (new_val)

Query or set the internal character variable that is appended to successful command-line completion attempts. The default value is " " (a single space).

Built-in Function: completion_matches (hint)

Generate possible completions given hint.

This function is provided for the benefit of programs like Emacs which might be controlling Octave and handling user input. The current command number is not incremented when this function is called. This is a feature, not a bug.

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 line regardless of where the cursor is. If this line is non-empty, add it to the history list. If this 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 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.

Command: history options

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

-w file

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

-r file

Read the file file, replacing the current history list with its contents. If the name is omitted, use the default history file (normally `~/.octave_hist').

n

Only display the most recent n lines of history.

-q

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

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

Command: edit_history options

If invoked with no arguments, edit_history allows you to 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. By default, 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 exiting the editor.

The edit_history command takes two optional arguments specifying the history numbers of first and last commands to edit. For example, the command

edit_history 13

extracts all the commands from the 13th through the last in the history list. The command

edit_history 13 169

only extracts commands 13 through 169. Specifying a larger number for the first command than the last command reverses the list of commands before placing them in the buffer to be edited. If both arguments are omitted, the previous command in the history list is used.

Command: run_history [first] [last]

Similar to edit_history, except that the editor is not invoked, and the commands are simply executed as they appear in the history list.

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

Built-in Function: val = history_file ()

Built-in Function: old_val = history_file (new_val)

Query or set the internal variable that specifies the name of the file used to store command history. The default value is "~/.octave_hist", but may be overridden by the environment variable OCTAVE_HISTFILE.
See also: history_size, saving_history, history_timestamp_format_string.

Built-in Function: val = history_size ()

Built-in Function: 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 1024, but may be overridden by the environment variable OCTAVE_HISTSIZE.
See also: history_file, history_timestamp_format, saving_history.

Built-in Function: val = saving_history ()

Built-in Function: old_val = saving_history (new_val)

Query or set the internal variable that controls whether commands entered on the command line are saved in the history file.
See also: history_file, history_size, history_timestamp_format.

Built-in Function: val = history_timestamp_format_string ()

Built-in Function: old_val = history_timestamp_format_string (new_val)

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>"

See also: strftime, history_file, history_size, saving_history.

Built-in Function: val = EDITOR ()

Built-in Function: old_val = EDITOR (new_val)

Query or set the internal variable that specifies the editor to use with the edit_history command. If the environment variable EDITOR is set when Octave starts, its value is used as the default. Otherwise, EDITOR is set to "emacs".
See also: edit_history.

2.4.6 Customizing readline

As mentioned earlier Octave uses the GNU readline library for command-line editing and history features. It is possible to customize how readline works through a configuration file.

Built-in Function: read_readline_init_file (file)

Read the readline library initialization file file. If file is omitted, read the default initialization file (normally `~/.inputrc').

See (readline)Readline Init File section `Readline Init File' in GNU Readline Library, for details.

2.4.7 Customizing the Prompt

The following variables are available for customizing the appearance of the command-line prompts. Octave allows the prompt to be customized by inserting a number of backslash-escaped special characters that are decoded as follows:

`\t'

The time.

`\d'

The date.

`\n'

Begins a new line by printing the equivalent of a carriage return followed by a line feed.

`\s'

The name of the program (usually just `octave').

`\w'

The current working directory.

`\W'

The basename of the current working directory.

`\u'

The username of the current user.

`\h'

The hostname, up to the first `.'.

`\H'

The hostname.

`\#'

The command number of this command, counting from when Octave starts.

`\!'

The history number of this command. This differs from `\#' by the number of commands in the history list when Octave starts.

`\$'

If the effective UID is 0, a `#', otherwise a `$'.

`\nnn'

The character whose character code in octal is nnn.

`\\'

A backslash.

Built-in Function: val = PS1 ()

Built-in Function: old_val = PS1 (new_val)

Query or set the primary prompt string. When executing interactively, Octave displays the primary prompt when it is ready to read a command.

The default value of the primary prompt string is "\s:\#> ". To change it, use a command like

octave:13> PS1 ("\\u@\\H> ")

which will result in the prompt `boris@kremvax> ' for the user `boris' logged in on the host `kremvax.kgb.su'. Note that two backslashes are required to enter a backslash into a double-quoted character string. See section Strings.
See also: PS2, PS4.

Built-in Function: val = PS2 ()

Built-in Function: old_val = PS2 (new_val)

Query or set the secondary prompt string. The secondary prompt is printed when Octave is expecting additional input to complete a command. For example, if you are typing a for loop that spans several lines, Octave will print the secondary prompt at the beginning of each line after the first. The default value of the secondary prompt string is "> ".
See also: PS1, PS4.

Built-in Function: val = PS4 ()

Built-in Function: old_val = PS4 (new_val)

Query or set the character string used to prefix output produced when echoing commands when echo_executing_commands is enabled. The default value is "+ ". See section Invoking Octave from the Command Line, for a description of --echo-commands.
See also: echo_executing_commands, PS1, PS2.

2.4.8 Diary and Echo Commands

Octave's diary feature allows you to keep a log of all or part of an interactive session by recording the input you type and the output that Octave produces in a separate file.

Command: diary options

Create a list of all commands and the output they produce, mixed together just as you see them on your terminal. Valid options are:

on

Start recording your session in a file called `diary' in your current working directory.

off

Stop recording your session in the diary file.

file

Record your session in the file named file.

Without any arguments, diary toggles the current diary state.

Sometimes it is useful to see the commands in a function or script as they are being evaluated. This can be especially helpful for debugging some kinds of problems.

Command: echo options

Control whether commands are displayed as they are executed. Valid options are:

on

Enable echoing of commands as they are executed in script files.

off

Disable echoing of commands as they are executed in script files.

on all

Enable echoing of commands as they are executed in script files and functions.

off all

Disable echoing of commands as they are executed in script files and functions.

If invoked without any arguments, echo toggles the current echo state.

Built-in Function: val = echo_executing_commands ()

Built-in Function: old_val = echo_executing_commands (new_val)

Query or set the internal variable that controls the echo state. It may be the sum of the following values:

1

Echo commands read from script files.

2

Echo commands from functions.

4

Echo commands read from command line.

More than one state can be active at once. For example, a value of 3 is equivalent to the command echo on all.

The value of echo_executing_commands is set by the echo command and the command line option --echo-input.

This document was generated on December, 26 2007 using texi2html 1.76.