@@@ tvec doc wip

[mLib] / test / tvec-core.c

/* -*-c-*-
 *
 * Main test vector driver
 *
 * (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.
 */

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

#include <assert.h>
#include <ctype.h>
#include <errno.h>
#include <string.h>

#include "alloc.h"
#include "tvec.h"

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

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

const char *tvec_strlevel(unsigned level)
{
  switch (level) {
#define CASE(tag, name, val)                                            \
    case TVLEV_##tag: return (name);
    TVEC_LEVELS(CASE)
#undef CASE
    default: return ("??");
  }
}

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

void tvec_report(struct tvec_state *tv, unsigned level, const char *msg, ...)
{
  va_list ap;

  va_start(ap, msg); tvec_report_v(tv, level, msg, &ap); va_end(ap);
}

void tvec_report_v(struct tvec_state *tv, unsigned level,
                   const char *msg, va_list *ap)
{
  tv->output->ops->report(tv->output, level, msg, ap);
  if (level >= TVLEV_ERR) tv->f |= TVSF_ERROR;
}

/* --- @tvec_error@, @tvec_notice@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @const char *msg@, @va_list ap@ = error message
 *
 * Returns:     The @tvec_error@ function returns @-1@ as a trivial
 *              convenience; @tvec_notice@ does not return a value.
 *
 * Use:         Report an error or a notice.  Errors are distinct from test
 *              failures, and indicate that a problem was encountered which
 *              compromised the activity of testing.  Notices are important
 *              information which doesn't fit into any other obvious
 *              category.
 */

int tvec_error(struct tvec_state *tv, const char *msg, ...)
{
  va_list ap;

  va_start(ap, msg); tvec_report_v(tv, TVLEV_ERR, msg, &ap); va_end(ap);
  return (-1);
}

void tvec_notice(struct tvec_state *tv, const char *msg, ...)
{
  va_list ap;

  va_start(ap, msg); tvec_report_v(tv, TVLEV_NOTE, msg, &ap); va_end(ap);
}

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

void tvec_skipgroup(struct tvec_state *tv, const char *excuse, ...)
{
  va_list ap;

  va_start(ap, excuse); tvec_skipgroup_v(tv, excuse, &ap); va_end(ap);
}

void tvec_skipgroup_v(struct tvec_state *tv, const char *excuse, va_list *ap)
{
  if (!(tv->f&TVSF_SKIP)) {
    tv->f |= TVSF_SKIP; tv->grps[TVOUT_SKIP]++;
    tv->output->ops->skipgroup(tv->output, excuse, ap);
  }
}

/* --- @set_outcome@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @unsigned out@ = the new outcome
 *
 * Returns:     ---
 *
 * Use:         Sets the outcome bits in the test state flags, and clears
 *              @TVSF_ACTIVE@.
 */

static void set_outcome(struct tvec_state *tv, unsigned out)
  { tv->f = (tv->f&~(TVSF_ACTIVE | TVSF_OUTMASK)) | (out << TVSF_OUTSHIFT); }

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

void tvec_skip(struct tvec_state *tv, const char *excuse, ...)
{
  va_list ap;
  va_start(ap, excuse); tvec_skip_v(tv, excuse, &ap); va_end(ap);
}

void tvec_skip_v(struct tvec_state *tv, const char *excuse, va_list *ap)
{
  assert(tv->f&TVSF_ACTIVE);
  set_outcome(tv, TVOUT_SKIP);
  tv->output->ops->skip(tv->output, excuse, ap);
}

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

void tvec_fail(struct tvec_state *tv, const char *detail, ...)
{
  va_list ap;
  va_start(ap, detail); tvec_fail_v(tv, detail, &ap); va_end(ap);
}

void tvec_fail_v(struct tvec_state *tv, const char *detail, va_list *ap)
{
  assert((tv->f&TVSF_ACTIVE) ||
         (tv->f&TVSF_OUTMASK) == (TVOUT_LOSE << TVSF_OUTSHIFT));
  set_outcome(tv, TVOUT_LOSE); tv->output->ops->fail(tv->output, detail, ap);
}

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

void tvec_dumpreg(struct tvec_state *tv,
                  unsigned disp, const union tvec_regval *r,
                  const struct tvec_regdef *rd)
  { tv->output->ops->dumpreg(tv->output, disp, r, 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.
 */

void tvec_mismatch(struct tvec_state *tv, unsigned f)
{
  const struct tvec_regdef *rd;
  const struct tvec_reg *rin, *rout;

  for (rd = tv->test->regs; rd->name; rd++) {
    if (rd->i >= tv->nrout) {
      if (!(f&TVMF_IN)) continue;
      rin = TVEC_REG(tv, in, rd->i);
      tvec_dumpreg(tv, TVRD_INPUT, rin->f&TVRF_LIVE ? &rin->v : 0, rd);
    } else {
      if (!(f&TVMF_OUT)) continue;
      rin = TVEC_REG(tv, in, rd->i); rout = TVEC_REG(tv, out, rd->i);
      if (!(rin->f&TVRF_LIVE))
        tvec_dumpreg(tv, TVRD_OUTPUT, rout->f&TVRF_LIVE ? &rout->v : 0, rd);
      else if ((rout->f&TVRF_LIVE) && rd->ty->eq(&rin->v, &rout->v, rd))
        tvec_dumpreg(tv, TVRD_MATCH, &rin->v, rd);
      else {
        tvec_dumpreg(tv, TVRD_FOUND, rout->f&TVRF_LIVE ? &rout->v : 0, rd);
        tvec_dumpreg(tv, TVRD_EXPECT, &rin->v, rd);
      }
    }
  }
}

/*----- Parsing -----------------------------------------------------------*/

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

int tvec_syntax(struct tvec_state *tv, int ch, const char *expect, ...)
{
  va_list ap;

  va_start(ap, expect); tvec_syntax_v(tv, ch, expect, &ap); va_end(ap);
  return (-1);
}

int tvec_syntax_v(struct tvec_state *tv, int ch,
                  const char *expect, va_list *ap)
{
  dstr d = DSTR_INIT;
  char found[8];

  switch (ch) {
    case EOF: strcpy(found, "#eof"); break;
    case '\n': strcpy(found, "#eol"); ungetc(ch, tv->fp); break;
    default:
      if (isprint(ch)) sprintf(found, "`%c'", ch);
      else sprintf(found, "#\\x%02x", ch);
      break;
  }
  dstr_vputf(&d, expect, ap);
  tvec_error(tv, "syntax error: expected %s but found %s", d.buf, found);
  dstr_destroy(&d); return (-1);
}

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

int tvec_dupreg(struct tvec_state *tv, const char *name)
  { return (tvec_error(tv, "register `%s' is already set", name)); }

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

void tvec_skipspc(struct tvec_state *tv)
{
  int ch;

  for (;;) {
    ch = getc(tv->fp);
    if (ch == EOF) break;
    else if (ch == '\n' || !isspace(ch)) { ungetc(ch, tv->fp); break; }
  }
}

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

int tvec_flushtoeol(struct tvec_state *tv, unsigned f)
{
  int ch, rc = 0;

  for (;;) {
    ch = getc(tv->fp);
    switch (ch) {
      case '\n': tv->lno++; return (rc);
      case EOF: return (rc);
      case ';': f |= TVFF_ALLOWANY; break;
      default:
        if (!(f&TVFF_ALLOWANY) && !isspace(ch)) {
          tvec_syntax(tv, ch, "end-of-line");
          rc = -1; f |= TVFF_ALLOWANY;
        }
        break;
    }
  }
}

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

int tvec_nexttoken(struct tvec_state *tv)
{
  enum { TAIL, NEWLINE, INDENT, COMMENT };
  int ch;
  unsigned s = TAIL;

  for (;;) {
    ch = getc(tv->fp);
    switch (ch) {
      case EOF:
        return (-1);

      case ';':
        s = COMMENT;
        break;

      case '\n':
        if (s == NEWLINE || s == INDENT) { ungetc(ch, tv->fp); return (-1); }
        else { tv->lno++; s = NEWLINE; }
        break;

      default:
        if (isspace(ch))
          { if (s == NEWLINE) s = INDENT; }
        else if (s != COMMENT) {
          ungetc(ch, tv->fp);
          if (s == NEWLINE) return (-1);
          else return (0);
        }
        break;
    }
  }
}

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

int tvec_readword(struct tvec_state *tv, dstr *d, const char *delims,
                  const char *expect, ...)
{
  va_list ap;
  int rc;

  va_start(ap, expect);
  rc = tvec_readword_v(tv, d, delims, expect, &ap);
  va_end(ap);
  return (rc);
}

int tvec_readword_v(struct tvec_state *tv, dstr *d, const char *delims,
                    const char *expect, va_list *ap)
{
  int ch;

  ch = getc(tv->fp);
  if (!ch || ch == '\n' || ch == EOF || ch == ';' ||
      (delims && strchr(delims, ch))) {
    if (expect) return (tvec_syntax(tv, ch, expect, ap));
    else { ungetc(ch, tv->fp); return (-1); }
  }
  if (d->len) DPUTC(d, ' ');
  do {
    DPUTC(d, ch);
    ch = getc(tv->fp);
  } while (ch && ch != EOF && !isspace(ch) &&
           (!delims || !strchr(delims, ch)));
  DPUTZ(d); if (ch != EOF) ungetc(ch, tv->fp);
  return (0);
}

/*----- Main machinery ----------------------------------------------------*/

struct groupstate {
  void *ctx;                            /* test environment context */
};
#define GROUPSTATE_INIT { 0 }

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

void tvec_initregs(struct tvec_state *tv)
{
  const struct tvec_regdef *rd;
  struct tvec_reg *r;

  for (rd = tv->test->regs; rd->name; rd++) {
    assert(rd->i < tv->nreg); r = TVEC_REG(tv, in, rd->i);
    rd->ty->init(&r->v, rd); r->f = 0;
    if (rd->i < tv->nrout)
      { r = TVEC_REG(tv, out, rd->i); rd->ty->init(&r->v, rd); r->f = 0; }
  }
}

void tvec_releaseregs(struct tvec_state *tv)
{
  const struct tvec_regdef *rd;
  struct tvec_reg *r;

  for (rd = tv->test->regs; rd->name; rd++) {
    assert(rd->i < tv->nreg); r = TVEC_REG(tv, in, rd->i);
    rd->ty->release(&r->v, rd); r->f = 0;
    if (rd->i < tv->nrout)
      { r = TVEC_REG(tv, out, rd->i); rd->ty->release(&r->v, rd); r->f = 0; }
  }
}

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

void tvec_resetoutputs(struct tvec_state *tv)
{
  const struct tvec_regdef *rd;
  struct tvec_reg *r;

  for (rd = tv->test->regs; rd->name; rd++) {
    assert(rd->i < tv->nreg);
    if (rd->i >= tv->nrout) continue;
    r = TVEC_REG(tv, out, rd->i);
    rd->ty->release(&r->v, rd);
    rd->ty->init(&r->v, rd);
    r->f = TVEC_REG(tv, in, rd->i)->f&TVRF_LIVE;
  }
}

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

int tvec_checkregs(struct tvec_state *tv)
{
  const struct tvec_regdef *rd;
  const struct tvec_reg *rin, *rout;

  for (rd = tv->test->regs; rd->name; rd++) {
    if (rd->i >= tv->nrout) continue;
    rin = TVEC_REG(tv, in, rd->i); rout = TVEC_REG(tv, out, rd->i);
    if (!rin->f&TVRF_LIVE) continue;
    if (!(rout->f&TVRF_LIVE) || !rd->ty->eq(&rin->v, &rout->v, rd))
      return (-1);
  }
  return (0);
}

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

void tvec_check(struct tvec_state *tv, const char *detail, ...)
{
  va_list ap;
  va_start(ap, detail); tvec_check_v(tv, detail, &ap); va_end(ap);
}

void tvec_check_v(struct tvec_state *tv, const char *detail, va_list *ap)
{
  if (tvec_checkregs(tv))
    { tvec_fail_v(tv, detail, ap); tvec_mismatch(tv, TVMF_IN | TVMF_OUT); }
}

/* --- @open_test@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     ---
 *
 * Use:         Note that we are now collecting data for a new test.  The
 *              current line number is recorded in @test_lno@.  The
 *              @TVSF_OPEN@ flag is set, and @TVSF_XFAIL@ is reset.
 *
 *              If a test is already open, then do nothing.
 */

static void open_test(struct tvec_state *tv)
{
  if (!(tv->f&TVSF_OPEN)) {
    tv->test_lno = tv->lno;
    tv->f |= TVSF_OPEN; tv->f &= ~TVSF_XFAIL;
  }
}

/* --- @begin_test@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     ---
 *
 * Use:         Note that we're about to try running a state.  This is called
 *              before the test environment's @before@ function.  Mark the
 *              test as active, clear the outcome, and inform the output
 *              driver.
 */

static void begin_test(struct tvec_state *tv)
{
  tv->f |= TVSF_ACTIVE; tv->f &= ~TVSF_OUTMASK;
  tv->output->ops->btest(tv->output);
}

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

void tvec_endtest(struct tvec_state *tv)
{
  unsigned out;

  if (!(tv->f&TVSF_ACTIVE)) /* nothing to do */;
  else if (tv->f&TVSF_XFAIL) set_outcome(tv, TVOUT_XFAIL);
  else set_outcome(tv, TVOUT_WIN);
  out = (tv->f&TVSF_OUTMASK) >> TVSF_OUTSHIFT;
  assert(out < TVOUT_LIMIT); tv->curr[out]++;
  tv->output->ops->etest(tv->output, out);
  tv->f &= ~TVSF_OPEN;
}

/* --- @tvec_xfail@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     ---
 *
 * Use:         Mark the current test as an `expected failure'.  That is, the
 *              behaviour -- if everything works as expected -- is known to
 *              be incorrect, perhaps as a result of a longstanding bug, so
 *              calling it a `success' would be inappropriate.  A failure, as
 *              reported by @tvec_fail@, means that the behaviour is not as
 *              expected -- either the long-standing bug has been fixed, or a
 *              new bug has been introduced -- so investigation is required.
 *
 *              An expected failure doesn't cause the test group or the
 *              session as a whole to fail, but it isn't counted as a win
 *              either.
 */

void tvec_xfail(struct tvec_state *tv)
  { tv->f |= TVSF_XFAIL; }

/* --- @check@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @struct groupstate *g@ = private test group state
 *
 * Returns:     ---
 *
 * Use:         Run the current test.
 *
 *              This function is called once the data for a test has been
 *              collected.  It's responsible for checking that all of the
 *              necessary registers have been assigned values.  It marks the
 *              output registers as live if the corresponding inputs are
 *              live.  It calls the environment's @before@, @run@, and
 *              @after@ functions if provided; if there is no @run@ function,
 *              it calls @tvec_check@ to verify the output values.
 */

static void check(struct tvec_state *tv, struct groupstate *g)
{
  const struct tvec_test *t = tv->test;
  const struct tvec_env *env = t->env;
  const struct tvec_regdef *rd;

  if (!(tv->f&TVSF_OPEN)) return;

  for (rd = t->regs; rd->name; rd++) {
    if (TVEC_REG(tv, in, rd->i)->f&TVRF_LIVE)
      { if (rd->i < tv->nrout) TVEC_REG(tv, out, rd->i)->f |= TVRF_LIVE; }
    else if (!(rd->f&TVRF_OPT)) {
      tvec_error(tv, "required register `%s' not set in test `%s'",
                 rd->name, t->name);
      goto end;
    }
  }

  if (!(tv->f&TVSF_SKIP)) {
    begin_test(tv);
    if (env && env->before) env->before(tv, g->ctx);
    if (!(tv->f&TVSF_ACTIVE))
      /* setup forced a skip */;
    else if (env && env->run)
      env->run(tv, t->fn, g->ctx);
    else {
      t->fn(tv->in, tv->out, g->ctx);
      tvec_check(tv, 0);
    }
    tvec_endtest(tv);
  }
  if (env && env->after) env->after(tv, g->ctx);

end:
  tv->f &= ~TVSF_OPEN; tvec_releaseregs(tv); tvec_initregs(tv);
}

/* --- @begin_test_group@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @struct groupstate *g@ = private test group state
 *
 * Returns:     ---
 *
 * Use:         Begins a test group.  Expects @tv->test@ to have been set
 *              already.  Calls the output driver, initializes the registers,
 *              clears the @tv->curr@ counters, allocates the environment
 *              context and calls the environment @setup@ function.
 */

static void begin_test_group(struct tvec_state *tv, struct groupstate *g)
{
  const struct tvec_test *t = tv->test;
  const struct tvec_env *env = t->env;
  unsigned i;

  tv->output->ops->bgroup(tv->output);
  tv->f &= ~(TVSF_SKIP | TVSF_MUFFLE);
  tvec_initregs(tv);
  for (i = 0; i < TVOUT_LIMIT; i++) tv->curr[i] = 0;
  if (env && env->ctxsz) g->ctx = xmalloc(env->ctxsz);
  if (env && env->setup) env->setup(tv, env, 0, g->ctx);
}

/* --- @report_group@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *
 * Returns:     ---
 *
 * Use:         Reports the result of the test group to the output driver.
 *
 *              If all of the tests have been skipped then report this as a
 *              group skip.  Otherwise, determine and report the group
 *              outcome.
 */

static void report_group(struct tvec_state *tv)
{
  unsigned i, out, nrun;

  for (i = 0, nrun = 0; i < TVOUT_LIMIT; i++)
    { nrun += tv->curr[i]; tv->all[i] += tv->curr[i]; }

  if (tv->curr[TVOUT_SKIP] == nrun)
    { out = TVOUT_SKIP; tvec_skipgroup(tv, nrun ? 0 : "no tests to run"); }
  else {
    if (tv->curr[TVOUT_LOSE]) out = TVOUT_LOSE;
    else out = TVOUT_WIN;
    tv->grps[out]++; tv->output->ops->egroup(tv->output);
  }
}

/* --- @end_test_group@ --- *
 *
 * Arguments:   @struct tvec_state *tv@ = test-vector state
 *              @struct groupstate *g@ = private test group state
 *
 * Returns:     ---
 *
 * Use:         Handles the end of a test group.  Called at the end of the
 *              input file or when a new test group header is found.
 *
 *              If a test is open, call @check@ to see whether it worked.  If
 *              the test group is not being skipped, report the group
 *              result.  Call the test environment @teardown@ function.  Free
 *              the environment context and release the registers.
 *
 *              If there's no test group active, then nothing happens.
 */

static void end_test_group(struct tvec_state *tv, struct groupstate *g)
{
  const struct tvec_test *t = tv->test;
  const struct tvec_env *env;

  if (!t) return;
  if (tv->f&TVSF_OPEN) check(tv, g);
  if (!(tv->f&TVSF_SKIP)) report_group(tv);
  env = t->env; if (env && env->teardown) env->teardown(tv, g->ctx);
  tvec_releaseregs(tv); tv->test = 0; xfree(g->ctx); g->ctx = 0;
}

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

enum { WIN, XFAIL, NOUT };
static const struct tvec_uassoc outcome_assoc[] = {
  { "success",          WIN },
  { "win",              WIN },
  { "expected-failure", XFAIL },
  { "xfail",            XFAIL },
  TVEC_ENDENUM
};
static const struct tvec_urange outcome_range = { 0, NOUT - 1 };
static const struct tvec_uenuminfo outcome_enum =
  { "test-outcome", outcome_assoc, &outcome_range };
static const struct tvec_regdef outcome_regdef =
  { "outcome", 0, &tvty_uenum, 0, { &outcome_enum } };

int tvec_read(struct tvec_state *tv, const char *infile, FILE *fp)
{
  dstr d = DSTR_INIT;
  const struct tvec_test *test;
  const struct tvec_env *env;
  const struct tvec_regdef *rd;
  struct tvec_reg *r;
  struct groupstate g = GROUPSTATE_INIT;
  union tvec_regval rv;
  int ch, ret, rc = 0;

  /* Set the initial location. */
  tv->infile = infile; tv->lno = 1; tv->fp = fp;

  for (;;) {

    /* Get the next character and dispatch.  Note that we're always at the
     * start of a line here.
     */
    ch = getc(tv->fp);
    switch (ch) {

      case EOF:
        /* End of the file.  Exit the loop. */

        goto end;

      case '[':
        /* A test group header. */

        /* End the current group, if there is one. */
        end_test_group(tv, &g);

        /* Read the group name.  There may be leading and trailing
         * whitespace.
         */
        tvec_skipspc(tv);
        DRESET(&d); tvec_readword(tv, &d, "];", "group name");
        tvec_skipspc(tv);
        ch = getc(tv->fp); if (ch != ']') tvec_syntax(tv, ch, "`]'");

        /* Find the matching test definition. */
        for (test = tv->tests; test->name; test++)
          if (STRCMP(d.buf, ==, test->name)) goto found_test;

        /* There wasn't one.  Report the error.  Muffle errors about the
         * contents of this section because they won't be interesting.
         */
        tvec_error(tv, "unknown test group `%s'", d.buf);
        tv->f |= TVSF_MUFFLE; goto flush_line;

      found_test:
        /* Eat trailing whitespace and comments. */
        tvec_flushtoeol(tv, 0);

        /* Set up the new test group. */
        tv->test = test; begin_test_group(tv, &g);
        break;

      case '\n':
        /* A newline, so this was a completely empty line.  Advance the line
         * counter, and run the current test.
         */

        tv->lno++;
        if (tv->f&TVSF_OPEN) check(tv, &g);
        break;

      case ';':
        /* A semicolon.  Skip the comment. */

        tvec_flushtoeol(tv, TVFF_ALLOWANY);
        break;

      default:
        /* Something else. */

        if (isspace(ch)) {
          /* Whitespace.  Skip and see what we find. */

          tvec_skipspc(tv); ch = getc(tv->fp);

          /* If the file ends, then we're done.  If we find a comment then we
           * skip it.  If there's some non-whitespace, then report an error.
           * Otherwise the line was effectively blank, so run the test.
           */
          if (ch == EOF) goto end;
          else if (ch == ';') tvec_flushtoeol(tv, TVFF_ALLOWANY);
          else if (tvec_flushtoeol(tv, 0)) rc = -1;
          else check(tv, &g);
        } else {
          /* Some non-whitespace thing. */

          /* Put the character back and read a word, which ought to be a
           * register name.
           */
          ungetc(ch, tv->fp);
          DRESET(&d);
          if (tvec_readword(tv, &d, "=:;", "register name")) goto flush_line;

          /* Now there should be a separator. */
          tvec_skipspc(tv); ch = getc(tv->fp);
          if (ch != '=' && ch != ':')
            { tvec_syntax(tv, ch, "`=' or `:'"); goto flush_line; }
          tvec_skipspc(tv);

          /* If there's no test, then report an error.  Set the muffle flag,
           * because there's no point in complaining about every assignment
           * in this block.
           */
          if (!tv->test) {
            if (!(tv->f&TVSF_MUFFLE)) tvec_error(tv, "no current test");
            tv->f |= TVSF_MUFFLE; goto flush_line;
          }

          /* Open the test.  This is syntactically a stanza of settings, so
           * it's fair to report on missing register assignments.
           */
          open_test(tv);

          if (d.buf[0] == '@') {
            /* A special register assignment.  */
            env = tv->test->env;

            /* See if it's one of the core settings. */
            if (STRCMP(d.buf, ==, "@outcome")) {

              /* Parse the value. */
              if (tvty_uenum.parse(&rv, &outcome_regdef, tv))
                ret = -1;
              else {

                /* Act on the result. */
                if (rv.u == XFAIL) tvec_xfail(tv);
                ret = 1;
              }
            }

            /* If there's no environment, this is an unknown setting. */
            else if (!env || !env->set) ret = 0;

            /* Otherwise pass the setting on to the environment. */
            else ret = env->set(tv, d.buf, g.ctx);

            /* If it wasn't understood, report an error and flush. */
            if (ret <= 0) {
              if (!ret)
                tvec_error(tv, "unknown special register `%s'", d.buf);
              goto flush_line;
            }
          } else {
            /* A standard register. */

            /* Find the definition. */
            for (rd = tv->test->regs; rd->name; rd++)
              if (STRCMP(rd->name, ==, d.buf)) goto found_reg;
            tvec_error(tv, "unknown register `%s' for test `%s'",
                       d.buf, tv->test->name);
            goto flush_line;

          found_reg:
            /* Complain if the register is already set. */
            r = TVEC_REG(tv, in, rd->i);
            if (r->f&TVRF_LIVE)
              { tvec_dupreg(tv, rd->name); goto flush_line; }

            /* Parse a value and mark the register as live. */
            if (rd->ty->parse(&r->v, rd, tv)) goto flush_line;
            r->f |= TVRF_LIVE;
          }
        }
        break;
    }
    continue;

  flush_line:
    /* This is a general parse-failure handler.  Skip to the next line and
     * remember that things didn't go so well.
     */
    tvec_flushtoeol(tv, TVFF_ALLOWANY); rc = -1;
  }

  /* We reached the end.  If that was actually an I/O error then report it.
   */
  if (ferror(tv->fp))
    { tvec_error(tv, "error reading input: %s", strerror(errno)); rc = -1; }

end:
  /* Process the final test, if there was one, and wrap up the final
   * group.
   */
  end_test_group(tv, &g);

  /* Clean up. */
  tv->infile = 0; tv->fp = 0;
  dstr_destroy(&d);
  return (rc);
}

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

/* --- @tvec_begin@ --- *
 *
 * Arguments:   @struct tvec_state *tv_out@ = state structure to fill in
 *              @const struct tvec_config *config@ = test configuration
 *              @struct tvec_output *o@ = output driver
 *
 * Returns:     ---
 *
 * Use:         Initialize a state structure ready to do some testing.
 */

void tvec_begin(struct tvec_state *tv_out,
                const struct tvec_config *config,
                struct tvec_output *o)
{
  unsigned i;

  tv_out->f = 0;

  assert(config->nrout <= config->nreg);
  tv_out->nrout = config->nrout; tv_out->nreg = config->nreg;
  tv_out->regsz = config->regsz;
  tv_out->in = xmalloc(tv_out->nreg*tv_out->regsz);
  tv_out->out = xmalloc(tv_out->nrout*tv_out->regsz);
  for (i = 0; i < tv_out->nreg; i++) {
    TVEC_REG(tv_out, in, i)->f = 0;
    if (i < tv_out->nrout) TVEC_REG(tv_out, out, i)->f = 0;
  }

  for (i = 0; i < TVOUT_LIMIT; i++)
    tv_out->curr[i] = tv_out->all[i] = tv_out->grps[i] = 0;

  tv_out->tests = config->tests; tv_out->test = 0;
  tv_out->infile = 0; tv_out->lno = 0; tv_out->fp = 0;
  tv_out->output = o; tv_out->output->ops->bsession(tv_out->output, tv_out);
}

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

int tvec_end(struct tvec_state *tv)
{
  int rc = tv->output->ops->esession(tv->output);

  if (tv->test) tvec_releaseregs(tv);
  tv->output->ops->destroy(tv->output);
  xfree(tv->in); xfree(tv->out);
  return (rc);
}

/*----- Serialization and deserialization ---------------------------------*/

/* --- @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 serialized output is written to the buffer @b@.  Failure
 *              can be caused by running out of buffer space, or a failing
 *              type handler.
 */

int tvec_serialize(const struct tvec_reg *rv, buf *b,
                   const struct tvec_regdef *regs,
                   unsigned nr, size_t regsz)
{
  unsigned char *bitmap;
  size_t i, bitoff, nbits, bitsz;
  const struct tvec_regdef *rd;
  const struct tvec_reg *r;

  bitoff = BLEN(b);
  for (rd = regs, nbits = 0; rd->name; rd++, nbits++);
  bitsz = (nbits + 7)/8;

  bitmap = buf_get(b, bitsz); if (!bitmap) return (-1);
  memset(bitmap, 0, bitsz);
  for (rd = regs, i = 0; rd->name; rd++, i++) {
    if (rd->i >= nr) continue;
    r = TVEC_GREG(rv, rd->i, regsz); if (!(r->f&TVRF_LIVE)) continue;
    bitmap = BBASE(b) + bitoff; bitmap[i/8] |= 1 << i%8;
    if (rd->ty->tobuf(b, &r->v, rd)) return (-1);
  }
  return (0);
}

/* --- @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.
 *
 *              Failure results only from a failing register type handler.
 */

int tvec_deserialize(struct tvec_reg *rv, buf *b,
                     const struct tvec_regdef *regs,
                     unsigned nr, size_t regsz)
{
  const unsigned char *bitmap;
  size_t i, nbits, bitsz;
  const struct tvec_regdef *rd;
  struct tvec_reg *r;

  for (rd = regs, nbits = 0; rd->name; rd++, nbits++);
  bitsz = (nbits + 7)/8;

  bitmap = buf_get(b, bitsz); if (!bitmap) return (-1);
  for (rd = regs, i = 0; rd->name; rd++, i++) {
    if (rd->i >= nr) continue;
    if (!(bitmap[i/8]&(1 << i%8))) continue;
    r = TVEC_GREG(rv, rd->i, regsz);
    if (rd->ty->frombuf(b, &r->v, rd)) return (-1);
    r->f |= TVRF_LIVE;
  }
  return (0);
}

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

static const struct tvec_regdef no_regs = { 0, 0, 0, 0, { 0 } };

static void fakefn(const struct tvec_reg *in, struct tvec_reg *out, void *p)
  { assert(!"fake test function"); }

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

void tvec_adhoc(struct tvec_state *tv, struct tvec_test *t)
{
  t->name = "<unset>"; t->regs = &no_regs; t->env = 0; t->fn = fakefn;
  tv->tests = t;
}

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

void tvec_begingroup(struct tvec_state *tv, const char *name,
                     const char *file, unsigned lno)
{
  struct tvec_test *t = (/*unconst*/ struct tvec_test *)tv->tests;

  t->name = name; tv->test = t;
  tv->infile = file; tv->lno = tv->test_lno = lno;
  begin_test_group(tv, 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.
 */

void tvec_endgroup(struct tvec_state *tv)
{
  if (!(tv->f&TVSF_SKIP)) report_group(tv);
  tv->test = 0;
}

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

void tvec_begintest(struct tvec_state *tv, const char *file, unsigned lno)
{
  tv->infile = file; tv->lno = tv->test_lno = lno;
  open_test(tv); begin_test(tv);
}

struct adhoc_claim {
  unsigned f;
#define ACF_FRESH 1u
  const char *saved_file; unsigned saved_lno;
};

static void adhoc_claim_setup(struct tvec_state *tv,
                              struct adhoc_claim *ck,
                              const struct tvec_regdef *regs,
                              const char *file, unsigned lno)
{
  struct tvec_test *t = (/*unconst*/ struct tvec_test *)tv->test;

  ck->f = 0;

  if (!(tv->f&TVSF_OPEN))
    { ck->f |= ACF_FRESH; tvec_begintest(tv, file, lno); }

  ck->saved_file = tv->infile; if (file) tv->infile = file;
  ck->saved_lno = tv->test_lno; if (file) tv->test_lno = lno;
  t->regs = regs ? regs : &no_regs;
}

static void adhoc_claim_teardown(struct tvec_state *tv,
                                 struct adhoc_claim *ck)
{
  struct tvec_test *t = (/*unconst*/ struct tvec_test *)tv->test;

  t->regs = &no_regs;
  tv->infile = ck->saved_file; tv->test_lno = ck->saved_lno;

  if (ck->f&ACF_FRESH) tvec_endtest(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.
 */

int tvec_claim_v(struct tvec_state *tv, int ok,
                 const char *file, unsigned lno,
                 const char *msg, va_list *ap)
{
  struct adhoc_claim ck;

  adhoc_claim_setup(tv, &ck, 0, file, lno);
  if (!ok) tvec_fail_v(tv, msg, ap);
  adhoc_claim_teardown(tv, &ck);
  return (ok);
}

int tvec_claim(struct tvec_state *tv, int ok,
               const char *file, unsigned lno, const char *msg, ...)
{
  va_list ap;

  va_start(ap, msg); tvec_claim_v(tv, ok, file, lno, msg, &ap); va_end(ap);
  return (ok);
}

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)
{
  struct tvec_regdef regs[2];
  struct adhoc_claim ck;
  int ok;

  tv->in[0].f = tv->out[0].f = TVRF_LIVE;

  regs[0].name = "value"; regs[0].i = 0;
  regs[0].ty = ty; regs[0].f = 0;
  if (arg) regs[0].arg = *arg;
  else regs[0].arg.p = 0;

  regs[1].name = 0;

  adhoc_claim_setup(tv, &ck, regs, file, lno);
  ok = ty->eq(&tv->in[0].v, &tv->out[0].v, &regs[0]);
  if (!ok)
    { tvec_fail(tv, "%s", expr); tvec_mismatch(tv, TVMF_IN | TVMF_OUT); }
  adhoc_claim_teardown(tv, &ck);
  return (ok);
}

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