Debugger Documentation

This page details the Minigrace Debugger. To access the debugger, simply check the debugger check box

  1. Interface
  2. Breakpoints
  3. Restart and Continue
  4. Step and Backstep
  5. Variables
  6. Cached Values
  7. Actual Workings

Interface

Ace Debugger
Breakpoints
(No breakpoints added yet)
Variables:

Mouse over parts of the interface above to see a quick explanation of what each part does.

Debugger Toggle: Unchecking this checkbox will hide the debugger interface, checking it again will show it again.

Standard Error: This is the textarea where standard error and logging messages are printed to.

Back-Step: This button will take the debugger to the line just before whatever line it's currently stopped on.

Restart: This button will run the debugger from the beginning to until it hits a breakpoint.

Continue: This button will run the debugger past any previous stops until it hits it's next breakpoint. Note that this may make it stop for each cycle of a loop if there's a breakpoint set somewhere in the loop.

Step: This button will take the debugger to the line just before whatever line it's currently stopped on.

breakpoints: This is where the currently set breakpoints are listed.

Breakpoint: This is a breakpoint. The number is the line where the program will stop if it reaches this point from being run by Restart or Continue. Disable will prevent this breakpoint from stopping the program, and Enable will enable the breakpoint to again possibly stop the program. Remove will completely remove the breakpoint.

Add a breakpoint: Enter a number greater than or equal to 1 and click Add a breakpoint to add a breakpoint.

Variable List: This is where variables that are in existence at the time the program stops or is interrupted can be seen.


A Breakpoint is an intentional stopping point in the program. If ace is enabled, then you can set breakpoints by clicking on the space just to the left of the line number, and click again to disable it. Otherwise, place a breakpoint in the program by typing the line number you want to stop at and clicking the Add a breakpoint button. Remove a breakpoint by clicking Remove, disable it by clicking Disable. Breakpoints only stop the program if the program is started by clicking either the Restart or Continue buttons.


Restart and Continue

The Restart and Continue buttons run the program until it hits a breakpoint or finishes execution.

Continue will run the debugger past wherever the program last stopped until the next breakpoint, while Restart will stop at the first breakpoint the program encounters.


Step and Back-step

Step will pause the program just after the last line the program paused on. Back-Step will pause the program just before the last line the program paused on.


Variables

All variables created in the current scope of the program should be displayed in the variables section, along with their values or an expandable menu option to display variables within the given variable. lists and objects are the most common variables types that may have a menu option. If the program is interrupted before a variable is declared, it will not appear in the display.

It is possible to adjust how the debugger displays an object from within Grace. To change the value displayed by an object, add a debugValue method to the object that will return a string. 

    method debugValue() {
        "\"Type == object\"" 
    }
The above example will make the object display a value of "Type == object".

To change the variables within the object that are displayed, add a debugIterator to the object that will return an iterator. 

    method debugIterator() {
        return object {
            var b := 1
            var test
        }.debugIterator()
    }
The above example will make the object show itself as having a variable b with a value of 1 and a variable test with an undefined value.

To stop an object from having an expandable menu, the following to the object: 

    var debugIteratorEnabled := false
The object will now show up as a variable without an expandable menu option.


Cached Values

For programs that use the random method from the math module or the input.read method from the io module, Caching is done on these methods to prevent odd behavior from the debugger. To clear the cache, simply uncheck then reacheck the debugger check box.

For Developers: As of writing this, to add a new method to the list of methods to be cached, you need to edit debugger.js to add the name of the module and method that will be cached. Find "GraceDebugger.cache = {" and inside the definition should be the following lines: 

    names : [
        {module: "math", method : "random"},
Add the following line just after the above, but change "module name" and "method name" to the appropriate values. 
        {module: "module name", method : "method name"},
That should cause the debugger to start caching that method's return values.


Actual Workings

This Debugger does not actually pause the program mid-execution, but instead interrupts it based on line changes. It resumes by running the program again, but changing where the interrupt occurs so that it seems to stop and resume. Because of this, any non-deterministic behavior the program contains may cause unpredictable behavior. The Caching system was put in place to help deal with this issue.