Compatibility: the `init' function no longer calls `imprint' for you.

[sod] / lib / sod-structs.3

diff --git a/lib/sod-structs.3 b/lib/sod-structs.3
index 6aefc9d..2d4ecd1 100644 (file)
--- a/lib/sod-structs.3
+++ b/lib/sod-structs.3
@@ -7,23 +7,26 @@
 .
 .\"----- Licensing notice ---------------------------------------------------
 .\"
 .
 .\"----- Licensing notice ---------------------------------------------------
 .\"

-.\" This file is part of the Sensble Object Design, an object system for C.
+.\" This file is part of the Sensible Object Design, an object system for C.

 .\"
 .\" SOD is free software; you can redistribute it and/or modify
 .\"
 .\" 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.
+.\" it under the terms of the GNU Library 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
 .\"
 .\" 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.
+.\" GNU Library 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.
+.\" You should have received a copy of the GNU Library 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.

 .
 .

+.\" Highlight using terminal escapes, rather than overstriking.

 .\"\X'tty: sgr 1'
 .\"\X'tty: sgr 1'

+.

 .\" String definitions and font selection.
 .ie t \{\
 .  ds o \(bu
 .\" String definitions and font selection.
 .ie t \{\
 .  ds o \(bu


@@ -192,11 +195,13 @@ has no direct superclasses,
 and
 .B SodClass
 is its own metaclass.
 and
 .B SodClass
 is its own metaclass.

-It is not possible to define root classes because of circularities:
+It is not possible to define root classes in module files
+because of circularities:

 .B SodObject
 has
 .B SodClass
 .B SodObject
 has
 .B SodClass

-as its metaclass, and
+as its metaclass,
+and

 .B SodClass
 is a subclass of
 .BR SodObject .
 .B SodClass
 is a subclass of
 .BR SodObject .


@@ -266,12 +271,8 @@ The function returns its argument
 A pointer to a function:
 given a pointer
 .I p
 A pointer to a function:
 given a pointer
 .I p

-to at least
-.I initsz
-bytes of appropriately aligned memory,
-initialize an instance of the class in it:
-all of the vtable and class pointers are initialized,
-as are slots for which initializers are defined.
+to an imprinted instance,
+initialize all of its slots for which initializers are defined.

 Other slots are left untouched.
 The function returns its argument
 .IR p .
 Other slots are left untouched.
 The function returns its argument
 .IR p .


@@ -546,7 +547,8 @@ and this is followed by corresponding members
 .IB a ;
 .PP
 for each of
 .IB a ;
 .PP
 for each of

-.IR C 's superclasses
+.IR C 's
+superclasses

 .IR A
 in the same chain in some (unimportant) order.
 A `pointer to
 .IR A
 in the same chain in some (unimportant) order.
 A `pointer to


@@ -617,13 +619,17 @@ each
 .B ichain
 must have as a prefix the
 .B ichain
 .B ichain
 must have as a prefix the
 .B ichain

-for each superclass in the same chain, and
-each slot must be stored in exactly one place.
+for each superclass in the same chain,
+and each slot must be stored in exactly one place.

 The layout of vtables doesn't have this second requirement:
 it doesn't matter that there are
 multiple method entry pointers
 for the same effective method
 as long as they all work correctly.
 The layout of vtables doesn't have this second requirement:
 it doesn't matter that there are
 multiple method entry pointers
 for the same effective method
 as long as they all work correctly.

+Indeed, it's essential that they do,
+because each chain's method entry function
+will need to apply a different offset to the receiver pointer
+before invoking the effective method.

 .PP
 A vtable for a class
 .I C
 .PP
 A vtable for a class
 .I C


@@ -655,10 +661,8 @@ extern const union \fIC\fB__vtu_\fIh\fB \fIC\fB__vtable_\fIh\fB;
 .fi
 .PP
 The outer layer is a
 .fi
 .PP
 The outer layer is a

-.IP

 .B union
 .IB C __vtu_ h
 .B union
 .IB C __vtu_ h

-.PP

 containing a member
 .IP
 .B struct
 containing a member
 .IP
 .B struct


@@ -718,7 +722,7 @@ of
 The metaclass
 .I R
 of
 The metaclass
 .I R
 of

-.IR O .
+.I O

 is then the
 .I root metaclass
 of
 is then the
 .I root metaclass
 of


@@ -781,7 +785,7 @@ be the most specific superclass of
 in the same chain as
 .IR J .
 Then, if there is currently no class pointer of type
 in the same chain as
 .IR J .
 Then, if there is currently no class pointer of type

-.I Q
+.IR Q ,

 then add a member
 .RS
 .IP
 then add a member
 .RS
 .IP


@@ -825,7 +829,7 @@ If class
 .I A
 defines any messages,
 and there is currently no member
 .I A
 defines any messages,
 and there is currently no member

-.I a
+.IR a ,

 then add a member
 .RS
 .IP
 then add a member
 .RS
 .IP


@@ -885,6 +889,27 @@ defined as
 .IB an , 
 .B ...);
 .PP
 .IB an , 
 .B ...);
 .PP

+or a standard message which takes keyword arguments,
+defined as
+.IP
+.I tr
+.IB m ( \c
+.I t1
+.IB a1 ,
+.RB ... ,
+.I tn
+.IB an ?\&
+.IR tn +1
+.IR kn +1
+.RB [ =
+.IR dn +1] \c
+.B ,
+.I tm
+.I km
+.RB [ =
+.IR dm ] \c
+);
+.PP

 two entry points are defined:
 the usual `main' entry point
 which accepts a variable number of
 two entry points are defined:
 the usual `main' entry point
 which accepts a variable number of


@@ -892,7 +917,8 @@ arguments,
 and a `valist' entry point
 which accepts an argument of type
 .B va_list
 and a `valist' entry point
 which accepts an argument of type
 .B va_list

-in place of the variable portion of the argument list.
+in place of the variable portion of the argument list
+or keywords.

 .IP
 .I tr
 .BI (* m )( \c
 .IP
 .I tr
 .BI (* m )( \c


@@ -942,6 +968,7 @@ somewhat less ugly.
 If
 .I m
 takes a variable number of arguments,
 If
 .I m
 takes a variable number of arguments,

+or keyword arguments,

 the macro is more complicated
 and is only available in compilers advertising C99 support,
 but the effect is the same.
 the macro is more complicated
 and is only available in compilers advertising C99 support,
 but the effect is the same.