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