|
6778
|
1 @c Copyright (C) 1996, 1997, 2007 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 () |
|
|
104 @print{} Invalid call to f. Correct usage is: |
|
|
105 @print{} |
|
|
106 @print{} -- Function File: f (ARG1) |
|
|
107 @print{} |
|
|
108 @print{} |
|
|
109 @print{} |
|
|
110 @print{} error: evaluating if command near line 6, column 3 |
|
|
111 @print{} error: called from `f' in file `/home/jwe/octave/f.m' |
|
|
112 @end example |
|
|
113 |
|
|
114 @DOCSTRING(print_usage) |
|
|
115 |
|
|
116 @DOCSTRING(usage) |
|
|
117 |
|
6551
|
118 @DOCSTRING(beep) |
|
|
119 |
|
3373
|
120 @DOCSTRING(beep_on_error) |
|
3294
|
121 |
|
6667
|
122 @node Catching Errors |
|
|
123 @subsection Catching Errors |
|
|
124 |
|
|
125 When an error occurs, it can be detected and handled using the |
|
|
126 @code{try} statement as described in @ref{The try Statement}. |
|
|
127 As an example, the following piece of code counts the number of errors |
|
|
128 that occurs during a @code{for} loop. |
|
|
129 |
|
|
130 @example |
|
|
131 number_of_errors = 0; |
|
|
132 for n = 1:100 |
|
|
133 try |
|
|
134 @dots{} |
|
|
135 catch |
|
|
136 number_of_errors++; |
|
|
137 end_try_catch |
|
|
138 endfor |
|
|
139 @end example |
|
3294
|
140 |
|
6667
|
141 The above example treats all errors the same. In many situations it |
|
|
142 can however be necessary to discriminate between errors, and take |
|
|
143 different actions depending on the error. The @code{lasterror} |
|
|
144 function returns a structure containing information about the last |
|
|
145 error that occurred. As an example, the code above could be changed |
|
|
146 to count the number of errors related to the @samp{*} operator. |
|
6549
|
147 |
|
6667
|
148 @example |
|
|
149 number_of_errors = 0; |
|
|
150 for n = 1:100 |
|
|
151 try |
|
|
152 @dots{} |
|
|
153 catch |
|
|
154 msg = lasterror.message; |
|
|
155 if (strfind (msg, "operator *")) |
|
|
156 number_of_errors++; |
|
|
157 endif |
|
|
158 end_try_catch |
|
|
159 endfor |
|
|
160 @end example |
|
3294
|
161 |
|
6549
|
162 @DOCSTRING(lasterror) |
|
|
163 |
|
4169
|
164 @DOCSTRING(lasterr) |
|
|
165 |
|
6667
|
166 When an error has been handled it is possible to raise it again. This |
|
|
167 can be useful when an error needs to be detected, but the program should |
|
|
168 still abort. This is possible using the @code{rethrow} function. The |
|
|
169 previous example can now be changed to count the number of errors |
|
|
170 related to the @samp{*} operator, but still abort of another kind of |
|
|
171 error occurs. |
|
|
172 |
|
|
173 @example |
|
|
174 number_of_errors = 0; |
|
|
175 for n = 1:100 |
|
|
176 try |
|
|
177 @dots{} |
|
|
178 catch |
|
|
179 msg = lasterror.message; |
|
|
180 if (strfind (msg, "operator *")) |
|
|
181 number_of_errors++; |
|
|
182 else |
|
|
183 rethrow (lasterror); |
|
|
184 endif |
|
|
185 end_try_catch |
|
|
186 endfor |
|
|
187 @end example |
|
4169
|
188 |
|
6549
|
189 @DOCSTRING(rethrow) |
|
|
190 |
|
6667
|
191 @c XXX: I have no idea what the rest of the functions are used for... |
|
6549
|
192 |
|
|
193 @DOCSTRING(errno) |
|
|
194 |
|
|
195 @DOCSTRING(errno_list) |
|
|
196 |
|
6667
|
197 @node Handling Warnings |
|
|
198 @section Handling Warnings |
|
|
199 |
|
|
200 Like an error, a warning is issued when something unexpected happens. |
|
|
201 Unlike an error, a warning doesn't abort the currently running program. |
|
|
202 A simple example of a warning is when a number is divided by zero. In |
|
|
203 this case Octave will issue a warning and assign the value @code{Inf} |
|
|
204 to the result. |
|
|
205 |
|
|
206 @example |
|
|
207 a = 1/0 |
|
|
208 @print{} warning: division by zero |
|
|
209 @result{} a = Inf |
|
|
210 @end example |
|
|
211 |
|
|
212 @menu |
|
|
213 * Issuing Warnings:: |
|
|
214 * Enabling and Disabling Warnings:: |
|
|
215 @end menu |
|
|
216 |
|
|
217 @node Issuing Warnings |
|
|
218 @subsection Issuing Warnings |
|
|
219 |
|
|
220 It is possible to issue warnings from any code using the @code{warning} |
|
|
221 function. In its most simple form, the @code{warning} function takes a |
|
|
222 string describing the warning as its input argument. As an example, |
|
|
223 the following code controls if the variable @samp{a} is non-negative, |
|
|
224 and if not issues a warning and sets @samp{a} to zero. |
|
|
225 |
|
|
226 @example |
|
|
227 a = -1; |
|
|
228 if (a < 0) |
|
|
229 warning ("'a' must be non-negative number. Setting 'a' to zero."); |
|
|
230 a = 0; |
|
|
231 endif |
|
|
232 @print{} 'a' must be non-negative number. Setting 'a' to zero. |
|
|
233 @end example |
|
3294
|
234 |
|
6667
|
235 Since warnings aren't fatal to a running program, it is not possible |
|
|
236 to catch a warning using the @code{try} statement or something similar. |
|
|
237 It is however possible to access the last warning as a string using the |
|
|
238 @code{lastwarn} function. |
|
|
239 |
|
|
240 It is also possible to assign an identification string a a warning. |
|
|
241 If a warning has such an ID the user can enable and disable this warning |
|
|
242 as will be described in the next section. To assign an ID to a warning, |
|
|
243 simply call @code{warning} with two string arguments, where the first |
|
|
244 is the identification string, and the second is the actual warning. |
|
|
245 |
|
|
246 @DOCSTRING(warning) |
|
|
247 |
|
|
248 @DOCSTRING(lastwarn) |
|
|
249 |
|
|
250 @node Enabling and Disabling Warnings |
|
|
251 @subsection Enabling and Disabling Warnings |
|
|
252 |
|
|
253 The @code{warning} function also allows you to control which warnings |
|
|
254 are actually printed to the screen. If the @code{warning} function |
|
|
255 is called with a string argument that is either @code{"on"} or @code{"off"} |
|
|
256 all warnings will be enabled or disabled. |
|
3294
|
257 |
|
6667
|
258 It is also possible to enable and disable individual warnings through |
|
|
259 their string identifications. The following code will issue a warning |
|
|
260 |
|
|
261 @example |
|
|
262 warning ("non-negative-variable", |
|
|
263 "'a' must be non-negative number. Setting 'a' to zero."); |
|
|
264 @end example |
|
|
265 |
|
|
266 @noindent |
|
|
267 while the following won't issue a warning |
|
|
268 |
|
|
269 @example |
|
|
270 warning ("off", "non-negative-variable"); |
|
|
271 warning ("non-negative-variable", |
|
|
272 "'a' must be non-negative number. Setting 'a' to zero."); |
|
|
273 @end example |
|
|
274 |
|
|
275 The functions distributed with Octave can issue one of the following |
|
|
276 warnings. |
|
|
277 |
|
|
278 @DOCSTRING(warning_ids) |
|
|
279 |
|
|
280 |
