X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/3dca7758421664a838c54b273bd9221f02072045:/doc/sod-tut.tex..1f7d590d9c7b87442c8d8b6424ed4f769d377692:/doc/tutorial.tex diff --git a/doc/sod-tut.tex b/doc/tutorial.tex similarity index 86% rename from doc/sod-tut.tex rename to doc/tutorial.tex index ca686aa..afc6109 100644 --- a/doc/sod-tut.tex +++ b/doc/tutorial.tex @@ -23,8 +23,7 @@ %%% 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} +\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 @@ -35,7 +34,7 @@ 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} +\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. @@ -68,7 +67,7 @@ means that is has the following features. 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} +\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 @@ -84,8 +83,8 @@ The main consequences of this are as follows. \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);% + \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 @@ -96,11 +95,11 @@ The main consequences of this are as follows. \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 \$< +\begin{prog} + SOD = sod \\ + \\ + .SUFFIXES: .sod .c .h \\ + .sod.c:; \$(SOD) -tc \$< \\ .sod.h:; \$(SOD) -th \$< \end{prog} ought to do the job. @@ -109,48 +108,47 @@ 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 -\#include +\begin{prog} +/* -*-sod-*- */ \\ +\\ +code c : includes \{ \\ +\#include "greeter.h" \\ +\} \\ +\\ +code h : includes \{ \\ +\#include \\ +\#include \\ +\} \\ +\\ +class Greeter : SodObject \{ \\ \ind + void greet(FILE *fp) \{ \\ \ind + fputs("Hello, world!\textbackslash n", fp); \- \\ + \} \- \\ \} - -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 % +\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); \- -\} % +\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}\quad\=\kill% -\#include - -int main(void) \+ - \{ fputs("Hello, world\\n", stdout); return (0); \} % +\begin{prog} +\#include \\ +\\ +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. @@ -161,13 +159,13 @@ 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" % +\begin{prog} + \#include "greeter.h" \end{prog} needs to appear in the generated @|greeter.c| file; the second says that -\begin{prog}% - \#include - \#include % +\begin{prog} + \#include \\ + \#include \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 @@ -176,10 +174,10 @@ 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 @ : @
\{ - \> @ - \} % +\begin{prog} + code @ : @
\{ \\ \ind + @ \- \\ + \} \end{prog} The @ is either @"c" or @"h", and says which output file the code wants to be written to. The @
is a name which explains where in the @@ -193,13 +191,13 @@ 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; % +\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); % +\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 @@ -209,8 +207,8 @@ 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); % +\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