1@c Copyright (C) 1996-2019 John W. Eaton 2@c 3@c This file is part of Octave. 4@c 5@c Octave is free software: you can redistribute it and/or modify it 6@c under the terms of the GNU General Public License as published by 7@c the Free Software Foundation, either version 3 of the License, or 8@c (at your option) any later version. 9@c 10@c Octave is distributed in the hope that it will be useful, but 11@c WITHOUT ANY WARRANTY; without even the implied warranty of 12@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13@c GNU General Public License for more details. 14@c 15@c You should have received a copy of the GNU General Public License 16@c along with Octave; see the file COPYING. If not, see 17@c <https://www.gnu.org/licenses/>. 18 19@node Getting Started 20@chapter Getting Started 21 22This chapter explains some of Octave's basic features, including how to 23start an Octave session, get help at the command prompt, edit the 24command line, and write Octave programs that can be executed as commands 25from your shell. 26 27@menu 28* Invoking Octave from the Command Line:: 29* Quitting Octave:: 30* Getting Help:: 31* Command Line Editing:: 32* Errors:: 33* Executable Octave Programs:: 34* Comments:: 35@end menu 36 37@node Invoking Octave from the Command Line 38@section Invoking Octave from the Command Line 39 40Normally, Octave is used interactively by running the program 41@samp{octave} without any arguments. Once started, Octave reads 42commands from the terminal until you tell it to exit. 43 44You can also specify the name of a file on the command line, and Octave 45will read and execute the commands from the named file and then exit 46when it is finished. 47 48You can further control how Octave starts by using the command-line 49options described in the next section, and Octave itself can remind you 50of the options available. Type @samp{octave --help} to display all 51available options and briefly describe their use (@samp{octave -h} is a 52shorter equivalent). 53 54@menu 55* Command Line Options:: 56* Startup Files:: 57@end menu 58 59@node Command Line Options 60@subsection Command Line Options 61@cindex Octave command options 62@cindex command options 63@cindex options, Octave command 64 65Here is a complete list of the command line options that Octave 66accepts. 67 68 69@table @code 70 71@item --built-in-docstrings-file @var{filename} 72@cindex @sortas{options, Octave command --built-in-docstrings-file} @ @ @code{--built-in-docstrings-file @var{filename}} 73Specify the name of the file containing documentation strings for the 74built-in functions of Octave. This value is normally correct and should 75only need to specified in extraordinary situations. 76 77@item --debug 78@itemx -d 79@cindex @sortas{options, Octave command --debug} @ @ @code{--debug} 80@cindex @sortas{options, Octave command -d} @ @ @code{-d} 81Enter parser debugging mode. Using this option will cause Octave's 82parser to print a lot of information about the commands it reads, and is 83probably only useful if you are actually trying to debug the parser. 84 85@item --debug-jit 86@cindex @sortas{options, Octave command --debug-jit} @ @ @code{--debug-jit} 87Enable JIT compiler debugging and tracing. 88 89@item --doc-cache-file @var{filename} 90@cindex @sortas{options, Octave command --doc-cache-file} @ @ @code{--doc-cache-file @var{filename}} 91Specify the name of the doc cache file to use. The value of @var{filename} 92specified on the command line will override any value of 93@w{@env{OCTAVE_DOC_CACHE_FILE}} found in the environment, but not any commands 94in the system or user startup files that use the @code{doc_cache_file} 95function. 96 97@item --echo-commands 98@itemx -x 99@cindex @sortas{options, Octave command --echo-commands} @ @ @code{--echo-commands} 100@cindex @sortas{options, Octave command -x} @ @ @code{-x} 101Echo commands as they are executed. 102 103@item --eval @var{code} 104@cindex @sortas{options, Octave command --eval} @ @ @code{--eval @var{code}} 105Evaluate @var{code} and exit when finished unless @option{--persist} is also 106specified. 107 108@item --exec-path @var{path} 109@cindex @sortas{options, Octave command --exec-path} @ @ @code{--exec-path @var{path}} 110Specify the path to search for programs to run. The value of @var{path} 111specified on the command line will override any value of 112@w{@env{OCTAVE_EXEC_PATH}} found in the environment, but not any commands 113in the system or user startup files that call the 114@w{@env{EXEC_PATH}} function. 115 116@item --gui 117@cindex @sortas{options, Octave command --gui} @ @ @code{--gui} 118Start the graphical user interface (GUI). 119 120@item --help 121@itemx -h 122@cindex @sortas{options, Octave command --help} @ @ @code{--help} 123@cindex @sortas{options, Octave command -h} @ @ @code{-h} 124Print short help message and exit. 125 126@item --image-path @var{path} 127@cindex @sortas{options, Octave command --image-path} @ @ @code{--image-path @var{path}} 128Add path to the head of the search path for images. The value of 129@var{path} specified on the command line will override any value of 130@w{@env{OCTAVE_IMAGE_PATH}} found in the environment, but not any commands 131in the system or user startup files that call the @w{@env{IMAGE_PATH}} 132function. 133 134@item --info-file @var{filename} 135@cindex @sortas{options, Octave command --info-file} @ @ @code{--info-file @var{filename}} 136Specify the name of the info file to use. The value of @var{filename} 137specified on the command line will override any value of 138@w{@env{OCTAVE_INFO_FILE}} found in the environment, but not any commands 139in the system or user startup files that use the @code{info_file} 140function. 141 142@item --info-program @var{program} 143@cindex @sortas{options, Octave command --info-program} @ @ @code{--info-program @var{program}} 144Specify the name of the info program to use. The value of @var{program} 145specified on the command line will override any value of 146@w{@env{OCTAVE_INFO_PROGRAM}} found in the environment, but not any 147commands in the system or user startup files that use the 148@code{info_program} function. 149 150@item --interactive 151@itemx -i 152@cindex @sortas{options, Octave command --interactive} @ @ @code{--interactive} 153@cindex @sortas{options, Octave command -i} @ @ @code{-i} 154Force interactive behavior. This can be useful for running Octave via a 155remote shell command or inside an Emacs shell buffer. 156 157@item --jit-compiler 158@cindex @sortas{options, Octave command --jit-compiler} @ @ @code{--jit-compiler} 159Enable the JIT compiler used for accelerating loops. 160 161@item --line-editing 162@cindex @sortas{options, Octave command --line-editing} @ @ @code{--line-editing} 163Force readline use for command-line editing. 164 165@item --no-gui 166@cindex @sortas{options, Octave command --no-gui} @ @ @code{--no-gui} 167Disable the graphical user interface (GUI) and use the command line 168interface (CLI) instead. This is the default behavior, but this option 169may be useful to override a previous @option{--gui}. 170 171@item --no-history 172@itemx -H 173@cindex @sortas{options, Octave command --no-history} @ @ @code{--no-history} 174@cindex @sortas{options, Octave command -H} @ @ @code{-H} 175Disable recording of command-line history. 176 177@item --no-init-file 178@cindex @sortas{options, Octave command --no-init-file} @ @ @code{--no-init-file} 179@cindex @sortas{octaverc ~/.octaverc} @code{~/.octaverc} 180@cindex @sortas{octaverc .octaverc} @code{.octaverc} 181Don't read the initialization files @file{~/.octaverc} and @file{.octaverc}. 182 183@item --no-init-path 184@cindex @sortas{options, Octave command --no-init-path} @ @ @code{--no-init-path} 185Don't initialize the search path for function files to include default 186locations. 187 188@item --no-line-editing 189@cindex @sortas{options, Octave command --no-line-editing} @ @ @code{--no-line-editing} 190Disable command-line editing. 191 192@item --no-site-file 193@cindex @sortas{options, Octave command --no-site-file} @ @ @code{--no-site-file} 194@cindex site startup file 195Don't read the site-wide @file{octaverc} initialization files. 196 197@item --no-window-system 198@itemx -W 199@cindex @sortas{options, Octave command --no-window-system} @ @ @code{--no-window-system} 200@cindex @sortas{options, Octave command -W} @ @ @code{-W} 201Disable use of a windowing system including graphics. This forces a 202strictly terminal-only environment. 203 204@item --norc 205@itemx -f 206@cindex @sortas{options, Octave command --norc} @ @ @code{--norc} 207@cindex @sortas{options, Octave command -f} @ @ @code{-f} 208Don't read any of the system or user initialization files at startup. 209This is equivalent to using both of the options @option{--no-init-file} 210and @option{--no-site-file}. 211 212@item --path @var{path} 213@itemx -p @var{path} 214@cindex @sortas{options, Octave command --path} @ @ @code{--path @var{path}} 215@cindex @sortas{options, Octave command -p} @ @ @code{-p @var{path}} 216Add path to the head of the search path for function files. The 217value of @var{path} specified on the command line will override any value 218of @w{@env{OCTAVE_PATH}} found in the environment, but not any commands in the 219system or user startup files that set the internal load path through one 220of the path functions. 221 222@item --persist 223@cindex @sortas{options, Octave command --persist} @ @ @code{--persist} 224Go to interactive mode after @option{--eval} or reading from a file 225named on the command line. 226 227@item --silent 228@itemx --quiet 229@itemx -q 230@cindex @sortas{options, Octave command --silent} @ @ @code{--silent} 231@cindex @sortas{options, Octave command --quiet} @ @ @code{--quiet} 232@cindex @sortas{options, Octave command -q} @ @ @code{-q} 233Don't print the usual greeting and version message at startup. 234 235@item --texi-macros-file @var{filename} 236@cindex @sortas{options, Octave command --texi-macros-file} @ @ @code{--texi-macros-file @var{filename}} 237Specify the name of the file containing Texinfo macros for use by makeinfo. 238 239@item --traditional 240@itemx --braindead 241@cindex @sortas{options, Octave command --traditional} @ @ @code{--traditional} 242@cindex @sortas{options, Octave command --braindead} @ @ @code{--braindead} 243For compatibility with @sc{matlab}, set initial values for 244user preferences to the following values 245 246@example 247@group 248PS1 = ">> " 249PS2 = "" 250beep_on_error = true 251confirm_recursive_rmdir = false 252crash_dumps_octave_core = false 253disable_diagonal_matrix = true 254disable_permutation_matrix = true 255disable_range = true 256fixed_point_format = true 257history_timestamp_format_string = "%%-- %D %I:%M %p --%%" 258print_empty_dimensions = false 259save_default_options = "-mat-binary" 260struct_levels_to_print = 0 261@end group 262@end example 263 264@noindent 265and disable the following warnings 266 267@example 268@group 269Octave:abbreviated-property-match 270Octave:colon-nonscalar-argument 271Octave:data-file-in-path 272Octave:function-name-clash 273Octave:possible-matlab-short-circuit-operator 274@end group 275@end example 276 277@noindent 278Note that this does not enable the @code{Octave:language-extension} 279warning, which you might want if you want to be told about writing code 280that works in Octave but not @sc{matlab} (@pxref{XREFwarning,,warning}, 281@ref{XREFwarning_ids,,warning_ids}). 282 283@item --verbose 284@itemx -V 285@cindex @sortas{options, Octave command --verbose} @ @ @code{--verbose} 286@cindex @sortas{options, Octave command -V} @ @ @code{-V} 287Turn on verbose output. 288 289@item --version 290@itemx -v 291@cindex @sortas{options, Octave command --version} @ @ @code{--version} 292@cindex @sortas{options, Octave command -v} @ @ @code{-v} 293Print the program version number and exit. 294 295@item @var{file} 296Execute commands from @var{file}. Exit when done unless 297@option{--persist} is also specified. 298@end table 299 300Octave also includes several functions which return information 301about the command line, including the number of arguments and all of the 302options. 303 304@DOCSTRING(argv) 305 306@DOCSTRING(program_name) 307 308@DOCSTRING(program_invocation_name) 309 310Here is an example of using these functions to reproduce the command 311line which invoked Octave. 312 313@example 314@group 315printf ("%s", program_name ()); 316arg_list = argv (); 317for i = 1:nargin 318 printf (" %s", arg_list@{i@}); 319endfor 320printf ("\n"); 321@end group 322@end example 323 324@noindent 325@xref{Indexing Cell Arrays}, for an explanation of how to retrieve objects 326from cell arrays, and @ref{Defining Functions}, for information about the 327variable @code{nargin}. 328 329@node Startup Files 330@subsection Startup Files 331@cindex initialization 332@cindex startup 333 334When Octave starts, it looks for commands to execute from the files in 335the following list. These files may contain any valid Octave commands, 336including function definitions. 337 338@cindex startup files 339 340@table @code 341@item @var{octave-home}/share/octave/site/m/startup/octaverc 342@cindex site startup file 343where @code{@var{octave-home}} is the directory in which Octave is installed 344(the default is @file{/usr/local}). 345This file is provided so that changes to the default Octave environment 346can be made globally for all users at your site for all versions of Octave 347you have installed. Care should be taken when making changes to this file 348since all users of Octave at your site will be affected. The default file 349may be overridden by the environment variable @w{@env{OCTAVE_SITE_INITFILE}}. 350 351@item @var{octave-home}/share/octave/@var{version}/m/startup/octaverc 352@cindex version startup file 353where @code{@var{octave-home}} is the directory in which Octave is installed 354(the default is @file{/usr/local}), and @code{@var{version}} is the version 355number of Octave. This file is provided so that changes to the default 356Octave environment can be made globally for all users of a particular version 357of Octave. Care should be taken when making changes to this file since all 358users of Octave at your site will be affected. The default file may be 359overridden by the environment variable @w{@env{OCTAVE_VERSION_INITFILE}}. 360 361@item @var{config-dir}/octave/octaverc 362@cindex personal startup file 363where @code{@var{config-dir}} is the platform-dependent location for user 364local configuration files (e.g., @w{@env{$XDG_CONFIG_HOME}} on many Unix-like 365operating systems or @w{@env{%APPDATA%}} on Windows). 366 367@item ~/.octaverc 368@cindex personal startup file 369@cindex @sortas{octaverc ~/.octaverc} @code{~/.octaverc} 370This file is used to make personal changes to the default Octave environment. 371 372@item .octaverc 373@cindex project startup file 374@cindex @sortas{octaverc .octaverc} @code{.octaverc} 375This file can be used to make changes to the default Octave environment for a 376particular project. Octave searches for this file in the current directory 377after it reads @file{~/.octaverc}. Any use of the @code{cd} command in the 378@file{~/.octaverc} file will affect the directory where Octave searches for 379@file{.octaverc}. 380 381If you start Octave in your home directory, commands from the file 382@file{~/.octaverc} will only be executed once. 383 384@item startup.m 385@cindex @code{startup.m} 386This file is used to make personal changes to the default Octave environment. 387It is executed for @sc{matlab} compatibility, but @file{~/.octaverc} is the 388preferred location for configuration changes. 389@end table 390 391A message will be displayed as each of the startup files is read if you 392invoke Octave with the @option{--verbose} option but without the 393@option{--silent} option. 394 395The startup files are always processed in the system's locale charset 396(independent of the m-file encoding that is set, for example, in the GUI 397properties). In other words, the system's locale charset is in effect until a 398user manually sets the m-file encoding (e.g., in one of the startup files) and 399triggers re-parsing of any relevant m-files. Octave can be forced to use a 400new encoding with the undocumented function @code{__mfile_encoding__}: 401 402@example 403@group 404__mfile_encoding__ ("utf-8"); # set new encoding 405clear ("functions"); # re-parse all .m files in the new encoding 406@end group 407@end example 408 409This changes the encoding that is used to interpret all subsequently run 410startup and m-files (not including the currently executing file). 411 412@node Quitting Octave 413@section Quitting Octave 414@cindex exiting octave 415@cindex quitting octave 416@cindex finish.m 417@cindex site exiting file 418 419Shutdown is initiated with the @code{exit} or @code{quit} commands (they are 420equivalent). Similar to startup, Octave has a shutdown process that can be 421customized by user script files. During shutdown Octave will search for the 422script file @file{finish.m} in the function load path. Commands to save all 423workspace variables or cleanup temporary files may be placed there. Additional 424functions to execute on shutdown may be registered with @code{atexit}. 425 426@DOCSTRING(quit) 427 428@DOCSTRING(atexit) 429 430@node Getting Help 431@section Commands for Getting Help 432@cindex online help 433@cindex help, online 434 435The entire text of this manual is available from the Octave prompt 436via the command @kbd{doc}. In addition, the documentation for 437individual user-written functions and variables is also available via 438the @kbd{help} command. This section describes the commands used for 439reading the manual and the documentation strings for user-supplied 440functions and variables. @xref{Function Files}, for more information 441about how to document the functions you write. 442 443@DOCSTRING(help) 444 445@DOCSTRING(doc) 446 447@DOCSTRING(lookfor) 448 449To see what is new in the current release of Octave, use the @code{news} 450function. 451 452@DOCSTRING(news) 453 454@DOCSTRING(info) 455 456@DOCSTRING(warranty) 457 458The following functions can be used to change which programs are used 459for displaying the documentation, and where the documentation can be 460found. 461 462@DOCSTRING(info_file) 463 464@DOCSTRING(info_program) 465 466@DOCSTRING(makeinfo_program) 467 468@DOCSTRING(texi_macros_file) 469 470@DOCSTRING(doc_cache_file) 471 472@DOCSTRING(built_in_docstrings_file) 473 474@DOCSTRING(suppress_verbose_help_message) 475 476The following functions are principally used internally by Octave for 477generating the documentation. They are documented here for completeness 478and because they may occasionally be useful for users. 479 480@DOCSTRING(doc_cache_create) 481 482@DOCSTRING(get_help_text) 483 484@DOCSTRING(get_help_text_from_file) 485 486@DOCSTRING(get_first_help_sentence) 487 488@node Command Line Editing 489@section Command Line Editing 490@cindex command-line editing 491@cindex editing the command line 492 493Octave uses the GNU Readline library to provide an extensive set of 494command-line editing and history features. Only the most common 495features are described in this manual. In addition, all of the editing 496functions can be bound to different key strokes at the user's discretion. 497This manual assumes no changes from the default Emacs bindings. See the GNU 498Readline Library manual for more information on customizing Readline and 499for a complete feature list. 500 501To insert printing characters (letters, digits, symbols, etc.), simply 502type the character. Octave will insert the character at the cursor and 503advance the cursor forward. 504 505Many of the command-line editing functions operate using control 506characters. For example, the character @kbd{Control-a} moves the cursor 507to the beginning of the line. To type @kbd{C-a}, hold down @key{CTRL} 508and then press @key{a}. In the following sections, control characters 509such as @kbd{Control-a} are written as @kbd{C-a}. 510 511Another set of command-line editing functions use Meta characters. To 512type @kbd{M-u}, hold down the @key{META} key and press @key{u}. Depending 513on the keyboard, the @key{META} key may be labeled @key{ALT} or 514even @key{WINDOWS}. If your terminal does not have a @key{META} key, you 515can still type Meta characters using two-character sequences starting 516with @kbd{ESC}. Thus, to enter @kbd{M-u}, you would type 517@key{ESC} @key{u}. The @kbd{ESC} character sequences are also allowed on 518terminals with real Meta keys. In the following sections, Meta 519characters such as @kbd{Meta-u} are written as @kbd{M-u}. 520 521 522@menu 523* Cursor Motion:: 524* Killing and Yanking:: 525* Commands for Text:: 526* Commands for Completion:: 527* Commands for History:: 528* Customizing readline:: 529* Customizing the Prompt:: 530* Diary and Echo Commands:: 531@end menu 532 533@node Cursor Motion 534@subsection Cursor Motion 535 536The following commands allow you to position the cursor. 537 538@table @kbd 539@item C-b 540Move back one character. 541 542@item C-f 543Move forward one character. 544 545@item @key{BACKSPACE} 546Delete the character to the left of the cursor. 547 548@item @key{DEL} 549Delete the character underneath the cursor. 550 551@item C-d 552Delete the character underneath the cursor. 553 554@item M-f 555Move forward a word. 556 557@item M-b 558Move backward a word. 559 560@item C-a 561Move to the start of the line. 562 563@item C-e 564Move to the end of the line. 565 566@item C-l 567Clear the screen, reprinting the current line at the top. 568 569@item C-_ 570@itemx C-/ 571Undo the last action. You can undo all the way back to an empty line. 572 573@item M-r 574Undo all changes made to this line. This is like typing the `undo' 575command enough times to get back to the beginning. 576@end table 577 578The above table describes the most basic possible keystrokes that you need 579in order to do editing of the input line. On most terminals, you can 580also use the left and right arrow keys in place of @kbd{C-f} and @kbd{C-b} 581to move forward and backward. 582 583Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves 584forward a word. It is a loose convention that control keystrokes 585operate on characters while meta keystrokes operate on words. 586 587@cindex clearing the screen 588 589The function @code{clc} will allow you to clear the screen from within 590Octave programs. 591 592@DOCSTRING(clc) 593 594@node Killing and Yanking 595@subsection Killing and Yanking 596 597@dfn{Killing} text means to delete the text from the line, but to save 598it away for later use, usually by @dfn{yanking} it back into the line. 599If the description for a command says that it `kills' text, then you can 600be sure that you can get the text back in a different (or the same) 601place later. 602 603Here is the list of commands for killing text. 604 605@table @kbd 606@item C-k 607Kill the text from the current cursor position to the end of the line. 608 609@item M-d 610Kill from the cursor to the end of the current word, or if between 611words, to the end of the next word. 612 613@item M-@key{DEL} 614Kill from the cursor to the start of the previous word, or if between 615words, to the start of the previous word. 616 617@item C-w 618Kill from the cursor to the previous whitespace. This is different than 619@kbd{M-@key{DEL}} because the word boundaries differ. 620@end table 621 622And, here is how to @dfn{yank} the text back into the line. Yanking 623means to copy the most-recently-killed text from the kill buffer. 624 625@table @kbd 626@item C-y 627Yank the most recently killed text back into the buffer at the cursor. 628 629@item M-y 630Rotate the kill-ring, and yank the new top. You can only do this if 631the prior command is @kbd{C-y} or @kbd{M-y}. 632@end table 633 634When you use a kill command, the text is saved in a @dfn{kill-ring}. 635Any number of consecutive kills save all of the killed text together, so 636that when you yank it back, you get it in one clean sweep. The kill 637ring is not line specific; the text that you killed on a previously 638typed line is available to be yanked back later, when you are typing 639another line. 640 641@node Commands for Text 642@subsection Commands for Changing Text 643 644The following commands can be used for entering characters that would 645otherwise have a special meaning (e.g., @key{TAB}, @kbd{C-q}, etc.), or 646for quickly correcting typing mistakes. 647 648@table @kbd 649@item C-q 650@itemx C-v 651Add the next character that you type to the line verbatim. This is 652how to insert things like @kbd{C-q} for example. 653 654@item M-@key{TAB} 655Insert a tab character. 656 657@item C-t 658Drag the character before the cursor forward over the character at the 659cursor, also moving the cursor forward. If the cursor is at the end of 660the line, then transpose the two characters before it. 661 662@item M-t 663Drag the word behind the cursor past the word in front of the cursor 664moving the cursor over that word as well. 665 666@item M-u 667Uppercase the characters following the cursor to the end of the current 668(or following) word, moving the cursor to the end of the word. 669 670@item M-l 671Lowercase the characters following the cursor to the end of the current 672(or following) word, moving the cursor to the end of the word. 673 674@item M-c 675Uppercase the character following the cursor (or the beginning of the 676next word if the cursor is between words), moving the cursor to the end 677of the word. 678@end table 679 680@node Commands for Completion 681@subsection Letting Readline Type for You 682@cindex command completion 683 684The following commands allow Octave to complete command and variable 685names for you. 686 687@table @kbd 688@item @key{TAB} 689Attempt to do completion on the text before the cursor. Octave can 690complete the names of commands and variables. 691 692@item M-? 693List the possible completions of the text before the cursor. 694@end table 695 696@DOCSTRING(completion_append_char) 697 698@DOCSTRING(completion_matches) 699 700@node Commands for History 701@subsection Commands for Manipulating the History 702@cindex command history 703@cindex input history 704@cindex history of commands 705 706Octave normally keeps track of the commands you type so that you can 707recall previous commands to edit or execute them again. When you exit 708Octave, the most recent commands you have typed, up to the number 709specified by the variable @code{history_size}, are saved in a file. 710When Octave starts, it loads an initial list of commands from the file 711named by the variable @code{history_file}. 712 713Here are the commands for simple browsing and searching the history 714list. 715 716@table @kbd 717@item @key{LFD} 718@itemx @key{RET} 719Accept the current line regardless of where the cursor is. If the line is 720non-empty, add it to the history list. If the line was a history 721line, then restore the history line to its original state. 722 723@item C-p 724Move `up' through the history list. 725 726@item C-n 727Move `down' through the history list. 728 729@item M-< 730Move to the first line in the history. 731 732@item M-> 733Move to the end of the input history, i.e., the line you are entering! 734 735@item C-r 736Search backward starting at the current line and moving `up' through 737the history as necessary. This is an incremental search. 738 739@item C-s 740Search forward starting at the current line and moving `down' through 741the history as necessary. 742@end table 743 744On most terminals, you can also use the up and down arrow keys in place 745of @kbd{C-p} and @kbd{C-n} to move through the history list. 746 747In addition to the keyboard commands for moving through the history 748list, Octave provides three functions for viewing, editing, and 749re-running chunks of commands from the history list. 750 751@DOCSTRING(history) 752 753@DOCSTRING(edit_history) 754 755@DOCSTRING(run_history) 756 757@noindent 758Octave also allows you customize the details of when, where, and how history 759is saved. 760 761@DOCSTRING(history_save) 762 763@DOCSTRING(history_control) 764 765@DOCSTRING(history_file) 766 767@DOCSTRING(history_size) 768 769@DOCSTRING(history_timestamp_format_string) 770 771@DOCSTRING(EDITOR) 772 773@node Customizing readline 774@subsection Customizing @code{readline} 775@cindex @sortas{inputrc ~/.inputrc} @code{~/.inputrc} 776@cindex customizing @code{readline} 777@cindex @code{readline} customization 778 779Octave uses the GNU Readline library for command-line editing and 780history features. Readline is very flexible and can be modified through 781a configuration file of commands (See the GNU Readline library for the 782exact command syntax). The default configuration file is normally 783@file{~/.inputrc}. 784 785Octave provides two commands for initializing Readline and thereby changing 786the command line behavior. 787 788@DOCSTRING(readline_read_init_file) 789 790@DOCSTRING(readline_re_read_init_file) 791 792@node Customizing the Prompt 793@subsection Customizing the Prompt 794@cindex prompt customization 795@cindex customizing the prompt 796 797The following variables are available for customizing the appearance of 798the command-line prompts. Octave allows the prompt to be customized by 799inserting a number of backslash-escaped special characters that are 800decoded as follows: 801 802@table @samp 803@item \t 804The time. 805 806@item \d 807The date. 808 809@item \n 810Begins a new line by printing the equivalent of a carriage return 811followed by a line feed. 812 813@item \s 814The name of the program (usually just @samp{octave}). 815 816@item \w 817The current working directory. 818 819@item \W 820The basename of the current working directory. 821 822@item \u 823The username of the current user. 824 825@item \h 826The hostname, up to the first `.'. 827 828@item \H 829The hostname. 830 831@item \# 832The command number of this command, counting from when Octave starts. 833 834@item \! 835The history number of this command. This differs from @samp{\#} by the 836number of commands in the history list when Octave starts. 837 838@item \$ 839If the effective UID is 0, a @samp{#}, otherwise a @samp{$}. 840 841@item \nnn 842The character whose character code in octal is @var{nnn}. 843 844@item \\ 845A backslash. 846@end table 847 848@DOCSTRING(PS1) 849 850@DOCSTRING(PS2) 851 852@DOCSTRING(PS4) 853 854@node Diary and Echo Commands 855@subsection Diary and Echo Commands 856@cindex diary of commands and output 857@cindex command and output logs 858@cindex logging commands and output 859@cindex echoing executing commands 860@cindex command echoing 861 862Octave's diary feature allows you to keep a log of all or part of an 863interactive session by recording the input you type and the output that 864Octave produces in a separate file. 865 866@DOCSTRING(diary) 867 868Sometimes it is useful to see the commands in a function or script as 869they are being evaluated. This can be especially helpful for debugging 870some kinds of problems. 871 872@DOCSTRING(echo) 873 874@node Errors 875@section How Octave Reports Errors 876@cindex error messages 877@cindex messages, error 878 879Octave reports two kinds of errors for invalid programs. 880 881A @dfn{parse error} occurs if Octave cannot understand something you 882have typed. For example, if you misspell a keyword, 883 884@example 885octave:13> function y = f (x) y = x***2; endfunction 886@end example 887 888@noindent 889Octave will respond immediately with a message like this: 890 891@example 892@group 893parse error: 894 895 syntax error 896 897>>> function y = f (x) y = x***2; endfunction 898 ^ 899@end group 900@end example 901 902@noindent 903For most parse errors, Octave uses a caret (@samp{^}) to mark the point 904on the line where it was unable to make sense of your input. In this 905case, Octave generated an error message because the keyword for 906exponentiation (@code{**}) was misspelled. It marked the error at the 907third @samp{*} because the code leading up to this was correct but the final 908@samp{*} was not understood. 909 910Another class of error message occurs at evaluation time. These 911errors are called @dfn{run-time errors}, or sometimes 912@dfn{evaluation errors}, because they occur when your program is being 913@dfn{run}, or @dfn{evaluated}. For example, if after correcting the 914mistake in the previous function definition, you type 915 916@example 917octave:13> f () 918@end example 919 920@noindent 921Octave will respond with 922 923@example 924@group 925error: `x' undefined near line 1 column 24 926error: called from: 927error: f at line 1, column 22 928@end group 929@end example 930 931@noindent 932This error message has several parts, and gives quite a bit of 933information to help you locate the source of the error. The messages 934are generated from the point of the innermost error, and provide a 935traceback of enclosing expressions and function calls. 936 937In the example above, the first line indicates that a variable named 938@samp{x} was found to be undefined near line 1 and column 24 of some 939function or expression. For errors occurring within functions, lines 940are counted from the beginning of the file containing the function 941definition. For errors occurring outside of an enclosing function, 942the line number indicates the input line number, which is usually displayed 943in the primary prompt string. 944 945The second and third lines of the error message indicate that the error 946occurred within the function @code{f}. If the function @code{f} had been 947called from within another function, for example, @code{g}, the list of 948errors would have ended with one more line: 949 950@example 951error: g at line 1, column 17 952@end example 953 954These lists of function calls make it fairly easy to trace the 955path your program took before the error occurred, and to correct the 956error before trying again. 957 958@node Executable Octave Programs 959@section Executable Octave Programs 960@cindex executable scripts 961@cindex scripts 962@cindex batch processing 963@cindex self contained programs 964@cindex program, self contained 965 966@opindex @code{#!} self-contained script 967Once you have learned Octave, you may want to write self-contained 968Octave scripts, using the @samp{#!} script mechanism. You can do this 969on GNU systems and on many Unix systems @footnote{The @samp{#!} 970mechanism works on Unix systems derived from Berkeley Unix, System V 971Release 4, and some System V Release 3 systems.}. 972 973Self-contained Octave scripts are useful when you want to write a 974program which users can invoke without knowing that the program is 975written in the Octave language. Octave scripts are also used for batch 976processing of data files. Once an algorithm has been developed and tested 977in the interactive portion of Octave, it can be committed to an executable 978script and used again and again on new data files. 979 980As a trivial example of an executable Octave script, you might create a 981text file named @file{hello}, containing the following lines: 982 983@example 984@group 985#! @var{octave-interpreter-name} -qf 986# a sample Octave program 987printf ("Hello, world!\n"); 988@end group 989@end example 990 991@noindent 992(where @var{octave-interpreter-name} should be replaced with the full 993path and name of your Octave binary). Note that this will only work if 994@samp{#!} appears at the very beginning of the file. After making the 995file executable (with the @code{chmod} command on Unix systems), you can 996simply type: 997 998@example 999hello 1000@end example 1001 1002@noindent 1003at the shell, and the system will arrange to run Octave as if you had 1004typed: 1005 1006@example 1007octave hello 1008@end example 1009 1010The line beginning with @samp{#!} lists the full path and filename of an 1011interpreter to be run, and an optional initial command line argument to 1012pass to that interpreter. The operating system then runs the 1013interpreter with the given argument and the full argument list of the 1014executed program. The first argument in the list is the full filename 1015of the Octave executable. The rest of the argument list will either be 1016options to Octave, or data files, or both. The @samp{-qf} options are 1017usually specified in stand-alone Octave programs to prevent them from 1018printing the normal startup message, and to keep them from behaving 1019differently depending on the contents of a particular user's 1020@file{~/.octaverc} file. @xref{Invoking Octave from the Command Line}. 1021 1022Note that some operating systems may place a limit on the number of 1023characters that are recognized after @samp{#!}. Also, the arguments 1024appearing in a @samp{#!} line are parsed differently by various 1025shells/systems. The majority of them group all the arguments together in one 1026string and pass it to the interpreter as a single argument. In this case, the 1027following script: 1028 1029@example 1030@group 1031#! @var{octave-interpreter-name} -q -f # comment 1032@end group 1033@end example 1034 1035@noindent 1036is equivalent to typing at the command line: 1037 1038@example 1039@group 1040octave "-q -f # comment" 1041@end group 1042@end example 1043 1044@noindent 1045which will produce an error message. Unfortunately, it is 1046not possible for Octave to determine whether it has been called from the 1047command line or from a @samp{#!} script, so some care is needed when using the 1048@samp{#!} mechanism. 1049 1050@menu 1051* Passing Arguments to Executable Scripts:: 1052* Dual-Purpose Executable Scripts and Octave Functions:: 1053@end menu 1054 1055@node Passing Arguments to Executable Scripts 1056@subsection Passing Arguments to Executable Scripts 1057 1058Note that when Octave is started from an executable script, the built-in 1059function @code{argv} returns a cell array containing the command line 1060arguments passed to the executable Octave script, not the arguments 1061passed to the Octave interpreter on the @samp{#!} line of the script. 1062For example, the following program will reproduce the command line that 1063was used to execute the script, not @samp{-qf}. 1064 1065@example 1066@group 1067#! /bin/octave -qf 1068printf ("%s", program_name ()); 1069arg_list = argv (); 1070for i = 1:nargin 1071 printf (" %s", arg_list@{i@}); 1072endfor 1073printf ("\n"); 1074@end group 1075@end example 1076 1077@node Dual-Purpose Executable Scripts and Octave Functions 1078@subsection Dual-Purpose Executable Scripts and Octave Functions 1079 1080To write m-files that can act as executable programs when called from the shell 1081or as normal functions when called from within Octave, use default input 1082arguments initialized with the @code{argv} function. 1083 1084If a function is called from the shell Octave will not pass any input 1085parameters to the function and therefore the default argument is used. But 1086when a function is called from the interpreter any arguments @emph{are} passed 1087to the function and these override the default. 1088 1089Additionally, the file must end with the extension @file{.m} so that the 1090interpreter will recognize it as an Octave function. Finally, the output from 1091@code{argv} is a cell array of strings. It may be necessary to convert this 1092to a numeric value with @code{str2double} or @code{str2num} before processing. 1093 1094As a complete example, consider the following code located in the file 1095@file{mysin.m}. 1096 1097@example 1098@group 1099#! /bin/octave -qf 1100function retval = mysin (x = str2double (argv()@{end@})) 1101 retval = sin (x) 1102endfunction 1103@end group 1104@end example 1105 1106This can be called from the shell with 1107 1108@example 1109mysin.m 1.5 1110@end example 1111 1112@noindent 1113or from Octave with 1114 1115@example 1116mysin (1.5) 1117@end example 1118 1119@node Comments 1120@section Comments in Octave Programs 1121@cindex comments 1122@cindex use of comments 1123@cindex documenting Octave programs 1124 1125A @dfn{comment} is some text that is included in a program for the sake 1126of human readers, and which is NOT an executable part of the program. 1127Comments can explain what the program does, and how it works. Nearly all 1128programming languages have provisions for comments, because programs are 1129typically hard to understand without them. 1130 1131@menu 1132* Single Line Comments:: 1133* Block Comments:: 1134* Comments and the Help System:: 1135@end menu 1136 1137@node Single Line Comments 1138@subsection Single Line Comments 1139 1140@opindex @code{#} comment marker 1141@opindex @code{%} comment marker 1142In the Octave language, a comment starts with either the sharp sign 1143character, @samp{#}, or the percent symbol @samp{%} and continues to the 1144end of the line. Any text following the sharp sign or percent symbol is 1145ignored by the Octave interpreter and not executed. The following example 1146shows whole line and partial line comments. 1147 1148@example 1149@group 1150function countdown 1151 # Count down for main rocket engines 1152 disp (3); 1153 disp (2); 1154 disp (1); 1155 disp ("Blast Off!"); # Rocket leaves pad 1156endfunction 1157@end group 1158@end example 1159 1160@node Block Comments 1161@subsection Block Comments 1162@cindex block comments 1163@cindex multi-line comments 1164 1165@opindex @code{#@{} block comment marker 1166@opindex @code{%@{} block comment marker 1167Entire blocks of code can be commented by enclosing the code between 1168matching @samp{#@{} and @samp{#@}} or @samp{%@{} and @samp{%@}} markers. 1169For example, 1170 1171@example 1172@group 1173function quick_countdown 1174 # Count down for main rocket engines 1175 disp (3); 1176 #@{ 1177 disp (2); 1178 disp (1); 1179 #@} 1180 disp ("Blast Off!"); # Rocket leaves pad 1181endfunction 1182@end group 1183@end example 1184 1185@noindent 1186will produce a very quick countdown from @qcode{'3'} to @qcode{"Blast Off"} as 1187the lines "@code{disp (2);}" and "@code{disp (1);}" won't be executed. 1188 1189The block comment markers must appear alone as the only characters on a line 1190(excepting whitespace) in order to be parsed correctly. 1191 1192@node Comments and the Help System 1193@subsection Comments and the Help System 1194@cindex documenting functions 1195@cindex documenting user scripts 1196@cindex help, user-defined functions 1197 1198The @code{help} command (@pxref{Getting Help}) is able to find the first 1199block of comments in a function and return those as a documentation 1200string. This means that the same commands used to get help 1201on built-in functions are available for properly formatted user-defined 1202functions. For example, after defining the function @code{f} below, 1203 1204@example 1205@group 1206function xdot = f (x, t) 1207 1208# usage: f (x, t) 1209# 1210# This function defines the right-hand 1211# side functions for a set of nonlinear 1212# differential equations. 1213 1214 r = 0.25; 1215 @dots{} 1216endfunction 1217@end group 1218@end example 1219 1220@noindent 1221the command @kbd{help f} produces the output 1222 1223@example 1224@group 1225 usage: f (x, t) 1226 1227 This function defines the right-hand 1228 side functions for a set of nonlinear 1229 differential equations. 1230@end group 1231@end example 1232 1233Although it is possible to put comment lines into keyboard-composed, 1234throw-away Octave programs, it usually isn't very useful because the 1235purpose of a comment is to help you or another person understand the 1236program at a later time. 1237 1238The @code{help} parser currently only recognizes single line comments 1239(@pxref{Single Line Comments}) and not block comments for the initial 1240help text. 1241