incorrect behaviour. In particular, the situation need not be immediately
diagnosed, and the consequences may be far-reaching.
+A \emph{specified} function, variable, symbol, class, type, macro, or other
+item is one documented in this specification.
+
The following conventions apply throughout this specification.
\begin{itemize}
syntax, then it is an error to provide an argument not having that
particular type or syntax.
-\item If a specification describes a function then that function might be
- implemented as a generic function; it is an error to attempt to (re)define
+\item A specified function may, e.g., in a later version, accept additional
+ optional and/or keyword arguments. A specified macro may be extended to
+ accept syntax other than that documented in this specification, e.g., to
+ add additional optional arguments.
+
+\item If a specified function or macro is described as returning the values
+ returned by some user-supplied function or form, then it will do precisely
+ that, and there are no restrictions on which or how many values such a
+ user-supplied function or form may return. Other specified functions or
+ macros may return additional values beyond those described (so it is likely
+ an error to invoke them in forms such as @|multiple-value-list| or
+ @|multiple-value-call|). It is an error for a user-supplied function or
+ form not to return the documented number and types of values.
+
+\item The \emph{specified packages} are the @|SOD| package, and all packages
+ whose names begin @|SOD-|. The specified packages are reserved for the Sod
+ translator. It is an error to define or alter specified packages (e.g., to
+ export additional symbols from them, import symbols into them, shadow
+ symbols in them, or modify their `use' lists), to refer to internal symbols
+ in specified packages, or to define functions or macros, or proclaim
+ @|special| variables, whose names are exported by specified packages. If a
+ symbol exported from a specified package has a name beginning and ending
+ with @|*| or @|+|, then it is an error to use it as a lexical variable.
+
+\item A specified function might be implemented as a generic function even if
+ it is not documented as being one; it is an error to attempt to (re)define
it as a generic function, or to attempt to add methods to it. A function
specified as being a generic function will certainly be so; if user methods
- are permitted on the generic function then this will be specified.
+ are permitted on the generic function then this will be documented.
\item Where a class precedence list is specified, either explicitly or
implicitly by a class hierarchy, the implementation may include additional
\item An object $o$ is a \emph{direct instance} of a class $c$ if @|(eq
(class-of $o$) $c$)|; $o$ is an \emph{instance} of $c$ if it is a direct
- instance of any subclass of $c$.
-
-\item If a class is specified as being \emph{abstract} then it is an error to
- construct direct instances of it, e.g., using @|make-instance|.
+ instance of any subclass of $c$. If a class is specified as being
+ \emph{abstract} then it is an error to construct direct instances of it,
+ e.g., using @|make-instance|.
\item If an object is specified as being \emph{immutable} then it is an error
- to mutate it, e.g., using @|(setf (slot-value \ldots) \ldots)|. Programs
- may rely on immutable objects retaining their state.
+ to mutate it, e.g., using @|(setf (slot-value \ldots) \ldots)|. User
+ programs may rely on immutable objects retaining their state.
\item A value is \emph{fresh} if it is guaranteed to be not @|eql| to any
previously existing value. A list is \emph{fresh} if it is guaranteed that
none of the cons cells in its main cdr chain (i.e., the list head, its cdr,
- and so on) are @|eql| to any previously existing value.
-
-\item Unless otherwise specified, it is an error to mutate any part of value
- passed as an argument to, or a non-fresh part of a value returned by, a
- function specified in this document.
+ and so on) are @|eql| to any previously existing value. Unless otherwise
+ specified, it is an error to mutate any part of value passed as an argument
+ to, or a non-fresh part of a value returned by, a specified function.
\item Unless otherwise specified, it is an error to change the class of an
- instance of any class described here; and it is an error to change the
- class of an object to a class described here.
+ instance of any specified class; and it is an error to change the class of
+ an object to a specified class.
\end{itemize}
\begin{describe}{mac}
{example-macro
- (@{ @<symbol> @! (@<symbol> @<form>) @}^*) \\ \ind
- @[[ @<declaration>^* @! @<doc-string> @]] \\
+ (@{ @<symbol> @! (@<symbol> @<form>) @}^*) \\ \ind
+ @[[ @<declaration>^* @! @<doc-string> @]] \\
@<form>^*
\nlret @<value>^*}
The synopsis for a macro describes the acceptable syntax using the
~mdw / sod / blobdiff