X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/b1254eb62a3ca4eb2839cd0f340d754f45d549a2..4307347660f48628e307f299eb4fac58ba35fd1a:/doc/concepts.tex

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 9a77c44..89dcd8f 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -110,6 +110,7 @@ appropriate C declarations, tables, and functions.  An object cannot
 (usually) change its direct class, and the direct class of an object is not
 affected by, for example, the static type of a pointer to it.
 
+
 \subsection{Superclasses and inheritance}
 \label{sec:concepts.classes.inherit}
 
@@ -232,6 +233,7 @@ Classes have a number of other attributes:
   then all the superclasses of $C$ must have distinct nicknames.
 \end{itemize}
 
+
 \subsection{Slots} \label{sec:concepts.classes.slots}
 
 Each class defines a number of \emph{slots}.  Much like a structure member, a
@@ -257,6 +259,7 @@ expressions if the generated code is expected to be processed by a
 implementation of C89.  Initializers will be evaluated once each time an
 instance is initialized.
 
+
 \subsection{C language integration} \label{sec:concepts.classes.c}
 
 For each class~$C$, the Sod translator defines a C type, the \emph{class
@@ -278,7 +281,7 @@ about these slot members: C code can access them in the usual way.
 For example, if @|MyClass| has the nickname @|mine|, and defines a slot @|x|
 of type @|int|, then the simple function
 \begin{prog}
-  int get_x(MyClass *m) \{ return (m->mine.x); \}
+  int get_x(MyClass *m) \{ return (m@->mine.x); \}
 \end{prog}
 will extract the value of @|x| from an instance of @|MyClass|.
 
@@ -346,15 +349,15 @@ interim approach is to specify slot initializers where appropriate and send
 class-specific messages for more complicated parametrized initialization.
 
 Automatic-duration instances can be conveniently constructed and initialized
-using the @|SOD_DECL| macro (page~\pageref{mac:SOD-DECL}).  No special
-support is currently provided for dynamically allocated instances.  A simple
-function using @|malloc| might work as follows.
+using the \descref{SOD_DECL}[macro]{mac}.  No special support is currently
+provided for dynamically allocated instances.  A simple function using
+@|malloc| might work as follows.
 \begin{prog}
   void *new_instance(const SodClass *c) \\
   \{ \\ \ind
-    void *p = malloc(c->cls.initsz); \\
+    void *p = malloc(c@->cls.initsz); \\
     if (!p) return (0); \\
-    c->cls.init(p); \\
+    c@->cls.init(p); \\
     return (p); \- \\
   \}
 \end{prog}
@@ -363,26 +366,27 @@ function using @|malloc| might work as follows.
 There is currently no provided assistance for finalization or deallocation.
 It is the programmer's responsibility to decide and implement an appropriate
 protocol.  Note that to free an instance allocated from the heap, one must
-correctly find its base address: the @|SOD_INSTBASE| macro
-(page~\pageref{mac:SOD-INSTBASE}) will do this for you.
+correctly find its base address: the \descref{SOD_INSTBASE}[macro]{mac} will
+do this for you.
 
 The following simple mixin class is suggested.
 \begin{prog}
-  [nick = disposable] \\*
-  class DisposableObject : SodObject \{ \\*[\jot] \ind
-    void release() \{ ; \} \\*
-    \quad /\=\+* Release resources held by the receiver. */ \-\- \\*[\jot]
-  \} \\[\bigskipamount]
-  code c : user \{ \\* \ind
-    /\=\+* Free object p's instance storage.  If p is a DisposableObject \\*
-       {}* then release its resources beforehand. \\*
-       {}*/ \- \\*
-    void free_instance(void *p) \\*
-    \{ \\* \ind
-      DisposableObject *d = SOD_CONVERT(DisposableObject, p); \\*
-      if (d) DisposableObject_release(d); \\*
-      free(d); \- \\*
-    \} \- \\*
+  [nick = disposable] \\
+  class DisposableObject : SodObject \{ \\- \ind
+    void release() \{ ; \} \\
+    \quad /* Release resources held by the receiver. */ \- \\-
+  \}
+  \\+
+  code c : user \{ \\- \ind
+    /\=\+* Free object p's instance storage.  If p is a DisposableObject \\
+       {}* then release its resources beforehand. \\
+       {}*/ \- \\
+    void free_instance(void *p) \\
+    \{ \\ \ind
+      DisposableObject *d = SOD_CONVERT(DisposableObject, p); \\
+      if (d) DisposableObject_release(d); \\
+      free(d); \- \\
+    \} \- \\
   \}
 \end{prog}
 
@@ -403,13 +407,13 @@ There are three main cases to distinguish.
   a lookup at runtime to find the appropriate offset by which to adjust the
   pointer.  The conversion can be performed using the appropriate generated
   upcast macro (see below); the general case is handled by the macro
-  @|SOD_XCHAIN| (page~\pageref{mac:SOD-XCHAIN}).
+  \descref{SOD_XCHAIN}{mac}.
 \item If $B$ is a subclass of~$C$ then the conversion is an \emph{upcast};
   otherwise the conversion is a~\emph{cross-cast}.  In either case, the
   conversion can fail: the object in question might not be an instance of~$B$
-  at all.  The macro @|SOD_CONVERT| (page~\pageref{mac:SOD-CONVERT}) and the
-  function @|sod_convert| (page~\pageref{fun:sod-convert}) perform general
-  conversions.  They return a null pointer if the conversion fails.
+  at all.  The macro \descref{SOD_CONVERT}{mac} and the function
+  \descref{sod_convert}{fun} perform general conversions.  They return a null
+  pointer if the conversion fails.
 \end{itemize}
 The Sod translator generates macros for performing both in-chain and
 cross-chain upcasts.  For each class~$C$, and each proper superclass~$B$
@@ -428,6 +432,47 @@ nickname @|super|, then the macro @|MYCLASS__CONV_SUPER| converts a
 \xref{sec:structures.layout.additional} for the formal description.
 
 %%%--------------------------------------------------------------------------
+\section{Keyword arguments} \label{sec:concepts.keywords}
+
+In standard C, the actual arguments provided to a function are matched up
+with the formal arguments given in the function definition according to their
+ordering in a list.  Unless the (rather cumbersome) machinery for dealing
+with variable-length argument tails (@|<stdarg.h>|) is used, exactly the
+correct number of arguments must be supplied, and in the correct order.
+
+A \emph{keyword argument} is matched by its distinctive \emph{name}, rather
+than by its position in a list.  Keyword arguments may be \emph{omitted},
+causing some default behaviour by the function.  A function can detect
+whether a particular keyword argument was supplied: so the default behaviour
+need not be the same as that caused by any specific value of the argument.
+
+Keyword arguments can be provided in three ways.
+\begin{enumerate}
+\item Directly, as a variable-length argument tail, consisting (for the most
+  part) of alternating keyword names, as pointers to null-terminated strings,
+  and argument values, and terminated by a null pointer.  This is somewhat
+  error-prone, and the support library defines some macros which help ensure
+  that keyword argument lists are well formed.
+\item Indirectly, through a @|va_list| object capturing a variable-length
+  argument tail passed to some other function.  Such indirect argument tails
+  have the same structure as the direct argument tails described above.
+  Because @|va_list| objects are hard to copy, the keyword-argument support
+  library consistently passes @|va_list| objects \emph{by reference}
+  throughout its programming interface.
+\item Indirectly, through a vector of @|struct kwval| objects, each of which
+  contains a keyword name, as a pointer to a null-terminated string, and the
+  \emph{address} of a corresponding argument value.  (This indirection is
+  necessary so that the items in the vector can be of uniform size.)
+  Argument vectors are rather inconvenient to use, but are the only practical
+  way in which a caller can decide at runtime which arguments to include in a
+  call, which is useful when writing wrapper functions.
+\end{enumerate}
+
+Keyword arguments are provided as a general feature for C functions.
+However, Sod has special support for messages which accept keyword arguments
+(\xref{sec:concepts.methods.keywords}).
+
+%%%--------------------------------------------------------------------------
 \section{Messages and methods} \label{sec:concepts.methods}
 
 Objects can be sent \emph{messages}.  A message has a \emph{name}, and
@@ -473,6 +518,7 @@ contains a copy of the direct method body.  Within the body of a direct
 method defined for a class $C$, the variable @|me|, of type pointer to class
 type of $C$, refers to the receiving object.
 
+
 \subsection{Effective methods and method combinations}
 \label{sec:concepts.methods.combination}
 
@@ -491,9 +537,7 @@ another, $N$, with respect to a receiving class~$C$, if the class defining
 $M$ is a more (resp.\ less) specific superclass of~$C$ than the class
 defining $N$.
 
-\subsection{The standard method combination}
-\label{sec:concepts.methods.standard}
-
+\subsubsection{The standard method combination}
 The default method combination is called the \emph{standard method
 combination}; other method combinations are useful occasionally for special
 effects.  The standard method combination accepts four direct method roles,
@@ -590,9 +634,7 @@ arguments.  If the method body has overwritten its formal arguments, then
 @|CALL_NEXT_METHOD| will pass along the updated values, rather than the
 original ones.
 
-\subsection{Aggregating method combinations}
-\label{sec:concepts.methods.aggregating}
-
+\subsubsection{Aggregating method combinations}
 A number of other method combinations are provided.  They are called
 `aggregating' method combinations because, instead of invoking just the most
 specific primary method, as the standard method combination does, they invoke
@@ -621,19 +663,55 @@ The aggregating method combinations provided are as follows.
 \item[max] The message must return a scalar type.  The applicable primary
   methods are invoked in turn.  The final result is the largest of the
   individual values.
-\item[and] The message must return @|int|.  The applicable primary methods
-  are invoked in turn.  If any method returns zero then the final result is
-  zero and no further methods are invoked.  If all of the applicable primary
-  methods return nonzero, then the final result is a nonzero value.
-\item[or] The message must return @|int|.  The applicable primary methods are
-  invoked in turn.  If any method returns nonzero then the final result is a
-  nonzero value and no further methods are invoked.  If all of the applicable
-  primary methods return zero, then the final result is zero.
+\item[and] The message must return a scalar type.  The applicable primary
+  methods are invoked in turn.  If any method returns zero then the final
+  result is zero and no further methods are invoked.  If all of the
+  applicable primary methods return nonzero, then the final result is the
+  result of the last primary method.
+\item[or] The message must return a scalar type.  The applicable primary
+  methods are invoked in turn.  If any method returns nonzero then the final
+  result is that nonzero value and no further methods are invoked.  If all of
+  the applicable primary methods return zero, then the final result is zero.
 \end{description}
 
 There is also a @|custom| aggregating method combination, which is described
 in \xref{sec:fixme.custom-aggregating-method-combination}.
 
+
+\subsection{Messages with keyword arguments}
+\label{sec:concepts.methods.keywords}
+
+A message or a direct method may declare that it accepts keyword arguments.
+A message which accepts keyword arguments is called a \emph{keyword message};
+a direct method which accepts keyword arguments is called a \emph{keyword
+method}.
+
+While method combinations may set their own rules, usually keyword methods
+can only be defined on keyword messages, and all methods defined on a keyword
+message must be keyword methods.  The direct methods defined on a keyword
+message may differ in the keywords they accept, both from each other, and
+from the message.  If two superclasses of some common class both define
+keyword methods on the same message, and the methods both accept a keyword
+argument with the same name, then these two keyword arguments must also have
+the same type.  Different applicable methods may declare keyword arguments
+with the same name but different defaults; see below.
+
+The keyword arguments acceptable in a message sent to an object are the
+keywords listed in the message definition, together with all of the keywords
+accepted by any applicable method.  There is no easy way to determine at
+runtime whether a particular keyword is acceptable in a message to a given
+instance.
+
+At runtime, a direct method which accepts one or more keyword arguments
+receives an additional argument named @|suppliedp|.  This argument is a small
+structure.  For each keyword argument named $k$ accepted by the direct
+method, @|suppliedp| contains a one-bit-wide bitfield member of type
+@|unsigned|, also named $k$.  If a keyword argument named $k$ was passed in
+the message, then @|suppliedp.$k$| is one, and $k$ contains the argument
+value; otherwise @|suppliedp.$k$| is zero, and $k$ contains the default value
+from the direct method definition if there was one, or an unspecified value
+otherwise.
+
 %%%--------------------------------------------------------------------------
 \section{Metaclasses} \label{sec:concepts.metaclasses}
 
