@c Copyright (C) 1996, 1997, 2007, 2008 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@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 ()

Invalid call to f.  Correct usage is:

     @print{}  -- Function File: f (ARG1)
     @print{}      Function help text goes here...
     @print{} 
     @print{} 
     @print{} 
     @print{} error: called from:
     @print{} error:   print_usage at line -1, column -1
     @print{} error:   /home/jwe/octave/f.m at line 7, column 5
@end example

@DOCSTRING(print_usage)

@DOCSTRING(usage)

@DOCSTRING(beep)

@DOCSTRING(beep_on_error)

@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

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.

@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)

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 if 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)

@c XXX: I have no idea what the rest of the functions are used for...

@DOCSTRING(errno)

@DOCSTRING(errno_list)

@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. Setting 'a' to zero.");
  a = 0;
endif
     @print{} 'a' must be non-negative. Setting 'a' to zero.
@end example

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 to 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.

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. 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. Setting 'a' to zero.");
@end example

The functions distributed with Octave can issue one of the following
warnings.

@DOCSTRING(warning_ids)