@@@ more mess

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

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

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

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

/* Possible test outcomes. */
enum { TVOUT_LOSE, TVOUT_SKIP, TVOUT_WIN, TVOUT_LIMIT };

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 */
#define TVSF_OUTSHIFT 4

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

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


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

/* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- *
 *
 * Arguments:	@struct tvec_state *tv@ = test-vector state
 *		@const char *excuse@, @va_list ap@ = reason why group 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*/);

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

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

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

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

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

struct tvec_output {
  const struct tvec_outops *ops;
  struct tvec_state *tv;
};

enum { TVBU_OP, TVBU_BYTE };

struct bench_timing;

struct tvec_outops {
  void (*error)(struct tvec_output */*o*/,
		const char */*msg*/, va_list */*ap*/);
  void (*notice)(struct tvec_output */*o*/,
		 const char */*msg*/, va_list */*ap*/);

  void (*bsession)(struct tvec_output */*o*/);
  int (*esession)(struct tvec_output */*o*/);

  void (*bgroup)(struct tvec_output */*o*/);
  void (*egroup)(struct tvec_output */*o*/, unsigned /*outcome*/);
  void (*skipgroup)(struct tvec_output */*o*/,
		    const char */*excuse*/, va_list */*ap*/);

  void (*btest)(struct tvec_output */*o*/);
  void (*skip)(struct tvec_output */*o*/,
	       const char */*excuse*/, va_list */*ap*/);
  void (*fail)(struct tvec_output */*o*/,
	       const char */*detail*/, va_list */*ap*/);
  void (*dumpreg)(struct tvec_output */*o*/,
		  unsigned /*disp*/, const union tvec_regval */*rv*/,
		  const struct tvec_regdef */*rd*/);
  void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/);

  void (*bbench)(struct tvec_output */*o*/,
		 const char */*ident*/, unsigned /*unit*/);
  void (*ebench)(struct tvec_output */*o*/,
		 const char */*ident*/, unsigned /*unit*/,
		 const struct bench_timing */*tm*/);

  void (*destroy)(struct tvec_output */*o*/);
};

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

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

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

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

struct tvec_regty {
  void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
  void (*release)(union tvec_regval */*rv*/,
		  const struct tvec_regdef */*rd*/);
  int (*eq)(const union tvec_regval */*rv0*/,
	    const union tvec_regval */*rv1*/,
	    const struct tvec_regdef */*rd*/);
  int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
	       const struct tvec_regdef */*rd*/);
  int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
		 const struct tvec_regdef */*rd*/);
  int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
	       struct tvec_state */*tv*/);
  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
};

extern const struct tvec_regty tvty_int, tvty_uint;
struct tvec_irange { long min, max; };
struct tvec_urange { unsigned long min, max; };

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;
extern const struct tvec_frange
  tvrange_float, tvrange_double;

extern int tvec_claimeq_int(struct tvec_state */*tv*/,
			    long /*i0*/, long /*i1*/,
			    const char */*file*/, unsigned /*lno*/,
			    const char */*expr*/);
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_INT(tv, i0, i1)					\
	(tvec_claimeq_int(tv, i0, i1, __FILE__, __LINE__, #i0 " /= " #i1))
#define TVEC_CLAIMEQ_UINT(tv, u0, u1)					\
	(tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))

extern const struct tvec_regty tvty_float;
struct tvec_floatinfo {
  unsigned f;
#define TVFF_NOMIN 1u
#define TVFF_NOMAX 2u
#define TVFF_NANOK 4u
#define TVFF_EXACT 0u
#define TVFF_ABSDELTA 0x10
#define TVFF_RELDELTA 0x20
#define TVFF_EQMASK 0xf0
  double min, max;
  double delta;
};

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*/);
extern int tvec_claimeq_float(struct tvec_state */*tv*/,
			      double /*f0*/, double /*f1*/,
			      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 ")"))
#define TVEC_CLAIMEQ_FLOAT(tv, f0, f1)					\
	(tvec_claimeq_float(tv, f0, f1, __FILE__, __LINE__, #f0 " /= " #f1))

extern const struct tvec_regty tvty_enum;

#define DEFASSOC(tag_, ty, slot)					\
	struct tvec_##slot##assoc { const char *tag; ty slot; };
TVEC_MISCSLOTS(DEFASSOC)
#undef DEFASSOC

struct tvec_enuminfo { const char *name; unsigned mv; /* ... */ };
struct tvec_ienuminfo {
  struct tvec_enuminfo _ei;
  const struct tvec_iassoc *av;
  const struct tvec_irange *ir;
};
struct tvec_uenuminfo {
  struct tvec_enuminfo _ei;
  const struct tvec_uassoc *av;
  const struct tvec_urange *ur;
};
struct tvec_fenuminfo {
  struct tvec_enuminfo _ei;
  const struct tvec_fassoc *av;
  const struct tvec_floatinfo *fi;
};
struct tvec_penuminfo {
  struct tvec_enuminfo _ei;
  const struct tvec_passoc *av;
};

const struct tvec_ienuminfo tvenum_bool;

#define DECLCLAIM(tag, ty, slot)					\
	extern int tvec_claimeq_##slot##enum				\
	  (struct tvec_state */*tv*/,					\
	   const struct tvec_##slot##enuminfo */*ei*/,			\
	   ty /*e0*/, ty /*e1*/,					\
	   const char */*file*/, unsigned /*lno*/, const char */*expr*/);
TVEC_MISCSLOTS(DECLCLAIM)
#undef DECLCLAIM
#define TVEC_CLAIMEQ_IENUM(tv, ei, e0, e1)				\
	(tvec_claimeq_ienum(tv, ei, e0, e1,				\
			    __FILE__, __LINE__, #e0 " /= " #e1))
#define TVEC_CLAIMEQ_UENUM(tv, ei, e0, e1)				\
	(tvec_claimeq_uenum(tv, ei, e0, e1,				\
			    __FILE__, __LINE__, #e0 " /= " #e1))
#define TVEC_CLAIMEQ_FENUM(tv, ei, e0, e1)				\
	(tvec_claimeq_fenum(tv, ei, e0, e1,				\
			    __FILE__, __LINE__, #e0 " /= " #e1))
#define TVEC_CLAIMEQ_PENUM(tv, ei, e0, e1)				\
	(tvec_claimeq_penum(tv, ei, e0, e1,				\
			    __FILE__, __LINE__, #e0 " /= " #e1))

extern const struct tvec_regty tvty_flags;
struct tvec_flag { const char *tag; unsigned long m, v; };
struct tvec_flaginfo {
  const char *name;
  const struct tvec_flag *fv;
  const struct tvec_urange *range;
};

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))

extern const struct tvec_regty tvty_char;
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))

extern const struct tvec_regty tvty_string, tvty_bytes;

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*/);
extern int tvec_claimeq_strz(struct tvec_state */*tv*/,
			     const char */*p0*/, const char */*p1*/,
			     const char */*file*/, unsigned /*lno*/,
			     const char */*expr*/);
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_STRING(tv, p0, sz0, p1, sz1)			\
	(tvec_claimeq_string(tv, p0, sz0, p1, sz1, __FILE__, __LINE__,	\
			     #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
#define TVEC_CLAIMEQ_STRZ(tv, p0, p1)					\
	(tvec_claimeq_strz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
#define TVEC_CLAIMEQ_BYTES(tv, p0, sz0, p1, sz1)			\
	(tvec_claimeq(tv, p0, sz0, p1, sz1, __FILE__, __LINE__,		\
		      #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))

extern const struct tvec_regty tvty_buffer;

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

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

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

extern void tvec_begingroup(struct tvec_state */*tv*/, const char */*name*/,
			    const char */*file*/, unsigned /*lno*/);
extern void tvec_reportgroup(struct tvec_state */*tv*/);
extern void tvec_endgroup(struct tvec_state */*tv*/);

#define TVEC_BEGINGROUP(tv, name)					\
	do tvec_begingroup(tv, name, __FILE__, __LINE__); while (0)

#define TVEC_TESTGROUP(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); })

extern void tvec_begintest(struct tvec_state */*tv*/,
			   const char */*file*/, unsigned /*lno*/);
extern void tvec_endtest(struct tvec_state */*tv*/);

#define TVEC_BEGINTEST(tv)						\
	do tvec_begintest(tv, __FILE__, __LINE__); while (0)

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

extern int PRINTF_LIKE(5, 6)
  tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
	     const char */*file*/, unsigned /*lno*/,
	     const char */*expr*/, ...);

#define TVEC_CLAIM(tv, cond)						\
	(tvec_claim(tv, !!(cond), __FILE__, __LINE__, #cond " untrue"))

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;		/* environment (per test, not grp) */
};
#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;

extern int tvec_benchsetup(struct tvec_state */*tv*/,
			   const struct tvec_env */*env*/,
			   void */*pctx*/, void */*ctx*/);
extern int tvec_benchset(struct tvec_state */*tv*/, const char */*var*/,
			 const struct tvec_env */*env*/, void */*ctx*/);
extern int tvec_benchbefore(struct tvec_state */*tv*/, void */*ctx*/);
extern void tvec_benchrun(struct tvec_state */*tv*/,
			  tvec_testfn */*fn*/, void */*ctx*/);
extern void tvec_benchafter(struct tvec_state */*tv*/, void */*ctx*/);
extern void tvec_benchteardown(struct tvec_state */*tv*/, void */*ctx*/);

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

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

extern const struct tvec_config tvec_adhocconfig;

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

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

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

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

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

#ifdef __cplusplus
  }
#endif

#endif