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