AGUTIL

A collection of Common Lisp utility functions and macros not found (to the best of my knowledge) in other utility packages.

Macro Writing

Function: GENSYMS &KEY KEY

Returns a list of unique symbols, generated by GENSYM. The SYMBOL-NAME of each element in SYMS is used as a prefix of the corresponding generated symbol. If KEY is provided the SYMBOL-NAME of the result returned by calling KEY with each element in SYMS is used as the prefix.

Packages

Function: MERGE-PACKAGES NEW-PACKAGE-NAME &REST PACKAGES

Creates a new package with name NEW-PACKAGE-NAME, if it does not already exist, into which all external symbols in each package in PACKAGES are imported, by SHADOWING-IMPORT. The external symbols of each package in PACKAGES are imported in the order in which the package appears in the list, thus symbols imported from packages towards the end of the PACKAGES list will shadow symbols imported from packages at the beginning of the list.

Macro: DEFINE-MERGED-PACKAGE NAME &REST PACKAGES

Convenience macro which defines a merged package using MERGE-PACKAGES. NAME (not evaluated) is the name of the new package and PACKAGES (not evaluated) is the list of packages of which the external symbols are imported in package NAME.

Functional Programming

Function REPEAT-FUNCTION FN N

Returns a list of N items obtained by calling the function FN N times.

Utility Macros

Macro: LET-IF (&REST BINDINGS) CONDITION &BODY BODY

Binds variables to different values computed by different init-forms based on whether CONDITION evaluates to true or false. BINDINGS is a list of bindings where the first element is the variable symbol the second element is the init-form to evaluated if CONDITION evaluates to true, the second element is the init-form to evaluate if CONDITION evaluates to false.

Macro: MATCH-STATE ARG &BODY STATES

Implements an FSM (Finite State Machine) where each state may specify a pattern (in the form accepted by the trivia pattern matcher) and a list of from states, when the argument matches the pattern of a particular state and the current state is in the state's from states list, the FSM transitions to that state.

Each element in STATES is a list of the following form: (STATE PATTERN [:FROM STATES] . BODY) where STATE is a symbol identifying the state, PATTERN is the pattern to be matched, and STATES is the optional list of from states (it and the :FROM keyword may be excluded). if there is only one state it does not have to be in a list. If a state specifies no from states, it is as if all states, in the MATCH-STATE form, are specified as from states.

When a state becomes the current state the forms in its BODY are executed, in which the machine may either transition to the next state using the lexically defined function (NEXT NEW-ARG) where NEW-ARG is the new argument to be matched against the patterns. If NEXT is never called in body the return value of the last form in BODY becomes the return value of the MATCH-STATE form.

The initial argument is given by evaluating the form ARG. The initial state may be optionally specified, when the first element of STATES is :START the second element is taken as the form to be evaluated to produce the start state, otherwise the start state defaults to :START. Patterns are matched in the order given, the first state whose pattern matches (both the argument pattern and FROM list) becomes the current state.

FIFO Queue

Function: MAKE-QUEUE &REST ELEMS

Creates a FIFO queue with initial elements ELEMS.

Function: QUEUE-EMPTY? QUEUE

Returns true if QUEUE is empty.

Function: ENQUEUE ELEM QUEUE

Adds ELEM to the head of QUEUE. QUEUE is modified.

Function: DEQUEUE QUEUE

Removes and returns the element at the tail of QUEUE. NIL if the queue is empty. QUEUE is modified.

Function: ENQUEUE-LIST ELEMS QUEUE

Adds each element in the list ELEMS to the head of the queue QUEUE. QUEUE is modified.

Function: QUEUE->LIST QUEUE

Returns a list of the elements in QUEUE.