`(sigil error)`

(sigil error) - Exception Handling

Handle errors gracefully with exceptions. Use guard for structured error handling, create typed exceptions for different error conditions, and format exceptions for user-friendly error messages.

Provides both traditional exception vectors (for raise/guard) and a struct-based error hierarchy for structured access to error details. Use exception->error to convert caught exceptions to rich error structs.

(import (sigil error))

;; Handle errors with guard
(guard (exn
         ((type-error? exn) "wrong type!")
         (else (format "error: ~a" (exception-message exn))))
  (risky-operation))

;; Convert to struct for structured access
(guard (exn
         (else
          (let ((err (exception->error exn)))
            (when (type-error? err)
              (display (type-error-expected-type err))))))
  (car 42))

Exports

sigil-errorprocedure

Base error type with message and optional stack trace.

sigil-error?procedure

Test if a value is a sigil-error struct.

sigil-error-messageprocedure

Get the message field of a sigil-error struct.

sigil-error-stack-traceprocedure

Get the stack-trace field of a sigil-error struct.

%type-error--typevariable

Get the stack-trace field of a sigil-error struct.

type-errorprocedure

Type mismatch error with procedure name and expected/got types.

(type-error message: "car: expected pair"
            procedure-name: "car"
            expected-type: "pair")

type-error?procedure

Test if a value is a type-error struct.

type-error-messageprocedure

Get the message field of a type-error struct.

type-error-stack-traceprocedure

Get the stack-trace field of a type-error struct.

type-error-procedure-nameprocedure

Get the procedure-name field of a type-error struct.

type-error-expected-typeprocedure

Get the expected-type field of a type-error struct.

type-error-got-typeprocedure

Get the got-type field of a type-error struct.

type-error->sigil-errorprocedure

Get the got-type field of a type-error struct.

%arity-error--typevariable

Get the got-type field of a type-error struct.

arity-errorprocedure

Wrong argument count error.

(arity-error message: "foo: expected 2 arguments, got 3"
             procedure-name: "foo"
             expected-count: 2
             got-count: 3)

arity-error?procedure

Test if a value is a arity-error struct.

arity-error-messageprocedure

Get the message field of a arity-error struct.

arity-error-stack-traceprocedure

Get the stack-trace field of a arity-error struct.

arity-error-procedure-nameprocedure

Get the procedure-name field of a arity-error struct.

arity-error-expected-countprocedure

Get the expected-count field of a arity-error struct.

arity-error-got-countprocedure

Get the got-count field of a arity-error struct.

arity-error->sigil-errorprocedure

Get the got-count field of a arity-error struct.

%unbound-error--typevariable

Get the got-count field of a arity-error struct.

unbound-errorprocedure

Unbound variable error.

(unbound-error message: "unbound variable 'foo'"
               variable-name: "foo")

unbound-error?procedure

Test if a value is a unbound-error struct.

unbound-error-messageprocedure

Get the message field of a unbound-error struct.

unbound-error-stack-traceprocedure

Get the stack-trace field of a unbound-error struct.

unbound-error-variable-nameprocedure

Get the variable-name field of a unbound-error struct.

unbound-error->sigil-errorprocedure

Get the variable-name field of a unbound-error struct.

%range-error--typevariable

Get the variable-name field of a unbound-error struct.

range-errorprocedure

Index or value out of range error.

(range-error message: "vector-ref: index 10 out of bounds"
             procedure-name: "vector-ref"
             index: 10
             max-bound: 5)

range-error?procedure

Test if a value is a range-error struct.

range-error-messageprocedure

Get the message field of a range-error struct.

range-error-stack-traceprocedure

Get the stack-trace field of a range-error struct.

range-error-procedure-nameprocedure

Get the procedure-name field of a range-error struct.

range-error-indexprocedure

Get the index field of a range-error struct.

range-error-min-boundprocedure

Get the min-bound field of a range-error struct.

range-error-max-boundprocedure

Get the max-bound field of a range-error struct.

range-error->sigil-errorprocedure

Get the max-bound field of a range-error struct.

%io-error--typevariable

Get the max-bound field of a range-error struct.

io-errorprocedure

I/O error with path and operation.

(io-error message: "file not found"
          path: "/tmp/foo.txt"
          operation: "open")

io-error?procedure

Test if a value is a io-error struct.

io-error-messageprocedure

Get the message field of a io-error struct.

io-error-stack-traceprocedure

Get the stack-trace field of a io-error struct.

io-error-pathprocedure

Get the path field of a io-error struct.

io-error-operationprocedure

Get the operation field of a io-error struct.

io-error->sigil-errorprocedure

Get the operation field of a io-error struct.

sigil-error?procedure

Test if a value is any error (struct or exception).

type-error?procedure

Test if a value is a type error (struct or exception).

(guard (exn
         ((type-error? exn) "type mismatch")
         (else "other"))
  (car 5))

arity-error?procedure

Test if a value is an arity error (struct or exception).

(guard (exn
         ((arity-error? exn) "wrong arg count")
         (else "other"))
  (apply my-func wrong-args))

unbound-error?procedure

Test if a value is an unbound variable error (struct or exception).

range-error?procedure

Test if a value is a range error (struct or exception).

io-error?procedure

Test if a value is an I/O error (struct or exception).

make-errorprocedure

Create a generic error exception.

(raise (make-error "Something went wrong"))
(raise (make-error "Invalid input" input-value))

error?procedure

Test if an exception is a generic error.

vm-error?procedure

Test if an exception is a VM-level error.

VM errors are runtime errors from the Sigil VM that don't map to a more specific error type (type-error, arity-error, etc.).

(guard (exn
         ((vm-error? exn) "VM error caught")
         (else "other error"))
  (dangerous-op))

exception->errorprocedure

Convert an exception (or any raised value) to a rich error struct.

Maps exception kinds to the appropriate struct type, extracting structured fields from the irritants list. Already-converted struct errors are returned as-is.

(guard (exn
         (else
          (let ((err (exception->error exn)))
            (when (type-error? err)
              (format "expected ~a" (type-error-expected-type err))))))
  (car 42))

format-exceptionprocedure

Format an exception as a human-readable string.

Works with both old-style exception vectors and new error structs. Includes the error kind, message, structured fields, and stack trace.

(guard (exn
         (else (display (format-exception exn))))
  (error "something failed"))
; Error (error): something failed

format-stack-traceprocedure

Format a stack trace as a string.

By default, only shows frames with named functions, hiding anonymous lambdas to reduce noise from macro expansion and internal implementation. Pass #t to show all frames including anonymous ones.

(format-stack-trace (exception-stack-trace exn))
; =>   "0: my-function\n     at main.sgl:42:5\n  ..."

(format-stack-trace (exception-stack-trace exn) #t)  ; show all

print-exceptionprocedure

Print an exception to standard output.

(guard (exn
         (else (print-exception exn)))
  (error "failed"))

make-exceptionprocedure

Create an exception with the given kind, message, and irritants.

Re-exported from (sigil core)

make-exception-with-traceprocedure

Create an exception with stack trace.

Re-exported from (sigil core)

exception?procedure

Check if obj is an exception.

Re-exported from (sigil core)

exception-kindprocedure

Get the kind of an exception (e.g., 'error, 'type-error).

Re-exported from (sigil core)

exception-messageprocedure

Get the message from an exception.

Re-exported from (sigil core)

exception-irritantsprocedure

Get the irritants (additional data) from an exception.

Re-exported from (sigil core)

exception-stack-traceprocedure

Get the stack trace from an exception.

Re-exported from (sigil core)

raiseprocedure

Raise an exception (non-continuable). The compiler compiles direct calls to OP_RAISE (which handles stack trace attachment and searches the VM exception handler stack). This Scheme wrapper exists for first-class use (e.g. apply/map).

Re-exported from (sigil core)

raise-continuableprocedure

Raise a continuable exception. The handler can return a value to continue execution.

Re-exported from (sigil core)

errorprocedure

Convenience function to raise an error exception. (error "message" irritant ...)

Re-exported from (sigil core)

with-exception-handlerprocedure

Install an exception handler and execute thunk (R6RS style). Handler is a procedure taking the exception. Thunk is the body to execute.

Re-exported from (sigil core)

current-exception-handlerprocedure

Get the current exception handler.

Re-exported from (sigil core)