* src/fileio.c: Don't convert \r to \n just because of C-x $
[emacs.git] / lisp / emacs-lisp / pcase.el
blob9de24015494029da00abc0aea4adfcdc11d5718a
1 ;;; pcase.el --- ML-style pattern-matching macro for Elisp -*- lexical-binding: t -*-
3 ;; Copyright (C) 2010-2019 Free Software Foundation, Inc.
5 ;; Author: Stefan Monnier <monnier@iro.umontreal.ca>
6 ;; Keywords:
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 <https://www.gnu.org/licenses/>.
23 ;;; Commentary:
25 ;; ML-style pattern matching.
26 ;; The entry points are autoloaded.
28 ;; Todo:
30 ;; - (pcase e (`(,x . ,x) foo)) signals an "x unused" warning if `foo' doesn't
31 ;; use x, because x is bound separately for the equality constraint
32 ;; (as well as any pred/guard) and for the body, so uses at one place don't
33 ;; count for the other.
34 ;; - provide ways to extend the set of primitives, with some kind of
35 ;; define-pcase-matcher. We could easily make it so that (guard BOOLEXP)
36 ;; could be defined this way, as a shorthand for (pred (lambda (_) BOOLEXP)).
37 ;; But better would be if we could define new ways to match by having the
38 ;; extension provide its own `pcase--split-<foo>' thingy.
39 ;; - along these lines, provide patterns to match CL structs.
40 ;; - provide something like (setq VAR) so a var can be set rather than
41 ;; let-bound.
42 ;; - provide a way to fallthrough to subsequent cases (not sure what I meant by
43 ;; this :-()
44 ;; - try and be more clever to reduce the size of the decision tree, and
45 ;; to reduce the number of leaves that need to be turned into function:
46 ;; - first, do the tests shared by all remaining branches (it will have
47 ;; to be performed anyway, so better do it first so it's shared).
48 ;; - then choose the test that discriminates more (?).
49 ;; - provide Agda's `with' (along with its `...' companion).
50 ;; - implement (not PAT). This might require a significant redesign.
51 ;; - ideally we'd want (pcase s ((re RE1) E1) ((re RE2) E2)) to be able to
52 ;; generate a lex-style DFA to decide whether to run E1 or E2.
54 ;;; Code:
56 (require 'macroexp)
58 ;; Macro-expansion of pcase is reasonably fast, so it's not a problem
59 ;; when byte-compiling a file, but when interpreting the code, if the pcase
60 ;; is in a loop, the repeated macro-expansion becomes terribly costly, so we
61 ;; memoize previous macro expansions to try and avoid recomputing them
62 ;; over and over again.
63 ;; FIXME: Now that macroexpansion is also performed when loading an interpreted
64 ;; file, this is not a real problem any more.
65 (defconst pcase--memoize (make-hash-table :weakness 'key :test 'eq))
66 ;; (defconst pcase--memoize (make-hash-table :test 'eq))
67 ;; (defconst pcase--memoize-1 (make-hash-table :test 'eq))
68 ;; (defconst pcase--memoize-2 (make-hash-table :weakness 'key :test 'equal))
70 (defconst pcase--dontcare-upats '(t _ pcase--dontcare))
72 (defvar pcase--dontwarn-upats '(pcase--dontcare))
74 (def-edebug-spec
75 pcase-PAT
76 (&or symbolp
77 ("or" &rest pcase-PAT)
78 ("and" &rest pcase-PAT)
79 ("guard" form)
80 ("let" pcase-PAT form)
81 ("pred" pcase-FUN)
82 ("app" pcase-FUN pcase-PAT)
83 pcase-MACRO
84 sexp))
86 (def-edebug-spec
87 pcase-FUN
88 (&or lambda-expr
89 ;; Punt on macros/special forms.
90 (functionp &rest form)
91 sexp))
93 ;; See bug#24717
94 (put 'pcase-MACRO 'edebug-form-spec 'pcase--edebug-match-macro)
96 ;; Only called from edebug.
97 (declare-function get-edebug-spec "edebug" (symbol))
98 (declare-function edebug-match "edebug" (cursor specs))
100 (defun pcase--edebug-match-macro (cursor)
101 (let (specs)
102 (mapatoms
103 (lambda (s)
104 (let ((m (get s 'pcase-macroexpander)))
105 (when (and m (get-edebug-spec m))
106 (push (cons (symbol-name s) (get-edebug-spec m))
107 specs)))))
108 (edebug-match cursor (cons '&or specs))))
110 ;;;###autoload
111 (defmacro pcase (exp &rest cases)
112 "Evaluate EXP to get EXPVAL; try passing control to one of CASES.
113 CASES is a list of elements of the form (PATTERN CODE...).
114 For the first CASE whose PATTERN \"matches\" EXPVAL,
115 evaluate its CODE..., and return the value of the last form.
116 If no CASE has a PATTERN that matches, return nil.
118 Each PATTERN expands, in essence, to a predicate to call
119 on EXPVAL. When the return value of that call is non-nil,
120 PATTERN matches. PATTERN can take one of the forms:
122 _ matches anything.
123 \\='VAL matches if EXPVAL is `equal' to VAL.
124 KEYWORD shorthand for \\='KEYWORD
125 INTEGER shorthand for \\='INTEGER
126 STRING shorthand for \\='STRING
127 SYMBOL matches anything and binds it to SYMBOL.
128 If a SYMBOL is used twice in the same pattern
129 the second occurrence becomes an `eq'uality test.
130 (pred FUN) matches if FUN called on EXPVAL returns non-nil.
131 (app FUN PAT) matches if FUN called on EXPVAL matches PAT.
132 (guard BOOLEXP) matches if BOOLEXP evaluates to non-nil.
133 (let PAT EXPR) matches if EXPR matches PAT.
134 (and PAT...) matches if all the patterns match.
135 (or PAT...) matches if any of the patterns matches.
137 FUN in `pred' and `app' can take one of the forms:
138 SYMBOL or (lambda ARGS BODY)
139 call it with one argument
140 (F ARG1 .. ARGn)
141 call F with ARG1..ARGn and EXPVAL as n+1'th argument
143 FUN, BOOLEXP, EXPR, and subsequent PAT can refer to variables
144 bound earlier in the pattern by a SYMBOL pattern.
146 Additional patterns can be defined using `pcase-defmacro'.
148 See Info node `(elisp) Pattern-Matching Conditional' in the
149 Emacs Lisp manual for more information and examples."
150 (declare (indent 1) (debug (form &rest (pcase-PAT body))))
151 ;; We want to use a weak hash table as a cache, but the key will unavoidably
152 ;; be based on `exp' and `cases', yet `cases' is a fresh new list each time
153 ;; we're called so it'll be immediately GC'd. So we use (car cases) as key
154 ;; which does come straight from the source code and should hence not be GC'd
155 ;; so easily.
156 (let ((data (gethash (car cases) pcase--memoize)))
157 ;; data = (EXP CASES . EXPANSION)
158 (if (and (equal exp (car data)) (equal cases (cadr data)))
159 ;; We have the right expansion.
160 (cddr data)
161 ;; (when (gethash (car cases) pcase--memoize-1)
162 ;; (message "pcase-memoize failed because of weak key!!"))
163 ;; (when (gethash (car cases) pcase--memoize-2)
164 ;; (message "pcase-memoize failed because of eq test on %S"
165 ;; (car cases)))
166 ;; (when data
167 ;; (message "pcase-memoize: equal first branch, yet different"))
168 (let ((expansion (pcase--expand exp cases)))
169 (puthash (car cases) `(,exp ,cases ,@expansion) pcase--memoize)
170 ;; (puthash (car cases) `(,exp ,cases ,@expansion) pcase--memoize-1)
171 ;; (puthash (car cases) `(,exp ,cases ,@expansion) pcase--memoize-2)
172 expansion))))
174 (declare-function help-fns--signature "help-fns"
175 (function doc real-def real-function buffer))
177 ;; FIXME: Obviously, this will collide with nadvice's use of
178 ;; function-documentation if we happen to advise `pcase'.
179 ;;;###autoload
180 (put 'pcase 'function-documentation '(pcase--make-docstring))
181 ;;;###autoload
182 (defun pcase--make-docstring ()
183 (let* ((main (documentation (symbol-function 'pcase) 'raw))
184 (ud (help-split-fundoc main 'pcase)))
185 ;; So that eg emacs -Q -l cl-lib --eval "(documentation 'pcase)" works,
186 ;; where cl-lib is anything using pcase-defmacro.
187 (require 'help-fns)
188 (with-temp-buffer
189 (insert (or (cdr ud) main))
190 ;; Presentation Note: For conceptual continuity, we guarantee
191 ;; that backquote doc immediately follows main pcase doc.
192 ;; (The order of the other extensions is unimportant.)
193 (let (more)
194 ;; Collect all the extensions.
195 (mapatoms (lambda (symbol)
196 (let ((me (get symbol 'pcase-macroexpander)))
197 (when me
198 (push (cons symbol me)
199 more)))))
200 ;; Ensure backquote is first.
201 (let ((x (assq '\` more)))
202 (setq more (cons x (delq x more))))
203 ;; Do the output.
204 (while more
205 (let* ((pair (pop more))
206 (symbol (car pair))
207 (me (cdr pair))
208 (doc (documentation me 'raw)))
209 (insert "\n\n-- ")
210 (setq doc (help-fns--signature symbol doc me
211 (indirect-function me)
212 nil))
213 (insert "\n" (or doc "Not documented.")))))
214 (let ((combined-doc (buffer-string)))
215 (if ud (help-add-fundoc-usage combined-doc (car ud)) combined-doc)))))
217 ;;;###autoload
218 (defmacro pcase-exhaustive (exp &rest cases)
219 "The exhaustive version of `pcase' (which see).
220 If EXP fails to match any of the patterns in CASES, an error is signaled."
221 (declare (indent 1) (debug pcase))
222 (let* ((x (gensym "x"))
223 (pcase--dontwarn-upats (cons x pcase--dontwarn-upats)))
224 (pcase--expand
225 ;; FIXME: Could we add the FILE:LINE data in the error message?
226 exp (append cases `((,x (error "No clause matching `%S'" ,x)))))))
228 ;;;###autoload
229 (defmacro pcase-lambda (lambda-list &rest body)
230 "Like `lambda' but allow each argument to be a pattern.
231 I.e. accepts the usual &optional and &rest keywords, but every
232 formal argument can be any pattern accepted by `pcase' (a mere
233 variable name being but a special case of it)."
234 (declare (doc-string 2) (indent defun)
235 (debug (&define (&rest pcase-PAT) lambda-doc def-body)))
236 (let* ((bindings ())
237 (parsed-body (macroexp-parse-body body))
238 (args (mapcar (lambda (pat)
239 (if (symbolp pat)
240 ;; Simple vars and &rest/&optional are just passed
241 ;; through unchanged.
243 (let ((arg (make-symbol
244 (format "arg%s" (length bindings)))))
245 (push `(,pat ,arg) bindings)
246 arg)))
247 lambda-list)))
248 `(lambda ,args ,@(car parsed-body)
249 (pcase-let* ,(nreverse bindings) ,@(cdr parsed-body)))))
251 (defun pcase--let* (bindings body)
252 (cond
253 ((null bindings) (macroexp-progn body))
254 ((pcase--trivial-upat-p (caar bindings))
255 (macroexp-let* `(,(car bindings)) (pcase--let* (cdr bindings) body)))
257 (let ((binding (pop bindings)))
258 (pcase--expand
259 (cadr binding)
260 `((,(car binding) ,(pcase--let* bindings body))
261 ;; We can either signal an error here, or just use `pcase--dontcare'
262 ;; which generates more efficient code. In practice, if we use
263 ;; `pcase--dontcare' we will still often get an error and the few
264 ;; cases where we don't do not matter that much, so
265 ;; it's a better choice.
266 (pcase--dontcare nil)))))))
268 ;;;###autoload
269 (defmacro pcase-let* (bindings &rest body)
270 "Like `let*', but supports destructuring BINDINGS using `pcase' patterns.
271 As with `pcase-let', BINDINGS are of the form (PATTERN EXP), but the
272 EXP in each binding in BINDINGS can use the results of the destructuring
273 bindings that precede it in BINDINGS' order.
275 Each EXP should match (i.e. be of compatible structure) to its
276 respective PATTERN; a mismatch may signal an error or may go
277 undetected, binding variables to arbitrary values, such as nil."
278 (declare (indent 1)
279 (debug ((&rest (pcase-PAT &optional form)) body)))
280 (let ((cached (gethash bindings pcase--memoize)))
281 ;; cached = (BODY . EXPANSION)
282 (if (equal (car cached) body)
283 (cdr cached)
284 (let ((expansion (pcase--let* bindings body)))
285 (puthash bindings (cons body expansion) pcase--memoize)
286 expansion))))
288 ;;;###autoload
289 (defmacro pcase-let (bindings &rest body)
290 "Like `let', but supports destructuring BINDINGS using `pcase' patterns.
291 BODY should be a list of expressions, and BINDINGS should be a list of
292 bindings of the form (PATTERN EXP).
293 All EXPs are evaluated first, and then used to perform destructuring
294 bindings by matching each EXP against its respective PATTERN. Then
295 BODY is evaluated with those bindings in effect.
297 Each EXP should match (i.e. be of compatible structure) to its
298 respective PATTERN; a mismatch may signal an error or may go
299 undetected, binding variables to arbitrary values, such as nil."
300 (declare (indent 1) (debug pcase-let*))
301 (if (null (cdr bindings))
302 `(pcase-let* ,bindings ,@body)
303 (let ((matches '()))
304 (dolist (binding (prog1 bindings (setq bindings nil)))
305 (cond
306 ((memq (car binding) pcase--dontcare-upats)
307 (push (cons (make-symbol "_") (cdr binding)) bindings))
308 ((pcase--trivial-upat-p (car binding)) (push binding bindings))
310 (let ((tmpvar (make-symbol (format "x%d" (length bindings)))))
311 (push (cons tmpvar (cdr binding)) bindings)
312 (push (list (car binding) tmpvar) matches)))))
313 `(let ,(nreverse bindings) (pcase-let* ,matches ,@body)))))
315 ;;;###autoload
316 (defmacro pcase-dolist (spec &rest body)
317 "Eval BODY once for each set of bindings defined by PATTERN and LIST elements.
318 PATTERN should be a `pcase' pattern describing the structure of
319 LIST elements, and LIST is a list of objects that match PATTERN,
320 i.e. have a structure that is compatible with PATTERN.
321 For each element of LIST, this macro binds the variables in
322 PATTERN to the corresponding subfields of the LIST element, and
323 then evaluates BODY with these bindings in effect. The
324 destructuring bindings of variables in PATTERN to the subfields
325 of the elements of LIST is performed as if by `pcase-let'.
326 \n(fn (PATTERN LIST) BODY...)"
327 (declare (indent 1) (debug ((pcase-PAT form) body)))
328 (if (pcase--trivial-upat-p (car spec))
329 `(dolist ,spec ,@body)
330 (let ((tmpvar (gensym "x")))
331 `(dolist (,tmpvar ,@(cdr spec))
332 (pcase-let* ((,(car spec) ,tmpvar))
333 ,@body)))))
336 (defun pcase--trivial-upat-p (upat)
337 (and (symbolp upat) (not (memq upat pcase--dontcare-upats))))
339 (defun pcase--expand (exp cases)
340 ;; (message "pid=%S (pcase--expand %S ...hash=%S)"
341 ;; (emacs-pid) exp (sxhash cases))
342 (macroexp-let2 macroexp-copyable-p val exp
343 (let* ((defs ())
344 (seen '())
345 (codegen
346 (lambda (code vars)
347 (let ((prev (assq code seen)))
348 (if (not prev)
349 (let ((res (pcase-codegen code vars)))
350 (push (list code vars res) seen)
351 res)
352 ;; Since we use a tree-based pattern matching
353 ;; technique, the leaves (the places that contain the
354 ;; code to run once a pattern is matched) can get
355 ;; copied a very large number of times, so to avoid
356 ;; code explosion, we need to keep track of how many
357 ;; times we've used each leaf and move it
358 ;; to a separate function if that number is too high.
360 ;; We've already used this branch. So it is shared.
361 (let* ((code (car prev)) (cdrprev (cdr prev))
362 (prevvars (car cdrprev)) (cddrprev (cdr cdrprev))
363 (res (car cddrprev)))
364 (unless (symbolp res)
365 ;; This is the first repeat, so we have to move
366 ;; the branch to a separate function.
367 (let ((bsym
368 (make-symbol (format "pcase-%d" (length defs)))))
369 (push `(,bsym (lambda ,(mapcar #'car prevvars) ,@code))
370 defs)
371 (setcar res 'funcall)
372 (setcdr res (cons bsym (mapcar #'cdr prevvars)))
373 (setcar (cddr prev) bsym)
374 (setq res bsym)))
375 (setq vars (copy-sequence vars))
376 (let ((args (mapcar (lambda (pa)
377 (let ((v (assq (car pa) vars)))
378 (setq vars (delq v vars))
379 (cdr v)))
380 prevvars)))
381 ;; If some of `vars' were not found in `prevvars', that's
382 ;; OK it just means those vars aren't present in all
383 ;; branches, so they can be used within the pattern
384 ;; (e.g. by a `guard/let/pred') but not in the branch.
385 ;; FIXME: But if some of `prevvars' are not in `vars' we
386 ;; should remove them from `prevvars'!
387 `(funcall ,res ,@args)))))))
388 (used-cases ())
389 (main
390 (pcase--u
391 (mapcar (lambda (case)
392 `(,(pcase--match val (pcase--macroexpand (car case)))
393 ,(lambda (vars)
394 (unless (memq case used-cases)
395 ;; Keep track of the cases that are used.
396 (push case used-cases))
397 (funcall
398 (if (pcase--small-branch-p (cdr case))
399 ;; Don't bother sharing multiple
400 ;; occurrences of this leaf since it's small.
401 #'pcase-codegen codegen)
402 (cdr case)
403 vars))))
404 cases))))
405 (dolist (case cases)
406 (unless (or (memq case used-cases)
407 (memq (car case) pcase--dontwarn-upats))
408 (message "Redundant pcase pattern: %S" (car case))))
409 (macroexp-let* defs main))))
411 (defun pcase--macroexpand (pat)
412 "Expands all macro-patterns in PAT."
413 (let ((head (car-safe pat)))
414 (cond
415 ((null head)
416 (if (pcase--self-quoting-p pat) `',pat pat))
417 ((memq head '(pred guard quote)) pat)
418 ((memq head '(or and)) `(,head ,@(mapcar #'pcase--macroexpand (cdr pat))))
419 ((eq head 'let) `(let ,(pcase--macroexpand (cadr pat)) ,@(cddr pat)))
420 ((eq head 'app) `(app ,(nth 1 pat) ,(pcase--macroexpand (nth 2 pat))))
422 (let* ((expander (get head 'pcase-macroexpander))
423 (npat (if expander (apply expander (cdr pat)))))
424 (if (null npat)
425 (error (if expander
426 "Unexpandable %s pattern: %S"
427 "Unknown %s pattern: %S")
428 head pat)
429 (pcase--macroexpand npat)))))))
431 ;;;###autoload
432 (defmacro pcase-defmacro (name args &rest body)
433 "Define a new kind of pcase PATTERN, by macro expansion.
434 Patterns of the form (NAME ...) will be expanded according
435 to this macro.
437 By convention, DOC should use \"EXPVAL\" to stand
438 for the result of evaluating EXP (first arg to `pcase').
439 \n(fn NAME ARGS [DOC] &rest BODY...)"
440 (declare (indent 2) (debug defun) (doc-string 3))
441 ;; Add the function via `fsym', so that an autoload cookie placed
442 ;; on a pcase-defmacro will cause the macro to be loaded on demand.
443 (let ((fsym (intern (format "%s--pcase-macroexpander" name)))
444 (decl (assq 'declare body)))
445 (when decl (setq body (remove decl body)))
446 `(progn
447 (defun ,fsym ,args ,@body)
448 (define-symbol-prop ',fsym 'edebug-form-spec ',(cadr (assq 'debug decl)))
449 (define-symbol-prop ',name 'pcase-macroexpander #',fsym))))
451 (defun pcase--match (val upat)
452 "Build a MATCH structure, hoisting all `or's and `and's outside."
453 (cond
454 ;; Hoist or/and patterns into or/and matches.
455 ((memq (car-safe upat) '(or and))
456 `(,(car upat)
457 ,@(mapcar (lambda (upat)
458 (pcase--match val upat))
459 (cdr upat))))
461 `(match ,val . ,upat))))
463 (defun pcase-codegen (code vars)
464 ;; Don't use let*, otherwise macroexp-let* may merge it with some surrounding
465 ;; let* which might prevent the setcar/setcdr in pcase--expand's fancy
466 ;; codegen from later metamorphosing this let into a funcall.
467 (if vars
468 `(let ,(mapcar (lambda (b) (list (car b) (cdr b))) vars)
469 ,@code)
470 `(progn ,@code)))
472 (defun pcase--small-branch-p (code)
473 (and (= 1 (length code))
474 (or (not (consp (car code)))
475 (let ((small t))
476 (dolist (e (car code))
477 (if (consp e) (setq small nil)))
478 small))))
480 ;; Try to use `cond' rather than a sequence of `if's, so as to reduce
481 ;; the depth of the generated tree.
482 (defun pcase--if (test then else)
483 (cond
484 ((eq else :pcase--dontcare) then)
485 ((eq then :pcase--dontcare) (debug) else) ;Can/should this ever happen?
486 (t (macroexp-if test then else))))
488 ;; Note about MATCH:
489 ;; When we have patterns like `(PAT1 . PAT2), after performing the `consp'
490 ;; check, we want to turn all the similar patterns into ones of the form
491 ;; (and (match car PAT1) (match cdr PAT2)), so you naturally need conjunction.
492 ;; Earlier code hence used branches of the form (MATCHES . CODE) where
493 ;; MATCHES was a list (implicitly a conjunction) of (SYM . PAT).
494 ;; But if we have a pattern of the form (or `(PAT1 . PAT2) PAT3), there is
495 ;; no easy way to eliminate the `consp' check in such a representation.
496 ;; So we replaced the MATCHES by the MATCH below which can be made up
497 ;; of conjunctions and disjunctions, so if we know `foo' is a cons, we can
498 ;; turn (match foo . (or `(PAT1 . PAT2) PAT3)) into
499 ;; (or (and (match car . `PAT1) (match cdr . `PAT2)) (match foo . PAT3)).
500 ;; The downside is that we now have `or' and `and' both in MATCH and
501 ;; in PAT, so there are different equivalent representations and we
502 ;; need to handle them all. We do not try to systematically
503 ;; canonicalize them to one form over another, but we do occasionally
504 ;; turn one into the other.
506 (defun pcase--u (branches)
507 "Expand matcher for rules BRANCHES.
508 Each BRANCH has the form (MATCH CODE . VARS) where
509 CODE is the code generator for that branch.
510 VARS is the set of vars already bound by earlier matches.
511 MATCH is the pattern that needs to be matched, of the form:
512 (match VAR . PAT)
513 (and MATCH ...)
514 (or MATCH ...)"
515 (when (setq branches (delq nil branches))
516 (let* ((carbranch (car branches))
517 (match (car carbranch)) (cdarbranch (cdr carbranch))
518 (code (car cdarbranch))
519 (vars (cdr cdarbranch)))
520 (pcase--u1 (list match) code vars (cdr branches)))))
522 (defun pcase--and (match matches)
523 (if matches `(and ,match ,@matches) match))
525 (defconst pcase-mutually-exclusive-predicates
526 '((symbolp . integerp)
527 (symbolp . numberp)
528 (symbolp . consp)
529 (symbolp . arrayp)
530 (symbolp . vectorp)
531 (symbolp . stringp)
532 (symbolp . byte-code-function-p)
533 (symbolp . recordp)
534 (integerp . consp)
535 (integerp . arrayp)
536 (integerp . vectorp)
537 (integerp . stringp)
538 (integerp . byte-code-function-p)
539 (integerp . recordp)
540 (numberp . consp)
541 (numberp . arrayp)
542 (numberp . vectorp)
543 (numberp . stringp)
544 (numberp . byte-code-function-p)
545 (numberp . recordp)
546 (consp . arrayp)
547 (consp . atom)
548 (consp . vectorp)
549 (consp . stringp)
550 (consp . byte-code-function-p)
551 (consp . recordp)
552 (arrayp . byte-code-function-p)
553 (vectorp . byte-code-function-p)
554 (vectorp . recordp)
555 (stringp . vectorp)
556 (stringp . recordp)
557 (stringp . byte-code-function-p)))
559 (defun pcase--mutually-exclusive-p (pred1 pred2)
560 (or (member (cons pred1 pred2)
561 pcase-mutually-exclusive-predicates)
562 (member (cons pred2 pred1)
563 pcase-mutually-exclusive-predicates)))
565 (defun pcase--split-match (sym splitter match)
566 (cond
567 ((eq (car-safe match) 'match)
568 (if (not (eq sym (cadr match)))
569 (cons match match)
570 (let ((res (funcall splitter (cddr match))))
571 (cons (or (car res) match) (or (cdr res) match)))))
572 ((memq (car-safe match) '(or and))
573 (let ((then-alts '())
574 (else-alts '())
575 (neutral-elem (if (eq 'or (car match))
576 :pcase--fail :pcase--succeed))
577 (zero-elem (if (eq 'or (car match)) :pcase--succeed :pcase--fail)))
578 (dolist (alt (cdr match))
579 (let ((split (pcase--split-match sym splitter alt)))
580 (unless (eq (car split) neutral-elem)
581 (push (car split) then-alts))
582 (unless (eq (cdr split) neutral-elem)
583 (push (cdr split) else-alts))))
584 (cons (cond ((memq zero-elem then-alts) zero-elem)
585 ((null then-alts) neutral-elem)
586 ((null (cdr then-alts)) (car then-alts))
587 (t (cons (car match) (nreverse then-alts))))
588 (cond ((memq zero-elem else-alts) zero-elem)
589 ((null else-alts) neutral-elem)
590 ((null (cdr else-alts)) (car else-alts))
591 (t (cons (car match) (nreverse else-alts)))))))
592 ((memq match '(:pcase--succeed :pcase--fail)) (cons match match))
593 (t (error "Uknown MATCH %s" match))))
595 (defun pcase--split-rest (sym splitter rest)
596 (let ((then-rest '())
597 (else-rest '()))
598 (dolist (branch rest)
599 (let* ((match (car branch))
600 (code&vars (cdr branch))
601 (split
602 (pcase--split-match sym splitter match)))
603 (unless (eq (car split) :pcase--fail)
604 (push (cons (car split) code&vars) then-rest))
605 (unless (eq (cdr split) :pcase--fail)
606 (push (cons (cdr split) code&vars) else-rest))))
607 (cons (nreverse then-rest) (nreverse else-rest))))
609 (defun pcase--split-equal (elem pat)
610 (cond
611 ;; The same match will give the same result.
612 ((and (eq (car-safe pat) 'quote) (equal (cadr pat) elem))
613 '(:pcase--succeed . :pcase--fail))
614 ;; A different match will fail if this one succeeds.
615 ((and (eq (car-safe pat) 'quote)
616 ;; (or (integerp (cadr pat)) (symbolp (cadr pat))
617 ;; (consp (cadr pat)))
619 '(:pcase--fail . nil))
620 ((and (eq (car-safe pat) 'pred)
621 (symbolp (cadr pat))
622 (get (cadr pat) 'side-effect-free))
623 (ignore-errors
624 (if (funcall (cadr pat) elem)
625 '(:pcase--succeed . nil)
626 '(:pcase--fail . nil))))))
628 (defun pcase--split-member (elems pat)
629 ;; FIXME: The new pred-based member code doesn't do these optimizations!
630 ;; Based on pcase--split-equal.
631 (cond
632 ;; The same match (or a match of membership in a superset) will
633 ;; give the same result, but we don't know how to check it.
634 ;; (???
635 ;; '(:pcase--succeed . nil))
636 ;; A match for one of the elements may succeed or fail.
637 ((and (eq (car-safe pat) 'quote) (member (cadr pat) elems))
638 nil)
639 ;; A different match will fail if this one succeeds.
640 ((and (eq (car-safe pat) 'quote)
641 ;; (or (integerp (cadr pat)) (symbolp (cadr pat))
642 ;; (consp (cadr pat)))
644 '(:pcase--fail . nil))
645 ((and (eq (car-safe pat) 'pred)
646 (symbolp (cadr pat))
647 (get (cadr pat) 'side-effect-free)
648 (ignore-errors
649 (let ((p (cadr pat)) (all t))
650 (dolist (elem elems)
651 (unless (funcall p elem) (setq all nil)))
652 all)))
653 '(:pcase--succeed . nil))))
655 (defun pcase--split-pred (vars upat pat)
656 (let (test)
657 (cond
658 ((and (equal upat pat)
659 ;; For predicates like (pred (> a)), two such predicates may
660 ;; actually refer to different variables `a'.
661 (or (and (eq 'pred (car upat)) (symbolp (cadr upat)))
662 ;; FIXME: `vars' gives us the environment in which `upat' will
663 ;; run, but we don't have the environment in which `pat' will
664 ;; run, so we can't do a reliable verification. But let's try
665 ;; and catch at least the easy cases such as (bug#14773).
666 (not (pcase--fgrep (mapcar #'car vars) (cadr upat)))))
667 '(:pcase--succeed . :pcase--fail))
668 ((and (eq 'pred (car upat))
669 (let ((otherpred
670 (cond ((eq 'pred (car-safe pat)) (cadr pat))
671 ((not (eq 'quote (car-safe pat))) nil)
672 ((consp (cadr pat)) #'consp)
673 ((stringp (cadr pat)) #'stringp)
674 ((vectorp (cadr pat)) #'vectorp)
675 ((byte-code-function-p (cadr pat))
676 #'byte-code-function-p))))
677 (pcase--mutually-exclusive-p (cadr upat) otherpred)))
678 '(:pcase--fail . nil))
679 ((and (eq 'pred (car upat))
680 (eq 'quote (car-safe pat))
681 (symbolp (cadr upat))
682 (or (symbolp (cadr pat)) (stringp (cadr pat)) (numberp (cadr pat)))
683 (get (cadr upat) 'side-effect-free)
684 (ignore-errors
685 (setq test (list (funcall (cadr upat) (cadr pat))))))
686 (if (car test)
687 '(nil . :pcase--fail)
688 '(:pcase--fail . nil))))))
690 (defun pcase--fgrep (vars sexp)
691 "Check which of the symbols VARS appear in SEXP."
692 (let ((res '()))
693 (while (consp sexp)
694 (dolist (var (pcase--fgrep vars (pop sexp)))
695 (unless (memq var res) (push var res))))
696 (and (memq sexp vars) (not (memq sexp res)) (push sexp res))
697 res))
699 (defun pcase--self-quoting-p (upat)
700 (or (keywordp upat) (integerp upat) (stringp upat)))
702 (defun pcase--app-subst-match (match sym fun nsym)
703 (cond
704 ((eq (car-safe match) 'match)
705 (if (and (eq sym (cadr match))
706 (eq 'app (car-safe (cddr match)))
707 (equal fun (nth 1 (cddr match))))
708 (pcase--match nsym (nth 2 (cddr match)))
709 match))
710 ((memq (car-safe match) '(or and))
711 `(,(car match)
712 ,@(mapcar (lambda (match)
713 (pcase--app-subst-match match sym fun nsym))
714 (cdr match))))
715 ((memq match '(:pcase--succeed :pcase--fail)) match)
716 (t (error "Uknown MATCH %s" match))))
718 (defun pcase--app-subst-rest (rest sym fun nsym)
719 (mapcar (lambda (branch)
720 `(,(pcase--app-subst-match (car branch) sym fun nsym)
721 ,@(cdr branch)))
722 rest))
724 (defsubst pcase--mark-used (sym)
725 ;; Exceptionally, `sym' may be a constant expression rather than a symbol.
726 (if (symbolp sym) (put sym 'pcase-used t)))
728 (defmacro pcase--flip (fun arg1 arg2)
729 "Helper function, used internally to avoid (funcall (lambda ...) ...)."
730 (declare (debug (sexp body)))
731 `(,fun ,arg2 ,arg1))
733 (defun pcase--funcall (fun arg vars)
734 "Build a function call to FUN with arg ARG."
735 (if (symbolp fun)
736 `(,fun ,arg)
737 (let* (;; `vs' is an upper bound on the vars we need.
738 (vs (pcase--fgrep (mapcar #'car vars) fun))
739 (env (mapcar (lambda (var)
740 (list var (cdr (assq var vars))))
741 vs))
742 (call (progn
743 (when (memq arg vs)
744 ;; `arg' is shadowed by `env'.
745 (let ((newsym (gensym "x")))
746 (push (list newsym arg) env)
747 (setq arg newsym)))
748 (if (functionp fun)
749 `(funcall #',fun ,arg)
750 `(,@fun ,arg)))))
751 (if (null vs)
752 call
753 ;; Let's not replace `vars' in `fun' since it's
754 ;; too difficult to do it right, instead just
755 ;; let-bind `vars' around `fun'.
756 `(let* ,env ,call)))))
758 (defun pcase--eval (exp vars)
759 "Build an expression that will evaluate EXP."
760 (let* ((found (assq exp vars)))
761 (if found (cdr found)
762 (let* ((vs (pcase--fgrep (mapcar #'car vars) exp))
763 (env (mapcar (lambda (v) (list v (cdr (assq v vars))))
764 vs)))
765 (if env (macroexp-let* env exp) exp)))))
767 ;; It's very tempting to use `pcase' below, tho obviously, it'd create
768 ;; bootstrapping problems.
769 (defun pcase--u1 (matches code vars rest)
770 "Return code that runs CODE (with VARS) if MATCHES match.
771 Otherwise, it defers to REST which is a list of branches of the form
772 \(ELSE-MATCH ELSE-CODE . ELSE-VARS)."
773 ;; Depending on the order in which we choose to check each of the MATCHES,
774 ;; the resulting tree may be smaller or bigger. So in general, we'd want
775 ;; to be careful to chose the "optimal" order. But predicate
776 ;; patterns make this harder because they create dependencies
777 ;; between matches. So we don't bother trying to reorder anything.
778 (cond
779 ((null matches) (funcall code vars))
780 ((eq :pcase--fail (car matches)) (pcase--u rest))
781 ((eq :pcase--succeed (car matches))
782 (pcase--u1 (cdr matches) code vars rest))
783 ((eq 'and (caar matches))
784 (pcase--u1 (append (cdar matches) (cdr matches)) code vars rest))
785 ((eq 'or (caar matches))
786 (let* ((alts (cdar matches))
787 (var (if (eq (caar alts) 'match) (cadr (car alts))))
788 (simples '()) (others '()) (memq-ok t))
789 (when var
790 (dolist (alt alts)
791 (if (and (eq (car alt) 'match) (eq var (cadr alt))
792 (let ((upat (cddr alt)))
793 (eq (car-safe upat) 'quote)))
794 (let ((val (cadr (cddr alt))))
795 (unless (or (integerp val) (symbolp val))
796 (setq memq-ok nil))
797 (push (cadr (cddr alt)) simples))
798 (push alt others))))
799 (cond
800 ((null alts) (error "Please avoid it") (pcase--u rest))
801 ;; Yes, we can use `memq' (or `member')!
802 ((> (length simples) 1)
803 (pcase--u1 (cons `(match ,var
804 . (pred (pcase--flip
805 ,(if memq-ok #'memq #'member)
806 ',simples)))
807 (cdr matches))
808 code vars
809 (if (null others) rest
810 (cons (cons
811 (pcase--and (if (cdr others)
812 (cons 'or (nreverse others))
813 (car others))
814 (cdr matches))
815 (cons code vars))
816 rest))))
818 (pcase--u1 (cons (pop alts) (cdr matches)) code vars
819 (if (null alts) (progn (error "Please avoid it") rest)
820 (cons (cons
821 (pcase--and (if (cdr alts)
822 (cons 'or alts) (car alts))
823 (cdr matches))
824 (cons code vars))
825 rest)))))))
826 ((eq 'match (caar matches))
827 (let* ((popmatches (pop matches))
828 (_op (car popmatches)) (cdrpopmatches (cdr popmatches))
829 (sym (car cdrpopmatches))
830 (upat (cdr cdrpopmatches)))
831 (cond
832 ((memq upat '(t _))
833 (let ((code (pcase--u1 matches code vars rest)))
834 (if (eq upat '_) code
835 (macroexp--warn-and-return
836 "Pattern t is deprecated. Use `_' instead"
837 code))))
838 ((eq upat 'pcase--dontcare) :pcase--dontcare)
839 ((memq (car-safe upat) '(guard pred))
840 (if (eq (car upat) 'pred) (pcase--mark-used sym))
841 (let* ((splitrest
842 (pcase--split-rest
843 sym (lambda (pat) (pcase--split-pred vars upat pat)) rest))
844 (then-rest (car splitrest))
845 (else-rest (cdr splitrest)))
846 (pcase--if (if (eq (car upat) 'pred)
847 (pcase--funcall (cadr upat) sym vars)
848 (pcase--eval (cadr upat) vars))
849 (pcase--u1 matches code vars then-rest)
850 (pcase--u else-rest))))
851 ((and (symbolp upat) upat)
852 (pcase--mark-used sym)
853 (if (not (assq upat vars))
854 (pcase--u1 matches code (cons (cons upat sym) vars) rest)
855 ;; Non-linear pattern. Turn it into an `eq' test.
856 (pcase--u1 (cons `(match ,sym . (pred (eq ,(cdr (assq upat vars)))))
857 matches)
858 code vars rest)))
859 ((eq (car-safe upat) 'let)
860 ;; A upat of the form (let VAR EXP).
861 ;; (pcase--u1 matches code
862 ;; (cons (cons (nth 1 upat) (nth 2 upat)) vars) rest)
863 (macroexp-let2
864 macroexp-copyable-p sym
865 (pcase--eval (nth 2 upat) vars)
866 (pcase--u1 (cons (pcase--match sym (nth 1 upat)) matches)
867 code vars rest)))
868 ((eq (car-safe upat) 'app)
869 ;; A upat of the form (app FUN PAT)
870 (pcase--mark-used sym)
871 (let* ((fun (nth 1 upat))
872 (nsym (gensym "x"))
873 (body
874 ;; We don't change `matches' to reuse the newly computed value,
875 ;; because we assume there shouldn't be such redundancy in there.
876 (pcase--u1 (cons (pcase--match nsym (nth 2 upat)) matches)
877 code vars
878 (pcase--app-subst-rest rest sym fun nsym))))
879 (if (not (get nsym 'pcase-used))
880 body
881 (macroexp-let*
882 `((,nsym ,(pcase--funcall fun sym vars)))
883 body))))
884 ((eq (car-safe upat) 'quote)
885 (pcase--mark-used sym)
886 (let* ((val (cadr upat))
887 (splitrest (pcase--split-rest
888 sym (lambda (pat) (pcase--split-equal val pat)) rest))
889 (then-rest (car splitrest))
890 (else-rest (cdr splitrest)))
891 (pcase--if (cond
892 ((null val) `(null ,sym))
893 ((integerp val) `(eql ,sym ,val))
894 ((symbolp val)
895 (if (pcase--self-quoting-p val)
896 `(eq ,sym ,val)
897 `(eq ,sym ',val)))
898 (t `(equal ,sym ',val)))
899 (pcase--u1 matches code vars then-rest)
900 (pcase--u else-rest))))
901 ((eq (car-safe upat) 'not)
902 ;; FIXME: The implementation below is naive and results in
903 ;; inefficient code.
904 ;; To make it work right, we would need to turn pcase--u1's
905 ;; `code' and `vars' into a single argument of the same form as
906 ;; `rest'. We would also need to split this new `then-rest' argument
907 ;; for every test (currently we don't bother to do it since
908 ;; it's only useful for odd patterns like (and `(PAT1 . PAT2)
909 ;; `(PAT3 . PAT4)) which the programmer can easily rewrite
910 ;; to the more efficient `(,(and PAT1 PAT3) . ,(and PAT2 PAT4))).
911 (pcase--u1 `((match ,sym . ,(cadr upat)))
912 ;; FIXME: This codegen is not careful to share its
913 ;; code if used several times: code blow up is likely.
914 (lambda (_vars)
915 ;; `vars' will likely contain bindings which are
916 ;; not always available in other paths to
917 ;; `rest', so there' no point trying to pass
918 ;; them down.
919 (pcase--u rest))
920 vars
921 (list `((and . ,matches) ,code . ,vars))))
922 (t (error "Unknown pattern `%S'" upat)))))
923 (t (error "Incorrect MATCH %S" (car matches)))))
925 (def-edebug-spec
926 pcase-QPAT
927 ;; Cf. edebug spec for `backquote-form' in edebug.el.
928 (&or ("," pcase-PAT)
929 (pcase-QPAT [&rest [&not ","] pcase-QPAT]
930 . [&or nil pcase-QPAT])
931 (vector &rest pcase-QPAT)
932 sexp))
934 (pcase-defmacro \` (qpat)
935 "Backquote-style pcase patterns: \\=`QPAT
936 QPAT can take the following forms:
937 (QPAT1 . QPAT2) matches if QPAT1 matches the car and QPAT2 the cdr.
938 [QPAT1 QPAT2..QPATn] matches a vector of length n and QPAT1..QPATn match
939 its 0..(n-1)th elements, respectively.
940 ,PAT matches if the `pcase' pattern PAT matches.
941 SYMBOL matches if EXPVAL is `equal' to SYMBOL.
942 KEYWORD likewise for KEYWORD.
943 NUMBER likewise for NUMBER.
944 STRING likewise for STRING.
946 The list or vector QPAT is a template. The predicate formed
947 by a backquote-style pattern is a combination of those
948 formed by any sub-patterns, wrapped in a top-level condition:
949 EXPVAL must be \"congruent\" with the template. For example:
951 \\=`(technical ,forum)
953 The predicate is the logical-AND of:
954 - Is EXPVAL a list of two elements?
955 - Is the first element the symbol `technical'?
956 - True! (The second element can be anything, and for the sake
957 of the body forms, its value is bound to the symbol `forum'.)"
958 (declare (debug (pcase-QPAT)))
959 (cond
960 ((eq (car-safe qpat) '\,) (cadr qpat))
961 ((vectorp qpat)
962 `(and (pred vectorp)
963 (app length ,(length qpat))
964 ,@(let ((upats nil))
965 (dotimes (i (length qpat))
966 (push `(app (pcase--flip aref ,i) ,(list '\` (aref qpat i)))
967 upats))
968 (nreverse upats))))
969 ((consp qpat)
970 `(and (pred consp)
971 (app car ,(list '\` (car qpat)))
972 (app cdr ,(list '\` (cdr qpat)))))
973 ((or (stringp qpat) (numberp qpat) (symbolp qpat)) `',qpat)
974 ;; In all other cases just raise an error so we can't break
975 ;; backward compatibility when adding \` support for other
976 ;; compounded values that are not `consp'
977 (t (error "Unknown QPAT: %S" qpat))))
979 (provide 'pcase)
980 ;;; pcase.el ends here