macroDebugging(4)

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

MACRO DEBUGGING

In writing new macros then you need to debug them, there are various strategies as follows:

Tracing

The simplest method is to add debugging information that is printed on the message line that traces the execution sequence as it progresses through the macro.

Use ml-write(2) to print out values as you go, use

1000 ml-write &spr "Got here, value [%s]" #l1

to see the values. The integer argument is a delay in milliseconds, the command above will print the message and then wait 1 second before continuing with execution. The wait allows you to see the message.

Once the macro is debugged then delete or comment out the trace messages.

Debugger

The macro debugger is a built in debugger that allows the macro execution sequence to be traced and debugged. The debugger is operation is controlled by the variable $debug(5) by default the value is 0 which disables the debugger. The debugger displays the next command to execute in the message line and the user may single step through the macro and interrogate the variables.

Use the $debug variable for interactive debugging. The best way is to insert the following line somewhere BEFORE the problem occurs where the macro needs to be debugged:

set-variable $debug 1

As soon as this variable is set then it drops the user into debug mode. If we applied this to our tutorial example then we would define it as:

define-macro write-region 
    set-variable $debug 1       ; Enable debugger 
    copy-region 
    set-variable #l0 $buffer-fname 
    set-position "\x88" 
    !force delete-buffer "*write-region-tmp*" 
    find-buffer "*write-region-tmp*" 
    yank 
    set-variable $buffer-fname #l0 
    !force set-variable #l1 @1 
    !if $status 
        !force !force @# write-buffer #l1 @mna 
    !else 
        !force !force @# write-buffer @mna 
    !endif 
    !if &not $status 
        !force delete-buffer $buffer-bname 
        goto-position "\x88" 
        !abort 
    !endif 
    delete-buffer $buffer-bname 
    goto-position "\x88" 
!emacro

so as soon as we execute write-region then we drop into debug mode. The mode line appears as follows:

macro-name:position:number [line] ?

where macro-name is the name of the macro that is executing, position is the line from the start of the macro definition. line is the macro line that is being executed. i.e.

display-matching-fenc:22:0 [4 show region] ?

At the prompt the commands that are available are:

?

Help, display the debugger commands.

^G

Abort the macro. Immediately terminates the macro sequence, the state of the buffers is undefined and leaves the windows in the state when the macro was aborted.

^L

Redraws the current screen.

c

$debug

s

Single steps through the macro, if another macro is invoked then debugging with continue in the new sub-macro.

v

Display the value of a variable. The user is prompted for a variable value to show, once entered, the value of the variable is displayed.

<any>

step

See the $debug(5) help page for more information.

It is important that you SAVE ALL YOUR WORK before starting to debug macros. It is possible to sometimes crash the editor up while developing macros, prior to the January 2005 build then the following example of infinite recursion would destroy the editor:

define-macro Test 
    Test 
!emacro

This macro nesting is now caught the nesting is limited to 20 calling macros.

For everyday macros that the typical user will write MicroEmacs will be robust and is not likely to result in any damage. If you start writing macros with for deeply nested macro hooks from the core of MicroEmacs (i.e. ipipe callbacks) then deleting buffers under the editor will cause stability problems when mistakes are made. For performance reasons it is not possible to check for all permutations of every command that could be issued that may possibly change the state of the editor and then recover. Provided that the calls are used within their calling remit then no ill effects will be observed.

Running macros without the editor

Macro logic can be run and checked without a terminal, and without starting the editor, using the piped mode option -p. This is useful for regression tests and for timing, as the macro runs to completion and the process exits.

The macro file is given with @ and it must define a start-up(3) macro, as there is no user input to drive the editor; without one the editor reports "Pipe script failed to exit" and stops. Exit with exit-emacs(2), giving a numeric argument of 4 so that the user is not prompted. Use ml-write(2) with a numeric argument of -2 to write to the standard output.

define-macro start-up 
    -2 ml-write &spr "2 + 2 = %d" &add 2 2 
    4 exit-emacs 0 
!emacro

Run with:

export MEPATH=<install>/macros:$PWD 
mec -p "@./mytest" < /dev/null

The output uses carriage returns as line endings, so pipe it through "tr '\r' '\n'" when reading it from a shell script. Note that the -P option is piped mode with debugging, which waits for input and is not suitable for an unattended run.

See test/emf/ and test/hearts/ for worked examples, the latter including a test runner script.

macroDebugging(4)

MACRO DEBUGGING

Tracing

Debugger

Running macros without the editor

SEE ALSO