macros.lisp 12 KB
Newer Older
Nikodemus Siivola's avatar
Nikodemus Siivola committed
1
2
(in-package :alexandria)

Nikodemus Siivola's avatar
Nikodemus Siivola committed
3
(defmacro with-gensyms (names &body forms)
lovrolu's avatar
lovrolu committed
4
  "Binds a set of variables to gensyms and evaluates the implicit progn FORMS.
5

lovrolu's avatar
lovrolu committed
6
7
Each element within NAMES is either a symbol SYMBOL or a pair (SYMBOL
STRING-DESIGNATOR). Bare symbols are equivalent to the pair (SYMBOL SYMBOL).
8

lovrolu's avatar
lovrolu committed
9
10
11
Each pair (SYMBOL STRING-DESIGNATOR) specifies that the variable named by SYMBOL
should be bound to a symbol constructed using GENSYM with the string designated
by STRING-DESIGNATOR being its first argument."
Nikodemus Siivola's avatar
Nikodemus Siivola committed
12
  `(let ,(mapcar (lambda (name)
Nikodemus Siivola's avatar
Nikodemus Siivola committed
13
14
15
16
17
18
19
                   (multiple-value-bind (symbol string)
                       (etypecase name
                         (symbol
                          (values name (symbol-name name)))
                         ((cons symbol (cons string-designator null))
                          (values (first name) (string (second name)))))
                     `(,symbol (gensym ,string))))
Nikodemus Siivola's avatar
Nikodemus Siivola committed
20
21
22
                 names)
     ,@forms))

Nikodemus Siivola's avatar
Nikodemus Siivola committed
23
(defmacro with-unique-names (names &body forms)
24
25
  "Alias for WITH-GENSYMS."
  `(with-gensyms ,names ,@forms))
Nikodemus Siivola's avatar
Nikodemus Siivola committed
26

Nikodemus Siivola's avatar
Nikodemus Siivola committed
27
(defmacro once-only (specs &body forms)
Nikodemus Siivola's avatar
Nikodemus Siivola committed
28
29
  "Evaluates FORMS with symbols specified in SPECS rebound to temporary
variables, ensuring that each initform is evaluated only once.
Nikodemus Siivola's avatar
Nikodemus Siivola committed
30

Nikodemus Siivola's avatar
Nikodemus Siivola committed
31
32
33
34
35
36
37
38
Each of SPECS must either be a symbol naming the variable to be rebound, or of
the form:

  (symbol initform)

Bare symbols in SPECS are equivalent to

  (symbol symbol)
Nikodemus Siivola's avatar
Nikodemus Siivola committed
39
40

Example:
Nikodemus Siivola's avatar
Nikodemus Siivola committed
41

Nikodemus Siivola's avatar
Nikodemus Siivola committed
42
  (defmacro cons1 (x) (once-only (x) `(cons ,x ,x)))
Nikodemus Siivola's avatar
Nikodemus Siivola committed
43
44
  (let ((y 0)) (cons1 (incf y))) => (1 . 1)
"
Nikodemus Siivola's avatar
Nikodemus Siivola committed
45
46
47
48
49
50
51
52
53
  (let ((gensyms (make-gensym-list (length specs) "ONCE-ONLY"))
        (names-and-forms (mapcar (lambda (spec)
                                   (etypecase spec
                                     (list
                                      (destructuring-bind (name form) spec
                                        (cons name form)))
                                     (symbol
                                      (cons spec spec))))
                                 specs)))
Nikodemus Siivola's avatar
Nikodemus Siivola committed
54
    ;; bind in user-macro
Nikodemus Siivola's avatar
Nikodemus Siivola committed
55
56
    `(let ,(mapcar (lambda (g n) (list g `(gensym ,(string (car n)))))
                   gensyms names-and-forms)
Nikodemus Siivola's avatar
Nikodemus Siivola committed
57
       ;; bind in final expansion
Nikodemus Siivola's avatar
Nikodemus Siivola committed
58
59
60
       `(let (,,@(mapcar (lambda (g n)
                           ``(,,g ,,(cdr n)))
                         gensyms names-and-forms))
61
          ;; bind in user-macro
Nikodemus Siivola's avatar
Nikodemus Siivola committed
62
63
          ,(let ,(mapcar (lambda (n g) (list (car n) g))
                         names-and-forms gensyms)
Nikodemus Siivola's avatar
Nikodemus Siivola committed
64
65
             ,@forms)))))

66
67
68
69
70
(defun parse-body (body &key documentation whole)
  "Parses BODY into (values remaining-forms declarations doc-string).
Documentation strings are recognized only if DOCUMENTATION is true.
Syntax errors in body are signalled and WHOLE is used in the signal
arguments when given."
Nikodemus Siivola's avatar
Nikodemus Siivola committed
71
72
73
74
75
76
  (let ((doc nil)
        (decls nil)
        (current nil))
    (tagbody
     :declarations
       (setf current (car body))
77
78
79
80
       (when (and documentation (stringp current) (cdr body))
         (if doc
             (error "Too many documentation strings in ~S." (or whole body))
             (setf doc (pop body)))
Nikodemus Siivola's avatar
Nikodemus Siivola committed
81
         (go :declarations))
82
       (when (and (listp current) (eql (first current) 'declare))
Nikodemus Siivola's avatar
Nikodemus Siivola committed
83
84
85
         (push (pop body) decls)
         (go :declarations)))
    (values body (nreverse decls) doc)))
86

87
(defun parse-ordinary-lambda-list (lambda-list &key (normalize t)
88
                                   allow-specializers
89
90
91
                                   (normalize-optional normalize)
                                   (normalize-keyword normalize)
                                   (normalize-auxilary normalize))
Nikodemus Siivola's avatar
Nikodemus Siivola committed
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
  "Parses an ordinary lambda-list, returning as multiple values:

1. Required parameters.

2. Optional parameter specifications, normalized into form:

   (name init suppliedp)

3. Name of the rest parameter, or NIL.

4. Keyword parameter specifications, normalized into form:

   ((keyword-name name) init suppliedp)

5. Boolean indicating &ALLOW-OTHER-KEYS presence.

6. &AUX parameter specifications, normalized into form

   (name init).
111

112
113
7. Existence of &KEY in the lambda-list.

114
115
116
117
118
119
120
121
Signals a PROGRAM-ERROR is the lambda-list is malformed."
  (let ((state :required)
        (allow-other-keys nil)
        (auxp nil)
        (required nil)
        (optional nil)
        (rest nil)
        (keys nil)
122
        (keyp nil)
123
124
125
126
        (aux nil))
    (labels ((fail (elt)
               (simple-program-error "Misplaced ~S in ordinary lambda-list:~%  ~S"
                                     elt lambda-list))
127
128
129
130
131
             (check-variable (elt what &optional (allow-specializers allow-specializers))
               (unless (and (or (symbolp elt)
                                (and allow-specializers
                                     (consp elt) (= 2 (length elt)) (symbolp (first elt))))
                            (not (constantp elt)))
132
133
134
135
136
                 (simple-program-error "Invalid ~A ~S in ordinary lambda-list:~%  ~S"
                                       what elt lambda-list)))
             (check-spec (spec what)
               (destructuring-bind (init suppliedp) spec
                 (declare (ignore init))
137
                 (check-variable suppliedp what nil))))
138
139
140
141
142
143
144
145
146
      (dolist (elt lambda-list)
        (case elt
          (&optional
           (if (eq state :required)
               (setf state elt)
               (fail elt)))
          (&rest
           (if (member state '(:required &optional))
               (setf state elt)
147
               (fail elt)))
148
149
150
          (&key
           (if (member state '(:required &optional :after-rest))
               (setf state elt)
151
152
               (fail elt))
           (setf keyp t))
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
          (&allow-other-keys
           (if (eq state '&key)
               (setf allow-other-keys t
                     state elt)
               (fail elt)))
          (&aux
           (cond ((eq state '&rest)
                  (fail elt))
                 (auxp
                  (simple-program-error "Multiple ~S in ordinary lambda-list:~%  ~S"
                                        elt lambda-list))
                 (t
                  (setf auxp t
                        state elt))
                 ))
          (otherwise
           (when (member elt '#.(set-difference lambda-list-keywords
                                                '(&optional &rest &key &allow-other-keys &aux)))
             (simple-program-error
              "Bad lambda-list keyword ~S in ordinary lambda-list:~%  ~S"
              elt lambda-list))
           (case state
             (:required
              (check-variable elt "required parameter")
              (push elt required))
             (&optional
              (cond ((consp elt)
                     (destructuring-bind (name &rest tail) elt
                       (check-variable name "optional parameter")
182
183
                       (cond ((cdr tail)
                              (check-spec tail "optional-supplied-p parameter"))
184
185
                             ((and normalize-optional tail)
                              (setf elt (append elt '(nil))))
186
                             (normalize-optional
187
                              (setf elt (append elt '(nil nil)))))))
188
189
                    (t
                     (check-variable elt "optional parameter")
190
191
192
                     (when normalize-optional
                       (setf elt (cons elt '(nil nil))))))
              (push (ensure-list elt) optional))
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
             (&rest
              (check-variable elt "rest parameter")
              (setf rest elt
                    state :after-rest))
             (&key
              (cond ((consp elt)
                     (destructuring-bind (var-or-kv &rest tail) elt
                       (cond ((consp var-or-kv)
                              (destructuring-bind (keyword var) var-or-kv
                                (unless (symbolp keyword)
                                  (simple-program-error "Invalid keyword name ~S in ordinary ~
                                                         lambda-list:~%  ~S"
                                                        keyword lambda-list))
                                (check-variable var "keyword parameter")))
                             (t
                              (check-variable var-or-kv "keyword parameter")
209
210
                              (when normalize-keyword
                                (setf var-or-kv (list (make-keyword var-or-kv) var-or-kv)))))
211
212
213
214
215
216
                       (cond ((cdr tail)
                              (check-spec tail "keyword-supplied-p parameter"))
                             ((and normalize-keyword tail)
                              (setf tail (append tail '(nil))))
                             (normalize-keyword
                              (setf tail '(nil nil))))
217
218
219
                       (setf elt (cons var-or-kv tail))))
                    (t
                     (check-variable elt "keyword parameter")
220
221
                     (setf elt (if normalize-keyword
                                   (list (list (make-keyword elt) elt) nil nil)
222
                                   elt))))
223
224
225
226
227
228
              (push elt keys))
             (&aux
              (if (consp elt)
                  (destructuring-bind (var &optional init) elt
                    (declare (ignore init))
                    (check-variable var "&aux parameter"))
229
230
                  (progn
                    (check-variable elt "&aux parameter")
231
232
                    (setf elt (list* elt (when normalize-auxilary
                                           '(nil))))))
233
234
235
236
              (push elt aux))
             (t
              (simple-program-error "Invalid ordinary lambda-list:~%  ~S" lambda-list)))))))
    (values (nreverse required) (nreverse optional) rest (nreverse keys)
237
            allow-other-keys (nreverse aux) keyp)))
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271

;;;; DESTRUCTURING-*CASE

(defun expand-destructuring-case (key clauses case)
  (once-only (key)
    `(if (typep ,key 'cons)
         (,case (car ,key)
           ,@(mapcar (lambda (clause)
                       (destructuring-bind ((keys . lambda-list) &body body) clause
                         `(,keys
                           (destructuring-bind ,lambda-list (cdr ,key)
                             ,@body))))
                     clauses))
         (error "Invalid key to DESTRUCTURING-~S: ~S" ',case ,key))))

(defmacro destructuring-case (keyform &body clauses)
  "DESTRUCTURING-CASE, -CCASE, and -ECASE are a combination of CASE and DESTRUCTURING-BIND.
KEYFORM must evaluate to a CONS.

Clauses are of the form:

  ((CASE-KEYS . DESTRUCTURING-LAMBDA-LIST) FORM*)

The clause whose CASE-KEYS matches CAR of KEY, as if by CASE, CCASE, or ECASE,
is selected, and FORMs are then executed with CDR of KEY is destructured and
bound by the DESTRUCTURING-LAMBDA-LIST.

Example:

 (defun dcase (x)
   (destructuring-case x
     ((:foo a b)
      (format nil \"foo: ~S, ~S\" a b))
     ((:bar &key a b)
272
      (format nil \"bar: ~S, ~S\" a b))
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
     (((:alt1 :alt2) a)
      (format nil \"alt: ~S\" a))
     ((t &rest rest)
      (format nil \"unknown: ~S\" rest))))

  (dcase (list :foo 1 2))        ; => \"foo: 1, 2\"
  (dcase (list :bar :a 1 :b 2))  ; => \"bar: 1, 2\"
  (dcase (list :alt1 1))         ; => \"alt: 1\"
  (dcase (list :alt2 2))         ; => \"alt: 2\"
  (dcase (list :quux 1 2 3))     ; => \"unknown: 1, 2, 3\"

 (defun decase (x)
   (destructuring-case x
     ((:foo a b)
      (format nil \"foo: ~S, ~S\" a b))
     ((:bar &key a b)
289
      (format nil \"bar: ~S, ~S\" a b))
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
     (((:alt1 :alt2) a)
      (format nil \"alt: ~S\" a))))

  (decase (list :foo 1 2))        ; => \"foo: 1, 2\"
  (decase (list :bar :a 1 :b 2))  ; => \"bar: 1, 2\"
  (decase (list :alt1 1))         ; => \"alt: 1\"
  (decase (list :alt2 2))         ; => \"alt: 2\"
  (decase (list :quux 1 2 3))     ; =| error
"
  (expand-destructuring-case keyform clauses 'case))

(defmacro destructuring-ccase (keyform &body clauses)
  (expand-destructuring-case keyform clauses 'ccase))

(defmacro destructuring-ecase (keyform &body clauses)
  (expand-destructuring-case keyform clauses 'ecase))

(dolist (name '(destructuring-ccase destructuring-ecase))
  (setf (documentation name 'function) (documentation 'destructuring-case 'function)))