#
Chapter 33
`trace.ss`: Tracing Top-level Procedure Calls

This library mimics the tracing facility available in Chez SchemeTM.

Tracing does not respect tail calls; i.e., tracing a procedure that ends with a tail call checks the call so that it executes (and prints) as a non-tail call. Untracing a procedure restores its tail call behavior. Only one procedure can be traced for any single name across all namespaces.

`(trace``` `name``` `···``)` S Y N T A X

This form takes a sequence of global variables names; each name must be defined as as procedure in the current namespace when the `trace` expression is evaluated. Each `name` provided to `trace` is then redefined to a new procedure. This new procedure traces procedure-calls and procedure-returns by printing the arguments and results of the call. If multiple values are returned, each value is displayed starting on a separate line.

When traced procedures invoke each other, this is shown by printing a nesting prefix. If the nesting depth grows to ten and beyond, a number is printed to show the actual nesting depth.

The `trace` macro can be used on a name that is already traced in the current namespace. In this case, assuming that the name has not been redefined, `trace` has no effect. If the name has been redefined, then a new trace is installed. If `trace` is used on the same name in two different eventspaces, then the first installed trace will remain intact but it will no longer be recognized by the `trace` and `untrace` forms.

The value of a `trace` expression is the list of names specified for tracing.

`(untrace``` `name``` `···``)` S Y N T A X

This form undoes the effects of the `trace` form for each `name`, but only if the current definition of `name` is the one previously installed by `trace`. If the current definition for `name` is not the procedure installed by `trace`, then the definition is not changed.

The value of an `untrace` expression is the list of names restored to their untraced definitions.