[mLib] / test / tvec.h

/* -*-c-*-
 *
 * Test vector processing framework
 *
 * (c) 2023 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the mLib utilities library.
 *
 * mLib 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.
 *
 * mLib 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 mLib.  If not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
 * USA.
 */

#ifndef MLIB_TVEC_H
#define MLIB_TVEC_H

#ifdef __cplusplus
  extern "C" {
#endif

/* Here's the overall flow for a testing session.
 *
 * @tvec_begin@
 *                      -> output @bsession@
 * @tvec_read@
 *                      -> output @bgroup@
 *                      -> env @setup@
 *   one or more tests
 *                      -> type @init@ (input and output)
 *                      -> type @parse@ (input)
 *                      -> output @btest@
 *                      -> env @before@
 *                              -> @tvec_skipgroup@
 *                                      -> output @skipgroup@
 *                      -> env @run@
 *                              -> @tvec_skip@
 *                                      -> output @skip@
 *                              -> test @fn@
 *                              -> @tvec_checkregs@
 *                                      -> type @eq@
 *                              -> @tvec_fail@
 *                                      -> output @fail@
 *                              -> @tvec_mismatch@
 *                                      -> output @dumpreg@
 *                                              -> type @dump@
 *                      -> output @etest@
 *                      -> env @after@
 *   finally
 *                      -> output @egroup@
 *                      -> env @teardown@
 *
 * Ad-hoc testing
 *   @tvec_begingroup@
 *                      -> output @bgroup@
 *                      -> env @setup@
 *     @tvec_begintest@
 *                      -> output @btest@
 *     @tvec_skip@
 *                      -> output @skip@
 *     @tvec_claimeq@
 *                      -> @tvec_fail@
 *                              -> output @fail@
 *                      -> @tvec_mismatch@
 *                              -> output @dumpreg@
 *                              -> type @dump@
 *     @tvec_endtest@
 *                      -> output @etest@
 *     or @tvec_skipgroup@
 *                      -> output @skipgroup@
 * @tvec_endgroup@
 *                      -> output @egroup@
 *
 * @tvec_end@
 *                      -> output @esession@
 *                      -> output @destroy@
 *
 * @tvec_benchrun@
 *                      -> type @dump@ (compact style)
 *                      -> output @bbench@
 *                      -> subenv @run@
 *                              -> test @fn@
 *                      -> output @ebench@
 *                              -> @tvec_benchreport@
 *
 * The output functions @error@ and @notice@ can be called at arbitrary
 * times.
 */

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

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

#ifndef MLIB_ARENA_H
#  include "arena.h"
#endif

#ifndef MLIB_BUF_H
#  include "buf.h"
#endif

#ifndef MLIB_DSTR_H
#  include "dstr.h"
#endif

#ifndef MLIB_GPRINTF_H
#  include "gprintf.h"
#endif

#ifndef MLIB_MACROS_H
#  include "macros.h"
#endif

/*----- Miscellaneous values ----------------------------------------------*/

/* These are attached to structures which represent extension points, as a
 * way to pass an opaque parameter to whatever things are hooked onto them.
 */

#define TVEC_MISCSLOTS(_)                                               \
        _(PTR, const void *, p)         /* arbitrary pointer */         \
        _(INT, long, i)                 /* signed integer */            \
        _(UINT, unsigned long, u)       /* signed integer */            \
        _(FLT, double, f)               /* floating point */

union tvec_misc {
#define TVEC_DEFSLOT(tag, ty, slot) ty slot;
  TVEC_MISCSLOTS(TVEC_DEFSLOT)
#undef TVEC_DEFSLOT
};
enum {
#define TVEC_DEFCONST(tag, ty, slot) TVMISC_##tag,
  TVEC_MISCSLOTS(TVEC_DEFCONST)
  TVMISC_LIMIT
};

/*----- Register values ---------------------------------------------------*/

/* The framework doesn't have a preconceived idea about what's in a register
 * value: it just allocates them and accesses them through the register type
 * functions.  It doesn't even have a baked-in idea of how big a register
 * value is: instead, it gets that via the `regsz' slot in `struct
 * tvec_testinfo'.  So, as far as the framework is concerned, it's safe to
 * add new slots to this union, even if they make the overall union larger.
 * This can be done by defining the preprocessor macro `TVEC_REGSLOTS' to be
 * a `union' fragment defining any additional union members.
 *
 * This creates a distinction between code which does and doesn't know the
 * size of a register value.  Code which does, which typically means the test
 * functions, benchmarking setup and teardown functions, and tightly-bound
 * runner functions, is free to index the register vectors directly.  Code
 * which doesn't, which means the framework core itself and output formatting
 * machinery, must use the `TVEC_REG' macro (or its more general `TVEC_GREG'
 * companion) for indexing register vectors.  (In principle, register type
 * handlers also fit into this category, but they have no business peering
 * into register values other than the one's they're given.)
 */

union tvec_regval {
  /* The actual register value.  This is what the type handler sees.
   * Additional members can be added by setting `TVEC_REGSLOTS' before
   * including this file.
   *
   * A register value can be /initialized/, which simply means that its
   * contents represent a valid value according to its type -- the register
   * can be compared, dumped, serialized, parsed into, etc.  You can't do
   * anything safely to an uninitialized register value other than initialize
   * it.
   */

  long i;                               /* signed integer */
  unsigned long u;                      /* unsigned integer */
  void *p;                              /* pointer */
  double f;                             /* floating point */
  struct { char *p; size_t sz; } text;  /* text string */
  struct { unsigned char *p; size_t sz; } bytes; /* binary string of bytes */
  struct {                              /* buffer */
    unsigned char *p; size_t sz;        /* binary string */
    size_t a, m;                        /* residue and modulus */
    size_t off;                         /* offset into full buffer */
  } buf;
#ifdef TVEC_REGSLOTS
  TVEC_REGSLOTS
#endif
};

struct tvec_reg {
  /* A register.
   *
   * Note that all of the registers listed as being used by a particular test
   * group are initialized at all times[1] while that test group is being
   * processed.  (The other register slots don't even have types associated
   * with them, so there's nothing useful we could do with them.)
   *
   * The `TVRF_LIVE' flag indicates that the register was assigned a value by
   * the test vector file: it's the right thing to use to check whether an
   * optional register is actually present.  Even `dead' registers are still
   * initialized, though.
   *
   * [1] This isn't quite true.  Between individual tests, the registers are
   *     released and reinitialized in order to reset them to known values
   *     ready for the next test.  But you won't see them at this point.
   */

  unsigned f;                           /* flags */
#define TVRF_SEEN 1u                    /*   assignment seen in file  */
#define TVRF_LIVE 2u                    /*   used in current test  */
  union tvec_regval v;                  /* register value */
};

struct tvec_regdef {
  /* A register definition.  Register definitions list the registers which
   * are used by a particular test group (see `struct tvec_test' below).
   *
   * A vector of register definitions is terminated by a definition whose
   * `name' slot is null.
   */

  const char *name;                     /* register name (for input files) */
  const struct tvec_regty *ty;          /* register type descriptor */
  unsigned i;                           /* register index */
  unsigned f;                           /* flags */
#define TVRF_UNSET 1u                   /*   register may be marked unset */
#define TVRF_OPT 2u                     /*   register need not be assigned */
#define TVRF_ID 4u                      /*   part of test identity  */
  union tvec_misc arg;                  /* extra detail for the type */
};
#define TVEC_ENDREGS { 0, 0, 0, 0, { 0 } }

/* @TVEC_GREG(vec, i, regsz)@
 *
 * If @vec@ is a data pointer which happens to contain the address of a
 * vector of @struct tvec_reg@ objects, @i@ is an integer, and @regsz@ is the
 * size of a @struct tvec_reg@, then this evaluates to the address of the
 * @i@th element of the vector.
 *
 * This is the general tool you need for accessing register vectors when you
 * don't have absolute knowledge of the size of a @union tvec_regval@.
 * Usually you want to access one of the register vectors in a @struct
 * tvec_state@, and @TVEC_REG@ will be more convenient.
 */
#define TVEC_GREG(vec, i, regsz)                                        \
        ((struct tvec_reg *)((unsigned char *)(vec) + (i)*(regsz)))

/*----- Register types ----------------------------------------------------*/

struct tvec_state;                      /* forward declaration */

struct tvec_regty {
  /* A register type. */

  void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
    /* Initialize the value in @*rv@.  This will be called before any other
     * function acting on the value, including @release@.  Following @init@,
     * the register value must be valid to use for all other type entry
     * points.
     */

  void (*release)(union tvec_regval */*rv*/,
                  const struct tvec_regdef */*rd*/);
    /* Release any resources associated with the value in @*rv@.  The
     * register value may be left in an invalid state.
     */

  int (*eq)(const union tvec_regval */*rv0*/,
            const union tvec_regval */*rv1*/,
            const struct tvec_regdef */*rd*/);
    /* Return nonzero if @*rv0@ and @*rv1@ are equal values.  Asymmetric
     * criteria are permitted: @tvec_checkregs@ calls @eq@ with the input
     * register as @rv0@ and the output as @rv1@.
     */

  int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
               const struct tvec_regdef */*rd*/);
    /* Serialize the value @*rv@, writing the result to @b@.  Return zero on
     * success, or %$-1$% on error.
     */

  int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
                 const struct tvec_regdef */*rd*/);
    /* Deserialize a value from @b@, storing it in @*rv@.  Return zero on
     * success, or %$-1$% on error.
     */

  int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
               struct tvec_state */*tv*/);
    /* Parse a value from @tv->fp@, storing it in @*rv@.  Return zero on
     * success, or %$-1$% on error, having reported one or more errors via
     * @tvec_error@ or @tvec_syntax@.  If @TVSF_NEXT@ is not set on exit,
     * then the caller will advance to the start of the next non-continuation
     * line, reporting an error it any non-whitespace non-comment material
     * found following a successful return.
     */

  void (*dump)(const union tvec_regval */*rv*/,
               const struct tvec_regdef */*rd*/,
               unsigned /*style*/,
               const struct gprintf_ops */*gops*/, void */*go*/);
#define TVSF_COMPACT 1u
#define TVSF_RAW 2u
    /* Write a human-readable representation of the value @*rv@ using
     * @gprintf@ on @gops@ and @go@.  The @style@ is a collection of flags:
     * if @TVSF_COMPACT@ is set, then output should be minimal, and must fit
     * on a single line; otherwise, output may consist of multiple lines and
     * may contain redundant information if that is likely to be useful to a
     * human reader.  If @TVSF_RAW@ is set, then output should prefer
     * machine-readability over human-readability.
     */
};

/*----- Test descriptions -------------------------------------------------*/

struct tvec_env;

typedef void tvec_testfn(const struct tvec_reg */*in*/,
                         struct tvec_reg */*out*/,
                         void */*ctx*/);
  /* A test function.  It should read inputs from @in@ and write outputs to
   * @out@.  The @TVRF_LIVE@ is set on inputs which are actually present, and
   * on outputs which are wanted to test.  A test function can set additional
   * `gratuitous outputs' by setting @TVRF_LIVE@ on them; clearing
   * @TVRF_LIVE@ on a wanted output causes a mismatch.
   *
   * A test function may be called zero or more times by the environment.  In
   * particular, it may be called multiple times, though usually by prior
   * arrangement with the environment.
   *
   * The @ctx@ is supplied by the environment's @run@ function (see below).
   * The default environment calls the test function once, with a null
   * @ctx@.  There is no expectation that the environment's context has
   * anything to do with the test function's context.
   */

typedef int tvec_setvarfn(struct tvec_state */*tv*/, const char */*var*/,
                          const union tvec_regval */*rv*/, void */*ctx*/);
  /* Called after a variable is read.  Return zero on success or %$-1$% on
   * error.  This function is never called if the test group is skipped.
   */

struct tvec_vardef {
  size_t regsz;                         /* (minimum) register size */
  tvec_setvarfn *setvar;                /* function to set variable */
  struct tvec_regdef def;               /* register definition */
};

typedef void tvec_envsetupfn(struct tvec_state */*tv*/,
                             const struct tvec_env */*env*/,
                             void */*pctx*/, void */*ctx*/);
  /* Initialize the context; called at the start of a test group; @pctx@ is
   * null for environments called by the core, but may be non-null for
   * subordinate environments.  If setup fails, the function should call
   * @tvec_skipgroup@ with a suitable excuse.  The @set@, @after@, and
   * @teardown@ entry points will still be called, but @before@ and @run@
   * will not.
   */

typedef const struct tvec_vardef *tvec_envfindvarfn
  (struct tvec_state */*tv*/, const char */*name*/,
   void **/*ctx_out*/, void */*ctx*/);
  /* Called when the parser finds a %|@var|%' special variable.  If a
   * suitable variable was found, set @*ctx_out@ to a suitable context and
   * return the variable definition; the context will be passed to the
   * variable definition's @setvar@ function.  If no suitable variable was
   * found, then return null.
   */

typedef void tvec_envbeforefn(struct tvec_state */*tv*/, void */*ctx*/);
  /* Called prior to running a test.  This is the right place to act on any
   * `%|@var|%' settings.  If preparation fails, the function should call
   * @tvec_skip@ with a suitable excuse.  This function is never called if
   * the test group is skipped.  It %%\emph{is}%% called if the test will be
   * skipped due to erroneous test data.  It should check the @TVSF_ACTIVE@
   * flag if necessary.
   */

typedef void tvec_envrunfn(struct tvec_state */*tv*/,
                           tvec_testfn */*fn*/, void */*ctx*/);
  /* Run the test.  It should either call @tvec_skip@, or run @fn@ one or
   * more times.  In the latter case, it is responsible for checking the
   * outputs, and calling @tvec_fail@ as necessary; @tvec_checkregs@ will
   * check the register values against the supplied test vector, while
   * @tvec_check@ does pretty much everything necessary.  This function is
   * never called if the test group is skipped.
   */

typedef void tvec_envafterfn(struct tvec_state */*tv*/, void */*ctx*/);
  /* Called after running or skipping a test.  Typical actions involve
   * resetting whatever things were established by @set@.  This function
   * %%\emph{is}%% called if the test group is skipped or the test data is
   * erroneous, so that the test environment can reset variables set by the
   * @set@ entry point.  It should check the @TVSF_SKIP@ flag if necessary.
   */

typedef void tvec_envteardownfn(struct tvec_state */*tv*/, void */*ctx*/);
  /* Tear down the environment: called at the end of a test group. */

struct tvec_env {
  /* A test environment sets things up for and arranges to run the test.
   *
   * The caller is responsible for allocating storage for the environment's
   * context, based on the @ctxsz@ slot, and freeing it later; this space is
   * passed in as the @ctx@ parameter to the remaining functions; if @ctxsz@
   * is zero then @ctx@ is null.
   */

  size_t ctxsz;                         /* environment context size */

  tvec_envsetupfn *setup;               /* setup for group */
  tvec_envfindvarfn *findvar;           /* find variable */
  tvec_envbeforefn *before;             /* prepare for test */
  tvec_envrunfn *run;                   /* run test function */
  tvec_envafterfn *after;               /* clean up after test */
  tvec_envteardownfn *teardown;         /* tear down after group */
};

struct tvec_test {
  /* A test description. */

  const char *name;                     /* name of the test */
  const struct tvec_regdef *regs;       /* descriptions of the registers */
  const struct tvec_env *env;           /* environment to run test in */
  tvec_testfn *fn;                      /* test function */
};

struct tvec_config {
  /* An overall test configuration. */

  const struct tvec_test *const *tests; /* the tests to be performed */
  unsigned nrout, nreg;                 /* number of output/total regs */
  size_t regsz;                         /* size of a register */
};

/*----- Test state --------------------------------------------------------*/

struct tvec_output;

enum {
  /* Possible test outcomes. */

  TVOUT_LOSE,                           /* test failed */
  TVOUT_SKIP,                           /* test skipped */
  TVOUT_XFAIL,                          /* test passed, but shouldn't have */
  TVOUT_WIN,                            /* test passed */
  TVOUT_LIMIT                           /* (number of possible outcomes) */
};

struct tvec_state {
  /* The primary state structure for the test vector machinery. */

  /* Flags.  Read-only for all callers. */
  unsigned f;                           /* flags */
#define TVSF_SKIP 0x0001u               /*   skip this test group */
#define TVSF_OPEN 0x0002u               /*   test is open */
#define TVSF_ACTIVE 0x0004u             /*   test is active */
#define TVSF_ERROR 0x0008u              /*   an error occurred */
#define TVSF_OUTMASK 0x00f0u            /*   test outcome (@TVOUT_...@) */
#define TVSF_OUTSHIFT 4                 /*   shift applied to outcome */
#define TVSF_XFAIL 0x0100u              /*   test expected to fail */
#define TVSF_MUFFLE 0x0200u             /*   muffle errors */
#define TVSF_NEXT 0x0400u               /*   input at next definition */

  /* Memory allocation.  Read-only for all callers. */
  arena *a;

  /* Test configuration.  Read-only for all callers. */
  struct tvec_config cfg;               /* test configuration */

  /* Registers.  Available to execution environments, which may modify the
   * contents of the active registers, as defined by the current test group,
   * but not the vector pointers themselves or inactive registers.
   */
  struct tvec_reg *in, *out;            /* register vectors */

  /* Test group state.  Read-only for all callers. */
  const struct tvec_test *test;         /* current test */

  /* Test scoreboard.  Available to output formatters. */
  unsigned curr[TVOUT_LIMIT], all[TVOUT_LIMIT], grps[TVOUT_LIMIT];

  /* Output machinery.  Read-only for environments. */
  struct tvec_output *output;           /* output formatter */

  /* Input machinery.  Available to type parsers. */
  const char *infile; unsigned lno, test_lno; /* input file name, line */
  FILE *fp;                             /* input file stream */

  /* Adhoc testing state.  Private. */
  struct tvec_test adhoc_test;
  const struct tvec_test *adhoc_tests[];
};

/* @TVEC_REG(tv, vec, i)@
 *
 * If @tv@ is a pointer to a @struct tvec_state@, @vec@ is either @in@ or
 * @out@, and @i@ is an integer, then this evaluates to the address of the
 * @i@th register in the selected vector.
 */
#define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->cfg.regsz)

/*----- Session lifecycle -------------------------------------------------*/

/* --- @tvec_begin@ --- *
 *
 * Arguments:   @struct tvec_state *tv_out@ = state structure to fill in
 *              @const struct tvec_config *config@ = test configuration
 *              @struct tvec_output *o@ = output driver
 *
 * Returns:     ---
 *
 * Use:         Initialize a state structure ready to do some testing.  The
 *              test state takes ownership of the output driver: @tvec_end@
 *              will destroy it.
 */

extern void tvec_begin(struct tvec_state */*tv_out*/,
                       const struct tvec_config */*config*/,
                       struct tvec_output */*o*/);

/* --- @tvec_end@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     A proposed exit code.
 *
 * Use:         Conclude testing and suggests an exit code to be returned to
 *              the calling program.  (The exit code comes from the output
 *              driver's @esession@ method.)  The output driver, originally
 *              passed to @tvec_begin@ is destroyed.
 */

extern int tvec_end(struct tvec_state */*tv*/);

/* --- @tvec_read@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *infile@ = the name of the input file
 *              @FILE *fp@ = stream to read from
 *
 * Returns:     Zero on success, %$-1$% on error.
 *
 * Use:         Read test vector data from @fp@ and exercise test functions.
 *              THe return code doesn't indicate test failures: it's only
 *              concerned with whether there were problems with the input
 *              file or with actually running the tests.
 */

extern int tvec_read(struct tvec_state */*tv*/,
                     const char */*infile*/, FILE */*fp*/);

/*----- Command-line interface --------------------------------------------*/

/* --- @tvec_parseargs@ --- *
 *
 * Arguments:   @int argc@ = number of command-line arguments
 *              @char *argv[]@ = vector of argument strings
 *              @struct tvec_state *tv_out@ = test vector state to initialize
 *              @int *argpos_out@ = where to leave unread argument index
 *              @const struct tvec_config *config@ = test vector
 *                      configuration
 *
 * Returns:     ---
 *
 * Use:         Parse arguments and set up the test vector state @*tv_out@.
 *              If errors occur, print messages to standard error and exit
 *              with status 2.
 */

extern void tvec_parseargs(int /*argc*/, char */*argv*/[],
                           struct tvec_state */*tv_out*/,
                           int */*argpos_out*/,
                           const struct tvec_config */*config*/);

/* --- @tvec_readstdin@, @tvec_readfile@, @tvec_readarg@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test vector state
 *              @const char *file@ = pathname of file to read
 *              @const char *arg@ = argument to interpret
 *
 * Returns:     Zero on success, %$-1$% on error.
 *
 * Use:         Read test vector data from stdin or a named file.  The
 *              @tvec_readarg@ function reads from stdin if @arg@ is `%|-|%',
 *              and from the named file otherwise.
 */

extern int tvec_readstdin(struct tvec_state */*tv*/);
extern int tvec_readfile(struct tvec_state */*tv*/, const char */*file*/);
extern int tvec_readarg(struct tvec_state */*tv*/, const char */*arg*/);

/* --- @tvec_readdflt@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test vector state
 *              @const char *dflt@ = defsault filename or null
 *
 * Returns:     Zero on success, %$-1$% on error.
 *
 * Use:         Reads from the default test vector data.  If @file@ is null,
 *              then read from standard input, unless that's a terminal; if
 *              @file@ is not null, then read the named file, looking in the
 *              directory named by the `%|srcdir|%' environment variable if
 *              that's set, or otherwise in the current directory.
 */

extern int tvec_readdflt(struct tvec_state */*tv*/, const char */*file*/);

/* --- @tvec_readargs@ --- *
 *
 * Arguments:   @int argc@ = number of command-line arguments
 *              @char *argv[]@ = vector of argument strings
 *              @struct tvec_state *tv@ = test vector state
 *              @int *argpos_inout@ = current argument position (updated)
 *              @const char *dflt@ = default filename or null
 *
 * Returns:     Zero on success, %$-1$% on error.
 *
 * Use:         Reads from the sources indicated by the command-line
 *              arguments, in order, interpreting each as for @tvec_readarg@;
 *              if no arguments are given then read from @dflt@ as for
 *              @tvec_readdflt@.
 */

extern int tvec_readargs(int /*argc*/, char */*argv*/[],
                         struct tvec_state */*tv*/,
                         int */*argpos_inout*/, const char */*dflt*/);

/* --- @tvec_main@ --- *
 *
 * Arguments:   @int argc@ = number of command-line arguments
 *              @char *argv[]@ = vector of argument strings
 *              @const struct tvec_config *config@ = test vector
 *                      configuration
 *              @const char *dflt@ = default filename or null
 *
 * Returns:     Exit code.
 *
 * Use:         All-in-one test vector front-end.  Parse options from the
 *              command-line as for @tvec_parseargs@, and then process the
 *              remaining positional arguments as for @tvec_readargs@.  The
 *              function constructs and disposes of a test vector state.
 */

extern int tvec_main(int /*argc*/, char */*argv*/[],
                     const struct tvec_config */*config*/,
                     const char */*dflt*/);

/*----- Test processing ---------------------------------------------------*/

/* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *excuse@, @va_list *ap@ = reason why skipped
 *
 * Returns:     ---
 *
 * Use:         Skip the current group.  This should only be called from a
 *              test environment @setup@ function; a similar effect occurs if
 *              the @setup@ function fails.
 */

extern PRINTF_LIKE(2, 3)
  void tvec_skipgroup(struct tvec_state */*tv*/,
                      const char */*excuse*/, ...);
extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
                             const char */*excuse*/, va_list */*ap*/);

/* --- @tvec_skip@, @tvec_skip_v@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *excuse@, @va_list *ap@ = reason why test skipped
 *
 * Returns:     ---
 *
 * Use:         Skip the current test.  This should only be called from a
 *              test environment @run@ function; a similar effect occurs if
 *              the @before@ function fails.
 */

extern PRINTF_LIKE(2, 3)
  void tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
extern void tvec_skip_v(struct tvec_state */*tv*/,
                        const char */*excuse*/, va_list */*ap*/);

/* --- @tvec_fail@, @tvec_fail_v@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *detail@, @va_list *ap@ = description of test
 *
 * Returns:     ---
 *
 * Use:         Report the current test as a failure.  This function can be
 *              called multiple times for a single test, e.g., if the test
 *              environment's @run@ function invokes the test function
 *              repeatedly; but a single test that fails repeatedly still
 *              only counts as a single failure in the statistics.  The
 *              @detail@ string and its format parameters can be used to
 *              distinguish which of several invocations failed; it can
 *              safely be left null if the test function is run only once.
 */

extern PRINTF_LIKE(2, 3)
  void tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...);
extern void tvec_fail_v(struct tvec_state */*tv*/,
                        const char */*detail*/, va_list */*ap*/);

/* --- @tvec_dumpreg@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @unsigned disp@ = the register disposition (@TVRD_...@)
 *              @const union tvec_regval *tv@ = register value, or null
 *              @const struct tvec_regdef *rd@ = register definition
 *
 * Returns:     ---
 *
 * Use:         Dump a register value to the output.  This is the lowest-
 *              level function for dumping registers, and calls the output
 *              formatter directly.
 *
 *              Usually @tvec_mismatch@ is much more convenient.  Low-level
 *              access is required for reporting `virtual' registers
 *              corresponding to test environment settings.
 */

extern void tvec_dumpreg(struct tvec_state */*tv*/,
                         unsigned /*disp*/, const union tvec_regval */*rv*/,
                         const struct tvec_regdef */*rd*/);

/* --- @tvec_initregs@, @tvec_releaseregs@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     ---
 *
 * Use:         Initialize or release, respectively, the registers required
 *              by the current test.  All of the registers, both input and
 *              output, are effected.  Initialized registers are not marked
 *              live.
 */

extern void tvec_initregs(struct tvec_state */*tv*/);
extern void tvec_releaseregs(struct tvec_state */*tv*/);

/* --- @tvec_resetoutputs@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     ---
 *
 * Use:         Reset (releases and reinitializes) the output registers in
 *              the test state.  This is mostly of use to test environment
 *              @run@ functions, between invocations of the test function.
 *              Output registers are marked live if and only if the
 *              corresponding input register is live.
 */

extern void tvec_resetoutputs(struct tvec_state */*tv*/);

/* --- @tvec_checkregs@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     Zero on success, %$-1$% on mismatch.
 *
 * Use:         Compare the active output registers (according to the current
 *              test group definition) with the corresponding input register
 *              values.  A mismatch occurs if the two values differ
 *              (according to the register type's @eq@ method), or if the
 *              input is live but the output is dead.
 *
 *              This function only checks for a mismatch and returns the
 *              result; it takes no other action.  In particular, it doesn't
 *              report a failure, or dump register values.
 */

extern int tvec_checkregs(struct tvec_state */*tv*/);

/* --- @tvec_mismatch@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @unsigned f@ = flags (@TVMF_...@)
 *
 * Returns:     ---
 *
 * Use:         Dumps registers suitably to report a mismatch.  The flag bits
 *              @TVMF_IN@ and @TVF_OUT@ select input-only and output
 *              registers.  If both are reset then nothing happens.
 *              Suppressing the output registers may be useful, e.g., if the
 *              test function crashed rather than returning outputs.
 */

#define TVMF_IN 1u
#define TVMF_OUT 2u
extern void tvec_mismatch(struct tvec_state */*tv*/, unsigned /*f*/);

/* --- @tvec_check@, @tvec_check_v@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *detail@, @va_list *ap@ = description of test
 *
 * Returns:     ---
 *
 * Use:         Check the register values, reporting a failure and dumping
 *              the registers in the event of a mismatch.  This just wraps up
 *              @tvec_checkregs@, @tvec_fail@ and @tvec_mismatch@ in the
 *              obvious way.
 */

extern PRINTF_LIKE(2, 3)
  void tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
extern void tvec_check_v(struct tvec_state */*tv*/,
                         const char */*detail*/, va_list */*ap*/);

/*----- Output functions --------------------------------------------------*/

/* --- @tvec_strlevel@ --- *
 *
 * Arguments:   @unsigned level@ = level code
 *
 * Returns:     A human-readable description.
 *
 * Use:         Converts a level code into something that you can print in a
 *              message.
 */

extern const char *tvec_strlevel(unsigned /*level*/);

/* --- @tvec_report@, @tvec_report_v@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *msg@, @va_list *ap@ = error message
 *
 * Returns:     ---
 *
 * Use:         Report an message with a given severity.  Messages with level
 *              @TVLEV_ERR@ or higher force a nonzero exit code.
 */

#define TVEC_LEVELS(_)                                                  \
        _(INFO, "info", 3)                                              \
        _(NOTE, "notice", 4)                                            \
        _(ERR, "ERROR", 7)
enum {
#define TVEC_DEFLEVEL(tag, name, val) TVLEV_##tag = val,
  TVEC_LEVELS(TVEC_DEFLEVEL)
#undef TVEC_DEFLEVEL
  TVLEV_LIMIT
};

extern PRINTF_LIKE(3, 4)
  void tvec_report(struct tvec_state */*tv*/, unsigned /*level*/,
                   const char */*msg*/, ...);
extern void tvec_report_v(struct tvec_state */*tv*/, unsigned /*level*/,
                          const char */*msg*/, va_list */*ap*/);

/* --- @tvec_error@, @tvec_notice@, @tvec_info@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *msg@, @va_list *ap@ = error message
 *
 * Returns:     The @tvec_error@ function returns %$-1$% as a trivial
 *              convenience; @tvec_notice@ does not return a value.
 *
 * Use:         Report a message.  Errors are distinct from test
 *              failures, and indicate that a problem was encountered which
 *              compromised the activity of testing.  Notices are important
 *              information which doesn't fit into any other obvious
 *              category.  Information is anything else, and is a reasonable
 *              fallback for writing unstructured information in the absence
 *              of dedicated support in an output driver.
 *
 *              These functions are simple convenience wrappers around
 *              @tvec_report@.  Use @tvec_report_v@ directly if you have a
 *              captured @va_list@ of arguments to format.
 */

extern PRINTF_LIKE(2, 3)
  int tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
extern PRINTF_LIKE(2, 3)
  void tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
extern PRINTF_LIKE(2, 3)
  void tvec_info(struct tvec_state */*tv*/, const char */*msg*/, ...);

/* --- @tvec_unkregerr@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *name@ = register or pseudoregister name
 *
 * Returns:     %$-1$%.
 *
 * Use:         Reports an error that the register or pseudoregister is
 *              unrecognized.
 */

extern int tvec_unkregerr(struct tvec_state */*tv*/, const char */*name*/);

/* --- @tvec_dupregerr@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *name@ = register or pseudoregister name
 *
 * Returns:     %$-1$%.
 *
 * Use:         Reports an error that the register or pseudoregister has been
 *              assigned already in the current test.
 */

extern int tvec_dupregerr(struct tvec_state */*tv*/, const char */*name*/);

/*----- Built-in output drivers -------------------------------------------*/

/* --- @tvec_humanoutput@ --- *
 *
 * Arguments:   @FILE *fp@ = output file to write on
 *              @unsigned f, m@ = flags and mask
 *
 * Returns:     An output formatter.
 *
 * Use:         Return an output formatter which writes on @fp@ with the
 *              expectation that a human will interpret the output.
 *
 *              The flags @f@ and mask @m@ operate together.  Flag bits not
 *              covered by the mask must be left clear, i.e., @f&~m$ must be
 *              zero; the semantics are that a set mask bit indicates that
 *              the corresponding bit of @f@ should control the indicated
 *              behaviour; a clear mask bit indicates that a suitable default
 *              should be chosen based on environmental conditions.
 *
 *              If @TVHF_TTY@ is set, then the output shows a `scoreboard'
 *              indicating the outcome of each test case attempted, providing
 *              a visual indication of progress.  If @TVHF_COLOUR@ is set,
 *              then the output uses control codes for colour and other
 *              highlighting.  It is unusual to set @TVHF_COLOUR@ without
 *              @TVHF_TTY@, this is permitted anyway.
 *
 *              The environment variables %|TVEC_TTY|% and %|TVEC_COLOUR|%
 *              provide default values for these settings.  If they are not
 *              set, then @TVHF_TTY@ is set if @fp@ refers to a terminal, and
 *              @TVHF_COLOUR@ is set if @TVHF_TTY@ is set and, additionally,
 *              the %|TERM|% environment variable is set to a value other
 *              than %|dumb|%.
 */

#define TVHF_TTY 1u                     /*   output to terminal */
#define TVHF_COLOUR 2u                  /*   output in colour */
extern struct tvec_output *tvec_humanoutput(FILE */*fp*/,
                                            unsigned /*f*/, unsigned /*m*/);

/* --- @tvec_machineoutput@ --- *
 *
 * Arguments:   @FILE *fp@ = output file to write on
 *
 * Returns:     An output formatter.
 *
 * Use:         Return an output formatter which writes on @fp@ in a
 *              moderately simple machine-readable format.
 */

struct tvec_output *tvec_machineoutput(FILE *fp);

/* --- @tvec_tapoutput@ --- *
 *
 * Arguments:   @FILE *fp@ = output file to write on
 *              @unsigned style@ = output style (@TVSF_...@)
 *
 * Returns:     An output formatter.
 *
 * Use:         Return an output formatter which writes on @fp@ in `TAP'
 *              (`Test Anything Protocol') format.
 *
 *              TAP comes from the Perl community, but has spread rather
 *              further.  This driver currently produces TAP version 14, but
 *              pretends to be version 13.  The driver produces a TAP `test
 *              point' -- i.e., a result reported as `ok' or `not ok' -- for
 *              each input test group.  Failure reports and register dumps
 *              are produced as diagnostic messages before the final group
 *              result.  (TAP permits structuerd YAML data after the
 *              test-point result, which could be used to report details, but
 *              (a) postponing the details until after the report is
 *              inconvenient, and (b) there is no standardization for the
 *              YAML anyway, so in practice it's no more useful than the
 *              unstructured diagnostics.
 */

extern struct tvec_output *tvec_tapoutput(FILE */*fp*/);

/* --- @tvec_dfltoutput@ --- *
 *
 * Arguments:   @FILE *fp@ = output file to write on
 *
 * Returns:     An output formatter.
 *
 * Use:         Selects and instantiates an output formatter suitable for
 *              writing on @fp@.  The policy is subject to change, but
 *              currently the `human' output format is selected if @fp@ is
 *              interactive (i.e., if @isatty(fileno(fp))@ is true), and
 *              otherwise the `machine' format is used.
 */

extern struct tvec_output *tvec_dfltoutput(FILE */*fp*/);

/* --- @tvec_amoutput@ --- *
 *
 * Arguments:   @const struct tvec_amargs *a@ = arguments from Automake
 *                      command-line protocol
 *
 * Returns:     An output formatter.
 *
 * Use:         Returns an output formatter which writes on standard output
 *              in human format, pretending that the output is to a terminal
 *              (in order to cope with %%\manpage{make}{1}%%'s output-
 *              buffering behaviour, writes to the log file @a->log@ in
 *              machine-readable format, and writes an Automake rST-format
 *              test result file to @a->trs@.  The `test name' is currently
 *              ignored, because the framework has its own means of
 *              determining test names.
 */

struct tvec_amargs {
  unsigned f;                           /* flags */
#define TVAF_COLOUR 1u                  /*   produce colour output */
  const char *name;                     /* test name */
  FILE *log;                            /* `log' output file */
  FILE *trs;                            /* `trs' summary file */
};

extern struct tvec_output *tvec_amoutput(const struct tvec_amargs */*a*/);

/*------ Serialization utilities ------------------------------------------*/

/* Serialization format.
 *
 * The `candidate register definitions' are those entries @r@ in the @regs@
 * vector whose index @r.i@ is strictly less than @nr@ and where
 * @r.f&mask == want@* .  The `selected register definitions' are those
 * candidate register definitions @r@ for which the indicated register
 * @rv[r.i]@ has the @TVRF_LIVE@ flag set.  The serialized output begins with
 * a header bitmap: if there are %$n$% candidate register definitions then
 * the header bitmap consists of %$\lceil n/8 \rceil$% bytes.  Bits are
 * ordered starting from the least significant bit of the first byte, end
 * ending at the most significant bit of the final byte.  The bit
 * corresponding to a candidate register definition is set if and only if
 * that register defintion is selected.  The header bitmap is then followed
 * by the serializations of the selected registers -- i.e., for each selected
 * register definition @r@, the serialized value of register @rv[r.i]@ --
 * simply concatenated together, with no padding or alignment.
 */

/* --- @tvec_serialize@ --- *
 *
 * Arguments:   @const struct tvec_reg *rv@ = vector of registers
 *              @buf *b@ = buffer to write on
 *              @const struct tvec_regdef *regs@ = vector of register
 *                      descriptions, terminated by an entry with a null
 *                      @name@ slot
 *              @unsigned mask, want@ = flag-based selection
 *              @unsigned nr@ = number of entries in the @rv@ vector
 *              @size_t regsz@ = true size of each element of @rv@
 *
 * Returns:     Zero on success, %$-1$% on failure.
 *
 * Use:         Serialize a collection of register values.
 *
 *              The serialized output is written to the buffer @b@.  Failure
 *              can be caused by running out of buffer space, or a failing
 *              type handler.
 */

extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/,
                          const struct tvec_regdef */*regs*/,
                          unsigned /*mask*/, unsigned /*want*/,
                          unsigned /*nr*/, size_t /*regsz*/);

/* --- @tvec_deserialize@ --- *
 *
 * Arguments:   @struct tvec_reg *rv@ = vector of registers
 *              @buf *b@ = buffer to write on
 *              @const struct tvec_regdef *regs@ = vector of register
 *                      descriptions, terminated by an entry with a null
 *                      @name@ slot
 *              @unsigned mask, want@ = flag-based selection
 *              @unsigned nr@ = number of entries in the @rv@ vector
 *              @size_t regsz@ = true size of each element of @rv@
 *
 * Returns:     Zero on success, %$-1$% on failure.
 *
 * Use:         Deserialize a collection of register values.
 *
 *              The size of the register vector @nr@ and the register
 *              definitions @regs@ must match those used when producing the
 *              serialization.  For each serialized register value,
 *              deserialize and store the value into the appropriate register
 *              slot, and set the @TVRF_LIVE@ flag on the register.  See
 *              @tvec_serialize@ for a description of the format.
 *
 *              Failure results only from an input too small for the initial
 *              bitmap or a failing register type handler.
 */

extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
                            const struct tvec_regdef */*regs*/,
                            unsigned /*mask*/, unsigned /*want*/,
                            unsigned /*nr*/, size_t /*regsz*/);

/*----- Input utilities ---------------------------------------------------*/

/* These are provided by the core for the benefit of type @parse@ methods,
 * and test-environment @set@ functions, which get to read from the test
 * input file.  The latter are usually best implemented by calling on the
 * former.
 *
 * The two main rules are as follows.
 *
 *   * Leave the file position at the beginning of the line following
 *     whatever it was that you read.
 *
 *   * When you read and consume a newline (which you do at least once, by
 *     the previous rule), then increment @tv->lno@ to keep track of the
 *     current line number.
 */

/* --- @tvec_syntax@, @tvec_syntax_v@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @int ch@ = the character found (in @fgetc@ format)
 *              @const char *expect@, @va_list *ap@ = what was expected
 *
 * Returns:     %$-1$%.
 *
 * Use:         Report a syntax error quoting @ch@ and @expect@.
 *
 *              If @ch@ is a newline, or if @TVSF_NEXT@ is set, then unread
 *              it so that it can be read again (e.g., by @tvec_nexttoken@).
 *              The intent here is that you can safely read a character,
 *              inspect it, and then complain about it with @tvec_syntax@
 *              without having to worry too much about backing up.  The
 *              flipside of this is that you %%\emph{must}%% read a
 *              character, even if you don't have one ready, e,g, if you
 *              called @tvec_nexttoken@ and it said there wasn't one
 *              available.
 */

extern PRINTF_LIKE(3, 4)
  int tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
                  const char */*expect*/, ...);
extern int tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/,
                         const char */*expect*/, va_list */*ap*/);

/* --- @tvec_skipspc@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     ---
 *
 * Use:         Advance over any whitespace characters other than newlines.
 *              This will stop at `;', end-of-file, or any other kind of
 *              non-whitespace; and it won't consume a newline.
 */

extern void tvec_skipspc(struct tvec_state */*tv*/);

/* --- @tvec_nexttoken@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     Zero if there is a next token which can be read; %$-1$% if no
 *              token is available.
 *
 * Use:         Advance to the next whitespace-separated token, which may be
 *              on the next line.
 *
 *              Tokens are separated by non-newline whitespace, comments, and
 *              newlines followed by whitespace; a newline /not/ followed by
 *              whitespace instead begins the next assignment, and two
 *              newlines separated only by whitespace terminate the data for
 *              a test.
 *
 *              If this function returns zero, then the next character in the
 *              file begins a suitable token which can be read and processed.
 *              If it returns %$-1$% then there is no such token, @TVSF_NEXT@
 *              is set, and the file position is left correctly.  The line
 *              number count is updated appropriately.
 */

extern int tvec_nexttoken(struct tvec_state */*tv*/);

/* --- @tvec_readword@, @tvec_readword_v@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @dstr *d@ = string to append the word to
 *              @const char **p_inout@ = pointer into string, updated
 *              @const char *delims@ = additional delimiters to stop at
 *              @const char *expect@, @va_list *ap@ = what was expected
 *
 * Returns:     Zero on success, %$-1$% on failure.
 *
 * Use:         A `word' consists of characters other than whitespace, null
 *              characters, and other than those listed in @delims@;
 *              furthermore, a word does not begin with a `;'.  (If you want
 *              reading to stop at comments not preceded by whitespace, then
 *              include `;' in @delims@.  This is a common behaviour.)
 *
 *              The function advances past whitespace and comments, as for
 *              @tvec_nexttoken@.  If there is no word beginning after the
 *              current file position, but before the start of the next
 *              non-continuation line, then return %$-1$%; furthermore, if
 *              @expect@ is not null, then report an appropriate error via
 *              @tvec_syntax@.
 *
 *              Otherwise, the word is accumulated in @d@ and zero is
 *              returned; if @d@ was not empty at the start of the call, the
 *              newly read word is separated from the existing material by a
 *              single space character.  Since null bytes are never valid
 *              word constituents, a null terminator is written to @d@, and
 *              it is safe to treat the string in @d@ as being null-
 *              terminated.
 *
 *              If @p_inout@ is not null, then @*p_inout@ must be a pointer
 *              into @d->buf@, which will be adjusted so that it will
 *              continue to point at the same position even if the buffer is
 *              reallocated.  As a subtle tweak, if @*p_inout@ initially
 *              points at the end of the buffer, then it will be adjusted to
 *              point at the beginning of the next word, rather than at the
 *              additional intervening space.
 */

extern PRINTF_LIKE(5, 6)
  int tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
                    const char **/*p_inout*/, const char */*delims*/,
                    const char */*expect*/, ...);
extern int tvec_readword_v(struct tvec_state */*tv*/, dstr */*d*/,
                           const char **/*p_inout*/, const char */*delims*/,
                           const char */*expect*/, va_list */*ap*/);

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

#ifdef __cplusplus
  }
#endif

#endif