README.md — sigil-match

1# sigil-match

3> **Archived at Sigil 0.19.0:** The maintained implementation now lives in

4> `codeberg:sigil/sigil`. This repository and all tags remain available for

5> provenance, but no further standalone releases will be published.

Pattern matching library for [Sigil](https://codeberg.org/sigil/sigil). Destructure and dispatch on data using patterns. Match values against shapes, bind variables, and combine patterns with guards, boolean logic, and transformations.

9## Usage

11```scheme

12(import (sigil match))

14;; Destructure a list

15(match '(1 2 3)

16 ((a b c) (+ a b c))) ; => 6

18;; Type dispatch

19(match value

20 ((? number?) "it's a number")

21 ((? string?) "it's a string")

22 (_ "something else"))

24;; Literal matching

25(match cmd

26 ('quit (exit))

27 ('help (show-help))

28 (('load file) (load-file file))

29 (_ (unknown-command)))

30```

32## Pattern Types

34| Pattern | Description |

35|---------|-------------|

36| `_` | Wildcard, matches anything |

37| `()` | Empty list |

38| `'datum` | Literal value (uses `equal?`) |

39| `#t` / `#f` | Boolean literals |

40| `(p1 . p2)` | Pair: `p1` matches car, `p2` matches cdr |

41| `(p1 p2 ...)` | List: each element matched positionally |

42| `var` | Variable binding |

43| `(? pred)` | Guard: matches if `(pred val)` is true |

44| `(? pred pat)` | Guarded pattern: pred and pattern must both match |

45| `(and p ...)` | All patterns must match |

46| `(or p ...)` | Any pattern matches (first wins) |

47| `(not pat)` | Negation: matches if pattern doesn't |

48| `(= proc pat)` | Transform: apply proc, then match result |

49| `($ type p ...)` | SRFI-9 record: match type tag and fields positionally |

50| `(: type k: ...)` | Sigil struct: match by keyword fields |

51| `#{ k: p ... }` | Dict: match by keyword fields |

52| `#(p ...)` | Vector: match elements positionally |

54## Guard Patterns

56Use `(? predicate)` to match values satisfying a condition:

58```scheme

59(match x

60 ((? positive? n) (format "positive: ~a" n))

61 ((? negative? n) (format "negative: ~a" n))

62 (_ "zero"))

63```

65## Combining Patterns

67Use `and`, `or`, and `not` to combine patterns:

69```scheme

70;; All conditions must match

71(match n

72 ((and (? integer?) (? positive?)) "positive integer")

73 (_ "other"))

75;; Any condition can match

76(match color

77 ((or 'red 'green 'blue) "primary")

78 (_ "other"))

80;; Negation

81(match lst

82 ((not ()) "non-empty")

83 (() "empty"))

84```

86## Transform Patterns

88Use `(= proc pat)` to transform a value before matching:

90```scheme

91(match str

92 ((= string-length 0) "empty")

93 ((= string-length 1) "single char")

94 (_ "multiple chars"))

95```

97## Record Patterns (SRFI-9)

99Use `($ type fields ...)` to match SRFI-9 record types positionally:

100

101```scheme

102(define-record-type <point>

103 (make-point x y) point?

104 (x point-x) (y point-y))

105

106(match p

107 (($ <point> x y) (+ x y)))

108```

109

110## Struct Patterns (Sigil)

111

112Use `(: type field: ...)` to match Sigil structs by field name:

113

114```scheme

115(define-struct point (x) (y))

116

117(match p

118 ((: point x: y:) (+ x y)) ; shorthand: binds x and y

119 ((: point x: px y: py) ...)) ; explicit binding names

120

121;; Match only specific fields

122(match p

123 ((: point y:) y)) ; only match y field

124```

125

126## Dict Patterns

127

128Use `#{ key: pat ... }` or `(dict key: ...)` to match dicts by key:

129

130```scheme

131(match config

132 (#{ host: port: } (connect host port))

133 ((dict debug:) debug))

134

135;; Type check only

136(match val

137 ((dict) 'is-dict)

138 (_ 'other))

139```

140

141## Convenience Forms

142

143```scheme

144;; match-lambda: anonymous function with pattern matching

145(define get-x (match-lambda ((x . _) x)))

146(get-x '(1 2 3)) ; => 1

147

148;; match-lambda*: match all arguments as a list

149(define add-pair

150 (match-lambda* ((a b) (+ a b))))

151(add-pair 3 4) ; => 7

152

153;; match-let: destructuring let

154(match-let (((x y) '(1 2))

155 ((a . b) '(3 4 5)))

156 (list x y a b))

157; => (1 2 3 (4 5))

158```

159

160## Exports

161

162- `match` - Main matching macro

163- `match-lambda` - Single-argument matching lambda

164- `match-lambda*` - Multi-argument matching lambda

165- `match-let` - Destructuring let with patterns

166- `match-pattern` - Low-level pattern matching (used internally)

167

168## Dependencies

169

170- sigil-stdlib

171

172## Building

173

174```

175sigil deps install

176sigil build

177sigil test

178```

179

180## License

181

182BSD-3-Clause