the debugger

We have a Macaulay 2 source file with a pair of functions in it that we can use for demonstrating the debugger. Let's load it so we can run the functions in it.

i1 : load "demo1.m2"

We can see what functions were provided to us with listUserSymbols.

i2 : listUserSymbols

o2 = symbol class            valuelocation of symbol                         
     ------ -----            -----------------------
     g     :FunctionClosure--g    ../../../../Macaulay2/m2/demo1.m2:11:0-11:0

Let's peek at the code of the function g.

i3 : code g

o3 = -- ../../../../Macaulay2/m2/demo1.m2:11-14
     g = y -> (
          c := f(y-1);
          d := f(y-2);
          c+d)

We see that the function g calls a function f, but f is not visible to us (because f is a local variable).

The first few times we use g seem to work.

i4 : g 4

     17
o4 = --
      6

o4 : QQ

i5 : g 3

     7
o5 = -
     2

o5 : QQ

The following attempt results in an error, and the debugger starts up automatically.

i6 : g 2
../../../../Macaulay2/m2/demo1.m2:8:12:(2):[2]: division by zero
../../../../Macaulay2/m2/demo1.m2:8:12:(2):[2]: --entering debugger--

 -- useful debugger commands:
     break                  -- leave the debugger, returning to top level
     end                    -- abandon the code, enter debugger one level up
     listLocalSymbols       -- display local symbols and their values
     listUserSymbols        -- display user symbols and their values
     continue               -- execute the code and continue
     continue n             -- execute the code, stop after n microsteps
     return                 -- bypass code, return 'null', and continue
     return x               -- bypass code, return 'x', and continue
     value errorCode        -- execute the code, returning its value

 -- code just attempted: -- ../../../../Macaulay2/m2/demo1.m2:8
                              b := 1/x;

As suggested, we can use listLocalSymbols to list the local symbols and their values.

ii7 : listLocalSymbols

oo7 = symbol class            value     location of symbol                       
      ------ -----            -----     ------------------
      x     :ZZ             --0         ../../../../Macaulay2/m2/demo1.m2:6:5-6:5
      a     :String         --"hi there"../../../../Macaulay2/m2/demo1.m2:7:5-7:5
      b     :Nothing        --null      ../../../../Macaulay2/m2/demo1.m2:8:5-8:5
      f     :FunctionClosure--...       ../../../../Macaulay2/m2/demo1.m2:6:0-6:0

We see the the value of x is 0, and that explains the error message about division by zero. The other local symbols are the ones defined in the body of the function f, whose code can now be displayed with code.

ii8 : code f

oo8 = -- ../../../../Macaulay2/m2/demo1.m2:6-9
      f := x -> (
           a := "hi there";
           b := 1/x;
           b+1)

If we decide the problem is one level up, we can use end to quit this instance of the debugger. In this case, the debugger will be entered again at the point inside the function g from which the function f was called.

ii9 : end
--leaving debugger--
../../../../Macaulay2/m2/demo1.m2:13:11:(2):[2]: --entering debugger--

 -- code just attempted: -- ../../../../Macaulay2/m2/demo1.m2:13
                              d := f(y-2);

We can use listLocalSymbols again to see the local variables of g.

ii10 : listLocalSymbols

oo10 = symbol class            valuelocation of symbol                         
       ------ -----            -----------------------
       y     :ZZ             --2    ../../../../Macaulay2/m2/demo1.m2:11:4-11:4
       c     :QQ             --2    ../../../../Macaulay2/m2/demo1.m2:12:5-12:5
       d     :Nothing        --null ../../../../Macaulay2/m2/demo1.m2:13:5-13:5
       f     :FunctionClosure--...  ../../../../Macaulay2/m2/demo1.m2:6:0-6:0

After we are done debugging, we can quit the debugger entirely and return to top level with break.

ii11 : break
--leaving debugger--