| 1 | ;;; -*-lisp-*- |
| 2 | ;;; |
| 3 | ;;; $Id$ |
| 4 | ;;; |
| 5 | ;;; Basic definitions |
| 6 | ;;; |
| 7 | ;;; (c) 2005 Mark Wooding |
| 8 | ;;; |
| 9 | |
| 10 | ;;;----- Licensing notice --------------------------------------------------- |
| 11 | ;;; |
| 12 | ;;; This program is free software; you can redistribute it and/or modify |
| 13 | ;;; it under the terms of the GNU General Public License as published by |
| 14 | ;;; the Free Software Foundation; either version 2 of the License, or |
| 15 | ;;; (at your option) any later version. |
| 16 | ;;; |
| 17 | ;;; This program is distributed in the hope that it will be useful, |
| 18 | ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 19 | ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 20 | ;;; GNU General Public License for more details. |
| 21 | ;;; |
| 22 | ;;; You should have received a copy of the GNU General Public License |
| 23 | ;;; along with this program; if not, write to the Free Software Foundation, |
| 24 | ;;; Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
| 25 | |
| 26 | ;;;-------------------------------------------------------------------------- |
| 27 | ;;; Package things. |
| 28 | |
| 29 | (defpackage #:mdw.base |
| 30 | (:use #:common-lisp) |
| 31 | (:export #:unsigned-fixnum |
| 32 | #:compile-time-defun |
| 33 | #:show |
| 34 | #:stringify #:mappend #:listify #:fix-pair #:pairify #:parse-body |
| 35 | #:whitespace-char-p |
| 36 | #:slot-uninitialized |
| 37 | #:nlet #:while #:until #:case2 #:ecase2 |
| 38 | #:with-gensyms #:let*/gensyms #:with-places |
| 39 | #:locp #:locf #:ref #:with-locatives |
| 40 | #:update-place #:update-place-after |
| 41 | #:incf-after #:decf-after |
| 42 | #:fixnump) |
| 43 | #+cmu (:import-from #:extensions #:fixnump)) |
| 44 | |
| 45 | (in-package #:mdw.base) |
| 46 | |
| 47 | ;;;-------------------------------------------------------------------------- |
| 48 | ;;; Useful types. |
| 49 | |
| 50 | (deftype unsigned-fixnum () |
| 51 | "Unsigned fixnums; useful as array indices and suchlike." |
| 52 | `(mod ,most-positive-fixnum)) |
| 53 | |
| 54 | ;;;-------------------------------------------------------------------------- |
| 55 | ;;; Some simple macros to get things going. |
| 56 | |
| 57 | (defmacro compile-time-defun (name args &body body) |
| 58 | "Define a function which can be used by macros during the compilation |
| 59 | process." |
| 60 | `(eval-when (:compile-toplevel :load-toplevel) |
| 61 | (defun ,name ,args ,@body))) |
| 62 | |
| 63 | (defmacro show (x) |
| 64 | "Debugging tool: print the expression X and its values." |
| 65 | (let ((tmp (gensym))) |
| 66 | `(let ((,tmp (multiple-value-list ,x))) |
| 67 | (format t "~&") |
| 68 | (pprint-logical-block (*standard-output* nil :per-line-prefix ";; ") |
| 69 | (format t |
| 70 | "~S = ~@_~:I~:[#<no values>~;~:*~{~S~^ ~_~}~]" |
| 71 | ',x |
| 72 | ,tmp)) |
| 73 | (terpri) |
| 74 | (values-list ,tmp)))) |
| 75 | |
| 76 | (defun stringify (str) |
| 77 | "Return a string representation of STR. Strings are returned unchanged; |
| 78 | symbols are converted to their names (unqualified!). Other objects are |
| 79 | converted to their print representations." |
| 80 | (typecase str |
| 81 | (string str) |
| 82 | (symbol (symbol-name str)) |
| 83 | (t (with-output-to-string (s) |
| 84 | (princ str s))))) |
| 85 | |
| 86 | (defun mappend (function list &rest more-lists) |
| 87 | "Apply FUNCTION to corresponding elements of LIST and MORE-LISTS, yielding |
| 88 | a list. Return the concatenation of all the resulting lists. Like |
| 89 | mapcan, but nondestructive." |
| 90 | (apply #'append (apply #'mapcar function list more-lists))) |
| 91 | |
| 92 | (compile-time-defun listify (x) |
| 93 | "If X is a (possibly empty) list, return X; otherwise return (list X)." |
| 94 | (if (listp x) x (list x))) |
| 95 | |
| 96 | (compile-time-defun do-fix-pair (x y defaultp) |
| 97 | "Helper function for fix-pair and pairify." |
| 98 | (flet ((singleton (x) (values x (if defaultp y x)))) |
| 99 | (cond ((atom x) (singleton x)) |
| 100 | ((null (cdr x)) (singleton (car x))) |
| 101 | ((atom (cdr x)) (values (car x) (cdr x))) |
| 102 | ((cddr x) (error "Too many elements for a pair.")) |
| 103 | (t (values (car x) (cadr x)))))) |
| 104 | |
| 105 | (compile-time-defun fix-pair (x &optional (y nil defaultp)) |
| 106 | "Return two values extracted from X. It works as follows: |
| 107 | (A) -> A, Y |
| 108 | (A B) -> A, B |
| 109 | (A B . C) -> error |
| 110 | (A . B) -> A, B |
| 111 | A -> A, Y |
| 112 | where Y defaults to A if not specified." |
| 113 | (do-fix-pair x y defaultp)) |
| 114 | |
| 115 | (compile-time-defun pairify (x &optional (y nil defaultp)) |
| 116 | "As for fix-pair, but returns a list instead of two values." |
| 117 | (multiple-value-call #'list (do-fix-pair x y defaultp))) |
| 118 | |
| 119 | (defun whitespace-char-p (ch) |
| 120 | "Return whether CH is a whitespace character or not." |
| 121 | (case ch |
| 122 | ((#\space #\tab #\newline #\return #\vt #\formfeed) t) |
| 123 | (t nil))) |
| 124 | |
| 125 | (declaim (ftype (function nil ()) slot-unitialized)) |
| 126 | (defun slot-uninitialized () |
| 127 | "A function which signals an error. Can be used as an initializer form in |
| 128 | structure definitions without doom ensuing." |
| 129 | (error "No initializer for slot.")) |
| 130 | |
| 131 | (compile-time-defun parse-body (body &key (allow-docstring-p t)) |
| 132 | "Given a BODY (a list of forms), parses it into three sections: a |
| 133 | docstring, a list of declarations (forms beginning with the symbol |
| 134 | `declare') and the body forms. The result is returned as three lists |
| 135 | (even the docstring), suitable for interpolation into a backquoted list |
| 136 | using `@,'. If ALLOW-DOCSTRING-P is nil, docstrings aren't allowed at |
| 137 | all." |
| 138 | (let ((doc nil) (decls nil)) |
| 139 | (do ((forms body (cdr forms))) (nil) |
| 140 | (let ((form (and forms (car forms)))) |
| 141 | (cond ((and allow-docstring-p (not doc) (stringp form) (cdr forms)) |
| 142 | (setf doc form)) |
| 143 | ((and (consp form) |
| 144 | (eq (car form) 'declare)) |
| 145 | (setf decls (append decls (cdr form)))) |
| 146 | (t (return (values (and doc (list doc)) |
| 147 | (and decls (list (cons 'declare decls))) |
| 148 | forms)))))))) |
| 149 | |
| 150 | #-cmu |
| 151 | (progn |
| 152 | (declaim (inline fixnump)) |
| 153 | (defun fixnump (object) |
| 154 | "Answer non-nil if OBJECT is a fixnum, or nil if it isn't." |
| 155 | (typep object 'fixnum))) |
| 156 | |
| 157 | ;;;-------------------------------------------------------------------------- |
| 158 | ;;; Generating symbols. |
| 159 | |
| 160 | (defmacro with-gensyms (syms &body body) |
| 161 | "Everyone's favourite macro helper." |
| 162 | `(let (,@(mapcar (lambda (sym) `(,sym (gensym ,(symbol-name sym)))) |
| 163 | (listify syms))) |
| 164 | ,@body)) |
| 165 | |
| 166 | (defmacro let*/gensyms (binds &body body) |
| 167 | "A macro helper. BINDS is a list of binding pairs (VAR VALUE), where VALUE |
| 168 | defaults to VAR. The result is that BODY is evaluated in a context where |
| 169 | each VAR is bound to a gensym, and in the final expansion, each of those |
| 170 | gensyms will be bound to the corresponding VALUE." |
| 171 | (labels ((more (binds) |
| 172 | (let ((tmp (gensym "TMP")) (bind (car binds))) |
| 173 | `((let ((,tmp ,(cadr bind)) |
| 174 | (,(car bind) (gensym ,(symbol-name (car bind))))) |
| 175 | `(let ((,,(car bind) ,,tmp)) |
| 176 | ,,@(if (cdr binds) |
| 177 | (more (cdr binds)) |
| 178 | body))))))) |
| 179 | (if (null binds) |
| 180 | `(progn ,@body) |
| 181 | (car (more (mapcar #'pairify (listify binds))))))) |
| 182 | |
| 183 | ;;;-------------------------------------------------------------------------- |
| 184 | ;;; Some simple yet useful control structures. |
| 185 | |
| 186 | (defmacro nlet (name binds &body body) |
| 187 | "Scheme's named let." |
| 188 | (multiple-value-bind (vars vals) |
| 189 | (loop for bind in binds |
| 190 | for (var val) = (pairify bind nil) |
| 191 | collect var into vars |
| 192 | collect val into vals |
| 193 | finally (return (values vars vals))) |
| 194 | `(labels ((,name ,vars |
| 195 | ,@body)) |
| 196 | (,name ,@vals)))) |
| 197 | |
| 198 | (defmacro while (cond &body body) |
| 199 | "If COND is false, evaluate to nil; otherwise evaluate BODY and try again." |
| 200 | `(loop (unless ,cond (return)) (progn ,@body))) |
| 201 | |
| 202 | (defmacro until (cond &body body) |
| 203 | "If COND is true, evaluate to nil; otherwise evaluate BODY and try again." |
| 204 | `(loop (when ,cond (return)) (progn ,@body))) |
| 205 | |
| 206 | (compile-time-defun do-case2-like (kind vform clauses) |
| 207 | "Helper function for `case2' and `ecase2'." |
| 208 | (with-gensyms (scrutinee argument) |
| 209 | `(multiple-value-bind (,scrutinee ,argument) ,vform |
| 210 | (declare (ignorable ,argument)) |
| 211 | (,kind ,scrutinee |
| 212 | ,@(mapcar (lambda (clause) |
| 213 | (destructuring-bind |
| 214 | (cases (&optional varx vary) &rest forms) |
| 215 | clause |
| 216 | `(,cases |
| 217 | ,@(if varx |
| 218 | (list `(let ((,(or vary varx) ,argument) |
| 219 | ,@(and vary |
| 220 | `((,varx ,scrutinee)))) |
| 221 | ,@forms)) |
| 222 | forms)))) |
| 223 | clauses))))) |
| 224 | |
| 225 | (defmacro case2 (vform &body clauses) |
| 226 | "VFORM is a form which evaluates to two values, SCRUTINEE and ARGUMENT. |
| 227 | The CLAUSES have the form (CASES ([[SCRUVAR] ARGVAR]) FORMS...), where a |
| 228 | standard `case' clause has the form (CASES FORMS...). The `case2' form |
| 229 | evaluates the VFORM, and compares the SCRUTINEE to the various CASES, in |
| 230 | order, just like `case'. If there is a match, then the corresponding |
| 231 | FORMs are evaluated with ARGVAR bound to the ARGUMENT and SCRUVAR bound to |
| 232 | the SCRUTINEE (where specified). Note the bizarre defaulting behaviour: |
| 233 | ARGVAR is less optional than SCRUVAR." |
| 234 | (do-case2-like 'case vform clauses)) |
| 235 | |
| 236 | (defmacro ecase2 (vform &body clauses) |
| 237 | "Like `case2', but signals an error if no clause matches the SCRUTINEE." |
| 238 | (do-case2-like 'ecase vform clauses)) |
| 239 | |
| 240 | ;;;-------------------------------------------------------------------------- |
| 241 | ;;; with-places |
| 242 | |
| 243 | (defmacro %place-ref (getform setform newtmp) |
| 244 | "Grim helper macro for with-places." |
| 245 | (declare (ignore setform newtmp)) |
| 246 | getform) |
| 247 | |
| 248 | (define-setf-expander %place-ref (getform setform newtmp) |
| 249 | "Grim helper macro for with-places." |
| 250 | (values nil nil newtmp setform getform)) |
| 251 | |
| 252 | (defmacro with-places ((&key environment) places &body body) |
| 253 | "A hairy helper, for writing setf-like macros. PLACES is a list of binding |
| 254 | pairs (VAR PLACE), where PLACE defaults to VAR. The result is that BODY |
| 255 | is evaluated in a context where each VAR is bound to a gensym, and in the |
| 256 | final expansion, each of those gensyms will be bound to a symbol-macro |
| 257 | capable of reading or setting the value of the corresponding PLACE." |
| 258 | (if (null places) |
| 259 | `(progn ,@body) |
| 260 | (let*/gensyms (environment) |
| 261 | (labels |
| 262 | ((more (places) |
| 263 | (let ((place (car places))) |
| 264 | (with-gensyms (tmp valtmps valforms |
| 265 | newtmps setform getform) |
| 266 | `((let ((,tmp ,(cadr place)) |
| 267 | (,(car place) |
| 268 | (gensym ,(symbol-name (car place))))) |
| 269 | (multiple-value-bind |
| 270 | (,valtmps ,valforms |
| 271 | ,newtmps ,setform ,getform) |
| 272 | (get-setf-expansion ,tmp |
| 273 | ,environment) |
| 274 | (list 'let* |
| 275 | (mapcar #'list ,valtmps ,valforms) |
| 276 | `(symbol-macrolet ((,,(car place) |
| 277 | (%place-ref ,,getform |
| 278 | ,,setform |
| 279 | ,,newtmps))) |
| 280 | ,,@(if (cdr places) |
| 281 | (more (cdr places)) |
| 282 | body)))))))))) |
| 283 | (car (more (mapcar #'pairify (listify places)))))))) |
| 284 | |
| 285 | ;;;-------------------------------------------------------------------------- |
| 286 | ;;; Update-in-place macros built using with-places. |
| 287 | |
| 288 | (defmacro update-place (op place arg &environment env) |
| 289 | "Update PLACE with the value of OP PLACE ARG, returning the new value." |
| 290 | (with-places (:environment env) (place) |
| 291 | `(setf ,place (,op ,place ,arg)))) |
| 292 | |
| 293 | (defmacro update-place-after (op place arg &environment env) |
| 294 | "Update PLACE with the value of OP PLACE ARG, returning the old value." |
| 295 | (with-places (:environment env) (place) |
| 296 | (with-gensyms (x) |
| 297 | `(let ((,x ,place)) |
| 298 | (setf ,place (,op ,x ,arg)) |
| 299 | ,x)))) |
| 300 | |
| 301 | (defmacro incf-after (place &optional (by 1)) |
| 302 | "Increment PLACE by BY, returning the old value." |
| 303 | `(update-place-after + ,place ,by)) |
| 304 | |
| 305 | (defmacro decf-after (place &optional (by 1)) |
| 306 | "Decrement PLACE by BY, returning the old value." |
| 307 | `(update-place-after - ,place ,by)) |
| 308 | |
| 309 | ;;;-------------------------------------------------------------------------- |
| 310 | ;;; Locatives. |
| 311 | |
| 312 | (defstruct (loc (:predicate locp) (:constructor make-loc (reader writer))) |
| 313 | "Locative data type. See `locf' and `ref'." |
| 314 | (reader (slot-uninitialized) :type function) |
| 315 | (writer (slot-uninitialized) :type function)) |
| 316 | |
| 317 | (defmacro locf (place &environment env) |
| 318 | "Slightly cheesy locatives. (locf PLACE) returns an object which, using |
| 319 | the `ref' function, can be used to read or set the value of PLACE. It's |
| 320 | cheesy because it uses closures rather than actually taking the address of |
| 321 | something. Also, unlike Zetalisp, we don't overload `car' to do our dirty |
| 322 | work." |
| 323 | (multiple-value-bind |
| 324 | (valtmps valforms newtmps setform getform) |
| 325 | (get-setf-expansion place env) |
| 326 | `(let* (,@(mapcar #'list valtmps valforms)) |
| 327 | (make-loc (lambda () ,getform) |
| 328 | (lambda (,@newtmps) ,setform))))) |
| 329 | |
| 330 | (declaim (inline loc (setf loc))) |
| 331 | |
| 332 | (defun ref (loc) |
| 333 | "Fetch the value referred to by a locative." |
| 334 | (funcall (loc-reader loc))) |
| 335 | |
| 336 | (defun (setf ref) (new loc) |
| 337 | "Store a new value in the place referred to by a locative." |
| 338 | (funcall (loc-writer loc) new)) |
| 339 | |
| 340 | (defmacro with-locatives (locs &body body) |
| 341 | "LOCS is a list of items of the form (SYM [LOC-EXPR]), where SYM is a |
| 342 | symbol and LOC-EXPR evaluates to a locative. If LOC-EXPR is omitted, it |
| 343 | defaults to SYM. As an abbreviation for a common case, LOCS may be a |
| 344 | symbol instead of a list. The BODY is evaluated in an environment where |
| 345 | each SYM is a symbol macro which expands to (ref LOC-EXPR) -- or, in fact, |
| 346 | something similar which doesn't break if LOC-EXPR has side-effects. Thus, |
| 347 | references, including `setf' forms, fetch or modify the thing referred to |
| 348 | by the LOC-EXPR. Useful for covering over where something uses a |
| 349 | locative." |
| 350 | (setf locs (mapcar #'pairify (listify locs))) |
| 351 | (let ((tt (mapcar (lambda (l) (declare (ignore l)) (gensym)) locs)) |
| 352 | (ll (mapcar #'cadr locs)) |
| 353 | (ss (mapcar #'car locs))) |
| 354 | `(let (,@(mapcar (lambda (tmp loc) `(,tmp ,loc)) tt ll)) |
| 355 | (symbol-macrolet (,@(mapcar (lambda (sym tmp) |
| 356 | `(,sym (ref ,tmp))) ss tt)) |
| 357 | ,@body)))) |
| 358 | |
| 359 | ;;;----- That's all, folks -------------------------------------------------- |