Re: debug breakpoint commands want line numbers as strings!!

[David Bateman]

David Bateman wrote:
> Is there any reason why the debug commands require that the line numbers
> for breakpoints are set as strings? It seems that it makes more sense
> that these are integers or matrices instead. It also means that reseting
> all breakpoints in a function can't be written as
> 
> dbclear ("foo", dbstatus ("foo"))
> 
> which would make a lot of sense to me.. what about the attached patch?
> The above code then works, and it even keeps backward compatibility.
> 
> D.


If this patch is accepted, then you might also consider the attached
patch to debug.txi, that gives a bit of additional documentation and
explanation of the uses and limitations of the debugging functionality
of Octave. However, as the version of this documentation patch makes the
assumption that the previous patch is applied, it shouldn't be
considered separately..

D.

Index: doc/interpreter/debug.txi
===================================================================
RCS file: /usr/local/cvsroot/octave/doc/interpreter/debug.txi,v
retrieving revision 1.2
diff -u -r1.2 debug.txi
--- doc/interpreter/debug.txi   15 Nov 2002 23:22:27 -0000      1.2
+++ doc/interpreter/debug.txi   22 May 2007 00:54:22 -0000
@@ -5,18 +5,114 @@
 @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
+
address@hidden
+debug> for i = 1:n, foo(i); endfor
address@hidden example
+
address@hidden
+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} or @code{exit}.
+
address@hidden
+* Entering Debug Mode::
+* Breakpoints::
+* Debug Mode::
address@hidden menu
+
address@hidden Entering Debug Mode
address@hidden 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
address@hidden
+
address@hidden(debug_on_interrupt)
+
address@hidden(debug_on_warning)
+
address@hidden(debug_on_error)
+
address@hidden Breakpoints
address@hidden Breakpoints
+
+Breakpoints can be set in any Octave function, using the @code{dbstop}
+function.
+
 @DOCSTRING(dbstop)
 
address@hidden(dbclear)
address@hidden
+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
+
address@hidden
address@hidden
+dbstop ("asind", 1)
address@hidden 27
address@hidden group
address@hidden example
+
address@hidden
+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.
 
 @DOCSTRING(dbstatus)
 
address@hidden(dbwhere)
address@hidden
+Taking the above as an example, @code{dbstatus ("asind")} should return
+27. The breakpoints can then be cleared with the @code{dbclear} function
 
address@hidden(dbtype)
address@hidden(dbclear)
 
address@hidden(debug_on_interrupt)
address@hidden
+To clear all of the breakpoints in a function the recommended means,
+following the above example, is then
+
address@hidden
+dbclear ("asind", dbstatus ("asind"));
address@hidden example
+
+Another simple means of setting a breakpoint in an Octave script is the
+use of the @code{keyboard} function.
+
address@hidden(keyboard)
+
address@hidden
+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.
+
address@hidden Debug Mode
address@hidden 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.
 
address@hidden(debug_on_warning)
address@hidden(dbwhere)
 
address@hidden(debug_on_error)
address@hidden(dbtype)
Index: doc/interpreter/io.txi
===================================================================
RCS file: /usr/local/cvsroot/octave/doc/interpreter/io.txi,v
retrieving revision 1.19
diff -u -r1.19 io.txi
--- doc/interpreter/io.txi      20 Apr 2007 18:39:40 -0000      1.19
+++ doc/interpreter/io.txi      22 May 2007 00:54:22 -0000
@@ -101,10 +101,8 @@
 
 @DOCSTRING(menu)
 
address@hidden(keyboard)
-
-For both @code{input} and @code{keyboard}, the normal command line
-history and editing functions are available at the prompt.
+For @code{input}, the normal command line history and editing functions
+are available at the prompt.
 
 Octave also has a function that makes it possible to get a single
 character from the keyboard without requiring the user to type a
Index: doc/interpreter/octave.texi
===================================================================
RCS file: /usr/local/cvsroot/octave/doc/interpreter/octave.texi,v
retrieving revision 1.54
diff -u -r1.54 octave.texi
--- doc/interpreter/octave.texi 15 May 2007 20:17:27 -0000      1.54
+++ doc/interpreter/octave.texi 22 May 2007 00:54:22 -0000
@@ -333,6 +333,10 @@
 
 Debugging
 
+* Entering Debug Mode::
+* Breakpoints::
+* Debug Mode::
+
 Input and Output
 
 * Basic Input and Output::