Mercurial > hg > octave-nkf
annotate doc/interpreter/errors.txi @ 8920:eb63fbe60fab
update copyright notices
| author | John W. Eaton <jwe@octave.org> |
|---|---|
| date | Sat, 07 Mar 2009 10:41:27 -0500 |
| parents | fa78cb8d8a5c |
| children | fca0dc2fb042 |
| rev | line source |
|---|---|
| 8920 | 1 @c Copyright (C) 1996, 1997, 2007, 2008 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 | |
| 47 described in @ref{The try Statement}. | |
| 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 | |
| 62 function f (arg1) | |
| 63 if (nargin == 0) | |
| 64 error("not enough input arguments"); | |
| 65 endif | |
| 66 endfunction | |
| 67 @end example | |
| 68 | |
| 69 When the @code{error} function is called, it prints the given message | |
| 70 and returns to the Octave prompt. This means that no code following | |
| 71 a call to @code{error} will be executed. | |
| 72 | |
| 3373 | 73 @DOCSTRING(error) |
| 3294 | 74 |
| 6667 | 75 Since it is common to use errors when there is something wrong with |
| 76 the input to a function, Octave supports functions to simplify such code. | |
| 77 When the @code{print_usage} function is called, it reads the help text | |
| 78 of the function calling @code{print_usage}, and presents a useful error. | |
| 79 If the help text is written in Texinfo it is possible to present an | |
| 80 error message that only contains the function prototypes as described | |
| 81 by the @code{@@deftypefn} parts of the help text. When the help text | |
| 82 isn't written in Texinfo, the error message contains the entire help | |
| 83 message. | |
| 84 | |
| 85 Consider the following function. | |
| 86 @example | |
| 87 ## -*- texinfo -*- | |
| 88 ## @@deftypefn @{Function File@} f (@@var@{arg1@}) | |
| 89 ## Function help text goes here@dots{} | |
| 90 ## @@end deftypefn | |
| 91 function f (arg1) | |
| 92 if (nargin == 0) | |
| 93 print_usage (); | |
| 94 endif | |
| 95 endfunction | |
| 96 @end example | |
| 97 | |
| 98 @noindent | |
| 99 When it is called with no input arguments it produces the following | |
| 100 error. | |
| 101 | |
| 102 @example | |
| 103 f () | |
|
8015
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
104 |
|
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
105 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
|
106 |
| 6667 | 107 @print{} -- Function File: f (ARG1) |
|
8015
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
108 @print{} Function help text goes here... |
| 6667 | 109 @print{} |
| 110 @print{} | |
| 111 @print{} | |
|
8015
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
112 @print{} error: called from: |
|
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7031
diff
changeset
|
113 @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
|
114 @print{} error: /home/jwe/octave/f.m at line 7, column 5 |
| 6667 | 115 @end example |
| 116 | |
| 117 @DOCSTRING(print_usage) | |
| 118 | |
| 119 @DOCSTRING(usage) | |
| 120 | |
| 6551 | 121 @DOCSTRING(beep) |
| 122 | |
| 3373 | 123 @DOCSTRING(beep_on_error) |
| 3294 | 124 |
| 6667 | 125 @node Catching Errors |
| 126 @subsection Catching Errors | |
| 127 | |
| 128 When an error occurs, it can be detected and handled using the | |
| 129 @code{try} statement as described in @ref{The try Statement}. | |
| 130 As an example, the following piece of code counts the number of errors | |
| 131 that occurs during a @code{for} loop. | |
| 132 | |
| 133 @example | |
| 134 number_of_errors = 0; | |
| 135 for n = 1:100 | |
| 136 try | |
| 137 @dots{} | |
| 138 catch | |
| 139 number_of_errors++; | |
| 140 end_try_catch | |
| 141 endfor | |
| 142 @end example | |
| 3294 | 143 |
| 6667 | 144 The above example treats all errors the same. In many situations it |
| 145 can however be necessary to discriminate between errors, and take | |
| 146 different actions depending on the error. The @code{lasterror} | |
| 147 function returns a structure containing information about the last | |
| 148 error that occurred. As an example, the code above could be changed | |
| 149 to count the number of errors related to the @samp{*} operator. | |
| 6549 | 150 |
| 6667 | 151 @example |
| 152 number_of_errors = 0; | |
| 153 for n = 1:100 | |
| 154 try | |
| 155 @dots{} | |
| 156 catch | |
| 157 msg = lasterror.message; | |
| 158 if (strfind (msg, "operator *")) | |
| 159 number_of_errors++; | |
| 160 endif | |
| 161 end_try_catch | |
| 162 endfor | |
| 163 @end example | |
| 3294 | 164 |
| 6549 | 165 @DOCSTRING(lasterror) |
| 166 | |
| 4169 | 167 @DOCSTRING(lasterr) |
| 168 | |
| 6667 | 169 When an error has been handled it is possible to raise it again. This |
| 170 can be useful when an error needs to be detected, but the program should | |
| 171 still abort. This is possible using the @code{rethrow} function. The | |
| 172 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
|
173 related to the @samp{*} operator, but still abort if another kind of |
| 6667 | 174 error occurs. |
| 175 | |
| 176 @example | |
| 177 number_of_errors = 0; | |
| 178 for n = 1:100 | |
| 179 try | |
| 180 @dots{} | |
| 181 catch | |
| 182 msg = lasterror.message; | |
| 183 if (strfind (msg, "operator *")) | |
| 184 number_of_errors++; | |
| 185 else | |
| 186 rethrow (lasterror); | |
| 187 endif | |
| 188 end_try_catch | |
| 189 endfor | |
| 190 @end example | |
| 4169 | 191 |
| 6549 | 192 @DOCSTRING(rethrow) |
| 193 | |
| 6667 | 194 @c XXX: I have no idea what the rest of the functions are used for... |
| 6549 | 195 |
| 196 @DOCSTRING(errno) | |
| 197 | |
| 198 @DOCSTRING(errno_list) | |
| 199 | |
| 6667 | 200 @node Handling Warnings |
| 201 @section Handling Warnings | |
| 202 | |
| 203 Like an error, a warning is issued when something unexpected happens. | |
| 204 Unlike an error, a warning doesn't abort the currently running program. | |
| 205 A simple example of a warning is when a number is divided by zero. In | |
| 206 this case Octave will issue a warning and assign the value @code{Inf} | |
| 207 to the result. | |
| 208 | |
| 209 @example | |
| 210 a = 1/0 | |
| 211 @print{} warning: division by zero | |
| 212 @result{} a = Inf | |
| 213 @end example | |
| 214 | |
| 215 @menu | |
| 216 * Issuing Warnings:: | |
| 217 * Enabling and Disabling Warnings:: | |
| 218 @end menu | |
| 219 | |
| 220 @node Issuing Warnings | |
| 221 @subsection Issuing Warnings | |
| 222 | |
| 223 It is possible to issue warnings from any code using the @code{warning} | |
| 224 function. In its most simple form, the @code{warning} function takes a | |
| 225 string describing the warning as its input argument. As an example, | |
| 226 the following code controls if the variable @samp{a} is non-negative, | |
| 227 and if not issues a warning and sets @samp{a} to zero. | |
| 228 | |
| 229 @example | |
| 230 a = -1; | |
| 231 if (a < 0) | |
| 7031 | 232 warning ("'a' must be non-negative. Setting 'a' to zero."); |
| 6667 | 233 a = 0; |
| 234 endif | |
| 7031 | 235 @print{} 'a' must be non-negative. Setting 'a' to zero. |
| 6667 | 236 @end example |
| 3294 | 237 |
| 6667 | 238 Since warnings aren't fatal to a running program, it is not possible |
| 239 to catch a warning using the @code{try} statement or something similar. | |
| 240 It is however possible to access the last warning as a string using the | |
| 241 @code{lastwarn} function. | |
| 242 | |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8015
diff
changeset
|
243 It is also possible to assign an identification string to a warning. |
| 6667 | 244 If a warning has such an ID the user can enable and disable this warning |
| 245 as will be described in the next section. To assign an ID to a warning, | |
| 246 simply call @code{warning} with two string arguments, where the first | |
| 247 is the identification string, and the second is the actual warning. | |
| 248 | |
| 249 @DOCSTRING(warning) | |
| 250 | |
| 251 @DOCSTRING(lastwarn) | |
| 252 | |
| 253 @node Enabling and Disabling Warnings | |
| 254 @subsection Enabling and Disabling Warnings | |
| 255 | |
| 256 The @code{warning} function also allows you to control which warnings | |
| 257 are actually printed to the screen. If the @code{warning} function | |
| 258 is called with a string argument that is either @code{"on"} or @code{"off"} | |
| 259 all warnings will be enabled or disabled. | |
| 3294 | 260 |
| 6667 | 261 It is also possible to enable and disable individual warnings through |
| 262 their string identifications. The following code will issue a warning | |
| 263 | |
| 264 @example | |
| 265 warning ("non-negative-variable", | |
| 7031 | 266 "'a' must be non-negative. Setting 'a' to zero."); |
| 6667 | 267 @end example |
| 268 | |
| 269 @noindent | |
| 270 while the following won't issue a warning | |
| 271 | |
| 272 @example | |
| 273 warning ("off", "non-negative-variable"); | |
| 274 warning ("non-negative-variable", | |
| 7031 | 275 "'a' must be non-negative. Setting 'a' to zero."); |
| 6667 | 276 @end example |
| 277 | |
| 278 The functions distributed with Octave can issue one of the following | |
| 279 warnings. | |
| 280 | |
| 281 @DOCSTRING(warning_ids) | |
| 282 | |
| 283 |