action list

1.0.0

An implementation of action lists

About Action List

This library implements the action list data structure. This structure or paradigm is a useful alternative to state machines, and is especially suited for problems that have a temporal component.

How To

The interface is all rather straight-forward to use, with a variety of push functions to insert actions at the appropriate places.

(make-instance 'action-list:action-list)
(action-list:push-front (make-instance 'action-list:basic-action :update (lambda (a dt) (print dt)) :duration 1.0) *)
(dotimes (i 20)
  (action-list:update ** 0.1))

You can either subclass action to roll your own types, or use the basic-action and supply the various parts you want to customise with closures.

If an action is blocking-p, it will prevent later actions in the list from running. Without blocking actions, all actions will be updated in sequence. Blocking this from happening can be useful to ensure a sequence of actions take place.

To this end there are also the shorthand action types delay-action (to delay updates until a given point) and synchronize-action to block until all "parallel" actions before it have completed.

The action-list is also a standard sequence so you can iterate over it with sequences:dosequence and use other standard sequence operators. Note that an action instance can only be contained on a single action-list at any time. In order to copy an action-list, then, each action contained needs to be copied as well. The copy-into function is used to customise this behaviour when necessary. If you create your own actions that require extra slots, make sure to properly implement copy-into.

System Information

Version: 1.0.0

Dependencies:

Author: Nicolas Hafner

License: zlib

Homepage: https://github.com/Shinmera/action-list

Definition Index

ORG.SHIRAKUMO.FRAF.ACTION-LIST

No documentation provided.

EXTERNAL CLASS

ACTION

Base class representing an action.

An action is an object that is updated and performs... actions until a
specified time at which point it terminates and is removed from the
action list.

An action can be present on one or more lanes. If the action is
blocking, it prevents all later actions that are present on the same
lane/s as the blocking action from being updated.

You should create a subclass of this action that in the very least
implements UPDATE, and possibly START, STOP, DURATION, and LANES.

See ACTION-LIST
See PUSH-FRONT
See PUSH-BACK
See PUSH-BEFORE
See PUSH-AFTER
See POP-ACTION
See UPDATE
See DURATION
See ELAPSED-TIME
See REMAINING-TIME
See BLOCKING-P
See FINISHED-P
See LANES
See START
See STOP

EXTERNAL CLASS

ACTION-LIST

Representation of an action list.

An action list is a sequence of actions that are updated in turn until
a blocking action is encountered.

When an action list is copied, each of the actions within is copied
via CLONE-INTO, as an action can only ever be contained within a
single action-list. If the action list's length is adjusted downwards,
excessive actions are removed from the list as if by POP-ACTION. If
the action list's length is adjusted upwards, new elements are filled
by copying INITIAL-ELEMENT if passed, and constructing DUMMY-ACTIONs
otherwise. If INITIAL-CONTENTS is passed to a copying or adjusting
operation, each action in the list is removed as if by POP-ACTION, and
the new actions as supplied are inserted instead.

In short, copied action-lists will not contain actions that are EQ to
the ones of the source list.

See ACTION
See PUSH-FRONT
See PUSH-BACK
See PUSH-BEFORE
See PUSH-AFTER
See POP-ACTION
See UPDATE
See DURATION
See ELAPSED-TIME
See REMAINING-TIME
See BLOCKING-P
See FINISHED-P
See CLONE-INTO

EXTERNAL CLASS

ACTION-LIST-ACTION

Action that is simultaneously an action-list. Lets you hierarchically nest actions.

See ACTION-LIST (type)
See ACTION (type)

EXTERNAL CLASS

BASIC-ACTION

Action that lets you dynamically specify its parts.

To customise UPDATE, pass a closure of two arguments (the action and
the delta time) as an initarg.
To customise START, pass a closure of one argument (the action) as an
initarg.
To customise STOP, pass a closure of one argument (the action) as an
initarg.
To specify whether the action should block or not, pass the BLOCKING
initarg.

See LANE-LIMITED-ACTION
See TIME-LIMITED-ACTION

EXTERNAL CLASS

DELAY-ACTION

Action that delays execution by the passed DURATION.

By default blocks all lanes.

See TIME-LIMITED-ACTION
See LANE-LIMITED-ACTION

EXTERNAL CLASS

DUMMY-ACTION

Action that immediately finishes.

SEE ACTION (type)

EXTERNAL CLASS

LANE-LIMITED-ACTION

Superclass for actions that are restricted to a set of lanes.

Accepts the LANES as an  initarg.

See ACTION (type)
See LANES

EXTERNAL CLASS

SYNCHRONIZE-ACTION

Action that finishes once it reaches the front of the list.

By default blocks all lanes.

See LANE-LIMITED-ACTION

EXTERNAL CLASS

TIME-LIMITED-ACTION

Superclass for actions that have a specific duration before they automatically finish.

Accepts the DURATION as an initarg.

See ACTION (type)
See DUARTION

EXTERNAL GENERIC-FUNCTION

ACTION-LIST

OBJECT

Returns the action list in which it is contained.

If the action is not currently contained in an action list, an error
is signalled instead.

See ACTION
See ACTION-LIST (type)

EXTERNAL GENERIC-FUNCTION
(SETF ACTION-LIST)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

BLOCKING-P

OBJECT

Returns whether the object blocks later objects from being updated.

For an ACTION-LIST this returns T when the list contains a blocking
action.

See ACTION (type)
See ACTION-LIST (type)

EXTERNAL GENERIC-FUNCTION
(SETF BLOCKING-P)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

CLONE-INTO

TARGET
SOURCE

Copy the properties of SOURCE into NEW.

When NEW is T, a shallow copy of SOURCE is created and CLONE-INTO is
called with this new copy as NEW.

This function is used when copying ACTION-LISTs.

See ACTION-LIST (type)

EXTERNAL GENERIC-FUNCTION

DURATION

OBJECT

Returns the duration of the object's runtime, in seconds.

See ACTION (type)
See ACTION-LIST (type)

EXTERNAL GENERIC-FUNCTION
(SETF DURATION)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

ELAPSED-TIME

OBJECT

Returns the length of time for which the object has been updated, in seconds.

See ACTION (type)
See ACTION-LIST (type)

EXTERNAL GENERIC-FUNCTION
(SETF ELAPSED-TIME)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

FINISHED-P

OBJECT

Accesses whether the object is finished.

An action should set this to T when it should no longer be UPADTEd and
should be removed from the ACTION-LIST at the next opportunity.

For an ACTION-LIST this returns T when the list is empty.

See ACTION (type)
See ACTION-LIST (type)

EXTERNAL GENERIC-FUNCTION
(SETF FINISHED-P)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

LANES

ACTION

Returns an integer bitfield that represents the lanes the action is active on.

Every bit of the integer that is active (1) represents a lane the
action is active on. If the action is blocking, the lanes it is active
on will be blocked from being updated until the action is finished.

Either way, an action is only updated if at least one of the lanes it
is active on is not blocked by a prior action.

See ACTION (type)

EXTERNAL GENERIC-FUNCTION
(SETF LANES)
- NEW-VALUE
- OBJECT
No documentation provided.

EXTERNAL GENERIC-FUNCTION

POP-ACTION

ACTION
ACTION-LIST

Removes the action from the action list.

See ACTION (type)
See ACTION-LIST (type)

EXTERNAL GENERIC-FUNCTION

PUSH-AFTER

NEW-ACTION
ACTION

Push the NEW action immediately after the OLD action.

Signals an error if the OLD action is not contained in any action
list.

See ACTION (type)

EXTERNAL GENERIC-FUNCTION

PUSH-BACK

NEW-ACTION
ACTION-LIST

Push the action to the back of the action list.

See ACTION (type)
See ACTION-LIST (type)

EXTERNAL GENERIC-FUNCTION

PUSH-BEFORE

NEW-ACTION
ACTION

Push the NEW action in front of the OLD action.

Signals an error if the OLD action is not contained in any
action list.

See ACTION (type)

EXTERNAL GENERIC-FUNCTION

PUSH-FRONT

NEW-ACTION
ACTION-LIST

Push the action to the front of the action list.

See ACTION (type)
See ACTION-LIST (type)

EXTERNAL GENERIC-FUNCTION

REMAINING-TIME

OBJECT

Returns the length of time for which the object will remain running, in seconds.

Note that this only considers time for which the object is actually
updated. If the object is blocked from receiving updates, the
remaining time will not decrease.

Objects may also not finish even after the remaining time has passed.

See ACTION (type)
See ACTION-LIST (type)

EXTERNAL GENERIC-FUNCTION

START

ACTION

Function called when an action is added to an action-list.

See ACTION (type)

EXTERNAL GENERIC-FUNCTION

STOP

ACTION

Function called when an action is finished and removed from an action-list.

Note that this is NOT called if the action is manually removed from
the action list via POP-ACTION.
It IS called once when the action is FINISHED-P and the action list is
next updated.

See ACTION (type)

EXTERNAL GENERIC-FUNCTION

UPDATE

OBJECT
DT

Performs the update step of the object, advancing it by DT seconds.

See ACTION (type)
See ACTION-LIST (type)