The ubiquitous Reference Manual

Table of Contents

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

The ubiquitous Reference Manual

This is the ubiquitous Reference Manual, version 2.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 19:26:08 2020 GMT+0.


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

1 Introduction

About Ubiquitous

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.

How To

Load ubiquitous through ASDF or Quicklisp.

(ql:quickload :ubiquitous)

The main functions you will be using are restore, and 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 designator-pathname.

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.

(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 read-storage and 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 (asdf:system-source-directory :ubiquitous).

Concurrency

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.

Metadata

Since version 2.0, Ubiquitous will output a metadata header into the configuration file. It will typically have the following structure:

; meta (:version 1.0 :package "CL-USER")

The purpose of this header is to ensure print/read consistency. When offloading, the current *package* is output into the header, so that when the configuration is restored, unqualified symbols in the configuration are read with the same home package as they were printed with.

If the header is missing your configuration will still read fine, and since it is a comment, configurations will still be compatible when read with version 1.0 of Ubiquitous. An error is however signalled if the header is malformed, or the referred package cannot be found.

If you implement your own storage format, you should ensure that you output and respect the same header, or a similar header. See maybe-read-metadata, with-processed-metadata, print-metadata, and related functions.

Shortcomings

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:

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-reader and 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 hash-table, standard-object, standard-class, and package) to serialise objects, several things might get lost in translation, such as the fill-pointer and adjustability of a vector.


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 ubiquitous

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://github.com/Shinmera/ubiquitous

License

zlib

Description

A library providing a universal application configuration mechanism.

Version

2.0.0

Source

ubiquitous.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 ubiquitous.asd

Location

ubiquitous.asd

Systems

ubiquitous (system)


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

3.1.2 ubiquitous/package.lisp

Parent

ubiquitous (system)

Location

package.lisp

Packages

ubiquitous


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

3.1.3 ubiquitous/pathname.lisp

Dependency

package.lisp (file)

Parent

ubiquitous (system)

Location

pathname.lisp

Exported Definitions
Internal Definitions

split-package-name (function)


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

3.1.4 ubiquitous/accessor.lisp

Dependency

pathname.lisp (file)

Parent

ubiquitous (system)

Location

accessor.lisp

Exported Definitions
Internal Definitions

*nothing* (special variable)


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

3.1.5 ubiquitous/metadata.lisp

Dependency

accessor.lisp (file)

Parent

ubiquitous (system)

Location

metadata.lisp

Exported Definitions
Internal Definitions

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

3.1.6 ubiquitous/storage.lisp

Dependency

metadata.lisp (file)

Parent

ubiquitous (system)

Location

storage.lisp

Exported Definitions
Internal Definitions

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

3.1.7 ubiquitous/config.lisp

Dependency

storage.lisp (file)

Parent

ubiquitous (system)

Location

config.lisp

Exported Definitions

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

3.1.8 ubiquitous/documentation.lisp

Dependency

config.lisp (file)

Parent

ubiquitous (system)

Location

documentation.lisp

Internal Definitions

setdocs (macro)


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

4 Packages

Packages are listed by definition order.


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

4.1 ubiquitous

Source

package.lisp (file)

Nickname

org.shirakumo.ubiquitous

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: *changed*

When non-NIL it means a change has occurred and the config should be offloaded.

Package

ubiquitous

Source

config.lisp (file)

Special Variable: *commit*

When non-NIL, an OFFLOAD is performed after a call to (SETF VALUE) or REMVALUE.

Package

ubiquitous

Source

config.lisp (file)

Special Variable: *metadata-prefix*

The prefix that is used to recognise the metadata header.

Package

ubiquitous

Source

metadata.lisp (file)

Special Variable: *metadata-version*

The current version of the configuration metadata.

Should be a float.

Package

ubiquitous

Source

metadata.lisp (file)

Special Variable: *storage*

Special variable containing the current root storage object. Defaults to an EQUAL hash-table.

Package

ubiquitous

Source

storage.lisp (file)

Special Variable: *storage-pathname*

The pathname for the file where the current *STORAGE* is stored. Defaults to (DESIGNATOR-PATHNAME :GLOBAL *STORAGE-TYPE*).

See DESIGNATOR-PATHNAME
See *STORAGE-TYPE*

Package

ubiquitous

Source

storage.lisp (file)

Special Variable: *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.

Package

ubiquitous

Source

storage.lisp (file)


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

5.1.2 Macros

Macro: define-ubiquitous-reader TYPE (FORM) &body BODY

Define a new function that produces an object of TYPE by parsing the read FORM.

Package

ubiquitous

Source

storage.lisp (file)

Macro: define-ubiquitous-writer TYPE (OBJECT &optional PRIORITY) &body BODY

Define a new function that produces a list of objects to be written to reproduce OBJECT of TYPE.

Package

ubiquitous

Source

storage.lisp (file)

Macro: with-local-storage (DESIGNATOR &key TYPE STORAGE TRANSACTION) &body BODY

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

Package

ubiquitous

Source

storage.lisp (file)

Macro: with-processed-metadata META &body BODY

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

Package

ubiquitous

Source

metadata.lisp (file)

Macro: with-storage (STORAGE) &body BODY

Binds *STORAGE* to the given STORAGE object, ensuring a local configuration.

Package

ubiquitous

Source

storage.lisp (file)

Macro: with-transaction (&key STORAGE TYPE DESIGNATOR) &body BODY

Executes BODY within a transaction.

See CALL-WITH-TRANSACTION

Package

ubiquitous

Source

config.lisp (file)


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

5.1.3 Functions

Function: config-directory ()

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

Package

ubiquitous

Source

pathname.lisp (file)

Function: config-pathname TYPE

Returns a pathname with the proper directory and type set.

See CONFIG-DIRECTORY

Package

ubiquitous

Source

pathname.lisp (file)

Function: find-metadata-package NAME

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

Package

ubiquitous

Source

metadata.lisp (file)

Function: generate-metadata ()

Generates valid metadata for the current environment.

Package

ubiquitous

Source

metadata.lisp (file)

Function: lazy-loader ACTION FIELD &optional VALUE

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

Package

ubiquitous

Source

storage.lisp (file)

Function: maybe-read-metadata STREAM

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

Package

ubiquitous

Source

metadata.lisp (file)

Function: print-metadata STREAM &optional METADATA

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

Package

ubiquitous

Source

metadata.lisp (file)

Function: process-metadata META

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

Package

ubiquitous

Source

metadata.lisp (file)


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

5.1.4 Generic functions

Generic Function: augment OBJECT FIELD SECONDARY

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

Package

ubiquitous

Source

accessor.lisp (file)

Methods
Method: augment OBJECT FIELD (SECONDARY hash-table)
Method: augment OBJECT FIELD (SECONDARY structure-object)
Method: augment OBJECT FIELD (SECONDARY array)
Method: augment OBJECT FIELD (SECONDARY pathname)
Method: augment OBJECT FIELD (SECONDARY bit-vector)
Method: augment OBJECT FIELD (SECONDARY string)
Method: augment OBJECT FIELD (SECONDARY character)
Method: augment OBJECT FIELD (SECONDARY integer)
Method: augment OBJECT FIELD (SECONDARY symbol)
Generic Function: bad-package-name CONDITION

Returns the bad package name that the condition captured.

See BAD-CONFIGURATION-PACKAGE

Package

ubiquitous

Methods
Method: bad-package-name (CONDITION bad-configuration-package)
Source

metadata.lisp (file)

Generic Function: call-with-transaction FUNCTION &key STORAGE TYPE DESIGNATOR

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

Package

ubiquitous

Source

config.lisp (file)

Methods
Method: call-with-transaction FUNCTION &key STORAGE TYPE DESIGNATOR
Generic Function: defaulted-value DEFAULT &rest PATH

Same as VALUE, but automatically returns and sets DEFAULT if the field cannot be found.

See VALUE

Package

ubiquitous

Source

config.lisp (file)

Methods
Method: defaulted-value DEFAULT &rest PATH
Generic Function: designator-pathname DESIGNATOR TYPE

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

Package

ubiquitous

Source

pathname.lisp (file)

Methods
Method: designator-pathname DESIGNATOR TYPE around
Method: designator-pathname (DESIGNATOR string) TYPE
Method: designator-pathname (DESIGNATOR symbol) TYPE
Method: designator-pathname (DESIGNATOR pathname) TYPE
Generic Function: destroy &optional DESIGNATOR TYPE

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

Package

ubiquitous

Source

storage.lisp (file)

Methods
Method: destroy &optional DESIGNATOR TYPE
Generic Function: field OBJECT FIELD &optional DEFAULT

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.

Package

ubiquitous

Source

accessor.lisp (file)

Writer

(setf field) (generic function)

Methods
Method: field (OBJECT function) FIELD &optional DEFAULT
Method: field (OBJECT null) FIELD &optional DEFAULT
Method: field (OBJECT symbol) (FIELD symbol) &optional DEFAULT
Method: field (OBJECT standard-object) (FIELD symbol) &optional DEFAULT
Method: field (OBJECT list) (FIELD string) &optional DEFAULT
Method: field (OBJECT list) (FIELD symbol) &optional DEFAULT
Method: field (OBJECT list) (FIELD integer) &optional DEFAULT
Method: field (OBJECT vector) (FIELD integer) &optional DEFAULT
Method: field (OBJECT hash-table) FIELD &optional DEFAULT
Generic Function: (setf field) VALUE OBJECT FIELD
Package

ubiquitous

Source

accessor.lisp (file)

Reader

field (generic function)

Methods
Method: (setf field) VALUE (OBJECT function) FIELD
Method: (setf field) VALUE (OBJECT symbol) (FIELD symbol)
Method: (setf field) VALUE (OBJECT standard-object) (FIELD symbol)
Method: (setf field) VALUE (OBJECT list) (FIELD string)
Method: (setf field) VALUE (OBJECT list) (FIELD symbol)
Method: (setf field) VALUE (OBJECT list) (FIELD integer)
Method: (setf field) VALUE (OBJECT vector) (FIELD integer)
Method: (setf field) VALUE (OBJECT hash-table) FIELD
Method: (setf field) VALUE OBJECT FIELD around
Generic Function: file CONDITION

To be used on NO-STORAGE-FILE, returns the pathname to the file that could not be found.

Package

ubiquitous

Writer

(setf file) (generic function)

Methods
Method: file (CONDITION no-storage-file)
Source

storage.lisp (file)

Generic Function: (setf file) NEW-VALUE CONDITION
Package

ubiquitous

Reader

file (generic function)

Methods
Method: (setf file) NEW-VALUE (CONDITION no-storage-file)
Source

storage.lisp (file)

Generic Function: header CONDITION

Returns the header that is malformed.

See BAD-METADATA-HEADER

Package

ubiquitous

Methods
Method: header (CONDITION bad-metadata-header)
Source

metadata.lisp (file)

Generic Function: offload &optional DESIGNATOR TYPE STORAGE

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

Package

ubiquitous

Source

storage.lisp (file)

Methods
Method: offload &optional DESIGNATOR TYPE STORAGE
Generic Function: package-directory PACKAGE

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

ubiquitous

Source

pathname.lisp (file)

Methods
Method: package-directory (PACKAGE package)
Method: package-directory (PACKAGE (eql keyword))
Method: package-directory (PACKAGE null)
Method: package-directory (PACKAGE (eql common-lisp))
Method: package-directory (NAME string)
Method: package-directory (NAME symbol)
Generic Function: read-storage TYPE STREAM

Reads a storage object from STREAM, which must be stored in a format suitable for TYPE. Returns the read storage object.

Package

ubiquitous

Source

storage.lisp (file)

Methods
Method: read-storage (TYPE (eql lisp)) STREAM
Generic Function: reader-type CONDITION

Returns the type that was attempted to be read.

See UNKNOWN-READER-TYPE

Package

ubiquitous

Methods
Method: reader-type (CONDITION unknown-reader-type)
Source

storage.lisp (file)

Generic Function: remfield OBJECT FIELD

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.

Package

ubiquitous

Source

accessor.lisp (file)

Methods
Method: remfield (OBJECT function) FIELD
Method: remfield (OBJECT symbol) (FIELD symbol)
Method: remfield (OBJECT list) (FIELD string)
Method: remfield (OBJECT list) (FIELD symbol)
Method: remfield (OBJECT list) (FIELD integer)
Method: remfield (OBJECT hash-table) FIELD
Method: remfield OBJECT FIELD around
Generic Function: remvalue &rest PATH

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

Package

ubiquitous

Source

config.lisp (file)

Methods
Method: remvalue &rest PATH
Generic Function: restore &optional DESIGNATOR TYPE

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

Package

ubiquitous

Source

storage.lisp (file)

Methods
Method: restore &optional DESIGNATOR TYPE
Generic Function: value &rest PATH

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*

Package

ubiquitous

Source

config.lisp (file)

Writer

(setf value) (generic function)

Methods
Method: value &rest PATH
Generic Function: (setf value) VALUE &rest PATH
Package

ubiquitous

Source

config.lisp (file)

Reader

value (generic function)

Methods
Method: (setf value) VALUE &rest PATH
Generic Function: version CONDITION

Returns the version captured by the condition.

See UNKNOWN-VERSION

Package

ubiquitous

Methods
Method: version (CONDITION unknown-version)
Source

metadata.lisp (file)

Generic Function: write-storage TYPE STREAM STORAGE

Writes the STORAGE object to STREAM in a format suitable for TYPE. Returns the written STORAGE object.

Package

ubiquitous

Source

storage.lisp (file)

Methods
Method: write-storage (TYPE (eql lisp)) STREAM STORAGE
Method: write-storage TYPE PATHNAME STORAGE around

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

5.1.5 Conditions

Condition: bad-configuration-package ()

Error signalled when the metadata header refers to an unknown package.

See BAD-PACKAGE-NAME
See METADATA-CONDITION

Package

ubiquitous

Source

metadata.lisp (file)

Direct superclasses
Direct methods

bad-package-name (method)

Direct slots
Slot: package
Initargs

:package-name

Initform

(quote (error "package-name required."))

Readers

bad-package-name (generic function)

Condition: bad-metadata-header ()

Error signalled when the metadata header is malformed.

See HEADER
See METADATA-CONDITION

Package

ubiquitous

Source

metadata.lisp (file)

Direct superclasses
Direct methods

header (method)

Direct slots
Slot: header
Initargs

:header

Initform

(quote (error "header required."))

Readers

header (generic function)

Condition: metadata-condition ()

Superclass for conditions related to configuration metadata.

Package

ubiquitous

Source

metadata.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses
Condition: no-storage-file ()

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

Package

ubiquitous

Source

storage.lisp (file)

Direct superclasses

condition (condition)

Direct methods
  • file (method)
  • file (method)
Direct slots
Slot: file
Initargs

:file

Readers

file (generic function)

Writers

(setf file) (generic function)

Direct Default Initargs
InitargValue
:file(error "file required.")
Condition: unknown-reader-type ()

Error signalled if an unknown structure type is encountered in the config.

See READER-TYPE
See UBIQUITOUS-READER

Package

ubiquitous

Source

storage.lisp (file)

Direct superclasses

error (condition)

Direct methods

reader-type (method)

Direct slots
Slot: type
Initargs

:reader-type

Initform

(quote (error "reader-type required."))

Readers

reader-type (generic function)

Condition: unknown-version ()

Warning signalled when the metadata header contains an unknown version number.

See VERSION
See METADATA-CONDITION

Package

ubiquitous

Source

metadata.lisp (file)

Direct superclasses
Direct methods

version (method)

Direct slots
Slot: version
Initargs

:version

Initform

(quote (error "version required."))

Readers

version (generic function)


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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *nothing*

Variable with a value used to represent an inexistent value.

Package

ubiquitous

Source

accessor.lisp (file)

Special Variable: *ubiquitous-char*

A string of two characters denoting the start and end of a special construct.

Package

ubiquitous

Source

storage.lisp (file)

Special Variable: *ubiquitous-print-table*

The pprint-dispatch-table used to write storage objects to file.

Package

ubiquitous

Source

storage.lisp (file)

Special Variable: *ubiquitous-read-table*

The readtable used to read storage objects from file.

Package

ubiquitous

Source

storage.lisp (file)

Special Variable: *ubiquitous-readers*

A hash table of functions invoked upon reading a special construct.

Package

ubiquitous

Source

storage.lisp (file)


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

5.2.2 Macros

Macro: setdocs &body PAIRS
Package

ubiquitous

Source

documentation.lisp (file)


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

5.2.3 Functions

Function: check-metadata META

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

Package

ubiquitous

Source

metadata.lisp (file)

Function: class-slots CLASS
Package

ubiquitous

Source

storage.lisp (file)

Function: prefix-p PREFIX STRING

Returns T if the PREFIX is a prefix of STRING.

Package

ubiquitous

Source

metadata.lisp (file)

Function: slot-definition-name SLOT
Package

ubiquitous

Source

storage.lisp (file)

Function: split-package-name PACKAGE
Package

ubiquitous

Source

pathname.lisp (file)

Function: ubiquitous-reader STREAM C

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

Package

ubiquitous

Source

storage.lisp (file)

Function: ubiquitous-writer STREAM FORM

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.

Package

ubiquitous

Source

storage.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   U  
Index Entry  Section

F
File, Lisp, ubiquitous.asd: The ubiquitous․asd file
File, Lisp, ubiquitous/accessor.lisp: The ubiquitous/accessor․lisp file
File, Lisp, ubiquitous/config.lisp: The ubiquitous/config․lisp file
File, Lisp, ubiquitous/documentation.lisp: The ubiquitous/documentation․lisp file
File, Lisp, ubiquitous/metadata.lisp: The ubiquitous/metadata․lisp file
File, Lisp, ubiquitous/package.lisp: The ubiquitous/package․lisp file
File, Lisp, ubiquitous/pathname.lisp: The ubiquitous/pathname․lisp file
File, Lisp, ubiquitous/storage.lisp: The ubiquitous/storage․lisp file

L
Lisp File, ubiquitous.asd: The ubiquitous․asd file
Lisp File, ubiquitous/accessor.lisp: The ubiquitous/accessor․lisp file
Lisp File, ubiquitous/config.lisp: The ubiquitous/config․lisp file
Lisp File, ubiquitous/documentation.lisp: The ubiquitous/documentation․lisp file
Lisp File, ubiquitous/metadata.lisp: The ubiquitous/metadata․lisp file
Lisp File, ubiquitous/package.lisp: The ubiquitous/package․lisp file
Lisp File, ubiquitous/pathname.lisp: The ubiquitous/pathname․lisp file
Lisp File, ubiquitous/storage.lisp: The ubiquitous/storage․lisp file

U
ubiquitous.asd: The ubiquitous․asd file
ubiquitous/accessor.lisp: The ubiquitous/accessor․lisp file
ubiquitous/config.lisp: The ubiquitous/config․lisp file
ubiquitous/documentation.lisp: The ubiquitous/documentation․lisp file
ubiquitous/metadata.lisp: The ubiquitous/metadata․lisp file
ubiquitous/package.lisp: The ubiquitous/package․lisp file
ubiquitous/pathname.lisp: The ubiquitous/pathname․lisp file
ubiquitous/storage.lisp: The ubiquitous/storage․lisp file

Jump to:   F   L   U  

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

A.2 Functions

Jump to:   (  
A   B   C   D   F   G   H   L   M   O   P   R   S   U   V   W  
Index Entry  Section

(
(setf field): Exported generic functions
(setf field): Exported generic functions
(setf field): Exported generic functions
(setf field): Exported generic functions
(setf field): Exported generic functions
(setf field): Exported generic functions
(setf field): Exported generic functions
(setf field): Exported generic functions
(setf field): Exported generic functions
(setf field): Exported generic functions
(setf file): Exported generic functions
(setf file): Exported generic functions
(setf value): Exported generic functions
(setf value): Exported generic functions

A
augment: Exported generic functions
augment: Exported generic functions
augment: Exported generic functions
augment: Exported generic functions
augment: Exported generic functions
augment: Exported generic functions
augment: Exported generic functions
augment: Exported generic functions
augment: Exported generic functions
augment: Exported generic functions

B
bad-package-name: Exported generic functions
bad-package-name: Exported generic functions

C
call-with-transaction: Exported generic functions
call-with-transaction: Exported generic functions
check-metadata: Internal functions
class-slots: Internal functions
config-directory: Exported functions
config-pathname: Exported functions

D
defaulted-value: Exported generic functions
defaulted-value: Exported generic functions
define-ubiquitous-reader: Exported macros
define-ubiquitous-writer: Exported macros
designator-pathname: Exported generic functions
designator-pathname: Exported generic functions
designator-pathname: Exported generic functions
designator-pathname: Exported generic functions
designator-pathname: Exported generic functions
destroy: Exported generic functions
destroy: Exported generic functions

F
field: Exported generic functions
field: Exported generic functions
field: Exported generic functions
field: Exported generic functions
field: Exported generic functions
field: Exported generic functions
field: Exported generic functions
field: Exported generic functions
field: Exported generic functions
field: Exported generic functions
file: Exported generic functions
file: Exported generic functions
find-metadata-package: Exported functions
Function, check-metadata: Internal functions
Function, class-slots: Internal functions
Function, config-directory: Exported functions
Function, config-pathname: Exported functions
Function, find-metadata-package: Exported functions
Function, generate-metadata: Exported functions
Function, lazy-loader: Exported functions
Function, maybe-read-metadata: Exported functions
Function, prefix-p: Internal functions
Function, print-metadata: Exported functions
Function, process-metadata: Exported functions
Function, slot-definition-name: Internal functions
Function, split-package-name: Internal functions
Function, ubiquitous-reader: Internal functions
Function, ubiquitous-writer: Internal functions

G
generate-metadata: Exported functions
Generic Function, (setf field): Exported generic functions
Generic Function, (setf file): Exported generic functions
Generic Function, (setf value): Exported generic functions
Generic Function, augment: Exported generic functions
Generic Function, bad-package-name: Exported generic functions
Generic Function, call-with-transaction: Exported generic functions
Generic Function, defaulted-value: Exported generic functions
Generic Function, designator-pathname: Exported generic functions
Generic Function, destroy: Exported generic functions
Generic Function, field: Exported generic functions
Generic Function, file: Exported generic functions
Generic Function, header: Exported generic functions
Generic Function, offload: Exported generic functions
Generic Function, package-directory: Exported generic functions
Generic Function, read-storage: Exported generic functions
Generic Function, reader-type: Exported generic functions
Generic Function, remfield: Exported generic functions
Generic Function, remvalue: Exported generic functions
Generic Function, restore: Exported generic functions
Generic Function, value: Exported generic functions
Generic Function, version: Exported generic functions
Generic Function, write-storage: Exported generic functions

H
header: Exported generic functions
header: Exported generic functions

L
lazy-loader: Exported functions

M
Macro, define-ubiquitous-reader: Exported macros
Macro, define-ubiquitous-writer: Exported macros
Macro, setdocs: Internal macros
Macro, with-local-storage: Exported macros
Macro, with-processed-metadata: Exported macros
Macro, with-storage: Exported macros
Macro, with-transaction: Exported macros
maybe-read-metadata: Exported functions
Method, (setf field): Exported generic functions
Method, (setf field): Exported generic functions
Method, (setf field): Exported generic functions
Method, (setf field): Exported generic functions
Method, (setf field): Exported generic functions
Method, (setf field): Exported generic functions
Method, (setf field): Exported generic functions
Method, (setf field): Exported generic functions
Method, (setf field): Exported generic functions
Method, (setf file): Exported generic functions
Method, (setf value): Exported generic functions
Method, augment: Exported generic functions
Method, augment: Exported generic functions
Method, augment: Exported generic functions
Method, augment: Exported generic functions
Method, augment: Exported generic functions
Method, augment: Exported generic functions
Method, augment: Exported generic functions
Method, augment: Exported generic functions
Method, augment: Exported generic functions
Method, bad-package-name: Exported generic functions
Method, call-with-transaction: Exported generic functions
Method, defaulted-value: Exported generic functions
Method, designator-pathname: Exported generic functions
Method, designator-pathname: Exported generic functions
Method, designator-pathname: Exported generic functions
Method, designator-pathname: Exported generic functions
Method, destroy: Exported generic functions
Method, field: Exported generic functions
Method, field: Exported generic functions
Method, field: Exported generic functions
Method, field: Exported generic functions
Method, field: Exported generic functions
Method, field: Exported generic functions
Method, field: Exported generic functions
Method, field: Exported generic functions
Method, field: Exported generic functions
Method, file: Exported generic functions
Method, header: Exported generic functions
Method, offload: Exported generic functions
Method, package-directory: Exported generic functions
Method, package-directory: Exported generic functions
Method, package-directory: Exported generic functions
Method, package-directory: Exported generic functions
Method, package-directory: Exported generic functions
Method, package-directory: Exported generic functions
Method, read-storage: Exported generic functions
Method, reader-type: Exported generic functions
Method, remfield: Exported generic functions
Method, remfield: Exported generic functions
Method, remfield: Exported generic functions
Method, remfield: Exported generic functions
Method, remfield: Exported generic functions
Method, remfield: Exported generic functions
Method, remfield: Exported generic functions
Method, remvalue: Exported generic functions
Method, restore: Exported generic functions
Method, value: Exported generic functions
Method, version: Exported generic functions
Method, write-storage: Exported generic functions
Method, write-storage: Exported generic functions

O
offload: Exported generic functions
offload: Exported generic functions

P
package-directory: Exported generic functions
package-directory: Exported generic functions
package-directory: Exported generic functions
package-directory: Exported generic functions
package-directory: Exported generic functions
package-directory: Exported generic functions
package-directory: Exported generic functions
prefix-p: Internal functions
print-metadata: Exported functions
process-metadata: Exported functions

R
read-storage: Exported generic functions
read-storage: Exported generic functions
reader-type: Exported generic functions
reader-type: Exported generic functions
remfield: Exported generic functions
remfield: Exported generic functions
remfield: Exported generic functions
remfield: Exported generic functions
remfield: Exported generic functions
remfield: Exported generic functions
remfield: Exported generic functions
remfield: Exported generic functions
remvalue: Exported generic functions
remvalue: Exported generic functions
restore: Exported generic functions
restore: Exported generic functions

S
setdocs: Internal macros
slot-definition-name: Internal functions
split-package-name: Internal functions

U
ubiquitous-reader: Internal functions
ubiquitous-writer: Internal functions

V
value: Exported generic functions
value: Exported generic functions
version: Exported generic functions
version: Exported generic functions

W
with-local-storage: Exported macros
with-processed-metadata: Exported macros
with-storage: Exported macros
with-transaction: Exported macros
write-storage: Exported generic functions
write-storage: Exported generic functions
write-storage: Exported generic functions

Jump to:   (  
A   B   C   D   F   G   H   L   M   O   P   R   S   U   V   W  

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

A.3 Variables

Jump to:   *  
F   H   P   S   T   V  
Index Entry  Section

*
*changed*: Exported special variables
*commit*: Exported special variables
*metadata-prefix*: Exported special variables
*metadata-version*: Exported special variables
*nothing*: Internal special variables
*storage*: Exported special variables
*storage-pathname*: Exported special variables
*storage-type*: Exported special variables
*ubiquitous-char*: Internal special variables
*ubiquitous-print-table*: Internal special variables
*ubiquitous-read-table*: Internal special variables
*ubiquitous-readers*: Internal special variables

F
file: Exported conditions

H
header: Exported conditions

P
package: Exported conditions

S
Slot, file: Exported conditions
Slot, header: Exported conditions
Slot, package: Exported conditions
Slot, type: Exported conditions
Slot, version: Exported conditions
Special Variable, *changed*: Exported special variables
Special Variable, *commit*: Exported special variables
Special Variable, *metadata-prefix*: Exported special variables
Special Variable, *metadata-version*: Exported special variables
Special Variable, *nothing*: Internal special variables
Special Variable, *storage*: Exported special variables
Special Variable, *storage-pathname*: Exported special variables
Special Variable, *storage-type*: Exported special variables
Special Variable, *ubiquitous-char*: Internal special variables
Special Variable, *ubiquitous-print-table*: Internal special variables
Special Variable, *ubiquitous-read-table*: Internal special variables
Special Variable, *ubiquitous-readers*: Internal special variables

T
type: Exported conditions

V
version: Exported conditions

Jump to:   *  
F   H   P   S   T   V  

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

A.4 Data types

Jump to:   B   C   M   N   P   S   U  
Index Entry  Section

B
bad-configuration-package: Exported conditions
bad-metadata-header: Exported conditions

C
Condition, bad-configuration-package: Exported conditions
Condition, bad-metadata-header: Exported conditions
Condition, metadata-condition: Exported conditions
Condition, no-storage-file: Exported conditions
Condition, unknown-reader-type: Exported conditions
Condition, unknown-version: Exported conditions

M
metadata-condition: Exported conditions

N
no-storage-file: Exported conditions

P
Package, ubiquitous: The ubiquitous package

S
System, ubiquitous: The ubiquitous system

U
ubiquitous: The ubiquitous system
ubiquitous: The ubiquitous package
unknown-reader-type: Exported conditions
unknown-version: Exported conditions

Jump to:   B   C   M   N   P   S   U