This chapter explains some of Octave's basic features, including how to start an Octave session, get help at the command prompt, edit the command line, and write Octave programs that can be executed as commands from your shell.
Normally, Octave is used interactively by running the program `octave' without any arguments. Once started, Octave reads commands from the terminal until you tell it to exit.
You can also specify the name of a file on the command line, and Octave will read and execute the commands from the named file and then exit when it is finished.
You can further control how Octave starts by using the command-line options described in the next section, and Octave itself can remind you of the options available. Type `octave --help' to display all available options and briefly describe their use (`octave -h' is a shorter equivalent).
Here is a complete list of all the command line options that Octave accepts.
--debug
-d
--echo-commands
-x
--exec-path path
OCTAVE_EXEC_PATH found in the environment, but not any commands
in the system or user startup files that set the built-in variable
EXEC_PATH.
--help
-h
-?
--info-file filename
OCTAVE_INFO_FILE found in the environment, but not any commands
in the system or user startup files that set the built-in variable
INFO_FILE.
--info-program program
OCTAVE_INFO_PROGRAM found in the environment, but not any
commands in the system or user startup files that set the built-in
variable INFO_PROGRAM.
--interactive
-i
--no-history
-H
--no-init-file
--no-line-editing
--no-site-file
--norc
-f
--no-init-file
and --no-site-file.
--path path
-p path
OCTAVE_PATH found in the environment, but not any commands in the
system or user startup files that set the built-in variable LOADPATH.
--silent
--quiet
-q
--traditional
--braindead
PS1 = ">> " PS2 = "" beep_on_error = 1 default_save_format = "mat-binary" define_all_return_values = 1 do_fortran_indexing = 1 crash_dumps_octave_core = 0 empty_list_elements_ok = 1 implicit_str_to_num_ok = 1 ok_to_lose_imaginary_part = 1 page_screen_output = 0 prefer_column_vectors = 0 print_empty_dimensions = 0 treat_neg_dim_as_zero = 1 warn_function_name_clash = 0 whitespace_in_literal_matrix = "traditional"
--verbose
-V
--version
-v
file
Octave also includes several built-in variables that contain information about the command line, including the number of arguments and all of the options.
@anchor{doc-argv}
octave --no-line-editing --silent
argv would be a cell array of strings with the elements
--no-line-editing and --silent.
If you write an executable Octave script, argv will contain the
list of arguments passed to the script. See section Executable Octave Programs,
for an example of how to create an executable Octave script.
@anchor{doc-program_invocation_name}
program_invocation_name is automatically set to the name that was
typed at the shell prompt to run Octave, and the value of
program_name is automatically set to the final component of
program_invocation_name. For example, if you typed
`/usr/local/bin/octave' to start Octave,
program_invocation_name would have the value
"/usr/local/bin/octave", and program_name would
have the value "octave".
If executing a script from the command line (e.g., octave foo.m)
or using an executable Octave script, the program name is set to the
name of the script. See section Executable Octave Programs, for an example of
how to create an executable Octave script.
Here is an example of using these variables to reproduce Octave's command line.
printf ("%s", program_name);
for i = 1:nargin
printf (" %s", nth (argv, i));
endfor
printf ("\n");
See section Index Expressions, for an explanation of how to properly index
arrays of strings and substrings in Octave, and See section Defining Functions,
for information about the variable nargin.
When Octave starts, it looks for commands to execute from the following files:
octave-home/share/octave/site/m/startup/octaverc
octave-home/share/octave/version/m/startup/octaverc
~/.octaverc
.octaverc
cd
command in the `~/.octaverc' file will affect the directory that
Octave searches for the file `.octaverc'.
If you start Octave in your home directory, commands from from the file
`~/.octaverc' will only be executed once.
A message will be displayed as each of the startup files is read if you
invoke Octave with the --verbose option but without the
--silent option.
Startup files may contain any valid Octave commands, including function definitions.
@anchor{doc-quit}
@anchor{doc-atexit}
function print_fortune ()
printf ("\n%s\n", system ("fortune"));
fflush (stdout);
endfunction
atexit ("print_fortune");
will print a message when Octave exits.
The entire text of this manual is available from the Octave prompt via the command help -i. In addition, the documentation for individual user-written functions and variables is also available via the help command. This section describes the commands used for reading the manual and the documentation strings for user-supplied functions and variables. See section Function Files, for more information about how to document the functions you write.
@anchor{doc-help}
help command can be used to print brief usage-style
messages, or to display information directly from an on-line version of
the printed manual, using the GNU Info browser. If invoked without any
arguments, help prints a list of all the available operators,
functions, and built-in variables. If the first argument is -i,
the help command searches the index of the on-line version of
this manual for the given topics.
For example, the command help help prints a short message
describing the help command, and help -i help starts the
GNU Info browser at this node in the on-line version of the manual.
Once the GNU Info browser is running, help for using it is available using the command C-h.
The help command can give you information about operators, but not the comma and semicolons that are used as command separators. To get help for those, you must type help comma or help semicolon.
@anchor{doc-INFO_FILE}
INFO_FILE names the location of the Octave info file.
The default value is "octave-home/info/octave.info", in
which octave-home is the directory where all of Octave is installed.
@anchor{doc-INFO_PROGRAM}
INFO_PROGRAM names the info program to run. Its
default initial value is
"octave-home/libexec/octave/version/exec/arch/info"
in which octave-home is the directory where all of Octave is
installed, version is the Octave version number, and arch
is the system type (for example, i686-pc-linux-gnu). The
default initial value may be overridden by the environment variable
OCTAVE_INFO_PROGRAM, or the command line argument
--info-program NAME, or by setting the value of
INFO_PROGRAM in a startup script
@anchor{doc-MAKEINFO_PROGRAM}
MAKEINFO_PROGRAM names the makeinfo program that
Octave runs to format help text that contains Texinfo markup commands.
Its default initial value is "makeinfo".
@anchor{doc-suppress_verbose_help_message}
suppress_verbose_help_message is nonzero, Octave
will not add additional help information to the end of the output from
the help command and usage messages for built-in commands.
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 charcters 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.
The following commands allow you to position the cursor.
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.
@anchor{doc-clc}
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.
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.
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.
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.
The following commands allow Octave to complete command and variable names for you.
@anchor{doc-completion_append_char}
completion_append_char is used as the character to
append to successful command-line completion attempts. The default
value is " " (a single space).
@anchor{doc-completion_matches}
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.
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.
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.
@anchor{doc-history}
history displays a list of commands
that you have executed. Valid options are:
-w file
-r file
n
-q
For example, to display the five most recent commands that you have typed without displaying line numbers, use the command history -q 5.
@anchor{doc-edit_history}
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.
@anchor{doc-run_history}
edit_history, except that the editor is not invoked,
and the commands are simply executed as they appear in the history list.
@anchor{doc-EDITOR}
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".
@anchor{doc-history_file}
"~/.octave_hist", but may be
overridden by the environment variable OCTAVE_HISTFILE.
@anchor{doc-history_size}
1024, but may be overridden by the
environment variable OCTAVE_HISTSIZE.
@anchor{doc-saving_history}
saving_history is nonzero, command entered
on the command line are saved in the file specified by the variable
history_file.
readline@anchor{doc-read_readline_init_file}
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:
@anchor{doc-PS1}
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. See section Strings.
@anchor{doc-PS2}
PS1 at the beginning of each line after the first. The default
value of PS2 is "> ".
@anchor{doc-PS4}
--echo-input option, the value of
PS4 is printed before each line of input that is echoed. The
default value of PS4 is "+ ". See section Invoking Octave, for
a description of --echo-input.
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.
@anchor{doc-diary}
on
off
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.
@anchor{doc-echo}
on
off
on all
off all
If invoked without any arguments, echo toggles the current echo
state.
@anchor{doc-echo_executing_commands}
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.
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.
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. See section 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.
See section 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");
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 (see section Commands for 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.
Go to the first, previous, next, last section, table of contents.