AtlatestRepositorysigil-match

sigil-match / treeREADME.md

Read it rendered

1# sigil-match
2
3Pattern 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.
4
5## Usage
6
7```scheme
8(import (sigil match))
9
10;; Destructure a list
11(match '(1 2 3)
12 ((a b c) (+ a b c))) ; => 6
14;; Type dispatch
15(match value
16 ((? number?) "it's a number")
17 ((? string?) "it's a string")
18 (_ "something else"))
20;; Literal matching
21(match cmd
22 ('quit (exit))
23 ('help (show-help))
24 (('load file) (load-file file))
25 (_ (unknown-command)))
26```
28## Pattern Types
30| Pattern | Description |
31|---------|-------------|
32| `_` | Wildcard, matches anything |
33| `()` | Empty list |
34| `'datum` | Literal value (uses `equal?`) |
35| `#t` / `#f` | Boolean literals |
36| `(p1 . p2)` | Pair: `p1` matches car, `p2` matches cdr |
37| `(p1 p2 ...)` | List: each element matched positionally |
38| `var` | Variable binding |
39| `(? pred)` | Guard: matches if `(pred val)` is true |
40| `(? pred pat)` | Guarded pattern: pred and pattern must both match |
41| `(and p ...)` | All patterns must match |
42| `(or p ...)` | Any pattern matches (first wins) |
43| `(not pat)` | Negation: matches if pattern doesn't |
44| `(= proc pat)` | Transform: apply proc, then match result |
45| `($ type p ...)` | SRFI-9 record: match type tag and fields positionally |
46| `(: type k: ...)` | Sigil struct: match by keyword fields |
47| `#{ k: p ... }` | Dict: match by keyword fields |
48| `#(p ...)` | Vector: match elements positionally |
50## Guard Patterns
52Use `(? predicate)` to match values satisfying a condition:
54```scheme
55(match x
56 ((? positive? n) (format "positive: ~a" n))
57 ((? negative? n) (format "negative: ~a" n))
58 (_ "zero"))
59```
61## Combining Patterns
63Use `and`, `or`, and `not` to combine patterns:
65```scheme
66;; All conditions must match
67(match n
68 ((and (? integer?) (? positive?)) "positive integer")
69 (_ "other"))
71;; Any condition can match
72(match color
73 ((or 'red 'green 'blue) "primary")
74 (_ "other"))
76;; Negation
77(match lst
78 ((not ()) "non-empty")
79 (() "empty"))
80```
82## Transform Patterns
84Use `(= proc pat)` to transform a value before matching:
86```scheme
87(match str
88 ((= string-length 0) "empty")
89 ((= string-length 1) "single char")
90 (_ "multiple chars"))
91```
93## Record Patterns (SRFI-9)
95Use `($ type fields ...)` to match SRFI-9 record types positionally:
97```scheme
98(define-record-type <point>
99 (make-point x y) point?
100 (x point-x) (y point-y))
102(match p
103 (($ <point> x y) (+ x y)))
104```
106## Struct Patterns (Sigil)
108Use `(: type field: ...)` to match Sigil structs by field name:
110```scheme
111(define-struct point (x) (y))
113(match p
114 ((: point x: y:) (+ x y)) ; shorthand: binds x and y
115 ((: point x: px y: py) ...)) ; explicit binding names
117;; Match only specific fields
118(match p
119 ((: point y:) y)) ; only match y field
120```
122## Dict Patterns
124Use `#{ key: pat ... }` or `(dict key: ...)` to match dicts by key:
126```scheme
127(match config
128 (#{ host: port: } (connect host port))
129 ((dict debug:) debug))
131;; Type check only
132(match val
133 ((dict) 'is-dict)
134 (_ 'other))
135```
137## Convenience Forms
139```scheme
140;; match-lambda: anonymous function with pattern matching
141(define get-x (match-lambda ((x . _) x)))
142(get-x '(1 2 3)) ; => 1
144;; match-lambda*: match all arguments as a list
145(define add-pair
146 (match-lambda* ((a b) (+ a b))))
147(add-pair 3 4) ; => 7
149;; match-let: destructuring let
150(match-let (((x y) '(1 2))
151 ((a . b) '(3 4 5)))
152 (list x y a b))
153; => (1 2 3 (4 5))
154```
156## Exports
158- `match` - Main matching macro
159- `match-lambda` - Single-argument matching lambda
160- `match-lambda*` - Multi-argument matching lambda
161- `match-let` - Destructuring let with patterns
162- `match-pattern` - Low-level pattern matching (used internally)
164## Dependencies
166- sigil-stdlib
168## Building
170```
171sigil deps install
172sigil build
173sigil test
174```
176## License
178BSD-3-Clause