The place-modifiers Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The place-modifiers Reference Manual

This is the place-modifiers Reference Manual, version 2.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:24:01 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Project's home: http://www.hexstreamsoft.com/projects/place-modifiers/


place-modifiers essentially gives access to hundreds of modify-macros
through one single macro: MODIFY.

(Things start a bit slowly, but don't worry, it gets more and more interesting!)


3 trivial examples
------------------

(let ((place 7))
  (modify (1+ place))
  place)
==
(let ((place 7))
  (incf place)
  place)
=> 8

(let ((place '(old)))
  (modify (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" "hi")))
  (modify (adjoin "HELLO" place :test #'string-equal))
  place)
==
(let ((place '("hello" "hi")))
  (pushnew "HELLO" place :test #'string-equal)
  place)
=> ("hello" "hi")


Equivalent to hundreds of modify macros!
----------------------------------------

Not very exciting so far. But INCF, PUSH and PUSHNEW give you access to 3
modify-macros, whereas MODIFY gives you access to literally hundreds!

;; Traditionally "nreversef"
(let ((place (list 1 2 3)))
  (modify (nreverse place))
  place)
=> (3 2 1)

;; "string-upcasef"?...
(let ((place "Yay"))
  (modify (string-upcase place))
  place)
=> "YAY"

;; "listf"?
(let ((place 'atom))
  (modify (list place))
  place)
=> (ATOM)

;; "class-off"?
(let ((place 'symbol))
  (modify (class-of place))
  place)
=> #

;; "parse-integerf"?
(let ((place "1986"))
  (modify (parse-integer place))
  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)))
  (modify (nreverse place))
  place)

(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)))
  (modify (nreverse my-list-of-three-elements))
  place)
==
(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)
  (modify (/ (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, :old
--------------------------

MODIFY normally returns the new value(s) of the place, per the usual conventions:

(let ((place 2))
  (values (modify (expt place 8))
          place))
=> 256, 256

But one simple yet very useful feature is to be able to return the old value instead:

(let ((place 2))
  (values (modify (:old (expt place 8)))
          place))
=> 2, 256


Ambiguity: place-modification-expression VS place
-------------------------------------------------

Some place-modifiers are also valid places. One example is AREF. In
the following example, how does MODIFY know which of "(aref object 0)"
or "object" should be interpreted as being the place to modify?

(let ((object (vector 'e)))
  (values (modify (:old (list (aref object 0))))
          object))
=> E, #((E))
or #(E), (E) ?


Conservative recursion through "spots" by default
-------------------------------------------------

It's simple: 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.

;; "(aref object 0)" is the place to modify, not "object". Conservative default.
(let ((object (vector 'e)))
  (values (modify (:old (list (aref object 0))))
          object))
=> E, #((E))


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:

(let ((list '((d . 4))))
  (values (modify (:old (cons 'first (list* 'a 1 'b 2 (acons 'c 3 list)))))
          list))
=> ((D . 4)), (FIRST A 1 B 2 (C . 3) (D . 4))


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.

(let ((object (vector 'e)))
  (values (modify (:old (list (aref (:place object) 0))))
          object))
=> #(E), (E) ?


Possible place at top-level: treated as place-modification-expression
---------------------------------------------------------------------

Of course, the "top-level" (ignoring :old) of MODIFY can only accept a
place-modification-expression and not a place, so there can be no
ambiguity there:

(let ((object (vector 'e)))
  (values (modify (:old (aref (:place object) 0)))
          object))
=> #(E), E


Multiple place-modification-expressions: SETF-like
--------------------------------------------------

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.

(let ((x 'a) (y 'b))
  (values (modify (list x)
                  (:old (cons y x)))
          x
          y))
==
(let ((x 'a) (y 'b))
  (values (progn (modify (list x))
                 (modify (:old (cons y x))))
          x
          y))
=> (A), (B A), B


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.

;; Primary variant


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))
     (modify (1+ (aref variant-counts
                       (1- (length (spot-indexes info))))))))
  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.


This library is in the Public Domain.
See the UNLICENSE file for details.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 place-modifiers

Author

Jean-Philippe Paradis <hexstream@gmail.com>

License

Public Domain

Description

Essentially gives access to hundreds of modify-macros through one single macro: MODIFY.

Version

2.1

Dependencies
Source

place-modifiers.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 place-modifiers.asd

Location

place-modifiers.asd

Systems

place-modifiers (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 place-modifiers/package.lisp

Parent

place-modifiers (system)

Location

package.lisp

Packages

place-modifiers


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 place-modifiers/info.lisp

Dependency

package.lisp (file)

Parent

place-modifiers (system)

Location

info.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 place-modifiers/main.lisp

Dependency

info.lisp (file)

Parent

place-modifiers (system)

Location

main.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.5 place-modifiers/definitions.lisp

Dependency

main.lisp (file)

Parent

place-modifiers (system)

Location

definitions.lisp


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 place-modifiers

Source

package.lisp (file)

Nickname

place-modifier

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *spot-index-format*
Package

place-modifiers

Source

info.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: define (&key SPOT-INDEX-FORMAT) &body DEFINITIONS
Package

place-modifiers

Source

info.lisp (file)

Macro: modify &rest PLACE-MODIFICATION-EXPRESSIONS
Package

place-modifiers

Source

main.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: convert-spot-indexes SPOT-INDEXES SOURCE-FORMAT DESTINATION-FORMAT &key (PLURALITY-FORMAT DESTINATION-PLURALITY-FORMAT)
Package

place-modifiers

Source

info.lisp (file)

Function: ensure NAMES INCONCEIVABLE-PLACE-P &key SPOT-INDEXES SPOT-INDEX-FORMAT
Package

place-modifiers

Source

info.lisp (file)

Function: locate NAME &key ERRORP
Package

place-modifiers

Source

info.lisp (file)

Function: map-infos FUNCTION
Package

place-modifiers

Source

info.lisp (file)

Function: parse-operator NAME/VARIANT &key ERRORP
Package

place-modifiers

Source

main.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Generic functions

Generic Function: inconceivable-place-p OBJECT
Package

place-modifiers

Source

info.lisp (file)

Methods
Method: inconceivable-place-p (STANDARD-INFO standard-info)

automatically generated reader method

Generic Function: names OBJECT
Package

place-modifiers

Source

info.lisp (file)

Methods
Method: names (STANDARD-INFO standard-info)

automatically generated reader method

Generic Function: spot-index INFO VARIANT
Package

place-modifiers

Source

info.lisp (file)

Methods
Method: spot-index (INFO standard-info) VARIANT
Generic Function: spot-indexes OBJECT &key FORMAT PLURALITY-FORMAT
Package

place-modifiers

Source

info.lisp (file)

Methods
Method: spot-indexes (INFO standard-info) &key FORMAT PLURALITY-FORMAT

Previous: , Up: Exported definitions   [Contents][Index]

5.1.5 Classes

Class: info ()
Package

place-modifiers

Source

info.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

standard-info (class)

Class: standard-info ()
Package

place-modifiers

Source

info.lisp (file)

Direct superclasses

info (class)

Direct methods
Direct slots
Slot: %names
Type

list

Initargs

:names

Readers

names (generic function)

Slot: %inconceivable-place-p
Type

boolean

Initargs

:inconceivable-place-p

Readers

inconceivable-place-p (generic function)

Slot: %spot-indexes
Type

list

Initargs

:spot-indexes


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *infos*
Package

place-modifiers

Source

info.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: %actual-spot-index ARGS-COUNT SPOT-INDEX NAME
Package

place-modifiers

Source

main.lisp (file)

Function: %analyze PME-OR-PLACE &key ON-PME ON-PLACE ON-AMBIGUOUS ON-PLACE-MARKER
Package

place-modifiers

Source

main.lisp (file)

Function: %augment-template BASE-TEMPLATE OPERATOR BEFORE-SPOT AFTER-SPOT
Package

place-modifiers

Source

main.lisp (file)

Function: %augmented-template-caller FUNCTION TEMPLATE
Package

place-modifiers

Source

main.lisp (file)

Function: %expand PLACE-MODIFICATION-EXPRESSION ENV
Package

place-modifiers

Source

main.lisp (file)

Function: %finish TEMPLATE PLACE ENV OLDP
Package

place-modifiers

Source

main.lisp (file)

Function: %plurality-aware-map FUNCTION LIST-OR-ATOM DESTINATION-PLURALITY-FORMAT &key FORCEP
Package

place-modifiers

Source

info.lisp (file)

Function: %split PM-INFO VARIANT ARGS PLACE-MODIFICATION-EXPRESSION
Package

place-modifiers

Source

main.lisp (file)

Function: %split-at-index SEQUENCE INDEX
Package

place-modifiers

Source

main.lisp (file)

Function: %walk-conservatively-non-top-level PME-OR-PLACE
Package

place-modifiers

Source

main.lisp (file)

Function: %walk-speculatively-non-top-level PME-OR-PLACE TEMPLATE
Package

place-modifiers

Source

main.lisp (file)

Function: nop &rest ARGS
Package

place-modifiers

Source

main.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   P  
Index Entry  Section

F
File, Lisp, place-modifiers.asd: The place-modifiers<dot>asd file
File, Lisp, place-modifiers/definitions.lisp: The place-modifiers/definitions<dot>lisp file
File, Lisp, place-modifiers/info.lisp: The place-modifiers/info<dot>lisp file
File, Lisp, place-modifiers/main.lisp: The place-modifiers/main<dot>lisp file
File, Lisp, place-modifiers/package.lisp: The place-modifiers/package<dot>lisp file

L
Lisp File, place-modifiers.asd: The place-modifiers<dot>asd file
Lisp File, place-modifiers/definitions.lisp: The place-modifiers/definitions<dot>lisp file
Lisp File, place-modifiers/info.lisp: The place-modifiers/info<dot>lisp file
Lisp File, place-modifiers/main.lisp: The place-modifiers/main<dot>lisp file
Lisp File, place-modifiers/package.lisp: The place-modifiers/package<dot>lisp file

P
place-modifiers.asd: The place-modifiers<dot>asd file
place-modifiers/definitions.lisp: The place-modifiers/definitions<dot>lisp file
place-modifiers/info.lisp: The place-modifiers/info<dot>lisp file
place-modifiers/main.lisp: The place-modifiers/main<dot>lisp file
place-modifiers/package.lisp: The place-modifiers/package<dot>lisp file

Jump to:   F   L   P  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %  
C   D   E   F   G   I   L   M   N   P   S  
Index Entry  Section

%
%actual-spot-index: Internal functions
%analyze: Internal functions
%augment-template: Internal functions
%augmented-template-caller: Internal functions
%expand: Internal functions
%finish: Internal functions
%plurality-aware-map: Internal functions
%split: Internal functions
%split-at-index: Internal functions
%walk-conservatively-non-top-level: Internal functions
%walk-speculatively-non-top-level: Internal functions

C
convert-spot-indexes: Exported functions

D
define: Exported macros

E
ensure: Exported functions

F
Function, %actual-spot-index: Internal functions
Function, %analyze: Internal functions
Function, %augment-template: Internal functions
Function, %augmented-template-caller: Internal functions
Function, %expand: Internal functions
Function, %finish: Internal functions
Function, %plurality-aware-map: Internal functions
Function, %split: Internal functions
Function, %split-at-index: Internal functions
Function, %walk-conservatively-non-top-level: Internal functions
Function, %walk-speculatively-non-top-level: Internal functions
Function, convert-spot-indexes: Exported functions
Function, ensure: Exported functions
Function, locate: Exported functions
Function, map-infos: Exported functions
Function, nop: Internal functions
Function, parse-operator: Exported functions

G
Generic Function, inconceivable-place-p: Exported generic functions
Generic Function, names: Exported generic functions
Generic Function, spot-index: Exported generic functions
Generic Function, spot-indexes: Exported generic functions

I
inconceivable-place-p: Exported generic functions
inconceivable-place-p: Exported generic functions

L
locate: Exported functions

M
Macro, define: Exported macros
Macro, modify: Exported macros
map-infos: Exported functions
Method, inconceivable-place-p: Exported generic functions
Method, names: Exported generic functions
Method, spot-index: Exported generic functions
Method, spot-indexes: Exported generic functions
modify: Exported macros

N
names: Exported generic functions
names: Exported generic functions
nop: Internal functions

P
parse-operator: Exported functions

S
spot-index: Exported generic functions
spot-index: Exported generic functions
spot-indexes: Exported generic functions
spot-indexes: Exported generic functions

Jump to:   %  
C   D   E   F   G   I   L   M   N   P   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   %   *  
S  
Index Entry  Section

%
%inconceivable-place-p: Exported classes
%names: Exported classes
%spot-indexes: Exported classes

*
*infos*: Internal special variables
*spot-index-format*: Exported special variables

S
Slot, %inconceivable-place-p: Exported classes
Slot, %names: Exported classes
Slot, %spot-indexes: Exported classes
Special Variable, *infos*: Internal special variables
Special Variable, *spot-index-format*: Exported special variables

Jump to:   %   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   I   P   S  
Index Entry  Section

C
Class, info: Exported classes
Class, standard-info: Exported classes

I
info: Exported classes

P
Package, place-modifiers: The place-modifiers package
place-modifiers: The place-modifiers system
place-modifiers: The place-modifiers package

S
standard-info: Exported classes
System, place-modifiers: The place-modifiers system

Jump to:   C   I   P   S