build/dev/lib/_pkg/sigil-stdlib/language/special-forms.md

2# Special Forms

4> Core syntax constructs for definitions and control flow.

6## Definitions

8### define

10Define a variable or procedure.

12```scheme

13;; Variable definition

14(define pi 3.14159)

15(define message "hello")

17;; Procedure definition (shorthand)

18(define (square x)

19 (* x x))

21;; Equivalent to:

22(define square

23 (lambda (x) (* x x)))

25;; Multiple expressions in body

26(define (greet name)

27 (display "Hello, ")

28 (display name)

29 (newline))

30```

32### lambda

34Create an anonymous procedure.

36```scheme

37(lambda (x) (* x x)) ; one parameter

38(lambda (x y) (+ x y)) ; two parameters

39(lambda args (length args)) ; rest parameter (collects all args)

40(lambda (x . rest) x) ; one required, rest optional

41```

43### set!

45Mutate an existing binding.

47```scheme

48(define counter 0)

49(set! counter (+ counter 1))

50```

52Use sparingly. Prefer functional style when possible.

54## Local Bindings

56### let

58Bind variables in parallel (bindings can't reference each other).

60```scheme

61(let ((x 1)

62 (y 2))

63 (+ x y))

64; => 3

66;; Named let for recursion

67(let loop ((n 5) (acc 1))

68 (if (zero? n)

69 acc

70 (loop (- n 1) (* acc n))))

71; => 120 (factorial)

72```

74### let*

76Bind variables sequentially (each can see previous bindings).

78```scheme

79(let* ((x 1)

80 (y (+ x 1))

81 (z (+ y 1)))

82 (list x y z))

83; => (1 2 3)

84```

86### letrec

88Bind variables that can reference each other (for mutual recursion).

90```scheme

91(letrec ((even? (lambda (n)

92 (or (zero? n) (odd? (- n 1)))))

93 (odd? (lambda (n)

94 (and (not (zero? n)) (even? (- n 1))))))

95 (even? 10))

96; => #t

97```

99## Conditionals

100

101### if

102

103Two-branch conditional.

104

105```scheme

106(if (> x 0)

107 "positive"

108 "not positive")

109

110;; Without else branch (returns unspecified value if false)

111(if (file-exists? path)

112 (load-file path))

113```

114

115### cond

116

117Multi-branch conditional with pattern-like clauses.

118

119```scheme

120(cond

121 ((< x 0) "negative")

122 ((= x 0) "zero")

123 (else "positive"))

124

125;; With => to pass test result to procedure

126(cond

127 ((assoc key alist) => cdr)

128 (else default))

129```

130

131### case

132

133Dispatch on value using `eq?` comparison. Best for symbols and small integers.

134

135```scheme

136(case color

137 ((red green blue) "primary")

138 ((cyan magenta yellow) "secondary")

139 (else "other"))

140```

141

142### when / unless

143

144Single-branch conditionals for side effects.

145

146```scheme

147(when (> x 0)

148 (display "positive")

149 (newline))

150

151(unless (null? items)

152 (process-items items))

153```

154

155## Boolean Operations

156

157### and

158

159Short-circuit AND. Returns last true value or first false.

160

161```scheme

162(and #t #t) ; => #t

163(and 1 2 3) ; => 3

164(and #f (error)) ; => #f (error not evaluated)

165```

166

167### or

168

169Short-circuit OR. Returns first true value or last false.

170

171```scheme

172(or #f #f) ; => #f

173(or #f 1 2) ; => 1

174(or (find x) default) ; common pattern

175```

176

177### not

178

179Boolean negation.

180

181```scheme

182(not #f) ; => #t

183(not #t) ; => #f

184(not '()) ; => #f (only #f is false)

185```

186

187## Sequencing

188

189### begin

190

191Execute expressions in order, return last value.

192

193```scheme

194(begin

195 (display "one")

196 (display "two")

197 "result")

198; prints: onetwo

199; => "result"

200```

201

202## Iteration

203

204For iteration, use named `let` or higher-order functions like `map` and `fold`.

205

206### Named let

207

208```scheme

209;; Count down

210(let loop ((n 5))

211 (when (> n 0)

212 (display n)

213 (loop (- n 1))))

214; prints: 54321

215

216;; Accumulating loop

217(let loop ((items '(1 2 3 4 5))

218 (sum 0))

219 (if (null? items)

220 sum

221 (loop (cdr items) (+ sum (car items)))))

222; => 15

223```

224

225### Higher-order functions

226

227```scheme

228;; Transform each element

229(map (lambda (x) (* x 2)) '(1 2 3)) ; => (2 4 6)

230

231;; Keep matching elements

232(filter even? '(1 2 3 4 5)) ; => (2 4)

233

234;; Reduce to single value

235(fold-left + 0 '(1 2 3 4 5)) ; => 15

236```