Various, style: Generally prefer `: ' over ` : '.

[sod] / doc / tutorial.tex

%%% -*-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:tutorial}

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:tutorial.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:tutorial.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}
  /* -*-sod-*- */                                               \\+

  code c: includes \{                                           \\
  \#include "greeter.h"                                         \\
  \}                                                            \\+

  code h: includes \{                                           \\
  \#include <stdio.h>                                           \\
  \#include <sod/sod.h>                                         \\
  \}                                                            \\+

  class Greeter: SodObject \{                                   \\ \ind
    void greet(FILE *fp) \{                                     \\ \ind
      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}
  \#include "greeter.h"                                         \\+

  int main(void)                                                \\
  \{                                                            \\ \ind
    SOD_DECL(Greeter, g);                                       \\+

    Greeter_greet(g, stdout);                                   \\
    return (0);                                               \-\\
  \}
\end{prog}
Compare this to the traditional
\begin{prog}
  \#include <stdio.h>                                           \\+

  int main(void)                                                \\ \ind
    \{ 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/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}
  code @<file-label>: @<section> \{                             \\ \ind
    @<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: