+++ /dev/null
-%%% -*-latex-*-
-%%%
-%%% Tutorial information
-%%%
-%%% (c) 2009 Straylight/Edgeware
-%%%
-
-%%%----- Licensing notice ---------------------------------------------------
-%%%
-%%% This file is part of the Simple Object Definition system.
-%%%
-%%% SOD is free software; you can redistribute it and/or modify
-%%% it under the terms of the GNU General Public License as published by
-%%% the Free Software Foundation; either version 2 of the License, or
-%%% (at your option) any later version.
-%%%
-%%% SOD is distributed in the hope that it will be useful,
-%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
-%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-%%% GNU General Public License for more details.
-%%%
-%%% You should have received a copy of the GNU General Public License
-%%% along with SOD; if not, write to the Free Software Foundation,
-%%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
-\chapter{Tutorial}
-\label{ch:tut}
-
-This chapter provides a tutorial introduction to the Sod object system. It
-intentionally misses out nitty-gritty details. If you want those, the
-remaining chapters provide a complete reference to Sod.
-
-The author isn't terribly good at writing tutorial-style documentation.
-You'll have to bear with him. If you think you can do a better job, I'm sure
-that he'll be grateful for your contribution.
-
-%%%--------------------------------------------------------------------------
-\section{Introduction} \label{sec:tut.intro}
-
-Sod is an object system for the C~programming language. Because it doesn't
-have enough already. Actually, that's not right: it's got plenty already.
-But Sod is a Sensible Object Design, and C doesn't have any of those.
-
-What does that mean when the author's not off on one of his tirades? It
-means that is has the following features.
-\begin{itemize}
-\item It has a \emph{minimal runtime system}. Sod isn't likely to interfere
- with other language runtimes or be difficult to deal with from a practical
- point of view.
-\item It provides \emph{multiple inheritance}. Rather than having a single
- superclass, Sod allows a class to specify any number of superclasses.
- Moreover, it implements multiple inheritance using \emph{superclass
- linearization}, which means that it's not a nightmare to deal with.
-\item It provides multiple \emph{method rôles}, including `before', `after'
- and `around' methods, which makes constructing object protocols rather more
- straightforward.
-\item It provides a number of \emph{method combinations}. For those coming
- from languages other than Lisp, a method combination is a rule for deciding
- how to invoke the various methods which might be used to respond to a
- message. (This might still sound like a strange idea. We'll deal with it
- in detail later.)
-\item It allows \emph{user-defined method combinations}. It does a whole lot
- more: there's an entire translation-time \emph{meta-object protocol}, so
- that extensions can modify many different aspects of the object system.
- The downside is that you have to learn Common Lisp and roll up your sleeves
- if you want to do any of this.
-\end{itemize}
-There's a good chance that half of that didn't mean anything to you. Bear
-with me, though, because we'll explain it all eventually.
-
-\subsection{Building programs with Sod} \label{sec:tut.intro.build}
-
-Sod is basically a fancy preprocessor, in the same vein as Lex and Yacc. It
-reads source files written in a vaguely C-like language. It produces output
-files which are actually C code (both header files and standalone sources),
-and which contain chunks of the input files verbatim.
-
-The main consequences of this are as follows.
-\begin{itemize}
-\item The output is completely portable between different machines and
- compilers. If you're preparing a source distribution for general release,
- it's probably a good idea to provide the generated C~source as well as your
- Sod sources.
-\item Sod hasn't made any attempt to improve C's syntax. It's just as
- hostile to object-oriented programming as it ever was. This means that
- you'll end up writing ugly things like
- \begin{prog}%
- thing->_vt->foo.frob(thing, mumble);%
- \end{prog}
- fairly frequently. This can be made somewhat less painful using macros,
- but we're basically stuck with C. The upside is that you know exactly what
- you're getting. A common complaint about \Cplusplus\ is that it has a
- tendency to hide arbitrarily complicated runtime behaviour behind
- apparently innocent syntax: you don't get any of that with Sod. Some
- people might even think this is a benefit.
-\end{itemize}
-Of course, this means that your build system needs to become more
-complicated. If you use \man{make}{1}, then something like
-\begin{prog}%
- SOD = sod
-
- .SUFFIXES: .sod .c .h
- .sod.c:; \$(SOD) -tc \$<
- .sod.h:; \$(SOD) -th \$<
-\end{prog}
-ought to do the job.
-
-%%%--------------------------------------------------------------------------
-\section{A traditional trivial introduction}
-
-The following is a simple Sod input file.
-\begin{prog}\quad\=\quad\=\kill%
-/* -*-sod-*- */
-
-code c : includes \{
-\#include "greeter.h"
-\}
-
-code h : includes \{
-\#include <stdio.h>
-\#include <sod.h>
-\}
-
-class Greeter : SodObject \{ \+
- void greet(FILE *fp) \{ \+
- fputs("Hello, world!\textbackslash n", fp); \-
- \} \-
-\} %
-\end{prog}
-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
-directory. Here's how we might use such a simple thing.
-\begin{prog}\quad\=\kill%
-\#include "greeter.h"
-
-int main(void)
-\{ \+
- struct Greeter__ilayout g_obj;
- Greeter *g = Greeter__class->cls.init(\&g_obj);
-
- g->_vt.greeter.greet(g, stdout);
- return (0); \-
-\} %
-\end{prog}
-Compare this to the traditional
-\begin{prog}\quad\=\kill%
-\#include <stdio.h>
-
-int main(void) \+
- \{ fputs("Hello, world\\n", stdout); return (0); \} %
-\end{prog}
-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
-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
-\begin{prog}%
- \#include "greeter.h" %
-\end{prog}
-needs to appear in the generated @|greeter.c| file; the second says that
-\begin{prog}%
- \#include <stdio.h>
- \#include <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
-approach to all of this: it expects you, the programmer, to deal with it.
-
-The basic syntax for @"code" stanzas is
-\begin{prog}\quad\=\kill%
- code @<file-label> : @<section> \{
- \> @<code>
- \} %
-\end{prog}
-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:
-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
-in response, it writes a traditional greeting to the file passed in with the
-message.
-
-So far, so good. The C code, which we thought we understood, contains some
-bizarre looking runes. Let's take it one step at a time.
-\begin{prog}%
- struct Greeter__ilayout g_obj; %
-\end{prog}
-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
-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.
-
-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
-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
-picked one by forcing the classname to lowercase.
-
-%%%----- That's all, folks --------------------------------------------------
-
-%%% Local variables:
-%%% mode: LaTeX
-%%% TeX-master: "sod.tex"
-%%% TeX-PDF-mode: t
-%%% End:
~mdw / sod / blobdiff