Mercurial > hg > octave-nkf
annotate doc/interpreter/errors.txi @ 10843:229675bb7647 ss-3-3-52
version is now 3.3.52
| author | John W. Eaton <jwe@octave.org> |
|---|---|
| date | Sun, 01 Aug 2010 11:49:45 -0400 |
| parents | 322f43e0e170 |
| children | fd0a3ac60b0e |
| 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. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
9293
diff
changeset
|
88 |
| 6667 | 89 @example |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
90 @group |
| 6667 | 91 ## -*- texinfo -*- |
| 92 ## @@deftypefn @{Function File@} f (@@var@{arg1@}) | |
| 93 ## Function help text goes here@dots{} | |
| 94 ## @@end deftypefn | |
| 95 function f (arg1) | |
| 96 if (nargin == 0) | |
| 97 print_usage (); | |
| 98 endif | |
| 99 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
100 @end group |
| 6667 | 101 @end example |
| 102 | |
| 103 @noindent | |
| 104 When it is called with no input arguments it produces the following | |
| 105 error. | |
| 106 | |
| 107 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
108 @group |
| 6667 | 109 f () |
|
8015
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
110 |
|
9293
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
111 @print{} error: Invalid call to f. Correct usage is: |
|
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
112 @print{} |
|
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
113 @print{} -- Function File: f (ARG1) |
|
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
114 @print{} |
|
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
115 @print{} |
|
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
116 @print{} Additional help for built-in functions and operators is |
|
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
117 @print{} available in the on-line version of the manual. Use the command |
|
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
118 @print{} `doc <topic>' to search the manual index. |
|
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
119 @print{} |
|
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
120 @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
|
121 @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
|
122 @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
|
123 @end group |
| 6667 | 124 @end example |
| 125 | |
| 126 @DOCSTRING(print_usage) | |
| 127 | |
| 128 @DOCSTRING(usage) | |
| 129 | |
| 6551 | 130 @DOCSTRING(beep) |
| 131 | |
| 3373 | 132 @DOCSTRING(beep_on_error) |
| 3294 | 133 |
| 6667 | 134 @node Catching Errors |
| 135 @subsection Catching Errors | |
| 136 | |
| 137 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
|
138 @code{try} statement as described in @ref{The @code{try} Statement}. |
| 6667 | 139 As an example, the following piece of code counts the number of errors |
| 140 that occurs during a @code{for} loop. | |
| 141 | |
| 142 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
143 @group |
| 6667 | 144 number_of_errors = 0; |
| 145 for n = 1:100 | |
| 146 try | |
| 147 @dots{} | |
| 148 catch | |
| 149 number_of_errors++; | |
| 150 end_try_catch | |
| 151 endfor | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
152 @end group |
| 6667 | 153 @end example |
| 3294 | 154 |
| 6667 | 155 The above example treats all errors the same. In many situations it |
| 156 can however be necessary to discriminate between errors, and take | |
| 157 different actions depending on the error. The @code{lasterror} | |
| 158 function returns a structure containing information about the last | |
| 159 error that occurred. As an example, the code above could be changed | |
| 160 to count the number of errors related to the @samp{*} operator. | |
| 6549 | 161 |
| 6667 | 162 @example |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
163 @group |
| 6667 | 164 number_of_errors = 0; |
| 165 for n = 1:100 | |
| 166 try | |
| 167 @dots{} | |
| 168 catch | |
| 169 msg = lasterror.message; | |
| 170 if (strfind (msg, "operator *")) | |
| 171 number_of_errors++; | |
| 172 endif | |
| 173 end_try_catch | |
| 174 endfor | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
175 @end group |
| 6667 | 176 @end example |
| 3294 | 177 |
| 6549 | 178 @DOCSTRING(lasterror) |
| 179 | |
| 4169 | 180 @DOCSTRING(lasterr) |
| 181 | |
| 6667 | 182 When an error has been handled it is possible to raise it again. This |
| 183 can be useful when an error needs to be detected, but the program should | |
| 184 still abort. This is possible using the @code{rethrow} function. The | |
| 185 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
|
186 related to the @samp{*} operator, but still abort if another kind of |
| 6667 | 187 error occurs. |
| 188 | |
| 189 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
190 @group |
| 6667 | 191 number_of_errors = 0; |
| 192 for n = 1:100 | |
| 193 try | |
| 194 @dots{} | |
| 195 catch | |
| 196 msg = lasterror.message; | |
| 197 if (strfind (msg, "operator *")) | |
| 198 number_of_errors++; | |
| 199 else | |
| 200 rethrow (lasterror); | |
| 201 endif | |
| 202 end_try_catch | |
| 203 endfor | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
204 @end group |
| 6667 | 205 @end example |
| 4169 | 206 |
| 6549 | 207 @DOCSTRING(rethrow) |
| 208 | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
209 @c FIXME: I have no idea what the rest of the functions are used for... |
| 6549 | 210 |
| 211 @DOCSTRING(errno) | |
| 212 | |
| 213 @DOCSTRING(errno_list) | |
| 214 | |
| 6667 | 215 @node Handling Warnings |
| 216 @section Handling Warnings | |
| 217 | |
| 218 Like an error, a warning is issued when something unexpected happens. | |
| 219 Unlike an error, a warning doesn't abort the currently running program. | |
| 220 A simple example of a warning is when a number is divided by zero. In | |
| 221 this case Octave will issue a warning and assign the value @code{Inf} | |
| 222 to the result. | |
| 223 | |
| 224 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
225 @group |
| 6667 | 226 a = 1/0 |
| 227 @print{} warning: division by zero | |
| 228 @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
|
229 @end group |
| 6667 | 230 @end example |
| 231 | |
| 232 @menu | |
| 233 * Issuing Warnings:: | |
| 234 * Enabling and Disabling Warnings:: | |
| 235 @end menu | |
| 236 | |
| 237 @node Issuing Warnings | |
| 238 @subsection Issuing Warnings | |
| 239 | |
| 240 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
|
241 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
|
242 string describing the warning as its input argument. As an example, |
| 6667 | 243 the following code controls if the variable @samp{a} is non-negative, |
| 244 and if not issues a warning and sets @samp{a} to zero. | |
| 245 | |
| 246 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
247 @group |
| 6667 | 248 a = -1; |
| 249 if (a < 0) | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
250 warning ("'a' must be non-negative. Setting 'a' to zero."); |
| 6667 | 251 a = 0; |
| 252 endif | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
253 @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
|
254 @end group |
| 6667 | 255 @end example |
| 3294 | 256 |
| 6667 | 257 Since warnings aren't fatal to a running program, it is not possible |
| 258 to catch a warning using the @code{try} statement or something similar. | |
| 259 It is however possible to access the last warning as a string using the | |
| 260 @code{lastwarn} function. | |
| 261 | |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8015
diff
changeset
|
262 It is also possible to assign an identification string to a warning. |
| 6667 | 263 If a warning has such an ID the user can enable and disable this warning |
| 264 as will be described in the next section. To assign an ID to a warning, | |
| 265 simply call @code{warning} with two string arguments, where the first | |
| 266 is the identification string, and the second is the actual warning. | |
| 267 | |
| 268 @DOCSTRING(warning) | |
| 269 | |
| 270 @DOCSTRING(lastwarn) | |
| 271 | |
| 272 @node Enabling and Disabling Warnings | |
| 273 @subsection Enabling and Disabling Warnings | |
| 274 | |
| 275 The @code{warning} function also allows you to control which warnings | |
| 276 are actually printed to the screen. If the @code{warning} function | |
| 277 is called with a string argument that is either @code{"on"} or @code{"off"} | |
| 278 all warnings will be enabled or disabled. | |
| 3294 | 279 |
| 6667 | 280 It is also possible to enable and disable individual warnings through |
| 281 their string identifications. The following code will issue a warning | |
| 282 | |
| 283 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
284 @group |
| 6667 | 285 warning ("non-negative-variable", |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
286 "'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
|
287 @end group |
| 6667 | 288 @end example |
| 289 | |
| 290 @noindent | |
| 291 while the following won't issue a warning | |
| 292 | |
| 293 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
294 @group |
| 6667 | 295 warning ("off", "non-negative-variable"); |
| 296 warning ("non-negative-variable", | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
297 "'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
|
298 @end group |
| 6667 | 299 @end example |
| 300 | |
| 301 The functions distributed with Octave can issue one of the following | |
| 302 warnings. | |
| 303 | |
| 304 @DOCSTRING(warning_ids) | |
| 305 | |
| 306 |