[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

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

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

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

#ifndef MLIB_CONTROL_H
#  include "control.h"
#endif

#ifndef MLIB_BUF_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 { unsigned char *p; size_t sz; } bytes; /* binary string of bytes */
  struct { char *p; size_t sz; } str;   /* text string */
#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_LIVE 1u                    /*   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) */
  unsigned i;                           /* register index */
  const struct tvec_regty *ty;          /* register type descriptor */
  unsigned f;                           /* flags */
#define TVRF_OPT 1u                     /*   optional register */
#define TVRF_ID 2u                      /*   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)))

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

enum {
  /* Possible test outcomes. */

  TVOUT_LOSE,                           /* test failed */
  TVOUT_SKIP,                           /* test skipped */
  TVOUT_WIN,                            /* test passed */
  TVOUT_LIMIT                           /* (number of possible outcomes) */
};

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

  unsigned f;                           /* flags */
#define TVSF_SKIP 1u                    /*   skip this test group */
#define TVSF_OPEN 2u                    /*   test is open */
#define TVSF_ACTIVE 4u                  /*   test is active */
#define TVSF_ERROR 8u                   /*   an error occurred */
#define TVSF_OUTMASK 0xf0               /*   test outcome (@TVOUT_...@) */
#define TVSF_OUTSHIFT 4                 /*   shift applied to outcome */

  /* Registers.  Available to execution environments. */
  unsigned nrout, nreg;                /* number of output/total registers */
  size_t regsz;                         /* size of register entry */
  struct tvec_reg *in, *out;            /* register vectors */

  /* Test groups state.  Available to output formatters. */
  const struct tvec_test *tests, *test; /* all tests and current test */

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

  /* Output machinery. */
  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 */
};

/* @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)->regsz)

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

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

/*----- Output formatting -------------------------------------------------*/

struct tvec_output {
  /* An output formatter. */
  const struct tvec_outops *ops;        /* pointer to operations */
};

/* Benchmarking details. */
enum {
  TVBU_OP,                             /* counting operations of some kind */
  TVBU_BYTE                             /* counting bytes (@rbuf >= 0@) */
};
struct bench_timing;                    /* forward declaration */

struct tvec_outops {
  /* Output operations. */

  void (*bsession)(struct tvec_output */*o*/, struct tvec_state */*tv*/);
        /* Begin a test session.  The output driver will probably want to
         * save @tv@, because this isn't provided to any other methods.
         */

  int (*esession)(struct tvec_output */*o*/);
        /* End a session, and return the suggested exit code. */

  void (*bgroup)(struct tvec_output */*o*/);
        /* Begin a test group.  The test group description is @tv->test@. */

  void (*skipgroup)(struct tvec_output */*o*/,
                    const char */*excuse*/, va_list */*ap*/);
        /* The group is being skipped; @excuse@ may be null or a format
         * string explaining why.  The @egroup@ method will not be called
         * separately.
         */

  void (*egroup)(struct tvec_output */*o*/);
        /* End a test group.  At least one test was attempted or @skipgroup@
         * would have been called instead.  If @tv->curr[TVOUT_LOSE]@ is
         * nonzero then the test group as a whole failed; otherwise it
         * passed.
         */

  void (*btest)(struct tvec_output */*o*/);
        /* Begin a test case. */

  void (*skip)(struct tvec_output */*o*/,
               const char */*excuse*/, va_list */*ap*/);
        /* The test case is being skipped; @excuse@ may be null or a format
         * string explaining why.  The @etest@ function will still be called
         * (so this works differently from @skipgroup@ and @egroup@).  A test
         * case can be skipped at most once, and, if skipped, it cannot fail.
         */

  void (*fail)(struct tvec_output */*o*/,
               const char */*detail*/, va_list */*ap*/);
        /* The test case failed.
         *
         * The output driver should preferably report the filename (@infile@)
         * and line number (@test_lno@, not @lno@) for the failing test.
         *
         * The @detail@ may be null or a format string describing detail
         * about how the failing test was run which can't be determined from
         * the registers; a @detail@ is usually provided when (and only when)
         * the test environment potentially invokes the test function more
         * than once.
         *
         * A single test case can fail multiple times!
         */

  void (*dumpreg)(struct tvec_output */*o*/,
                  unsigned /*disp*/, const union tvec_regval */*rv*/,
                  const struct tvec_regdef */*rd*/);
        /* Dump a register.  The `disposition' @disp@ explains what condition
         * the register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes.
         * The register value is at @rv@, and its definition, including its
         * type, at @rd@.  Note that this function may be called on virtual
         * registers which aren't in either of the register vectors or
         * mentioned by the test description.
         */

  void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/);
        /* The test case concluded with the given @outcome@ (one of the
         * @TVOUT_...@ codes.
         */

  void (*bbench)(struct tvec_output */*o*/,
                 const char */*ident*/, unsigned /*unit*/);
        /* Begin a benchmark.  The @ident@ is a formatted string identifying
         * the benchmark based on the values of the input registered marked
         * @TVRF_ID@; the output driver is free to use this or come up with
         * its own way to identify the test, e.g., by inspecting the register
         * values for itself.  The @unit@ is one of the @TVBU_...@ constants
         * explaining what sort of thing is being measured.
         */

  void (*ebench)(struct tvec_output */*o*/,
                 const char */*ident*/, unsigned /*unit*/,
                 const struct bench_timing */*tm*/);
        /* End a benchmark.  The @ident@ and @unit@ arguments are as for
         * @bbench@.  If @tm@ is zero then the measurement failed; otherwise
         * @tm->n@ counts total number of things (operations or bytes, as
         * indicated by @unit@) processed in the indicated time.
         */

  void (*error)(struct tvec_output */*o*/,
                const char */*msg*/, va_list */*ap*/);
        /* Report an error.  The driver should ideally report the filename
         * (@infile@) and line number (@lno@) prompting the error.
         */

  void (*notice)(struct tvec_output */*o*/,
                 const char */*msg*/, va_list */*ap*/);
        /* Report a miscellaneous message.  The driver should ideally report
         * the filename (@infile@) and line number (@lno@) prompting the
         * error.
         */

  void (*destroy)(struct tvec_output */*o*/);
        /* Release any resources acquired by the driver. */
};

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

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.
   */

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 */

  int (*setup)(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.  Return zero on success, or @-1@ on failure.
     * If setup fails, the context is freed, and the test group is skipped.
     */

  int (*set)(struct tvec_state */*tv*/, const char */*var*/,
             const struct tvec_env */*env*/, void */*ctx*/);
    /* Called when the parser finds a %|@var|%' setting to parse and store
     * the value.  If @setup@ failed, this is still called (so as to skip the
     * value), but @ctx@ is null.
     */

  int (*before)(struct tvec_state */*tv*/, void */*ctx*/);
    /* Called prior to running a test.  This is the right place to act on any
     * `%|@var|%' settings.  Return zero on success or @-1@ on failure (which
     * causes the test to be skipped).  This function is never called if the
     * test group is skipped.
     */

  void (*run)(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.
     */

  void (*after)(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 is
     * never called if the test group is skipped.
     */

  void (*teardown)(struct tvec_state */*tv*/, void */*ctx*/);
    /* Tear down the environment: called at the end of a test group.  If the
     * setup failed, then this function is still called, with a null @ctx@.
     */
};

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 */
};
#define TVEC_ENDTESTS { 0, 0, 0, 0 }

enum {
  /* Register output dispositions. */

  TVRD_INPUT,                           /* input-only register */
  TVRD_OUTPUT,                          /* output-only (input is dead) */
  TVRD_MATCH,                           /* matching (equal) registers */
  TVRD_FOUND,                           /* mismatching output register */
  TVRD_EXPECT                           /* mismatching input register */
};

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

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@.
         */

  void (*release)(union tvec_regval */*rv*/,
                  const struct tvec_regdef */*rd*/);
        /* Release any resources associated with the value in @*rv@. */

  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@.  A successful return should leave
         * the input position at the start of the next line; the caller will
         * flush the remainder of the line itself.
         */

  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
        /* 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.
         */
};

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

/* 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@
 *                      -> env @run@
 *                              -> @tvec_skip@
 *                                      -> output @skip@
 *                              -> test @fn@
 *                              -> @tvec_checkregs@
 *                                      -> type @eq@
 *                              -> @tvec_fail@
 *                                      -> output @fail@
 *                              -> @tvec_mismatch@
 *                                      -> output @dumpreg@
 *                                              -> type @dump@
 *                      -> env @after@
 *                      -> output @etest@
 *   or
 *                      -> output @skipgroup@
 *   finally
 *                      -> output @egroup@
 *                      -> env @teardown@
 *
 * @tvec_adhoc@
 *   @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.
 */

/* --- @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.
 */

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.)
 */

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 --------------------------------------------*/

extern const struct tvec_config tvec_adhocconfig;
/* A special @struct tvec_config@ to use for programs which perform ad-hoc
 * testing.
 */

/* --- @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 *cofig@ = 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 *cofig@ = 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 void PRINTF_LIKE(2, 3)
  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 void PRINTF_LIKE(2, 3)
  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_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.
 */

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_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 void PRINTF_LIKE(2, 3)
  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
 *              @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_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 void PRINTF_LIKE(2, 3)
  tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
extern void tvec_check_v(struct tvec_state */*tv*/,
                         const char */*detail*/, va_list */*ap*/);

/*----- Ad-hoc testing ----------------------------------------------------*/

/* --- @tvec_adhoc@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @struct tvec_test *t@ = space for a test definition
 *
 * Returns:     ---
 *
 * Use:         Begin ad-hoc testing, i.e., without reading a file of
 *              test-vector data.
 *
 *              The structure at @t@ will be used to record information about
 *              the tests underway, which would normally come from a static
 *              test definition.  The other functions in this section assume
 *              that @tvec_adhoc@ has been called.
 */

extern void tvec_adhoc(struct tvec_state */*tv*/, struct tvec_test */*t*/);

/* --- @tvec_begingroup@, @TVEC_BEGINGROUP@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *name@ = name for this test group
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *
 * Returns:     ---
 *
 * Use:         Begin an ad-hoc test group with the given name.  The @file@
 *              and @lno@ can be anything, but it's usually best if they
 *              refer to the source code performing the test: the macro
 *              @TVEC_BEGINGROUP@ does this automatically.
 */

extern void tvec_begingroup(struct tvec_state */*tv*/, const char */*name*/,
                            const char */*file*/, unsigned /*lno*/);
#define TVEC_BEGINGROUP(tv, name)                                       \
        do tvec_begingroup(tv, name, __FILE__, __LINE__); while (0)

/* --- @tvec_endgroup@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     ---
 *
 * Use:         End an ad-hoc test group.  The statistics are updated and the
 *              outcome is reported to the output formatter.
 */

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

/* --- @TVEC_TESTGROUP@, @TVEC_TESTGROUP_TAG@ --- *
 *
 * Arguments:   @tag@ = label-disambiguation tag
 *              @const struct tvec_state *tv = test-vector state
 *              @const char *name@ = test-group name
 *
 * Returns:     ---
 *
 * Use:         Control-structure macro: @TVEC_TESTGROUP(tv, name) stmt@
 *              establishes a test group with the given @name@ (attributing
 *              it to the source file and lie number), executes @stmt@, and
 *              ends the test group.  If @stmt@ invokes @break@ then the test
 *              group is skipped.  @TVEC_TESTGROUP_TAG@ is the same, with an
 *              additional @tag@ argument for use in higher-level macros.
 */

#define TVEC_TESTGROUP_TAG(tag, tv, name)                               \
        MC_WRAP(tag##__around,                                          \
          { TVEC_BEGINGROUP(tv, name); },                               \
          { tvec_endgroup(tv); },                                       \
          { if (!((tv)->f&TVSF_SKIP)) tvec_skipgroup(tv, 0);            \
            tvec_endgroup(tv); })
#define TVEC_TESTGROUP(tv, name) TVEC_TESTGROUP_TAG(grp, tv, name)

/* --- @tvec_begintest@, @TVEC_BEGINTEST@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *
 * Returns:     ---
 *
 * Use:         Begin an ad-hoc test case.  The @file@ and @lno@ can be
 *              anything, but it's usually best if they refer to the source
 *              code performing the test: the macro @TVEC_BEGINGROUP@ does
 *              this automatically.
 */

extern void tvec_begintest(struct tvec_state */*tv*/,
                           const char */*file*/, unsigned /*lno*/);
#define TVEC_BEGINTEST(tv)                                              \
        do tvec_begintest(tv, __FILE__, __LINE__); while (0)

/* --- *tvec_endtest@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     ---
 *
 * Use:         End a ad-hoc test case,  The statistics are updated and the
 *              outcome is reported to the output formatter.
 */

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

/* --- @TVEC_TEST@, @TVEC_TEST_TAG@ --- *
 *
 * Arguments:   @tag@ = label-disambiguation tag
 *              @struct tvec_test *t@ = space for a test definition
 *
 * Returns:     ---
 *
 * Use:         Control-structure macro: @TVEC_TEST(tv) stmt@ begins a test
 *              case, executes @stmt@, and ends the test case.  If @stmt@
 *              invokes @break@ then the test case is skipped.
 *              @TVEC_TEST_TAG@ is the same, with an additional @tag@ argumet
 *              for use in higher-level macros.
 */

#define TVEC_TEST_TAG(tag, tv)                                          \
        MC_WRAP(tag##__around,                                          \
          { TVEC_BEGINTEST(tv); },                                      \
          { tvec_endtest(tv); },                                        \
          { if ((tv)->f&TVSF_ACTIVE) tvec_skip((tv), 0);                \
            tvec_endtest(tv); })
#define TVEC_TEST(tv) TVEC_TEST_TAG(test, tv)

/* --- @tvec_claim@, @tvec_claim_v@, @TVEC_CLAIM@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @int ok@ = a flag
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *msg@, @va_list *ap@ = message to report on
 *                      failure
 *
 * Returns:     The value @ok@.
 *
 * Use:         Check that a claimed condition holds, as (part of) a test.
 *              If no test case is underway (i.e., if @TVSF_OPEN@ is reset in
 *              @tv->f@), then a new test case is begun and ended.  The
 *              @file@ and @lno@ are passed to the output formatter to be
 *              reported in case of a failure.  If @ok@ is nonzero, then
 *              nothing else happens; so, in particular, if @tvec_claim@
 *              established a new test case, then the test case succeeds.  If
 *              @ok@ is zero, then a failure is reported, quoting @msg@.
 *
 *              The @TVEC_CLAIM@ macro is similar, only it (a) identifies the
 *              file and line number of the call site automatically, and (b)
 *              implicitly quotes the source text of the @ok@ condition in
 *              the failure message.
 */

extern int PRINTF_LIKE(5, 6)
  tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
             const char */*file*/, unsigned /*lno*/,
             const char */*msg*/, ...);
extern int tvec_claim_v(struct tvec_state */*tv*/, int /*ok*/,
                        const char */*file*/, unsigned /*lno*/,
                        const char */*msg*/, va_list */*ap*/);
#define TVEC_CLAIM(tv, cond)                                            \
        (tvec_claim(tv, !!(cond), __FILE__, __LINE__, "%s untrue", #cond))

/* --- @tvec_claimeq@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const struct tvec_regty *ty@ = register type
 *              @const union tvec_misc *arg@ = register type argument
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if the input and output values of register 0 are
 *              equal, zero if they differ.
 *
 * Use:         Check that the input and output values of register 0 are
 *              equal (according to the register type @ty@).  As for
 *              @tvec_claim@ above, a test case is automatically begun and
 *              ended if none is already underway.  If the values are
 *              unequal, then @tvec_fail@ is called, quoting @expr@, and the
 *              mismatched values are dumped.
 *
 *              This function is not expected to be called directly, but
 *              through type-specific wrapper functions or macros such as
 *              @TVEC_CLAIMEQ_INT@.
 */

extern int tvec_claimeq(struct tvec_state */*tv*/,
                        const struct tvec_regty */*ty*/,
                        const union tvec_misc */*arg*/,
                        const char */*file*/, unsigned /*lno*/,
                        const char */*expr*/);

/*----- Benchmarking ------------------------------------------------------*/

struct tvec_bench {
  struct tvec_env _env;                 /* benchmarking is an environment */
  struct bench_state **bst;             /* benchmark state anchor or null */
  unsigned long niter;                  /* iterations done per unit */
  int riter, rbuf;                      /* iterations and buffer registers */
  const struct tvec_env *env;           /* subordinate environment */
};
#define TVEC_BENCHENV                                                   \
  { sizeof(struct tvec_benchctx),                                       \
    tvec_benchsetup,                                                    \
    tvec_benchset,                                                      \
    tvec_benchbefore,                                                   \
    tvec_benchrun,                                                      \
    tvec_benchafter,                                                    \
    tvec_benchteardown }
#define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate

struct tvec_benchctx {
  const struct tvec_bench *b;
  struct bench_state *bst;
  double dflt_target;
  void *subctx;
};

extern struct bench_state *tvec_benchstate;

/* --- @tvec_benchsetup@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test vector state
 *              @const struct tvec_env *env@ = environment description
 *              @void *pctx@ = parent context (ignored)
 *              @void *ctx@ = context pointer to initialize
 *
 * Returns:     Zero on success, @-1@ on failure.
 *
 * Use:         Initialize a benchmarking environment context.
 *
 *              The environment description must really be a @struct
 *              tvec_bench@.  If the @bst@ slot is null, then a temporary
 *              benchmark state is allocated for the current test group and
 *              released at the end.  Otherwise, it must be the address of a
 *              pointer to a benchmark state: if the pointer is null, then a
 *              fresh state is allocated and initialized and the pointer is
 *              updated; otherwise, the pointer is assumed to refer to an
 *              existing valid benchmark state.
 */

extern int tvec_benchsetup(struct tvec_state */*tv*/,
                           const struct tvec_env */*env*/,
                           void */*pctx*/, void */*ctx*/);

/* --- @tvec_benchset@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test vector state
 *              @const char *var@ = variable name to set
 *              @const struct tvec_env *env@ = environment description
 *              @void *ctx@ = context pointer
 *
 * Returns:     Zero on success, @-1@ on failure.
 *
 * Use:         Set a special variable.  The following special variables are
 *              supported.
 *
 *                * %|@target|% is the (approximate) number of seconds to run
 *                  the benchmark.
 *
 *              Unrecognized variables are passed to the subordinate
 *              environment, if there is one.
 */

extern int tvec_benchset(struct tvec_state */*tv*/, const char */*var*/,
                         const struct tvec_env */*env*/, void */*ctx*/);

/* --- @tvec_benchbefore@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test vector state
 *              @void *ctx@ = context pointer
 *
 * Returns:     Zero on success, @-1@ on failure.
 *
 * Use:         Invoke the subordinate environment's @before@ function to
 *              prepare for the benchmark.
 */

extern int tvec_benchbefore(struct tvec_state */*tv*/, void */*ctx*/);

/* --- @tvec_benchrun@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test vector state
 *              @tvec_testfn *fn@ = test function to run
 *              @void *ctx@ = context pointer for the test function
 *
 * Returns:     ---
 *
 * Use:         Measures and reports the performance of a test function.
 *
 *
 */

extern void tvec_benchrun(struct tvec_state */*tv*/,
                          tvec_testfn */*fn*/, void */*ctx*/);

/* --- @tvec_benchafter@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test vector state
 *              @void *ctx@ = context pointer
 *
 * Returns:     ---
 *
 * Use:         Invoke the subordinate environment's @after@ function to
 *              clean up after the benchmark.
 */

extern void tvec_benchafter(struct tvec_state */*tv*/, void */*ctx*/);

/* --- @tvec_benchteardown@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test vector state
 *              @void *ctx@ = context pointer
 *
 * Returns:     ---
 *
 * Use:         Tear down the benchmark environment.
 */

extern void tvec_benchteardown(struct tvec_state */*tv*/, void */*ctx*/);

/* --- @tvec_benchreport@ --- *
 *
 * Arguments:   @const struct gprintf_ops *gops@ = print operations
 *              @void *go@ = print destination
 *              @unsigned unit@ = the unit being measured (~TVBU_...@)
 *              @const struct bench_timing *tm@ = the benchmark result
 *
 * Returns:     ---
 *
 * Use:         Formats a report about the benchmark performance.  This
 *              function is intended to be called on by an output
 *              @ebench@ function.
 */

extern void tvec_benchreport
  (const struct gprintf_ops */*gops*/, void */*go*/,
   unsigned /*unit*/, const struct bench_timing */*tm*/);

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

/* --- @tvec_error@, @tvec_error_v@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *msg@, @va_list ap@ = error message
 *
 * Returns:     @-1@.
 *
 * Use:         Report an error.  Errors are distinct from test failures,
 *              and indicate that a problem was encountered which compromised
 *              the activity of testing.
 */

extern int PRINTF_LIKE(2, 3)
  tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
extern int tvec_error_v(struct tvec_state */*tv*/,
                        const char */*msg*/, va_list */*ap*/);

/* --- @tvec_notice@, @tvec_notice_v@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *msg@, @va_list ap@ = message
 *
 * Returns:     ---
 *
 * Use:         Output a notice: essentially, some important information
 *              which doesn't fit into any of the existing categories.
 */

extern void PRINTF_LIKE(2, 3)
  tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
extern void tvec_notice_v(struct tvec_state */*tv*/,
                          const char */*msg*/, va_list */*ap*/);

/* --- @tvec_humanoutput@ --- *
 *
 * Arguments:   @FILE *fp@ = output file to write on
 *
 * Returns:     An output formatter.
 *
 * Use:         Return an output formatter which writes on @fp@ with the
 *              expectation that a human will be watching and interpreting
 *              the output.  If @fp@ denotes a terminal, the display shows a
 *              `scoreboard' indicating the outcome of each test case
 *              attempted, and may in addition use colour and other
 *              highlighting.
 */

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

/* --- @tvec_tapoutput@ --- *
 *
 * Arguments:   @FILE *fp@ = output file to write on
 *
 * 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 produces TAP 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 `tap' format is used.
 */

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

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

/* --- @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 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 `candidate register definitions' are those entries @r@ in
 *              the @regs@ vector whose index @r.i@ is strictly less than
 *              @nr@.  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.
 *
 *              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 /*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 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.
 *
 *              On successful completion, store the address of the first byte
 *              after the serialized data in @*end_out@ if @end_out@ is not
 *              null.  Failure results only from a failing register type
 *              handler.
 */

extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
                            const struct tvec_regdef */*regs*/,
                            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_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_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, then back up so that it can be read again (e.g.,
 *              by @tvec_flushtoeol@ or @tvec_nexttoken@, which will also
 *              advance the line number).
 */

extern int PRINTF_LIKE(3, 4)
  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_flushtoeol@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @unsigned f@ = flags (@TVFF_...@)
 *
 * Returns:     Zero on success, @-1@ on error.
 *
 * Use:         Advance to the start of the next line, consuming the
 *              preceding newline.
 *
 *              A syntax error is reported if no newline character is found,
 *              i.e., the file ends in mid-line.  A syntax error is also
 *              reported if material other than whitespace or a comment is
 *              found before the end of the line end, and @TVFF_ALLOWANY@ is
 *              not set in @f@.  The line number count is updated
 *              appropriately.
 */

#define TVFF_ALLOWANY 1u
extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);

/* --- @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,
 *              and the file position is left correctly.  The line number
 *              count is updated appropriately.
 */

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

/* --- @tvec_readword@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @dstr *d@ = string to append the word to
 *              @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.)
 *
 *              If there is no word beginning at the current file position,
 *              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.
 */

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

/*----- Integer types: signed and unsigned --------------------------------*/

/* Integers may be input in decimal, hex, binary, or octal, following
 * approximately usual conventions.
 *
 *   * Signed integers may be preceded with a `+' or `-' sign.
 *
 *   * Decimal integers are just a sequence of decimal digits `0' ... `9'.
 *
 *   * Octal integers are a sequence of digits `0' ... `7', preceded by `0o'
 *     or `0O'.
 *
 *   * Hexadecimal integers are a sequence of digits `0' ... `9', `a'
 *     ... `f', or `A' ... `F', preceded by `0x' or `0X'.
 *
 *   * Radix-B integers are a sequence of digits `0' ... `9', `a' ... `f', or
 *     `A' ... `F', each with value less than B, preceded by `Br' or `BR',
 *     where 0 < B < 36 is expressed in decimal without any leading `0' or
 *     internal underscores `_'.
 *
 *   * A digit sequence may contain internal underscore `_' separators, but
 *     not before or after all of the digits; and two consecutive `_'
 *     characters are not permitted.
 */

extern const struct tvec_regty tvty_int, tvty_uint;

/* The @arg.p@ slot may be null or a pointer to @struct tvec_irange@ or
 * @struct tvec_urange@ as appropriate.  The bounds are inclusive; use, e.g.,
 * @LONG_MAX@ explicitly if one or the other bound is logically inapplicable.
 */
struct tvec_irange { long min, max; };
struct tvec_urange { unsigned long min, max; };

/* Bounds corresponding to common integer types. */
extern const struct tvec_irange
  tvrange_schar, tvrange_short, tvrange_int, tvrange_long,
  tvrange_sbyte, tvrange_i16, tvrange_i32;
extern const struct tvec_urange
  tvrange_uchar, tvrange_ushort, tvrange_uint, tvrange_ulong, tvrange_size,
  tvrange_byte, tvrange_u16, tvrange_u32;

/* --- @tvec_claimeq_int@, @TVEC_CLAIMEQ_INT@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @long i0, i1@ = two signed integers
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if @i0@ and @i1@ are equal, otherwise zero.
 *
 * Use:         Check that values of @i0@ and @i1@ are equal.  As for
 *              @tvec_claim@ above, a test case is automatically begun and
 *              ended if none is already underway.  If the values are
 *              unequal, then @tvec_fail@ is called, quoting @expr@, and the
 *              mismatched values are dumped: @i0@ is printed as the output
 *              value and @i1@ is printed as the input reference.
 *
 *              The @TVEC_CLAIM_INT@ macro is similar, only it (a) identifies
 *              the file and line number of the call site automatically, and
 *              (b) implicitly quotes the source text of the @i0@ and @i1@
 *              arguments in the failure message.
 */

extern int tvec_claimeq_int(struct tvec_state */*tv*/,
                            long /*i0*/, long /*i1*/,
                            const char */*file*/, unsigned /*lno*/,
                            const char */*expr*/);
#define TVEC_CLAIMEQ_INT(tv, i0, i1)                                    \
        (tvec_claimeq_int(tv, i0, i1, __FILE__, __LINE__, #i0 " /= " #i1))

/* --- @tvec_claimeq_uint@, @TVEC_CLAIMEQ_UINT@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @unsigned long u0, u1@ = two unsigned integers
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if @u0@ and @u1@ are equal, otherwise zero.
 *
 * Use:         Check that values of @u0@ and @u1@ are equal.  As for
 *              @tvec_claim@ above, a test case is automatically begun and
 *              ended if none is already underway.  If the values are
 *              unequal, then @tvec_fail@ is called, quoting @expr@, and the
 *              mismatched values are dumped: @u0@ is printed as the output
 *              value and @u1@ is printed as the input reference.
 *
 *              The @TVEC_CLAIM_UINT@ macro is similar, only it (a)
 *              identifies the file and line number of the call site
 *              automatically, and (b) implicitly quotes the source text of
 *              the @u0@ and @u1@ arguments in the failure message.
 */

extern int tvec_claimeq_uint(struct tvec_state */*tv*/,
                            unsigned long /*u0*/, unsigned long /*u1*/,
                            const char */*file*/, unsigned /*lno*/,
                            const char */*expr*/);
#define TVEC_CLAIMEQ_UINT(tv, u0, u1)                                   \
        (tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))

/*----- Floating-point type -----------------------------------------------*/

/* Floating-point are either NaN (`#nan', if supported by the platform);
 * positive or negative infinity (`#inf', `+#inf', or, preferred, `#+inf',
 * and `-#inf' or, preferred, `#-inf', if supported by the platform), or a
 * number in strtod(3) syntax.
 *
 * The comparison rules for floating-point numbers are complex: see
 * @tvec_claimeqish_float@ for details.
 */

extern const struct tvec_regty tvty_float;

struct tvec_floatinfo {
  /* Details about acceptable floating-point values. */

  unsigned f;                           /* flags (@TVFF_...@ bits) */
#define TVFF_NOMIN 1u                   /*   ignore @min@ (allow -inf) */
#define TVFF_NOMAX 2u                   /*   ignore @max@ (allow +inf) */
#define TVFF_NANOK 4u                   /*   permit NaN */
#define TVFF_EQMASK 0xf0                /*   how to compare */
#define TVFF_EXACT 0x00                 /*     must equal exactly */
#define TVFF_ABSDELTA 0x10              /*     must be within @delta@ */
#define TVFF_RELDELTA 0x20              /*     diff < @delta@ fraction */
  double min, max;                      /* smallest/largest value allowed */
  double delta;                         /* maximum tolerable difference */
};

/* --- @tvec_claimeqish_float@, @TVEC_CLAIMEQISH_FLOAT@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @double f0, f1@ = two floating-point numbers
 *              @unsigned f@ = flags (@TVFF_...@)
 *              @double delta@ = maximum tolerable difference
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if @f0@ and @u1@ are sufficiently close, otherwise
 *              zero.
 *
 * Use:         Check that values of @f0@ and @f1@ are sufficiently close.
 *              As for @tvec_claim@ above, a test case is automatically begun
 *              and ended if none is already underway.  If the values are
 *              too far apart, then @tvec_fail@ is called, quoting @expr@,
 *              and the mismatched values are dumped: @f0@ is printed as the
 *              output value and @f1@ is printed as the input reference.
 *
 *              The details for the comparison are as follows.
 *
 *                * A NaN value matches any other NaN, and nothing else.
 *
 *                * An infinity matches another infinity of the same sign,
 *                  and nothing else.
 *
 *                * If @f&TVFF_EQMASK@ is @TVFF_EXACT@, then any
 *                  representable number matches only itself: in particular,
 *                  positive and negative zero are considered distinct.
 *                  (This allows tests to check that they land on the correct
 *                  side of branch cuts, for example.)
 *
 *                * If @f&TVFF_EQMASK@ is @TVFF_ABSDELTA@, then %$x$% matches
 *                  %$y$% when %$|x - y| < \delta$%.
 *
 *                * If @f&TVFF_EQMASK@ is @TVFF_RELDELTA@, then %$x$% matches
 *                  %$y$% when %$|1 - y/x| < \delta$%.  (Note that this
 *                  criterion is asymmetric FIXME
 *
 *              The @TVEC_CLAIM_FLOAT@ macro is similar, only it (a)
 *              identifies the file and line number of the call site
 *              automatically, and (b) implicitly quotes the source text of
 *              the @f0@ and @f1@ arguments (and @delta@) in the failure
 *              message.
 */

extern int tvec_claimeqish_float(struct tvec_state */*tv*/,
                                 double /*f0*/, double /*f1*/,
                                 unsigned /*f*/, double /*delta*/,
                                 const char */*file*/, unsigned /*lno*/,
                                 const char */*expr*/);
#define TVEC_CLAIMEQISH_FLOAT(tv, f0, f1, f, delta)                     \
        (tvec_claimeqish_float(tv, f0, f1, f, delta, , __FILE__, __LINE__, \
                               #f0 " /= " #f1 " (+/- " #delta ")"))

/* --- @tvec_claimeq_float@, @TVEC_CLAIMEQ_FLOAT@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @double f0, f1@ = two floating-point numbers
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if @f0@ and @u1@ are identical, otherwise zero.
 *
 * Use:         Check that values of @f0@ and @f1@ are identical.  The
 *              function is exactly equivalent to @tvec_claimeqish_float@
 *              with @f == TVFF_EXACT@; the macro is similarly like
 *              @TVEC_CLAIMEQISH_FLOAT@ with @f == TVFF_EXACT@, except that
 *              it doesn't bother to quote a delta.
 */

extern int tvec_claimeq_float(struct tvec_state */*tv*/,
                              double /*f0*/, double /*f1*/,
                              const char */*file*/, unsigned /*lno*/,
                              const char */*expr*/);
#define TVEC_CLAIMEQ_FLOAT(tv, f0, f1)                                  \
        (tvec_claimeq_float(tv, f0, f1, __FILE__, __LINE__, #f0 " /= " #f1))

/*----- Enumerated types --------------------------------------------------*/

/* An enumeration describes a set of values of some underlying type, each of
 * which has a symbolic name.  Values outside of the defined set can occur --
 * on output, because of bugs in the tested code, or on input to test
 * handling of unexpected values.
 *
 * There is a distinct enumerated type for each of the branches of
 * @tvec_misc@.  In the following, we write @t@ for the type code, which is
 * @i@ for signed integer, @u@ for unsigned integer, @f@ for floating-point,
 * and @p@ for pointer.
 *
 * On input, an enumerated value may be given by name or as a literal value.
 * For enumerations based on numeric types, the literal values can be written
 * in the same syntax as the underlying values.  For enumerations based on
 * pointers, the only permitted literal is `#nil', which denotes a null
 * pointer.  On output, names are preferred (with the underlying value given
 * in a comment).
 */

#define DEFENUMTY(tag, ty, slot)                                        \
        extern const struct tvec_regty tvty_##slot##enum;
TVEC_MISCSLOTS(DEFENUMTY)
#undef DEFENUMTY

/* A @struct tvec_tassoc@ associates a string tag with a value. */
#define DEFASSOC(tag_, ty, slot)                                        \
        struct tvec_##slot##assoc { const char *tag; ty slot; };
TVEC_MISCSLOTS(DEFASSOC)
#undef DEFASSOC

#define TVEC_ENDENUM { 0, 0 }

/* Information about an enumerated type. */
#define DEFINFO(tag, ty, slot)                                          \
        struct tvec_##slot##enuminfo {                                  \
          const char *name;             /* type name for diagnostics */ \
          const struct tvec_##slot##assoc *av; /* name/value mappings */ \
          EXTRA_##tag##_INFOSLOTS       /* type-specific extra info */  \
        };

#define EXTRA_INT_INFOSLOTS                                             \
        const struct tvec_irange *ir;   /* allowed range of raw values */

#define EXTRA_UINT_INFOSLOTS                                            \
        const struct tvec_urange *ur;   /* allowed range of raw values */

#define EXTRA_FLT_INFOSLOTS                                             \
        const struct tvec_floatinfo *fi; /* range and matching policy */

#define EXTRA_PTR_INFOSLOTS             /* (nothing) */

TVEC_MISCSLOTS(DEFINFO)

#undef EXTRA_INT_INFOSLOTS
#undef EXTRA_UINT_INFOSLOTS
#undef EXTRA_FLT_INFOSLOTS
#undef EXTRA_PTR_INFOSLOTS

#undef DEFINFO

/* Standard enumerations. */
const struct tvec_ienuminfo tvenum_bool;

/* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const struct tvec_typeenuminfo *ei@ = enumeration type info
 *              @ty t0, t1@ = two values
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if @t0@ and @t1@ are equal, otherwise zero.
 *
 * Use:         Check that values of @t0@ and @t1@ are equal.  As for
 *              @tvec_claim@ above, a test case is automatically begun and
 *              ended if none is already underway.  If the values are
 *              unequal, then @tvec_fail@ is called, quoting @expr@, and the
 *              mismatched values are dumped: @t0@ is printed as the output
 *              value and @t1@ is printed as the input reference.
 *
 *              The @TVEC_CLAIM_TENUM@ macro is similar, only it (a)
 *              identifies the file and line number of the call site
 *              automatically, and (b) implicitly quotes the source text of
 *              the @t0@ and @t1@ arguments in the failure message.
 */

#define DECLCLAIM(tag, ty, slot)                                        \
        extern int tvec_claimeq_##slot##enum                            \
          (struct tvec_state */*tv*/,                                   \
           const struct tvec_##slot##enuminfo */*ei*/,                  \
           ty /*t0*/, ty /*t1*/,                                        \
           const char */*file*/, unsigned /*lno*/, const char */*expr*/);
TVEC_MISCSLOTS(DECLCLAIM)
#undef DECLCLAIM
#define TVEC_CLAIMEQ_IENUM(tv, ei, i0, i1)                              \
        (tvec_claimeq_ienum(tv, ei, i0, i1,                             \
                            __FILE__, __LINE__, #i0 " /= " #i1))
#define TVEC_CLAIMEQ_UENUM(tv, ei, u0, u1)                              \
        (tvec_claimeq_uenum(tv, ei, u0, u1,                             \
                            __FILE__, __LINE__, #u0 " /= " #u1))
#define TVEC_CLAIMEQ_FENUM(tv, ei, f0, f1)                              \
        (tvec_claimeq_fenum(tv, ei, f0, f1,                             \
                            __FILE__, __LINE__, #f0 " /= " #f1))
#define TVEC_CLAIMEQ_PENUM(tv, ei, p0, p1)                              \
        (tvec_claimeq_penum(tv, ei, p0, p1,                             \
                            __FILE__, __LINE__, #p0 " /= " #p1))

/*----- Flags type --------------------------------------------------------*/

/* A flags value packs a number of fields into a single nonnegative integer.
 * Symbolic names are associated with the possible values of the various
 * fields; more precisely, each name is associated with a value and a
 * covering bitmask.
 *
 * The input syntax is a sequence of items separated by `|' signs.  Each item
 * may be the symbolic name of a field value, or a literal unsigned integer.
 * The masks associated with the given symbolic names must be disjoint.  The
 * resulting numerical value is simply the bitwise OR of the given values.
 *
 * On output, the table of symbolic names and their associated values and
 * masks is repeatedly scanned, in order, to find disjoint matches -- i.e.,
 * entries whose value matches the target value in the bit positions
 * indicated by the mask, and whose mask doesn't overlap with any previously
 * found matches; the names are then output, separated by `|'.  Any remaining
 * nonzero bits not covered by any of the matching masks are output as a
 * single literal integer, in hex.
 */

extern const struct tvec_regty tvty_flags;

struct tvec_flag {
  /* Definition of a single flag or bitfield value.
   *
   * Each named setting comes with a value @v@ and a mask @m@; the mask
   * should cover all of the value bits, i.e., @(v&~m) == 0@.
   */

  const char *tag;                      /* name */
  unsigned long m, v;                   /* mask and value */
};

#define TVEC_ENDFLAGS { 0, 0, 0 }

struct tvec_flaginfo {
  /* Information about a flags type. */

  const char *name;                     /* type name for diagnostics  */
  const struct tvec_flag *fv;           /* name/mask/value mappings */
  const struct tvec_urange *range;      /* permitted range for literals */
};

/* --- @tvec_claimeq_flags@, @TVEC_CLAIMEQ_FLAGS@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const struct tvec_flaginfo *fi@ = flags type info
 *              @unsigned long f0, f1@ = two values
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if @f0@ and @f1@ are equal, otherwise zero.
 *
 * Use:         Check that values of @f0@ and @f1@ are equal.  As for
 *              @tvec_claim@ above, a test case is automatically begun and
 *              ended if none is already underway.  If the values are
 *              unequal, then @tvec_fail@ is called, quoting @expr@, and the
 *              mismatched values are dumped: @f0@ is printed as the output
 *              value and @f1@ is printed as the input reference.
 *
 *              The @TVEC_CLAIM_FLAGS@ macro is similar, only it (a)
 *              identifies the file and line number of the call site
 *              automatically, and (b) implicitly quotes the source text of
 *              the @f0@ and @f1@ arguments in the failure message.
 */

extern int tvec_claimeq_flags(struct tvec_state */*tv*/,
                              const struct tvec_flaginfo */*fi*/,
                              unsigned long /*f0*/, unsigned long /*f1*/,
                              const char */*file*/, unsigned /*lno*/,
                              const char */*expr*/);
#define TVEC_CLAIMEQ_FLAGS(tv, fi, f0, f1)                              \
        (tvec_claimeq_flags(tv, fi, f0, f1,                             \
                            __FILE__, __LINE__, #f0 " /= " #f1))

/*----- Character type ----------------------------------------------------*/

/* A character value holds a character, as read by @fgetc@.  The special
 * @EOF@ value can also be represented.
 *
 * On input, a character value can be given by name, with a leading `%|#|%';
 * or a character or `%|\|%'-escape sequence, optionally in single quotes.
 *
 * The following escape sequences and character names are recognized.
 *
 *   * `%|#eof|%' is the special end-of-file marker.
 *
 *   * `%|#nul|%' is the NUL character, sometimes used to terminate strings.
 *
 *   * `%|bell|%', `%|bel|%', `%|ding|%', or `%|\a|%' is the BEL character
 *     used to ring the terminal bell (or do some other thing to attract the
 *     user's attention).
 *
 *   * %|#backspace|%, %|#bs|%, or %|\b|% is the backspace character, used to
 *     move the cursor backwords by one cell.
 *
 *   * %|#escape|% %|#esc|%, or%|\e|% is the escape character, used to
 *     introduce special terminal commands.
 *
 *   * %|#formfeed|%, %|#ff|%, or %|\f|% is the formfeed character, used to
 *     separate pages of text.
 *
 *   * %|#newline|%, %|#linefeed|%, %|#lf|%, %|#nl|%, or %|\n|% is the
 *     newline character, used to terminate lines of text or advance the
 *     cursor to the next line (perhaps without returning it to the start of
 *     the line).
 *
 *   * %|#return|%, %|#carriage-return|%, %|#cr|%, or %|\r|% is the
 *     carriage-return character, used to return the cursor to the start of
 *     the line.
 *
 *   * %|#tab|%, %|#horizontal-tab|%, %|#ht|%, or %|\t|% is the tab
 *     character, used to advance the cursor to the next tab stop on the
 *     current line.
 *
 *   * %|#vertical-tab|%, %|#vt|%, %|\v|% is the vertical tab character.
 *
 *   * %|#space|%, %|#spc|% is the space character.
 *
 *   * %|#delete|%, %|#del|% is the delete character, used to erase the most
 *     recent character.
 *
 *   * %|\'|% is the single-quote character.
 *
 *   * %|\\|% is the backslash character.
 *
 *   * %|\"|% is the double-quote character.
 *
 *   * %|\NNN|% or %|\{NNN}|% is the character with code NNN in octal.  The
 *     NNN may be up to three digits long.
 *
 *   * %|\xNN|% or %|\x{NN}|% is the character with code NNN in hexadecimal.
 */

extern const struct tvec_regty tvty_char;

/* --- @tvec_claimeq_char@, @TVEC_CLAIMEQ_CHAR@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @int ch0, ch1@ = two character codes
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if @ch0@ and @ch1@ are equal, otherwise zero.
 *
 * Use:         Check that values of @ch0@ and @ch1@ are equal.  As for
 *              @tvec_claim@ above, a test case is automatically begun and
 *              ended if none is already underway.  If the values are
 *              unequal, then @tvec_fail@ is called, quoting @expr@, and the
 *              mismatched values are dumped: @ch0@ is printed as the output
 *              value and @ch1@ is printed as the input reference.
 *
 *              The @TVEC_CLAIM_CHAR@ macro is similar, only it (a)
 *              identifies the file and line number of the call site
 *              automatically, and (b) implicitly quotes the source text of
 *              the @ch0@ and @ch1@ arguments in the failure message.
 */

extern int tvec_claimeq_char(struct tvec_state */*tv*/,
                             int /*ch0*/, int /*ch1*/,
                             const char */*file*/, unsigned /*lno*/,
                             const char */*expr*/);
#define TVEC_CLAIMEQ_CHAR(tv, c0, c1)                                   \
        (tvec_claimeq_char(tv, c0, c1, __FILE__, __LINE__, #c0 " /= " #c1))

/*----- Text and binary string types --------------------------------------*/

/* A string is a sequence of octets.  Text and binary strings differ
 * primarily in presentation: text strings are shown as raw characters where
 * possible; binary strings are shown as hex dumps with an auxiliary text
 * display.
 *
 * The input format for both kinds of strings is basically the same: a
 * `compound string', consisting of
 *
 *   * single-quoted strings, which are interpreted entirely literally, but
 *     can't contain single quotes or newlines;
 *
 *   * double-quoted strings, in which `%|\|%'-escapes are interpreted as for
 *     characters;
 *
 *   * character names, marked by an initial `%|#|%' sign;
 *
 *   * special tokens marked by an initial `%|!|%' sign; or
 *
 *   * barewords interpreted according to the current coding scheme.
 *
 * The special tokens are
 *
 *   * `%|!bare|%', which causes subsequent sequences of barewords to be
 *     treated as plain text;
 *
 *   * `%|!hex|%', `%|!base32|%', `%|!base64|%', which cause subsequent
 *     barewords to be decoded in the requested manner.
 *
 *   * `%|!repeat|% %$n$% %|{|% %%\textit{string}%% %|}|%', which includes
 *     %$n$% copies of the (compound) string.
 *
 * Either kind of string can contain internal nul characters.  A trailing nul
 * is appended -- beyond the stated input length -- to input strings as a
 * convenience to test functions.  Test functions may include such a nul
 * character on output but this is not checked by the equality test.
 *
 * A @struct tvec_urange@ may be supplied as an argument: the length of the
 * string (in bytes) will be checked against the permitted range.
 */

extern const struct tvec_regty tvty_string, tvty_bytes;

/* --- @tvec_claimeq_string@, @TVEC_CLAIMEQ_STRING@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *p0@, @size_t sz0@ = first string with length
 *              @const char *p1@, @size_t sz1@ = second string with length
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
 *              zero.
 *
 * Use:         Check that strings at @p0@ and @p1@ are equal.  As for
 *              @tvec_claim@ above, a test case is automatically begun and
 *              ended if none is already underway.  If the values are
 *              unequal, then @tvec_fail@ is called, quoting @expr@, and the
 *              mismatched values are dumped: @p0@ is printed as the output
 *              value and @p1@ is printed as the input reference.
 *
 *              The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
 *              identifies the file and line number of the call site
 *              automatically, and (b) implicitly quotes the source text of
 *              the @ch0@ and @ch1@ arguments in the failure message.
 */

extern int tvec_claimeq_string(struct tvec_state */*tv*/,
                               const char */*p0*/, size_t /*sz0*/,
                               const char */*p1*/, size_t /*sz1*/,
                               const char */*file*/, unsigned /*lno*/,
                               const char */*expr*/);
#define TVEC_CLAIMEQ_STRING(tv, p0, sz0, p1, sz1)                       \
        (tvec_claimeq_string(tv, p0, sz0, p1, sz1, __FILE__, __LINE__,  \
                             #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))

/* --- @tvec_claimeq_strz@, @TVEC_CLAIMEQ_STRZ@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *p0, *p1@ = two strings to compare
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
 *              zero.
 *
 * Use:         Check that strings at @p0@ and @p1@ are equal, as for
 *              @tvec_claimeq_string@, except that the strings are assumed
 *              null-terminated, so their lengths don't need to be supplied
 *              explicitly.  The macro is similarly like
 *              @TVEC_CLAIMEQ_STRING@.
 */

extern int tvec_claimeq_strz(struct tvec_state */*tv*/,
                             const char */*p0*/, const char */*p1*/,
                             const char */*file*/, unsigned /*lno*/,
                             const char */*expr*/);
#define TVEC_CLAIMEQ_STRZ(tv, p0, p1)                                   \
        (tvec_claimeq_strz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))

/* --- @tvec_claimeq_bytes@, @TVEC_CLAIMEQ_BYTES@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const void *p0@, @size_t sz0@ = first string with length
 *              @const void *p1@, @size_t sz1@ = second string with length
 *              @const char *file@, @unsigned @lno@ = calling file and line
 *              @const char *expr@ = the expression to quote on failure
 *
 * Returns:     Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
 *              zero.
 *
 * Use:         Check that binary strings at @p0@ and @p1@ are equal.  As for
 *              @tvec_claim@ above, a test case is automatically begun and
 *              ended if none is already underway.  If the values are
 *              unequal, then @tvec_fail@ is called, quoting @expr@, and the
 *              mismatched values are dumped: @p0@ is printed as the output
 *              value and @p1@ is printed as the input reference.
 *
 *              The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
 *              identifies the file and line number of the call site
 *              automatically, and (b) implicitly quotes the source text of
 *              the @ch0@ and @ch1@ arguments in the failure message.
 */

extern int tvec_claimeq_bytes(struct tvec_state */*tv*/,
                               const void */*p0*/, size_t /*sz0*/,
                               const void */*p1*/, size_t /*sz1*/,
                               const char */*file*/, unsigned /*lno*/,
                               const char */*expr*/);
#define TVEC_CLAIMEQ_BYTES(tv, p0, sz0, p1, sz1)                        \
        (tvec_claimeq(tv, p0, sz0, p1, sz1, __FILE__, __LINE__,         \
                      #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))

/* --- @tvec_allocstring@, @tvec_allocbytes@ --- *
 *
 * Arguments:   @union tvec_regval *rv@ = register value
 *              @size_t sz@ = required size
 *
 * Returns:     ---
 *
 * Use:         Allocated space in a text or binary string register.  If the
 *              current register size is sufficient, its buffer is left
 *              alone; otherwise, the old buffer, if any, is freed and a
 *              fresh buffer allocated.  These functions are not intended to
 *              be used to adjust a buffer repeatedly, e.g., while building
 *              output incrementally: (a) they will perform badly, and (b)
 *              the old buffer contents are simply discarded if reallocation
 *              is necessary.  Instead, use a @dbuf@ or @dstr@.
 *
 *              The @tvec_allocstring@ function sneakily allocates an extra
 *              byte for a terminating zero.  The @tvec_allocbytes@ function
 *              doesn't do this.
 */

extern void tvec_allocstring(union tvec_regval */*rv*/, size_t /*sz*/);
extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);

/*----- Buffer type -------------------------------------------------------*/

/* Buffer registers are primarily used for benchmarking.  Only a buffer's
 * size is significant: its contents are ignored on comparison and output,
 * and unspecified on input.
 *
 * The input is simply the buffer size, as an integer, optionally suffixed
 * with a unit `kB', `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or
 * without the `B') denoting a power of 1024.  Units are used on output only
 * when the size would be expressed exactly.
 */

extern const struct tvec_regty tvty_buffer;

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

#ifdef __cplusplus
  }
#endif

#endif