Mercurial > hg > octave-nkf
annotate doc/interpreter/errors.txi @ 14856:c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
* OctaveFAQ.texi, basics.txi, container.txi, contrib.txi, diagperm.txi,
diffeq.txi, dynamic.txi, errors.txi, eval.txi, expr.txi, func.txi,
geometry.txi, interp.txi, intro.txi, numbers.txi, oop.txi, plot.txi, poly.txi,
quad.txi, set.txi, sparse.txi, stmt.txi, testfun.txi, vectorize.txi,
refcard.tex: Use Octave coding conventions for cuddling parentheses.
| author | Rik <octave@nomad.inbox5.com> |
|---|---|
| date | Mon, 09 Jul 2012 17:00:46 -0700 |
| parents | 72c96de7a403 |
| children | ae43fc2ddcac |
| rev | line source |
|---|---|
|
14138
72c96de7a403
maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents:
12560
diff
changeset
|
1 @c Copyright (C) 1996-2012 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:: | |
|
12560
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
52 * Recovering From Errors:: |
| 6667 | 53 @end menu |
| 54 | |
| 55 @node Raising Errors | |
| 56 @subsection Raising Errors | |
| 57 | |
| 58 The most common use of errors is for checking input arguments to | |
| 59 functions. The following example calls the @code{error} function if | |
| 60 the function @code{f} is called without any input arguments. | |
| 61 | |
| 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 | 64 function f (arg1) |
| 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 | 67 endif |
| 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 | 70 @end example |
| 71 | |
| 72 When the @code{error} function is called, it prints the given message | |
| 73 and returns to the Octave prompt. This means that no code following | |
| 74 a call to @code{error} will be executed. | |
| 75 | |
| 3373 | 76 @DOCSTRING(error) |
| 3294 | 77 |
| 6667 | 78 Since it is common to use errors when there is something wrong with |
| 79 the input to a function, Octave supports functions to simplify such code. | |
| 80 When the @code{print_usage} function is called, it reads the help text | |
| 81 of the function calling @code{print_usage}, and presents a useful error. | |
| 82 If the help text is written in Texinfo it is possible to present an | |
| 83 error message that only contains the function prototypes as described | |
| 84 by the @code{@@deftypefn} parts of the help text. When the help text | |
| 85 isn't written in Texinfo, the error message contains the entire help | |
| 86 message. | |
| 87 | |
| 88 Consider the following function. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
9293
diff
changeset
|
89 |
| 6667 | 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 | 92 ## -*- texinfo -*- |
| 93 ## @@deftypefn @{Function File@} f (@@var@{arg1@}) | |
| 94 ## Function help text goes here@dots{} | |
| 95 ## @@end deftypefn | |
| 96 function f (arg1) | |
| 97 if (nargin == 0) | |
| 98 print_usage (); | |
| 99 endif | |
| 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 | 102 @end example |
| 103 | |
| 104 @noindent | |
| 105 When it is called with no input arguments it produces the following | |
| 106 error. | |
| 107 | |
| 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 | 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: |
|
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{} -- 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
|
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{} |
|
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 |
|
d371cb65428a
Fix output from 'print_usage' in Errors chapter in the manual
Soren Hauberg <hauberg@gmail.com>
parents:
9245
diff
changeset
|
118 @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
|
119 @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
|
120 @print{} |
|
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 | 125 @end example |
| 126 | |
| 127 @DOCSTRING(print_usage) | |
| 128 | |
| 129 @DOCSTRING(usage) | |
| 130 | |
| 6551 | 131 @DOCSTRING(beep) |
| 132 | |
| 3373 | 133 @DOCSTRING(beep_on_error) |
| 3294 | 134 |
| 6667 | 135 @node Catching Errors |
| 136 @subsection Catching Errors | |
| 137 | |
| 138 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
|
139 @code{try} statement as described in @ref{The @code{try} Statement}. |
| 6667 | 140 As an example, the following piece of code counts the number of errors |
| 141 that occurs during a @code{for} loop. | |
| 142 | |
| 143 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
144 @group |
| 6667 | 145 number_of_errors = 0; |
| 146 for n = 1:100 | |
| 147 try | |
| 148 @dots{} | |
| 149 catch | |
| 150 number_of_errors++; | |
| 151 end_try_catch | |
| 152 endfor | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
153 @end group |
| 6667 | 154 @end example |
| 3294 | 155 |
| 6667 | 156 The above example treats all errors the same. In many situations it |
| 157 can however be necessary to discriminate between errors, and take | |
| 158 different actions depending on the error. The @code{lasterror} | |
| 159 function returns a structure containing information about the last | |
| 160 error that occurred. As an example, the code above could be changed | |
| 161 to count the number of errors related to the @samp{*} operator. | |
| 6549 | 162 |
| 6667 | 163 @example |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
164 @group |
| 6667 | 165 number_of_errors = 0; |
| 166 for n = 1:100 | |
| 167 try | |
| 168 @dots{} | |
| 169 catch | |
| 170 msg = lasterror.message; | |
| 171 if (strfind (msg, "operator *")) | |
| 172 number_of_errors++; | |
| 173 endif | |
| 174 end_try_catch | |
| 175 endfor | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
176 @end group |
| 6667 | 177 @end example |
| 3294 | 178 |
| 6549 | 179 @DOCSTRING(lasterror) |
| 180 | |
| 4169 | 181 @DOCSTRING(lasterr) |
| 182 | |
| 6667 | 183 When an error has been handled it is possible to raise it again. This |
| 184 can be useful when an error needs to be detected, but the program should | |
| 185 still abort. This is possible using the @code{rethrow} function. The | |
| 186 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
|
187 related to the @samp{*} operator, but still abort if another kind of |
| 6667 | 188 error occurs. |
| 189 | |
| 190 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
191 @group |
| 6667 | 192 number_of_errors = 0; |
| 193 for n = 1:100 | |
| 194 try | |
| 195 @dots{} | |
| 196 catch | |
| 197 msg = lasterror.message; | |
| 198 if (strfind (msg, "operator *")) | |
| 199 number_of_errors++; | |
| 200 else | |
| 201 rethrow (lasterror); | |
| 202 endif | |
| 203 end_try_catch | |
| 204 endfor | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
205 @end group |
| 6667 | 206 @end example |
| 4169 | 207 |
| 6549 | 208 @DOCSTRING(rethrow) |
| 209 | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
210 @c FIXME: I have no idea what the rest of the functions are used for... |
| 6549 | 211 |
| 212 @DOCSTRING(errno) | |
| 213 | |
| 214 @DOCSTRING(errno_list) | |
| 215 | |
|
12560
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
216 @node Recovering From Errors |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
217 @subsection Recovering From Errors |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
218 |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
219 Octave provides several ways of recovering from errors. There are |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
220 @code{try}/@code{catch} blocks, |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
221 @code{unwind_protect}/@code{unwind_protect_cleanup} blocks, |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
222 and finally the @code{onCleanup} command. |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
223 |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
224 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
|
225 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
|
226 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
|
227 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
|
228 is executed. |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
229 |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
230 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
|
231 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
|
232 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
|
233 For example: |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
234 |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
235 @example |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
236 @group |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
237 function rand42 |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
238 old_state = rand ('state'); |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
239 restore_state = onCleanup (@@() rand ('state', old_state); |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
240 rand ('state', 42); |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
241 @dots{} |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
242 endfunction # rand generator state restored by onCleanup |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
243 @end group |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
244 @end example |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
245 |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
246 @DOCSTRING(onCleanup) |
|
d6ad4ed57dda
Add onCleanup function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
247 |
| 6667 | 248 @node Handling Warnings |
| 249 @section Handling Warnings | |
| 250 | |
| 251 Like an error, a warning is issued when something unexpected happens. | |
| 252 Unlike an error, a warning doesn't abort the currently running program. | |
| 253 A simple example of a warning is when a number is divided by zero. In | |
| 254 this case Octave will issue a warning and assign the value @code{Inf} | |
| 255 to the result. | |
| 256 | |
| 257 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
258 @group |
| 6667 | 259 a = 1/0 |
| 260 @print{} warning: division by zero | |
| 261 @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
|
262 @end group |
| 6667 | 263 @end example |
| 264 | |
| 265 @menu | |
| 266 * Issuing Warnings:: | |
| 267 * Enabling and Disabling Warnings:: | |
| 268 @end menu | |
| 269 | |
| 270 @node Issuing Warnings | |
| 271 @subsection Issuing Warnings | |
| 272 | |
| 273 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
|
274 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
|
275 string describing the warning as its input argument. As an example, |
| 6667 | 276 the following code controls if the variable @samp{a} is non-negative, |
| 277 and if not issues a warning and sets @samp{a} to zero. | |
| 278 | |
| 279 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
280 @group |
| 6667 | 281 a = -1; |
| 282 if (a < 0) | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
283 warning ("'a' must be non-negative. Setting 'a' to zero."); |
| 6667 | 284 a = 0; |
| 285 endif | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
286 @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
|
287 @end group |
| 6667 | 288 @end example |
| 3294 | 289 |
| 6667 | 290 Since warnings aren't fatal to a running program, it is not possible |
| 291 to catch a warning using the @code{try} statement or something similar. | |
| 292 It is however possible to access the last warning as a string using the | |
| 293 @code{lastwarn} function. | |
| 294 | |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8015
diff
changeset
|
295 It is also possible to assign an identification string to a warning. |
| 6667 | 296 If a warning has such an ID the user can enable and disable this warning |
| 297 as will be described in the next section. To assign an ID to a warning, | |
| 298 simply call @code{warning} with two string arguments, where the first | |
| 299 is the identification string, and the second is the actual warning. | |
| 300 | |
| 301 @DOCSTRING(warning) | |
| 302 | |
| 303 @DOCSTRING(lastwarn) | |
| 304 | |
| 305 @node Enabling and Disabling Warnings | |
| 306 @subsection Enabling and Disabling Warnings | |
| 307 | |
| 308 The @code{warning} function also allows you to control which warnings | |
| 309 are actually printed to the screen. If the @code{warning} function | |
| 310 is called with a string argument that is either @code{"on"} or @code{"off"} | |
| 311 all warnings will be enabled or disabled. | |
| 3294 | 312 |
| 6667 | 313 It is also possible to enable and disable individual warnings through |
| 314 their string identifications. The following code will issue a warning | |
| 315 | |
| 316 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9039
diff
changeset
|
317 @group |
| 6667 | 318 warning ("non-negative-variable", |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
319 "'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
|
320 @end group |
| 6667 | 321 @end example |
| 322 | |
| 323 @noindent | |
| 324 while the following won't issue a warning | |
| 325 | |
| 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 | 328 warning ("off", "non-negative-variable"); |
| 329 warning ("non-negative-variable", | |
|
9039
51dc9691f23f
Cleanup documentation files errors.texi, debug.texi, io.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
330 "'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
|
331 @end group |
| 6667 | 332 @end example |
| 333 | |
| 334 The functions distributed with Octave can issue one of the following | |
| 335 warnings. | |
| 336 | |
| 337 @DOCSTRING(warning_ids) | |
| 338 | |
| 339 |