build/dev/lib/_pkg/sigil-stdlib/language/exceptions.md

2# Exceptions

4> Error handling with guard, raise, and exception types.

6Note: Exception handling requires `(import (sigil error))`.

8## guard

10Handle exceptions with pattern-like clauses. The primary way to catch errors.

12```scheme

13(import (sigil error))

15(guard (err

16 ((type-error? err)

17 (display "Type error: ")

18 (display (exception-message err))

19 #f)

20 ((error? err)

21 (display "Error occurred")

22 #f)

23 (else

24 (raise err))) ; Re-raise if unhandled

25 (risky-operation))

26```

28### Syntax

30```scheme

31(guard (variable

32 (test expression ...)

33 (test expression ...)

34 (else expression ...))

35 body ...)

36```

Each clause tests the caught exception. If a test succeeds, its expressions are evaluated and the result returned. The `else` clause catches anything.

40### Without else

42If no clause matches and there's no `else`, the exception propagates.

44```scheme

45(guard (e ((eq? (exception-kind e) 'expected) 'handled))

46 (raise (make-exception 'unexpected "oops" '())))

47; Exception propagates (not caught)

48```

50## raise

52Signal an exception. Transfers control to the nearest handler.

54```scheme

55(raise (make-exception 'my-error "something went wrong" '()))

56```

58## error

60Convenient way to signal an error with a formatted message.

62```scheme

63(error "Something went wrong")

64(error "Invalid argument: ~a" x)

65(error "Expected ~a, got ~a" expected actual)

66```

68The message uses `format`-style placeholders:

69- `~a` - Display representation

70- `~s` - Write representation (quoted strings)

72## Exception Types

74Sigil provides typed exceptions via `(sigil error)`:

76```scheme

77(import (sigil error))

79;; Type predicates

80(exception? e) ; Any exception

81(error? e) ; General error

82(type-error? e) ; Type mismatch

83(range-error? e) ; Value out of range

84(arity-error? e) ; Wrong argument count

86;; Low-level exception constructors

87(make-exception 'kind "message" irritants)

88(make-error "message")

90;; Struct error constructors (preferred)

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

92(arity-error message: "msg" expected-count: 2 got-count: 3)

93(range-error message: "msg" index: 10 min-bound: 0 max-bound: 5)

94(unbound-error message: "msg" variable-name: "x")

95(io-error message: "msg" path: "/tmp/foo" operation: "open")

96```

98### Exception Fields

100```scheme

101(exception-kind e) ; Symbol identifying error type

102(exception-message e) ; Human-readable message

103(exception-irritants e) ; Related values (list)

104(exception-stack-trace e) ; Stack trace if available

105```

106

107## make-exception

108

109Create a custom exception.

110

111```scheme

112(make-exception 'not-found "Resource not found" (list path))

113```

114

115Arguments:

1161. Kind (symbol) - identifies the exception type

1172. Message (string) - human-readable description

1183. Irritants (list) - related values for debugging

119

120## Common Patterns

121

122### Safe Operations

123

124```scheme

125(define (safe-divide a b)

126 (guard (e (else #f))

127 (/ a b)))

128

129(safe-divide 10 2) ; => 5

130(safe-divide 10 0) ; => #f

131```

132

133### Default on Error

134

135```scheme

136(define (read-config-or-default path)

137 (guard (e ((error? e) (default-config)))

138 (read-config path)))

139```

140

141### Re-raise After Logging

142

143```scheme

144(define (with-error-logging thunk)

145 (guard (e (else

146 (display "Error: ")

147 (display (exception-message e))

148 (newline)

149 (raise e))) ; Re-raise after logging

150 (thunk)))

151```

152

153## Stack Traces

154

155When an unhandled exception reaches the REPL, Sigil prints a stack trace showing where the error occurred.

156

157In code, access via `(exception-stack-trace e)` when available.

158

159## with-exception-handler

160

161Low-level handler installation. Rarely needed directly—prefer `guard`.

162

163```scheme

164(with-exception-handler

165 (lambda (e)

166 (display "caught!")

167 (raise e)) ; Must re-raise or return

168 (lambda ()

169 (risky-operation)))

170```

171

172The handler must either:

173- Raise the exception (or a different one)

174- Return a value (only for continuable exceptions)