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