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

Emacs Octave Support

The development of Octave code can greatly be facilitated using Emacs with Octave mode, a major mode for editing Octave files which can e.g. automatically indent the code, do some of the typing (with Abbrev mode) and show keywords, comments, strings, etc. in different faces (with Font-lock mode on devices that support it).

It is also possible to run Octave from within Emacs, either by directly entering commands at the prompt in a buffer in Inferior Octave mode, or by interacting with Octave from within a file with Octave code. This is useful in particular for debugging Octave code.

Finally, you can convince Octave to use the Emacs info reader for help -i.

All functionality is provided by the Emacs Lisp package EOS (for "Emacs Octave Support"). This chapter describes how to set up and use this package.

Please contact <Kurt.Hornik@ci.tuwien.ac.at> if you have any questions or suggestions on using EOS.

Installing EOS

The Emacs package EOS consists of the three files `octave-mod.el', `octave-inf.el', and `octave-hlp.el'. These files, or better yet their byte-compiled versions, should be somewhere in your Emacs load-path.

If you have GNU Emacs with a version number at least as high as 19.35, you are all set up, because EOS is respectively will be part of GNU Emacs as of version 19.35.

Otherwise, copy the three files from the `emacs' subdirectory of the Octave distribution to a place where Emacs can find them (this depends on how your Emacs was installed). Byte-compile them for speed if you want.

Using Octave Mode

If you are lucky, your sysadmins have already arranged everything so that Emacs automatically goes into Octave mode whenever you visit an Octave code file as characterized by its extension `.m'. If not, proceed as follows.

To begin using Octave mode for all `.m' files you visit, add the following lines to a file loaded by Emacs at startup time, typically your `~/.emacs' file:
```
(autoload 'octave-mode "octave-mod" nil t)
(setq auto-mode-alist
      (cons '("\\.m$" . octave-mode) auto-mode-alist))
```
Finally, to turn on the abbrevs, auto-fill and font-lock features automatically, also add the following lines to one of the Emacs startup files:
```
(add-hook 'octave-mode-hook
          (lambda ()
            (abbrev-mode 1)
            (auto-fill-mode 1)
            (if (eq window-system 'x)
                (font-lock-mode 1))))
```
See the Emacs manual for more information about how to customize Font-lock mode.

In Octave mode, the following special Emacs commands can be used in addition to the standard Emacs commands.

C-h m

Describe the features of Octave mode.

LFD

Reindent the current Octave line, insert a newline and indent the new line (octave-reindent-then-newline-and-indent). An abbrev before point is expanded if abbrev-mode is non-nil.

TAB

Indents current Octave line based on its contents and on previous lines (indent-according-to-mode).

;

Insert an "electric" semicolon (octave-electric-semi). If octave-auto-indent is non-nil, reindent the current line. If octave-auto-newline is non-nil, automagically insert a newline and indent the new line.

`

Start entering an abbreviation (octave-abbrev-start). If Abbrev mode is turned on, typing `C-h or `? lists all abbrevs. Any other key combination is executed normally. Note that all Octave abbrevs start with a grave accent.

M-LFD

Break line at point and insert continuation marker and alignment (octave-split-line).

M-TAB

Perform completion on Octave symbol preceding point, comparing that symbol against Octave's reserved words and builtin variables (octave-complete-symbol).

M-C-a

Move backward to the beginning of a function (octave-beginning-of-defun). With prefix argument N, do it that many times if N is positive; otherwise, move forward to the N-th following beginning of a function.

M-C-e

Move forward to the end of a function (octave-end-of-defun). With prefix argument N, do it that many times if N is positive; otherwise, move back to the N-th preceding end of a function.

M-C-h

Puts point at beginning and mark at the end of the current Octave function, i.e., the one containing point or following point (octave-mark-defun).

M-C-q

Properly indents the Octave function which contains point (octave-indent-defun).

M-;

If there is no comment already on this line, create a code-level comment (started by two comment characters) if the line is empty, or an in-line comment (started by one comment character) otherwise (octave-indent-for-comment). Point is left after the start of the comment which is properly aligned.

C-c ;

Puts the comment character `#' (more precisely, the string value of octave-comment-start) at the beginning of every line in the region (octave-comment-region). With just C-u prefix argument, uncomment each line in the region. A numeric prefix argument N means use N comment characters.

C-c :

Uncomments every line in the region (octave-uncomment-region).

C-c C-p

Move one line of Octave code backward, skipping empty and comment lines (octave-previous-code-line). With numeric prefix argument N, move that many code lines backward (forward if N is negative).

C-c C-n

Move one line of Octave code forward, skipping empty and comment lines (octave-next-code-line). With numeric prefix argument N, move that many code lines forward (backward if N is negative).

C-c C-a

Move to the `real' beginning of the current line (octave-beginning-of-line). If point is in an empty or comment line, simply go to its beginning; otherwise, move backwards to the beginning of the first code line which is not inside a continuation statement, i.e., which does not follow a code line ending in `...' or `\', or is inside an open parenthesis list.

C-c C-e

Move to the `real' end of the current line (octave-end-of-line). If point is in a code line, move forward to the end of the first Octave code line which does not end in `...' or `\' or is inside an open parenthesis list. Otherwise, simply go to the end of the current line.

C-c M-C-n

Move forward across one balanced begin-end block of Octave code (octave-forward-block). With numeric prefix argument N, move forward across n such blocks (backward if N is negative).

C-c M-C-p

Move back across one balanced begin-end block of Octave code (octave-backward-block). With numeric prefix argument N, move backward across N such blocks (forward if N is negative).

C-c M-C-d

Move forward down one begin-end block level of Octave code (octave-down-block). With numeric prefix argument, do it that many times; a negative argument means move backward, but still go down one level.

C-c M-C-u

Move backward out of one begin-end block level of Octave code (octave-backward-up-block). With numeric prefix argument, do it that many times; a negative argument means move forward, but still to a less deep spot.

C-c M-C-h

Put point at the beginning of this block, mark at the end (octave-mark-block). The block marked is the one that contains point or follows point.

C-c ]

Close the current block on a separate line (octave-close-block). An error is signaled if no block to close is found.

C-c f

Insert a function skeleton, prompting for the function's name, arguments and return values which have to be entered without parens (octave-insert-defun).

C-c C-h

Search the function, operator and variable indices of all info files with documentation for Octave for entries (octave-help). If used interactively, the entry is prompted for with completion. If multiple matches are found, one can cycle through them using the standard `,' (Info-index-next) command of the Info reader. The variable octave-help-files is a list of files to search through and defaults to '("octave"). If there is also an Octave Local Guide with corresponding info file, say, `octave-LG', you can have octave-help search both files by

(setq octave-help-files '("octave" "octave-LG"))

in one of your Emacs startup files.

A common problem is that the RET key does not indent the line to where the new text should go after inserting the newline. This is because the standard Emacs convention is that RET (aka C-m) just adds a newline, whereas LFD (aka C-j) adds a newline and indents it. This is particularly inconvenient for users with keyboards which do not have a special LFD key at all; in such cases, it is typically more convenient to use RET as the LFD key (rather than typing C-j).

You can make RET do this by adding

(define-key octave-mode-map "\C-m"
  'octave-reindent-then-newline-and-indent)

to one of your Emacs startup files. Another, more generally applicable solution is

(defun RET-behaves-as-LFD ()
  (let ((x (key-binding "\C-j")))
    (local-set-key "\C-m" x)))
(add-hook 'octave-mode-hook 'RET-behaves-as-LFD)

(this works for all modes by adding to the startup hooks, without having to know the particular binding of RET in that mode!). Similar considerations apply for using M-RET as M-LFD. As Barry A. Warsaw <bwarsaw@cnri.reston.va.us> says in the documentation for his cc-mode, "This is a very common question. :-) If you want this to be the default behavior, don't lobby me, lobby RMS!"

The following variables can be used to customize Octave mode.

octave-auto-indent: Non-nil means auto-indent the current line after a semicolon or space. Default is nil.
octave-auto-newline: Non-nil means auto-insert a newline and indent after semicolons are typed. The default value is nil.
octave-blink-matching-block: Non-nil means show matching begin of block when inserting a space, newline or `;' after an else or end keyword. Default is t. This is an extremely useful feature for automatically verifying that the keywords match--if they don't, an error message is displayed.
octave-block-offset: Extra indentation applied to statements in block structures. Default is 2.
octave-continuation-offset: Extra indentation applied to Octave continuation lines. Default is 4.
octave-continuation-string: String used for Octave continuation lines. Normally `\'.
octave-mode-startup-message: If t (default), a startup message is displayed when Octave mode is called.

If Font Lock mode is enabled, Octave mode will display

strings in font-lock-string-face
comments in font-lock-comment-face
the Octave reserved words (such as all block keywords) and the text functions (such as `cd' or `who') which are also reserved using font-lock-keyword-face
the builtin operators (`&&', `<>', ...) using font-lock-reference-face
the builtin variables (such as `prefer_column_vectors', `NaN' or `LOADPATH') in font-lock-variable-name-face
and the function names in function declarations in font-lock-function-name-face.

There is also rudimentary support for Imenu (currently, function names can be indexed).

You can generate TAGS files for Emacs from Octave `.m' files using the shell script otags that is installed alongside your copy of Octave.

Customization of Octave mode can be performed by modification of the variable octave-mode-hook. It the value of this variable is non-nil, turning on Octave mode calls its value.

If you discover a problem with Octave mode, you can conveniently send a bug report using C-c C-b (octave-submit-bug-report). This automatically sets up a mail buffer with version information already added. You just need to add a description of the problem, including a reproducible test case and send the message.

Running Octave From Within Emacs

The package `octave' provides commands for running an inferior Octave process in a special Emacs buffer. Use

M-x run-octave

to directly start an inferior Octave process. If Emacs does not know about this command, add the line

(autoload 'run-octave "octave-inf" nil t)

to your `.emacs' file.

This will start Octave in a special buffer the name of which is specified by the variable inferior-octave-buffer and defaults to "*Inferior Octave*". From within this buffer, you can interact with the inferior Octave process `as usual', i.e., by entering Octave commands at the prompt. The buffer is in Inferior Octave mode, which is derived from the standard Comint mode, a major mode for interacting with an inferior interpreter. See the documentation for comint-mode for more details, and use C-h b to find out about available special keybindings.

You can also communicate with an inferior Octave process from within files with Octave code (i.e., buffers in Octave mode), using the following commands.

C-c i l: Send the current line to the inferior Octave process (octave-send-line). With positive prefix argument N, send that many lines. If octave-send-line-auto-forward is non-nil, go to the next unsent code line.
C-c i b: Send the current block to the inferior Octave process (octave-send-block).
C-c i f: Send the current function to the inferior Octave process (octave-send-defun).
C-c i r: Send the region to the inferior Octave process (octave-send-region).
C-c i s: Make sure that `inferior-octave-buffer' is displayed (octave-show-process-buffer).
C-c i h: Delete all windows that display the inferior Octave buffer (octave-hide-process-buffer).
C-c i k: Kill the inferior Octave process and its buffer (octave-kill-process).

The effect of the commands which send code to the Octave process can be customized by the following variables.

octave-send-echo-input: Non-nil means echo input sent to the inferior Octave process. Default is t.
octave-send-show-buffer: Non-nil means display the buffer running the Octave process after sending a command (but without selecting it). Default is t.

If you send code and there is no inferior Octave process yet, it will be started automatically.

The startup of the inferior Octave process is highly customizable. The variable inferior-octave-startup-args can be used for specifying command lines arguments to be passed to Octave on startup as a list of strings. For example, to suppress the startup message and use `traditional' mode, set this to '("-q" "--traditional"). You can also specify a startup file of Octave commands to be loaded on startup; note that these commands will not produce any visible output in the process buffer. Which file to use is controlled by the variable inferior-octave-startup-file. If this is nil, the file `~/.emacs-octave' is used if it exists.

And finally, inferior-octave-mode-hook is run after starting the process and putting its buffer into Inferior Octave mode. Hence, if you like the up and down arrow keys to behave in the interaction buffer as in the shell, and you want this buffer to use nice colors, add

(add-hook 'inferior-octave-mode-hook
          (lambda ()
            (turn-on-font-lock)
            (define-key inferior-octave-mode-map [up]
              'comint-previous-input)
            (define-key inferior-octave-mode-map [down]
              'comint-next-input)))

to your `.emacs' file. You could also swap the roles of C-a (beginning-of-line) and C-c C-a (comint-bol) using this hook.

Note: If you set your Octave prompts to something different from the defaults, make sure that inferior-octave-prompt matches them. Otherwise, nothing will work, because Emacs will have no idea when Octave is waiting for input, or done sending output.

Using the Emacs Info Reader for Octave

You can also set up the Emacs Info reader for dealing with the results of Octave's `help -i'. For this, the package `gnuserv' needs to be installed, which unfortunately still does not come with GNU Emacs (it does with XEmacs). It can be retrieved from any GNU Emacs Lisp Code Directory archive, e.g. @url{ftp://ftp.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive}, in the `packages' subdirectory. The alpha version of an enhanced version of gnuserv is available at @url{ftp://ftp.wellfleet.com/netman/psmith/emacs/gnuserv-2.1alpha.tar.gz}.

If `gnuserv' is installed, add the lines

(autoload 'octave-help "octave-hlp" nil t)
(require 'gnuserv)
(gnuserv-start)

to your `.emacs' file.

You can use either `plain' Emacs Info or the function octave-help as your Octave info reader (for `help -i'). In the former case, set the Octave variable INFO_PROGRAM to "info-emacs-info". The latter is perhaps more attractive because it allows to look up keys in the indices of several info files related to Octave (provided that the Emacs variable octave-help-files is set correctly). In this case, set INFO_PROGRAM to "info-emacs-octave-help".

If you use Octave from within Emacs, these settings are best done in the `~/.emacs-octave' startup file (or the file pointed to by the Emacs variable inferior-octave-startup-file).

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