Scheme Programmer's Manual

NAME

error, assertion-violation - raise an exception

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs base))                ;R6RS
(import (scheme base))              ;R7RS

SYNOPSIS

(error who message irritant1 ...)                ;R6RS
(assertion-violation who message irritant1 ...)  ;R6RS

(error message irritant1 ...)                    ;R7RS

DESCRIPTION

These procedures raise an exception.

The error procedure should be called when an error has occurred, typically caused by something that has gone wrong in the interaction of the program with the external world or the user.

The assertion-violation procedure should be called when an invalid call to a procedure was made, either passing an invalid number of arguments, or passing an argument that it is not specified to handle.

The who argument should describe the procedure or operation that detected the exception. The message argument should describe the exceptional situation. The irritants should be the arguments to the operation that detected the operation.

R6RS
The condition object provided with the exception has the following condition types:
*
If who is not #f, the condition has condition type &who, with who as the value of its field. In that case, who should be the name of the procedure or entity that detected the exception. If it is #f, the condition does not have condition type &who.
*
The condition has condition type &message, with message as the value of its field.
*
The condition has condition type &irritants, and its field has as its value a list of the irritants.
Moreover, the condition created by error has condition type &error, and the condition created by assertion-violation has condition type &assertion.
R7RS
Raises an exception as if by calling raise(3scheme) on a newly allocated implementation-defined object which encapsulates the information provided by message, as well as any irritants. The procedure error-object? must return #t on such objects.
There is no assertion-violation procedure. Instead, error is used.

RETURN VALUES

These procedures do not return.

EXAMPLES

;; R6RS (define (fac n)
  (when (not (integer-valued? n))
    (assertion-violation 'fac "non-integral argument" n))
  (when (negative? n)
    (assertion-violation 'fac "negative argument" n))
  (letrec ((loop (lambda (n r)
                    (if (zero? n)
                        r
                        (loop (- n 1) (* r n))))))
    (loop n 1)))

(fac 5) => 120 (fac 4.5) => &assertion exception (fac -3) => &assertion exception

;; R7RS (define (null-list? l)
  (cond ((pair? l) #f)
        ((null? l) #t)
        (else
          (error
            "null-list?: argument out of domain"
            l))))

APPLICATION USAGE

These procedures are used when there is an error in the program.

RATIONALE

The difference between an error and assertion is that an assertion is caused by faults internal to the program, i.e. one would be inclined to say that a program which crashes from an &assertion is buggy, whereas if it crashes from an &error then it crashed due to external circumstances.

COMPATIBILITY

The assertion-violation procedure is absent from R7RS. Code that needs to work on both R6RS and R7RS can define an assertion-violation procedure that calls error and moves the who argument into the message.

Previous to R6RS and R7RS, programs would either contain a deliberate error and hope that it would be detected and reported, or they would use SRFI-23. Most Scheme implementations did have some built-in error reporting mechanism that could be used, but it would be non-portable.

ERRORS

This procedure can raise exceptions with the following condition types:
&assertion (R6RS)
The wrong number of arguments was passed or an argument was outside its domain. In particular, who must be a string or a symbol or #f and message must be a string.
R7RS
The assertions described above are errors. Implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically.

SEE ALSO

raise(3scheme), assert(7scheme), guard(7scheme)

STANDARDS

R6RS, R7RS

HISTORY

The error procedure is absent from R2RS to R5RS. Before R2RS, Scheme had access to the error function in MacLISP. Programs in the R4RS and R5RS era often used SRFI-23.

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at

Index

NAME
LIBRARY
SYNOPSIS
DESCRIPTION
RETURN VALUES
EXAMPLES
APPLICATION USAGE
RATIONALE
COMPATIBILITY
ERRORS
SEE ALSO
STANDARDS
HISTORY
AUTHORS
Return to Main Contents