octave-nkf: doc/interpreter/errors.txi annotate

annotate doc/interpreter/errors.txi @ 19630:0e1f5a750d00

maint: Periodic merge of gui-release to default.

author	John W. Eaton <jwe@octave.org>
date	Tue, 20 Jan 2015 10:24:46 -0500
parents	d4a920d28242 446c46af4b42
children	4197fc428c7d

rev	line source
17744 d63878346099 maint: Update copyright notices for release. John W. Eaton <jwe@octave.org> parents: 17281 diff changeset	1 @c Copyright (C) 1996-2013 John W. Eaton
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	2 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	3 @c This file is part of Octave.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	4 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	5 @c Octave is free software; you can redistribute it and/or modify it
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	6 @c under the terms of the GNU General Public License as published by the
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	7 @c Free Software Foundation; either version 3 of the License, or (at
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	8 @c your option) any later version.
19627 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18220 diff changeset	9 @c
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	10 @c Octave is distributed in the hope that it will be useful, but WITHOUT
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	13 @c for more details.
19627 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18220 diff changeset	14 @c
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	15 @c You should have received a copy of the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	16 @c along with Octave; see the file COPYING. If not, see
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6778 diff changeset	17 @c <http://www.gnu.org/licenses/>.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	18
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	19 @node Errors and Warnings
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	20 @chapter Errors and Warnings
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	21
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	22 Octave includes several functions for printing error and warning
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	23 messages. When you write functions that need to take special action
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	24 when they encounter abnormal conditions, you should print the error
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	25 messages using the functions described in this chapter.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	26
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	27 Since many of Octave's functions use these functions, it is also useful
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	28 to understand them, so that errors and warnings can be handled.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	29
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	30 @menu
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	31 * Handling Errors::
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	32 * Handling Warnings::
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	33 @end menu
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	34
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	35 @node Handling Errors
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	36 @section Handling Errors
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	37
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	38 An error is something that occurs when a program is in a state where
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	39 it doesn't make sense to continue. An example is when a function is
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	40 called with too few input arguments. In this situation the function
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	41 should abort with an error message informing the user of the lacking
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	42 input arguments.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	43
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	44 Since an error can occur during the evaluation of a program, it is
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	45 very convenient to be able to detect that an error occurred, so that
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	46 the error can be fixed. This is possible with the @code{try} statement
15684 ddc651eecf7a Fix Info index for language statements (bug #37787) Rik <rik@octave.org> parents: 15544 diff changeset	47 described in @ref{The try Statement}.
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	48
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	49 @menu
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	50 * Raising Errors::
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	51 * Catching Errors::
12560 d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	52 * Recovering From Errors::
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	53 @end menu
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	54
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	55 @node Raising Errors
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	56 @subsection Raising Errors
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	57
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	58 The most common use of errors is for checking input arguments to
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	59 functions. The following example calls the @code{error} function if
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	60 the function @code{f} is called without any input arguments.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	61
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	62 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	63 @group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	64 function f (arg1)
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	65 if (nargin == 0)
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	66 error ("not enough input arguments");
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	67 endif
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	68 endfunction
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	69 @end group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	70 @end example
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	71
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	72 When the @code{error} function is called, it prints the given message
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	73 and returns to the Octave prompt. This means that no code following
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	74 a call to @code{error} will be executed.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	75
3373 36405da8e173 [project @ 1999-11-23 20:54:17 by jwe] jwe parents: 3294 diff changeset	76 @DOCSTRING(error)
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	77
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	78 Since it is common to use errors when there is something wrong with
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	79 the input to a function, Octave supports functions to simplify such code.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	80 When the @code{print_usage} function is called, it reads the help text
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	81 of the function calling @code{print_usage}, and presents a useful error.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	82 If the help text is written in Texinfo it is possible to present an
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	83 error message that only contains the function prototypes as described
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	84 by the @code{@@deftypefn} parts of the help text. When the help text
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	85 isn't written in Texinfo, the error message contains the entire help
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	86 message.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	87
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	88 Consider the following function.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 9293 diff changeset	89
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	90 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	91 @group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	92 ## -- texinfo --
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	93 ## @@deftypefn @{Function File@} f (@@var@{arg1@})
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	94 ## Function help text goes here@dots{}
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	95 ## @@end deftypefn
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	96 function f (arg1)
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	97 if (nargin == 0)
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	98 print_usage ();
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	99 endif
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	100 endfunction
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	101 @end group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	102 @end example
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	103
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	104 @noindent
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	105 When it is called with no input arguments it produces the following
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	106 error.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	107
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	108 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	109 @group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	110 f ()
8015 30629059b72d Update the manual to reflect the changes in error output sh@sh-laptop parents: 7031 diff changeset	111
9293 d371cb65428a Fix output from 'print_usage' in Errors chapter in the manual Soren Hauberg <hauberg@gmail.com> parents: 9245 diff changeset	112 @print{} error: Invalid call to f. Correct usage is:
19627 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18220 diff changeset	113 @print{}
9293 d371cb65428a Fix output from 'print_usage' in Errors chapter in the manual Soren Hauberg <hauberg@gmail.com> parents: 9245 diff changeset	114 @print{} -- Function File: f (ARG1)
19627 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18220 diff changeset	115 @print{}
446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18220 diff changeset	116 @print{}
9293 d371cb65428a Fix output from 'print_usage' in Errors chapter in the manual Soren Hauberg <hauberg@gmail.com> parents: 9245 diff changeset	117 @print{} Additional help for built-in functions and operators is
15544 6a4e79110857 doc: Replace 'on-line' with modern 'online' in documentation and messages. Rik <rik@octave.org> parents: 15524 diff changeset	118 @print{} available in the online version of the manual. Use the command
9293 d371cb65428a Fix output from 'print_usage' in Errors chapter in the manual Soren Hauberg <hauberg@gmail.com> parents: 9245 diff changeset	119 @print{} `doc <topic>' to search the manual index.
19627 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18220 diff changeset	120 @print{}
9293 d371cb65428a Fix output from 'print_usage' in Errors chapter in the manual Soren Hauberg <hauberg@gmail.com> parents: 9245 diff changeset	121 @print{} Help and information about Octave is also available on the WWW
d371cb65428a Fix output from 'print_usage' in Errors chapter in the manual Soren Hauberg <hauberg@gmail.com> parents: 9245 diff changeset	122 @print{} at http://www.octave.org and via the help@@octave.org
d371cb65428a Fix output from 'print_usage' in Errors chapter in the manual Soren Hauberg <hauberg@gmail.com> parents: 9245 diff changeset	123 @print{} mailing list.
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	124 @end group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	125 @end example
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	126
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	127 @DOCSTRING(print_usage)
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	128
6551 75c4045cf1db [project @ 2007-04-20 08:09:16 by jwe] jwe parents: 6549 diff changeset	129 @DOCSTRING(beep)
75c4045cf1db [project @ 2007-04-20 08:09:16 by jwe] jwe parents: 6549 diff changeset	130
3373 36405da8e173 [project @ 1999-11-23 20:54:17 by jwe] jwe parents: 3294 diff changeset	131 @DOCSTRING(beep_on_error)
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	132
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	133 @node Catching Errors
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	134 @subsection Catching Errors
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	135
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	136 When an error occurs, it can be detected and handled using the
15684 ddc651eecf7a Fix Info index for language statements (bug #37787) Rik <rik@octave.org> parents: 15544 diff changeset	137 @code{try} statement as described in @ref{The try Statement}.
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	138 As an example, the following piece of code counts the number of errors
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	139 that occurs during a @code{for} loop.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	140
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	141 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	142 @group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	143 number_of_errors = 0;
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	144 for n = 1:100
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	145 try
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	146 @dots{}
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	147 catch
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	148 number_of_errors++;
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	149 end_try_catch
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	150 endfor
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	151 @end group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	152 @end example
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	153
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	154 The above example treats all errors the same. In many situations it
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	155 can however be necessary to discriminate between errors, and take
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	156 different actions depending on the error. The @code{lasterror}
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	157 function returns a structure containing information about the last
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	158 error that occurred. As an example, the code above could be changed
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	159 to count the number of errors related to the @samp{*} operator.
6549 5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 4699 diff changeset	160
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	161 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	162 @group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	163 number_of_errors = 0;
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	164 for n = 1:100
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	165 try
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	166 @dots{}
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	167 catch
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	168 msg = lasterror.message;
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	169 if (strfind (msg, "operator *"))
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	170 number_of_errors++;
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	171 endif
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	172 end_try_catch
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	173 endfor
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	174 @end group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	175 @end example
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	176
18220 6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	177 @noindent
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	178 Alternatively, the output of the @code{lasterror} function can be found
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	179 in a variable indicated immediately after the @code{catch} keyword, as
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	180 in the example below showing how to redirect an error as a warning:
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	181
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	182 @example
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	183 @group
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	184 try
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	185 @dots{}
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	186 catch err
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	187 warning(err.identifier, err.message);
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	188 @dots{}
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	189 end_try_catch
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	190 @end group
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	191 @end example
6fd22474783e doc: Update manual for "catch err" syntax (bug #33217) Felipe G. Nievinski <fgnievinski@gmail.com> parents: 17757 diff changeset	192
6549 5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 4699 diff changeset	193 @DOCSTRING(lasterror)
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 4699 diff changeset	194
4169 d5667eaf8859 [project @ 2002-11-12 03:13:42 by jwe] jwe parents: 4167 diff changeset	195 @DOCSTRING(lasterr)
d5667eaf8859 [project @ 2002-11-12 03:13:42 by jwe] jwe parents: 4167 diff changeset	196
15731 18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	197 It is also possible to assign an identification string to an error.
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	198 If an error has such an ID the user can catch this error
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	199 as will be shown in the next example. To assign an ID to an error,
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	200 simply call @code{error} with two string arguments, where the first
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	201 is the identification string, and the second is the actual error. Note
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 16826 diff changeset	202 that error IDs are in the format @qcode{"NAMESPACE:ERROR-NAME"}. The namespace
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 16826 diff changeset	203 @qcode{"Octave"} is used for Octave's own errors. Any other string is available
15731 18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	204 as a namespace for user's own errors.
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	205
16826 a4969508008e doc: Periodic spellcheck of the documentation. Rik <rik@octave.org> parents: 16816 diff changeset	206 The next example counts indexing errors. The errors are caught using the
15731 18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	207 field identifier of the structure returned by the function @code{lasterror}.
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	208
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	209 @example
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	210 @group
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	211 number_of_errors = 0;
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	212 for n = 1:100
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	213 try
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	214 @dots{}
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	215 catch
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	216 id = lasterror.identifier;
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	217 if (strcmp (id, "Octave:invalid-indexing"))
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	218 number_of_errors++;
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	219 endif
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	220 end_try_catch
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	221 endfor
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	222 @end group
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	223 @end example
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	224
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	225 The functions distributed with Octave can issue one of the following
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	226 errors.
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	227
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	228 @DOCSTRING(error_ids)
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	229
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	230 When an error has been handled it is possible to raise it again. This
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	231 can be useful when an error needs to be detected, but the program should
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	232 still abort. This is possible using the @code{rethrow} function. The
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	233 previous example can now be changed to count the number of errors
8347 fa78cb8d8a5c corrections for typos Brian Gough<bjg@network-theory.co.uk> parents: 8015 diff changeset	234 related to the @samp{*} operator, but still abort if another kind of
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	235 error occurs.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	236
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	237 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	238 @group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	239 number_of_errors = 0;
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	240 for n = 1:100
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	241 try
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	242 @dots{}
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	243 catch
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	244 msg = lasterror.message;
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	245 if (strfind (msg, "operator *"))
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	246 number_of_errors++;
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	247 else
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	248 rethrow (lasterror);
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	249 endif
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	250 end_try_catch
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	251 endfor
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	252 @end group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	253 @end example
4169 d5667eaf8859 [project @ 2002-11-12 03:13:42 by jwe] jwe parents: 4167 diff changeset	254
6549 5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 4699 diff changeset	255 @DOCSTRING(rethrow)
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 4699 diff changeset	256
9039 51dc9691f23f Cleanup documentation files errors.texi, debug.texi, io.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	257 @c FIXME: I have no idea what the rest of the functions are used for...
6549 5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 4699 diff changeset	258
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 4699 diff changeset	259 @DOCSTRING(errno)
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 4699 diff changeset	260
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 4699 diff changeset	261 @DOCSTRING(errno_list)
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 4699 diff changeset	262
12560 d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	263 @node Recovering From Errors
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	264 @subsection Recovering From Errors
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	265
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	266 Octave provides several ways of recovering from errors. There are
19627 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18220 diff changeset	267 @code{try}/@code{catch} blocks,
446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18220 diff changeset	268 @code{unwind_protect}/@code{unwind_protect_cleanup} blocks,
12560 d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	269 and finally the @code{onCleanup} command.
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	270
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	271 The @code{onCleanup} command associates an ordinary Octave variable (the
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	272 trigger) with an arbitrary function (the action). Whenever the Octave variable
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	273 ceases to exist---whether due to a function return, an error, or simply because
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	274 the variable has been removed with @code{clear}---then the assigned function
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	275 is executed.
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	276
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	277 The function can do anything necessary for cleanup such as closing open file
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	278 handles, printing an error message, or restoring global variables to their
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	279 initial values. The last example is a very convenient idiom for Octave code.
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	280 For example:
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	281
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	282 @example
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	283 @group
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	284 function rand42
17757 dae2230227a7 doc: Use double-quote in preference to single quote in code examples. Rik <rik@octave.org> parents: 17744 diff changeset	285 old_state = rand ("state");
18713 a142f35f3cb6 doc: Fix unbalanced parentheses in documentation. Rik <rik@octave.org> parents: 18220 diff changeset	286 restore_state = onCleanup (@@() rand ("state", old_state));
17757 dae2230227a7 doc: Use double-quote in preference to single quote in code examples. Rik <rik@octave.org> parents: 17744 diff changeset	287 rand ("state", 42);
12560 d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	288 @dots{}
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	289 endfunction # rand generator state restored by onCleanup
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	290 @end group
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	291 @end example
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	292
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	293 @DOCSTRING(onCleanup)
d6ad4ed57dda Add onCleanup function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	294
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	295 @node Handling Warnings
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	296 @section Handling Warnings
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	297
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	298 Like an error, a warning is issued when something unexpected happens.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	299 Unlike an error, a warning doesn't abort the currently running program.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	300 A simple example of a warning is when a number is divided by zero. In
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	301 this case Octave will issue a warning and assign the value @code{Inf}
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	302 to the result.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	303
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	304 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	305 @group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	306 a = 1/0
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	307 @print{} warning: division by zero
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	308 @result{} a = Inf
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	309 @end group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	310 @end example
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	311
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	312 @menu
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	313 * Issuing Warnings::
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	314 * Enabling and Disabling Warnings::
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	315 @end menu
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	316
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	317 @node Issuing Warnings
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	318 @subsection Issuing Warnings
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	319
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	320 It is possible to issue warnings from any code using the @code{warning}
9039 51dc9691f23f Cleanup documentation files errors.texi, debug.texi, io.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	321 function. In its most simple form, the @code{warning} function takes a
51dc9691f23f Cleanup documentation files errors.texi, debug.texi, io.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	322 string describing the warning as its input argument. As an example,
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	323 the following code controls if the variable @samp{a} is non-negative,
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	324 and if not issues a warning and sets @samp{a} to zero.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	325
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	326 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	327 @group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	328 a = -1;
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	329 if (a < 0)
9039 51dc9691f23f Cleanup documentation files errors.texi, debug.texi, io.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	330 warning ("'a' must be non-negative. Setting 'a' to zero.");
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	331 a = 0;
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	332 endif
9039 51dc9691f23f Cleanup documentation files errors.texi, debug.texi, io.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	333 @print{} 'a' must be non-negative. Setting 'a' to zero.
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	334 @end group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	335 @end example
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	336
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	337 Since warnings aren't fatal to a running program, it is not possible
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	338 to catch a warning using the @code{try} statement or something similar.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	339 It is however possible to access the last warning as a string using the
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	340 @code{lastwarn} function.
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	341
8347 fa78cb8d8a5c corrections for typos Brian Gough<bjg@network-theory.co.uk> parents: 8015 diff changeset	342 It is also possible to assign an identification string to a warning.
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	343 If a warning has such an ID the user can enable and disable this warning
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	344 as will be described in the next section. To assign an ID to a warning,
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	345 simply call @code{warning} with two string arguments, where the first
15524 15628a84a4fa Document form of warning IDs is NAMESPACE:WARNING-NAME (bug #37559) Rik <rik@octave.org> parents: 14138 diff changeset	346 is the identification string, and the second is the actual warning. Note
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 16826 diff changeset	347 that warning IDs are in the format @qcode{"NAMESPACE:WARNING-NAME"}. The
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 16826 diff changeset	348 namespace @qcode{"Octave"} is used for Octave's own warnings. Any other string
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 16826 diff changeset	349 is available as a namespace for user's own warnings.
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	350
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	351 @DOCSTRING(warning)
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	352
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	353 @DOCSTRING(lastwarn)
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	354
15731 18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	355 The functions distributed with Octave can issue one of the following
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	356 warnings.
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	357
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	358 @DOCSTRING(warning_ids)
18f168880226 error_ids: Adding ids and documentation Juan Pablo Carbajal <ajuanpi+dev@gmail.com> parents: 15685 diff changeset	359
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	360 @node Enabling and Disabling Warnings
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	361 @subsection Enabling and Disabling Warnings
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	362
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	363 The @code{warning} function also allows you to control which warnings
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	364 are actually printed to the screen. If the @code{warning} function
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 16826 diff changeset	365 is called with a string argument that is either @qcode{"on"} or @qcode{"off"}
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	366 all warnings will be enabled or disabled.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	367
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	368 It is also possible to enable and disable individual warnings through
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	369 their string identifications. The following code will issue a warning
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	370
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	371 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	372 @group
19627 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18220 diff changeset	373 warning ("example:non-negative-variable",
9039 51dc9691f23f Cleanup documentation files errors.texi, debug.texi, io.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	374 "'a' must be non-negative. Setting 'a' to zero.");
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	375 @end group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	376 @end example
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	377
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	378 @noindent
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	379 while the following won't issue a warning
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	380
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	381 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	382 @group
15524 15628a84a4fa Document form of warning IDs is NAMESPACE:WARNING-NAME (bug #37559) Rik <rik@octave.org> parents: 14138 diff changeset	383 warning ("off", "example:non-negative-variable");
19627 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18220 diff changeset	384 warning ("example:non-negative-variable",
9039 51dc9691f23f Cleanup documentation files errors.texi, debug.texi, io.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	385 "'a' must be non-negative. Setting 'a' to zero.");
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9039 diff changeset	386 @end group
6667 a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	387 @end example
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	388
a36e4bb26943 [project @ 2007-05-28 06:20:12 by jwe] jwe parents: 6551 diff changeset	389

Mercurial > octave-nkf

annotate doc/interpreter/errors.txi @ 19630:0e1f5a750d00