error(3scm)

error(3scm) — raise an exception 💅

okay so bestie, this is the error(3scm) page from the Scheme Programmer's Manual — the one all about raising exceptions, and it's giving very much “stop the program, something happened” energy. ✨

💖 NAME 💖

error, assertion-violation — raise an exception. periodt.

🦋 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. That's the whole vibe. 💅

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(3scm) 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. Like, not even a little. They raise and that's it. 💀

💜 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. Simple as that, bestie. 🫶

🔥 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(3scm), assert(7scm), guard(7scm)

⭐ 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 https://github.com/schemedoc/manpages/.

---

okay that's the whole page, bestie — it's from the Scheme Programmer's Manual, page error(3scm), dated 2021-03-07. 🫶✨