@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997, 2007 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 Debugging
@chapter Debugging

Octave includes a built-in debugger to aid in the development of
scripts. This can be used to interrupt the execution of an Octave script
at a certain point, or when certain conditions are met. Once execution
has stopped, and debug mode is entered, the symbol table at the point
where execution has stopped can be examined and modified to check for
errors.

The normal commandline editing and history functions are available in
debug mode. However, one limitation on the debug mode is that
commands entered at the debug prompt are evaluated as strings, rather
than being handled by the Octave parser. This means that all commands in
debug mode must be contained on a single line. That is, it is alright to
write

@example
debug> for i = 1:n, foo(i); endfor
@end example

@noindent
in debug mode. However, writing the above in three lines will not be
correctly evaluated. To leave the debug mode, you should simply type
either @code{quit}, @code{exit}, @code{return} or @code{dbcont}.

@menu
* Entering Debug Mode::
* Breakpoints::
* Debug Mode::
@end menu

@node Entering Debug Mode
@section Entering Debug Mode

There are two basic means of interrupting the execution of an Octave
script. These are breakpoints @ref{Breakpoints}, discussed in the next
section and interruption based on some condition.

Octave supports three means to stop execution based on the values set in
the functions @code{debug_on_interrupt}, @code{debug_on_warning} and
@code{debug_on_error}.

@anchor{doc-debug_on_interrupt}
@deftypefn {Built-in Function} {@var{val} =} debug_on_interrupt ()
@deftypefnx {Built-in Function} {@var{old_val} =} debug_on_interrupt (@var{new_val})
Query or set the internal variable that controls whether Octave will try
to enter debugging mode when it receives an interrupt signal (typically
generated with @kbd{C-c}).  If a second interrupt signal is received
before reaching the debugging mode, a normal interrupt will occur.
@end deftypefn


@anchor{doc-debug_on_warning}
@deftypefn {Built-in Function} {@var{val} =} debug_on_warning ()
@deftypefnx {Built-in Function} {@var{old_val} =} debug_on_warning (@var{new_val})
Query or set the internal variable that controls whether Octave will try
to enter the debugger when a warning is encountered.
@end deftypefn


@anchor{doc-debug_on_error}
@deftypefn {Built-in Function} {@var{val} =} debug_on_error ()
@deftypefnx {Built-in Function} {@var{old_val} =} debug_on_error (@var{new_val})
Query or set the internal variable that controls whether Octave will try
to enter the debugger when an error is encountered.  This will also
inhibit printing of the normal traceback message (you will only see
the top-level error message).
@end deftypefn


@node Breakpoints
@section Breakpoints

Breakpoints can be set in any Octave function, using the @code{dbstop}
function.

@anchor{doc-dbstop}
@deftypefn {Loadable Function} {rline =} dbstop (@var{func}, @var{line}, @dots{})
Set a breakpoint in a function
@table @code
@item func
String representing the function name.  When already in debug
mode this should be left out and only the line should be given.
@item line
Line you would like the breakpoint to be set on. Multiple
lines might be given as separate arguments or as a vector.
@end table

The rline returned is the real line that the breakpoint was set at.
@seealso{dbclear, dbstatus, dbnext}
@end deftypefn


@noindent
Note that breakpoints can not be set in built-in functions
(eg. @code{sin}, etc) or dynamically loaded function (ie. oct-files). To
set a breakpoint immediately on entering a function, the breakpoint
should be set to line 1. The leading comment block will be ignored and
the breakpoint will be set to the first executable statement in the
function. For example

@example
@group
dbstop ("asind", 1)
@result{} 27
@end group
@end example

@noindent
Note that the return value of @code{27} means that the breakpoint was
effectively set to line 27. The status of breakpoints in a function can
be queried with the @code{dbstatus} function.

@anchor{doc-dbstatus}
@deftypefn {Loadable Function} {lst =} dbstatus (@var{func})
Return a vector containing the lines on which a function has 
breakpoints set.
@table @code
@item func
String representing the function name.  When already in debug
mode this should be left out.
@end table
@seealso{dbclear, dbwhere}
@end deftypefn


@noindent
Taking the above as an example, @code{dbstatus ("asind")} should return
27. The breakpoints can then be cleared with the @code{dbclear} function

@anchor{doc-dbclear}
@deftypefn {Loadable Function} {} dbclear (@var{func}, @var{line}, @dots{})
Delete a breakpoint in a function
@table @code
@item func
String representing the function name.  When already in debug
mode this should be left out and only the line should be given.
@item line
Line where you would like to remove the breakpoint. Multiple
lines might be given as separate arguments or as a vector.
@end table
No checking is done to make sure that the line you requested is really
a breakpoint. If you get the wrong line nothing will happen.
@seealso{dbstop, dbstatus, dbwhere}
@end deftypefn


@noindent
To clear all of the breakpoints in a function the recommended means,
following the above example, is then

@example
dbclear ("asind", dbstatus ("asind"));
@end example

Another simple means of setting a breakpoint in an Octave script is the
use of the @code{keyboard} function.

@anchor{doc-keyboard}
@deftypefn {Built-in Function} {} keyboard (@var{prompt})
This function is normally used for simple debugging.  When the
@code{keyboard} function is executed, Octave prints a prompt and waits
for user input.  The input strings are then evaluated and the results
are printed.  This makes it possible to examine the values of variables
within a function, and to assign new values to variables.  No value is
returned from the @code{keyboard} function, and it continues to prompt
for input until the user types @samp{quit}, or @samp{exit}.

If @code{keyboard} is invoked without any arguments, a default prompt of
@samp{debug> } is used.
@end deftypefn


@noindent
The @code{keyboard} function is typically placed in a script at the
point where the user desires that the execution is stopped. It
automatically sets the running script into the debug mode.

@node Debug Mode
@section Debug Mode

There are two additional support functions that allow the user to
interrogate where in the execution of a script Octave entered the debug
mode and to print the code in the script surrounding the point where
Octave entered debug mode.

@anchor{doc-dbwhere}
@deftypefn {Loadable Function} {} dbwhere ()
Show where we are in the code
@seealso{dbclear, dbstatus, dbstop}
@end deftypefn


@anchor{doc-dbtype}
@deftypefn {Loadable Function} {} dbtype ()
List script file with line numbers.
@seealso{dbclear, dbstatus, dbstop}
@end deftypefn


Debug mode equally allows single line stepping through a function using
the commands @code{dbstep} and @code{dbnext}.  These differ slightly in
the way they treat the next executable line if the next line itself is a
function defined in an m-file.  The @code{dbnext} command will execute
the next line, while staying in the existing function being debugged.
The @code{dbstep} command will step in to the new function.
