on -- trace a function each time it's run

Usage:

on f
Inputs:
- f, a function
Optional inputs:
- CallLimit => an integer, default value 100000, the maximum number of times to permit the function f to be called
- Name => a string, default value null, the name to use for the function, in case f is an anonymous function (not assigned to a global variable)
- GenerateAssertions => a Boolean value, default value false, whether to print assertion statements that can be used as input to Macaulay2 to check the behavior of the function remains the same. Arguments and values are prepared with toExternalString, failure of which is silently ignored.
Outputs:
- a function, a new function that returns the same values that f would have returned, but has a few side effects useful for debugging: upon entry, it prints its arguments, and upon exit it prints its return values. The display includes the name of f, a sequence number in parentheses that tells how many times the function has been called, and a number in brackets that gives the nesting (recursion) depth. The sequence number allows the entry and exit reports to be connected.

Description

Ideally, this function would replace f, i.e., we would write f = on f. Unfortunately, all the pre-installed system functions are write-protected; fortunately, their methods are not, and can be replaced.

i1 : ker Matrix := on(lookup(ker,Matrix),GenerateAssertions=>true,Name=>"ker");

i2 : f = x -> kernel (x|x);

i3 : R = QQ[a..c];

i4 : f vars R
-- ker (1) called with OptionTable: OptionTable{DegreeLimit => {}       }
--                                              Strategy => {}
--                                              SubringLimit => infinity
-- ker (1) returned FunctionClosure: FunctionClosure[${prefix}/share/Macaulay2/Core/matrix1.m2:592:35-602:58]
-- ker (1) called with Matrix: | a b c a b c |
-- ker (1) returned Module: image {1} | -1 0  0  -b 0  -c |
--                                {1} | 0  -1 0  a  -c 0  |
--                                {1} | 0  0  -1 0  b  a  |
--                                {1} | 1  0  0  0  0  0  |
--                                {1} | 0  1  0  0  0  0  |
--                                {1} | 0  0  1  0  0  0  |
assert( ker(map(R^1,R^{6:{-1}},{{a, b, c, a, b, c}})) === (image(map(R^{6:{-1}},R^{3:{-1}, 3:{-2}},{{-1, 0, 0, -b, 0, -c}, {0, -1, 0, a, -c, 0}, {0, 0, -1, 0, b, a}, {1, 0, 0, 0, 0, 0}, {0, 1, 0, 0, 0, 0}, {0, 0, 1, 0, 0, 0}}))))

o4 = image {1} | -1 0  0  -b 0  -c |
           {1} | 0  -1 0  a  -c 0  |
           {1} | 0  0  -1 0  b  a  |
           {1} | 1  0  0  0  0  0  |
           {1} | 0  1  0  0  0  0  |
           {1} | 0  0  1  0  0  0  |

                             6
o4 : R-module, submodule of R

For the programmer

The object on is a function closure.

The source of this document is in Macaulay2Doc/ov_debugging.m2:442:0.

on -- trace a function each time it's run

Description

See also

For the programmer