Action lists are defined using the
define-action-list
macro, and are undefined using the
undefine-action-list
. It is also possible to make unnamed, unregistered lists using
make-unregistered-action-list
.
define-action-list
uid
&key
documentation
sort-time
dummy-actions
default-order
execution-function
The
define-action-list
macro defines an action list.
uid
is a unique identifier, and is a general lisp object, to be compared by
equalp
. It names the list in the global registry of lists. See
make-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 identifier
nil
. If a registered action-list with the
uid
already exists (that is, one which returns
t
when compared with
equalp
), 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 to
execute-actions
, respectively. The remaining arguments are any number of keyword-value pairs that may be specified in the call to
execute-actions
. If no execution function is specified, then the default execution function will be used to execute the action-list.
undefine-action-list
uid
The
undefine-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 macro
with-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 for
with-action-list-mapping
and
with-action-item-error-handling
for examples of execution-functions.
Actions are added to an action list using
define-action
, and are removed using
undefine-action
.
define-action
name-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
name-or-list
action-name
This macro removes the action specified by action-name from the list specified by name-or-list .