1 ;;; pcase.el --- ML-style pattern-matching macro for Elisp
3 ;; Copyright (C) 2010, 2011 Free Software Foundation, Inc.
5 ;; Author: Stefan Monnier <monnier@iro.umontreal.ca>
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;; ML-style pattern matching.
26 ;; The entry points are autoloaded.
30 ;; - provide ways to extend the set of primitives, with some kind of
31 ;; define-pcase-matcher. We could easily make it so that (guard BOOLEXP)
32 ;; could be defined this way, as a shorthand for (pred (lambda (_) BOOLEXP)).
33 ;; But better would be if we could define new ways to match by having the
34 ;; extension provide its own `pcase--split-<foo>' thingy.
35 ;; - ideally we'd want (pcase s ((re RE1) E1) ((re RE2) E2)) to be able to
36 ;; generate a lex-style DFA to decide whether to run E1 or E2.
40 (eval-when-compile (require 'cl))
42 ;; Macro-expansion of pcase is reasonably fast, so it's not a problem
43 ;; when byte-compiling a file, but when interpreting the code, if the pcase
44 ;; is in a loop, the repeated macro-expansion becomes terribly costly, so we
45 ;; memoize previous macro expansions to try and avoid recomputing them
46 ;; over and over again.
47 (defconst pcase-memoize (make-hash-table :weakness t :test 'equal))
49 (defconst pcase--dontcare-upats '(t _ dontcare))
52 (defmacro pcase (exp &rest cases)
53 "Perform ML-style pattern matching on EXP.
54 CASES is a list of elements of the form (UPATTERN CODE...).
56 UPatterns can take the following forms:
58 SYMBOL matches anything and binds it to SYMBOL.
59 (or UPAT...) matches if any of the patterns matches.
60 (and UPAT...) matches if all the patterns match.
61 `QPAT matches if the QPattern QPAT matches.
62 (pred PRED) matches if PRED applied to the object returns non-nil.
63 (guard BOOLEXP) matches if BOOLEXP evaluates to non-nil.
65 QPatterns can take the following forms:
66 (QPAT1 . QPAT2) matches if QPAT1 matches the car and QPAT2 the cdr.
67 ,UPAT matches if the UPattern UPAT matches.
68 STRING matches if the object is `equal' to STRING.
69 ATOM matches if the object is `eq' to ATOM.
70 QPatterns for vectors are not implemented yet.
72 PRED can take the form
73 FUNCTION in which case it gets called with one argument.
74 (FUN ARG1 .. ARGN) in which case it gets called with N+1 arguments.
75 A PRED of the form FUNCTION is equivalent to one of the form (FUNCTION).
76 PRED patterns can refer to variables bound earlier in the pattern.
77 E.g. you can match pairs where the cdr is larger than the car with a pattern
78 like `(,a . ,(pred (< a))) or, with more checks:
79 `(,(and a (pred numberp)) . ,(and (pred numberp) (pred (< a))))"
80 (declare (indent 1) (debug case)) ;FIXME: edebug `guard' and vars.
81 (or (gethash (cons exp cases) pcase-memoize)
82 (puthash (cons exp cases)
83 (pcase--expand exp cases)
87 (defmacro pcase-let* (bindings &rest body)
88 "Like `let*' but where you can use `pcase' patterns for bindings.
89 BODY should be an expression, and BINDINGS should be a list of bindings
90 of the form (UPAT EXP)."
91 (declare (indent 1) (debug let))
93 ((null bindings) (if (> (length body) 1) `(progn ,@body) (car body)))
94 ((pcase--trivial-upat-p (caar bindings))
95 `(let (,(car bindings)) (pcase-let* ,(cdr bindings) ,@body)))
97 `(pcase ,(cadr (car bindings))
98 (,(caar bindings) (pcase-let* ,(cdr bindings) ,@body))
99 ;; We can either signal an error here, or just use `dontcare' which
100 ;; generates more efficient code. In practice, if we use `dontcare' we
101 ;; will still often get an error and the few cases where we don't do not
102 ;; matter that much, so it's a better choice.
106 (defmacro pcase-let (bindings &rest body)
107 "Like `let' but where you can use `pcase' patterns for bindings.
108 BODY should be a list of expressions, and BINDINGS should be a list of bindings
109 of the form (UPAT EXP)."
110 (declare (indent 1) (debug let))
111 (if (null (cdr bindings))
112 `(pcase-let* ,bindings ,@body)
114 (dolist (binding (prog1 bindings (setq bindings nil)))
116 ((memq (car binding) pcase--dontcare-upats)
117 (push (cons (make-symbol "_") (cdr binding)) bindings))
118 ((pcase--trivial-upat-p (car binding)) (push binding bindings))
120 (let ((tmpvar (make-symbol (format "x%d" (length bindings)))))
121 (push (cons tmpvar (cdr binding)) bindings)
122 (push (list (car binding) tmpvar) matches)))))
123 `(let ,(nreverse bindings) (pcase-let* ,matches ,@body)))))
125 (defmacro pcase-dolist (spec &rest body)
126 (if (pcase--trivial-upat-p (car spec))
127 `(dolist ,spec ,@body)
128 (let ((tmpvar (make-symbol "x")))
129 `(dolist (,tmpvar ,@(cdr spec))
130 (pcase-let* ((,(car spec) ,tmpvar))
134 (defun pcase--trivial-upat-p (upat)
135 (and (symbolp upat) (not (memq upat pcase--dontcare-upats))))
137 (defun pcase--expand (exp cases)
138 (let* ((defs (if (symbolp exp) '()
139 (let ((sym (make-symbol "x")))
140 (prog1 `((,sym ,exp)) (setq exp sym)))))
144 (let ((prev (assq code seen)))
146 (let ((res (pcase-codegen code vars)))
147 (push (list code vars res) seen)
149 ;; Since we use a tree-based pattern matching
150 ;; technique, the leaves (the places that contain the
151 ;; code to run once a pattern is matched) can get
152 ;; copied a very large number of times, so to avoid
153 ;; code explosion, we need to keep track of how many
154 ;; times we've used each leaf and move it
155 ;; to a separate function if that number is too high.
157 ;; We've already used this branch. So it is shared.
158 (destructuring-bind (code prevvars res) prev
159 (unless (symbolp res)
160 ;; This is the first repeat, so we have to move
161 ;; the branch to a separate function.
163 (make-symbol (format "pcase-%d" (length defs)))))
164 (push `(,bsym (lambda ,(mapcar #'car prevvars) ,@code)) defs)
165 (setcar res 'funcall)
166 (setcdr res (cons bsym (mapcar #'cdr prevvars)))
167 (setcar (cddr prev) bsym)
169 (setq vars (copy-sequence vars))
170 (let ((args (mapcar (lambda (pa)
171 (let ((v (assq (car pa) vars)))
172 (setq vars (delq v vars))
175 (when vars ;New additional vars.
176 (error "The vars %s are only bound in some paths"
177 (mapcar #'car vars)))
178 `(funcall ,res ,@args)))))))
181 (mapcar (lambda (case)
182 `((match ,exp . ,(car case))
184 (if (pcase--small-branch-p (cdr case))
185 ;; Don't bother sharing multiple
186 ;; occurrences of this leaf since it's small.
187 #'pcase-codegen codegen)
191 `(let ,defs ,main))))
193 (defun pcase-codegen (code vars)
194 `(let ,(mapcar (lambda (b) (list (car b) (cdr b))) vars)
197 (defun pcase--small-branch-p (code)
198 (and (= 1 (length code))
199 (or (not (consp (car code)))
201 (dolist (e (car code))
202 (if (consp e) (setq small nil)))
205 ;; Try to use `cond' rather than a sequence of `if's, so as to reduce
206 ;; the depth of the generated tree.
207 (defun pcase--if (test then else)
209 ((eq else :pcase--dontcare) then)
210 ((eq (car-safe else) 'if)
211 (if (equal test (nth 1 else))
212 ;; Doing a test a second time: get rid of the redundancy.
213 ;; FIXME: ideally, this should never happen because the pcase--split-*
214 ;; funs should have eliminated such things, but pcase--split-member
215 ;; is imprecise, so in practice it can happen occasionally.
216 `(if ,test ,then ,@(nthcdr 3 else))
218 (,(nth 1 else) ,(nth 2 else))
219 (t ,@(nthcdr 3 else)))))
220 ((eq (car-safe else) 'cond)
222 ;; Doing a test a second time: get rid of the redundancy, as above.
223 ,@(remove (assoc test else) (cdr else))))
224 (t `(if ,test ,then ,else))))
226 (defun pcase--upat (qpattern)
228 ((eq (car-safe qpattern) '\,) (cadr qpattern))
229 (t (list '\` qpattern))))
232 ;; When we have patterns like `(PAT1 . PAT2), after performing the `consp'
233 ;; check, we want to turn all the similar patterns into ones of the form
234 ;; (and (match car PAT1) (match cdr PAT2)), so you naturally need conjunction.
235 ;; Earlier code hence used branches of the form (MATCHES . CODE) where
236 ;; MATCHES was a list (implicitly a conjunction) of (SYM . PAT).
237 ;; But if we have a pattern of the form (or `(PAT1 . PAT2) PAT3), there is
238 ;; no easy way to eliminate the `consp' check in such a representation.
239 ;; So we replaced the MATCHES by the MATCH below which can be made up
240 ;; of conjunctions and disjunctions, so if we know `foo' is a cons, we can
241 ;; turn (match foo . (or `(PAT1 . PAT2) PAT3)) into
242 ;; (or (and (match car . `PAT1) (match cdr . `PAT2)) (match foo . PAT3)).
243 ;; The downside is that we now have `or' and `and' both in MATCH and
244 ;; in PAT, so there are different equivalent representations and we
245 ;; need to handle them all. We do not try to systematically
246 ;; canonicalize them to one form over another, but we do occasionally
247 ;; turn one into the other.
249 (defun pcase--u (branches)
250 "Expand matcher for rules BRANCHES.
251 Each BRANCH has the form (MATCH CODE . VARS) where
252 CODE is the code generator for that branch.
253 VARS is the set of vars already bound by earlier matches.
254 MATCH is the pattern that needs to be matched, of the form:
258 (when (setq branches (delq nil branches))
259 (destructuring-bind (match code &rest vars) (car branches)
260 (pcase--u1 (list match) code vars (cdr branches)))))
262 (defun pcase--and (match matches)
263 (if matches `(and ,match ,@matches) match))
265 (defun pcase--split-match (sym splitter match)
268 (if (not (eq sym (cadr match)))
270 (let ((pat (cddr match)))
272 ;; Hoist `or' and `and' patterns to `or' and `and' matches.
273 ((memq (car-safe pat) '(or and))
274 (pcase--split-match sym splitter
276 (mapcar (lambda (alt)
277 `(match ,sym . ,alt))
279 (t (let ((res (funcall splitter (cddr match))))
280 (cons (or (car res) match) (or (cdr res) match))))))))
282 (let ((then-alts '())
284 (neutral-elem (if (eq 'or (car match))
285 :pcase--fail :pcase--succeed))
286 (zero-elem (if (eq 'or (car match)) :pcase--succeed :pcase--fail)))
287 (dolist (alt (cdr match))
288 (let ((split (pcase--split-match sym splitter alt)))
289 (unless (eq (car split) neutral-elem)
290 (push (car split) then-alts))
291 (unless (eq (cdr split) neutral-elem)
292 (push (cdr split) else-alts))))
293 (cons (cond ((memq zero-elem then-alts) zero-elem)
294 ((null then-alts) neutral-elem)
295 ((null (cdr then-alts)) (car then-alts))
296 (t (cons (car match) (nreverse then-alts))))
297 (cond ((memq zero-elem else-alts) zero-elem)
298 ((null else-alts) neutral-elem)
299 ((null (cdr else-alts)) (car else-alts))
300 (t (cons (car match) (nreverse else-alts)))))))
301 (t (error "Uknown MATCH %s" match))))
303 (defun pcase--split-rest (sym splitter rest)
304 (let ((then-rest '())
306 (dolist (branch rest)
307 (let* ((match (car branch))
308 (code&vars (cdr branch))
310 (pcase--split-match sym splitter match)))
311 (unless (eq (car splitted) :pcase--fail)
312 (push (cons (car splitted) code&vars) then-rest))
313 (unless (eq (cdr splitted) :pcase--fail)
314 (push (cons (cdr splitted) code&vars) else-rest))))
315 (cons (nreverse then-rest) (nreverse else-rest))))
317 (defun pcase--split-consp (syma symd pat)
319 ;; A QPattern for a cons, can only go the `then' side.
320 ((and (eq (car-safe pat) '\`) (consp (cadr pat)))
321 (let ((qpat (cadr pat)))
322 (cons `(and (match ,syma . ,(pcase--upat (car qpat)))
323 (match ,symd . ,(pcase--upat (cdr qpat))))
325 ;; A QPattern but not for a cons, can only go the `else' side.
326 ((eq (car-safe pat) '\`) (cons :pcase--fail nil))))
328 (defun pcase--split-equal (elem pat)
330 ;; The same match will give the same result.
331 ((and (eq (car-safe pat) '\`) (equal (cadr pat) elem))
332 (cons :pcase--succeed :pcase--fail))
333 ;; A different match will fail if this one succeeds.
334 ((and (eq (car-safe pat) '\`)
335 ;; (or (integerp (cadr pat)) (symbolp (cadr pat))
336 ;; (consp (cadr pat)))
338 (cons :pcase--fail nil))))
340 (defun pcase--split-member (elems pat)
341 ;; Based on pcase--split-equal.
343 ;; The same match (or a match of membership in a superset) will
344 ;; give the same result, but we don't know how to check it.
346 ;; (cons :pcase--succeed nil))
347 ;; A match for one of the elements may succeed or fail.
348 ((and (eq (car-safe pat) '\`) (member (cadr pat) elems))
350 ;; A different match will fail if this one succeeds.
351 ((and (eq (car-safe pat) '\`)
352 ;; (or (integerp (cadr pat)) (symbolp (cadr pat))
353 ;; (consp (cadr pat)))
355 (cons :pcase--fail nil))))
357 (defun pcase--split-pred (upat pat)
358 ;; FIXME: For predicates like (pred (> a)), two such predicates may
359 ;; actually refer to different variables `a'.
361 (cons :pcase--succeed :pcase--fail)))
363 (defun pcase--fgrep (vars sexp)
364 "Check which of the symbols VARS appear in SEXP."
367 (dolist (var (pcase--fgrep vars (pop sexp)))
368 (unless (memq var res) (push var res))))
369 (and (memq sexp vars) (not (memq sexp res)) (push sexp res))
372 ;; It's very tempting to use `pcase' below, tho obviously, it'd create
373 ;; bootstrapping problems.
374 (defun pcase--u1 (matches code vars rest)
375 "Return code that runs CODE (with VARS) if MATCHES match.
376 and otherwise defers to REST which is a list of branches of the form
377 \(ELSE-MATCH ELSE-CODE . ELSE-VARS)."
378 ;; Depending on the order in which we choose to check each of the MATCHES,
379 ;; the resulting tree may be smaller or bigger. So in general, we'd want
380 ;; to be careful to chose the "optimal" order. But predicate
381 ;; patterns make this harder because they create dependencies
382 ;; between matches. So we don't bother trying to reorder anything.
384 ((null matches) (funcall code vars))
385 ((eq :pcase--fail (car matches)) (pcase--u rest))
386 ((eq :pcase--succeed (car matches))
387 (pcase--u1 (cdr matches) code vars rest))
388 ((eq 'and (caar matches))
389 (pcase--u1 (append (cdar matches) (cdr matches)) code vars rest))
390 ((eq 'or (caar matches))
391 (let* ((alts (cdar matches))
392 (var (if (eq (caar alts) 'match) (cadr (car alts))))
393 (simples '()) (others '()))
396 (if (and (eq (car alt) 'match) (eq var (cadr alt))
397 (let ((upat (cddr alt)))
398 (and (eq (car-safe upat) '\`)
399 (or (integerp (cadr upat)) (symbolp (cadr upat))
400 (stringp (cadr upat))))))
401 (push (cddr alt) simples)
404 ((null alts) (error "Please avoid it") (pcase--u rest))
405 ((> (length simples) 1)
406 ;; De-hoist the `or' MATCH into an `or' pattern that will be
407 ;; turned into a `memq' below.
408 (pcase--u1 (cons `(match ,var or . ,(nreverse simples)) (cdr matches))
410 (if (null others) rest
412 (pcase--and (if (cdr others)
413 (cons 'or (nreverse others))
419 (pcase--u1 (cons (pop alts) (cdr matches)) code vars
420 (if (null alts) (progn (error "Please avoid it") rest)
422 (pcase--and (if (cdr alts)
423 (cons 'or alts) (car alts))
427 ((eq 'match (caar matches))
428 (destructuring-bind (op sym &rest upat) (pop matches)
430 ((memq upat '(t _)) (pcase--u1 matches code vars rest))
431 ((eq upat 'dontcare) :pcase--dontcare)
432 ((functionp upat) (error "Feature removed, use (pred %s)" upat))
433 ((memq (car-safe upat) '(guard pred))
434 (destructuring-bind (then-rest &rest else-rest)
436 sym (apply-partially #'pcase--split-pred upat) rest)
437 (pcase--if (if (and (eq (car upat) 'pred) (symbolp (cadr upat)))
439 (let* ((exp (cadr upat))
440 ;; `vs' is an upper bound on the vars we need.
441 (vs (pcase--fgrep (mapcar #'car vars) exp))
443 ((eq 'guard (car upat)) exp)
444 ((functionp exp) `(,exp ,sym))
448 ;; Let's not replace `vars' in `exp' since it's
449 ;; too difficult to do it right, instead just
450 ;; let-bind `vars' around `exp'.
451 `(let ,(mapcar (lambda (var)
452 (list var (cdr (assq var vars))))
454 ;; FIXME: `vars' can capture `sym'. E.g.
455 ;; (pcase x ((and `(,x . ,y) (pred (fun x)))))
457 (pcase--u1 matches code vars then-rest)
458 (pcase--u else-rest))))
460 (pcase--u1 matches code (cons (cons upat sym) vars) rest))
461 ((eq (car-safe upat) '\`)
462 (pcase--q1 sym (cadr upat) matches code vars rest))
463 ((eq (car-safe upat) 'or)
464 (let ((all (> (length (cdr upat)) 1))
467 (dolist (alt (cdr upat))
468 (unless (and (eq (car-safe alt) '\`)
469 (or (symbolp (cadr alt)) (integerp (cadr alt))
471 (stringp (cadr alt))))
474 ;; Use memq for (or `a `b `c `d) rather than a big tree.
475 (let ((elems (mapcar 'cadr (cdr upat))))
476 (destructuring-bind (then-rest &rest else-rest)
478 sym (apply-partially #'pcase--split-member elems) rest)
479 (pcase--if `(,(if memq-fine #'memq #'member) ,sym ',elems)
480 (pcase--u1 matches code vars then-rest)
481 (pcase--u else-rest))))
482 (pcase--u1 (cons `(match ,sym ,@(cadr upat)) matches) code vars
483 (append (mapcar (lambda (upat)
484 `((and (match ,sym . ,upat) ,@matches)
488 ((eq (car-safe upat) 'and)
489 (pcase--u1 (append (mapcar (lambda (upat) `(match ,sym ,@upat))
493 ((eq (car-safe upat) 'not)
494 ;; FIXME: The implementation below is naive and results in
496 ;; To make it work right, we would need to turn pcase--u1's
497 ;; `code' and `vars' into a single argument of the same form as
498 ;; `rest'. We would also need to split this new `then-rest' argument
499 ;; for every test (currently we don't bother to do it since
500 ;; it's only useful for odd patterns like (and `(PAT1 . PAT2)
501 ;; `(PAT3 . PAT4)) which the programmer can easily rewrite
502 ;; to the more efficient `(,(and PAT1 PAT3) . ,(and PAT2 PAT4))).
503 (pcase--u1 `((match ,sym . ,(cadr upat)))
504 (lexical-let ((rest rest))
505 ;; FIXME: This codegen is not careful to share its
506 ;; code if used several times: code blow up is likely.
508 ;; `vars' will likely contain bindings which are
509 ;; not always available in other paths to
510 ;; `rest', so there' no point trying to pass
514 (list `((and . ,matches) ,code . ,vars))))
515 (t (error "Unknown upattern `%s'" upat)))))
516 (t (error "Incorrect MATCH %s" (car matches)))))
518 (defun pcase--q1 (sym qpat matches code vars rest)
519 "Return code that runs CODE if SYM matches QPAT and if MATCHES match.
520 and if not, defers to REST which is a list of branches of the form
521 \(OTHER_MATCH OTHER-CODE . OTHER-VARS)."
523 ((eq (car-safe qpat) '\,) (error "Can't use `,UPATTERN"))
524 ((floatp qpat) (error "Floating point patterns not supported"))
527 (error "Vector QPatterns not implemented yet"))
529 (let ((syma (make-symbol "xcar"))
530 (symd (make-symbol "xcdr")))
531 (destructuring-bind (then-rest &rest else-rest)
532 (pcase--split-rest sym
533 (apply-partially #'pcase--split-consp syma symd)
535 (pcase--if `(consp ,sym)
536 `(let ((,syma (car ,sym))
538 ,(pcase--u1 `((match ,syma . ,(pcase--upat (car qpat)))
539 (match ,symd . ,(pcase--upat (cdr qpat)))
541 code vars then-rest))
542 (pcase--u else-rest)))))
543 ((or (integerp qpat) (symbolp qpat) (stringp qpat))
544 (destructuring-bind (then-rest &rest else-rest)
545 (pcase--split-rest sym (apply-partially 'pcase--split-equal qpat) rest)
546 (pcase--if `(,(if (stringp qpat) #'equal #'eq) ,sym ',qpat)
547 (pcase--u1 matches code vars then-rest)
548 (pcase--u else-rest))))
549 (t (error "Unkown QPattern %s" qpat))))
553 ;;; pcase.el ends here