Octave Terminal Control
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 and then
press . 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 and pressing
. If your terminal does not have a key, you can still type
Meta charcters using two-character sequences starting with `ESC'.
Thus, to enter `M-u', you could type . 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'.
* Menu:
* Cursor Motion::
* Killing and Yanking::
* Commands For Text::
* Commands For Completion::
* Commands For History::
* Customizing readline::
* Customizing the Prompt::
* Diary and Echo Commands::
Cursor Motion
-------------
The following commands allow you to position the cursor.
`C-b'
Move back one character.
`C-f'
Move forward one character.
`'
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.
There is also a function available so that you can clear the screen
from within Octave programs.
- Built-in Function: clc ()
- Built-in Function: home ()
Clear the terminal screen and move the cursor to the upper left
corner.
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-'
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-' 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.
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-'
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'
Lowecase 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.
Letting Readline Type For You
-----------------------------
The following commands allow Octave to complete command and variable
names for you.
`'
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 Variable: completion_append_char
The value of `completion_append_char' is used as the character to
append 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.
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.
`'
`'
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.
- Built-in Variable: EDITOR
A string naming 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"'.
- Built-in Variable: history_file
This variable 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'.
- Built-in Variable: history_size
This variable 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'.
- Built-in Variable: saving_history
If the value of `saving_history' is nonzero, command entered on
the command line are saved in the file specified by the variable
`history_file'.
Customizing `readline'
----------------------
- Built-in Function: read_readline_init_file (FILE)
Read the readline library initialiazation file FILE. If FILE is
omitted, read the default initialization file (normally
`~/.inputrc'.
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 Variable: PS1
The primary prompt string. When executing interactively, Octave
displays the primary prompt `PS1' when it is ready to read a
command.
The default value of `PS1' 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 string.
*Note Strings::.
- Built-in Variable: PS2
The secondary prompt string, which is printed when Octave is
expecting additional input to complete a command. For example,
when defining a function over several lines, Octave will print the
value of `PS1' at the beginning of each line after the first. The
default value of `PS2' is `"> "'.
- Built-in Variable: PS4
If Octave is invoked with the `--echo-input' option, the value of
`PS4' is printed before each line of input that is echoed. The
default value of `PS4' is `"+ "'. *Note Invoking Octave::, for a
description of `--echo-input'.
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 Variable: echo_executing_commands
This variable may also be used to control 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'.
How Octave Reports Errors
=========================
Octave reports two kinds of errors for invalid programs.
A "parse error" occurs if Octave cannot understand something you
have typed. For example, if you misspell a keyword,
octave:13> functon y = f (x) y = x^2; endfunction
Octave will respond immediately with a message like this:
parse error:
functon y = f (x) y = x^2; endfunction
^
For most parse errors, Octave uses a caret (`^') to mark the point on
the line where it was unable to make sense of your input. In this
case, Octave generated an error message because the keyword `function'
was misspelled. Instead of seeing `function f', Octave saw two
consecutive variable names, which is invalid in this context. It
marked the error at `y' because the first name by itself was accepted
as valid input.
Another class of error message occurs at evaluation time. These
errors are called "run-time errors", or sometimes "evaluation errors"
because they occur when your program is being "run", or "evaluated".
For example, if after correcting the mistake in the previous function
definition, you type
octave:13> f ()
Octave will respond with
error: `x' undefined near line 1 column 24
error: evaluating expression near line 1, column 24
error: evaluating assignment expression near line 1, column 22
error: called from `f'
This error message has several parts, and gives you quite a bit of
information to help you locate the source of the error. The messages
are generated from the point of the innermost error, and provide a
traceback of enclosing expressions and function calls.
In the example above, the first line indicates that a variable named
`x' was found to be undefined near line 1 and column 24 of some
function or expression. For errors occurring within functions, lines
are counted from the beginning of the file containing the function
definition. For errors occurring at the top level, the line number
indicates the input line number, which is usually displayed in the
prompt string.
The second and third lines in the example indicate that the error
occurred within an assignment expression, and the last line of the error
message indicates that the error occurred within the function `f'. If
the function `f' had been called from another function, for example,
`g', the list of errors would have ended with one more line:
error: called from `g'
These lists of function calls usually make it fairly easy to trace
the path your program took before the error occurred, and to correct the
error before trying again.
Executable Octave Programs
==========================
Once you have learned Octave, you may want to write self-contained
Octave scripts, using the `#!' script mechanism. You can do this on
GNU systems and on many Unix systems (1)
For example, you could create a text file named `hello', containing
the following lines:
#! OCTAVE-INTERPRETER-NAME -qf
# a sample Octave program
printf ("Hello, world!\n");
(where OCTAVE-INTERPRETER-NAME should be replaced with the full file
name for your Octave binary). After making this file executable (with
the `chmod' command), you can simply type:
hello
at the shell, and the system will arrange to run Octave as if you had
typed:
octave hello
The line beginning with `#!' lists the full file name of an
interpreter to be run, and an optional initial command line argument to
pass to that interpreter. The operating system then runs the
interpreter with the given argument and the full argument list of the
executed program. The first argument in the list is the full file name
of the Octave program. The rest of the argument list will either be
options to Octave, or data files, or both. The `-qf' option is usually
specified in stand-alone Octave programs to prevent them from printing
the normal startup message, and to keep them from behaving differently
depending on the contents of a particular user's `~/.octaverc' file.
*Note Invoking Octave::. Note that some operating systems may place a
limit on the number of characters that are recognized after `#!'.
Self-contained Octave scripts are useful when you want to write a
program which users can invoke without knowing that the program is
written in the Octave language.
If you invoke an executable Octave script with command line
arguments, the arguments are available in the built-in variable `argv'.
*Note Command Line Options::. For example, the following program will
reproduce the command line that is used to execute it.
#! /bin/octave -qf
printf ("%s", program_name);
for i = 1:nargin
printf (" %s", argv(i,:));
endfor
printf ("\n");
---------- Footnotes ----------
(1) The `#!' mechanism works on Unix systems derived from Berkeley
Unix, System V Release 4, and some System V Release 3 systems.
Comments in Octave Programs
===========================
A "comment" is some text that is included in a program for the sake
of human readers, and that is not really part of the program. Comments
can explain what the program does, and how it works. Nearly all
programming languages have provisions for comments, because programs are
typically hard to understand without them.
In the Octave language, a comment starts with either the sharp sign
character, `#', or the percent symbol `%' and continues to the end of
the line. The Octave interpreter ignores the rest of a line following
a sharp sign or percent symbol. For example, we could have put the
following into the function `f':
function xdot = f (x, t)
# usage: f (x, t)
#
# This function defines the right hand
# side functions for a set of nonlinear
# differential equations.
r = 0.25;
...
endfunction
The `help' command (*note Getting Help::) is able to find the first
block of comments in a function (even those that are composed directly
on the command line). This means that users of Octave can use the same
commands to get help for built-in functions, and for functions that you
have defined. For example, after defining the function `f' above, the
command `help f' produces the output
usage: f (x, t)
This function defines the right hand
side functions for a set of nonlinear
differential equations.
Although it is possible to put comment lines into keyboard-composed
throw-away Octave programs, it usually isn't very useful, because the
purpose of a comment is to help you or another person understand the
program at a later time.
Data Types
**********
All versions of Octave include a number of built-in data types,
including real and complex scalars and matrices, character strings, and
a data structure type.
It is also possible to define new specialized data types by writing a
small amount of C++ code. On some systems, new data types can be loaded
dynamically while Octave is running, so it is not necessary to recompile
all of Octave just to add a new type. *Note Dynamically Linked
Functions::, for more information about Octave's dynamic linking
capabilities. *Note User-defined Data Types:: describes what you must
do to define a new data type for Octave.
- Built-in Function: typeinfo (EXPR)
Return the type of the expression EXPR, as a string. If EXPR is
omitted, return an array of strings containing all the currently
installed data types.