code.delx.au - gnu-emacs/blob - 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 @c FIXME: `electric-indent-mode' is enabled by default in GNU Emacs 24.4.
 152 A common problem is that the @key{RET} key does @emph{not} indent the
 153 line to where the new text should go after inserting the newline.  This
 154 is because the standard Emacs convention is that @key{RET} (aka
 155 @kbd{C-m}) just adds a newline, whereas @key{LFD} (aka @kbd{C-j}) adds a
 156 newline and indents it.  This is particularly inconvenient for users with
 157 keyboards which do not have a special @key{LFD} key at all; in such
 158 cases, it is typically more convenient to use @key{RET} as the @key{LFD}
 159 key (rather than typing @kbd{C-j}).
 160
 161 You can make @key{RET} do this by adding
 162 @lisp
 163 (define-key octave-mode-map "\C-m"
 164   'octave-reindent-then-newline-and-indent)
 165 @end lisp
 166 @noindent
 167 to one of your Emacs startup files.  Another, more generally applicable
 168 solution is
 169 @lisp
 170 (defun RET-behaves-as-LFD ()
 171   (let ((x (key-binding "\C-j")))
 172     (local-set-key "\C-m" x)))
 173 (add-hook 'octave-mode-hook 'RET-behaves-as-LFD)
 174 @end lisp
 175 @noindent
 176 (this works for all modes by adding to the startup hooks, without
 177 having to know the particular binding of @key{RET} in that mode!).
 178 Similar considerations apply for using @key{M-RET} as @key{M-LFD}.  As
 179 @email{bwarsaw@@cnri.reston.va.us, Barry A. Warsaw} says in the
 180 documentation for his @code{cc-mode}, ``This is a very common
 181 question.  @code{:-)} If you want this to be the default behavior,
 182 don't lobby me, lobby RMS!''
 183
 184 The following variables can be used to customize Octave mode.
 185
 186 @vtable @code
 187 @item octave-blink-matching-block
 188 Non-@code{nil} means show matching begin of block when inserting a space,
 189 newline or @samp{;} after an else or end keyword.  Default is @code{t}.
 190 This is an extremely useful feature for automatically verifying that the
 191 keywords match---if they don't, an error message is displayed.
 192
 193 @item octave-block-offset
 194 Extra indentation applied to statements in block structures.
 195 Default is 2.
 196
 197 @item octave-continuation-offset
 198 Extra indentation applied to Octave continuation lines.
 199 Default is 4.
 200
 201 @item octave-font-lock-texinfo-comment
 202 Highlight texinfo comment blocks.  The default value is @code{t}.
 203 @end vtable
 204
 205 If Font Lock mode is enabled, Octave mode will display
 206
 207 @itemize @bullet
 208 @item
 209 strings in @code{font-lock-string-face}
 210
 211 @item
 212 comments in @code{font-lock-comment-face}
 213
 214 @item
 215 the Octave reserved words (such as all block keywords) and the text
 216 functions (such as @samp{cd} or @samp{who}) which are also reserved
 217 using @code{font-lock-keyword-face}
 218
 219 @item
 220 the built-in operators (@samp{&&}, @samp{==}, @dots{}) using
 221 @code{font-lock-reference-face}
 222
 223 @item
 224 and the function names in function declarations in
 225 @code{font-lock-function-name-face}.
 226
 227 @item
 228 Function comments blocks in @code{octave-function-comment-block}
 229 @end itemize
 230
 231 @cindex Imenu Support
 232 There is also rudimentary support for Imenu (@pxref{Imenu,,, emacs,
 233 The GNU Emacs Manual}).  Currently, function names can be indexed.
 234
 235 @cindex ElDoc Mode Support
 236 @vindex octave-eldoc-message-style
 237 ElDoc mode (@pxref{Lisp Doc,,, emacs, The GNU Emacs Manual}) is
 238 supported.  By customizing @code{octave-eldoc-message-style} it can be
 239 changed from displaying one or multi line hints.
 240
 241 @c @cindex TAGS
 242 @c @cindex Emacs TAGS files
 243 @c @cindex @file{octave-tags}
 244 @c You can generate TAGS files for Emacs from Octave @file{.m} files using
 245 @c the shell script @file{octave-tags} that is installed alongside your copy of
 246 @c Octave.
 247 @c
 248 @vindex octave-mode-hook
 249 Customization of Octave mode can be performed by modification of the
 250 variable @code{octave-mode-hook}.
 251
 252 @node Running Octave from Within Emacs
 253 @chapter Running Octave from Within Emacs
 254 @cindex Inferior Octave Mode
 255
 256 Octave mode provides commands for running an inferior
 257 Octave process in a special Emacs buffer.  Use
 258 @lisp
 259 M-x run-octave
 260 @end lisp
 261 @noindent
 262 to directly start an inferior Octave process.
 263
 264 @vindex inferior-octave-buffer
 265 This will start Octave in a special buffer the name of which is
 266 specified by the variable @code{inferior-octave-buffer} and defaults
 267 to @file{*Inferior Octave*}.  From within this buffer, you can
 268 interact with the inferior Octave process `as usual', i.e., by
 269 entering Octave commands at the prompt.  The buffer is in Inferior
 270 Octave mode, which is derived from the standard Comint mode, a major
 271 mode for interacting with an inferior interpreter.  See the
 272 documentation for @code{comint-mode} for more details, and use
 273 @kbd{C-h b} to find out about available special keybindings.
 274
 275 You can also communicate with an inferior Octave process from within
 276 files with Octave code (i.e., buffers in Octave mode), using the
 277 following commands.
 278
 279 @table @kbd
 280 @item C-c C-i l
 281 @kindex C-c C-i l
 282 @findex octave-send-line
 283 @vindex octave-send-line-auto-forward
 284 Send the current line to the inferior Octave process
 285 (@code{octave-send-line}).  With positive prefix argument @var{n},
 286 send that many lines.  If @code{octave-send-line-auto-forward} is
 287 non-@code{nil}, go to the next unsent code line.
 288
 289 @item C-c C-i b
 290 @kindex C-c C-i b
 291 @findex octave-send-block
 292 Send the current block to the inferior Octave process
 293 (@code{octave-send-block}).
 294
 295 @item C-c C-i f
 296 @kindex C-c C-i f
 297 @findex octave-send-defun
 298 Send the current function to the inferior Octave process
 299 (@code{octave-send-defun}).
 300
 301 @item C-c C-i r
 302 @kindex C-c C-i r
 303 @findex octave-send-region
 304 Send the region to the inferior Octave process
 305 (@code{octave-send-region}).
 306
 307 @item C-c C-i a
 308 @kindex C-c C-i a
 309 @findex octave-send-buffer
 310 Send the entire buffer to the inferior Octave process
 311 (@code{octave-send-buffer}).  If the buffer is associated with a file
 312 then sourcing the buffer by using @kbd{C-c C-l}
 313 (@code{octave-source-file}) should be preferred.
 314
 315 @item C-c C-i s
 316 @kindex C-c C-i s
 317 @findex octave-show-process-buffer
 318 Make sure that `inferior-octave-buffer' is displayed
 319 (@code{octave-show-process-buffer}).
 320
 321 @item C-c C-i q
 322 @kindex C-c C-i q
 323 @findex octave-hide-process-buffer
 324 Delete all windows that display the inferior Octave buffer
 325 (@code{octave-hide-process-buffer}).
 326
 327 @item C-c C-i k
 328 @kindex C-c C-i k
 329 @findex octave-kill-process
 330 Kill the inferior Octave process and its buffer
 331 (@code{octave-kill-process}).
 332
 333 @item C-c C-l
 334 @kindex C-c C-l
 335 @findex octave-source-file
 336 Parse and execute the current file in the inferior Octave buffer
 337 (@code{octave-source-file}).  This is done using Octave's
 338 @code{source} function.
 339
 340 @item M-.
 341 @kindex M-.
 342 @findex octave-find-definition
 343 @vindex octave-source-directories
 344 Find the definition of a function or variable.  Functions implemented
 345 in C++ can be found if variable @code{octave-source-directories} is
 346 set correctly (@code{octave-find-definition}).
 347
 348 @item C-h d
 349 @kindex C-h d
 350 @findex octave-help
 351 @vindex octave-help-buffer
 352 Display the documentation for function (@code{octave-help}).  The
 353 buffer name can be changed by customizing @code{octave-help-buffer}.
 354
 355 @item C-h a
 356 @kindex C-h a
 357 @findex octave-lookfor
 358 Search for a given string in all the first sentence of function help
 359 strings (@code{octave-lookfor}).  With a @code{universal-argument} the
 360 entire help string is searched.
 361
 362 @end table
 363
 364 The effect of the commands which send code to the Octave process can be
 365 customized by the following variables.
 366
 367 @vtable @code
 368 @item octave-send-echo-input
 369 Non-@code{nil} means echo input sent to the inferior Octave process.
 370 Default is @code{t}.
 371
 372 @item octave-send-show-buffer
 373 Non-@code{nil} means display the buffer running the Octave process after
 374 sending a command (but without selecting it).
 375 Default is @code{t}.
 376 @end vtable
 377
 378 If you send code and there is no inferior Octave process yet, it will
 379 be started automatically.
 380
 381 @vindex inferior-octave-startup-args
 382 The startup of the inferior Octave process is highly customizable.
 383 The variable @code{inferior-octave-startup-args} can be used for
 384 specifying command lines arguments to be passed to Octave on startup
 385 as a list of strings.  For example, to suppress the startup message
 386 and use `traditional' mode, set this to @code{("-q" "--traditional")}.
 387 You can also specify a startup file of Octave commands to be loaded on
 388 startup; note that these commands will not produce any visible output
 389 in the process buffer.  Which file to use is controlled by the
 390 variable @code{inferior-octave-startup-file}.  The default is
 391 @file{~/.emacs-octave} or if this file is not found
 392 @file{~/.emacs.d/init_octave.m}.
 393
 394 @vindex inferior-octave-prompt-read-only
 395 By customizing @code{inferior-octave-prompt-read-only} the prompt can
 396 be changed to be read only.  The default value is the same as
 397 @code{comint-prompt-read-only}.
 398
 399 @vindex inferior-octave-mode-hook
 400 And finally, @code{inferior-octave-mode-hook} is run after starting
 401 the process and putting its buffer into Inferior Octave mode.  Hence,
 402 if you like the up and down arrow keys to behave in the interaction
 403 buffer as in the shell, and you want this buffer to use nice colors,
 404 add
 405 @lisp
 406 (add-hook 'inferior-octave-mode-hook
 407           (lambda ()
 408             (define-key inferior-octave-mode-map [up]
 409               'comint-previous-input)
 410             (define-key inferior-octave-mode-map [down]
 411               'comint-next-input)))
 412 @end lisp
 413 @noindent
 414 to your @file{.emacs} or @file{init.el} file.  You could also swap the
 415 roles of @kbd{C-a} (@code{beginning-of-line}) and @code{C-c C-a}
 416 (@code{comint-bol}) using this hook.
 417
 418 @vindex inferior-octave-prompt
 419 @quotation
 420 @strong{Note} that if you set your Octave prompts to something different
 421 from the defaults, make sure that @code{inferior-octave-prompt} matches
 422 them.  Otherwise, @emph{nothing} will work, because Emacs will not know
 423 when Octave is waiting for input, or done sending output.
 424 @end quotation
 425
 426 @node GNU Free Documentation License
 427 @chapter GNU Free Documentation License
 428 @include doclicense.texi
 429
 430 @node Key Index
 431 @unnumbered Key Index
 432
 433 @printindex ky
 434
 435 @node Variable Index
 436 @unnumbered Variable Index
 437
 438 @printindex vr
 439
 440 @node Lisp Function Index
 441 @unnumbered Function Index
 442
 443 @printindex fn
 444
 445 @node Concept Index
 446 @unnumbered Concept Index
 447
 448 @printindex cp
 449
 450
 451 @bye
 452
 453 @c TODO Update
 454
 455 @c @node Using the Emacs Info Reader for Octave
 456 @c @chapter Using the Emacs Info Reader for Octave
 457
 458 @c You may also use the Emacs Info reader with Octave's @code{doc} function.
 459
 460 @c If @file{gnuserv} is installed, add the lines
 461 @c @lisp
 462 @c (autoload 'octave-help "octave-hlp" nil t)
 463 @c (require 'gnuserv)
 464 @c (gnuserv-start)
 465 @c @end lisp
 466 @c @noindent
 467 @c to your @file{.emacs} file.
 468
 469 @c You can use either `plain' Emacs Info or the function @code{octave-help}
 470 @c as your Octave info reader (for @samp{help -i}).  In the former case,
 471 @c use @code{info_program ("info-emacs-info")}.
 472 @c The latter is perhaps more attractive because it allows to look up keys
 473 @c in the indices of @emph{several} info files related to Octave (provided
 474 @c that the Emacs variable @code{octave-help-files} is set correctly).  In
 475 @c this case, use @code{info_program ("info-emacs-octave-help")}.
 476
 477 @c If you use Octave from within Emacs, it is best to add these settings to
 478 @c your @file{~/.emacs-octave} startup file (or the file pointed to by the
 479 @c Emacs variable @code{inferior-octave-startup-file}).