`(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.

(import (sigil error))

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

;; Raise an error
(error "file not found: ~a" filename)

;; Create typed exceptions
(raise (make-type-error "expected number" 'number "hello"))

Exports

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.

(guard (exn
         ((error? exn) "generic error")
         (else "other"))
  (raise (make-error "oops")))
; => "generic error"

make-type-errorprocedure

Create a type error exception.

Use when a value has the wrong type.

(raise (make-type-error "Expected a number" 'number "hello"))

type-error?procedure

Test if an exception is a type error.

(guard (exn
         ((type-error? exn) "type mismatch")
         (else "other"))
  (check-type x))

make-range-errorprocedure

Create a range error exception.

Use when a value is outside allowed bounds.

(raise (make-range-error "Index out of bounds" 10 0 5))

range-error?procedure

Test if an exception is a range error.

(guard (exn
         ((range-error? exn) "out of bounds")
         (else "other"))
  (vector-ref v 100))

make-arity-errorprocedure

Create an arity error exception.

Use when a function receives wrong number of arguments.

(raise (make-arity-error "Wrong number of arguments" 2 5))

arity-error?procedure

Test if an exception is an arity error.

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

vm-error?procedure

Test if an exception is a VM-level error.

VM errors are runtime errors from the Sigil VM such as type mismatches in primitive operations (e.g., (car 5)), division by zero, or index out of bounds. These can now be caught with guard.

(guard (exn
         ((vm-error? exn) "VM error caught")
         (else "other error"))
  (car 5))  ; => "VM error caught"

format-exceptionprocedure

Format an exception as a human-readable string.

Includes the error kind, message, irritants, and stack trace.

(guard (exn
         (else (display (format-exception exn))))
  (error "something failed"))
; Error (error): something failed
;
; Stack trace (most recent call first):
;   0: my-function
;      at main.sgl:42:5

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). Aborts to the nearest exception handler.

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)