Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the modf Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 14:25:58 2020 GMT+0.
| • Introduction | What modf is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
* Modf
Modf is a =setf= like macro for functional programming. Like =setf=, Modf knows
how to modify many Lisp objects such that a place will evaluate to a new value
of your choosing. Unlike =setf=, Modf doesn't mutate the data in anyway.
Instead it creates a new object with the requested changes in place. See [[http://directed-procrastination.blogspot.com/2011/05/introducting-modf-setf-for-functional.html][my
blog]] post on Modf for a bit more info. Be warned though, while the gist is
definitely there, it has become a bit out of date as Modf has progressed.
** What does Modf do?
To give a pathologic example, Modf allows you to change =t= to =nil= in the
following expression easily.
#+BEGIN_SRC lisp
(defparameter *crazy* '(1 #(a (2 #(b (3 #(c (4 t))))))))
==> *CRAZY*
;; Change that last value with Modf
(modf
(cadr (aref (cadr (aref (cadr (aref (cadr *crazy*) 1)) 1)) 1))
nil)
==> (1 #(A (2 #(B (3 #(C (4 NIL)))))))
;; But note that the original data is unchanged
,*crazy*
==> (1 #(A (2 #(B (3 #(C (4 T)))))))
;; Note that the Modf form looks a lot like how you would use setf
(setf
(cadr (aref (cadr (aref (cadr (aref (cadr *crazy*) 1)) 1)) 1))
nil)
==> NIL
,*crazy*
==> (1 #(A (2 #(B (3 #(C (4 NIL)))))))
;; What does Modf gain us, take a look. Look it over. It's all necessary
(macroexpand
'(modf
(cadr (aref (cadr (aref (cadr (aref (cadr *crazy*) 1)) 1)) 1))
nil))
==>
(LET ((#:G1556 *CRAZY*))
(CONS (CAR #:G1556)
(LET ((#:G1555 (CDR #:G1556)))
(CONS
(LET ((#:G1554 (CAR #:G1555)))
(FUNCALL (MODF-FN AREF)
(LET ((#:G1553 (AREF #:G1554 1)))
(CONS (CAR #:G1553)
(LET ((#:G1552 (CDR #:G1553)))
(CONS
(LET ((#:G1551 (CAR #:G1552)))
(FUNCALL (MODF-FN AREF)
(LET ((#:G1550 (AREF #:G1551 1)))
(CONS (CAR #:G1550)
(LET ((#:G1549
(CDR #:G1550)))
(CONS
(LET ((#:G1548
(CAR #:G1549)))
(FUNCALL
(MODF-FN AREF)
(LET ((#:G1547
(AREF #:G1548 1)))
(CONS (CAR #:G1547)
(LET ((#:G1546
(CDR
#:G1547)))
(CONS NIL
(CDR
#:G1546)))))
#:G1548 1))
(CDR #:G1549)))))
#:G1551 1))
(CDR #:G1552)))))
#:G1554 1))
(CDR #:G1555)))))
#+END_SRC
The aim is to make this work for any Lisp object, including CLOS objects and
structures.
** How does Modf work?
It works similar to the way =setf= works. With =setf= expansions are defined
that take some kind of accessor function and turn it into a function that sets
the value at that place. In Modf, expansions are defined that turn an accessor
function into a function that builds a new object the specified change in place.
** Where does Modf work?
Modf strives to be portable and work everywhere as long as Modf expansion
functions are defined. See the section /Defining your own Modf Expansions/. I
aim to cover all primitive data types in CL. As of now, it should work in any
Lisp when working with lists, arrays, hash tables, and, given you have defined
your Modf expanders for your data types, class instances and structs.
For usability purposes, however, a lot of effort has gone into making Modf work
for data even if Modf expansions haven't been defined. This is a very difficult
to impossible task. For one, we have no way of knowing which argument holds the
actual data structure. If no expansion is defined, we assume it is at the first
argument of the place (adjusting for =apply= statements).
In the case of class accessor methods without defined Modf expansions,
Closer-Mop is used to examine the data at run time and produce the functional
changes. For structures we don't even have Closer-Mop to help us and a series
of heuristics are used at run time to try to invert accessor functions (again,
only if no Modf expander has been defined).
If Modf doesn't work for something common out of the box, feel free to post a
bug report. It would be even better if you can think of a way figure out what
to do.
Modf is tested regularly on the major Libre Software implementations (SBCL,
CMUCL, CCL, CLISP, ECL).
** Defining your own Modf expansions
Modf works my defining various expansion constructs. These expansion constructs
can be in the form of:
1. *Rewrite Rules* via =define-modf-rewrite=, a simple macro like facility that
rewrites the place you want to =modf= into something simpler. Think =(cadr
x)= -> =(car (cdr x))=.
2. *Expanders* via =define-modf-expander=, a more general expansion mechanism
where you define a function that is given the place to be modded, the
current value of that place, and the new value it should be modded to.
3. *Modf functions and Methods* via =define-modf-function= and
=define-modf-method=, which you should think of as a way to define =(setf
fn)= like functions for Modf.
In principle, the last construct alone is enough to do anything you want. The
others are included for your convenience and with thoughts of compiler
optimization on the in place expansions performed by expanders.
For expanders and Modf functions/methods, you need to specify which argument
actually holds the data that is being modified. This is given as an extra
argument after the name.
** Known issues
1. Tons of stuff with ABCL. It actually works for most things in ABCL, but I
don't have the patience to get the test suite running.
2. Perhaps issues with order of evaluation. I haven't gone through a thorough
audit of this yet.
** Documentation
Working on it. This is supposed to be a literate program, but the comments in
the source are chicken scratch.
** Author
Zach Kost-Smith
** License
3-Clause BSD. See file COPYING.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The modf system |
Zach Kost-Smith <zachkostsmith@gmail.com>
3 Clause BSD (http://opensource.org/licenses/BSD-3-Clause)
A SETF like macro for functional programming
This library simplifies functional programming by making it easier to make new data structures with specified changes in place.
modf.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The modf.asd file | ||
| • The modf/package.lisp file | ||
| • The modf/utils.lisp file | ||
| • The modf/modf.lisp file | ||
| • The modf/rewrite-rules.lisp file | ||
| • The modf/basic.lisp file | ||
| • The modf/modf-def.lisp file |
Next: The modf/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
modf.asd
modf (system)
Next: The modf/utils․lisp file, Previous: The modf․asd file, Up: Lisp files [Contents][Index]
Next: The modf/modf․lisp file, Previous: The modf/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
modf (system)
utils.lisp
mkstr (function)
Next: The modf/rewrite-rules․lisp file, Previous: The modf/utils․lisp file, Up: Lisp files [Contents][Index]
utils.lisp (file)
modf (system)
modf.lisp
Next: The modf/basic․lisp file, Previous: The modf/modf․lisp file, Up: Lisp files [Contents][Index]
Next: The modf/modf-def․lisp file, Previous: The modf/rewrite-rules․lisp file, Up: Lisp files [Contents][Index]
rewrite-rules.lisp (file)
modf (system)
basic.lisp
Previous: The modf/basic․lisp file, Up: Lisp files [Contents][Index]
basic.lisp (file)
modf (system)
modf-def.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The modf package | ||
| • The modf-def package |
Next: The modf-def package, Previous: Packages, Up: Packages [Contents][Index]
package.lisp (file)
Previous: The modf package, Up: Packages [Contents][Index]
modf-def.lisp (file)
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported macros |
Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Define Modf expansions for class slot accessor and reader methods.
modf-def.lisp (file)
Define a new expander which inverts forms starting with NAME. Your function should return an expansion from EXPR to a form that will build a new object that has NEW-VAL in the place specified by expr. NTH-ARG marks which argument is considered the actual data which will be inverted next.
This macro defines Modf expanders for a class. We can do this given the definition form for the class (much like with DEFINE-MODF-FOR-STRUCT-SLOTS) or the a name of a finalized class.
modf-def.lisp (file)
This macro defines Modf expanders for structure slots when given a structure definition form.
modf-def.lisp (file)
Define a new modf function. It inverts NAME forms by modifying the NTH-ARG term of the arguments of the place form in the MODF macro.
Define a new modf method. It inverts NAME forms by modifying the NTH-ARG term of the arguments of the place form in the MODF macro. This method can specialize on any of ARGS.
Define a new rewrite rule. If a form starting with NAME is encountered, call the defined function to return a form that we can deal with (i.e. one defined via DEFINE-MODF-EXPANDER, DEFINE-MODF-FUNCTION, and DEFINE-MODF-METHOD).
Define a new structure with Modf expansions for slots.
modf-def.lisp (file)
Make a new object (which may use some of the old object) such that PLACE
evaluates to VALUE.
MORE should have the form...
MORE : NIL
| (TEMPORARY-BINDING ANOTHER-MODF-PLACE ANOTHER-VALUE . MORE)
Use it to specify a temporary binding for the new object created which will be used in the subsequence MODF-PLACE NEW-VALUE pairs until the end of the MODF form.
Expand to the defined Modf function. Basically, (MODF-FN SYM) is the functional analog of #’(SETF SYM).
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal functions | ||
| • Internal generic functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
This controls whether we should make educated guesses regarding inverting structure slot readers. For strictly correct behavior, set this to nil.
Holds what argument to try to invert next.
Next: Internal generic functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
basic.lisp (file)
basic.lisp (file)
basic.lisp (file)
basic.lisp (file)
basic.lisp (file)
basic.lisp (file)
basic.lisp (file)
basic.lisp (file)
modf-def.lisp (file)
modf-def.lisp (file)
modf-def.lisp (file)
This is a generic catch as much as you can function. It attempts to identify
class accessor functions, structure accessor functions, and provides late MODF
defined functions (i.e. you used MODF before using DEFINE-MODF-FUNCTION).
All of this functionality is less than ideal efficiency wise, but working over efficiency any day, right? If you want better performance, define all of you functions ahead of time.
MaKe STRing
utils.lisp (file)
modf-def.lisp (file)
modf-def.lisp (file)
Make a symbol name that depends on symbol name and package, but is very unlikely to be chosen by anyone. This is for avoiding collisions for my benefit, not the users, as these symbols belong to the MODF package.
basic.lisp (file)
basic.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
basic.lisp (file)
basic.lisp (file)
basic.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | F L M |
|---|
| Jump to: | F L M |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | A B C D E F G L M R |
|---|
| Jump to: | A B C D E F G L M R |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
S |
|---|
| Jump to: | *
S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | M P S |
|---|
| Index Entry | Section | ||
|---|---|---|---|
| | |||
| M | |||
modf: | The modf system | ||
modf: | The modf package | ||
modf-def: | The modf-def package | ||
| | |||
| P | |||
Package, modf: | The modf package | ||
Package, modf-def: | The modf-def package | ||
| | |||
| S | |||
System, modf: | The modf system | ||
| | |||
| Jump to: | M P S |
|---|