Various, style: Generally prefer `: ' over ` : '.

[sod] / lib / keyword.h

/* -*-c-*-
 *
 * Keyword argument handling
 *
 * (c) 2015 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * 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
 * 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
 * GNU Library General Public License for more details.
 *
 * 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.
 */

#ifndef KEYWORD_H
#define KEYWORD_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <stdarg.h>
#include <stddef.h>
#include <string.h>

/*----- Function annotations ----------------------------------------------*/

/* Some macros are defined for annotating functions.  They may improve
 * compiler diagnostics when used properly.  They should be included as part
 * of the function's declaration specifiers.
 *
 *   * @KWCALL@ marks a function as expecting keyword arguments.  The
 *     compiler may check that there are an odd number of arguments, that the
 *     even-numbered (starting from zero) arguments have pointer-to-character
 *     type, and that the final argument is null.
 *
 *   * @KW__NORETURN@ marks a function as never returning.  Applied to
 *     @kw_unknown@ and its various friends.  Users are not expected to use
 *     this.
 */

#if defined(__GNUC__)
#  define KW__GCC_VERSION_P(maj, min)					\
	(__GNUC__ > (maj) || (__GNUC__ == (maj) && __GNUC_MINOR__ >= (min)))
#  if KW__GCC_VERSION_P(2, 5)
#    define KW__NORETURN __attribute__((__noreturn__))
#  endif
#  if KW__GCC_VERSION_P(4, 0)
#    define KWCALL __attribute__((__sentinel__))
#  endif
#endif

/* --- Trivial definitions, if we don't have compiler support --- */

#ifndef KW__NORETURN
#  define KW__NORETURN
#endif

#ifndef KWCALL
#  define KWCALL
#endif

/*----- Type definitions --------------------------------------------------*/

/* A keyword/value pair.  A vector of these can be passed as the value of the
 * special keyword `kw.tab'.  This is a rather cumbersome way of constructing
 * lists of keyword arguments for a function in a programmatic way.
 */
struct kwval {
  const char *kw;			/* The keyword name, as a string */
  const void *val;			/* A pointer to the keyword value */
};

/* A table of keyword/value pairs.  This is used as the value of a `kw.tab'
 * argument which is itself in a @struct kwval@ table, since it's not
 * possible to store both the vector and length directly.
 */
struct kwtab {
  const struct kwval *v;		/* The address of the vector */
  size_t n;				/* The number of keywords */
};

/* The type of unknown-keyword handler functions. */
typedef void kw_unkhookfn(const char */*set*/, const char */*kw*/);

/*----- Global variables --------------------------------------------------*/

/* A global hook function for handling unknown-keyword errors.  The default
 * function prints a message to the standard error stream and aborts.
 *
 * The hook function must not return.  It's not possible to recover from an
 * unknown-keyword error while parsing a variable-length argument tail, since
 * it's impossible to find out what type the corresponding argument value is.
 *
 * Having a single global hook isn't really very satisfactory, but a fully
 * adequate solution gets complicated quickly.  An external library will
 * eventually be available to pick up the slack.
 */
extern kw_unkhookfn *kw_unkhook;

/*----- Argument list macros ----------------------------------------------*/

/* These macros are intended to be conveniences rather than a proper
 * abstraction.  Functions with more complicated interfaces, and their
 * callers, will have to make their own arrangements.
 */

/* --- @KWTAIL@ --- *
 *
 * Arguments:	---
 *
 * Use:		Marker to be included in a function prototype (at the end of
 *		the argument list) to indicate that the function accepts
 *		keyword arguments.  It is acceptable for the @KWTAIL@ marker
 *		to be only thing in the argument list.
 */

#define KWTAIL const char *kwfirst_, ...

/* --- @KWARGS@ --- *
 *
 * Arguments:	@body@ = a sequence of @K(kw, value)@ macro calls, without
 *			separators
 *
 * Use:		A package of actual keyword arguments.  In C89, the @body@
 *		must not be empty: to pass no keywords, use @NO_KWARGS@
 *		instead.
 */

#define KWARGS(body) body KW__END
#define KW__END ((const char *)0)

/* --- @NO_KWARGS@ --- *
 *
 * Arguments:	---
 *
 * Use:		Special marker to include in an actual argument list to
 *		indicate that no keyword arguments are to be passed.  See
 *		@KWARGS@ above.
 */

#define NO_KWARGS KW__END, KW__END
  /* Slight hack.  The @KWCALL@ macro sets GCC and similar compilers up to
   * check for a sentinal null pointer at the end of the variable-length
   * argument tail.  Alas, if there are no keywords at all, then the null
   * terminator ends up in the @kwfirst_@ argument, and the tail is propetly
   * empty, with the result that the compiler gives an annoying warning.
   * Supplying an extra argument here is obviously harmless, and makes the
   * otherwise useful warning go away in this case where it's not wanted.
   */

/* --- @K@ --- *
 *
 * Arguments:	@kw@ = keyword name, as an unquoted token list
 *		@val@ = keyword value, as an expression
 *
 * Use:		Bundles a keyword @kw@ and value @val@ together.
 */

#define K(kw, val) #kw, (val),

/* --- @KW_VALIST@ --- *
 *
 * Arguments:	@va_list ap@ = argument-list extraction state
 *
 * Use:		Passes a reified variable-length argument tail into a keyword
 *		function.
 */

#define K_VALIST(ap) "kw.valist", &(ap),

/* --- @KW_TAB@ --- *
 *
 * Arguments:	@const struct kwval *v@ = base address of argument vector
 *		@size_t n@ = length of argument vector
 *
 * Use:		Passes an vector of keyword arguments into a keyword
 *		function.
 */

#define K_TAB(v, n) "kw.tab", (v), (size_t)(n),

/*----- Keyword set definitions -------------------------------------------*
 *
 * A `keyword set' describes the collection of keyword arguments to be
 * accepted by a function (or group of functions).  Keyword sets have names,
 * which are C identifiers.  A keyword set must not be empty: use
 * @kw_parseempty@ instead of this machinery when defining a function which
 * may later accept keyword arguments but which currently doesn't define any.
 *
 * A keyword set definition is a macro of a single argument, conventionally
 * named `@_@'.  The macro for a keyword set called @foo@ is named
 * @foo_KWSET@.  It should consist of a triple @_(type, key, dflt)@ for each
 * keyword argument, where @type@ is the C type of the argument, @key@ is the
 * name of the argument (as a C identifier), and @dflt@ is an expression
 * (valid to use in an aggregate initializer) to provide the default value
 * for the argument.  The @type@ must be such that @type *@ is the type of a
 * pointer to object of @type@.
 */

/* --- @KWSET_STRUCT@ --- *
 *
 * Arguments:	@set@ = the keyword set name
 *
 * Use:		Defines the keyword set argument structure @struct
 *		set_kwargs@.
 *
 *		The structure is used to communicate argument values between
 *		a function accepting keyword arguments and the argument
 *		parsing function constructed by @KWSET_PARSEFN@.  It contains
 *		two members for each keyword argument: one with the name of
 *		the argument and the appropriate type to hold its value; the
 *		other is a one-bit-wide bitfield named with a `_suppliedp'
 *		suffix, and is set to indicate whether the caller provided a
 *		a value for the corresponding keyword argument.
 */

#define KWSET_STRUCT(set)						\
  struct set##_kwargs {							\
    set##_KWSET(KWSET__SUPPLIEDP)					\
    set##_KWSET(KWSET__STRUCTMEM)					\
  }
#define KWSET__SUPPLIEDP(type, name, dflt) unsigned name##_suppliedp: 1;
#define KWSET__STRUCTMEM(type, name, dflt) type name;

/* --- @KWSET_PARSEFN@ --- *
 *
 * Arguments:	@set@ = the keyword set name
 *
 * Use:		Defines the keyword argument parsing function @set_kwparse@.
 *		A call to this macro may be preceded by a storage-class
 *		specifier, e.g., @static@, to specify the linkage for the
 *		parsing function's name.
 *
 *		This function takes five arguments:
 *
 *		@struct set_kwargs *kw@ = pointer to keyword set argument
 *			structure to fill in
 *		@const char *kwfirst@ = first keyword argument name from the
 *			variable-length argument tail, or null if the
 *			argument tail is empty
 *		@va_list *ap@ = pointer to variable-length tail extraction
 *			state object
 *		@const struct kwval *v@ = base address of argument vector
 *		@size_t n@ = length of argument vector
 *
 *		The `kwparse' function extracts keyword arguments from the
 *		argument tail (via @*ap@), and then the vector @v@; it
 *		updates the structure @*kw@ with their values, and sets the
 *		`_suppliedp' flags accordingly.  It's unusual to call the
 *		`kwparse' function with both a nontrivial argument tail and
 *		vector, but the effect is nonetheless well-defined.
 *
 *		The argument tail consists of alternating keyword argument
 *		names (as pointers to null-terminated strings) and values,
 *		terminated by a null pointer.  The argument values are simply
 *		copied into the structure.  Passing the @kwfirst@ argument
 *		separately allows functions to declare an explicit positional
 *		argument for the first keyword name, which is useful if the
 *		function has no other positional arguments.
 *
 *		The argument vector consists of @struct kwval@ items, each of
 *		which contains a keyword name (as a pointer to a null-
 *		terminated string) and the address of its value.  Argument
 *		values are again copied into the structure.  Note that a
 *		vector doesn't store the arguments directly.  This makes them
 *		rather cumbersome to set up, but the benefit is a simple and
 *		uniform approach for all keyword arguments.
 *
 *		The main application for argument vectors is for `front-end'
 *		functions which want to pass on some subset of their keywords
 *		to another function.  There isn't currently any macrology
 *		provided for achieving this, but it's not especially
 *		difficult.
 *
 *		There are (currently) two special keyword arguments, whose
 *		names are not valid identifiers.  Future additions will also
 *		have names beginning `kw.'.
 *
 *		  * `kw.valist' -- the corresponding argument has type
 *		    @va_list *@, and represents an entire variable-length
 *		    argument tail to process, including the first keyword
 *		    name.
 *
 *		  * `kw.tab' -- the corresponding argument is a vector of
 *		    @struct kwval@ items to process.  In a variable-length
 *		    argument tail, this is passed as two arguments: the base
 *		    address of the vector, and the length (as a @size_t@).
 *		    In an argument vector, this is passed instead as a value
 *		    of type @struct kwtab@.
 *
 *		If an unknown keyword is encountered while parsing, the
 *		function @kw_unknown@ is called.
 *
 *		The keyword argument `kw.unknown' will never be defined.
 */

#define KWSET_PARSEFN(set)						\
  void set##_kwparse(struct set##_kwargs *kw,				\
		     const char *kwfirst, va_list *ap,			\
		     const struct kwval *v, size_t n)			\
  {									\
    const char *k, *kk;							\
    va_list *aap;							\
    const struct kwtab *t;						\
    const struct kwval *vv;						\
    size_t nn;								\
									\
    for (k = kwfirst; k; k = va_arg(*ap, const char *)) {		\
      if (!strcmp(k, "kw.valist")) {					\
	aap = va_arg(*ap, va_list *);					\
	kk = va_arg(*aap, const char *);				\
	set##_kwparse(kw, kk, aap, 0, 0);				\
      } else if (!strcmp(k, "kw.tab")) {				\
	vv = va_arg(*ap, const struct kwval *);				\
	nn = va_arg(*ap, size_t);					\
	set##_kwparse(kw, 0, 0, vv, nn);				\
      }									\
      set##_KWSET(KWSET__ARGVA)						\
      else kw_unknown(#set, k);						\
    }									\
									\
    while (n) {								\
      if (!strcmp(v->kw, "kw.valist")) {				\
	aap = *(va_list *const *)v->val;				\
	kk = va_arg(*aap, const char *);				\
	set##_kwparse(kw, kk, aap, 0, 0);				\
      } else if (!strcmp(v->kw, "kw.tab")) {				\
	t = (const struct kwtab *)v->val;				\
	set##_kwparse(kw, 0, 0, t->v, t->n);				\
      }									\
      set##_KWSET(KWSET__ARGTAB)					\
      else kw_unknown(#set, v->kw);					\
      v++; n--;								\
    }									\
  }
#define KWSET__ARGVA(type, name, dflt)					\
  else if (!strcmp(k, #name)) {						\
    kw->name##_suppliedp = 1;						\
    kw->name = va_arg(*ap, type);					\
  }
#define KWSET__ARGTAB(type, name, dflt)					\
  else if (!strcmp(v->kw, #name)) {					\
    kw->name##_suppliedp = 1;						\
    kw->name = *(type const *)v->val;					\
  }

/*----- Defining keyword-accepting functions ------------------------------*/

/* --- @KWDECL@ --- *
 *
 * Arguments:	@set@ = the keyword set name
 *		@kw@ = the name for the keyword argument structure value
 *
 * Use:		Declares and initializes a keyword argument structure object
 *		@kw@.  The `_suppliedp' members are initially all zero; the
 *		argument value members are set to their default values as
 *		specified in the keyword set definition macro.
 */

#define KWDECL(set, kw)							\
  struct set##_kwargs kw =						\
    { set##_KWSET(KWSET__SPINIT) set##_KWSET(KWSET__DFLT) }
#define KWSET__SPINIT(type, name, dflt) 0,
#define KWSET__DFLT(type, name, dflt) dflt,

/* --- @KW_PARSE@, @KW_PARSE_EMPTY@ --- *
 *
 * Arguments:	@set@ = the keyword set name
 *		@kw@ = the name of the keyword argument structure
 *		@kwfirst@ = the first keyword argument name from the
 *			variable-length argument tail (and, therefore, the
 *			final positional argument)
 *
 * Use:		Invokes the appropriate `kwparse' function to process the
 *		function's variable-length argument tail as keyword
 *		arguments.
 *
 *		It is recommended that functions avoid allocating resources
 *		or making observable changes to program state until they have
 *		successfully parsed their keyword arguments.
 *
 *		It is not possible to define an empty keyword argument set.
 *		If a function currently accepts no keyword argumets, but
 *		wants to reserve the ability to accept them later, then it
 *		should use @KW_PARSE_EMPTY@ (or, better, @KWPARSE_EMPTY@
 *		below).  The keyword argument set name here is used only for
 *		diagnostic purposes, and need not (and probably should not)
 *		correspond to a keyword-set definition macro.
 */

#define KW_PARSE(set, kw, kwfirst) do {					\
  va_list ap_;								\
  va_start(ap_, kwfirst);						\
  set##_kwparse(&(kw), kwfirst, &ap_, 0, 0);				\
  va_end(ap_);								\
} while (0)

#define KW_PARSE_EMPTY(set, kwfirst) do {				\
  va_list ap_;								\
  va_start(ap_, kwfirst);						\
  kw_parseempty(#set, kwfirst, &ap, 0, 0);				\
  va_end(ap_);								\
} while (0)

/* --- @KWPARSE@, @KWPARSE_EMPTY@ --- *
 *
 * Arguments:	@set@ = the keyword set name
 *
 * Use:		All-in-one keyword parsing for simple cases.
 *
 *		This declares a keyword argument structure literally named
 *		@kw@, and parses the function's variable-length argument tail
 *		on the assumption that the function's argument list prototype
 *		contains a @KWTAIL@ marker.
 *
 *		It is recommended that functions avoid allocating resources
 *		or making observable changes to program state until they have
 *		successfully parsed their keyword arguments.
 *
 *		In C89, this macro must be placed precisely between the
 *		declarations at the start of the function body, and the
 *		statements after them.
 *
 *		It is not possible to define an empty keyword argument set.
 *		If a function currently accepts no keyword argumets, but
 *		wants to reserve the ability to accept them later, then it
 *		should use @KWPARSE_EMPTY@.  The keyword argument set name
 *		here is used only for diagnostic purposes, and need not (and
 *		probably should not) correspond to a keyword-set definition
 *		macro.
 */

#define KWPARSE(set) KWDECL(set, kw); KW_PARSE(set, kw, kwfirst_)

#define KWPARSE_EMPTY(set) KW_PARSE_EMPTY(set, kwfirst_)

/* --- @KW_COUNT@ --- *
 *
 * Arguments:	@set@ = the keyword set name
 *
 * Use:		Expands to the number of keywords defined in the @set@.
 */

#define KW_COUNT(set) (0u set##_KWSET(KW__COUNT))
#define KW__COUNT(type, name, dflt) + 1u

/* --- @KW_COPY@ --- *
 *
 * Arguments:	@fromset@ = the source keyword set name
 *		@toset@ = the destination keyword set name
 *		@kw@ = the source keyword argument structure
 *		@v@ = the destination vector
 *		@n@ = next free index in vector
 *
 * Use:		Copies arguments from the source structure @kw@ into the
 *		vector @v@.  The structure @kw@ must have type @struct
 *		fromset_kwargs *@.  The argument @v@ must have type @struct
 *		kwval *@ (after array-to- pointer decay), and there must be a
 *		variable @v_n@ of sufficiently large integral type suitably
 *		initialized.  Elements of the vector, starting with element
 *		@n@, will be filled in with those keyword arguments defined
 *		in @toset@ -- which must be a subset of @srcsrc@ from @kw@
 *		for which the `_suppliedp' flags are set.  The @val@ members
 *		will point directly into the @kw@ structure.  The @n@
 *		counter will be updated, and on completion will contain the
 *		index of the first unused entry in the vector.
 */

#define KW_COPY(fromset, toset, kw, v, n) do {				\
  const struct fromset##_kwargs *kw_ = &(kw);				\
  struct kwval *v_ = (v);						\
  size_t n_ = (n);							\
  toset##_KWSET(KW__COPY)						\
  (n) = n_;								\
} while (0)

#define KW__COPY(type, name, dflt)					\
  if (kw_->name##_suppliedp) {						\
    v_[n_].kw = #name;							\
    v_[n_].val = &kw_->name;						\
    n_++;								\
  }

/*----- Functions provided ------------------------------------------------*/

/* --- @kw_unknown@ --- *
 *
 * Arguments:	@const char *set@ = the keyword set name, as a string
 *		@const char *kw@ = the unknown keyword argument, as a string
 *
 * Returns:	Doesn't.
 *
 * Use:		Called when an unrecognized keyword argument is encountered
 *		during parsing.  This calls the @kw_unkhook@ with the same
 *		arguments. Recovery via @longjmp@ or a similar machanism is
 *		acceptable.
 */

extern KW__NORETURN void kw_unknown(const char */*set*/, const char */*kw*/);

/* --- @kw_defunknown@ --- *
 *
 * Arguments:	@const char *set@ = keyword set name
 *		@const char *kw@ = the offending keyword name
 *
 * Returns:	Doesn't.
 *
 * Use:		This is the default @kw_unkhook@ hook function.
 *
 *		In a hosted implementation, this function reports an internal
 *		error to stderr about the unknown keyword and calls @abort@.
 *		It is an implementation responsibility for freestanding
 *		implementations wanting to use this keyword argument
 *		mechanism.
 */

extern KW__NORETURN kw_unkhookfn kw_defunknown;

/* --- @kw__hookfailed@ --- *
 *
 * Arguments:	---
 *
 * Returns:	Doesn't.
 *
 * Use:		Called by @kw_unknown@ if the @kw_unkhook@ hook function
 *		returns.
 *
 *		User code is not expected to call this function.  It exists
 *		as an implementation respensibility for freestanding
 *		implementations wanting to use this keyword argument
 *		mechanism.
 */

extern KW__NORETURN void kw__hookfailed(void);

/* --- @kw_parseempty@ --- *
 *
 * Arguments:	@const char *set@ = the keyword set name, as a string
 *		@const char *kwfirst@ = the first keyword argument name
 *		@va_list *ap@ = pointer to argument-tail extraction state
 *		@const struct kwval *v@ = base address of argument vector
 *		@size_t n@ = size of argument vector
 *
 * Returns:	---
 *
 * Use:		Goes through the motions of parsing keyword arguments, but
 *		doesn't in fact handle any other than the standard ones
 *		described above (see @KWSET_PARSEFN@).  This is useful when a
 *		function doesn't currently define any keyword arguments but
 *		wants to reserve the right to define some in the future.
 *		(The usual machinery can't be used in this case, since the
 *		argument structure would be empty.  Besides, it would be
 *		pointless to include multiple copies of the same boilerplate
 *		code in a program.)
 */

extern void kw_parseempty(const char */*set*/,
			  const char */*kwfirst*/, va_list */*ap*/,
			  const struct kwval */*v*/, size_t /*n*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif