ADB Reference Guide

The Asteroid Debugger (ADB) is a source code debugger for the Asteroid programming language.

It supports the following:

  • Breakpoints

  • Single stepping at the source level

  • Stepping through function calls

  • Stack frame inspection

  • Evaluation of arbitrary Asteroid code

  • Macros

  • REPL Instances

ADB features a unique “explicit” mode which details much of the pattern matching and underlying mechanics of Asteroid allow developers to debug pattern matches. Explicit mode details many of the steps of pattern matching, function calling, statement execution, and return values. Explicit mode is very experimental and is under current research. As a result, explicit mode is currently incomplete.


asteroid --adb <FILENAME>

asteroid -g <FILENAME>

Debugging sessions

The debugger’s prompt (ADB) allows the user to enter commands to effect the source environment and debugger behavior.

Each debugging session will have a few pieces of information:

Filename and line number

[/home/user/test.ast (1)]

The current line which will be executed

-->> let p = pattern %[(x:%integer) if x > 0 and x < 100]%.

The command prompt


ADB runs like any other debugger, here’s a small example session where we see running commands, listing the program, and setting and continuing to breakpoints.

[/home/user/test.ast (1)]
-->> let p = pattern %[(x:%integer) if x > 0 and x < 100]%.
(ADB) ll
----- Program Listing -----
>  1 let p = pattern %[(x:%integer) if x > 0 and x < 100]%.
   3 let d = pattern %[(x:*p, y:*p, z:*p)]%.
   4 let x:*p = 99.
   6 let t:*d = (1,2,3).
   7 [EOF]
(ADB) break 6
(ADB) continue
----- Breakpoint -----
[/home/user/test.ast (6)]
-->> let t:\*d = (1,2,3).


Below is a list of the commands available to the debugger. Most of which can be shortened. These shortenings are shown in parenthesis (c(ommand)).


l(ist) lists the lines around the currently executing line


ll (longlist) lists the entire program


s(tep) through to the next statement or through function call.


c(ontinue) cont(inue) continue execution until the next breakpoint.


n(ext) continue onto the next executing line at the current scope.


u(ntil) ?lineno By default, continue execution until a line with a greater number than the current one is reached.

Given an optional line number, continue execution until a line number greater than or equal to that number is reached


(r(et))urn Continue execution until the return of the current function is reached


b(reak) number\* set a breakpoint at one or more lines. Running without any arguments lists your breakpoints.

Example: b 1 2 3, break.

Conditional breakpoints can be set in the same way, just attach if eval("condition") after each breakpoint number.


-- Set a conditional breakpoint on 10 and normal breakpoints on 11, 15, and 23.
b 10 if eval("x == 123") 11 15 23


d(elete) (number)+ del(ete) (number)+ delete a list of breakpoints.


del 1 5 8 9


macro (name) (command list). Define a macro. Running just macro lists your macros.

Example macro that continues to a breakpoint and prints the value of x:

macro gox = c; eval("io@println(x)");


eval(“asteroid code”) Evaluate the asteroid code between quotes. Works exactly like a single-line repl.

Example, print out the value of x:



! Open up a repl in the current context


(_)_retval Print the most recent return value


h(elp) (command)? gives help for a given command. Running just help shows all available commands. Example:

h macro
help break


((r)et)val Prints the most recent return value


< move up one stack frame


> move down one stack frame


w(here) displays the frame stack and the currently active frame.


e(xplicit) (on|off)? By default, this command run without an argument toggles explicit mode. If given a literal on or off, explicit mode will be switched to the corresponding state.


-- Toggle Explicit mode

-- Turn on/off
explicit on
e on
explicit off
e off


q(uit) Quits the current ADB session