doc/misc/octave-mode.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename ../../info/octave-mode
   4 @settitle Octave Mode
   5 @documentencoding UTF-8
   6 @c %**end of header
   7
   8 @copying
   9 Copyright @copyright{} 1996--2014 Free Software Foundation, Inc.
  10
  11 @quotation
  12 Permission is granted to copy, distribute and/or modify this document
  13 under the terms of the GNU Free Documentation License, Version 1.3 or
  14 any later version published by the Free Software Foundation; with no
  15 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
  16 and with the Back-Cover Texts as in (a) below.  A copy of the license
  17 is included in the section entitled ``GNU Free Documentation License.''
  18
  19 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  20 modify this GNU manual.''
  21 @end quotation
  22 @end copying
  23
  24 @dircategory Emacs editing modes
  25 @direntry
  26 * Octave mode: (octave-mode).   Emacs mode for editing GNU Octave files.
  27 @end direntry
  28
  29 @finalout
  30
  31 @titlepage
  32 @title Octave Mode
  33 @subtitle An Emacs mode for programming in GNU Octave
  34
  35 @page
  36 @vskip 0pt plus 1filll
  37 @insertcopying
  38 @end titlepage
  39
  40 @contents
  41
  42 @ifnottex
  43 @node Top
  44 @top Octave Mode
  45
  46 @insertcopying
  47 @end ifnottex
  48
  49 @menu
  50 * Overview::
  51 * Using Octave Mode::
  52 * Running Octave from Within Emacs::
  53 * GNU Free Documentation License::
  54 * Key Index::
  55 * Variable Index::
  56 * Lisp Function Index::
  57 * Concept Index::
  58 @end menu
  59
  60 @node Overview
  61 @chapter Overview
  62
  63 The development of Octave code can greatly be facilitated using Emacs
  64 with Octave mode, a major mode for editing Octave files which can
  65 e.g.@: automatically indent the code, do some of the typing (with
  66 Abbrev mode) and show keywords, comments, strings, etc.@: in different
  67 faces (with Font-lock mode on devices that support it).
  68
  69 It is also possible to run Octave from within Emacs, either by
  70 directly entering commands at the prompt in a buffer in Inferior
  71 Octave mode, or by interacting with Octave from within a file with
  72 Octave code.  This is useful in particular for debugging Octave code.
  73
  74 @node Using Octave Mode
  75 @chapter Using Octave Mode
  76 @cindex Using Octave Mode
  77
  78 In Octave mode, the following special Emacs commands can be used in
  79 addition to the standard Emacs commands.
  80
  81 @table @kbd
  82 @item C-M-j
  83 @kindex C-M-j
  84 @findex octave-indent-new-comment-line
  85 @vindex octave-continuation-string
  86 Break Octave line at point, continuing comment if within one.  Insert
  87 @code{octave-continuation-string} before breaking the line unless
  88 inside a list.  Signal an error if within a single-quoted string.
  89
  90 @item C-c ;
  91 @kindex C-c ;
  92 @findex octave-update-function-file-comment
  93 Query replace function names in function file comment.
  94
  95 @item C-c C-p
  96 @kindex C-c C-p
  97 @findex octave-previous-code-line
  98 Move one line of Octave code backward, skipping empty and comment
  99 lines (@code{octave-previous-code-line}).  With numeric prefix
 100 argument @var{n}, move that many code lines backward (forward if
 101 @var{n} is negative).
 102
 103 @item C-c C-n
 104 @kindex C-c C-n
 105 @findex octave-next-code-line
 106 Move one line of Octave code forward, skipping empty and comment lines
 107 (@code{octave-next-code-line}).  With numeric prefix argument @var{n},
 108 move that many code lines forward (backward if @var{n} is negative).
 109
 110 @item C-c C-a
 111 @kindex C-c C-a
 112 @findex octave-beginning-of-line
 113 Move to the beginning of the physical line
 114 (@code{octave-beginning-of-line}).  If point is in an empty or comment
 115 line, simply go to its beginning; otherwise, move backwards to the
 116 beginning of the first code line which is not inside a continuation
 117 statement, i.e., which does not follow a code line ending in
 118 @samp{...}  or @samp{\}, or is inside an open parenthesis list.
 119
 120 @item C-c C-e
 121 @kindex C-c C-e
 122 @findex octave-end-of-line
 123 Move to the end of the physical line (@code{octave-end-of-line}).  If
 124 point is in a code line, move forward to the end of the first Octave
 125 code line which does not end in @samp{...} or @samp{\} or is inside an
 126 open parenthesis list.  Otherwise, simply go to the end of the current
 127 line.
 128
 129 @item C-c M-C-h
 130 @kindex C-c M-C-h
 131 @findex octave-mark-block
 132 Put point at the beginning of this block, mark at the end
 133 (@code{octave-mark-block}).  The block marked is the one that contains
 134 point or follows point.
 135
 136 @item C-c ]
 137 @kindex C-c ]
 138 Close the current block on a separate line (@code{smie-close-block}).
 139 An error is signaled if no block to close is found.
 140
 141 @item C-c C-f
 142 @kindex C-c C-f
 143 @findex octave-insert-defun
 144 Insert a function skeleton, prompting for the function's name, arguments
 145 and return values which have to be entered without parentheses
 146 (@code{octave-insert-defun}).
 147 @noindent
 148 in one of your Emacs startup files.
 149 @end table
 150
 151 A common problem is that the @key{RET} key does @emph{not} indent the
 152 line to where the new text should go after inserting the newline.  This
 153 is because the standard Emacs convention is that @key{RET} (aka
 154 @kbd{C-m}) just adds a newline, whereas @key{LFD} (aka @kbd{C-j}) adds a
 155 newline and indents it.  This is particularly inconvenient for users with
 156 keyboards which do not have a special @key{LFD} key at all; in such
 157 cases, it is typically more convenient to use @key{RET} as the @key{LFD}
 158 key (rather than typing @kbd{C-j}).
 159
 160 You can make @key{RET} do this by adding
 161 @lisp
 162 (define-key octave-mode-map "\C-m"
 163   'octave-reindent-then-newline-and-indent)
 164 @end lisp
 165 @noindent
 166 to one of your Emacs startup files.  Another, more generally applicable
 167 solution is
 168 @lisp
 169 (defun RET-behaves-as-LFD ()
 170   (let ((x (key-binding "\C-j")))
 171     (local-set-key "\C-m" x)))
 172 (add-hook 'octave-mode-hook 'RET-behaves-as-LFD)
 173 @end lisp
 174 @noindent
 175 (this works for all modes by adding to the startup hooks, without
 176 having to know the particular binding of @key{RET} in that mode!).
 177 Similar considerations apply for using @key{M-RET} as @key{M-LFD}.  As
 178 @email{bwarsaw@@cnri.reston.va.us, Barry A. Warsaw} says in the
 179 documentation for his @code{cc-mode}, ``This is a very common
 180 question.  @code{:-)} If you want this to be the default behavior,
 181 don't lobby me, lobby RMS!''
 182
 183 The following variables can be used to customize Octave mode.
 184
 185 @vtable @code
 186 @item octave-blink-matching-block
 187 Non-@code{nil} means show matching begin of block when inserting a space,
 188 newline or @samp{;} after an else or end keyword.  Default is @code{t}.
 189 This is an extremely useful feature for automatically verifying that the
 190 keywords match---if they don't, an error message is displayed.
 191
 192 @item octave-block-offset
 193 Extra indentation applied to statements in block structures.
 194 Default is 2.
 195
 196 @item octave-continuation-offset
 197 Extra indentation applied to Octave continuation lines.
 198 Default is 4.
 199
 200 @item octave-font-lock-texinfo-comment
 201 Highlight texinfo comment blocks.  The default value is @code{t}.
 202 @end vtable
 203
 204 If Font Lock mode is enabled, Octave mode will display
 205
 206 @itemize @bullet
 207 @item
 208 strings in @code{font-lock-string-face}
 209
 210 @item
 211 comments in @code{font-lock-comment-face}
 212
 213 @item
 214 the Octave reserved words (such as all block keywords) and the text
 215 functions (such as @samp{cd} or @samp{who}) which are also reserved
 216 using @code{font-lock-keyword-face}
 217
 218 @item
 219 the built-in operators (@samp{&&}, @samp{==}, @dots{}) using
 220 @code{font-lock-reference-face}
 221
 222 @item
 223 and the function names in function declarations in
 224 @code{font-lock-function-name-face}.
 225
 226 @item
 227 Function comments blocks in @code{octave-function-comment-block}
 228 @end itemize
 229
 230 @cindex Imenu Support
 231 There is also rudimentary support for Imenu (@pxref{Imenu,,, emacs,
 232 The GNU Emacs Manual}).  Currently, function names can be indexed.
 233
 234 @cindex ElDoc Mode Support
 235 @vindex octave-eldoc-message-style
 236 ElDoc mode (@pxref{Lisp Doc,,, emacs, The GNU Emacs Manual}) is
 237 supported.  By customizing @code{octave-eldoc-message-style} it can be
 238 changed from displaying one or multi line hints.
 239
 240 @c @cindex TAGS
 241 @c @cindex Emacs TAGS files
 242 @c @cindex @file{octave-tags}
 243 @c You can generate TAGS files for Emacs from Octave @file{.m} files using
 244 @c the shell script @file{octave-tags} that is installed alongside your copy of
 245 @c Octave.
 246 @c
 247 @vindex octave-mode-hook
 248 Customization of Octave mode can be performed by modification of the
 249 variable @code{octave-mode-hook}.
 250
 251 @node Running Octave from Within Emacs
 252 @chapter Running Octave from Within Emacs
 253 @cindex Inferior Octave Mode
 254
 255 Octave mode provides commands for running an inferior
 256 Octave process in a special Emacs buffer.  Use
 257 @lisp
 258 M-x run-octave
 259 @end lisp
 260 @noindent
 261 to directly start an inferior Octave process.
 262
 263 @vindex inferior-octave-buffer
 264 This will start Octave in a special buffer the name of which is
 265 specified by the variable @code{inferior-octave-buffer} and defaults
 266 to @file{*Inferior Octave*}.  From within this buffer, you can
 267 interact with the inferior Octave process `as usual', i.e., by
 268 entering Octave commands at the prompt.  The buffer is in Inferior
 269 Octave mode, which is derived from the standard Comint mode, a major
 270 mode for interacting with an inferior interpreter.  See the
 271 documentation for @code{comint-mode} for more details, and use
 272 @kbd{C-h b} to find out about available special keybindings.
 273
 274 You can also communicate with an inferior Octave process from within
 275 files with Octave code (i.e., buffers in Octave mode), using the
 276 following commands.
 277
 278 @table @kbd
 279 @item C-c C-i l
 280 @kindex C-c C-i l
 281 @findex octave-send-line
 282 @vindex octave-send-line-auto-forward
 283 Send the current line to the inferior Octave process
 284 (@code{octave-send-line}).  With positive prefix argument @var{n},
 285 send that many lines.  If @code{octave-send-line-auto-forward} is
 286 non-@code{nil}, go to the next unsent code line.
 287
 288 @item C-c C-i b
 289 @kindex C-c C-i b
 290 @findex octave-send-block
 291 Send the current block to the inferior Octave process
 292 (@code{octave-send-block}).
 293
 294 @item C-c C-i f
 295 @kindex C-c C-i f
 296 @findex octave-send-defun
 297 Send the current function to the inferior Octave process
 298 (@code{octave-send-defun}).
 299
 300 @item C-c C-i r
 301 @kindex C-c C-i r
 302 @findex octave-send-region
 303 Send the region to the inferior Octave process
 304 (@code{octave-send-region}).
 305
 306 @item C-c C-i a
 307 @kindex C-c C-i a
 308 @findex octave-send-buffer
 309 Send the entire buffer to the inferior Octave process
 310 (@code{octave-send-buffer}).  If the buffer is associated with a file
 311 then sourcing the buffer by using @kbd{C-c C-l}
 312 (@code{octave-source-file}) should be preferred.
 313
 314 @item C-c C-i s
 315 @kindex C-c C-i s
 316 @findex octave-show-process-buffer
 317 Make sure that `inferior-octave-buffer' is displayed
 318 (@code{octave-show-process-buffer}).
 319
 320 @item C-c C-i q
 321 @kindex C-c C-i q
 322 @findex octave-hide-process-buffer
 323 Delete all windows that display the inferior Octave buffer
 324 (@code{octave-hide-process-buffer}).
 325
 326 @item C-c C-i k
 327 @kindex C-c C-i k
 328 @findex octave-kill-process
 329 Kill the inferior Octave process and its buffer
 330 (@code{octave-kill-process}).
 331
 332 @item C-c C-l
 333 @kindex C-c C-l
 334 @findex octave-source-file
 335 Parse and execute the current file in the inferior Octave buffer
 336 (@code{octave-source-file}).  This is done using Octave's
 337 @code{source} function.
 338
 339 @item M-.
 340 @kindex M-.
 341 @findex octave-find-definition
 342 @vindex octave-source-directories
 343 Find the definition of a function or variable.  Functions implemented
 344 in C++ can be found if variable @code{octave-source-directories} is
 345 set correctly (@code{octave-find-definition}).
 346
 347 @item C-h d
 348 @kindex C-h d
 349 @findex octave-help
 350 @vindex octave-help-buffer
 351 Display the documentation for function (@code{octave-help}).  The
 352 buffer name can be changed by customizing @code{octave-help-buffer}.
 353
 354 @item C-h a
 355 @kindex C-h a
 356 @findex octave-lookfor
 357 Search for a given string in all the first sentence of function help
 358 strings (@code{octave-lookfor}).  With a @code{universal-argument} the
 359 entire help string is searched.
 360
 361 @end table
 362
 363 The effect of the commands which send code to the Octave process can be
 364 customized by the following variables.
 365
 366 @vtable @code
 367 @item octave-send-echo-input
 368 Non-@code{nil} means echo input sent to the inferior Octave process.
 369 Default is @code{t}.
 370
 371 @item octave-send-show-buffer
 372 Non-@code{nil} means display the buffer running the Octave process after
 373 sending a command (but without selecting it).
 374 Default is @code{t}.
 375 @end vtable
 376
 377 If you send code and there is no inferior Octave process yet, it will
 378 be started automatically.
 379
 380 @vindex inferior-octave-startup-args
 381 The startup of the inferior Octave process is highly customizable.
 382 The variable @code{inferior-octave-startup-args} can be used for
 383 specifying command lines arguments to be passed to Octave on startup
 384 as a list of strings.  For example, to suppress the startup message
 385 and use `traditional' mode, set this to @code{("-q" "--traditional")}.
 386 You can also specify a startup file of Octave commands to be loaded on
 387 startup; note that these commands will not produce any visible output
 388 in the process buffer.  Which file to use is controlled by the
 389 variable @code{inferior-octave-startup-file}.  The default is
 390 @file{~/.emacs-octave} or if this file is not found
 391 @file{~/.emacs.d/init_octave.m}.
 392
 393 @vindex inferior-octave-prompt-read-only
 394 By customizing @code{inferior-octave-prompt-read-only} the prompt can
 395 be changed to be read only.  The default value is the same as
 396 @code{comint-prompt-read-only}.
 397
 398 @vindex inferior-octave-mode-hook
 399 And finally, @code{inferior-octave-mode-hook} is run after starting
 400 the process and putting its buffer into Inferior Octave mode.  Hence,
 401 if you like the up and down arrow keys to behave in the interaction
 402 buffer as in the shell, and you want this buffer to use nice colors,
 403 add
 404 @lisp
 405 (add-hook 'inferior-octave-mode-hook
 406           (lambda ()
 407             (define-key inferior-octave-mode-map [up]
 408               'comint-previous-input)
 409             (define-key inferior-octave-mode-map [down]
 410               'comint-next-input)))
 411 @end lisp
 412 @noindent
 413 to your @file{.emacs} or @file{init.el} file.  You could also swap the
 414 roles of @kbd{C-a} (@code{beginning-of-line}) and @code{C-c C-a}
 415 (@code{comint-bol}) using this hook.
 416
 417 @vindex inferior-octave-prompt
 418 @quotation
 419 @strong{Note} that if you set your Octave prompts to something different
 420 from the defaults, make sure that @code{inferior-octave-prompt} matches
 421 them.  Otherwise, @emph{nothing} will work, because Emacs will not know
 422 when Octave is waiting for input, or done sending output.
 423 @end quotation
 424
 425 @node GNU Free Documentation License
 426 @chapter GNU Free Documentation License
 427 @include doclicense.texi
 428
 429 @node Key Index
 430 @unnumbered Key Index
 431
 432 @printindex ky
 433
 434 @node Variable Index
 435 @unnumbered Variable Index
 436
 437 @printindex vr
 438
 439 @node Lisp Function Index
 440 @unnumbered Function Index
 441
 442 @printindex fn
 443
 444 @node Concept Index
 445 @unnumbered Concept Index
 446
 447 @printindex cp
 448
 449
 450 @bye
 451
 452 @c TODO Update
 453
 454 @c @node Using the Emacs Info Reader for Octave
 455 @c @chapter Using the Emacs Info Reader for Octave
 456
 457 @c You may also use the Emacs Info reader with Octave's @code{doc} function.
 458
 459 @c If @file{gnuserv} is installed, add the lines
 460 @c @lisp
 461 @c (autoload 'octave-help "octave-hlp" nil t)
 462 @c (require 'gnuserv)
 463 @c (gnuserv-start)
 464 @c @end lisp
 465 @c @noindent
 466 @c to your @file{.emacs} file.
 467
 468 @c You can use either `plain' Emacs Info or the function @code{octave-help}
 469 @c as your Octave info reader (for @samp{help -i}).  In the former case,
 470 @c use @code{info_program ("info-emacs-info")}.
 471 @c The latter is perhaps more attractive because it allows to look up keys
 472 @c in the indices of @emph{several} info files related to Octave (provided
 473 @c that the Emacs variable @code{octave-help-files} is set correctly).  In
 474 @c this case, use @code{info_program ("info-emacs-octave-help")}.
 475
 476 @c If you use Octave from within Emacs, it is best to add these settings to
 477 @c your @file{~/.emacs-octave} startup file (or the file pointed to by the
 478 @c Emacs variable @code{inferior-octave-startup-file}).