# $debug(5)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

## NAME

$debug - Macro debugging flag

## SYNOPSIS

$debug debugLevel; Default is `0`

-3 <= debugLevel <= 3

## DESCRIPTION

$debug is used to control macro debugging, it is a bit based flag where:

`0x01`

Displays an error message when an un-handled exception is encountered, this is useful to locate problems in the macro code i.e. missing arguments etc. This setting may be used in normal running and macro execution is halted when an error is encountered, it is non-intrusive up until the point of failure. Enabling slightly slows execution but is not typically noticeable on modern processors.

`0x02`

Setting this bit enables the macro debugger. With macro debugging enabled, before a line of macro code is executed the line and its location is first print on the message line with a prompt allowing the user to view variables, abort execution, dive into sub macros etc. The behaviour of the macro debugger can be altered by bits `0x04` and `0x08`.

`0x04`

When set all macro lines encountered are printed. When this bit is not set only the lines of code that are executed are printed, i.e. if a false !if was encountered the lines within the !if would not be printed. Problems arise with !elif and !else lines and this bit is not set as the !elif and !else lines are never printed.

`0x08`

When set the debug prompt is disabled so the macro line is printed on the message line and then immediately executed. This allows the user to see the execution flow of the macro code while still executing the code at a reasonable pace.

`0x10`

Setting this bit has no immediate effect. However as soon as the key bound to abort-command(2) (typically "`C-g`") is pressed the macro debugger is enabled, i.e. bit `0x02` is set. This can be invaluable when tracing problems, for example the following macro code will loop infinitely:-

    !repeat
        beginning-of-line
        backward-char
        !force forward-line
    !until &not $status

This is a fairly obvious bug, but if buried in a thousand lines of macro code it could be very difficult to spot and to find it during execution would be very tedious if not impossible. But by setting $debug to `0x10` the macro can be executed as normal and as soon as the macro is stuck the user can simply press "`C-g`" to start macro debugging at the current execution point.

Note that the "`C-g`" which triggers the macro debugger is discarded so it does not cause the current command to abort.

`0x20`

Setting this bit is similar to `0x10` except the macro debugger is enabled by the ringing of the bell. When some commands fail they always print an error message and ring the bell as the error needs handling (e.g. missing argument in a !if statement). However if the macro has been called with a !force the execution will not be aborted so tracing this issue could be difficult without this setting.

## SEE ALSO

execute-file(2).

Writing MicroEmacs Macros
Macro Glossary
Macro Debugging - A Crash Course
MicroEmacs Macro Language at a Glance

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12

</HMTL>