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.
Usage¶
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)
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]%.
2
3 let d = pattern %[(x:*p, y:*p, z:*p)]%.
4 let x:*p = 99.
5
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).
(ADB)
Commands¶
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)).
List¶
l(ist)
lists the lines around the currently executing line
Longlist¶
ll (longlist)
lists the entire program
Step¶
s(tep)
through to the next statement or through function call.
Continue¶
c(ontinue)
cont(inue)
continue execution until the next breakpoint.
Next¶
n(ext)
continue onto the next executing line at the current scope.
Until¶
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
Return¶
(r(et))urn
Continue execution until the return of the current function is reached
Breakpoints¶
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.
Example:
-- Set a conditional breakpoint on 10 and normal breakpoints on 11, 15, and 23.
b 10 if eval("x == 123") 11 15 23
Delete¶
d(elete) (number)+
del(ete) (number)+
delete a list of breakpoints.
Example:
del 1 5 8 9
Macro¶
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¶
eval(“asteroid code”) Evaluate the asteroid code between quotes. Works exactly like a single-line repl.
Example, print out the value of x
:
eval("x")
!¶
!
Open up a repl in the current context
__retval__¶
(_)_retval
Print the most recent return value
Help¶
h(elp) (command)?
gives help for a given command. Running just help
shows all available commands.
Example:
h macro
help break
Retval¶
((r)et)val
Prints the most recent return value
<¶
<
move up one stack frame
>¶
>
move down one stack frame
Where¶
w(here)
displays the frame stack and the currently active frame.
Explicit¶
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.
Explicit
-- Toggle Explicit mode
explicit
e
-- Turn on/off
explicit on
e on
explicit off
e off
Quit¶
q(uit)
Quits the current ADB session