| 
| Errors, Assertions, and Traces | 
|---|
 |  |  | 
Bigloo permits to signal an error via the  error function. Errors
are implemented by the means of exceptions (see  with-exception-handler,
 with-handler, and  raise forms). Assertions allow the checking
of predicates at certain points in programs.   
| 
Returns a string which is the name of the dynamic type of| typeof obj | bigloo procedure |  obj. |  
| 
This form signals an error by calling the current error handler with| error proc msg obj | bigloo procedure |  proc,msgandobjas arguments.
 
 
Switching on the| (define (foo l)
   (if (not (pair? l))
       (error "foo" "argument not a pair" l)
       (car l)))
 (foo 4)
error--> *** ERROR:bigloo:foo:
         argument not a pair -- 4
 |  -gcompilation switch enables stack dumping
when theerrorfunction is invoked. That is, when a program is
compiled with-gand when, at runtime, the shell variableBIGLOOSTACKDEPTHis set and contains a number, an execution
stack of depthBIGLOOSTACKDEPTHis printed when an error is
raised. |  
| 
This form signals an error by calling the current error handler with| error/location proc msg obj file location | bigloo procedure |  proc,msgandobjas arguments. The error is prompted
infile, at character positionlocation.
 
 
| (define (foo l)
   (if (not (pair? l))
       (error/location
         "foo" "argument not a pair" l "foo.scm" 115)
       (car l)))
 (foo 4)
error--> File "foo.scm", line 4, character 115:
         #       (car l)))
         #       ^
         # *** ERROR:bigloo:foo
         # argument not a pair -- 4
             0. FOO
             1. DYNAMIC-WIND
             2. INTERP
             3. ENGINE
             4. MAIN
 |  |  
| 
| get-trace-stack size | bigloo procedure |  
Switching on the| dump-trace-stack output-port size | bigloo procedure |  -gcompilation switch enables stack dumping
Compiler Description. That is, the list of the pending calls
can be dumped by the runtime-system. The functionget-trace-stackbuilds such a trace. The list built byget-trace-stackonly
contains thesizetop most pending calls. The functiondump-trace-stackdisplays a representation of this stack on theoutput-port.
 
 |  
| 
This form signals a warning. That is, is| warning/location file location [arg]... | bigloo procedure |  argare displayed
on the standard error port. The warning is prompted infileat
character positionlocation.
 
 
| (define (foo l)
   (if (not (pair? l))
       (begin
          (warning/location
            "foo.scm" 154 "foo:" "argument not a pair -- " l)
          '())
       (car l)))
 (foo 4)
-| File "foo.scm", line 6, character 154:
   #       (car l)))
   #       ^
   # *** WARNING:bigloo:foo:
   argument not a pair -- 4
=> '()
 |  |  
| 
| exception-notify exc | bigloo procedure |  
| error-notify err | bigloo procedure |  
Display a message describing the error or warning on the default error port.| warning-notify err | bigloo procedure |  |  
| 
Returns the current exception handler with is a 0-ary procedure.| current-exception-handler | SRFI-18 function |  |  
| 
Returns the result(s) of calling| with-exception-handler handler thunk | SRFI-18 function |  thunkwith no arguments. Thehandler, which must be a procedure, is installed as the current
exception handler in the dynamic environment in effect during the call
tothunk. When possible, preferwith-handlertowith-exception-handlerbecause the former provides better debugging
support and because its semantics is more intuitive. |  
| 
Returns the result(s) of evaluating| with-handler handler body | bigloo form |  body. Thehandler, which must be a procedure, is installed as the current
exception handler in the dynamic environment in effect during the evaluation
ofbody. Contrarily towith-exception-handler, if an exception
is raised, thehandleris invoked and the value of thewith-handlerform is the value produced by invoking thehandler.
The handler is executed in the continuation of thewith-handlerform.
 JVM note: When executed within a JVM, the form
 with-handleralso catches Java exceptions.
 Important note: Since Bigloo version 3.2c, error handlers are executed
after the execution stack is unwound. Hence, error handlers are
executed after protected blocks.  For instance in the following
code:
 
 
 
The| (with-handler 
   (lambda (e) action)
   (unwind-protect
      body
      protect))
 |  actionis executed afterprotect.
 
 |  
| 
Calls the current exception handler with obj as the single
argument. obj may be any Scheme object. Note that invoking the current
handler does not escape from the current computation. It is up the to
handler to perform the escape. It an error, signaled by the runtime
system, if the current exception handler returns.| raise obj | SRFI-18 function |  
 
 
| (define (f n)
  (if (< n 0) (raise "negative arg") (sqrt n))))
 (define (g)
  (bind-exit (return)
    (with-exception-handler
      (lambda (exc)
        (return
          (if (string? exc)
              (string-append "error: " exc)
              "unknown error")))
      (lambda ()
        (write (f 4.))
        (write (f -1.))
        (write (f 9.))))))
 
 (g)  -| 2. and returns "error: negative arg"
 |  |  
The standard Bigloo runtime system uses the following classes for
signaling errors and warnings. 
| 
| (class &exception
   (fname read-only (default #f))
   (location read-only (default #f)))
 |  |  
| 
| (class &error::&exception
   (proc read-only)
   (msg read-only)
   (obj read-only))
 |  |  
| 
| (class &type-error::&error
   (type read-only))
 |  |  
| 
| (class &io-error::&error)
 |  |  
| 
| &io-port-error::&io-error | class |  
| (class &io-port-error::&io-error)
 |  |  
| 
| &io-read-error::&io-error | class |  
| (class &io-read-error::&io-port-error)
 |  |  
| 
| &io-write-error::&io-port-error | class |  
| (class &io-write-error::&io-port-error)
 |  |  
| 
| &io-closed-error::&io-port-error | class |  
| (class &io-closed-error::&io-port-error)
 |  |  
| 
| &io-file-not-found-error::&io-error | class |  
| (class &io-file-not-found-error::&io-error)
 |  |  
| 
| &io-parse-error::&io-error | class |  
| (class &io-parse-error::&io-error)
 |  |  
| 
| &io-unknown-host-error::&io-error | class |  
| (class &io-unknown-host-error::&io-error)
 |  |  
| 
| &io-malformed-url-error::&io-error | class |  
| (class &io-malformed-url-error::&io-error)
 |  |  
| 
| (class &http-error::&error)
 |  |  
| 
| &http-redirection-error::&http-error | class |  
| (class &http-redirection-error::&http-error)
 |  |  
| 
| &http-status-error::&http-error | class |  
| (class &http-status-error::&http-error)
 |  |  
| 
| &http-redirection::&http-error | class |  
| (class &http-redirection::&exception
  (port::input-port read-only)
  (url::bstring read-only))
 |  |  
| 
| process-exception::&error | class |  
| (class &process-exception::&error)
 |  |  
| 
| &warning::&exception | class |  
| (class &warning::&exception
   (args read-only))
 |  |  
| 
| &eval-warning::&warning | class |  
| (class &warning::&warning)
 |  |  
| 
This form is deprecated. As much as possible, it should be replaced with
true exceptions (i.e.,| try exp handler | bigloo syntax |  with-exception-handlerandraise). 
The argumentexpis evaluated. If an error is raised, thehandleris called. The argumenthandleris a procedure of
four arguments. Its first argument is the continuation oftry. The
other arguments areproc,mesandobj. Invoking the
first argument will resume after the error.
 
 
The argument| (let ((handler (lambda (escape proc mes obj)
                  (print "***ERROR:" proc ":" mes " -- " obj)
                  (escape #f))))
   (try (car 1) handler))
   -| ***ERROR:CAR:not a pair -- 1
   => #f
 |  handleris not evaluated in the dynamic scope of itstryform. That is:
 
 
| (let ((handler (lambda (escape proc mes obj)
                  (escape (car obj)))))
   (try (car 1) handler))
   error--> *** ERROR:bigloo:CAR
            Type `PAIR' expected, `BINT' provided -- 1
 |  |  
Some library functions exist to help in writing handlers: 
| 
This form signals a warning. That is, is| warning [arg]... | bigloo procedure |  argare displayed
on the standard error port.
 
 
| (define (foo l)
   (if (not (pair? l))
       (begin
          (warning "foo:" "argument not a pair -- " l)
          '())
       (car l)))
 (foo 4)
-| *** WARNING:bigloo:foo:
   argument not a pair -- 4
=> '()
 |  |  
| 
Assertions can be enabled or disabled using Bigloo's compilation flags| assert (var...) s-expression | bigloo syntax |  -gflag to enable them). If the assertions are disabled they are
not evaluated. If an assertion is evaluated, if the expressionexpdoes not evaluate to#t, an error is signaled and the interpreter
is launched in an environment wherevar... are bound to their
current values.
 Assertion forms are legal expressions which always evaluate
to the
 unspecifiedobject.
 Here is an example of assertion usage:
 
 
 
This module is compiled with the| (module foo
   (eval (export foo)))
 (define (foo x y)
   [assert (x y) (< x y)]
   (labels ((gee (t)
                 [assert (t) (>= t 0)]
                 (let ((res (+ x t)))
                    [assert (res t) (> res 10)]
                    res)))
      (set! x (gee y))
      [assert (x) (> x 10)]
      x))
 
 (repl)
 |  -gflag to enable assertions, then
the produced executable is run:
 
 
| $ a.out
 1:=> (foo 1 2)
 
 File "foo.scm", line 9, character 158:
#                   [assert (res t) (> res 10)]
#                   ^
# *** ERROR:bigloo:assert
# assertion failed -- (BEGIN (> RES 10))
    0. GEE
    1. FOO
-----------------------
Variables' value are : 
   RES : 3
   T : 2
-----------------------
*:=> ^D
File "foo.scm", line 12, character 228:
#      [assert (x) (> x 10)]
#      ^
# *** ERROR:bigloo:assert
# assertion failed -- (BEGIN (> X 10))
    0. FOO
-----------------------
Variables' value are : 
   X : 3
-----------------------
 
 *:=> 3
1:=> (foo 1 2)
File "foo.scm", line 9, character 158:
#                   [assert (res t) (> res 10)]
#                   ^
# *** ERROR:bigloo:assert
# assertion failed -- (BEGIN (> RES 10))
    0. GEE
    1. FOO
-----------------------
Variables' value are : 
   RES : 3
   T : 2
-----------------------
 
 *:=>
 |  |  
Bigloo provides a trace facility whose is intended for simple
debugging tasks. It is a replacement for user  displays that
clutters the source code. Here is a typical example using it: 
| (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)
 |  
which produces the following output: 
| + 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
 |  
Traces generation is controlled by a set of functions and parameters
(see Parameters ). The functions are described in this chapter. 
| 
The variable| with-trace level label . body | bigloo syntax |  levelis the level of a trace. It is a positive
integer. It enables simple filtering for traces. A trace is displayed
if and only if the debugging level used to compile or to execute the
program is greater than the trace level. The variablelabelis a
label, .e.i., an identifier denoting the trace. This identifier will
be displayed in debug mode.  The variablebodyis the body of
the form, that is, the expression to be evaluated.
 Unless a trace is activated
 (with-trace lv la body)(when its
levellvis greater than the current debug level) is equivalent
to(begin body). When traces are activated, before executingbody.
 The debugging level is controlled by two parameters:
 bigloo-debugandbigloo-compiler-debug(see Parameters).
 
 |  
| 
This function displays all its arguments. It has to be used nested in
a| trace-item . args | bigloo function |  with-traceform. |  
| 
| trace-bold s | bigloo function |  
These two functions are provided for convenience. They returns strings
made of their parameters.| trace-string s | bigloo function |  |  
| 
The| trace-color color . args | bigloo function |  colorargument is a positive integer. 
This function returns a string which is the representation ofargsand that appears on the terminal in colorcolor.
 Colors can be enable or disabled using the
 bigloo-trace-colorparameter (see Parameters). |  
| 
| trace-margin | bigloo function |  
The| trace-margin-set! | bigloo function |  trace-marginparameter 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:
 
 
| (make-thread (lambda () 
                (trace-margin-set! (trace-color 1 "="))
                ...))
(make-thread (lambda () 
                (trace-margin-set! (trace-color 2 "="))
                ...))
 |  |  
| 
| trace-port | bigloo function |  
These functions return and set the output port used by traces.| trace-port-set! | bigloo function |  |  |