Mercurial > octave-nkf
changeset 6667:a36e4bb26943
[project @ 2007-05-28 06:20:12 by jwe]
| author | jwe |
|---|---|
| date | Mon, 28 May 2007 06:20:13 +0000 |
| parents | 5d4ce539004f |
| children | 69197bd681f6 |
| files | doc/ChangeLog doc/interpreter/errors.txi doc/interpreter/octave.texi doc/interpreter/stmt.txi doc/interpreter/var.txi |
| diffstat | 5 files changed, 248 insertions(+), 15 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog Mon May 28 06:07:39 2007 +0000 +++ b/doc/ChangeLog Mon May 28 06:20:13 2007 +0000 @@ -1,3 +1,11 @@ +2007-05-28 Søren Hauberg <hauberg@gmail.com> + + * interpreter/errors.txi: Add new sections and some more detailed + descriptions on errors and warnings. + * interpreter/octave.texi, interpreter/stmt.txi, + interpreter/var.txi: Add references to the new sections in + errors.txi. + 2007-05-28 Søren Hauberg <hauberg@gmail.com> * interpreter/io.txi: Rearrange some sections, and add
--- a/doc/interpreter/errors.txi Mon May 28 06:07:39 2007 +0000 +++ b/doc/interpreter/errors.txi Mon May 28 06:20:13 2007 +0000 @@ -2,43 +2,265 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Error Handling -@chapter Error Handling +@node Errors and Warnings +@chapter Errors and Warnings Octave includes several functions for printing error and warning messages. When you write functions that need to take special action when they encounter abnormal conditions, you should print the error messages using the functions described in this chapter. +Since many of Octave's functions use these functions, it is also useful +to understand them, so that errors and warnings can be handled. + +@menu +* Handling Errors:: +* Handling Warnings:: +@end menu + +@node Handling Errors +@section Handling Errors + +An error is something that occurs when a program is in a state where +it doesn't make sense to continue. An example is when a function is +called with too few input arguments. In this situation the function +should abort with an error message informing the user of the lacking +input arguments. + +Since an error can occur during the evaluation of a program, it is +very convenient to be able to detect that an error occurred, so that +the error can be fixed. This is possible with the @code{try} statement +described in @ref{The try Statement}. + +@menu +* Raising Errors:: +* Catching Errors:: +@end menu + +@node Raising Errors +@subsection Raising Errors + +The most common use of errors is for checking input arguments to +functions. The following example calls the @code{error} function if +the function @code{f} is called without any input arguments. + +@example +function f (arg1) + if (nargin == 0) + error("not enough input arguments"); + endif +endfunction +@end example + +When the @code{error} function is called, it prints the given message +and returns to the Octave prompt. This means that no code following +a call to @code{error} will be executed. + @DOCSTRING(error) +Since it is common to use errors when there is something wrong with +the input to a function, Octave supports functions to simplify such code. +When the @code{print_usage} function is called, it reads the help text +of the function calling @code{print_usage}, and presents a useful error. +If the help text is written in Texinfo it is possible to present an +error message that only contains the function prototypes as described +by the @code{@@deftypefn} parts of the help text. When the help text +isn't written in Texinfo, the error message contains the entire help +message. + +Consider the following function. +@example +## -*- texinfo -*- +## @@deftypefn @{Function File@} f (@@var@{arg1@}) +## Function help text goes here@dots{} +## @@end deftypefn +function f (arg1) + if (nargin == 0) + print_usage (); + endif +endfunction +@end example + +@noindent +When it is called with no input arguments it produces the following +error. + +@example +f () + @print{} Invalid call to f. Correct usage is: + @print{} + @print{} -- Function File: f (ARG1) + @print{} + @print{} + @print{} + @print{} error: evaluating if command near line 6, column 3 + @print{} error: called from `f' in file `/home/jwe/octave/f.m' +@end example + +@DOCSTRING(print_usage) + +@DOCSTRING(usage) + @DOCSTRING(beep) @DOCSTRING(beep_on_error) -@DOCSTRING(warning) +@node Catching Errors +@subsection Catching Errors + +When an error occurs, it can be detected and handled using the +@code{try} statement as described in @ref{The try Statement}. +As an example, the following piece of code counts the number of errors +that occurs during a @code{for} loop. + +@example +number_of_errors = 0; +for n = 1:100 + try + @dots{} + catch + number_of_errors++; + end_try_catch +endfor +@end example -@DOCSTRING(print_usage) +The above example treats all errors the same. In many situations it +can however be necessary to discriminate between errors, and take +different actions depending on the error. The @code{lasterror} +function returns a structure containing information about the last +error that occurred. As an example, the code above could be changed +to count the number of errors related to the @samp{*} operator. -@DOCSTRING(usage) +@example +number_of_errors = 0; +for n = 1:100 + try + @dots{} + catch + msg = lasterror.message; + if (strfind (msg, "operator *")) + number_of_errors++; + endif + end_try_catch +endfor +@end example @DOCSTRING(lasterror) @DOCSTRING(lasterr) -@DOCSTRING(lastwarn) +When an error has been handled it is possible to raise it again. This +can be useful when an error needs to be detected, but the program should +still abort. This is possible using the @code{rethrow} function. The +previous example can now be changed to count the number of errors +related to the @samp{*} operator, but still abort of another kind of +error occurs. + +@example +number_of_errors = 0; +for n = 1:100 + try + @dots{} + catch + msg = lasterror.message; + if (strfind (msg, "operator *")) + number_of_errors++; + else + rethrow (lasterror); + endif + end_try_catch +endfor +@end example @DOCSTRING(rethrow) -@DOCSTRING(warning_ids) +@c XXX: I have no idea what the rest of the functions are used for... @DOCSTRING(errno) @DOCSTRING(errno_list) -The following pair of functions are of limited usefulness, and may be -removed from future versions of Octave. +@node Handling Warnings +@section Handling Warnings + +Like an error, a warning is issued when something unexpected happens. +Unlike an error, a warning doesn't abort the currently running program. +A simple example of a warning is when a number is divided by zero. In +this case Octave will issue a warning and assign the value @code{Inf} +to the result. + +@example +a = 1/0 + @print{} warning: division by zero + @result{} a = Inf +@end example + +@menu +* Issuing Warnings:: +* Enabling and Disabling Warnings:: +@end menu + +@node Issuing Warnings +@subsection Issuing Warnings + +It is possible to issue warnings from any code using the @code{warning} +function. In its most simple form, the @code{warning} function takes a +string describing the warning as its input argument. As an example, +the following code controls if the variable @samp{a} is non-negative, +and if not issues a warning and sets @samp{a} to zero. + +@example +a = -1; +if (a < 0) + warning ("'a' must be non-negative number. Setting 'a' to zero."); + a = 0; +endif + @print{} 'a' must be non-negative number. Setting 'a' to zero. +@end example -@DOCSTRING(perror) +Since warnings aren't fatal to a running program, it is not possible +to catch a warning using the @code{try} statement or something similar. +It is however possible to access the last warning as a string using the +@code{lastwarn} function. + +It is also possible to assign an identification string a a warning. +If a warning has such an ID the user can enable and disable this warning +as will be described in the next section. To assign an ID to a warning, +simply call @code{warning} with two string arguments, where the first +is the identification string, and the second is the actual warning. + +@DOCSTRING(warning) + +@DOCSTRING(lastwarn) + +@node Enabling and Disabling Warnings +@subsection Enabling and Disabling Warnings + +The @code{warning} function also allows you to control which warnings +are actually printed to the screen. If the @code{warning} function +is called with a string argument that is either @code{"on"} or @code{"off"} +all warnings will be enabled or disabled. -@DOCSTRING(strerror) +It is also possible to enable and disable individual warnings through +their string identifications. The following code will issue a warning + +@example +warning ("non-negative-variable", + "'a' must be non-negative number. Setting 'a' to zero."); +@end example + +@noindent +while the following won't issue a warning + +@example +warning ("off", "non-negative-variable"); +warning ("non-negative-variable", + "'a' must be non-negative number. Setting 'a' to zero."); +@end example + +The functions distributed with Octave can issue one of the following +warnings. + +@DOCSTRING(warning_ids) + +
--- a/doc/interpreter/octave.texi Mon May 28 06:07:39 2007 +0000 +++ b/doc/interpreter/octave.texi Mon May 28 06:20:13 2007 +0000 @@ -139,7 +139,7 @@ * Evaluation:: * Statements:: Looping and program flow control. * Functions and Scripts:: -* Error Handling:: +* Errors and Warnings:: * Debugging:: * Input and Output:: * Plotting:: @@ -329,7 +329,10 @@ * Script Files:: * Organization of Functions:: -Error Handling +Errors and Warnings + +* Handling Errors:: +* Handling Warnings:: Debugging
--- a/doc/interpreter/stmt.txi Mon May 28 06:07:39 2007 +0000 +++ b/doc/interpreter/stmt.txi Mon May 28 06:20:13 2007 +0000 @@ -820,7 +820,7 @@ of the message that would have been printed. This is the same as @code{eval (@var{try}, @var{catch})} but it is more efficient since the commands do not need to be parsed each time the @var{try} and -@var{catch} statements are evaluated. @xref{Error Handling}, for more +@var{catch} statements are evaluated. @xref{Errors and Warnings}, for more information about the @code{lasterr} function. @cindex continuation lines