Debugging utilities Isis software documentation

Debugging utilities

This document explains the debugging utilities available in Isis.

Exiting Isis

(exit) # Exit with code 0 (exit code) # Exit with given code These functions terminate the interpreter immediately, with the specified exit code. Often, an exit code of zero indicates success and non-zero indicates failure.
-> (exit) %

Debug mode

(debug True) # turn on debug mode (debug False) # turn off debug mode (debug) # toggle debug mode on and off This function turns debug mode on and off. When debug mode is turned on, whenever an interpretation error occurs, a message is printed indicating where the offending expression originated, including a file name and line and column numbers. Only core syntax interpretation errors will generate this message, not errors in primitives and C functions. If debug mode is turned off, only a brief error message is printed, with no location information.
-> ('x' 1 2) * Improper application. Null -> (debug) True -> ('x' 1 2) * Improper application. * Expression located in Console, line 3, col 0. Null

Displaying values

(display val val ...) # print the given values, return first value passed display is most useful for monitoring the value of an expression without disturbing the result of a program. The first value you pass to display is printed, and the same value is returned. In this way you can surround any expression with a call to display and the value of that expression will be printed while not disturbing the final result of the program. If you pass more than one argument, they will all be printed, but only the first argument is returned.
-> (set factorial (proc (x) (if (= (display x) 0) 1 (* x (factorial (- x 1)))))) Proc -> (factorial 6) 6 5 4 3 2 1 0 720 ->

Tracing procedure calls

(trace proc proc ...) # turn on tracing, using default names (usually unknown) (trace [proc name] [proc name] ...) # turn on tracing, using given names (untrace proc proc ...) # turn off tracing (tracename [proc name] [proc name] ...) # set the tracing name, without changing trace status Calling trace on one or more procedures turns on tracing for those procedures, and calling untrace turns it off.

Tracing is the most powerful debugging tool in Isis. By tracing a certain procedure, a message is printed whenever that procedure is called that includes a procedure name and the arguments that were passed to it. Recursive calls to traced procedures are displayed graphically using different levels of indentation.

Because procedures in Isis are inherently unnamed objects, you should supply a string name for that procedure to be used in the tracing messages. If you do not provide a tracing name, a default name will be used, which for C functions is usually adequate, but for procedures written directly in Isis, the default name will usually be [unknown]. You can change the tracing name of one or more procedures without changing their tracing status by using the tracename routine. Setting the tracing name to Null restores the default tracing name.

-> (set factorial (proc (x) (if (= x 0) 1 (* x (factorial (- x 1)))))) Proc -> (trace [factorial "fact"]) Null -> (factorial 12) ( fact 12 ) | ( fact 11 ) | | ( fact 10 ) | | | ( fact 9 ) | | | | ( fact 8 ) | | | | | ( fact 7 ) | | | | | | ( fact 6 ) | | | | | | | ( fact 5 ) | | | | | | | | ( fact 4 ) | | | | | | | | | ( fact 3 ) | | | | | | | | | | ( fact 2 ) | | | | | | | | | | | ( fact 1 ) | | | | | | | | | | | | ( fact 0 ) | | | | | | | | | | | | 1 | | | | | | | | | | | 1 | | | | | | | | | | 2 | | | | | | | | | 6 | | | | | | | | 24 | | | | | | | 120 | | | | | | 720 | | | | | 5040 | | | | 40320 | | | 362880 | | 3628800 | 39916800 479001600 479001600 -> (untrace factorial) Null -> (factorial 12) 479001600

Tracking memory usage

(memory) # display the status of the memory manager This routine displays memory manager statistics. It is meant to be used only by serious Isis hackers who need to know the memory usage patterns of the core interpreter.