This is the ubiquitous Reference Manual, version 2.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 07:59:08 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
ubiquitousA library providing a universal application configuration mechanism.
Yukari Hafner <shinmera@tymoon.eu>
Yukari Hafner <shinmera@tymoon.eu>
zlib
2.0.0
package.lisp (file).
pathname.lisp (file).
accessor.lisp (file).
metadata.lisp (file).
storage.lisp (file).
config.lisp (file).
documentation.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
ubiquitous/ubiquitous.asdubiquitous/package.lispubiquitous/pathname.lispubiquitous/accessor.lispubiquitous/metadata.lispubiquitous/storage.lispubiquitous/config.lispubiquitous/documentation.lispubiquitous/pathname.lisppackage.lisp (file).
ubiquitous (system).
config-directory (function).
config-pathname (function).
designator-pathname (generic function).
package-directory (generic function).
getenv (function).
parse-dos-namestring (function).
parse-native-namestring (function).
parse-unix-namestring (function).
split-package-name (function).
ubiquitous/accessor.lisppathname.lisp (file).
ubiquitous (system).
augment (generic function).
field (generic function).
(setf field) (generic function).
remfield (generic function).
*nothing* (special variable).
ubiquitous/metadata.lispaccessor.lisp (file).
ubiquitous (system).
*metadata-prefix* (special variable).
*metadata-version* (special variable).
bad-configuration-package (condition).
bad-metadata-header (condition).
bad-package-name (reader method).
find-metadata-package (function).
generate-metadata (function).
header (reader method).
maybe-read-metadata (function).
metadata-condition (condition).
print-metadata (function).
process-metadata (function).
unknown-version (condition).
version (reader method).
with-processed-metadata (macro).
check-metadata (function).
prefix-p (function).
ubiquitous/storage.lispmetadata.lisp (file).
ubiquitous (system).
*storage* (special variable).
*storage-pathname* (special variable).
*storage-type* (special variable).
define-ubiquitous-reader (macro).
define-ubiquitous-writer (macro).
destroy (generic function).
file (reader method).
(setf file) (writer method).
lazy-loader (function).
no-storage-file (condition).
offload (generic function).
read-storage (generic function).
reader-type (reader method).
restore (generic function).
unknown-reader-type (condition).
with-local-storage (macro).
with-storage (macro).
write-storage (generic function).
*ubiquitous-char* (special variable).
*ubiquitous-print-table* (special variable).
*ubiquitous-read-table* (special variable).
*ubiquitous-readers* (special variable).
class-slots (function).
slot-definition-name (function).
ubiquitous-reader (function).
ubiquitous-writer (function).
ubiquitous/config.lispstorage.lisp (file).
ubiquitous (system).
*changed* (special variable).
*commit* (special variable).
call-with-transaction (generic function).
defaulted-value (generic function).
remvalue (generic function).
value (generic function).
(setf value) (generic function).
with-transaction (macro).
ubiquitous/documentation.lispconfig.lisp (file).
ubiquitous (system).
setdocs (macro).
Packages are listed by definition order.
ubiquitousorg.shirakumo.ubiquitous
common-lisp.
*changed* (special variable).
*commit* (special variable).
*metadata-prefix* (special variable).
*metadata-version* (special variable).
*storage* (special variable).
*storage-pathname* (special variable).
*storage-type* (special variable).
augment (generic function).
bad-configuration-package (condition).
bad-metadata-header (condition).
bad-package-name (generic reader).
call-with-transaction (generic function).
config-directory (function).
config-pathname (function).
defaulted-value (generic function).
define-ubiquitous-reader (macro).
define-ubiquitous-writer (macro).
designator-pathname (generic function).
destroy (generic function).
field (generic function).
(setf field) (generic function).
file (generic reader).
(setf file) (generic writer).
find-metadata-package (function).
generate-metadata (function).
header (generic reader).
lazy-loader (function).
maybe-read-metadata (function).
metadata-condition (condition).
no-storage-file (condition).
offload (generic function).
package-directory (generic function).
print-metadata (function).
process-metadata (function).
read-storage (generic function).
reader-type (generic reader).
remfield (generic function).
remvalue (generic function).
restore (generic function).
unknown-reader-type (condition).
unknown-version (condition).
value (generic function).
(setf value) (generic function).
version (generic reader).
with-local-storage (macro).
with-processed-metadata (macro).
with-storage (macro).
with-transaction (macro).
write-storage (generic function).
*nothing* (special variable).
*ubiquitous-char* (special variable).
*ubiquitous-print-table* (special variable).
*ubiquitous-read-table* (special variable).
*ubiquitous-readers* (special variable).
check-metadata (function).
class-slots (function).
getenv (function).
parse-dos-namestring (function).
parse-native-namestring (function).
parse-unix-namestring (function).
prefix-p (function).
setdocs (macro).
slot-definition-name (function).
split-package-name (function).
ubiquitous-reader (function).
ubiquitous-writer (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
When non-NIL it means a change has occurred and the config should be offloaded.
When non-NIL, an OFFLOAD is performed after a call to (SETF VALUE) or REMVALUE.
The prefix that is used to recognise the metadata header.
The current version of the configuration metadata.
Should be a float.
Special variable containing the current root storage object. Defaults to an EQUAL hash-table.
The pathname for the file where the current *STORAGE* is stored.
Defaults to (DESIGNATOR-PATHNAME :GLOBAL *STORAGE-TYPE*).
See DESIGNATOR-PATHNAME
See *STORAGE-TYPE*
An indicator for the type of storage format to use.
Defaults to :LISP
Only used as a discerning argument to READ/WRITE-STORAGE.
Define a new function that produces an object of TYPE by parsing the read FORM.
Define a new function that produces a list of objects to be written to reproduce OBJECT of TYPE.
Useful for completely encapsulating the storage in a local block.
Unlike WITH-STORAGE, this also binds the *STORAGE-TYPE* and
*STORAGE-PATHNAME*. If TRANSACTION is non-NIL, WITH-TRANSACTION is
used, and otherwise a simple LET*. STORAGE defaults to the LAZY-LOADER
function, meaning that if the storage is never accessed, it is never
loaded to begin with. This, along with WITH-TRANSACTION can be a
good optimisation to avoid unnecessary disk access.
See *STORAGE*
See *STORAGE-TYPE*
See *STORAGE-PATHNAME*
See WITH-TRANSACTION
See LAZY-LOADER
Wraps the body in an environment where metadata can be safely applied and processes the given metadata within.
At the moment, this simply binds *PACKAGE* to ensure the package indicated
by the metadata can be applied without influencing the surrounding environment.
See PROCESS-METADATA
Binds *STORAGE* to the given STORAGE object, ensuring a local configuration.
Executes BODY within a transaction.
See CALL-WITH-TRANSACTION
Returns a hopefully suitable directory for ubiquitous configuration files.
On Windows this is (USER-HOMEDIR-PATHNAME)/AppData/Local/common-lisp/ubiquitous On other systems (USER-HOMEDIR-PATHNAME)/.config/common-lisp/ubiquitous
Returns a pathname with the proper directory and type set.
See CONFIG-DIRECTORY
Attempt to find a package of the given name for metadata package resolution.
This is like FIND-PACKAGE, except that it signals an error of type
BAD-CONFIGURATION-PACKAGE if no package could be found, and establishes
the USE-VALUE and CONTINUE restarts to recover from the error.
USE-VALUE lets you pass a package designator to use in place. Note that
if you do not pass a PACKAGE object, it will re-test the designator the
same way.
CONTINUE will instead use the current *PACKAGE*.
Note that using an alternate package may lead to symbols with the wrong
home package in the processed configuration.
See BAD-CONFIGURATION-PACKAGE
Generates valid metadata for the current environment.
A function that is to be used as a direct *STORAGE* value to delay the restoring.
When called, the function will call RESTORE and then delegate the given
action to the proper function (FIELD, (SETF FIELD), REMFIELD) using the
*STORAGE* as object.
See *STORAGE*
See FIELD
See REMFIELD
See WITH-LOCAL-STORAGE
Attempts to read a metadata line from the stream.
If the data at the current stream starts with *METADATA-PREFIX*, the line is
consumed and read. The read metadata structure is returned. If reading fails,
an error of type BAD-METADATA-HEADER is signalled.
See *METADATA-PREFIX*
See BAD-METADATA-HEADER
Writes a metadata header to the stream.
Writes a valid metadata header line to the stream, with the METADATA as the
header contents. The header will start with *METADATA-PREFIX* and will only
consume a single line.
See *METADATA-PREFIX*
See GENERATE-METADATA
Processes the metadata and applies its effects.
This may signal conditions if the metadata is malformed, or the current environment is not agreeable. Two restarts are established to recover:
USE-VALUE allows you to supply alternate metadata. The metadata is then
processed in place of the original.
CONTINUE will simply ignore the metadata and return successfully.
See CHECK-METADATA
See BAD-METADATA-HEADER
See BAD-CONFIGURATION-PACKAGE
See UNKNOWN-VERSION
Attempts to augment OBJECT on FIELD to be able to host a SECONDARY place.
This is done by (SETF FIELD) a hash-table on the given OBJECT and FIELD. The
type of SECONDARY decides the hash-table test to use:
SYMBOL, INTEGER, CHARACTER — EQL
STRING, BIT-VECTOR, PATHNAME — EQUAL
ARRAY, STRUCTURE-OBJECT, HASH-TABLE — EQUALP
See FIELD
hash-table)) ¶structure-object)) ¶array)) ¶pathname)) ¶bit-vector)) ¶string)) ¶character)) ¶integer)) ¶symbol)) ¶Returns the bad package name that the condition captured.
See BAD-CONFIGURATION-PACKAGE
bad-configuration-package)) ¶Calls FUNCTION with *COMMIT* set to NIL and offloads if necessary upon exit.
OFFLOAD is only called if *CHANGED* is non-NIL. Otherwise no change is assumed to
have taken place and the offload is prevented to avoid unnecessary writing.
The keyword parameters replace the bindings for *STORAGE* *STORAGE-TYPE* and
*STORAGE-PATHNAME* respectively.
See *COMMIT*
See *CHANGED*
See OFFLOAD
Same as VALUE, but automatically returns and sets DEFAULT if the field cannot be found.
See VALUE
Attempts to automatically find the proper pathname for the given DESIGNATOR and TYPE.
If DESIGNATOR is..
An absolute PATHNAME:
The pathname is used as-is.
A relative PATHNAME:
The pathname is merged with that of CONFIG-DIRECTORY.
A STRING:
The string is turned into a pathname by PATHNAME and merged with CONFIG-PATHNAME.
A SYMBOL:
A pathname with the symbol’s symbol-name as pathname-name, the CONFIG-PATHNAME’s
pathname-type, and the defaults from PACKAGE-PATHNAME is constructed.
Examples:
(designator-pathname #p"/a" :lisp) — #p"/a"
(designator-pathname #p"a" :lisp) — #p"~/.config/common-lisp/ubiquitous/a"
(designator-pathname "a" :lisp) — #p"~/.config/common-lisp/ubiquitous/a.conf.lisp"
(designator-pathname :foo :lisp) — #p"~/.config/common-lisp/ubiquitous/foo.conf.lisp"
(designator-pathname #:foo :lisp) — #p"~/.config/common-lisp/ubiquitous/foo.conf.lisp"
(designator-pathname ’cl:find :lisp) — ERROR
(designator-pathname ’foo:bar :lisp) — #p"~/.config/common-lisp/ubiquitous/foo/bar.conf.lisp"
See PACKAGE-PATHNAME
See CONFIG-DIRECTORY
Destroys *STORAGE* by deleting its file and restoring it to an empty hash table.
The file used to destroy the storage is calculated by passing
DESIGNATOR (defaulting to *STORAGE-PATHNAME*) and TYPE (defaulting to
*STORAGE-TYPE*) to DESIGNATOR-PATHNAME.
This sets *STORAGE*, *STORAGE-TYPE*, *STORAGE-PATHNAME*, and *CHANGED*.
See *STORAGE*
See *STORAGE-TYPE*
See *STORAGE-PATHNAME*
See *CHANGED*
See DESIGNATOR-PATHNAME
Access FIELD on OBJECT if possible. Returns DEFAULT if FIELD is not present. The secondary return value is a boolean depicting whether the field could be found.
This is SETF-able. However, while some objects and field combinations may be used
to read a field, an equivalent SETF method must not necessarily exist.
In the case where the object is a function, the function is called as follows:
(field func field default) => (funcall func :get field default)
(setf (field func field) value) => (funcall func :set field value)
Note that if there is no matching method to look up the requested field, an error is signalled.
function) field &optional default) ¶null) field &optional default) ¶symbol) (field symbol) &optional default) ¶standard-object) (field symbol) &optional default) ¶list) (field string) &optional default) ¶list) (field symbol) &optional default) ¶list) (field integer) &optional default) ¶vector) (field integer) &optional default) ¶hash-table) field &optional default) ¶function) field) ¶symbol) (field symbol)) ¶standard-object) (field symbol)) ¶list) (field string)) ¶list) (field symbol)) ¶list) (field integer)) ¶vector) (field integer)) ¶hash-table) field) ¶To be used on NO-STORAGE-FILE, returns the pathname to the file that could not be found.
no-storage-file)) ¶file.
no-storage-file)) ¶file.
Returns the header that is malformed.
See BAD-METADATA-HEADER
bad-metadata-header)) ¶Offloads *STORAGE* by writing it to file.
The file used to read the storage is calculated by passing
DESIGNATOR (defaulting to *STORAGE-PATHNAME*) and TYPE (defaulting to
*STORAGE-TYPE*) to DESIGNATOR-PATHNAME.
The file is first written to a temporary one and then renamed to the
actual file to avoid potential errors or interruptions that would result
in a garbled configuration file.
This sets *STORAGE-TYPE*, *STORAGE-PATHNAME*, and *CHANGED*.
During OFFLOAD, the following restarts are active:
ABORT Aborts and does not set any of the usual variables.
See *STORAGE*
See *STORAGE-TYPE*
See *STORAGE-PATHNAME*
See *CHANGED*
See DESIGNATOR-PATHNAME
See WRITE-STORAGE
Returns the directory for config files suitable for this package.
By default:
For the CL package, an error is signalled.
For the KEYWORD and NIL packages, the CONFIG-DIRECTORY is returned.
Otherwise, a subdirectory within the CONFIG-DIRECTORY is returned according to the
package’s name.
The user may add methods to this function to customise the behaviour of their own
packages.
See CONFIG-DIRECTORY
package)) ¶(eql #<package "keyword">))) ¶null)) ¶(eql #<package "common-lisp">))) ¶string)) ¶symbol)) ¶Reads a storage object from STREAM, which must be stored in a format suitable for TYPE. Returns the read storage object.
(eql :lisp)) stream) ¶Returns the type that was attempted to be read.
See UNKNOWN-READER-TYPE
unknown-reader-type)) ¶type.
Removes FIELD from OBJECT if possible.
The secondary return value is a boolean depicting whether the field was removed.
In the case where the object is a function, the function is called as follows:
(remfield func field) => (funcall func :remove field)
Note that if there is no matching method to look up the requested field, an error is signalled.
function) field) ¶symbol) (field symbol)) ¶list) (field string)) ¶list) (field symbol)) ¶list) (field integer)) ¶hash-table) field) ¶Removes the value denoted by the PATH.
The secondary return value is a boolean depicting whether the field could be found.
First traverses *STORAGE* until the last field in PATH by FIELD, then uses REMFIELD
on the last remaining field. If no PATH is given, the *STORAGE* is reset to an empty
hash-table.
See FIELD
See REMFIELD
Restores *STORAGE* by reading it from file if possible and returns it.
The file used to read the storage is calculated by passing
DESIGNATOR (defaulting to *STORAGE-PATHNAME*) and TYPE (defaulting to
*STORAGE-TYPE*) to DESIGNATOR-PATHNAME. If it exists, a stream is opened
and subsequently passed to READ-STORAGE. The result thereof is used as
the new storage object. If it does not exist, a warning of type
NO-STORAGE-FILE is signalled and a new EQUAL hash-table is used for the
storage object (unless a restart is invoked of course).
This sets *STORAGE*, *STORAGE-TYPE*, *STORAGE-PATHNAME*, and *CHANGED*.
During OFFLOAD, the following restarts are active:
USE-NEW-STORAGE Takes one argument to use as the new storage instead.
ABORT Aborts and does not set any of the usual variables.
See *STORAGE*
See *STORAGE-TYPE*
See *STORAGE-PATHNAME*
See *CHANGED*
See NO-STORAGE-FILE
See DESIGNATOR-PATHNAME
See READ-STORAGE
Traverses *STORAGE* by the fields in PATH and returns the value if it can be found. The secondary return value is a boolean depicting whether the field could be found.
This is SETF-able. If a PATH is set that is made up of fields that do not exist yet,
then these fields are automatically created as necessary (if possible) by usage of
AUGMENT. Setting with no PATH given sets the value of *STORAGE*. After setting a value,
OFFLOAD is called, unless *COMMIT* is NIL
See FIELD
See AUGMENT
See OFFLOAD
See *COMMIT*
Returns the version captured by the condition.
See UNKNOWN-VERSION
unknown-version)) ¶Writes the STORAGE object to STREAM in a format suitable for TYPE. Returns the written STORAGE object.
Error signalled when the metadata header refers to an unknown package.
See BAD-PACKAGE-NAME
See METADATA-CONDITION
error.
metadata-condition.
common-lisp.
(quote (error "package-name required."))
:package-name
This slot is read-only.
Error signalled when the metadata header is malformed.
See HEADER
See METADATA-CONDITION
error.
metadata-condition.
Superclass for conditions related to configuration metadata.
condition.
Condition signalled when the storage FILE to be RESTOREd does not exist.
This does not usually denote a problem, but can be useful to know about
if you want perform certain actions on what is probably a first-time
launch.
See FILE
See RESTORE
Error signalled if an unknown structure type is encountered in the config.
See READER-TYPE
See UBIQUITOUS-READER
error.
common-lisp.
(quote (error "reader-type required."))
:reader-type
This slot is read-only.
Warning signalled when the metadata header contains an unknown version number.
See VERSION
See METADATA-CONDITION
metadata-condition.
warning.
Variable with a value used to represent an inexistent value.
A string of two characters denoting the start and end of a special construct.
The pprint-dispatch-table used to write storage objects to file.
The readtable used to read storage objects from file.
A hash table of functions invoked upon reading a special construct.
Checks whether the read metadata structure is valid.
Namely an error of type BAD-METADATA-HEADER is signalled if the metadata
is not a list, and is not a proper plist.
See BAD-METADATA-HEADER
Returns T if the PREFIX is a prefix of STRING.
Reader function invoked when encountering the first character of *UBIQUITOUS-CHAR*.
This dispatches to the proper reader for the structure’s type. If an
unknown type is encountered, an error of type UNKNOWN-READER-TYPE is
signalled.
See UNKNOWN-READER-TYPE
Function to pretty print a generalised FORM to STREAM.
Emits a logical block wherein the FORM is printed.
The form must be a list and is stepped one by one. If the item in the list
is not a list, it is written readably to the stream. If it is a list, it is
written to the stream after a PPRINT-NEWLINE by PPRINT-LINEAR.
| Jump to: | (
A B C D F G H L M O P R S U V W |
|---|
| Jump to: | (
A B C D F G H L M O P R S U V W |
|---|
| Jump to: | *
F H P S T V |
|---|
| Jump to: | *
F H P S T V |
|---|
| Jump to: | A B C D F M N P S U |
|---|
| Jump to: | A B C D F M N P S U |
|---|