GNU Octave - Getting Started

Go to the first, previous, next, last section, table of contents.

# Getting Started

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.

## Invoking Octave

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).

### Command Line Options

Here is a complete list of all the command line options that Octave accepts.

`--debug`
`-d`
  Enter parser debugging mode. Using this option will cause Octave's parser to print a lot of information about the commands it reads, and is probably only useful if you are actually trying to debug the parser.
`--echo-commands`
`-x`
  Echo commands as they are executed.
`--exec-path path`
  Specify the path to search for programs to run. The value of path specified on the command line will override any value of `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`
`-?`
  Print short help message and exit.
`--info-file filename`
  Specify the name of the info file to use. The value of filename specified on the command line will override any value of `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`
  Specify the name of the info program to use. The value of program specified on the command line will override any value of `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`
  Force interactive behavior. This can be useful for running Octave via a remote shell command or inside an Emacs shell buffer. For another way to run Octave within Emacs, see section Emacs Octave Support.
`--no-init-file`
  Don't read the ``~/.octaverc'` or ``.octaverc'` files.
`--no-line-editing`
  Disable command-line editing.
`--no-site-file`
  Don't read the site-wide ``octaverc'` file.
`--norc`
`-f`
  Don't read any of the system or user initialization files at startup. This is equivalent to using both of the options `--no-init-file` and `--no-site-file`.
`--path path`
`-p path`
  Specify the path to search for function files. The value of path specified on the command line will override any value of `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`
  Don't print the usual greeting and version message at startup.
`--traditional`
`--braindead`
  Set initial values for user-preference variables to the following values for compatibility with MATLAB.

      PS1                           = ">> "
      PS2                           = ""
      beep_on_error                 = 1
      default_save_format           = "mat-binary"
      define_all_return_values      = 1
      do_fortran_indexing           = 1
      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`
  Turn on verbose output.
`--version`
`-v`
  Print the program version number and exit.
`file`
  Execute commands from 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.

Built-in Variable: argv
  The command line arguments passed to Octave are available in this variable. For example, if you invoked Octave using the command

      octave --no-line-editing --silent

  `argv` would be a string vector 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.

Built-in Variable: program_invocation_name
Built-in Variable: program_name
  When Octave starts, the value of the built-in variable `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", 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`.

### Startup Files

When Octave starts, it looks for commands to execute from the following files:

`octave-home/share/octave/site/m/startup/octaverc`
  Where octave-home is the directory in which all of Octave is installed (the default is ``/usr/local'`). This file is provided so that changes to the default Octave environment can be made globally for all users at your site for all versions of Octave you have installed. Some care should be taken when making changes to this file, since all users of Octave at your site will be affected.
`octave-home/share/octave/version/m/startup/octaverc`
  Where octave-home is the directory in which all of Octave is installed (the default is ``/usr/local'`), and version is the version number of Octave. This file is provided so that changes to the default Octave environment can be made globally for all users for a particular version of Octave. Some care should be taken when making changes to this file, since all users of Octave at your site will be affected.
`~/.octaverc`
  This file is normally used to make personal changes to the default Octave environment.
`.octaverc`
  This file can be used to make changes to the default Octave environment for a particular project. Octave searches for this file in the current directory after it reads ``~/.octaverc'`. Any use of the `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.

## Quitting Octave

Built-in Function: exit (status)
Built-in Function: quit (status)
  Exit the current Octave session. If the optional integer value status is supplied, pass that value to the operating system as the Octave's exit status.

Built-in Function: atexit (fcn)
  Register function to be called when Octave exits. For example,

      function print_flops_at_exit ()
        printf ("\n%s\n", system ("fortune"));
        fflush (stdout);
      endfunction
      atexit ("print_flops_at_exit");

  will print a message when Octave exits.

## Commands for Getting Help

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.

Command: help
  Octave's `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`.

Built-in Variable: INFO_FILE
  The variable `INFO_FILE` names the location of the Octave info file. The default value is `"octave-home/info/octave.info"`, where octave-home is the directory where all of Octave is installed.

Built-in Variable: INFO_PROGRAM
  The variable `INFO_PROGRAM` names the info program to run. Its initial value is `"octave-home/libexec/octave/version/exec/arch/info"`, where octave-home is the directory where all of Octave is installed, version is the Octave version number, and arch is the machine type. The value of `INFO_PROGRAM` can be overridden by the environment variable `OCTAVE_INFO_PROGRAM`, or the command line argument `--info-program NAME`, or by setting the value of the built-in variable `INFO_PROGRAM` in a startup script.

Built-in Variable: suppress_verbose_help_message
  If the value of `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.

## 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 charcters using two-character sequences starting with `ESC`. Thus, to enter `M-u`, you could type `ESC` `u`. 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`.

### 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.

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-`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.

### 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`
  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.

``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 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.

``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
  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 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. See section 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 `"+ "`. See section 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 is 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 the `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 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. 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");

## 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 (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.