X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/58f9b4000fb24a363ba8843ce999e8b9a27c4052..781a8fbd66088ce2eb16776fd951f8b79732d69c:/doc/concepts.tex

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 51cca98..1a84b88 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -195,7 +195,7 @@ It works as follows.
   earliest position in these candidate merges at which they disagree.  The
   \emph{candidate classes} at this position are the classes appearing at this
   position in the candidate merges.  Each candidate class must be a
-  superclass of exactly one of $C$'s direct superclasses, since otherwise the
+  superclass of distinct direct superclasses of $C$, since otherwise the
   candidates would be ordered by their common subclass's class precedence
   list.  The class precedence list contains, at this position, that candidate
   class whose subclass appears earliest in $C$'s local precedence order.
@@ -208,8 +208,8 @@ a link superclass, and the link superclass of a class $C$, if it exists, need
 not be a direct superclass of $C$.
 
 Superclass links must obey the following rule: if $C$ is a class, then there
-must be no three superclasses $X$, $Y$ and~$Z$ of $C$ such that both $Z$ is
-the link superclass of both $X$ and $Y$.  As a consequence of this rule, the
+must be no three superclasses $X$, $Y$ and~$Z$ of $C$ such that $Z$ is the
+link superclass of both $X$ and $Y$.  As a consequence of this rule, the
 superclasses of $C$ can be partitioned into linear \emph{chains}, such that
 superclasses $A$ and $B$ are in the same chain if and only if one can trace a
 path from $A$ to $B$ by following superclass links, or \emph{vice versa}.
@@ -251,7 +251,7 @@ sets the slots of a \emph{direct} instance of the class to the correct
 initial values.  If several of $C$'s superclasses define initializers for the
 same slot then the initializer from the most specific such class is used.  If
 none of $C$'s superclasses define an initializer for some slot then that slot
-will not be initialized.
+will be left uninitialized.
 
 The initializer for a slot with scalar type may be any C expression.  The
 initializer for a slot with aggregate type must contain only constant
@@ -371,21 +371,22 @@ 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}
 
@@ -412,7 +413,8 @@ There are three main cases to distinguish.
   conversion can fail: the object in question might not be an instance of~$B$
   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.
+  pointer if the conversion fails.  (There are therefore your analogue to the
+  \Cplusplus @|dynamic_cast<>| operator.)
 \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$
@@ -431,6 +433,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
@@ -495,13 +538,11 @@ 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,
-called @|primary| (the default), @|before|, @|after|, and @|around|.
+called `primary' (the default), @|before|, @|after|, and @|around|.
 
 All direct methods subject to the standard method combination must have
 argument lists which \emph{match} the message's argument list:
@@ -536,10 +577,13 @@ follows.
   returns; otherwise the behaviour of @|next_method| is to invoke the before
   methods (if any), followed by the most specific primary method, followed by
   the @|around| methods (if any), and to return whichever value was returned
-  by the most specific primary method.  That is, the behaviour of the least
-  specific @|around| method's @|next_method| function is exactly the
-  behaviour that the effective method would have if there were no @|around|
-  methods.
+  by the most specific primary method, as described in the following items.
+  That is, the behaviour of the least specific @|around| method's
+  @|next_method| function is exactly the behaviour that the effective method
+  would have if there were no @|around| methods.  Note that if the
+  least-specific @|around| method calls its @|next_method| more than once
+  then the whole sequence of @|before|, primary, and @|after| methods occurs
+  multiple times.
 
   The value returned by the most specific @|around| method is the value
   returned by the effective method.
@@ -575,7 +619,7 @@ A typical use for @|around| methods is to allow a base class to set up the
 dynamic environment appropriately for the primary methods of its subclasses,
 e.g., by claiming a lock, and restore it afterwards.
 
-The @|next_method| function provided to methods with the @|primary| and
+The @|next_method| function provided to methods with the primary and
 @|around| roles accepts the same arguments, and returns the same type, as the
 message, except that one or two additional arguments are inserted at the
 front of the argument list.  The first additional argument is always the
@@ -586,7 +630,7 @@ second additional argument; otherwise, In the former case, a variable
 of the argument pointer (so the method body can process the variable argument
 suffix itself, and still pass a fresh copy on to the next method).
 
-A method with the @|primary| or @|around| role may use the convenience macro
+A method with the primary or @|around| role may use the convenience macro
 @|CALL_NEXT_METHOD|, which takes no arguments itself, and simply calls
 @|next_method| with appropriate arguments: the receiver @|me| pointer, the
 argument pointer @|sod__master_ap| (if applicable), and the method's
@@ -594,9 +638,12 @@ 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}
+A primary or @|around| method which invokes its @|next_method| function is
+said to \emph{extend} the message behaviour; a method which does not invoke
+its @|next_method| is said to \emph{override} the behaviour.  Note that a
+method may make a decision to override or extend at runtime.
 
+\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
@@ -639,6 +686,41 @@ The aggregating method combinations provided are as follows.
 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}
 
