6 Action Lists

6.1 Defining and undefining action lists

Action lists are defined using thedefine-action-list macro, and are undefined using theundefine-action-list. It is also possible to make unnamed, unregistered lists usingmake-unregistered-action-list.

define-action-list

Macro

define-action-list uid &key documentation sort-time dummy-actions default-order execution-function

: Thedefine-action-list macro defines an action list.
: uid is a unique identifier, and must be a general lisp object, to be compared byequalp. It names the list in the global registry of lists. Seemake-unregistered-action-list to create unnamed, "unregistered" action-lists. The uid may be quoted, but is not required to be. It is possible, but not recommended, to define an action-list with unique identifiernil. If a registered action-list with the uid already exists (that is, one which returnst when compared withequalp), then notification and subsequent handling is controlled by the value of the*handle-existing-action-list* variable.
: The documentation string allows you to provide documentation for the action list.
: sort-time is a keyword specifying when added actions are sorted for the given list -- either:execute or:define-action.
: dummy-actions is a list of action-names that specify placeholding actions; they cannot be executed and are constrained to the order specified in this list, for example

'(:beginning :middle :end)

: default-order specifies default ordering constraints for subsequently defined action-items where no explicit ordering constraints are specified. An example is

'(:after beginning :before :end)

: execution-function specifies a user-defined function accepting arguments of the form:

(the-action-list other-args-list &rest keyword-value-pairs)

: where the two required arguments are the action-list and a list of additional arguments passed toexecute-actions, respectively. The remaining arguments are any number of keyword-value pairs that may be specified in the call toexecute-actions. If no execution function is specified, then the default execution function will be used to execute the action-list.

undefine-action-list

Macro

undefine-action-list uid

: Theundefine-action-list flushes the specified list (and all its action-items). If the action-list specified by uid does not exist, then handling is controlled by the value of the *handle-missing-action-list* variable.

When defining an action-list, the user may provide an associated execution-function. When executing the action-list, this user-defined execution-function is used instead of the default execution-function, to map over and "execute" the action-list's action-items. The macrowith-action-list-mapping provides facilities to map over action-items (that is, their corresponding "data"). In addition, the with-action-list-error-handling macro provides a simple mechanism to trap errors and print warnings while executing each action-item.

All execution-functions are required to accept arguments of the form:

  (action-list other-args &rest keyword-value-pairs)

where the two required arguments are the action-list and the list of additional arguments passed to execute-actions (see above), respectively. The remaining arguments are any number of keyword-value pairs that may be specified in the call to execute-actions. See the LispWorks Reference Manual entries forwith-action-list-mapping andwith-action-item-error-handling for examples of execution-functions.

Actions are added to an action list usingdefine-action, and are removed usingundefine-action.

define-action

Macro

define-action nae-or-list action-name data &rest specs

: This macro adds a new action to the list specified by name-or-list, which will be executed according to the action list's execution function.

undefine-action

Macro

undefine-action nae-or-list action-name

: This macro removes the action specified by action-name from the list specified by name-or-list.