lib/: Pure C machinery for handling `keyword arguments' to functions.

[sod] / doc / concepts.tex

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 20402dc0807aa3e1a0b80cc763b27525f8f9e3e7..8a8eb02fa2f3ca4f5a6f865612f6606440060b0c 100644 (file)
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -431,6 +431,45 @@ nickname @|super|, then the macro @|MYCLASS__CONV_SUPER| converts a
 @|MyClass~*| to a @|SuperClass~*|.  See
 \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.
+
 %%%--------------------------------------------------------------------------
 \section{Messages and methods} \label{sec:concepts.methods}