Debugging Macros

Here are a few techniques that can prove helpful in debugging
macros.

Identifying Exceptions

An exception is a condition reflecting
an error or other unusual result of program execution that requires
interruption of normal program flow and some kind of special
handling. Java has a rich (and extensible) collection of exception
classes which represent such conditions.

jEdit catches exceptions thrown by BeanShell scripts and
displays them in a dialog box. In addition, the full traceback is
written to the activity log (see Appendix B, The Activity Log for
more information about the activity log).

There are two broad categories of errors that will result in
exceptions:

Interpreter errors, which may
arise from typing mistakes like mismatched brackets or
missing semicolons, or from BeanShell's failure to find a
class corresponding to a particular variable.

Interpreter errors are usually accompanied by the line
number in the script, along with the cause of the
error.

Execution errors, which result
from runtime exceptions thrown by the Java platform when
macro code is executed.

Some exceptions thrown by the Java platform can often
seem cryptic. Nevertheless, examining the contents of the
activity log may reveals clues as to the cause of the
error.

Using the Activity Log as a Tracing Tool

Sometimes exception tracebacks will say what kind of error
occurred but not where it arose in the script. In those cases, you
can insert calls that log messages to the activity log in your
macro. If the logged messages appear when the macro is run, it means
that up to that point the macro is fine; but if an exception is
logged first, it means the logging call is located after the cause
of the error.

To write a message to the activity log, use the following
method of the Log class:

public static void
log(

int
urgency,

Object
source,

Object
message);

See the documentation for the Log class for
information about the method's parameters.

The following code sends a typical debugging message to the
activity log:

Log.log(Log.DEBUG, BeanShell.class, "counter = " + counter);

The corresponding activity log entry might read as
follows:

[debug] BeanShell: counter = 15

Using message dialog boxes as a tracing tool

If you would prefer not having to deal with the activity
log, you can use the Macros.message()
method as a tracing tool. Just insert calls like the following
in the macro code:

Macros.message(view,"tracing");

Execution of the macro is halted until the message dialog
box is closed. When you have finished debugging the macro, you
should delete or comment out the debugging calls to
Macros.message() in your final source
code.