@c =================================================================== @c
@c    serrano/prgm/project/bigloo/manuals/error.texi                   @c
@c    ------------------------------------------------------------     @c
@c    Author      :  Manuel Serrano                                    @c
@c    Creation    :  Mon Jun 15 10:31:21 1998                          @c
@c    Last change :  Mon Nov 12 15:20:43 2001 (serrano)                @c
@c    ------------------------------------------------------------     @c
@c    The error handling                                               @c
@c =================================================================== @c

@c ------------------------------------------------------------------- @c
@c    Error handling ...                                               @c
@c ------------------------------------------------------------------- @c
@node Tracing, Eval, Errors and Assertions, Top
@comment  node-name,  next,  previous,  up
@chapter Tracing
@cindex trace
@cindex debug

Bigloo provides a trace facility whose is intended for simple
debugging tasks. It is a replacement for user @code{display}s that
clutters the source code. Traces are enabled on compiled code when
a @code{-g} compiler option is specified 
(see @ref{Compiler Description}).
Here is a typical example using it:

@smalllisp
(define (foo x)
   (with-trace 1 'foo
      (let loop ((n x))
	 (with-trace 2 'loop
	    (trace-item "n=" n)
	    (when (> n 0)
	       (let liip ((m n))
		  (with-trace 2 'liip
		     (trace-item "m=" m))
		  (when (> m 0)
		     (liip (- m 1))))
	       (loop (- n 1)))))))

(foo 3)
@end smalllisp

which produces the following output:

@example
+ foo
  |--+ loop
  |  |- n=3
  |  |--+ liip
  |  |  |- m=3
  |  |--+ liip
  |  |  |- m=2
  |  |--+ liip
  |  |  |- m=1
  |  |--+ liip
  |  |  |- m=0
  |  |--+ loop
  |  |  |- n=2
  |  |  |--+ liip
  |  |  |  |- m=2
  |  |  |--+ liip
  |  |  |  |- m=1
  |  |  |--+ liip
  |  |  |  |- m=0
  |  |  |--+ loop
  |  |  |  |- n=1
  |  |  |  |--+ liip
  |  |  |  |  |- m=1
  |  |  |  |--+ liip
  |  |  |  |  |- m=0
  |  |  |  |--+ loop
  |  |  |  |  |- n=0
@end example

Traces generation is controlled by a set of functions and parameters
(see @ref{Parameters}). The functions are described in this chapter.

@deffn {bigloo syntax} with-trace level label . body

The variable @var{level} is the level of a trace. It might be a positive
integer or a symbol. It enables simple filtering for traces.

If @var{level} is an integer, the trace is displayed if and only if
the debugging level used to compile or to execute the program is
greater than the trace level. If @var{level} is a symbol, the trace
is displayed only if that symbol is a word contained in the 
Bigloo parameter @code{bigloo-trace}, which is, by default, initialized
from shell environment variable @code{BIGLOOTRACE}.

The variable @var{label} is a label, .e.i., an identifier denoting the
trace. This identifier will be displayed in debug mode.  The variable
@var{body} is the body of the form, that is, the expression to be
evaluated.

Unless a trace is activated @code{(with-trace lv la body)} (when its
level @var{lv} is greater than the current debug level) is equivalent
to @code{(begin body)}. When traces are activated, before executing
@var{body}.

The debugging level is controlled by two parameters:
@code{bigloo-debug} and @code{bigloo-compiler-debug} (see @ref{Parameters}).

@end deffn

@deffn {bigloo function} trace-item . args
This function displays all its arguments. It has to be used nested in
a @var{with-trace} form. 
@end deffn

@deffn {bigloo function} trace-bold s
@deffnx {bigloo function} trace-string s
These two functions are provided for convenience. They returns strings
made of their parameters.
@end deffn

@deffn {bigloo function} trace-color color . args
The @var{color} argument is a positive integer. 
This function returns a string which is the representation of @var{args}
and that appears on the terminal in color @var{color}.

Colors can be enable or disabled using the @code{bigloo-trace-color}
parameter (see @ref{Parameters}).
@end deffn

@deffn {bigloo function} trace-margin
@deffnx {bigloo function} trace-margin-set!
The @var{trace-margin} parameter is used to control the characters
that are displayed in the margin of a trace. Usual applications should
not use this. However, it may be convenient to set the margin by hands
in some context. For instance, it can be used to distinguished threads
in a multi-threaded application such as:

@smalllisp
(make-thread (lambda () 
                (trace-margin-set! (trace-color 1 "="))
                ...))
(make-thread (lambda () 
                (trace-margin-set! (trace-color 2 "="))
                ...))
@end smalllisp
@end deffn

@deffn {bigloo function} trace-port
@deffnx {bigloo function} trace-port-set!
These functions return and set the output port used by traces.
@end deffn


