\fixme{describe syntax; expand}
Properties:
\begin{description}
-\item[@"module_class"] A symbol naming the Lisp class to use to
+\item[@|module_class|] A symbol naming the Lisp class to use to
represent the module.
-\item[@"guard"] An identifier to use as the guard symbol used to prevent
+\item[@|guard|] An identifier to use as the guard symbol used to prevent
multiple inclusion in the header file.
\end{description}
Note that Sod doesn't attempt to compile Lisp files, or even to look for
existing compiled files. The right way to package a substantial extension to
the Sod translator is to provide the extension as a standard ASDF system (or
-similar) and leave a dropping @"foo-extension.lisp" in the module path saying
+similar) and leave a dropping @|foo-extension.lisp| in the module path saying
something like
\begin{quote}
\textsf{(asdf:load-system :foo-extension)}
The @<c-fragment> will be output unchanged to one of the output files.
The first @<identifier> is the symbolic name of an output file. Predefined
-output file names are @"c" and @"h", which are the implementation code and
+output file names are @|c| and @|h|, which are the implementation code and
header file respectively; other output files can be defined by extensions.
Output items are named with a sequence of identifiers, separated by
additional items in between them. (The particular output items needn't be
defined already -- indeed, they needn't be defined ever.)
-There is a predefined output item @"includes" in both the @"c" and @"h"
-output files which is a suitable place for inserting @"\#include"
+There is a predefined output item @|includes| in both the @|c| and @|h|
+output files which is a suitable place for inserting @|\#include|
preprocessor directives in order to declare types and functions for use
elsewhere in the generated output files.
The @<properties> provide additional information. The standard class
properties are as follows.
\begin{description}
-\item[@"lisp_class"] The name of the Lisp class to use within the translator
+\item[@|lisp_class|] The name of the Lisp class to use within the translator
to represent this class. The property value must be an identifier; the
- default is @"sod_class". Extensions may define classes with additional
+ default is @|sod_class|. Extensions may define classes with additional
behaviour, and may recognize additional class properties.
-\item[@"metaclass"] The name of the Sod metaclass for this class. In the
+\item[@|metaclass|] The name of the Sod metaclass for this class. In the
generated code, a class is itself an instance of another class -- its
\emph{metaclass}. The metaclass defines which slots the class will have,
which messages it will respond to, and what its behaviour will be when it
receives them. The property value must be an identifier naming a defined
- subclass of @"SodClass". The default metaclass is @"SodClass".
+ subclass of @|SodClass|. The default metaclass is @|SodClass|.
See \xref{sec:concepts.metaclasses} for more details.
-\item[@"nick"] A nickname for the class, to be used to distinguish it from
+\item[@|nick|] A nickname for the class, to be used to distinguish it from
other classes in various limited contexts. The property value must be an
identifier; the default is constructed by forcing the class name to
lower-case.
Properties:
\begin{description}
-\item[@"slot_class"] A symbol naming the Lisp class to use to represent the
+\item[@|slot_class|] A symbol naming the Lisp class to use to represent the
direct slot.
-\item[@"initarg"] An identifier naming an initialization argument which can
+\item[@|initarg|] An identifier naming an initialization argument which can
be used to provide a value for the slot. See
\xref{sec:concepts.lifecycle.birth} for the details.
-\item[@"initarg_class"] A symbol naming the Lisp class to use to represent
- the initarg. Only permitted if @"initarg" is also set.
+\item[@|initarg_class|] A symbol naming the Lisp class to use to represent
+ the initarg. Only permitted if @|initarg| is also set.
\end{description}
An @<initializer>, if present, is treated as if a separate
\end{grammar}
An @<initializer-item> provides an initial value for one or more slots. If
-prefixed by @"class", then the initial values are for class slots (i.e.,
+prefixed by @|class|, then the initial values are for class slots (i.e.,
slots of the class object itself); otherwise they are for instance slots.
The first component of the @<dotted-name> must be the nickname of one of the
Properties:
\begin{description}
-\item[@"initializer_class"] A symbol naming the Lisp class to use to
+\item[@|initializer_class|] A symbol naming the Lisp class to use to
represent the initializer.
-\item[@"initarg"] An identifier naming an initialization argument which can
+\item[@|initarg|] An identifier naming an initialization argument which can
be used to provide a value for the slot. See
\xref{sec:concepts.lifecycle.birth} for the details. An initializer item
must have either an @|initarg| property, or an initializer expression, or
both.
-\item[@"initarg_class"] A symbol naming the Lisp class to use to represent
- the initarg. Only permitted if @"initarg" is also set.
+\item[@|initarg_class|] A symbol naming the Lisp class to use to represent
+ the initarg. Only permitted if @|initarg| is also set.
\end{description}
Each class may define at most one initializer item with an explicit
\end{grammar}
Properties:
\begin{description}
-\item[@"initarg_class"] A symbol naming the Lisp class to use to represent
+\item[@|initarg_class|] A symbol naming the Lisp class to use to represent
the initarg.
\end{description}
\end{grammar}
Properties:
\begin{description}
-\item[@"message_class"] A symbol naming the Lisp class to use to represent
+\item[@|message_class|] A symbol naming the Lisp class to use to represent
the message.
-\item[@"combination"] A keyword naming the aggregating method combination to
+\item[@|combination|] A keyword naming the aggregating method combination to
use.
-\item[@"most_specific"] A keyword, either @`first' or @`last', according to
+\item[@|most_specific|] A keyword, either @`first' or @`last', according to
whether the most specific applicable method should be invoked first or
last.
\end{description}
Properties for the @|custom| aggregating method combination:
\begin{description}
-\item[@"retvar"] An identifier for the return value from the effective
+\item[@|retvar|] An identifier for the return value from the effective
method. The default is @|sod__ret|. Only permitted if the message return
type is not @|void|.
-\item[@"valvar"] An identifier holding each return value from a direct method
+\item[@|valvar|] An identifier holding each return value from a direct method
in the effective method. The default is @|sod__val|. Only permitted if
- the method return type (see @"methty" below) is not @|void|.
-\item[@"methty"] A C type, which is the return type for direct methods of
+ the method return type (see @|methty| below) is not @|void|.
+\item[@|methty|] A C type, which is the return type for direct methods of
this message. The default is the return type of the message.
-\item[@"decls"] A code fragment containing declarations to be inserted at the
+\item[@|decls|] A code fragment containing declarations to be inserted at the
head of the effective method body. The default is to insert nothing.
-\item[@"before"] A code fragment containing initialization to be performed at
+\item[@|before|] A code fragment containing initialization to be performed at
the beginning of the effective method body. The default is to insert
nothing.
-\item[@"empty"] A code fragment executed if there are no primary methods;
+\item[@|empty|] A code fragment executed if there are no primary methods;
it should usually store a suitable (identity) value in @<retvar>. The
default is not to emit an effective method at all if there are no primary
methods.
-\item[@"first"] A code fragment to set the return value after calling the
- first applicable direct method. The default is to use the @"each"
+\item[@|first|] A code fragment to set the return value after calling the
+ first applicable direct method. The default is to use the @|each|
fragment.
-\item[@"each"] A code fragment to set the return value after calling a direct
- method. If @"first" is also set, then it is used after the first direct
+\item[@|each|] A code fragment to set the return value after calling a direct
+ method. If @|first| is also set, then it is used after the first direct
method instead of this. The default is to insert nothing, which is
probably not what you want.
-\item[@"after"] A code fragment inserted at the end of the effective method
+\item[@|after|] A code fragment inserted at the end of the effective method
body. The default is to insert nothing.
-\item[@"count"] An identifier naming a variable to be declared in the
+\item[@|count|] An identifier naming a variable to be declared in the
effective method body, of type @|size_t|, holding the number of applicable
methods. The default is not to provide such a variable.
\end{description}
\end{grammar}
Properties:
\begin{description}
-\item[@"method_class"] A symbol naming the Lisp class to use to represent
+\item[@|method_class|] A symbol naming the Lisp class to use to represent
the direct method.
-\item[@"role"] A keyword naming the direct method's rôle. For the built-in
+\item[@|role|] A keyword naming the direct method's rôle. For the built-in
`simple' message classes, the acceptable rôle names are @|before|,
@|after|, and @|around|. By default, a primary method is constructed.
\end{description}
\} \-\\
\}
\end{prog}
-Save it as @"greeter.sod", and run
+Save it as @|greeter.sod|, and run
\begin{prog}
sod --gc --gh greeter
\end{prog}
-This will create files @"greeter.c" and @"greeter.h" in the current
+This will create files @|greeter.c| and @|greeter.h| in the current
directory. Here's how we might use such a simple thing.
\begin{prog}
\#include "greeter.h" \\+
and I'm sure you'll appreciate the benefits of using Sod already -- mostly to
do with finger exercise. Trust me, it gets more useful.
-The @".sod" file was almost comprehensible. There are two important parts to
+The @|.sod| file was almost comprehensible. There are two important parts to
it (after the comment which tells Emacs how to cope with it).
-The first part consists of the two @"code" stanzas. Both of them define
-gobbets of raw C code to copy into output files. The first one, @"code~:
-c"~\ldots, says that
+The first part consists of the two @|code| stanzas. Both of them define
+gobbets of raw C code to copy into output files. The first one, @|code~:
+c|~\ldots, says that
\begin{prog}
\#include "greeter.h"
\end{prog}
\#include <sod/sod.h>
\end{prog}
needs to appear in the header file @|greeter.h|. The generated C files need
-to get declarations for external types and functions (e.g., @"FILE" and
-@"fputs") from somewhere, and the generated @".c" file will need the
-declarations from the corresponding @".h" file. Sod takes a very simple
+to get declarations for external types and functions (e.g., @|FILE| and
+@|fputs|) from somewhere, and the generated @|.c| file will need the
+declarations from the corresponding @|.h| file. Sod takes a very simple
approach to all of this: it expects you, the programmer, to deal with it.
-The basic syntax for @"code" stanzas is
+The basic syntax for @|code| stanzas is
\begin{prog}
code @<file-label>: @<section> \{ \\ \ind
@<code> \-\\
\}
\end{prog}
-The @<file-label> is either @"c" or @"h", and says which output file the code
+The @<file-label> is either @|c| or @|h|, and says which output file the code
wants to be written to. The @<section> is a name which explains where in the
-output file to place the code. The @"includes" section is the usual choice:
+output file to place the code. The @|includes| section is the usual choice:
it's the `right' place for @`\#include' directives and similar declarations.
The remaining part, the `meat' of the file, defines a class called
-@"greeter". The class can respond to a single message, named @"greet", and
+@|greeter|. The class can respond to a single message, named @|greet|, and
in response, it writes a traditional greeting to the file passed in with the
message.
\begin{prog}
struct Greeter__ilayout g_obj;
\end{prog}
-allocates space for an instance of class @"Greeter". We're not going to use
+allocates space for an instance of class @|Greeter|. We're not going to use
this space directly. Instead, we do this frightening looking thing.
\begin{prog}
Greeter *g = Greeter__class@->cls.init(\&g_obj);
\end{prog}
-Taking it slowly: @"Greeter__class" is a pointer to the object that
-represents our class @"Greeter". This object contains a member, named
-@"cls.init", which points to a function whose job is to turn uninitialized
+Taking it slowly: @|Greeter__class| is a pointer to the object that
+represents our class @|Greeter|. This object contains a member, named
+@|cls.init|, which points to a function whose job is to turn uninitialized
storage space into working instances of the class. It returns a pointer to
the instance, which we use in preference to grovelling about in the
-@"ilayout" structure.
+@|ilayout| structure.
Having done this, we `send the instance a message':
\begin{prog}
g@->_vt@->greeter.greet(g, stdout);
\end{prog}
This looks horrific, and seems to repeat itself quite unnecessarily. The
-first @"g" is the recipient of our `message'. The second is indeed a copy of
+first @|g| is the recipient of our `message'. The second is indeed a copy of
the first: we have to tell it who it is. (Sod doesn't extend C's syntax, so
this is the sort of thing we just have to put up with.) The lowercase
-@"greeter" is our class's `nickname': we didn't choose one explicitly, so Sod
+@|greeter| is our class's `nickname': we didn't choose one explicitly, so Sod
picked one by forcing the classname to lowercase.
%%%----- That's all, folks --------------------------------------------------
~mdw / sod / commitdiff