API Reference

The following symbols are exported by the LIVE-CELLS package.

Macro (defcell name value-form)

Define a global cell identified by NAME.

This macro defines a cell identified by NAME with its value computed by VALUE-FORM. The value of the cell can be referenced by the symbol NAME following the DEFCELL form.

If VALUE-FORM is a constant, by CONSTANTP, a mutable cell is defined which can have its value set directly using SETF or SETQ on the symbol NAME.

If VALUE-FORM is not a constant a computed cell is created. A computed cell may reference one or more argument cells in VALUE-FORM or a function called during the evaluation of VALUE-FORM. When the values of any of the argument cells change, the value of the computed cell is recomputed by evaluating VALUE-FORM again. The referenced argument cells are determined automatically when the VALUE-FORM is evaluated.

This macro creates a cell definition that is visible globally to all forms unless it is lexically shadowed by a definition with the same NAME using CELL-LET. Note that despite being visible globally, the cell definition is still lexically scoped and not dynamically scoped like global variables defined with DEFVAR or DEFPARAMETER.

Macro (live &body forms)

Define a live block consisting of FORMS.

The FORMS are evaluated once when the LIVE form is first evaluated, after which they are evaluated again whenever the values of the cells referenced by them change. Cells may be referenced either directly in FORMS or by a function called during the evaluation of FORMS.

Returns a function which when called, stops the live block. Once stopped the live block will no longer be called when the values of the referenced cells change.

Macro (cell-let (&rest bindings) &body body)

Define cells that are visible only to the forms in BODY.

BINDINGS is a list of cell bindings to establish, similar to LET*. Each item in BINDINGS is a list of the form

(NAME VALUE-FORM)

where NAME is the symbol identifying the cell and VALUE-FORM is the value form of the cell. The cell can then be referenced within the forms in BODY by the symbol NAME.

The cells defined in BINDINGS lexcially shadow those in the environment defined with DEFCELL or by an enclosing CELL-LET form. Like LET* and unlike LET, each cell definition may reference the cells defined earlier in the same CELL-LET.

The forms in BODY are evaluated in an implicit PROGN. The value returned by the last form is returned by the CELL-LET form.

Macro (batch &body forms)

Batch assignments to the values of mutable cells.

The forms in FORMS are evaluated, in an implicit PROGN, with mutable cell assignment batching in effect. This means that when the value of a mutable cell is set by SETF within the dynamic extent of the BATCH form, the observers of the cell are only notified after the last form in FORMS is evaluated, or the BATCH form is exited by a non-local exit such as by RETURN-FROM. The effect of this is that the cells appear to have their values changed simultaneously.

Note

When a BATCH form is nested in the dynamic extent of another BATCH form, the nested BATCH form has no effect other than to evaluate FORMS. The observers of the cells are only notified when exiting the outermost BATCH form.

Returns the value of the last form in FORMS.

Function (none &optional default-value)

Stop the computation of a cell’s value.

When this function is called within the value form of cell, the computation of the cell’s value is stopped, the value form is exited and the cell’s current value is preserved.

If this function is called while computing the initial value of a cell, the value of the cell is set to DEFAULT-VALUE.

The symbol-macro NONE is a synonym for (NONE).

This function works by signaling a STOP-COMPUTATION condition, which is then handled by the cell. It is important that this condition is not handled by the value form of the cell, otherwise this function will have no effect.