Ubiquitous is a very easy-to-use library for persistent configuration storage. It automatically takes care of finding a suitable place to save your data, and provides simple functions to access and modify the data within.
Load ubiquitous through ASDF or Quicklisp.
The main functions you will be using are
value. The former loads the configuration according to a designator, and the latter is an accessor allowing you to retrieve and set properties.
(restore 'my-config) (setf (value :test) "hi!") (value :test)
Ubiquitous will not perform any loading unless you tell it to. Thus, before the storage is truly persistent, you need to tell it where to
restore from. Then, when values are set, it automatically saves the configuration to file. The location of the file is stored in
*storage-pathname*, which is automatically computed according to what is most suitable for the given
restore designator and OS. On Windows it will be under
%HOME%\AppData\Local\common-lisp\ubiquitous\ and everywhere else under
~/.config/common-lisp/ubiquitous/. The exact behaviour of the pathname choosing is documented in
value doesn't take a single name, but rather a path to a configuration value. The way things are traversed is handled by the
field generic accessor. It tries to handle a number of commonly used structures, but you might have to extend it for your own classes, if you want to store those directly and traverse them. If a place does not exist yet, Ubiquitous will try to augment it if possible by creating a hash-table. This allows you to directly write a long path without having to worry about the containers existing.
(setf (value 'something 'that 'goes 6 'levels 'deep) "Calling from the depths!")
Often times for configuration one might want to specify a default value to use.
(defaulted-value "localhost" :hostname)
In case you need to remove a value, there's
(remvalue 'something 'that 'goes 6 'levels 'deep)
By default, an extended s-expression format is used to store things in a file. If you need a different format, you can add methods to
write-storage, and set
*storage-type* to your type name. Since
(setf value) automatically calls
offload to persist the storage, this might lead to a lot of saving all over the place. In order to avoid this, you can bundle a block of operations in a
with-transaction form, which will only perform an
offload once the block exits.
Ubiquitous in itself does not have any external dependencies, so you may also bundle it into a singular file to just
load using ASDF:
(asdf:operate :build-op :ubiquitous)
Which will produce an independent
ubiquitous.lisp file in
By default Ubiquitous does not try to handle concurrent access in any way. The reason for this is not laziness, but merely the desire to avoid dependencies for those that don't need it. However, if you require safe concurrent access and handling of the storage, simply load
ubiquitous-concurrent instead of
ubiquitous. This will also pull in
bordeaux-threads and establish additional methods around the standard definitions that will ensure concurrency safety.
This will still work irregardless of how many different storage objects you use, as the locking on the operations happens on the currently accessed storage object itself, rather than on a global lock. In order to avoid needless locking and unlocking, you should bundle your operations into a
with-transaction block, which will only perform a lock once.
A couple of shortcomings exist in Ubiquitous, almost by necessity. As you might know out of experience, certain modifying operations are not possible to do without being able to modify the container of the object itself. As an example,
poping an element off the head of the list requires setting the variable that contains the list, rather than the list itself. This sort of thing is rather annoying to model in a generic manner without complicating the common case needlessly. Furthermore, in a couple of instances ambiguity arises due to multiple actions being possible.
In detail, the following operations are supported suboptimally, or not at all:
listwith one element left that is to be removed. The
carof the cons will simply be set to
vector. This would require shifting fields and potentially adjusting it. The desired effect cannot be estimated and so Ubiquitous does not support the operation at all.
standard-object, as class-slots cannot be removed without the MOP and you probably wouldn't want that to happen anyway.
vectorwhere the field is an index exceeding the length. In this case, an error is signalled as extending the object to the required length might not be a desired or possible effect.
listwhere the field is a symbol or string. Lists are commonly used as alists or plists. Ubiquitous strictly expects alists.
Another shortcoming is in the department of serialisation. Ubiquitous does not try to be overly smart about things, which especially comes into effect when serialising
standard-objects. Ubiquitous saves the class' slots and restores it by calling
allocate-instance without initargs and then
setf slot-value-ing one slot after the other. If you need more tailored support for serialising your object, you must extend
define-ubiquitous-writer, or write a new storage format altogether. Furthermore, since the default behaviour is to use the lisp printer and reader (with special handling for
package) to serialise objects, several things might get lost in translation, such as the fill-pointer and adjustability of a vector.
- No documentation provided.
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.
Special variable containing the current root storage object. Defaults to an EQUAL hash-table.
An indicator for the type of storage format to use. Defaults to :LISP Only used as a discerning argument to READ/WRITE-STORAGE.
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
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 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
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. An uninterned or keyword SYMBOL: The symbol-name is used as the pathname-name and merged with CONFIG-PATHNAME. A SYMBOL from the CL package: An error is raised, as in almost all certainty don't want to do this. Using a CL symbol would very likely run you into configuration conflicts with other applications. An interned SYMBOL: A pathname with the symbol's package-name as relative directory and the symbol-name as pathname-name is merged with CONFIG-PATHNAME. 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"
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.
- No documentation provided.
To be used on NO-STORAGE-FILE, returns the pathname to the file that could not be found.
- No documentation provided.
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
Reads a storage object from STREAM, which must be stored in a format suitable for TYPE. Returns the read storage object.
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.
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*
- No documentation provided.
Writes the STORAGE object to STREAM in a format suitable for TYPE. Returns the written STORAGE object.
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
Binds *STORAGE* to the given STORAGE object, ensuring a local configuration.
Executes BODY within a transaction. See CALL-WITH-TRANSACTION