3 %%% Miscellaneous functionality
5 %%% (c) 2015 Straylight/Edgeware
8 %%%----- Licensing notice ---------------------------------------------------
10 %%% This file is part of the Sensible Object Design, an object system for C.
12 %%% SOD is free software; you can redistribute it and/or modify
13 %%% it under the terms of the GNU General Public License as published by
14 %%% the Free Software Foundation; either version 2 of the License, or
15 %%% (at your option) any later version.
17 %%% SOD is distributed in the hope that it will be useful,
18 %%% but WITHOUT ANY WARRANTY; without even the implied warranty of
19 %%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 %%% GNU General Public License for more details.
22 %%% You should have received a copy of the GNU General Public License
23 %%% along with SOD; if not, write to the Free Software Foundation,
24 %%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
26 \chapter{Miscellaneous functionality
} \label{ch:misc
}
28 %%%--------------------------------------------------------------------------
29 \section{Utilities
} \label{sec:misc.utilities
}
31 These symbols are defined in the @|sod-utilities| package.
34 \subsection{Macro utilities
}
36 We begin with some simple utilities which help with writing macros. Several
37 of these are standard.
40 {with-gensyms (@
{ @<var> @! (@<var> @
[@<name>@
]) @
}^*) \\
\ind
44 Bind each @<var> (a symbol, not evaluated) to a freshly made gensym whose
45 name is based on the corresponding @<name> (a string, evaluated), and
46 evaluate the @<form>s as an implicit @|progn| in the resulting environment.
47 If @<name> is omitted, then the name of the @<var> is used as a default; a
48 bare symbol may be written in place of a singleton list.
52 {once-only (@
[[ :environment @<env> @
]]
53 @
{ @<var> @! (@<var> @
[@<value-form>@
]) @
}^*) \\
\ind
56 \-
\nlret @<result-form>
}
57 This is a helper to ensure that macro expansions evaluate their arguments
58 exactly once each, in the correct order.
60 Each @<var> is bound to an appropriate value (often a gensym) and then the
61 @<form>s are evaluated as an implicit @|progn| in the resulting environment
62 to produce an output form. This output form is then enclosed in one or
63 more binding forms to produce a @<result-form>. When the @<result-form> is
64 evaluated, the behaviour will be as if each @<value-form> is evaluated
65 exactly once each, in order, and each value is captured in the
68 A simple @|once-only| expansion might look something like
70 (let (\=(@<var>_1 (gensym)) \\
72 \>(@<var>_n (gensym))) \\
\ind
73 `(let (\=(,@<var>_1 ,@<value-form>_1) \\
75 \>(,@<var>_n ,@<value-form>_n)) \\
\ind
76 @<declaration>_1
\dots\ @<declaration>_m \\
77 @<form>_1
\dots\ @<form>_
\ell))
79 However, if @|once-only| can determine that some @<value-form> is a
80 constant (e.g., it is @|quote|d, self-evaluating, or reported as
81 @|constantp| in the given environment @<env>), then it need not allocate a
82 gensym: it can instead bind the @<var> directly to the constant value.
84 If a @<value-form> is omitted, then the value of the corresponding @<var>
85 is used. It is conventional usage for a macro to wrap @|once-only| around
86 its body so as to convert the arguments which it should evaluate into safe
87 gensyms capturing their runtime values. (Not that the simple expansion
88 given above can't do this correctly.) A bare symbol may be written in
89 place of a singleton list.
93 {parse-body @<body> \&key :docp :declp
94 @> @<doc-string> @<declarations> @<body-forms>
}
95 Parse the @<body> into a @<doc-string>, some @<declaration>s, and a list of
98 The @<body> is assumed to have the general syntax
100 @
[[ @<doc-string> @! @<declaration>^* @
]] \\
103 A @<doc-string> is permitted if and only if @<docp> is non-nil, and
104 declarations are permitted if and only if @<declp> is non-nil; both are
107 Each return value is a list, which is empty if the corresponding part of
108 the input @<body> is missing. Specifically:
110 \item @<doc-string> is either nil, or a singleton list containing a string;
111 \item @<declarations> is either nil, or a singleton list containing a
112 @|(declare
\dots)| form gathering up all of the individual
113 @<declaration>s within the @<body>; and
114 \item @<body-forms> is a list of the remaining forms in the @<body>.
116 Thus, the parsed body-parts can conveniently be spliced into a macro
117 expansion using @|,@@|.
120 \begin{describe
}{fun
}{symbolicate \&rest @<symbols> @> @<symbol>
}
121 Return the symbol, interned in the current @|*package*|, whose name is the
122 concatenation of the names of the given @<symbols>.
126 \subsection{Locatives
}
128 A
\emph{locative
} is a value which remembers where another value is stored,
129 -- whether it's in a variable, an array element, a structure slot, a hash
130 table, etc.\ -- and can modify and retrieve it.
132 Some Lisp systems have highly efficient locatives which actually keep track
133 of the machine addresses of the places to which they refer. Common Lisp does
134 not implement true locatives of this kind, but something sufficiently useful
137 These locatives can't usefully be compared. It should be possible to compare
138 true locatives, such that two locatives compare equal if and only if they
139 refer to the same place; but that doesn't work for these locatives.
141 \begin{describe
}{cls
}{locative
}
142 The type of locative objects.
145 \begin{describe
}{fun
}{locativep @<object> @> @<generalized-boolean>
}
146 Return non-nil if and only if @<object> is a locative.
149 \begin{describe
}{mac
}{locf @<place> @> @<locative>
}
150 Return a fresh locative capturing the @<place>, which may be any expression
151 usable as the first operand to @|setf|.
155 {\dhead{fun
}{ref @<locative> @> @<value>
}
156 \dhead{fun
}{setf (ref @<locative>) @<value>
}}
157 Retrieve and return the current value stored in the place captured by the
158 @<locative>. With @|setf|, store the new @<value> in the place captured by
162 \begin{describe
}{mac
}
164 @
{ @<var> @! (@
{ @<var> @!
165 (@<var> @
[@<locative>@
]) @
}^*) @
} \\
\ind
168 \-
\nlret @<values>^*
}
169 This is a macro which hides the use of locatives from its caller using
172 Each @<locative> should be an expression which evaluates to a locative
173 value (not a general place). These are evaluated once each, left to
174 right. The @<form>s are then evaluated as an implicit @|progn|, with each
175 @<var> defined as a symbol macro which will retrieve -- or, with @|setf|,
176 modify -- the value referred to by the corresponding locative.
178 If a @<locative> is omitted, it defaults to the value of @<var>; a
179 bare symbol may be used in place of a singleton list.
183 \subsection{Anaphorics
}
185 An anaphoric macro implicitly binds a well-known name to a value of interest,
186 in the course of doing something else. The concept was popularized by Paul
187 Graham
\cite{graham-
1993:on-lisp
}.
189 The macros described here all bind the variable @|it|.
191 \begin{describe
}{sym
}{it
}
192 The symbol @|it| is exported by the @|sod-utilities| package.
195 \begin{describe
}{mac
}{aif @<condition> @<consequent> @
[@<alt>@
] @> @<value>^*
}
196 Evaluate the @<condition>. If @<condition> is non-nil, then bind @|it| to
197 the resulting value and evaluate the @<consequent>, returning all of its
198 values. Otherwise, evaluate @<alt>, returning all of its values.
201 \begin{describe
}{mac
}{aand @<form>^* @> @<value>^*
}
202 Evaluate each @<form> in turn. If any @<form> evaluates to nil, then stop
203 and return nil. Each form except the first is evaluated with @|it| bound
204 to the (necessarily non-nil) value of the previous form. If all but the
205 last form evaluate non-nil, then return all the values of the final form.
208 (No @|aor| is provided, since @|it| would necessarily be bound to nil.)
210 \begin{describe
}{mac
}{awhen @<condition> @<form>^* @> nil
}
211 If @<condition> evaluates to a non-nil value, bind @|it| to that value, and
212 evaluate the @<form>s as an implicit @|progn|. Otherwise, return nil.
215 \begin{describe
}{mac
}{acond @
{ (@<condition> @<form>^*) @
}^* @> @<value>^*
}
216 Evaluate each @<condition> in turn, until one of them produces a non-nil
217 value. If the @<condition> is followed by one or more @<form>s, then bind
218 @|it| to the non-nil value of the @<condition> and evaluate the @<form>s as
219 an implicit @|progn|; otherwise, simply return the value of the
220 @<condition>. If no @<condition> produces a non-nil value then return nil.
224 {\dhead{mac
}{acase @<scrutinee>
225 @
{ (@
{ @<case> @! (@<case>^*) @
} @<form>^*) @
}^*
227 \dhead{mac
}{aecase @<scrutinee>
228 @
{ (@
{ @<case> @! (@<case>^*) @
} @<form>^*) @
}^*
230 \dhead{mac
}{atypecase @<scrutinee> @
{ (@<type> @<form>^*) @
}^*
232 \dhead{mac
}{aetypecase @<scrutinee> @
{ (@<type> @<form>^*) @
}^*
234 These are like the Common Lisp macros @|case|, @|ecase|, @|typecase|, and
235 @|etypecase|, except that @|it| is bound to the value of the @<scrutinee>
236 while evaluating the matching @<form>s.
239 \begin{describe
}{mac
}{asetf @
{ @<place> @<value> @
}^* @> @<value>^*
}
240 For each @<place> and @<value> in turn: bind @|it| to the current value of
241 the @<place>, evaluate the @<value> expression, and store the resulting
242 value back in the @<place>. Return the @<value>(s) stored by the final
243 pair: there may be more than one value, e.g., if @<place> is a @|values|
246 For example, @|(asetf @<place> (
1+ it))| is almost equivalent to @|(incf
247 @<place>)|, even if evaluating @<place> has side-effects.
251 \subsection{Metaobject protocol utilities
}
253 The following utilities make use of the introspection features of the CLOS
256 \begin{describe
}{gf
}{instance-initargs @<instance> @> @<initargs-list>
}
257 Return a fresh list of plausible initargs for the given @<instance>.
259 The default method should work for most classes, but may be overridden to
260 cope with special effects.
262 \begin{describe
}{meth
}{standard-object
}
263 {instance-initargs (@<instance> standard-object) @> @<initargs-list>
}
264 The default method works by digging through the instance's class's slot
265 definitions and enquiring about their initargs. Initargs which are
266 handled by methods on @|shared-initialize| or similar generic functions
272 {\dhead{fun
}{copy-instance @<instance> \&rest @<initargs>
274 \dhead{gf
}{copy-instance-using-class @<class> @<instance>
277 The @|copy-instance| function creates and returns a fresh copy of a given
278 @<instance>, possibly modifying it according to the given @<initargs>.
280 It immediately calls @|copy-instance-using-class|, calling it with the
281 instance's class and the instance itself, and simply returns the result of
282 that generic function.
284 The default method on @|copy-instance-using-class| should work for most
285 classes, but may be overridden to cope with special effects.
287 \begin{describe
}{meth
}{standard-class
}
288 {copy-instance-using-class \=(@<class> standard-class) @<instance> \\
290 \nlret @<new-instance>
}
291 The default method works as follows.
293 \item Allocate a fresh instance of @<class>, using @|allocate-instance|.
294 \item For each slot defined by @<class>, if that slot is bound in the
295 original instance, then set the corresponding slot in the new instance
297 \item Call @|shared-initialize| on the new instance, providing it the
298 given list of @<initargs>, but inhibiting the usual initialization of
299 slots from their initforms.
300 \item Return the new instance.
306 {\dhead{gf
}{generic-function-methods @<generic-function> @> @<list>
}
307 \dhead{gf
}{method-specializers @<method> @> @<list>
}
308 \dhead{cls
}{eql-specializer
}
309 \dhead{gf
}{eql-specializer-object @<specializer> @> @<value>
}}
310 These are precisely the MOP functions and class: the symbols are
311 re-exported for portability, because different Lisp systems define these
312 symbols in different packages.
316 \subsection{Other CLOS utilities
}
318 Some other minor CLOS utilities.
320 \begin{describe
}{mac
}
321 {default-slot (@<instance> @<slot> @
[@<slot-names>@
]) \\
\ind
323 This macro is useful in methods (usually @|:after| methods) on
324 @|shared-initialize|, to set slots to some sensible default values in the
325 case where no suitable initarg was given, and default initialization is too
326 complicated to be done using an initform.
328 Set a slot to a default value, obeying the @|shared-initialize| protocol.
329 If (a) the named @<slot> of @<instance> is unbound, and (b) either
330 @<slot-names> is @|t|, or @<slot> is a member of the list @<slot-names>,
331 then evaluate the @<form>s as an implicit @|progn| and store their
332 value in the @<slot>. Otherwise do nothing.
334 The @<instance>, @<slot>, and @<slot-names> (if any) are evaluated once
338 \begin{describe
}{mac
}
339 {define-on-demand-slot @<class> @<slot> (@<instance>) \\
\ind
340 @
[[ @<declaration>^* @! @<doc-string> @
]] \\
342 This macro makes slots with delayed initialization: rather than being
343 set when the object is constructed, the slot's initial value is only
344 calculated when it's first requested. This is useful if calculating the
345 slot value is expensive and often not required, or if it's not possible to
346 initialize the slot along with the rest of the object because of dependency
349 The macro arranges things as follows. Whenever @|slot-value| is called
350 (possibly indirectly, via a reader function) to read the named @<slot> (a
351 symbol, not evaluated) on an (indirect) instance of @<class>, but the slot
352 is unbound, then @<instance> is bound to the instance in question and the
353 @<form>s are evaluated as an implicit @|progn| within the lexical
354 environment of the @|define-on-demand-slot| call, and the resulting value
355 is used as the initial value of the slot. (Furthermore, a block named
356 @<slot> is wrapped around the @<form>s, allowing an early return if that
359 This macro currently works by defining a method on @|slot-unbound|.
363 \subsection{Building lists
}
365 Many Lisp functions end up constructing lists. In simple cases, a function
366 like @|mapcar| will just do the job directly. In more complex cases, a
367 common idiom is to build the list using @|push| for each element in turn; but
368 a list built this way ends up in the wrong order, so an additional pass,
369 usually using @|nreverse|, is necessary to fix it.
371 A `list builder' is an object which can be used to construct a list in the
372 right order. (Currently, a list-builder is simply a cons cell, whose cdr
373 points to the first cons-cell of the list, and whose car points to its last
374 cons; an empty list-builder is a cons whose cdr is nil and whose car is the
375 cons itself, i.e., @|\
#1=(\
#1\# . nil)|.)
377 \begin{describe
}{fun
}{make-list-builder \&optional @<initial> @> @<builder>
}
378 Return a fresh new list-builder, initially containing no items.
381 \begin{describe
}{fun
}{lbuild-add @<builder> @<item> @> @<builder>
}
382 Add @<item> to the end of the list being constructed in @<builder>.
385 \begin{describe
}{fun
}{lbuild-add-list @<builder> @<list> @> @<builder>
}
386 Append @<list> to the list being constructed in @<builder>. The list is
387 \emph{not
} copied: adding further items to the list will clobber cdr of its
391 \begin{describe
}{fun
}{lbuild-list @<builder> @> @<list>
}
392 Return the list being constructed in the @<builder>.
394 It is permitted to continue adding items to the list: this will mutate the
395 list in-place. Often, this is what you want. For example, one might write
396 an analogue to @|pushnew| like this:
398 (defun lbuild-add-new
399 (builder item \&key key test test-not \&rest keywords) \\
\ind
400 (declare (ignore key test test-not)) \\
401 (when (apply \#'member item (lbuild-list builder)
403 (lbuild-add builder item)))
408 \subsection{Merging lists
}
410 The following machinery merges lists representing a partial order. The
411 primary use for this is in computing class precedence lists during class
412 finalization. By building the input lists and choosing the tie-breaking
413 @<pick> function appropriately, many different linearization algorithms can
414 be implemented fairly easily using @|merge-lists| below.
418 {inconsistent-merge-error (error) \&key :candidates :present
}
419 \dhead{gf
}{merge-error-candidates @<error> @> @<list>
}
420 \dhead{gf
}{merge-error-present-function @<error> @> @<function>
}}
421 The @|inconsistent-merge-error| condition class used to represent a failure
422 of the
\descref{fun
}{merge-lists
}[function
].
424 The @<candidates> are a list of offending items from the input lists, in
425 some order: the error is reporting that the function has failed because it
426 is not possible to order the items listed in @<candidates> in any way
427 without being inconsistent with at least one of the input lists. There is
430 The @<present> function is used to convert the input items into
431 human-readable descriptions (printed using @|princ|); the default is
432 @|identity|, which will simply print the items in a `friendly' format.
433 (Using @|prin1-to-string| would print their machine-readable escaped forms
436 The functions @|merge-error-candidates| and @|merge-error-present-function|
437 respectively retrieve the candidates list and presentation function
438 assigned to a condition when it was created.
441 \begin{describe
}{fun
}
442 {merge-lists @<lists> \&key :pick :test :present @> @<list>
}
443 Return a merge of the @<lists>, considered as partial orderings.
445 In more detail: @<lists> should be a list of lists. Each distinct item, as
446 determined by the @<test> function (by default, @|eql|) appears in the
447 result list exactly once. Furthermore, if, in some input list, an item $x$
448 appears earlier than a different item $y$, then $x$ will also precede $y$
451 If the input lists contradict each other (e.g., list $A$ has $x$ before
452 $y$, but list $B$ has $y$ before $x$), then an error of type
453 @|inconsistent-merge-error| is signalled, with the offending items attached
454 as candidates, and the function @<present> (by default, @|identity|) as the
455 presentation function.
457 Frequently, a collection of input lists has multiple valid merges.
458 Whenever @|merge-lists| must decide between two or more equally good
459 candidates, it calls the @<pick> function to choose one of them.
460 Specifically, it invokes @|(funcall @<pick> @<candidates>
461 @<merge-so-far>)|, where @<candidates> are the items it needs to choose
462 between, and @<merge-so-far> is the currently determined prefix of the
463 final merge. The order of items in the @<candidates> list reflects their
464 order in the input lists: item $x$ precedes item $y$ in @<candidates> if
465 any only if an occurrence of $x$ appears in an earlier input list than
466 $y$. (This completely determines the order of candidates: if two items
467 appear in the same list, then that list would have ordered them and we
468 wouldn't have to call @<pick> to break the tie.) The default @<pick>
469 function simply chooses the item appearing in the earliest list, i.e.,
472 (lambda (candidates merge-so-far) \\
\ind
473 (declare (ignore merge-so-far)) \\
479 \subsection{Other list utilities
}
481 \begin{describe
}{fun
}
482 {mappend @<function> @<list> \&rest @<more-lists> @> @<result-list>
}
483 Return the result of appending @<list> and @<more-lists>, in order. All
484 but the final list are copied into the @<result-list>; the last one is used
488 \begin{describe
}{mac
}
489 {categorize (\=@<item-var> @<items>
490 @
[[ :bind (@
{ @<var> @!
491 (@<var> @
[@<value>@
]) @
}^*) @
]])
493 (@
{ (@<cat-var> @<cat-predicate>) @
}^*) \-\\
497 Partition an input list of @<items> according to the @<cat-predicate>s.
499 First, @<items> is evaluated, to yield a list. The @<item-var> is bound,
500 an empty list is created for each @|(@<cat-var> @<cat-predicate>)| pair,
501 and an iteration is begun. For each item in the list in turn is assigned
502 to @<item-var>; then, the bindings given by the @|:bind| keyword are
503 performed, as if by @|let*|; and the @<cat-predicate>s are evaluated in the
504 resulting environment, one by one, until one of them returns non-nil. When
505 this happens, the item is added to the corresponding list. If no predicate
506 matches the item, an error is signalled.
508 Once this iteration is complete, each @<cat-var> is bound to its
509 corresponding completed list, and the body @<form>s are evaluated in the
510 resulting environment (which does not include @<item-var>), as an implicit
511 @|progn|, and the macro yields the values of the final @<form>.
514 \begin{describe
}{fun
}{partial-order-minima @<items> @<order> @> @<list>
}
515 Return a list of minimal items from the list @<items> according to a
516 non-strict partial order defined by the function @<order>: @|(funcall
517 @<order> $x$ $y$)| should return non-nil if and only if $x
\preceq y$ in
521 \begin{describe
}{fun
}{cross-product \&rest @<pieces>
}
522 Return the cross product of the @<pieces>.
524 Each arguments may be a list, or a (non-nil) atom, which is equivalent to a
525 singleton list containing just that atom. Return a list of all possible
526 lists which can be constructed by taking one item from each argument list
527 in turn, in an arbitrary order.
530 \begin{describe
}{fun
}
531 {find-duplicates @<
report> @<sequence> \&key :key :test
}
532 Call @<
report> on each pair of duplicate items in a @<sequence>.
533 Duplicates are determined according to the @<key> (by default @|identity|)
534 and @<test> (by default @|eql|) functions, in the usual way: two items $x$
535 and $y$ are considered equal if and only if @|(funcall @<test> (funcall
536 @<key> $x$) (funcall @<key> $y$))| returns non-nil.
538 The @<
report> function is called as @|(funcall @<
report> @<duplicate>
539 @<previous>)|. Duplicates are reported in order; the @<previous> item is
540 always the first matching item in the sequence.
542 This function will work for arbitrary @<test> functions, but it will run
543 much more efficiently if @<test> is @|eq|, @|eql|, @|equal|, or @|equalp|,
544 because it can use hash-tables. (The generic implementation for lists is
545 especially inefficient.)
549 \subsection{Position tracking
}
551 The following functions are used to maintain file positions: see
552 \xref{sec:parsing.floc
}. Columns are counted starting from zero at the far
553 left. (No particular origin is needed for line numbers.) Newlines, vertical
554 tabs, and form-feeds all move to the start of the next line; horizontal tabs
555 move to the next multiple of eight columns; other characters simply advance
558 \begin{describe
}{fun
}
559 {update-position @<character> @<line> @<column>
560 @> @<new-line> @<new-column>
}
561 Assume that we found @<character> at a particular @<line> and @<column> in
562 a file: return the @<new-line> and @<new-column> for the next character.
565 \begin{describe
}{fun
}
566 {backtrack-position @<character> @<line> @<column>
567 @> @<old-line> @<old-column>
}
568 Assume that we are currently at a particular @<line> and @<column> in a
569 file, and wish to
\emph{unread
} @<character>: return an @<old-line> and
570 @<old-column> at which we might plausibly re-read the character, so that
571 the next call to
\descref{fun
}{update-position
} will return us to @<line>
572 and @<column>. (Specifically, the @<old-column> will likely be wrong if
573 @<character> is a horizontal tab. It is expected that this won't matter:
574 the purpose of this function is to set things up so that the
575 @|update-position| call that will accompany re-reading the character will
576 return the correct values, rather than to use the @<old-line> and
577 @<old-column> for any other purpose.)
581 \subsection{Object printing
}
583 \begin{describe
}{mac
}
584 {maybe-print-unreadable-object
587 :identity @<identity> @
]]) \\
\ind
590 If @|*print-escape*| is nil, then simply evaluate the @<form>s as an
591 implicit @|progn|; otherwise, print an `unreadable' object, as if by
593 (print-unreadable-object
596 @
[:identity @<identity>@
]) \\
\ind
601 \begin{describe
}{fun
}{print-ugly-stuff @<stream> @<func> @> @<value>^*
}
602 If @<stream> is a pretty-printing stream, then print a mandatory newline,
603 and call @<func> on the underlying non-pretty-printing stream. If
604 @<stream> is not a pretty-printing stream, then simply call @<func> on
607 The main purpose for this is to be able to access features of the
608 underlying stream which a pretty-printing stream can't proxy. Most
609 notably, this is used by C fragment output, which takes advantage of an
610 underlying
\descref{cls
}{position-aware-output-stream
} to print @|\#line|
611 directives, so that a C~compiler will blame the original fragment in the
612 Sod module source rather than the generated C code.
616 \subsection{Condition utilities
}
618 The following definitions are useful when working with conditions.
620 \begin{describe
}{cls
}
621 {simple-control-error (control-error simple-error)
622 \&key :format-control :format-arguments
}
623 This is the obvious multiply-inherited subclass of @|control-error| whose
624 print form is determined by a @<format-control> and a @<format-arguments>
628 \begin{describe
}{fun
}
629 {designated-condition
630 \=@<default-type> @<datum> @<arguments> \\
631 \>\&key :allow-pointless-arguments
633 Creates and returns a condition object of @<default-type>, given a
634 condition designator @<datum> and @<arguments>.
636 The Common Lisp specification carefully explains how a `datum' and an
637 argument list together form a `condition designator', and how such a pair
638 are to be converted into a condition object with some default type, but
639 there's no mechanism provided to simply do this task. (Functions like
640 @|error| and @|signal| implicitly, but have possibly-undesirable
641 side-effects, and don't allow control over the default type.)
645 \item If @<datum> is a condition object, then the designated condition is
646 simply @<datum>. In this case, if @<arguments> is not an empty list and
647 @<allow-pointless-arguments> is nil (the default), an error is signalled;
648 otherwise, the @<arguments> are ignored.
650 \item If @<datum> is a symbol, then the designated condition is constructed
653 (apply \#'make-condition @<datum> @<arguments>)
656 \item If @<datum> is a string or function (i.e., a `format-control'), then
657 the designated condition is constructed by calling
659 (make-condition \=@<default-type> \\
660 \>:format-control @<datum> \\
661 \>:format-arguments @<arguments>)
664 \item Otherwise the designator is malformed, and an error is signalled.
668 \begin{describe
}{fun
}
669 {invoke-associated-restart @<restart> @<condition> \&rest @<arguments>
}
670 Invoke the active restart named @<restart>, associated with the given
671 @<condition>, passing a list of @<arguments>.
673 The function attempts to find and invoke a restart with the given name. If
674 @<condition> is non-nil, then it searches among restarts associated with
675 that specific condition, and restarts associated with no condition; if
676 @<condition> is nil, then it searches among all restarts.
678 If a matching restart is found, it is invoked, passing the @<arguments>
679 list. Otherwise, an error (of class @|control-error|) is signalled.
683 {\dhead{cls
}{enclosing-condition (condition) \&key :condition
}
684 \dhead{gf
}{enclosed-condition @<enclosing-condition> @> @<condition>
}}
685 An @|enclosing condition| is a condition which contains another condition
686 within it. Objects of type @|enclosing-condition| are used to add
687 additional information to an existing condition, or to alter the type of a
688 condition without losing information.
690 When an @|enclosing-condition| is constructed, the @<condition> argument
691 names the existing condition to be enclosed. This enclosed condition can
692 be retrieved by calling @|enclosed-condition|.
695 \begin{describe
}{cls
}{information (condition) \&key
}
696 A condition of class @|information| conveys information which might be of
697 interest, but does not of itself indicate that anything is wrong.
699 Within a compiler, @|information| conditions may be signalled in order to
700 present the user with additional diagnostic information about a recently
704 \begin{describe
}{cls
}
705 {simple-information (simple-condition information) \\
\ind
706 \&key :format-control :format-arguments
}
707 This is the obvious multiply-inherited subclass of @|information|
708 whose print-representation is determined by a @<format-control> and a
709 @<format-arguments> list.
713 {\dhead{fun
}{info @<datum> \&rest @<arguments> @> @<flag>
}
715 \dhead{fun
}{noted \&optional @<condition>
}}
716 The @|info| function establishes a restart named @|noted| and signals a
717 condition of default type @|simple-information|, designated by the @<datum>
718 and @<arguments>. The @|info| function returns non-nil if and only if the
719 associated @|noted| restart was invoked.
721 The @|noted| restart accepts no arguments.
723 The @|noted| function finds and invokes a @|noted| restart: if @<condition>
724 is non-nil, then only the restart associated with that condition (and those
725 not associated with any condition) are considered; otherwise, all
726 conditions are considered.
729 \begin{describe
}{fun
}
730 {promiscuous-cerror @<continue-string> @<datum> \&rest @<arguments>
}
731 Establish a @|continue| restart and signal an error of default type
732 @|simple-error|, designated by @<datum> and @<arguments>. The restart's
733 report format is determined by @<continue-string> and the @<arguments>.
735 Some implementations of @|cerror| associate the @|continue| restart which
736 they establish with the condition they signal. This interferes with
737 special effects -- specifically, enclosing the signalled condition and
738 resignalling it. The @|promiscuous-cerror| function carefully avoids
739 associating its restart with the condition.
742 \begin{describe
}{fun
}{cerror* @<datum> \&rest @<arguments>
}
743 A simplified version of
\descref{fun
}{promiscuous-cerror
} which uses the
744 hardcoded string @|Continue| for the restart. This makes calling the
745 function more similar to other condition-signalling functions, at the
746 expense of some usability in environments which don't continue after
747 continuable errors automatically.
751 \subsection{Very miscellaneous utilities
}
753 \begin{describe
}{fun
}
754 {whitespace-char-p @<character> @> @<generalized-boolean>
}
755 Return non-nil if and only if @<character> is a whitespace character.
757 A character is whitespace if @|(peek-char t @<stream>)| would skip it.
760 \begin{describe
}{fun
}
761 {frob-identifier @<string> \&key :swap-case :swap-hyphen
762 @> @<frobbed-string>
}
763 Return a `frobbed' version of the identifier @<string>. Two different
764 transformations can be applied.
768 \item If @<swap-case> is non-nil (the default), and the letters in
769 @<string> are either all uppercase or all lowercase, then switch the case
770 of all of the letters.
772 \item If @<swap-hyphen> is non-nil (the default), and @<string> contains
773 either hyphens @`--' or underscores @`_', but not both, then replace the
774 hyphens by underscores or
\emph{vice-versa
}.
778 (These are the `obvious' transformations to convert a C identifier into a
783 \item @|(frob-identifier "foo")| $
\Longrightarrow$ @|"FOO"|
784 \item @|(frob-identifier "FOO")| $
\Longrightarrow$ @|"foo"|
785 \item @|(frob-identifier "FooBar")| $
\Longrightarrow$ @|"FooBar"|
786 \item @|(frob-identifier "Foo-Bar")| $
\Longrightarrow$ @|"Foo_Bar"|
787 \item @|(frob-identifier "Foo_Bar")| $
\Longrightarrow$ @|"Foo-Bar"|
788 \item @|(frob-identifier "foo_bar")| $
\Longrightarrow$ @|"FOO-BAR"|
789 \item @|(frob-identifier "foo_bar" :swap-hyphen nil)| $
\Longrightarrow$
791 \item @|(frob-identifier "foo_bar" :swap-case nil)| $
\Longrightarrow$
793 \item @|(frob-identifier "foo_bar" :swap-case nil :swap-hyphen nil)|
794 $
\Longrightarrow$ @|"foo_bar"|
798 \begin{describe
}{fun
}
799 {compose @<functions> @> @<function>
}
800 Return the left-to-right composition zero or more @<functions>.
802 Let $f_1$, $f_2$,
\ldots, $f_n$ be functions, and let $g = @|(compose $f_1$
803 $f_2$ $
\cdots$ $f_n$)|$ is their composition. If $g$ is applied to
804 arguments, the effect is as follows: first, $f_1$ is applied to the
805 arguments, yielding some value; $f_2$ is applied to this value, yielding a
806 second value; and so on, until finally the value yielded by $f_n$ is
807 returned as the result of $g$. Note that this is the reverse of the usual
808 mathematician's convention, but the author finds this ordering
809 significantly easier to work with:
810 \
[ g = f_n
\circ \cdots \circ f_2
\circ f_1 \
]
812 If any of the input functions return multiple values then
\emph{all
} of the
813 values are passed on to the next function in the list. (If the last
814 function returns multiple values then all of the values are returned from
817 The result of composing no functions is a function which simply returns all
818 of its arguments as values; essentially, $@|(compose)|
\equiv
822 \begin{describe
}{mac
}{defvar-unbound @<name> @<documentation> @> @<name>
}
823 Define a variable called @<name>, with a @<documentation> string.
825 The Common Lisp @|defvar| macro accepts both an initial value and a
826 doc-string as optional arguments, in that order, with the result that it's
827 not possible to define a variable and establish a documentation string for
828 it without also giving it an initial value. The @|defvar-unbound| macro,
829 on the other hand, never changes the symbol's variable-value.
832 \begin{describe
}{mac
}
833 {dosequence (@<var> @<sequence>
834 @
[[ :start @<start> @! :end @<end> @!
835 :indexvar @<index-var> @
]]) \\
\ind
837 @
{ @<tag> @! @<statement> @
}^*
}
838 Iterate over a @<sequence>. Common Lisp has a rich collection of iteration
839 primitives, and a rich collection of functions for working with sequences,
840 but no macro for iterating over the items of a sequence.
842 First, the @<sequence> is evaluated. If @<start> and/or @<end> are
843 provided, they are also evaluated (in that order), which should produce
844 integers; @<end> may be also be nil. If not provided, or nil (in the case
845 of @<end>), @<start> and @<end> default respectively to zero and the length
846 of the @<sequence>. For each item in the sequence between the @<start> and
847 @<end> positions (i.e., each item in @|(subseq @<sequence> @<start>
848 @<end>)|, in order, the body is evaluated as an implicit @|tagbody|, with
849 @<var> bound to the item and, if provided, @<index-var> bound to the item's
850 index. It is not specified whether the @<var> and @<index-var> are
851 let-bound or mutated in each iteration.
853 Unlike other Common Lisp @|do|
\dots\ forms, there is no `result' form.
856 \begin{describe
}{mac
}
857 {define-access-wrapper @<from> @<to>
858 @
[[ :read-only @<read-only-flag> @
]]}
859 Define @<from> as a function of one argument, so that @|(@<from> @<thing>)|
860 is equivalent to @|(@<to> @<thing>)|. If @<read-only-flag> is nil (the
861 default), then also define @|(setf @<from>)| so that @|(setf (@<from>
862 @<thing>) @<value>)| is equivalent to @|(setf (@<to> @<thing>) @<value>)|.
864 In a @|defstruct| form, the accessor function names are constructed based
865 on the structure name and slot names. The structure name and accessor
866 names are part of the exported interface, but the slot names ideally
867 shouldn't be. This causes a problem when the slot name which will lead to
868 the right accessor is already an external symbol in some package. You can
869 solve this problem by choosing an internal name for the symbol, and then
870 using this macro to define an accessor function with the name that you
871 want, in terms of the accessor that @|defstruct| made.
874 \begin{describe
}{fun
}
875 {distinguished-point-shortest-paths @<root> @<neighbours-func>
877 Calculate the shortest path from the @<root> to each node reachable from it
878 in a directed graph. The nodes of the graph can be any kind of object;
879 they will be compared using @|eql|.
881 The @<neighbours-func> should be a function which, given a node~$v$ as its
882 only argument, returns a list of cons cells @|($v'$ . $c'$)|, one for each
883 node~$v'$ adjacent to $v$, indicating the cost $c'$ of traversing the arc
886 The return value is a list of cons cells @|($c$ . $p$)|, where $p$ is list
887 of nodes, in reverse order, along a path from the @<root> to some other
888 node, and $c$ is the total cost of traversing this path. (Therefore @|(car
889 $p$)| is the destination node, and @|(car (last $p$))| is always the
892 The function runs in $O(n^
2)$ time, where $n$ is the number of nodes
893 reachable from the @<root>. Currently, it uses an algorithm due to Edsger
898 \subsection{Other exported symbols
}
900 \begin{describe
}{sym
}{int
}
901 The symbol @|int| is exported by the @|sod-utilities| package, without
902 giving it any particular meaning. This is done because it's given
903 non-conflicting meanings by two different packages, and it's more
904 convenient for user code not to have to deal with an unnecessary symbol
905 conflict. Specifically, the @|sod| package wants to define it as a C type
906 specifier, see
\descref{cls
}{simple-c-type
}; and @|optparse| wants to
907 define it as an option handler, see
\descref{opt
}{int
}.
910 %%%--------------------------------------------------------------------------
911 \section{Option parser
} \label{sec:misc.optparse
}
913 Most of these symbols are defined in the @|optparse| package.
915 \begin{describe
}{fun
}{exit \&optional (@<code>
0) \&key :abrupt
}
918 \begin{describe
}{var
}{*program-name*
}
921 \begin{describe
}{var
}{*command-line*
}
924 \begin{describe
}{fun
}{set-command-line-arguments
}
927 \begin{describe
}{fun
}{moan @<format-string> \&rest @<format-args>
}
930 \begin{describe
}{fun
}{die @<format-string> \&rest @<format-args>
}
933 \begin{describe
}{var
}{*options*
}
936 \begin{describe
}{cls
}{option
}
939 \begin{describe
}{fun
}{optionp @<object> @> @<generalized-boolean>
}
942 \begin{describe
}{fun
}
943 {make-option \=@<long-name> @<short-name> \+\\
944 \&optional @<arg-name> \\
945 \&key :tag :negated-tag
946 :arg-optional-p :documentation \-
951 {\dhead{fun
}{opt-short-name @<option> @> @<character-or-null>
}
952 \dhead{fun
}{setf (opt-short-name @<option>) @<character-or-null>
}
953 \dhead{fun
}{opt-long-name @<option> @> @<string-or-null>
}
954 \dhead{fun
}{setf (opt-long-name @<option>) @<string-or-null>
}
955 \dhead{fun
}{opt-tag @<option> @> @<tag>
}
956 \dhead{fun
}{setf (opt-tag @<option>) @<tag>
}
957 \dhead{fun
}{opt-negated-tag @<option> @> @<tag>
}
958 \dhead{fun
}{setf (opt-negated-tag @<option>) @<tag>
}
959 \dhead{fun
}{opt-arg-name @<option> @> @<string-or-null>
}
960 \dhead{fun
}{setf (opt-arg-name @<option>) @<string-or-null>
}
961 \dhead{fun
}{opt-arg-optional-p @<option> @> @<generalized-boolean>
}
962 \dhead{fun
}{setf (opt-arg-optional-p @<option>) @<generalized-boolean>
}
963 \dhead{fun
}{opt-documentation @<option> @> @<string-or-null>
}
964 \dhead{fun
}{setf (opt-documentation @<option>) @<string-or-null>
}}
967 \begin{describe
}{cls
}{option-parser
}
970 \begin{describe
}{fun
}{option-parser-p @<object> @> @<generalized-boolean>
}
973 \begin{describe
}{fun
}
974 {make-option-parser \&key \=:args :options :non-option :numericp \+ \\
975 :negated-numeric-p long-only-p \-
976 \nlret @<option-parser>
}
980 {\dhead{fun
}{op-options @<option-parser> @> @<list>
}
981 \dhead{fun
}{setf (op-options @<option-parser>) @<list>
}
982 \dhead{fun
}{op-non-option @<option-parser> @> @<action>
}
983 \dhead{fun
}{setf (op-non-option @<option-parser>) @<action>
}
984 \dhead{fun
}{op-long-only-p @<option-parser> @> @<generalized-boolean>
}
985 \dhead{fun
}{setf (op-long-only-p @<option-parser>) @<generalized-boolean>
}
986 \dhead{fun
}{op-numeric-p @<option-parser> @> @<generalized-boolean>
}
987 \dhead{fun
}{setf (op-numeric-p @<option-parser>) @<generalized-boolean>
}
988 \dhead{fun
}{op-negated-numeric-p @<option-parser> @<generalized-boolean>
}
989 \dhead{fun
}{setf (op-negated-numeric-p @<option-parser>) @<generalized-boolean>
}
990 \dhead{fun
}{op-negated-p @<option-parser> @> @<generalized-boolean>
}
991 \dhead{fun
}{setf (op-negated-p @<option-parser>) @<generalized-boolean>
}}
994 \begin{describe
}{cls
}
995 {option-parse-error (error simple-condition)
996 \&key :format-control :format-arguments
}
999 \begin{describe
}{fun
}{option-parse-error @<msg> \&optional @<args>
}
1002 \begin{describe
}{fun
}{option-parse-remainder @<option-parser>
}
1005 \begin{describe
}{fun
}{option-parse-return @<tag> \&optional @<argument>
}
1008 \begin{describe
}{fun
}{option-parse-next @<option-parser>
}
1011 \begin{describe
}{mac
}{option-parse-try @<form>^*
}
1014 \begin{describe
}{mac
}{with-unix-error-reporting () @<form>^*
}
1017 \begin{describe
}{mac
}
1018 {defopthandler @<name> (@<var> @
[@<arg>@
]) @<lambda-list> \\
\ind
1019 @
[[ @<declaration>^* @! @<doc-string> @
]] \\
1023 \begin{describe
}{fun
}
1024 {invoke-option-handler @<handler> @<locative> @<arg> @<arguments>
}
1027 \begin{describe
}{opt
}{set \&optional @<value>
}
1030 \begin{describe
}{opt
}{clear \&optional @<value>
}
1033 \begin{describe
}{opt
}{inc \&optional @<maximum> @<step>
}
1036 \begin{describe
}{opt
}{dec \&optional @<minimum> @<step>
}
1039 \begin{describe
}{opt
}{read
}
1042 \begin{describe
}{opt
}{int \&key :radix :min :max
}
1045 \begin{describe
}{opt
}{string
}
1048 \begin{describe
}{opt
}{keyword \&optional @<valid>
}
1051 \begin{describe
}{opt
}{list \&optional @<handler> \&rest @<handler-args>
}
1054 \begin{describe
}{mac
}
1055 {defoptmacro @<name> @<lambda-list> \\
\ind
1056 @
[[ @<declaration>^* @! @<doc-string> @
]] \\
1060 \begin{describe
}{fun
}{parse-option-form @<form>
}
1063 \begin{describe
}{mac
}
1064 {options @
{ \=@<string> @! \+ \\
1065 @<option-macro> @! (@<option-macro> @<macro-arg>^*) @! \\
1066 (@
[[ \=@<character> @! (:short-name @<character>) @! \+ \\
1067 @<string>^* @! @<symbol> @! @<rational> @!
1068 (:long-name @<string>) @! \\
1069 (@<string> @<format-arg>^+) @!
1070 (:doc @<string> @<format-arg>^*) @! \\
1071 (:arg @<arg-name>) @! (:opt-arg @<arg-name>) @! \\
1072 @<keyword> @! (:tag @<tag>) @!
1073 (:negated-tag @<tag>) @! \\
1074 @
{ (@<handler> @<var> @<handler-arg>^*) @
}^*
1078 \begin{describe
}{fun
}
1079 {simple-usage @<option-list> \&optional @<mandatory-args> @> @<list>
}
1082 \begin{describe
}{fun
}{show-usage @<prog> @<usage> \&optional @<stream>
}
1085 \begin{describe
}{fun
}
1086 {show-help @<prog> @<usage> @<option-list> \&optional @<stream>
}
1089 \begin{describe
}{fun
}{sanity-check-option-list @<option-list>
}
1093 {\dhead{var
}{*help*
}
1094 \dhead{var
}{*version*
}
1095 \dhead{var
}{*usage*
}}
1098 \begin{describe
}{fun
}{do-usage \&optional @<stream>
}
1101 \begin{describe
}{fun
}{die-usage
}
1104 \begin{describe
}{optmac
}
1105 {help-options \&key :short-help :short-version :short-usage
}
1108 \begin{describe
}{fun
}
1109 {define-program \&key \=:program-name \+ \\
1110 :help :version :usage :full-usage \\
1114 \begin{describe
}{mac
}
1115 {do-options (@
[[ :parser @<option-parser> @
]]) \\
\ind
1116 @
{ (@
{ @<case> @! (@<case>^*)@
} (@
[@
[@<opt-var>@
] @<arg-var>@
])
1120 \begin{describe
}{fun
}{sod-frontend:augment-options @<options-list>
}
1123 %%%--------------------------------------------------------------------------
1124 \section{Property sets
} \label{sec:misc.pset
}
1126 \begin{describe
}{fun
}{property-key @<name> @> @<keyword>
}
1129 \begin{describe
}{gf
}{decode-property @<raw-value> @> @<type> @<value>
}
1132 \begin{describe
}{cls
}{property
}
1135 \begin{describe
}{fun
}{propertyp @<object> @> @<generalized-boolean>
}
1138 \begin{describe
}{fun
}
1139 {make-property @<name> @<raw-value> \&key :type :location :seenp
}
1143 {\dhead{fun
}{p-name @<property> @> @<name>
}
1144 \dhead{meth
}{property
}{file-location (@<property> property) @> @<floc>
}
1145 \dhead{fun
}{p-value @<property> @> @<value>
}
1146 \dhead{fun
}{p-type @<property> @> @<type>
}
1147 \dhead{fun
}{p-key @<property> @> @<symbol>
}
1148 \dhead{fun
}{p-seenp @<property> @> @<boolean>
}
1149 \dhead{fun
}{setf (p-seenp @<property>) @<boolean>
}}
1152 \begin{describe
}{gf
}
1153 {coerce-property-value @<value> @<type> @<wanted> @> @<coerced-value>
}
1156 \begin{describe
}{cls
}{pset
}
1159 \begin{describe
}{fun
}{psetp @<object> @> @<generalized-boolean>
}
1162 \begin{describe
}{fun
}{make-pset @> @<pset>
}
1165 \begin{describe
}{fun
}{pset-get @<pset> @<key> @> @<property-or-nil>
}
1168 \begin{describe
}{fun
}{pset-store @<pset> @<property> @> @<property>
}
1171 \begin{describe
}{fun
}{pset-map @<func> @<pset>
}
1174 \begin{describe
}{mac
}
1175 {with-pset-iterator (@<iter> @<pset>) @<declaration>^* @<form>^*
}
1178 \begin{describe
}{fun
}
1179 {store-property @<pset> @<name> @<value> \&key :type :location
1183 \begin{describe
}{fun
}
1184 {get-property @<pset> @<name> @<type> \&optional @<default>
1185 @> @<value> @<floc-or-nil>
}
1188 \begin{describe
}{fun
}
1189 {add-property @<pset> @<name> @<value> \&key :type :location
1193 \begin{describe
}{fun
}{make-property-set \&rest @<plist> @> @<pset>
}
1196 \begin{describe
}{gf
}{property-set @<thing> @> @<pset>
}
1199 \begin{describe
}{fun
}{check-unused-properties @<pset>
}
1202 \begin{describe
}{mac
}
1203 {default-slot-from-property
1204 (@<instance> @<slot> @
[@<slot-names>@
]) \\
\ind\ind
1205 (@<pset> @<property> @<type> @
[@<prop-var> @<convert-form>^*@
]) \- \\
1210 \begin{describe
}{fun
}
1211 {parse-property @<scanner> @<pset>
1212 @> @<result> @<success-flag> @<consumed-flag>
}
1215 \begin{describe
}{fun
}
1216 {parse-property-set @<scanner>
1217 @> @<result> @<success-flag> @<consumed-flag>
}
1220 %%%--------------------------------------------------------------------------
1221 \section{Miscellaneous translator features
} \label{sec:misc.misc
}
1223 \begin{describe
}{var
}{*sod-version*
}
1226 \begin{describe
}{var
}{*debugout-pathname*
}
1229 \begin{describe
}{fun
}
1230 {test-module @<path> \&key :reason :clear :backtrace @> @<status>
}
1233 \begin{describe
}{fun
}
1234 {test-parse-c-type @<string>
1235 @> t @<c-type> @<kernel> @<string> @! nil @<indicator>
}
1238 \begin{describe
}{fun
}
1239 {test-parse-pset @<string>
1240 @> t @<pset> @! nil @<indicator>
}
1243 \begin{describe
}{mac
}
1244 {test-parser (@<scanner> \&key :backtrace) @<parser> @<input>
1245 @> @<result> @<status> @<remainder>
}
1248 \begin{describe
}{fun
}{exercise
}
1251 \begin{describe
}{fun
}{sod-frontend:main
}
1254 %%%----- That's all, folks --------------------------------------------------
1256 %%% Local variables:
1258 %%% TeX-master: "sod.tex"