Mercurial > hg > octave-nkf
annotate doc/interpreter/errors.txi @ 9245:16f53d29049f
update copyright notices
| author | John W. Eaton <jwe@octave.org> |
|---|---|
| date | Fri, 22 May 2009 10:46:00 -0400 |
| parents | 923c7cb7f13f |
| children | d371cb65428a |
| rev | line source |
|---|---|
| 9245 | 1 @c Copyright (C) 1996, 1997, 2007, 2008, 2009 John W. Eaton |
| 7018 | 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 the | |
| 7 @c Free Software Foundation; either version 3 of the License, or (at | |
| 8 @c your option) any later version. | |
| 9 @c | |
| 10 @c Octave is distributed in the hope that it will be useful, but WITHOUT | |
| 11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| 12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| 13 @c 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 <http://www.gnu.org/licenses/>. | |
| 3294 | 18 |
| 6667 | 19 @node Errors and Warnings |
| 20 @chapter Errors and Warnings | |
| 3294 | 21 |
| 22 Octave includes several functions for printing error and warning | |
| 23 messages. When you write functions that need to take special action | |
| 24 when they encounter abnormal conditions, you should print the error | |
| 25 messages using the functions described in this chapter. | |
| 26 | |
| 6667 | 27 Since many of Octave's functions use these functions, it is also useful |
| 28 to understand them, so that errors and warnings can be handled. | |
| 29 | |
| 30 @menu | |
| 31 * Handling Errors:: | |
| 32 * Handling Warnings:: | |
| 33 @end menu | |
| 34 | |
| 35 @node Handling Errors | |
| 36 @section Handling Errors | |
| 37 | |
| 38 An error is something that occurs when a program is in a state where | |
| 39 it doesn't make sense to continue. An example is when a function is | |
| 40 called with too few input arguments. In this situation the function | |
| 41 should abort with an error message informing the user of the lacking | |
| 42 input arguments. | |
| 43 | |
| 44 Since an error can occur during the evaluation of a program, it is | |
| 45 very convenient to be able to detect that an error occurred, so that | |
| 46 the error can be fixed. This is possible with the @code{try} statement | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
47 described in @ref{The @code{try} Statement}. |
| 6667 | 48 |
| 49 @menu | |
| 50 * Raising Errors:: | |
| 51 * Catching Errors:: | |
| 52 @end menu | |
| 53 | |
| 54 @node Raising Errors | |
| 55 @subsection Raising Errors | |
| 56 | |
| 57 The most common use of errors is for checking input arguments to | |
| 58 functions. The following example calls the @code{error} function if | |
| 59 the function @code{f} is called without any input arguments. | |
| 60 | |
| 61 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
62 @group |
| 6667 | 63 function f (arg1) |
| 64 if (nargin == 0) | |
| 65 error("not enough input arguments"); | |
| 66 endif | |
| 67 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
68 @end group |
| 6667 | 69 @end example |
| 70 | |
| 71 When the @code{error} function is called, it prints the given message | |
| 72 and returns to the Octave prompt. This means that no code following | |
| 73 a call to @code{error} will be executed. | |
| 74 | |
| 3373 | 75 @DOCSTRING(error) |
| 3294 | 76 |
| 6667 | 77 Since it is common to use errors when there is something wrong with |
| 78 the input to a function, Octave supports functions to simplify such code. | |
| 79 When the @code{print_usage} function is called, it reads the help text | |
| 80 of the function calling @code{print_usage}, and presents a useful error. | |
| 81 If the help text is written in Texinfo it is possible to present an | |
| 82 error message that only contains the function prototypes as described | |
| 83 by the @code{@@deftypefn} parts of the help text. When the help text | |
| 84 isn't written in Texinfo, the error message contains the entire help | |
| 85 message. | |
| 86 | |
| 87 Consider the following function. | |
| 88 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
89 @group |
| 6667 | 90 ## -*- texinfo -*- |
| 91 ## @@deftypefn @{Function File@} f (@@var@{arg1@}) | |
| 92 ## Function help text goes here@dots{} | |
| 93 ## @@end deftypefn | |
| 94 function f (arg1) | |
| 95 if (nargin == 0) | |
| 96 print_usage (); | |
| 97 endif | |
| 98 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
99 @end group |
| 6667 | 100 @end example |
| 101 | |
| 102 @noindent | |
| 103 When it is called with no input arguments it produces the following | |
| 104 error. | |
| 105 | |
| 106 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
107 @group |
| 6667 | 108 f () |
|
8015
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
109 |
|
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
110 Invalid call to f. Correct usage is: |
|
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
111 |
| 6667 | 112 @print{} -- Function File: f (ARG1) |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
113 @print{} Function help text goes here@dots{} |
| 6667 | 114 @print{} |
| 115 @print{} | |
| 116 @print{} | |
|
8015
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
117 @print{} error: called from: |
|
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
118 @print{} error: print_usage at line -1, column -1 |
|
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
119 @print{} error: /home/jwe/octave/f.m at line 7, column 5 |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
120 @end group |
| 6667 | 121 @end example |
| 122 | |
| 123 @DOCSTRING(print_usage) | |
| 124 | |
| 125 @DOCSTRING(usage) | |
| 126 | |
| 6551 | 127 @DOCSTRING(beep) |
| 128 | |
| 3373 | 129 @DOCSTRING(beep_on_error) |
| 3294 | 130 |
| 6667 | 131 @node Catching Errors |
| 132 @subsection Catching Errors | |
| 133 | |
| 134 When an error occurs, it can be detected and handled using the | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
135 @code{try} statement as described in @ref{The @code{try} Statement}. |
| 6667 | 136 As an example, the following piece of code counts the number of errors |
| 137 that occurs during a @code{for} loop. | |
| 138 | |
| 139 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
140 @group |
| 6667 | 141 number_of_errors = 0; |
| 142 for n = 1:100 | |
| 143 try | |
| 144 @dots{} | |
| 145 catch | |
| 146 number_of_errors++; | |
| 147 end_try_catch | |
| 148 endfor | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
149 @end group |
| 6667 | 150 @end example |
| 3294 | 151 |
| 6667 | 152 The above example treats all errors the same. In many situations it |
| 153 can however be necessary to discriminate between errors, and take | |
| 154 different actions depending on the error. The @code{lasterror} | |
| 155 function returns a structure containing information about the last | |
| 156 error that occurred. As an example, the code above could be changed | |
| 157 to count the number of errors related to the @samp{*} operator. | |
| 6549 | 158 |
| 6667 | 159 @example |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
160 @group |
| 6667 | 161 number_of_errors = 0; |
| 162 for n = 1:100 | |
| 163 try | |
| 164 @dots{} | |
| 165 catch | |
| 166 msg = lasterror.message; | |
| 167 if (strfind (msg, "operator *")) | |
| 168 number_of_errors++; | |
| 169 endif | |
| 170 end_try_catch | |
| 171 endfor | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
172 @end group |
| 6667 | 173 @end example |
| 3294 | 174 |
| 6549 | 175 @DOCSTRING(lasterror) |
| 176 | |
| 4169 | 177 @DOCSTRING(lasterr) |
| 178 | |
| 6667 | 179 When an error has been handled it is possible to raise it again. This |
| 180 can be useful when an error needs to be detected, but the program should | |
| 181 still abort. This is possible using the @code{rethrow} function. The | |
| 182 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
|
183 related to the @samp{*} operator, but still abort if another kind of |
| 6667 | 184 error occurs. |
| 185 | |
| 186 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
187 @group |
| 6667 | 188 number_of_errors = 0; |
| 189 for n = 1:100 | |
| 190 try | |
| 191 @dots{} | |
| 192 catch | |
| 193 msg = lasterror.message; | |
| 194 if (strfind (msg, "operator *")) | |
| 195 number_of_errors++; | |
| 196 else | |
| 197 rethrow (lasterror); | |
| 198 endif | |
| 199 end_try_catch | |
| 200 endfor | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
201 @end group |
| 6667 | 202 @end example |
| 4169 | 203 |
| 6549 | 204 @DOCSTRING(rethrow) |
| 205 | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
206 @c FIXME: I have no idea what the rest of the functions are used for... |
| 6549 | 207 |
| 208 @DOCSTRING(errno) | |
| 209 | |
| 210 @DOCSTRING(errno_list) | |
| 211 | |
| 6667 | 212 @node Handling Warnings |
| 213 @section Handling Warnings | |
| 214 | |
| 215 Like an error, a warning is issued when something unexpected happens. | |
| 216 Unlike an error, a warning doesn't abort the currently running program. | |
| 217 A simple example of a warning is when a number is divided by zero. In | |
| 218 this case Octave will issue a warning and assign the value @code{Inf} | |
| 219 to the result. | |
| 220 | |
| 221 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
222 @group |
| 6667 | 223 a = 1/0 |
| 224 @print{} warning: division by zero | |
| 225 @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
|
226 @end group |
| 6667 | 227 @end example |
| 228 | |
| 229 @menu | |
| 230 * Issuing Warnings:: | |
| 231 * Enabling and Disabling Warnings:: | |
| 232 @end menu | |
| 233 | |
| 234 @node Issuing Warnings | |
| 235 @subsection Issuing Warnings | |
| 236 | |
| 237 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
|
238 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
|
239 string describing the warning as its input argument. As an example, |
| 6667 | 240 the following code controls if the variable @samp{a} is non-negative, |
| 241 and if not issues a warning and sets @samp{a} to zero. | |
| 242 | |
| 243 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
244 @group |
| 6667 | 245 a = -1; |
| 246 if (a < 0) | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
247 warning ("'a' must be non-negative. Setting 'a' to zero."); |
| 6667 | 248 a = 0; |
| 249 endif | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
250 @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
|
251 @end group |
| 6667 | 252 @end example |
| 3294 | 253 |
| 6667 | 254 Since warnings aren't fatal to a running program, it is not possible |
| 255 to catch a warning using the @code{try} statement or something similar. | |
| 256 It is however possible to access the last warning as a string using the | |
| 257 @code{lastwarn} function. | |
| 258 | |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8015
diff
changeset
|
259 It is also possible to assign an identification string to a warning. |
| 6667 | 260 If a warning has such an ID the user can enable and disable this warning |
| 261 as will be described in the next section. To assign an ID to a warning, | |
| 262 simply call @code{warning} with two string arguments, where the first | |
| 263 is the identification string, and the second is the actual warning. | |
| 264 | |
| 265 @DOCSTRING(warning) | |
| 266 | |
| 267 @DOCSTRING(lastwarn) | |
| 268 | |
| 269 @node Enabling and Disabling Warnings | |
| 270 @subsection Enabling and Disabling Warnings | |
| 271 | |
| 272 The @code{warning} function also allows you to control which warnings | |
| 273 are actually printed to the screen. If the @code{warning} function | |
| 274 is called with a string argument that is either @code{"on"} or @code{"off"} | |
| 275 all warnings will be enabled or disabled. | |
| 3294 | 276 |
| 6667 | 277 It is also possible to enable and disable individual warnings through |
| 278 their string identifications. The following code will issue a warning | |
| 279 | |
| 280 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
281 @group |
| 6667 | 282 warning ("non-negative-variable", |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
283 "'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
|
284 @end group |
| 6667 | 285 @end example |
| 286 | |
| 287 @noindent | |
| 288 while the following won't issue a warning | |
| 289 | |
| 290 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
291 @group |
| 6667 | 292 warning ("off", "non-negative-variable"); |
| 293 warning ("non-negative-variable", | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
294 "'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
|
295 @end group |
| 6667 | 296 @end example |
| 297 | |
| 298 The functions distributed with Octave can issue one of the following | |
| 299 warnings. | |
| 300 | |
| 301 @DOCSTRING(warning_ids) | |
| 302 | |
| 303 |