|Programming language||Common Lisp|
|Library type||Operator overlay macro|
|Date||22 oct 2012|
(Nov 2012 dist and later)
|Depends on||Depended on by|
place-modifiers essentially gives access to hundreds of modify-macros through one single macro:
(Things start a bit slowly, but don't worry, it gets more and more interesting!)
⚓ 3 trivial examples
(let ((place '(old))) (
cons'new place)) place) == (let ((place '(old))) (push 'new place) place) => (NEW OLD)
;; Reminder for newbies: string-equal is case-insensitive comparison. (let ((place '(
"HELLO"place :test #'string-equal)) place) == (let ((place '(
"HELLO"place :test #'string-equal) place) => (
⚓ Equivalent to hundreds of modify macros!
;; Traditionally "nreversef" (let ((place (list 1 2 3))) (
nreverseplace)) place) => (3 2 1)
;; "string-upcasef"?... (let ((place
string-upcaseplace)) place) =>
;; "listf"? (let ((place 'atom)) (
listplace)) place) => (ATOM)
;; "class-off"? (let ((place 'symbol)) (
class-ofplace)) place) => #<BUILT-IN-CLASS SYMBOL>
;; "parse-integerf"? (let ((place
parse-integerplace)) place) => 1986
⚓ Why not just write it out by hand?
One might wonder, why not just write this instead?
(let ((place (list 1 2 3))) (setf place (nreverse place)) place) ;; instead of (let ((place (list 1 2 3))) (
(And forget about
(nreverse (list 1 2 3)) or
(list 3 2 1) because that's missing the point. ;P) The answer is that "place" might of course be much longer-named and/or more complex than this. And of course, multiple evaluation of the place will be averted, which is important when side-effects and/or expensive accesses are involved.
(let ((my-list-of-three-elements (list 1 2 3))) (
nreversemy-list-of-three-elements)) my-list-of-three-elements) == (let ((my-list-of-three-elements (list 1 2 3))) (setf my-list-of-three-elements (nreverse my-list-of-three-elements)) my-list-of-three-elements)
(let ((hash (make-hash-table))) (setf (gethash 'key hash) 10) (
/(gethash (print 'key) hash) 5)) (gethash 'key hash)) == (let ((hash (make-hash-table))) (setf (gethash 'key hash) 10) (let ((key (print 'key))) (setf (gethash key hash) (/ (gethash key hash) 5))) (gethash 'key hash)) -| KEY => 2, T
modify return values,
modify normally returns the new value(s) of the place, per the usual conventions:
But one simple yet very useful feature is to be able to return the old value instead:
⚓ place-modification-expression VS place
(let ((object (vector 'e))) (values (
list(aref object 0)))) object)) => E, #((E)) or #(E), (E) ?
⚓ Conservative recursion through "spots" by default
modify is "conservative" by default, so as soon as it encounters a possible place while recursing through the "spots" (described and explained below), then it will treat that as the place. This is the most intuitive possible default and is usually what you want.
In the above example,
(aref object 0) is the place to modify, not object.
⚓ Inconceivable places
Some place-modifiers are known to
modify as being "inconceivable places", which allows conservative recursion to proceed (at least) one step further, much conveniently:
⚓ Speculative recursion through "spots" in search of explicit :place form
After finding the most conservative place,
modify will still speculatively recurse through the remaining "spots" in search of a
:place "local special form", which would explicitly indicate at what level lies the intended place, overriding the conservative behavior.
⚓Possible place at top-level: treated as place-modification-expression
Of course, the "top-level" (ignoring
modify can only accept a place-modification-expression and not a place, so there can be no ambiguity there:
modify can accept multiple place-modification-expressions, in which case the modifications will happen in sequence, much in the same way as
setf with multiple places.
⚓ Place-modifier variants
Up to this point, we've always used the "primary variant", which is the one you'll need most often, but each place-modifier kind can have up to 4 variants, though most only have one or two. The "variant" determines which argument is treated as the "spot", positionally.
The determination of which variant maps to which spot is made by the definer of the place-modifier.
⚓ Some statistics about place-modifier variants
(let ((variant-counts (vector 0 0 0 0))) (
place-modifiers:map-infos(lambda (name info) (declare (ignore name)) (
1+(aref variant-counts (1- (length (
place-modifiers:spot-indexesinfo)))))))) variant-counts) => #(301 172 35 2)
So as of version 2.1, there are 301 place-modifiers with one single variant, 172 with 2 variants, and only 37 with 3 or 4 variants.