\begin{describe}{mac}
{with-gensyms (@{ @<var> @! (@<var> @[@<name>@]) @}^*) \\ \ind
@<declaration>^* \\
- @<form>^*}
+ @<form>^*
+ \-\nlret @<value>^*}
Bind each @<var> (a symbol, not evaluated) to a freshly made gensym whose
name is based on the corresponding @<name> (a string, evaluated), and
evaluate the @<form>s as an implicit @|progn| in the resulting environment.
@{ @<var> @! (@<var> @[@<value-form>@]) @}^*) \\ \ind
@<declaration>^* \\
@<form>^*
- \nlret @<result-form>}
+ \-\nlret @<result-form>}
This is a helper to ensure that macro expansions evaluate their arguments
exactly once each, in the correct order.
true locatives, such that two locatives compare equal if and only if they
refer to the same place; but that doesn't work for these locatives.
-\begin{describe}{cls}{loc}
+\begin{describe}{cls}{locative}
The type of locative objects.
\end{describe}
-\begin{describe}{fun}{locp @<object> @> @<generalized-boolean>}
+\begin{describe}{fun}{locativep @<object> @> @<generalized-boolean>}
Return non-nil if and only if @<object> is a locative.
\end{describe}
@{ @<var> @! (@{ @<var> @!
(@<var> @[@<locative>@]) @}^*) @} \\ \ind
@<declaration>^* \\
- @<form>^*}
+ @<form>^*
+ \-\nlret @<values>^*}
This is a macro which hides the use of locatives from its caller using
symbol-macros.
An anaphoric macro implicitly binds a well-known name to a value of interest,
in the course of doing something else. The concept was popularized by Paul
-Graham \cite{FIXME:OnLisp}.
+Graham \cite{graham-1993:on-lisp}.
The macros described here all bind the variable @|it|.
The symbol @|it| is exported by the @|sod-utilities| package.
\end{describe}
-\begin{describe}{mac}{aif @<condition> @<consequent> @[@<alt>@]}
+\begin{describe}{mac}{aif @<condition> @<consequent> @[@<alt>@] @> @<value>^*}
Evaluate the @<condition>. If @<condition> is non-nil, then bind @|it| to
the resulting value and evaluate the @<consequent>, returning all of its
values. Otherwise, evaluate @<alt>, returning all of its values.
\end{describe}
-\begin{describe}{mac}{aand @<form>^*}
+\begin{describe}{mac}{aand @<form>^* @> @<value>^*}
Evaluate each @<form> in turn. If any @<form> evaluates to nil, then stop
and return nil. Each form except the first is evaluated with @|it| bound
to the (necessarily non-nil) value of the previous form. If all but the
(No @|aor| is provided, since @|it| would necessarily be bound to nil.)
-\begin{describe}{mac}{awhen @<condition> @<form>^*}
+\begin{describe}{mac}{awhen @<condition> @<form>^* @> nil}
If @<condition> evaluates to a non-nil value, bind @|it| to that value, and
evaluate the @<form>s as an implicit @|progn|. Otherwise, return nil.
\end{describe}
-\begin{describe}{mac}{acond @{ (@<condition> @<form>^*) @}^*}
+\begin{describe}{mac}{acond @{ (@<condition> @<form>^*) @}^* @> @<value>^*}
Evaluate each @<condition> in turn, until one of them produces a non-nil
value. If the @<condition> is followed by one or more @<form>s, then bind
@|it| to the non-nil value of the @<condition> and evaluate the @<form>s as
\end{describe}
\begin{describe*}
- {\dhead{mac}
- {acase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
- \dhead{mac}
- {aecase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
- \dhead{mac}{atypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}
- \dhead{mac}{aetypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}}
+ {\dhead{mac}{acase @<scrutinee>
+ @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*
+ @> @<value>^*}
+ \dhead{mac}{aecase @<scrutinee>
+ @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*
+ @> @<value>^*}
+ \dhead{mac}{atypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*
+ @> @<value>^*}
+ \dhead{mac}{aetypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*
+ @> @<value>^*}}
These are like the Common Lisp macros @|case|, @|ecase|, @|typecase|, and
@|etypecase|, except that @|it| is bound to the value of the @<scrutinee>
while evaluating the matching @<form>s.
\end{describe*}
-\begin{describe}{mac}{asetf @{ @<place> @<value> @}^*}
+\begin{describe}{mac}{asetf @{ @<place> @<value> @}^* @> @<value>^*}
For each @<place> and @<value> in turn: bind @|it| to the current value of
the @<place>, evaluate the @<value> expression, and store the resulting
- value back in the @<place>.
+ value back in the @<place>. Return the @<value>(s) stored by the final
+ pair: there may be more than one value, e.g., if @<place> is a @|values|
+ form.
For example, @|(asetf @<place> (1+ it))| is almost equivalent to @|(incf
@<place>)|, even if evaluating @<place> has side-effects.
The following utilities make use of the introspection features of the CLOS
metaobject protocol.
-\begin{describe}{gf}{instance-initargs @<instance>}
+\begin{describe}{gf}{instance-initargs @<instance> @> @<initargs-list>}
Return a fresh list of plausible initargs for the given @<instance>.
This is done by digging through the instance's class's slot definitions and
the partial order.
\end{describe}
+\begin{describe}{fun}{cross-product \&rest @<pieces>}
+ Return the cross product of the @<pieces>.
+
+ Each arguments may be a list, or a (non-nil) atom, which is equivalent to a
+ singleton list containing just that atom. Return a list of all possible
+ lists which can be constructed by taking one item from each argument list
+ in turn, in an arbitrary order.
+\end{describe}
+
\begin{describe}{fun}
{find-duplicates @<report> @<sequence> \&key :key :test}
Call @<report> on each pair of duplicate items in a @<sequence>.
and $y$ are considered equal if and only if @|(funcall @<test> (funcall
@<key> $x$) (funcall @<key> $y$))| returns non-nil.
+ The @<report> function is called as @|(funcall @<report> @<duplicate>
+ @<previous>)|. Duplicates are reported in order; the @<previous> item is
+ always the first matching item in the sequence.
+
This function will work for arbitrary @<test> functions, but it will run
- much more efficiently if @<test> is @|eq|, @|eql|, @|equal|, or @|equalp|
- (because it can use hash-tables).
+ much more efficiently if @<test> is @|eq|, @|eql|, @|equal|, or @|equalp|,
+ because it can use hash-tables. (The generic implementation for lists is
+ especially inefficient.)
\end{describe}
Dijkstra.
\end{describe}
+
+\subsection{Other exported symbols}
+
+\begin{describe}{sym}{int}
+ The symbol @|int| is exported by the @|sod-utilities| package, without
+ giving it any particular meaning. This is done because it's given
+ non-conflicting meanings by two different packages, and it's more
+ convenient for user code not to have to deal with an unnecessary symbol
+ conflict. Specifically, the @|sod| package wants to define it as a C type
+ specifier, see \descref{cls}{simple-c-type}; and @|optparse| wants to
+ define it as an option handler, see \descref{opt}{int}.
+\end{describe}
+
%%%--------------------------------------------------------------------------
\section{Option parser} \label{sec:misc.optparse}
-These symbols are defined in the @|optparse| package.
+Most of these symbols are defined in the @|optparse| package.
\begin{describe}{fun}{exit \&optional (@<code> 0) \&key :abrupt}
\end{describe}
\dhead{fun}{setf (opt-negated-tag @<option>) @<tag>}
\dhead{fun}{opt-arg-name @<option> @> @<string-or-null>}
\dhead{fun}{setf (opt-arg-name @<option>) @<string-or-null>}
- \dhead{fun}{opt-optional-p @<option> @> @<generalized-boolean>}
- \dhead{fun}{setf (opt-optional-p @<option>) @<generalized-boolean>}
+ \dhead{fun}{opt-arg-optional-p @<option> @> @<generalized-boolean>}
+ \dhead{fun}{setf (opt-arg-optional-p @<option>) @<generalized-boolean>}
\dhead{fun}{opt-documentation @<option> @> @<string-or-null>}
\dhead{fun}{setf (opt-documentation @<option>) @<string-or-null>}}
\end{describe*}
\&key :format-control :format-arguments}
\end{describe}
+\begin{describe}{fun}{option-parse-error @<msg> \&optional @<args>}
+\end{describe}
+
\begin{describe}{fun}{option-parse-remainder @<option-parser>}
\end{describe}
@<form>^*) @}^*}
\end{describe}
+\begin{describe}{fun}{sod-frontend:augment-options @<options-list>}
+\end{describe}
+
%%%--------------------------------------------------------------------------
\section{Property sets} \label{sec:misc.pset}
\begin{describe*}
{\dhead{fun}{p-name @<property> @> @<name>}
+ \dhead{meth}{property}{file-location (@<property> property) @> @<floc>}
\dhead{fun}{p-value @<property> @> @<value>}
\dhead{fun}{p-type @<property> @> @<type>}
\dhead{fun}{p-key @<property> @> @<symbol>}