3 ;;; Protocol for property sets
5 ;;; (c) 2009 Straylight/Edgeware
8 ;;;----- Licensing notice ---------------------------------------------------
10 ;;; This file is part of the Sensble Object Design, an object system for C.
12 ;;; SOD 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.
17 ;;; SOD 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.
22 ;;; You should have received a copy of the GNU General Public License
23 ;;; along with SOD; if not, write to the Free Software Foundation,
24 ;;; Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
28 ;;;--------------------------------------------------------------------------
29 ;;; Property representation.
31 (export 'property-key)
32 (defun property-key (name)
33 "Convert NAME into a keyword.
35 If NAME isn't a symbol already, then flip its case (using
36 `frob-identifier'), and intern into the `keyword' package."
39 (string (intern (frob-identifier name) :keyword))))
41 (export 'property-type)
42 (defgeneric property-type (value)
43 (:documentation "Guess a sensible property type to use for VALUE.")
44 (:method ((value symbol)) :symbol)
45 (:method ((value integer)) :integer)
46 (:method ((value string)) :string)
47 (:method ((value character)) :char)
48 (:method (value) :other))
50 (export '(property propertyp make-property
51 p-name p-value p-type p-key p-seenp))
53 (:predicate propertyp)
55 (:constructor make-property
57 &key (type (property-type value))
60 &aux (key (property-key name))
61 (location (file-location %loc)))))
62 "A simple structure for holding a property in a property set.
64 The main useful feature is the ability to tick off properties which have
65 been used, so that we can complain about unrecognized properties.
67 An explicit type tag is necessary because we need to be able to talk
68 distinctly about identifiers, strings and symbols, and we've only got two
69 obvious Lisp types to play with. Sad, but true."
71 (name nil :type (or string symbol))
73 (type nil :type symbol)
74 (location (file-location nil) :type file-location)
75 (key nil :type symbol)
76 (seenp nil :type boolean))
78 (defun string-to-symbol
79 (string &key (package *package*) (swap-case t) (swap-hyphen t))
80 "Convert STRING to a symbol in PACKAGE.
82 Parse off a `PACKAGE:' prefix from STRING if necessary, to identify the
83 package; PACKAGE is used if there isn't a prefix. A doubled colon allows
84 access to internal symbols, and will intern if necessary. Note that
85 escape characters are /not/ processed; don't put colons in package names
86 if you want to use them from SOD property sets.
88 The portions of the string are modified by `frob-identifier'; the
89 arguments SWAP-CASE and SWAP-HYPHEN are passed to `frob-identifier' to
90 control this process."
92 (let* ((length (length string))
93 (colon (position #\: string)))
94 (multiple-value-bind (start internalp)
95 (cond ((not colon) (values 0 t))
96 ((and (< (1+ colon) length)
97 (char= (char string (1+ colon)) #\:))
98 (values (+ colon 2) t))
100 (values (1+ colon) nil)))
102 (let* ((package-name (if (zerop colon) "KEYWORD"
103 (frob-identifier (subseq string 0 colon)
105 :swap-hyphen swap-hyphen)))
106 (found (find-package package-name)))
108 (error "Unknown package `~A'" package-name))
109 (setf package found)))
110 (let ((name (frob-identifier (subseq string start)
112 :swap-hyphen swap-hyphen)))
113 (multiple-value-bind (symbol status)
114 (funcall (if internalp #'intern #'find-symbol) name package)
115 (cond ((or internalp (eq status :external))
118 (error "Symbol `~A' not found in package `~A'"
119 name (package-name package)))
121 (error "Symbol `~A' not external in package `~A'"
122 name (package-name package)))))))))
124 (export 'coerce-property-value)
125 (defgeneric coerce-property-value (value type wanted)
127 "Convert VALUE, a property of type TYPE, to be of type WANTED.
129 It's sensible to add additional methods to this function, but there are
130 all the ones we need.")
132 ;; If TYPE matches WANTED, we'll assume that VALUE already has the right
133 ;; form. Otherwise, if nothing else matched, then I guess we'll have to
134 ;; say it didn't work.
135 (:method (value type wanted)
136 (if (eql type wanted) value
137 (error "Incorrect type: expected ~A but found ~A" wanted type)))
139 ;; If the caller asks for type T then give him the raw thing.
140 (:method (value type (wanted (eql t)))
143 ;;;--------------------------------------------------------------------------
144 ;;; Property set representation.
146 (export '(pset psetp))
147 (defstruct (pset (:predicate psetp)
148 (:constructor %make-pset)
152 Wrapped up in a structure so that we can define a print function."
153 (hash (make-hash-table) :type hash-table))
155 (export '(make-pset pset-get pset-store pset-map))
156 (declaim (inline make-pset pset-get pset-store pset-map))
159 "Constructor for property sets."
162 (defun pset-get (pset key)
163 "Look KEY up in PSET and return what we find.
165 If there's no property by that name, return NIL."
166 (values (gethash key (%pset-hash pset))))
168 (defun pset-store (pset prop)
169 "Store property PROP in PSET.
171 Overwrite or replace any previous property with the same name. Mutates
173 (setf (gethash (p-key prop) (%pset-hash pset)) prop))
175 (defun pset-map (func pset)
176 "Call FUNC for each property in PSET."
177 (maphash (lambda (key value) (declare (ignore key)) (funcall func value))
180 (export 'with-pset-iterator)
181 (defmacro with-pset-iterator ((name pset) &body body)
182 "Evaluate BODY with NAME bound to a macro returning properties from PSET.
184 Evaluating (NAME) returns a property object or nil if all properties have
186 (with-gensyms (next win key value)
187 `(with-hash-table-iterator (,next (%pset-hash ,pset))
189 (multiple-value-bind (,win ,key ,value) (,next)
190 (declare (ignore ,key))
194 ;;;--------------------------------------------------------------------------
195 ;;; `Cooked' property set operations.
197 (export 'store-property)
198 (defun store-property
199 (pset name value &key (type (property-type value)) location)
200 "Store a property in PSET."
202 (make-property name value :type type :location location)))
204 (export 'get-property)
205 (defun get-property (pset name type &optional default)
206 "Fetch a property from a property set.
208 If a property NAME is not found in PSET, or if a property is found, but
209 its type doesn't match TYPE, then return DEFAULT and nil; otherwise return
210 the value and its file location. In the latter case, mark the property as
213 The value returned depends on the TYPE argument provided. If you pass
214 `nil' then you get back the entire `property' object. If you pass `t',
215 then you get whatever was left in the property set, uninterpreted.
216 Otherwise the value is coerced to the right kind of thing (where possible)
219 If PSET is nil, then return DEFAULT."
221 (let ((prop (and pset (pset-get pset (property-key name)))))
222 (with-default-error-location ((and prop (p-location prop)))
224 (values default nil))
226 (setf (p-seenp prop) t)
227 (values prop (p-location prop)))
229 (setf (p-seenp prop) t)
230 (values (coerce-property-value (p-value prop)
233 (p-location prop)))))))
235 (export 'add-property)
237 (pset name value &key (type (property-type value)) location)
238 "Add a property to PSET.
240 If a property with the same NAME already exists, report an error."
242 (with-default-error-location (location)
243 (let ((existing (get-property pset name nil)))
245 (error "Property ~S already defined~@[ at ~A~]"
246 name (p-location existing)))
247 (store-property pset name value :type type :location location))))
249 (export 'make-property-set)
250 (defun make-property-set (&rest plist)
251 "Make a new property set, with given properties.
253 This isn't the way to make properties when parsing, but it works well for
254 programmatic generation. The arguments should form a property list
255 (alternating keywords and values is good).
257 An attempt is made to guess property types from the Lisp types of the
258 values. This isn't always successful but it's not too bad. The
259 alternative is manufacturing a `property-value' object by hand and
260 stuffing into the set."
262 (property-set plist))
264 (export 'property-set)
265 (defgeneric property-set (thing)
267 "Convert THING into a property set.")
268 (:method ((pset pset)) pset)
269 (:method ((list list))
270 "Convert a list into a property set. This works for alists and plists."
271 (multiple-value-bind (next name value)
272 (if (and list (consp (car list)))
273 (values #'cdr #'caar #'cdar)
274 (values #'cddr #'car #'cadr))
275 (do ((pset (make-pset))
276 (list list (funcall next list)))
278 (add-property pset (funcall name list) (funcall value list))))))
280 (export 'check--unused-properties)
281 (defun check-unused-properties (pset)
282 "Issue errors about unused properties in PSET."
284 (pset-map (lambda (prop)
285 (unless (p-seenp prop)
286 (cerror*-with-location (p-location prop)
287 "Unknown property `~A'"
289 (setf (p-seenp prop) t)))
292 ;;;--------------------------------------------------------------------------
295 (defmacro default-slot-from-property
296 ((instance slot slot-names)
298 &optional (pvar (gensym "PROP-"))
301 "Initialize a slot from a property.
303 We initialize SLOT in INSTANCE. In full: if PSET contains a property
304 called NAME, then convert it to TYPE, bind the value to PVAR and evaluate
305 CONVERT-FORMS -- these default to just using the property value. If
306 there's no property, and the slot is named in SLOT-NAMES and currently
307 unbound, then evaluate DEFAULT-FORMS and use their value to compute the
310 (once-only (instance slot slot-names pset property type)
312 `(multiple-value-bind (,pvar ,floc)
313 (get-property ,pset ,property ,type)
315 (setf (slot-value ,instance ,slot)
316 (with-default-error-location (,floc)
317 ,@(or convert-forms `(,pvar))))
318 (default-slot (,instance ,slot ,slot-names)
319 ,@default-forms))))))
321 ;;;----- That's all, folks --------------------------------------------------