macros.lisp 11.9 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)
4 5 6 7 8 9 10 11 12 13 14
  "Binds each variable named by a symbol in NAMES to a unique symbol around
FORMS. Each of NAMES must either be either a symbol, or of the form:

 (symbol string-designator)

Bare symbols appearing in NAMES are equivalent to:

 (symbol symbol)

The string-designator is used as the argument to GENSYM when constructing the
unique symbol the named variable will be bound to."
Nikodemus Siivola's avatar
Nikodemus Siivola committed
15
  `(let ,(mapcar (lambda (name)
Nikodemus Siivola's avatar
Nikodemus Siivola committed
16 17 18 19 20 21 22
                   (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
23 24 25
                 names)
     ,@forms))

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

Nikodemus Siivola's avatar
Nikodemus Siivola committed
30
(defmacro once-only (specs &body forms)
Nikodemus Siivola's avatar
Nikodemus Siivola committed
31 32
  "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
33

Nikodemus Siivola's avatar
Nikodemus Siivola committed
34 35 36 37 38 39 40 41
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
42 43

Example:
Nikodemus Siivola's avatar
Nikodemus Siivola committed
44

Nikodemus Siivola's avatar
Nikodemus Siivola committed
45
  (defmacro cons1 (x) (once-only (x) `(cons ,x ,x)))
Nikodemus Siivola's avatar
Nikodemus Siivola committed
46 47
  (let ((y 0)) (cons1 (incf y))) => (1 . 1)
"
Nikodemus Siivola's avatar
Nikodemus Siivola committed
48 49 50 51 52 53 54 55 56
  (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
57
    ;; bind in user-macro
Nikodemus Siivola's avatar
Nikodemus Siivola committed
58 59
    `(let ,(mapcar (lambda (g n) (list g `(gensym ,(string (car n)))))
                   gensyms names-and-forms)
Nikodemus Siivola's avatar
Nikodemus Siivola committed
60
       ;; bind in final expansion
Nikodemus Siivola's avatar
Nikodemus Siivola committed
61 62 63
       `(let (,,@(mapcar (lambda (g n)
                           ``(,,g ,,(cdr n)))
                         gensyms names-and-forms))
64
          ;; bind in user-macro
Nikodemus Siivola's avatar
Nikodemus Siivola committed
65 66
          ,(let ,(mapcar (lambda (n g) (list (car n) g))
                         names-and-forms gensyms)
Nikodemus Siivola's avatar
Nikodemus Siivola committed
67 68
             ,@forms)))))

69 70 71 72 73
(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
74 75 76 77 78 79
  (let ((doc nil)
        (decls nil)
        (current nil))
    (tagbody
     :declarations
       (setf current (car body))
80 81 82 83
       (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
84
         (go :declarations))
85
       (when (and (listp current) (eql (first current) 'declare))
Nikodemus Siivola's avatar
Nikodemus Siivola committed
86 87 88
         (push (pop body) decls)
         (go :declarations)))
    (values body (nreverse decls) doc)))
89

90
(defun parse-ordinary-lambda-list (lambda-list &key (normalize t)
91
                                   allow-specializers
92 93 94
                                   (normalize-optional normalize)
                                   (normalize-keyword normalize)
                                   (normalize-auxilary normalize))
Nikodemus Siivola's avatar
Nikodemus Siivola committed
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
  "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).
114

115 116
7. Existence of &KEY in the lambda-list.

117 118 119 120 121 122 123 124
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)
125
        (keyp nil)
126 127 128 129
        (aux nil))
    (labels ((fail (elt)
               (simple-program-error "Misplaced ~S in ordinary lambda-list:~%  ~S"
                                     elt lambda-list))
130 131 132 133 134
             (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)))
135 136 137 138 139
                 (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))
140
                 (check-variable suppliedp what nil))))
141 142 143 144 145 146 147 148 149
      (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)
150
               (fail elt)))
151 152 153
          (&key
           (if (member state '(:required &optional :after-rest))
               (setf state elt)
154 155
               (fail elt))
           (setf keyp t))
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 182 183 184
          (&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")
185 186
                       (cond ((cdr tail)
                              (check-spec tail "optional-supplied-p parameter"))
187 188
                             ((and normalize-optional tail)
                              (setf elt (append elt '(nil))))
189
                             (normalize-optional
190
                              (setf elt (append elt '(nil nil)))))))
191 192
                    (t
                     (check-variable elt "optional parameter")
193 194 195
                     (when normalize-optional
                       (setf elt (cons elt '(nil nil))))))
              (push (ensure-list elt) optional))
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
             (&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")
212 213
                              (when normalize-keyword
                                (setf var-or-kv (list (make-keyword var-or-kv) var-or-kv)))))
214 215 216 217 218 219
                       (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))))
220 221 222
                       (setf elt (cons var-or-kv tail))))
                    (t
                     (check-variable elt "keyword parameter")
223 224
                     (setf elt (if normalize-keyword
                                   (list (list (make-keyword elt) elt) nil nil)
225
                                   elt))))
226 227 228 229 230 231
              (push elt keys))
             (&aux
              (if (consp elt)
                  (destructuring-bind (var &optional init) elt
                    (declare (ignore init))
                    (check-variable var "&aux parameter"))
232 233
                  (progn
                    (check-variable elt "&aux parameter")
234 235
                    (setf elt (list* elt (when normalize-auxilary
                                           '(nil))))))
236 237 238 239
              (push elt aux))
             (t
              (simple-program-error "Invalid ordinary lambda-list:~%  ~S" lambda-list)))))))
    (values (nreverse required) (nreverse optional) rest (nreverse keys)
240
            allow-other-keys (nreverse aux) keyp)))
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 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314

;;;; 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)
      (format nil \"bar, ~S, ~S\" a b))
     (((: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)
      (format nil \"bar, ~S, ~S\" a b))
     (((: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)))