Octave Mode
***********

Copyright © 1996--2014 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License.''

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.''

Overview
********

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.

Using Octave Mode
*****************

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

C-M-j
     Break Octave line at point, continuing comment if within one.  Insert octave-continuation-string before breaking the line unless inside a list.  Signal an error if within a single-quoted string.

C-c ;
     Query replace function names in function file comment.

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 beginning of the physical 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 end of the physical 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-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 (smie-close-block). An error is signaled if no block to close is found.

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

     in one of your Emacs startup files.

The following variables can be used to customize Octave mode.

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-font-lock-texinfo-comment
     Highlight texinfo comment blocks.  The default value is t.

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 built-in operators (&&, ==, ...) using font-lock-reference-face

  * and the function names in function declarations in font-lock-function-name-face.

  * Function comments blocks in octave-function-comment-block

There is also rudimentary support for Imenu (see Imenu (The GNU Emacs Manual)).  Currently, function names can be indexed.

ElDoc mode (see Lisp Doc (The GNU Emacs Manual)) is supported.  By customizing octave-eldoc-message-style it can be changed from displaying one or multi line hints.

Customization of Octave mode can be performed by modification of the variable octave-mode-hook.

Running Octave from Within Emacs
********************************

Octave mode 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.

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 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 C-i b
     Send the current block to the inferior Octave process (octave-send-block).

C-c C-i f
     Send the current function to the inferior Octave process (octave-send-defun).

C-c C-i r
     Send the region to the inferior Octave process (octave-send-region).

C-c C-i a
     Send the entire buffer to the inferior Octave process (octave-send-buffer).  If the buffer is associated with a file then sourcing the buffer by using C-c C-l (octave-source-file) should be preferred.

C-c C-i s
     Make sure that `inferior-octave-buffer' is displayed (octave-show-process-buffer).

C-c C-i q
     Delete all windows that display the inferior Octave buffer (octave-hide-process-buffer).

C-c C-i k
     Kill the inferior Octave process and its buffer (octave-kill-process).

C-c C-l
     Parse and execute the current file in the inferior Octave buffer (octave-source-file).  This is done using Octave's source function.

M-.
     Find the definition of a function or variable.  Functions implemented in C++ can be found if variable octave-source-directories is set correctly (octave-find-definition).

C-h d
     Display the documentation for function (octave-help).  The buffer name can be changed by customizing octave-help-buffer.

C-h a
     Search for a given string in all the first sentence of function help strings (octave-lookfor).  With a universal-argument the entire help string is searched.

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.  The default is ~/.emacs-octave or if this file is not found ~/.emacs.d/init_octave.m.

By customizing inferior-octave-prompt-read-only the prompt can be changed to be read only.  The default value is the same as comint-prompt-read-only.

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 ()
                 (define-key inferior-octave-mode-map [up]
                   'comint-previous-input)
                 (define-key inferior-octave-mode-map [down]
                   'comint-next-input)))

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

     Note that 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 not know when Octave is waiting for input, or done sending output.

GNU Free Documentation License
******************************

     [file doclicense.texi not included]