Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the defconfig Reference Manual, version 1.1.3, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:52:27 2021 GMT+0.
| • Introduction | What defconfig 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 |
#+TITLE: DEFCONFIG
*** Status [[https://travis-ci.com/szos/defconfig.svg?branch=main]]
Currently tested against SBCL, CCL, ABCL, ECL, and Allegro CL.
* Purpose
Defconfig is a customization and validation framework for places in CL. Its intended use is with user-exposed variables and accessors, to protect users from setting variables to an invalid value an potentially encountering undefined behavior. It can be used with both dynamic variables and ~setf~-able functions. It coexists alongside ~setf~, and does not replace it - ie you can still use ~setf~ if you want to avoid validating the value.
If you wish to just dive in, ~:import~ the symbols ~#:defconfig~, ~#:setv~, ~#:with-atomic-setv~, ~#:define-defconfig-db~, ~#:get-db~, and ~#:*setv-permissiveness*~ and read their docstrings.
If you encounter something that doesnt work as you think it should, please open an issue here. If you describe the exhibited behavior and the expected behavior, it will be added to the test suite and fixed (hopefully quickly).
* Usage
The basic usage of this system is through the macros ~defconfig~, ~setv~ and ~with-atomic-setv~. The macro ~defconfig~ defines a configuration object which is used to check values against a predicate. The macro ~setv~ uses these configuration objects to validate values before calling setf. An error is signalled if A) the value is invalid, B) the coerced value is invalid (when applicable) or C) the place one is trying to set doesnt have a configuration object. For A and B, restarts are put into place to ignore the invalidity and set regardless, or continue without setting. The macro ~with-atomic-setv~ collects all places set with ~setv~ in its body and if an error is signalled resets all changed values back to their original value held before the ~with-atomic-setv~ form.
* Regarding This Readme
This readme is not a complete explanation of defconfig. Please see =package.lisp= for a list of exported symbols and see the symbol docstrings for a better idea of what it does. Most (exported) symbols are well documented, slots have decent documentation describing their purpose/use, and errors should be grokkable from their ~:report~ functions.
* Basic Tutorial
Lets look at an example where one is defining a user-exposed variable for the background color of an application. Please see =tests/defconfig-tests.lisp= for more examples.
** Defconfig
Here we define a variable called ~*background-color*~ which holds a default value of the color white. It may only hold a color object. If we try to set it to a string, we try to parse a color object from the string. If that fails or we get something other than a string, we return the original value. We do this because the coercer is only ever called on an invalid value, and if we cannot make a color object from it we want to be certain that we return an invalid value. We then tag the configuration object with “color” and “background” such that it can be searched for by those names.
#+BEGIN_SRC lisp
(defpackage :my-app
(:local-nicknames (:dc :defconfig))
(:use :cl))
(in-package :my-app)
(defstruct color r g b)
(defun parse-color-from-string (string)
(make-color :r (parse-integer (subseq string 0 2) :radix 16)
:g (parse-integer (subseq string 2 4) :radix 16)
:b (parse-integer (subseq string 4 6) :radix 16)))
(dc:defconfig *background-color* (make-color :r 256 :g 256 :b 256)
:documentation "the background color for my app"
:typespec 'color
:coercer (lambda (value)
(handler-case (parse-color-from-string value)
(error () value)))
:tags '("color" "background"))
#+END_SRC
** Setv
Now, somewhere in the users =~/.myapp.d/init=, they want to set the background color to black. Lets look at three examples of that:
#+BEGIN_SRC lisp
(dc:setv *background-color* (make-color :r 0 :g 0 :b 0))
(dc:setv *background-color* "000000")
(dc:setv *background-color* "i dont know what this user is thinking!")
#+END_SRC
The first of these works without a hitch; ~setv~ determines that it is a valid value as per the typespec the user provided, and sets ~*background-color*~ to black.
The second of these would fail if we hadnt provided a coercer, but as we did, and it knows how to handle color strings, we generate a color from the color string and ~*background-color*~ gets set to black.
The third of these is also a string, but its impossible to parse a color from it. Assuming ~parse-color-from-string~ errors out on invalid strings, we return ~value~ and signal an error; ~*background-color*~ remains white.
** With-atomic-setv
Lets look at an example of ~with-atomic-setv~. We will define a bounded number variable, and then try setting it while signalling various errors.
#+BEGIN_SRC lisp
(dc:defconfig *bounded-number* 0
:typespec '(integer 0 10)
:coercer (lambda (x)
(if (stringp x)
(handler-case (parse-integer x)
(error () x))
x)))
(defun compute-something-that-signals-an-error ()
(error "we encountered an error, oh no!"))
(dc:with-atomic-setv ()
(dc:setv *bounded-number* 1)
(dc:setv *bounded-number* 50))
(dc:with-atomic-setv ()
(dc:setv *bounded-number* 1)
(compute-something-that-signals-an-error)
(dc:setv *bounded-number* 2))
(dc:with-atomic-setv (:handle-conditions dc:config-error)
(dc:setv *bounded-number* 1)
(compute-something-that-signals-an-error)
(dc:setv *bounded-number* 2))
#+END_SRC
The first of the calls to ~with-atomic-setv~ first sets ~*bounded-number*~ to 1, and then encounters an error when trying to set it to 50. It catches that error and resets ~*bounded-number*~ to 0, the value ~*bounded-number*~ had before the call to ~with-atomic-setv~.
The second of these first sets ~*bounded-number*~ to 1, and then an error is signalled by ~(compute-something-that-signals-an-error)~. It catches this error and resets ~*bounded-number*~ to 0.
The third of these first sets ~*bounded-number*~ to 1, and then an error is signalled that it is not set up to handle; it will only catch errors of type ~config-error~. Whether or not it attempts to set ~*bounded-number*~ to 2 is determined by what handlers and restarts are set up around the error. If there a restart is chosen that doesnt unwind the stack then ~*bounded-number*~ will be set to 2, but if there is a non-local transfer of control to a point outside of ~with-atomic-setv~ then ~*bounded-number*~ will remain set to 1. This is the only way to escape ~with-atomic-setv~ that leaves things in a partially configured state. Lets look at an example of this that would end up with ~*bounded-number*~ being 2:
#+BEGIN_SRC lisp
(defun compute-something-that-signals-an-error ()
(restart-case (error "we encountered an error, oh no!")
(continue () nil)))
(handler-bind ((error
(lambda (c)
(declare (ignore c))
(when (find-restart 'continue)
(invoke-restart 'continue)))))
(dc:with-atomic-setv (:handle-conditions dc:config-error)
(dc:setv *bounded-number* 1)
(compute-something-that-signals-an-error)
(dc:setv *bounded-number* 2)))
#+END_SRC
** Controlling Permissiveness
By setting ~*setv-permissiveness*~ one can control how ~setv~ handles missing configuration objects. It can be set to one of the following values:
- ~:strict~ - Signal all errors as they occur. This is the default behavior
- ~:greedy~ - When unable to find a configuration object in the specified database, search in all databases for a matching configuration object, using the first one encountered.
- ~:permissive~ - When a configuration object isnt found, set the variable to the value.
- ~:greedy+permissive~ - When a configuration object isnt found, search for one as per ~:greedy~. If one still isnt found, set the variable to the value.
* Quirks, Oddities and Limitations
There are a few places in ~defconfig~ that arent naturally intuitive.
** Setv and macros
Setv wont work with macros that expand into something else to be set in the same way setf does. Example:
#+BEGIN_SRC lisp
(defconfig *var* nil)
(defmacro var () '*var*)
(setf (var) 1) ; works
(setv (var) 2) ; tries to find config for the accessor var, not the variable *var*
#+END_SRC
** Psetv
The macro ~psetv~ is a ~setv~ equivalent of ~psetf~. However, while bindings are "preserved" throughout the form, if an error occurs and there is a non-local transfer of control, any places being set after the error will not be set. An example from the test suite:
#+BEGIN_SRC lisp
(defconfig-minimal *a* 'a
:typespec 'symbol)
(defconfig-minimal *b* "b"
:typespec 'string)
(defconfig-minimal *c* 'c
:typespec 'symbol)
(psetv *a* *c*
*b* *a*
*c* *a*)
#+END_SRC
If one enters this in a repl, an error condition will be signalled upon trying to set ~*b*~ to ~'a~, and if one chooses to abort (via ~q~, or ~sly-db-abort~) then ~*c*~ will retain the value ~'c~, and ~*b*~ ~"b"~.
** ~With-atomic-setv~
The star variant of ~with-atomic-setv~ has a quirk in that places get evaluated multiple times if one resets, while both variants evaluate accessors multiple times. Some code to demonstrate:
#+BEGIN_SRC lisp
(with-atomic-setv ()
(setv (accessor *myvar*) 0)
…)
(with-atomic-setv* ()
(setv (accessor *myvar*) 0)
…)
#+END_SRC
Both of these will evaluate ~(accessor *myvar*)~ multiple times depending on whether it gets reset or not.
#+BEGIN_SRC lisp
(with-atomic-setv ()
(setv (accessor (progn (incf *counter*)
*myvar*))
0)
…)
(with-atomic-setv* ()
(setv (accessor (progn (incf *counter*)
*myvar*))
0)
…)
#+END_SRC
In the above example, the first of these will evaluate ~(progn (incf *counter*) *myvar*)~ once and only once, while the second will evaluate ~(progn (incf *counter*) *myvar*)~ once if there is no reset, but twice if there is a reset.
Both version of this macro will evaluate the accessor multiple times. Another way of putting it is to say that ~with-atomic-setv*~ is symmetrical - that is to say, upon resetting every call to ~setv~ will have a matching reset. In contrast, ~with-atomic-setv~ will only reset a place if it hasn't already been reset.
** A Note About Reset-Place
The macro ~reset-place~ (and by extension the function ~reset-computed-place~) could be a little confusing. It takes a place, and resets it to its default value. However if ~previous-value~ is true, then it resets to the previous value instead. Before setting, it checks if the current value is eql to the value to reset to (this can be controlled with ~already-reset-test~) and if it is it isnt reset as it would have no effect. If it isnt, we both reset the place, AND set the ~previous-value~ slot to the (now no longer) current value. thusly, if the default value is a, previous value is b, and current value is c, and we reset to the default value, we will have a default of a, previous of c, and current of a. If we had instead reset to the previous value, we effectively swap the previous and current values.
Furthermore, we cannot reset accessor places.
** Defconfig and CLISP
Many distributions package an older version of CLISP upon which the defconfig testing dependency ~:fiveam~ wont load. CLISP version 2.49.92 and higher is known to work, and can be obtained from the 2.50 branch on gitlab. At the time of writing the master branch is v2.49.93+.
* Macros
** ~Define-variable-config~
*define-variable-config* /place default-value &key validator typespec coercer documentation db tags regen-config => config-info/
The ~define-variable-config~ macro generates a config info object and registers it in a database.
- *Side Effects*
- Causes /config-info/ to be places into /db/
- Any side effects of calling /validator/ on /default-value/, when /validator/ is provided.
- Arguments and Values
- /place/ - a symbol denoting a dynamic variable.
- /default-value/ - the default value for /place/. Must conform to /validator/ or /typespec/ when provided.
- /validator/ - a function of one argument returning true or nil. May not be provided alongside /typespec/.
- /typespec/ - a type specifier denoting valid types for /place/. May not be provided alongside /validator/
- /coercer/ - a function of one argument used to attempt to coerce its argument to a valid value. Will only be called on invalid values.
- /regen-config/ - when true, regenerate the configuration object regarless of its pre-existence
- /db/ - the database to register /config-info/ in.
- /tags/ - a set of tags used when searching for a configuration object
** ~Define-accessor-config~
*define-accessor-config* /place &key validator typespec coercer documentation db tags regen-config => config-info/
The ~define-accessor-config~ macro generates a config info object and registers it in a database.
- *Side Effects*
- Causes /config-info/ to be places into /db/
- Arguments and Values
- /place/ - a symbol denoting a dynamic variable.
- /validator/ - a function of one argument returning true or nil. May not be provided alongside /typespec/.
- /typespec/ - a type specifier denoting valid types for /place/. May not be provided alongside /validator/
- /coercer/ - a function of one argument used to attempt to coerce its argument to a valid value. Will only be called on invalid values.
- /regen-config/ - when true, regenerate the configuration object regarless of its pre-existence
- /db/ - the database to register /config-info/ in.
- /tags/ - a set of tags used when searching for a configuration object
** ~Defconfig~
*defconfig* /place &rest args => config-info/
The ~defconfig~ macro wraps around the ~define-*-config~ macros. When /place/ is a symbol, it expands into a call to ~define-variable-config~, as well as a call to either ~defparameter~ or ~defvar~. When /place/ is a symbol one additional key argument is accepted: ~:reinitialize~. When true, a ~defparameter~ form is generated.
- *Side Effects*:
- Causes /config-info/ to be placed into /db/
- May modify /place/
- May cause /place/ to be defined as a dynamic variable
- Any side effects of running /validator/
** ~Setv~
*setv* {/place/ /value/}* /:db/ => /result/
The ~setv~ macro expands into multiple calls to ~%%setv~, which validates a value before setting the place to it. It functions the same as ~setf~, but accepts the keyword ~:db~ to specify a database other than the default one provided by ~defconfig~. Returns the final value.
- *Side Effects*:
- Any side effects of evaluating a value. Place/value pairs are evaluated sequentially. If a value is not valid, no further values will be processed.
- Causes /place/ to be set to /value/
** ~Psetv~
*psetv* {/place/ /value/}* /:db/ => /result/
The ~psetv~ macro expands into multiple calls to ~%%setv~, the same as ~setv~, but differs in that all values are computed before setting, giving the illusion of setting in parallel (similar to ~psetf~).
- Side Effects:
- Any side effects of evaluating a value. Place/value pairs are evaluated sequentially. If a value is not valid, no further values will be processed.
- Causes /place/ to be set to /value/
** ~With-atomic-setv/*~
*with-atomic-setv* (/errorp/ /handle-conditions/ /db/) /form*/ => /results/
There are two versions of this macro: ~with-atomic-setv~ and ~with-atomic-setv*~. The former tracks places and values purely at runtime, while the latter tracks places at macroexpansion time and values at runtime.
The ~with-atomic-setv~ macro resets any places set using ~setv~ to the value it held before the call to ~with-atomic-setv~, when a condition is encountered. One can specify whether to re-signal the condition or not with ~:errorp~. If ~:errorp~ is nil a warning will be issued on encountering a handled condition and the condition will be returned. Re-signalled conditions are wrapped in the condition ~setv-wrapped-error~. One can specify which conditions to handle with ~:handle-conditions~, which accepts an (unquoted) type specifier. One can handle no conditions by passing ~(or)~, though that defeats the purpose of ~with-atomic-setv~. The default database to use for all calls to ~setv~ occuring within /form*/ can be controleld with ~:db~. It defaults to ~defconfig:*default-db*~.
An example:
#+BEGIN_SRC lisp
(with-atomic-setv (:errorp nil)
(error "hello")
"return string")
WARNING: WITH-ATOMIC-SETV encountered the error
#
and reset.
=> #
(with-atomic-setv (:errorp nil :handle-conditions config-error)
(error "hello")
"return string")
drops into the debugger
(with-atomic-setv (:errorp nil)
(warn "hello")
"return string")
WARNING: hello
=> "return string"
(with-atomic-setv (:errorp nil :handle-conditions (or error warning))
(warn "hello")
"return string")
WARNING: hello
=> #
#+END_SRC
** ~Define-defconfig-db~
*define-defconfig-db* /var/ /key/ /&key/ /parameter/ /if-exists/ /doc/
The ~define-defconfig-db~ macro defines a new dynamic variable containing a defconfig database and stores that database internally such that it can be referenced via /key/. All databases used with defconfig should be created using this macro. The key argument /parameter/ defaults to true, and controls whether the database is defined using ~defvar~ or ~defparameter~. Variable documentation is added via the /doc/ key argument. When a key already denotes a defconfig database, an error will be signalled. This can be handled by setting /if-exists/ to ~:use~ or ~redefine~, to either use the existing database or redefine the database respectively. When /if-exists/ is nil the error will propogate up to the user.
* Help Wanted
Currently, Travis is being used for CI. However, these builds sometimes fail for unknown reasons unrelated to the defconfig test suite. It would be nice to be able to detect these failures and re-run the job upon encountering them.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The defconfig system |
szos at posteo dot net
GPLv3
A configuration system for user exposed variables
1.1.3
defconfig.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The defconfig/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
defconfig.asd
defconfig (system)
Next: The defconfig/macros․lisp file, Previous: The defconfig․asd file, Up: Lisp files [Contents][Index]
Next: The defconfig/database․lisp file, Previous: The defconfig/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
defconfig (system)
macros.lisp
atypecase (macro)
Next: The defconfig/classes․lisp file, Previous: The defconfig/macros․lisp file, Up: Lisp files [Contents][Index]
macros.lisp (file)
defconfig (system)
database.lisp
Next: The defconfig/conditions․lisp file, Previous: The defconfig/database․lisp file, Up: Lisp files [Contents][Index]
database.lisp (file)
defconfig (system)
classes.lisp
Next: The defconfig/defconfig․lisp file, Previous: The defconfig/classes․lisp file, Up: Lisp files [Contents][Index]
classes.lisp (file)
defconfig (system)
conditions.lisp
Next: The defconfig/setv․lisp file, Previous: The defconfig/conditions․lisp file, Up: Lisp files [Contents][Index]
conditions.lisp (file)
defconfig (system)
defconfig.lisp
Next: The defconfig/access․lisp file, Previous: The defconfig/defconfig․lisp file, Up: Lisp files [Contents][Index]
defconfig.lisp (file)
defconfig (system)
setv.lisp
Previous: The defconfig/setv․lisp file, Up: Lisp files [Contents][Index]
setv.lisp (file)
defconfig (system)
access.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The defconfig package |
package.lisp (file)
common-lisp
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 special variables | ||
| • Exported macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported conditions |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Determines how setv will act when no config-info object is
found. :STRICT means to error out. :GREEDY means to search through all registered
databases for a config-info object and use the first one that is found, or if none
is found error out. :PERMISSIVE means to setf when a config-info object isnt
found. :GREEDY+PERMISSIVE means to search through all registered databases and
use the first object found, but if one isnt found to setf regardless.
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Defconfig defines a config-info object and potentially a dynamic variable.
PLACE may be either a symbol or a list of length 1. If PLACE is a list, defconfig
functions as a wrapper around define-accessor-config. If it is a symbol,
defconfig defines a variable config as well as a dynamic variable. Additionally,
if the first element of ARGS is a keyword and the second element of ARGS is not
a keyword, the default value will be the value of PLACE.
The following keys are acceptable in ARGS: VALIDATOR, TYPESPEC, COERCER,
DOCUMENTATION, DB, TAGS, and REGEN-CONFIG. REINITIALIZE is also acceptable if
PLACE is a symbol.
VALIDATOR and TYPESPEC may not coexist in a single defconfig call. VALIDATOR is
for providing a function to validate values. It must take a single value, the
value to validate. TYPESPEC takes a type specification and generates a
validation function from it.
If provided, COERCER must be a function taking a single argument: the value to
coerce. It is called iff an invalid value is passed to setv, and it is called on
the invalid value in an attempt to generate a valid one. The return value of
COERCER is checked against the VALIDATOR (or the function generated with
TYPESPEC) and if it is valid it is used in place of the original value.
DOCUMENTATION is the documentation of PLACE and is used in the
defvar/defparameter form when PLACE is a symbol and is placed in the config-info
object regardless of whether PLACE is a symbol or a list.
DB is the database to place the generated config-info object into, and defaults
to *default-db*. Defconfig does not check if DB is in the plist of databases
before placing the config-info object into DB. It is assumed that if a DB has
been removed from the database plist the user has a good understanding of what
they are doing and is managing the database themselves. (databases must be
manually removed from the plist).
TAGS are strings that can be used to search for a config-info object. The search functionality is currently only partially implemented.
defconfig.lisp (file)
Define a minimal config, with no value tracking.
defconfig.lisp (file)
Define an accessor config object and place it in DB with the key ACCESSOR
defconfig.lisp (file)
define a dynamic variable name VAR to be a defconfig database accessible by passing KEY to the function get-db. If PARAMETER is true, create this var with a defparameter form, otherwise use defvar. DOC is the documentation to pass to the def(parameter|var) form.
database.lisp (file)
define a minimal config object for PLACE and in DB.
defconfig.lisp (file)
Define a variable config object and place it in DB with the key PLACE.
defconfig.lisp (file)
The setv equivalent of psetf - set all places in parallel
looks up PLACE in DB and set it to its default or previous value.
access.lisp (file)
Setv must get an even number of ARGS - every place must have a value. Setv can also take the key argument :db, to specify which database to look up config objects in.
This macro, upon encountering an error, resets all places encountered within calls to setv to be reset to the value they held before the call to with-atomic-setv. Which errors to reset upon can be controlled with HANDLE-CONDITIONS. If it is nil, it defaults to ’error. If a handled condition is encountered, it will be wrapped in SETV-WRAPPED-ERROR, unless RE-ERROR is nil, in which case a warning will be generated and the condition will be returned.
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
delete the database associated with KEY. if MAKUNBOUND is T, then unbind the symbol holding the database associated with KEY
database.lisp (file)
get the database associated with KEY
database.lisp (file)
get the variable holding the database associated with KEY
database.lisp (file)
list all defconfig databases
database.lisp (file)
Returns a list of all configurable objects matching TERM. If DATABASE-KEY is provided, search only in that database.
access.lisp (file)
Push TAG onto the list of tags for the config-info object associated with PLACE in DB.
access.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
use to set the previous value of PLACE to the default value. This is useful for places that may hold a large object which you want gc’d
access.lisp (file)
The function by which invalid datum will attempt to be coerced
classes.lisp (file)
the database that the config info object is housed in.
classes.lisp (file)
The default value of this config-info object
classes.lisp (file)
The docstring for the place being governed. if a variable it is the same as the variables docstring
classes.lisp (file)
The formal name by which this config-info object can be searched for
classes.lisp (file)
The place which this config info governs.
classes.lisp (file)
The predicate against which valid values are checked
classes.lisp (file)
holds the value previously assigned to the config-info object. initially the same as default-value
classes.lisp (file)
Tags which can be used for finding a config-info object
classes.lisp (file)
When a typespec is provided instead of a validator, this slot will hold it
classes.lisp (file)
An explanation of the valid values and predicate function
classes.lisp (file)
Reset PLACE to its default value, unless PREVIOUS-VALUE is true, then reset to the previous value. TEST is used to check if a reset is needed.
access.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
This condition is the root condition for all defconfig conditions. If one wants to catch all defconfig conditions (such as with handler-case) then config-error should be used.
conditions.lisp (file)
error (condition)
This condition indicates KEY already denotes a database in *db-plist*
conditions.lisp (file)
config-error (condition)
database-already-exists-error-key (method)
:key
database-already-exists-error-key (generic function)
This condition indicates that coercion was attempted on VALUE, producing COERCED-VALUE, and that COERCED-VALUE is invalid for PLACE-FORM
conditions.lisp (file)
invalid-datum-error (condition)
invalid-coerced-datum-error-value (method)
:coerced-value
(quote nil)
invalid-coerced-datum-error-value (generic function)
This condition indicates that VALUE is invalid for PLACE-FORM
conditions.lisp (file)
config-error (condition)
invalid-coerced-datum-error (condition)
:place
(quote nil)
invalid-datum-error-place (generic function)
:value
(quote nil)
invalid-datum-error-value (generic function)
:config-object
(quote nil)
invalid-datum-error-config-object (generic function)
This condition indicates that the default-value slot of OBJECT is unbound. This will only be signalled when trying to reset a place to its default value.
conditions.lisp (file)
untrackable-place-error (condition)
This condition indicates that PLACE-FORM does not denote a config-info object in DATABASE
conditions.lisp (file)
config-error (condition)
:place
(quote nil)
no-config-found-error-place (generic function)
:db
(quote nil)
no-config-found-error-db (generic function)
This condition indicates that a reset was attempted on an accessor place.
conditions.lisp (file)
untrackable-place-error (condition)
This condition is only ever signalled from within WITH-ATOMIC-SETV, and indicates that an error was caught which caused WITH-ATOMIC-SETV to reset all places found within its body. It has one slot, CONDITION, which contains the condition that was caught.
conditions.lisp (file)
config-error (condition)
:error
setv-wrapped-error-condition (generic function)
(setf setv-wrapped-error-condition) (generic function)
conditions.lisp (file)
config-error (condition)
:object
untrackable-place-error-object (generic function)
:place
untrackable-place-error-place (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal macros | ||
| • Internal functions | ||
| • Internal generic functions | ||
| • Internal conditions | ||
| • Internal classes | ||
| • Internal types |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
A plist holding all databases for defconfig
database.lisp (file)
The default database for defconfig
database.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
generates a set of calls to %setv-with-reset.
this macro resets all encountered places within a call to with-atomic-setv*.
Wrap setv in a handler to catch all errors, which will reset all encountered places, after which it returns the condition from the named block.
This macro utilizes compiler-let to allow rollbacks of accessor stuff.
macros.lisp (file)
defconfig.lisp (file)
defconfig.lisp (file)
defconfig.lisp (file)
separates keys from list, storing the remainder in VAR, and making each key a variable via destructuring-bind.
this version of setv saves the original value of the places being set, and resets all to their original value if an error is encountered. the error is then resignalled. It is generally advisable to use WITH-ATOMIC-SETV instead.
access.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
access.lisp (file)
check VALUE against CONFIG-INFO-OBJECTs predicate. return VALUE if it passes. If ERRORP is true error if VALUE doesnt pass. If ERRORP is nil and VALUE doesnt pass, return INVALID-SYMBOL. Restarts are put in place to provide a value or set regardless.
return setf symbol if we want the caller to setf place. setf-symbol only needs to be provided if were calling this in a setv expansion.
add a database to *db-plist* in the correct format of (KEY (VARNAME value)). VARNAME is the quoted variable referencing the database, while value is the symbol-value of VARNAME. for internal use only
database.lisp (file)
takes a term, as well as a namespace and a database. the :db keyarg should be a database as returned by make-config-database. the :namespace keyarg should be one of :both :accessor or :variable. Note that the namespace keyarg isnt used if term is a symbol. Term should be either a string, a list of strings, a symbol, or a list of symbols representing an accessor and a place.
access.lisp (file)
access.lisp (file)
return t/nil if KEY denotes a pre-existing db
database.lisp (file)
Check that KEY is a keyword and doesnt already denotes a database in *db-plist*. If it does signal an error within the context of a use-value restart to allow the user to provide a new value to use instead of KEY
database.lisp (file)
database.lisp (file)
classes.lisp (file)
classes.lisp (file)
classes.lisp (file)
used internally by defconfig to wrap around getf - think of it as currying getf with *db-plist* as the place
database.lisp (file)
access.lisp (file)
Return a cons of two hash tables
database.lisp (file)
access.lisp (file)
returns two values - accumulated non-keys and keys
classes.lisp (file)
Next: Internal conditions, Previous: Internal functions, Up: Internal definitions [Contents][Index]
holds the value previously assigned to the config-info object. initially the same as default-value
classes.lisp (file)
Tags which can be used for finding a config-info object
classes.lisp (file)
conditions.lisp (file)
conditions.lisp (file)
conditions.lisp (file)
conditions.lisp (file)
conditions.lisp (file)
conditions.lisp (file)
conditions.lisp (file)
conditions.lisp (file)
conditions.lisp (file)
conditions.lisp (file)
Next: Internal classes, Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
conditions.lisp (file)
config-error (condition)
Next: Internal types, Previous: Internal conditions, Up: Internal definitions [Contents][Index]
classes.lisp (file)
config-info (class)
classes.lisp (file)
classes.lisp (file)
standard-object (class)
minimal-config-info (class)
the database that the config info object is housed in.
(or symbol cons)
:db
config-info-db (generic function)
The place which this config info governs.
symbol
:place
config-info-place (generic function)
classes.lisp (file)
standard-object (class)
minimal-config-info (class)
The predicate against which valid values are checked
(function (*) boolean)
:predicate
(function identity)
config-info-predicate (generic function)
The function by which invalid datum will attempt to be coerced
(or function null)
:coercer
config-info-coercer (generic function)
classes.lisp (file)
standard-object (class)
accessor-config-info (class)
The formal name by which this config-info object can be searched for
:name
"unnamed config-info object"
config-info-name (generic function)
Tags which can be used for finding a config-info object
:tags
(quote nil)
(setf config-info-tag-list) (generic function)
The docstring for the place being governed. if a variable it is the same as the variables docstring
(or string null)
:documentation
config-info-documentation (generic function)
An explanation of the valid values and predicate function
:valid-values
config-info-valid-values-description (generic function)
When a typespec is provided instead of a validator, this slot will hold it
config-info-typespec (generic function)
classes.lisp (file)
standard-object (class)
config-info (class)
The default value of this config-info object
:default
config-info-default-value (generic function)
holds the value previously assigned to the config-info object. initially the same as default-value
:previous
(setf config-info-prev-value) (generic function)
classes.lisp (file)
accessor-config-info (class)
Previous: Internal classes, Up: Internal definitions [Contents][Index]
database.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: | D F L |
|---|
| Jump to: | D F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | %
(
A C D F G I L M N P R S T U W |
|---|
| Jump to: | %
(
A C D F G I L M N P R S T U W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
C D K N O P S T V |
|---|
| Jump to: | *
C D K N O P S T V |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | A C D I M N P S T U W |
|---|
| Jump to: | A C D I M N P S T U W |
|---|