@@@ output doc

[mLib] / test / tvec-output.c

/* -*-c-*-
 *
 * Test vector output management
 *
 * (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 "config.h"

#include <assert.h>
#include <ctype.h>
#include <stdarg.h>
#include <stdio.h>
#include <string.h>

#include <unistd.h>

#include "alloc.h"
#include "bench.h"
#include "dstr.h"
#include "macros.h"
#include "quis.h"
#include "report.h"
#include "tvec.h"

/*----- Common machinery --------------------------------------------------*/

/* --- @regdisp@ --- *
 *
 * Arguments:   @unsigned disp@ = a @TVRD_...@ disposition code
 *
 * Returns:     A human-readable adjective describing the register
 *              disposition.
 */

static const char *regdisp(unsigned disp)
{
  switch (disp) {
    case TVRD_INPUT: return "input";
    case TVRD_OUTPUT: return "output";
    case TVRD_MATCH: return "matched";
    case TVRD_EXPECT: return "expected";
    case TVRD_FOUND: return "found";
    default: abort();
  }
}

/* --- @getenv_boolean@ --- *
 *
 * Arguments:   @const char *var@ = environment variable name
 *              @int dflt@ = default value
 *
 * Returns:     @0@ if the variable is set to something falseish, @1@ if it's
 *              set to something truish, or @dflt@ otherwise.
 */

static int getenv_boolean(const char *var, int dflt)
{
  const char *p;

  p = getenv(var);
  if (!p)
    return (dflt);
  else if (STRCMP(p, ==, "y") || STRCMP(p, ==, "yes") ||
           STRCMP(p, ==, "t") || STRCMP(p, ==, "true") ||
           STRCMP(p, ==, "on") || STRCMP(p, ==, "force") ||
           STRCMP(p, ==, "1"))
    return (1);
  else if (STRCMP(p, ==, "n") || STRCMP(p, ==, "no") ||
           STRCMP(p, ==, "f") || STRCMP(p, ==, "false") ||
           STRCMP(p, ==, "nil") || STRCMP(p, ==, "off") ||
           STRCMP(p, ==, "0"))
    return (0);
  else {
    moan("ignoring unexpected value `%s' for environment variable `%s'",
         var, p);
    return (dflt);
  }
}

/* --- @register_maxnamelen@ --- *
 *
 * Arguments:   @const struct tvec_state *tv@ = test vector state
 *
 * Returns:     The maximum length of a register name in the current test.
 */

static int register_maxnamelen(const struct tvec_state *tv)
{
  const struct tvec_regdef *rd;
  int maxlen = 10, n;

  for (rd = tv->test->regs; rd->name; rd++)
    { n = strlen(rd->name); if (n > maxlen) maxlen = n; }
  return (maxlen);
}

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

/* We have two main jobs in output layout: trimming trailing blanks; and
 * adding a prefix to each line.
 *
 * This is somehow much more complicated than it ought to be.
 */

struct layout {
  FILE *fp;                              /* output file */
  const char *prefix, *pfxtail, *pfxlim; /* prefix pointers */
  dstr w;                               /* trailing whitespace */
  unsigned f;                           /* flags */
#define LYTF_NEWL 1u                    /*   start of output line */
};

/* Support macros.  These assume `lyt' is defined as a pointer to the `struct
 * layout' state.
 */

#define SPLIT_RANGE(tail, base, limit) do {                             \
  /* Set TAIL to point just after the last nonspace character between   \
   * BASE and LIMIT.  If there are no nonspace characters, then set     \
   * TAIL to equal BASE.                                                \
   */                                                                   \
                                                                        \
  for (tail = limit; tail > base && ISSPACE(tail[-1]); tail--);         \
} while (0)

#define PUT_RANGE(base, limit) do {                                     \
  /* Write the range of characters between BASE and LIMIT to the output \
   * file.  Return immediately on error.                                \
   */                                                                   \
                                                                        \
  size_t n = limit - base;                                              \
  if (fwrite(base, 1, n, lyt->fp) < n) return (-1);                     \
} while (0)

#define PUT_CHAR(ch) do {                                               \
  /* Write CH to the output. Return immediately on error. */            \
                                                                        \
  if (putc(ch, lyt->fp) == EOF) return (-1);                            \
} while (0)

#define PUT_PREFIX do {                                                 \
  /* Output the prefix, if there is one.  Return immediately on error. */ \
                                                                        \
  if (lyt->prefix) PUT_RANGE(lyt->prefix, lyt->pfxlim);                 \
} while (0)

#define PUT_SAVED do {                                                  \
  /* Output the saved trailing blank material in the buffer. */         \
                                                                        \
  size_t n = lyt->w.len;                                                \
  if (n && fwrite(lyt->w.buf, 1, n, lyt->fp) < n) return (-1);          \
} while (0)

#define PUT_PFXINB do {                                                 \
  /* Output the initial nonblank portion of the prefix, if there is     \
   * one.  Return immediately on error.                                 \
   */                                                                   \
                                                                        \
  if (lyt->prefix) PUT_RANGE(lyt->prefix, lyt->pfxtail);                \
} while (0)

#define SAVE_PFXTAIL do {                                               \
  /* Save the trailing blank portion of the prefix. */                  \
                                                                        \
  if (lyt->prefix)                                                      \
    DPUTM(&lyt->w, lyt->pfxtail, lyt->pfxlim - lyt->pfxtail);           \
} while (0)

/* --- @init_layout@ --- *
 *
 * Arguments:   @struct layout *lyt@ = layout state to initialize
 *              @FILE *fp@ = output file
 *              @const char *prefix@ = prefix string (or null if empty)
 *
 * Returns:     ---
 *
 * Use:         Initialize a layout state.
 */

static void init_layout(struct layout *lyt, FILE *fp, const char *prefix)
{
  const char *q, *l;

  /* Basics. */
  lyt->fp = fp;
  lyt->f = LYTF_NEWL;
  dstr_create(&lyt->w);

  /* Prefix portions. */
  if (!prefix || !*prefix)
    lyt->prefix = lyt->pfxtail = lyt->pfxlim = 0;
  else {
    lyt->prefix = prefix;
    l = lyt->pfxlim = prefix + strlen(prefix);
    SPLIT_RANGE(q, prefix, l); lyt->pfxtail = q;
  }
}

/* --- @destroy_layout@ --- *
 *
 * Arguments:   @struct layout *lyt@ = layout state
 *              @unsigned f@ = flags (@DLF_...@)
 *
 * Returns:     ---
 *
 * Use:         Releases a layout state and the resources it holds.
 *              Close the file if @DLF_CLOSE@ is set in @f@; otherwise leave
 *              it open (in case it's @stderr@ or something).
 */

#define DLF_CLOSE 1u
static void destroy_layout(struct layout *lyt, unsigned f)
{
  if (f&DLF_CLOSE) fclose(lyt->fp);
  dstr_destroy(&lyt->w);
}

/* --- @layout_char@ --- *
 *
 * Arguments:   @struct layout *lyt@ = layout state
 *              @int ch@ = character to write
 *
 * Returns:     Zero on success, @-1@ on failure.
 *
 * Use:         Write a single character to the output.
 */

static int layout_char(struct layout *lyt, int ch)
{
  if (ch == '\n') {
    if (lyt->f&LYTF_NEWL) PUT_PFXINB;
    PUT_CHAR('\n'); lyt->f |= LYTF_NEWL; DRESET(&lyt->w);
  } else if (isspace(ch))
    DPUTC(&lyt->w, ch);
  else {
    if (lyt->f&LYTF_NEWL) { PUT_PFXINB; lyt->f &= ~LYTF_NEWL; }
    PUT_SAVED; PUT_CHAR(ch); DRESET(&lyt->w);
  }
  return (0);
}

/* --- @layout_string@ --- *
 *
 * Arguments:   @struct layout *lyt@ = layout state
 *              @const char *p@ = string to write
 *              @size_t sz@ = length of string
 *
 * Returns:     Zero on success, @-1@ on failure.
 *
 * Use:         Write a string to the output.
 */

static int layout_string(struct layout *lyt, const char *p, size_t sz)
{
  const char *q, *r, *l = p + sz;

  /* This is rather vexing.  There are a small number of jobs to do, but the
   * logic for deciding which to do when gets rather hairy if, as I've tried
   * here, one aims to minimize the number of decisions being checked, so
   * it's worth canning them into macros.
   *
   * Here, a `blank' is a whitespace character other than newline.  The input
   * buffer consists of one or more `segments', each of which consists of:
   *
   *   * an initial portion, which is either empty or ends with a nonblank
   *     character;
   *
   *   * a suffix which consists only of blanks; and
   *
   *   * an optional newline.
   *
   * All segments except the last end with a newline.
   */

#define SPLIT_SEGMENT do {                                              \
  /* Determine the bounds of the current segment.  If there is a final  \
   * newline, then q is non-null and points to this newline; otherwise, \
   * q is null.  The initial portion of the segment lies between p .. r \
   * and the blank suffix lies between r .. q (or r .. l if q is null). \
   * This sounds awkward, but the suffix is only relevant if there is   \
   * no newline.                                                        \
   */                                                                   \
                                                                        \
  q = memchr(p, '\n', l - p); SPLIT_RANGE(r, p, q ? q : l);             \
} while (0)

#define PUT_NONBLANK do {                                               \
  /* Output the initial portion of the segment. */                      \
                                                                        \
  PUT_RANGE(p, r);                                                      \
} while (0)

#define PUT_NEWLINE do {                                                \
  /* Write a newline, and advance to the next segment. */               \
                                                                        \
  PUT_CHAR('\n'); p = q + 1;                                            \
} while (0)

#define SAVE_TAIL do {                                                  \
  /* Save the trailing blank portion of the segment in the buffer.      \
   * Assumes that there is no newline, since otherwise the suffix would \
   * be omitted.                                                        \
   */                                                                   \
                                                                        \
  DPUTM(&lyt->w, r, l - r);                                             \
} while (0)

  /* Determine the bounds of the first segment.  Handling this is the most
   * complicated part of this function.
   */
  SPLIT_SEGMENT;

  if (!q) {
    /* This is the only segment.  We'll handle the whole thing here.
     *
     * If there's an initial nonblank portion, then we need to write that
     * out.  Furthermore, if we're at the start of the line then we'll need
     * to write the prefix, and if there's saved blank material then we'll
     * need to write that.  Otherwise, there's only blank stuff, which we
     * accumulate in the buffer.
     *
     * If we're at the start of a line here, then put the prefix followed by
     * any saved whitespace, and then our initial nonblank portion.  Then
     * save our new trailing space.
     */

    if (r > p) {
      if (lyt->f&LYTF_NEWL) { PUT_PREFIX; lyt->f &= ~LYTF_NEWL; }
      PUT_SAVED; PUT_NONBLANK; DRESET(&lyt->w);
    }
    SAVE_TAIL;
    return (0);
  }

  /* There is at least one more segment, so we know that there'll be a line
   * to output.
   */
  if (r > p) {
    if (lyt->f&LYTF_NEWL) PUT_PREFIX;
    PUT_SAVED; PUT_NONBLANK;
  } else if (lyt->f&LYTF_NEWL)
    PUT_PFXINB;
  PUT_NEWLINE; DRESET(&lyt->w);
  SPLIT_SEGMENT;

  /* Main loop over whole segments with trailing newlines.  For each one, we
   * know that we're starting at the beginning of a line and there's a final
   * newline, so we write the initial prefix and drop the trailing blanks.
   */
  while (q) {
    if (r > p) { PUT_PREFIX; PUT_NONBLANK; }
    else PUT_PFXINB;
    PUT_NEWLINE;
    SPLIT_SEGMENT;
  }

  /* At the end, there's no final newline.  If there's nonblank material,
   * then we can write the prefix and the nonblank stuff.  Otherwise, stash
   * the blank stuff (including the trailing blanks of the prefix) and leave
   * the newline flag set.
   */
  if (r > p) { PUT_PREFIX; PUT_NONBLANK; lyt->f &= ~LYTF_NEWL; }
  else { lyt->f |= LYTF_NEWL; SAVE_PFXTAIL; }
  SAVE_TAIL;

#undef SPLIT_SEGMENT
#undef PUT_NONBLANK
#undef PUT_NEWLINE
#undef SAVE_TAIL

  return (0);
}

#undef SPLIT_RANGE
#undef PUT_RANGE
#undef PUT_PREFIX
#undef PUT_PFXINB
#undef PUT_SAVED
#undef PUT_CHAR
#undef SAVE_PFXTAIL

/*----- Skeleton ----------------------------------------------------------*/
/*
static void ..._bsession(struct tvec_output *o, struct tvec_state *tv)
static int ..._esession(struct tvec_output *o)
static void ..._bgroup(struct tvec_output *o)
static void ..._skipgroup(struct tvec_output *o,
                          const char *excuse, va_list *ap)
static void ..._egroup(struct tvec_output *o)
static void ..._btest(struct tvec_output *o)
static void ..._skip(struct tvec_output *o, const char *excuse, va_list *ap)
static void ..._fail(struct tvec_output *o, const char *detail, va_list *ap)
static void ..._dumpreg(struct tvec_output *o, unsigned disp,
                        union tvec_regval *rv, const struct tvec_regdef *rd)
static void ..._etest(struct tvec_output *o, unsigned outcome)
static void ..._bbench(struct tvec_output *o,
                       const char *ident, unsigned unit)
static void ..._ebench(struct tvec_output *o,
                       const char *ident, unsigned unit,
                       const struct tvec_timing *t)
static void ..._error(struct tvec_output *o, const char *msg, va_list *ap)
static void ..._notice(struct tvec_output *o, const char *msg, va_list *ap)
static void ..._destroy(struct tvec_output *o)

static const struct tvec_outops ..._ops = {
  ..._bsession, ..._esession,
  ..._bgroup, ..._egroup, ..._skip,
  ..._btest, ..._skip, ..._fail, ..._dumpreg, ..._etest,
  ..._bbench, ..._ebench,
  ..._error, ..._notice,
  ..._destroy
};
*/
/*----- Human-readable output ---------------------------------------------*/

/* Attributes for colour output.  This should be done better, but @terminfo@
 * is a disaster.
 *
 * An attribute byte holds a foreground colour in the low nibble, a
 * background colour in the next nibble, and some flags in the next few
 * bits.  A colour is expressed in classic 1-bit-per-channel style, with red,
 * green, and blue in bits 0, 1, and 2, and a `bright' flag in bit 3.
 */
#define HAF_FGMASK 0x0f                 /* foreground colour mask */
#define HAF_FGSHIFT 0                   /* foreground colour shift */
#define HAF_BGMASK 0xf0                 /* background colour mask */
#define HAF_BGSHIFT 4                   /* background colour shift */
#define HAF_FG 256u                     /* set foreground? */
#define HAF_BG 512u                     /* set background? */
#define HAF_BOLD 1024u                  /* set bold? */
#define HCOL_BLACK 0u                   /* colour codes... */
#define HCOL_RED 1u
#define HCOL_GREEN 2u
#define HCOL_YELLOW 3u
#define HCOL_BLUE 4u
#define HCOL_MAGENTA 5u
#define HCOL_CYAN 6u
#define HCOL_WHITE 7u
#define HCF_BRIGHT 8u                   /* bright colour flag */
#define HFG(col) (HAF_FG | (HCOL_##col) << HAF_FGSHIFT) /* set foreground */
#define HBG(col) (HAF_BG | (HCOL_##col) << HAF_BGSHIFT) /* set background */

/* Predefined attributes. */
#define HA_PLAIN 0                   /* nothing special: terminal defaults */
#define HA_LOC (HFG(CYAN))              /* filename or line number */
#define HA_LOCSEP (HFG(BLUE))           /* location separator `:' */
#define HA_UNSET (HFG(YELLOW))          /* register not set */
#define HA_FOUND (HFG(RED))             /* incorrect output value */
#define HA_EXPECT (HFG(GREEN))          /* what the value should have been */
#define HA_WIN (HFG(GREEN))             /* reporting success */
#define HA_LOSE (HFG(RED) | HAF_BOLD)   /* reporting failure */
#define HA_XFAIL (HFG(BLUE) | HAF_BOLD) /* reporting expected failure */
#define HA_SKIP (HFG(YELLOW))           /* reporting a skipped test/group */
#define HA_ERR (HFG(MAGENTA) | HAF_BOLD) /* reporting an error */

/* Scoreboard indicators. */
#define HSB_WIN '.'                     /* test passed */
#define HSB_LOSE 'x'                    /* test failed */
#define HSB_XFAIL 'o'                   /* test failed expectedly */
#define HSB_SKIP '_'                    /* test wasn't run */

struct human_output {
  struct tvec_output _o;                /* output base class */
  struct tvec_state *tv;                /* stashed testing state */
  struct layout lyt;                    /* output layout */
  char *outbuf; size_t outsz;           /* buffer for formatted output */
  dstr scoreboard;                      /* history of test group results */
  unsigned attr;                        /* current terminal attributes */
  int maxlen;                           /* longest register name */
  unsigned f;                           /* flags */
#define HOF_TTY 1u                      /*   writing to terminal */
#define HOF_DUPERR 2u                   /*   duplicate errors to stderr */
#define HOF_COLOUR 4u                   /*   print in angry fruit salad */
#define HOF_PROGRESS 8u                 /*   progress display is active */
};

/* --- @set_colour@ --- *
 *
 * Arguments:   @FILE *fp@ = output stream to write on
 *              @int *sep_inout@ = where to maintain separator
 *              @const char *norm@ = prefix for normal colour
 *              @const char *bright@ = prefix for bright colour
 *              @unsigned colour@ = four bit colour code
 *
 * Returns:     ---
 *
 * Use:         Write to the output stream @fp@, the current character at
 *              @*sep_inout@, if that's not zero, followed by either @norm@
 *              or @bright@, according to whether the @HCF_BRIGHT@ flag is
 *              set in @colour@, followed by the plain colour code from
 *              @colour@; finally, update @*sep_inout@ to be a `%|;|%'.
 *
 *              This is an internal subroutine for @setattr@ below.
 */

static void set_colour(FILE *fp, int *sep_inout,
                       const char *norm, const char *bright,
                       unsigned colour)
{
  if (*sep_inout) putc(*sep_inout, fp);
  fprintf(fp, "%s%d", colour&HCF_BRIGHT ? bright : norm, colour&7);
  *sep_inout = ';';
}

/* --- @setattr@ --- *
 *
 * Arguments:   @struct human_output *h@ = output state
 *              @unsigned attr@ = attribute code to set
 *
 * Returns:     ---
 *
 * Use:         Send a control sequence to the output stream so that
 *              subsequent text is printed with the given attributes.
 *
 *              Some effort is taken to avoid unnecessary control sequences.
 *              In particular, if @attr@ matches the current terminal
 *              settings already, then nothing is written.
 */

static void setattr(struct human_output *h, unsigned attr)
{
  unsigned diff = h->attr ^ attr;
  int sep = 0;

  /* If there's nothing to do, we might as well stop now. */
  if (!diff || !(h->f&HOF_COLOUR)) return;

  /* Start on the control command. */
  fputs("\x1b[", h->lyt.fp);

  /* Change the boldness if necessary. */
  if (diff&HAF_BOLD) {
    if (attr&HAF_BOLD) putc('1', h->lyt.fp);
    else { putc('0', h->lyt.fp); diff = h->attr; }
    sep = ';';
  }

  /* Change the foreground colour if necessary. */
  if (diff&(HAF_FG | HAF_FGMASK)) {
    if (attr&HAF_FG)
      set_colour(h->lyt.fp, &sep, "3", "9",
                 (attr&HAF_FGMASK) >> HAF_FGSHIFT);
    else {
      if (sep) putc(sep, h->lyt.fp);
      fputs("39", h->lyt.fp); sep = ';';
    }
  }

  /* Change the background colour if necessary. */
  if (diff&(HAF_BG | HAF_BGMASK)) {
    if (attr&HAF_BG)
      set_colour(h->lyt.fp, &sep, "4", "10",
                 (attr&HAF_BGMASK) >> HAF_BGSHIFT);
    else {
      if (sep) putc(sep, h->lyt.fp);
      fputs("49", h->lyt.fp); sep = ';';
    }
  }

  /* Terminate the control command and save the new attributes. */
  putc('m', h->lyt.fp); h->attr = attr;
}

/* --- @clear_progress@ --- *
 *
 * Arguments:   @struct human_output *h@ = output state
 *
 * Returns:     ---
 *
 * Use:         Remove the progress display from the terminal.
 *
 *              If the progress display isn't active then do nothing.
 */

static void clear_progress(struct human_output *h)
{
  size_t i, n;

  if (h->f&HOF_PROGRESS) {
    n = strlen(h->tv->test->name) + 2 + h->scoreboard.len;
    for (i = 0; i < n; i++) fputs("\b \b", h->lyt.fp);
    h->f &= ~HOF_PROGRESS;
  }
}

/* --- @write_scoreboard_char@ --- *
 *
 * Arguments:   @struct human_output *h@ = output state
 *              @int ch@ = scoreboard character to print
 *
 * Returns:     ---
 *
 * Use:         Write a scoreboard character, indicating the outcome of a
 *              test, to the output stream, with appropriate highlighting.
 */

static void write_scoreboard_char(struct human_output *h, int ch)
{
  switch (ch) {
    case HSB_LOSE: setattr(h, HA_LOSE); break;
    case HSB_SKIP: setattr(h, HA_SKIP); break;
    case HSB_XFAIL: setattr(h, HA_XFAIL); break;
    default: setattr(h, HA_PLAIN); break;
  }
  putc(ch, h->lyt.fp); setattr(h, HA_PLAIN);
}

/* --- @show_progress@ --- *
 *
 * Arguments:   @struct human_output *h@ = output state
 *
 * Returns:     ---
 *
 * Use:         Show the progress display, with the record of outcomes for
 *              the current test group.
 *
 *              If the progress display is already active, or the output
 *              stream is not interactive, then nothing happens.
 */

static void show_progress(struct human_output *h)
{
  struct tvec_state *tv = h->tv;
  const char *p, *l;

  if (tv->test && (h->f&HOF_TTY) && !(h->f&HOF_PROGRESS)) {
    fprintf(h->lyt.fp, "%s: ", tv->test->name);
    if (!(h->f&HOF_COLOUR))
      dstr_write(&h->scoreboard, h->lyt.fp);
    else for (p = h->scoreboard.buf, l = p + h->scoreboard.len; p < l; p++)
      write_scoreboard_char(h, *p);
    fflush(h->lyt.fp); h->f |= HOF_PROGRESS;
  }
}

/* --- @report_location@ --- *
 *
 * Arguments:   @struct human_output *h@ = output state
 *              @FILE *fp@ = stream to write the location on
 *              @const char *file@ = filename
 *              @unsigned lno@ = line number
 *
 * Returns:     ---
 *
 * Use:         Print the filename and line number to the output stream @fp@.
 *              Also, if appropriate, print interleaved highlighting control
 *              codes to our usual output stream.  If @file@ is null then do
 *              nothing.
 */

static void report_location(struct human_output *h, FILE *fp,
                            const char *file, unsigned lno)
{
  unsigned f = 0;
#define f_flush 1u

  /* We emit highlighting if @fp@ is our usual output stream, or the
   * duplicate-errors flag is clear indicating that (we assume) they're
   * secretly going to the same place anyway.  If they're different streams,
   * though, we have to be careful to keep the highlighting and the actual
   * text synchronized.
   */

  if (!file)
    /* nothing to do */;
  else if (fp != h->lyt.fp && (h->f&HOF_DUPERR))
    fprintf(fp, "%s:%u: ", file, lno);
  else {
    if (fp != h->lyt.fp) f |= f_flush;

#define FLUSH(fp) do if (f&f_flush) fflush(fp); while (0)

    setattr(h, HA_LOC);         FLUSH(h->lyt.fp);
    fputs(file, fp);            FLUSH(fp);
    setattr(h, HA_LOCSEP);      FLUSH(h->lyt.fp);
    fputc(':', fp);             FLUSH(fp);
    setattr(h, HA_LOC);         FLUSH(h->lyt.fp);
    fprintf(fp, "%u", lno);     FLUSH(fp);
    setattr(h, HA_LOCSEP);      FLUSH(h->lyt.fp);
    fputc(':', fp);             FLUSH(fp);
    setattr(h, HA_PLAIN);       FLUSH(h->lyt.fp);
    fputc(' ', fp);

#undef FLUSH
  }

#undef f_flush
}

/* --- @human_writech@, @human_write@, @human_writef@ --- *
 *
 * Arguments:   @void *go@ = output sink, secretly a @struct human_output@
 *              @int ch@ = character to write
 *              @const char *@p@, @size_t sz@ = string (with explicit length)
 *                      to write
 *              @const char *p, ...@ = format control string and arguments to
 *                      write
 *
 * Returns:     ---
 *
 * Use:         Write characters, strings, or formatted strings to the
 *              output, applying appropriate layout.
 *
 *              For the human output driver, the layout machinery just strips
 *              trailing spaces.
 */

static int human_writech(void *go, int ch)
  { struct human_output *h = go; return (layout_char(&h->lyt, ch)); }

static int human_writem(void *go, const char *p, size_t sz)
  { struct human_output *h = go; return (layout_string(&h->lyt, p, sz)); }

static int human_nwritef(void *go, size_t maxsz, const char *p, ...)
{
  struct human_output *h = go;
  size_t n;
  va_list ap;

  va_start(ap, p);
  n = gprintf_memputf(&h->outbuf, &h->outsz, maxsz, p, ap);
  va_end(ap);
  return (layout_string(&h->lyt, h->outbuf, n));
}

static const struct gprintf_ops human_printops =
  { human_writech, human_writem, human_nwritef };

/* --- @human_bsession@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *              @struct tvec_state *tv@ = the test state producing output
 *
 * Returns:     ---
 *
 * Use:         Begin a test session.
 *
 *              The human driver just records the test state for later
 *              reference.
 */

static void human_bsession(struct tvec_output *o, struct tvec_state *tv)
  { struct human_output *h = (struct human_output *)o; h->tv = tv; }

/* --- @report_unusual@ --- *
 *
 * Arguments:   @struct human_output *h@ = output sink
 *              @unsigned nxfail, nskip@ = number of expected failures and
 *                      skipped tests
 *
 * Returns:     ---
 *
 * Use:         Write (directly on the output stream) a note about expected
 *              failures and/or skipped tests, if there were any.
 */

static void report_unusual(struct human_output *h,
                           unsigned nxfail, unsigned nskip)
{
  const char *sep = " (";
  unsigned f = 0;
#define f_any 1u

  if (nxfail) {
    fprintf(h->lyt.fp, "%s%u ", sep, nxfail);
    setattr(h, HA_XFAIL);
    fprintf(h->lyt.fp, "expected %s", nxfail == 1 ? "failure" : "failures");
    setattr(h, HA_PLAIN);
    sep = ", "; f |= f_any;
  }

  if (nskip) {
    fprintf(h->lyt.fp, "%s%u ", sep, nskip);
    setattr(h, HA_SKIP); fputs("skipped", h->lyt.fp); setattr(h, HA_PLAIN);
    sep = ", "; f |= f_any;
  }

  if (f&f_any) fputc(')', h->lyt.fp);

#undef f_any
}

/* --- @human_esession@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *
 * Returns:     Suggested exit status.
 *
 * Use:         End a test session.
 *
 *              The human driver prints a final summary of the rest results
 *              and returns a suitable exit code.
 */

static int human_esession(struct tvec_output *o)
{
  struct human_output *h = (struct human_output *)o;
  struct tvec_state *tv = h->tv;
  unsigned
    all_win = tv->all[TVOUT_WIN], grps_win = tv->grps[TVOUT_WIN],
    all_xfail = tv->all[TVOUT_XFAIL],
    all_lose = tv->all[TVOUT_LOSE], grps_lose = tv->grps[TVOUT_LOSE],
    all_skip = tv->all[TVOUT_SKIP], grps_skip = tv->grps[TVOUT_SKIP],
    all_pass = all_win + all_xfail, all_run = all_pass + all_lose,
    grps_run = grps_win + grps_lose;

  if (!all_lose) {
    setattr(h, HA_WIN); fputs("PASSED", h->lyt.fp); setattr(h, HA_PLAIN);
    fprintf(h->lyt.fp, " %s%u %s",
            !(all_skip || grps_skip) ? "all " : "",
            all_pass, all_pass == 1 ? "test" : "tests");
    report_unusual(h, all_xfail, all_skip);
    fprintf(h->lyt.fp, " in %u %s",
            grps_win, grps_win == 1 ? "group" : "groups");
    report_unusual(h, 0, grps_skip);
  } else {
    setattr(h, HA_LOSE); fputs("FAILED", h->lyt.fp); setattr(h, HA_PLAIN);
    fprintf(h->lyt.fp, " %u out of %u %s",
            all_lose, all_run, all_run == 1 ? "test" : "tests");
    report_unusual(h, all_xfail, all_skip);
    fprintf(h->lyt.fp, " in %u out of %u %s",
            grps_lose, grps_run, grps_run == 1 ? "group" : "groups");
    report_unusual(h, 0, grps_skip);
  }
  fputc('\n', h->lyt.fp);

  if (tv->f&TVSF_ERROR) {
    setattr(h, HA_ERR); fputs("ERRORS", h->lyt.fp); setattr(h, HA_PLAIN);
    fputs(" found in input; tests may not have run correctly\n", h->lyt.fp);
  }

  h->tv = 0; return (tv->f&TVSF_ERROR ? 2 : all_lose ? 1 : 0);
}

/* --- @human_bgroup@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *
 * Returns:     ---
 *
 * Use:         Begin a test group.
 *
 *              The human driver determines the length of the longest
 *              register name, resets the group progress scoreboard, and
 *              activates the progress display.
 */

static void human_bgroup(struct tvec_output *o)
{
  struct human_output *h = (struct human_output *)o;

  h->maxlen = register_maxnamelen(h->tv);
  dstr_reset(&h->scoreboard); show_progress(h);
}

/* --- @human_skipgroup@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *              @const char *excuse@, @va_list *ap@ = reason for skipping the
 *                      group, or null
 *
 * Returns:     ---
 *
 * Use:         Report that a test group is being skipped.
 *
 *              The human driver just reports the situation to its output
 *              stream.
 */

static void human_skipgroup(struct tvec_output *o,
                            const char *excuse, va_list *ap)
{
  struct human_output *h = (struct human_output *)o;

  if (!(h->f&HOF_TTY))
    fprintf(h->lyt.fp, "%s ", h->tv->test->name);
  else {
    show_progress(h); h->f &= ~HOF_PROGRESS;
    if (h->scoreboard.len) putc(' ', h->lyt.fp);
  }
  setattr(h, HA_SKIP); fputs("skipped", h->lyt.fp); setattr(h, HA_PLAIN);
  if (excuse) { fputs(": ", h->lyt.fp); vfprintf(h->lyt.fp, excuse, *ap); }
  fputc('\n', h->lyt.fp);
}

/* --- @human_egroup@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *
 * Returns:     ---
 *
 * Use:         Report that a test group has finished.
 *
 *              The human driver reports a summary of the group's tests.
 */

static void human_egroup(struct tvec_output *o)
{
  struct human_output *h = (struct human_output *)o;
  struct tvec_state *tv = h->tv;
  unsigned win = tv->curr[TVOUT_WIN], xfail = tv->curr[TVOUT_XFAIL],
    lose = tv->curr[TVOUT_LOSE], skip = tv->curr[TVOUT_SKIP],
    run = win + lose + xfail;

  if (h->f&HOF_TTY) h->f &= ~HOF_PROGRESS;
  else fprintf(h->lyt.fp, "%s:", h->tv->test->name);

  if (lose) {
    fprintf(h->lyt.fp, " %u/%u ", lose, run);
    setattr(h, HA_LOSE); fputs("FAILED", h->lyt.fp); setattr(h, HA_PLAIN);
    report_unusual(h, xfail, skip);
  } else {
    fputc(' ', h->lyt.fp); setattr(h, HA_WIN);
    fputs("ok", h->lyt.fp); setattr(h, HA_PLAIN);
    report_unusual(h, xfail, skip);
  }
  fputc('\n', h->lyt.fp);
}

/* --- @human_btest@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *
 * Returns:     ---
 *
 * Use:         Report that a test is starting.
 *
 *              The human driver makes sure the progress display is active.
 */

static void human_btest(struct tvec_output *o)
  { struct human_output *h = (struct human_output *)o; show_progress(h); }

/* --- @human_outcome@, @human_skip@, @human_fail@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *              @unsigned attr@ = attribute to apply to the outcome
 *              @const char *outcome@ = outcome string to report
 *              @const char *detail@, @va_list *ap@ = a detail message
 *              @const char *excuse@, @va_list *ap@ = reason for skipping the
 *                      test
 *
 * Returns:     ---
 *
 * Use:         Report that a test has been skipped or failed.
 *
 *              The human driver reports the situation on its output stream.
 */

static void human_outcome(struct tvec_output *o,
                          unsigned attr, const char *outcome,
                          const char *detail, va_list *ap)
{
  struct human_output *h = (struct human_output *)o;
  struct tvec_state *tv = h->tv;

  clear_progress(h);
  report_location(h, h->lyt.fp, tv->infile, tv->test_lno);
  fprintf(h->lyt.fp, "`%s' ", tv->test->name);
  setattr(h, attr); fputs(outcome, h->lyt.fp); setattr(h, HA_PLAIN);
  if (detail) { fputs(": ", h->lyt.fp); vfprintf(h->lyt.fp, detail, *ap); }
  fputc('\n', h->lyt.fp);
}

static void human_skip(struct tvec_output *o,
                       const char *excuse, va_list *ap)
  { human_outcome(o, HA_SKIP, "skipped", excuse, ap); }
static void human_fail(struct tvec_output *o,
                       const char *detail, va_list *ap)
  { human_outcome(o, HA_LOSE, "FAILED", detail, ap); }

/* --- @human_dumpreg@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *              @unsigned disp@ = register disposition
 *              @const union tvec_regval *rv@ = register value
 *              @const struct tvec_regdef *rd@ = register definition
 *
 * Returns:     ---
 *
 * Use:         Dump a register.
 *
 *              The human driver applies highlighting to mismatching output
 *              registers, but otherwise delegates to the register type
 *              handler and the layout machinery.
 */

static void human_dumpreg(struct tvec_output *o,
                          unsigned disp, const union tvec_regval *rv,
                          const struct tvec_regdef *rd)
{
  struct human_output *h = (struct human_output *)o;
  const char *ds = regdisp(disp); int n = strlen(ds) + strlen(rd->name);

  clear_progress(h);
  gprintf(&human_printops, h, "%*s%s %s = ",
          10 + h->maxlen - n, "", ds, rd->name);
  if (h->f&HOF_COLOUR) {
    if (!rv) setattr(h, HA_UNSET);
    else if (disp == TVRD_FOUND) setattr(h, HA_FOUND);
    else if (disp == TVRD_EXPECT) setattr(h, HA_EXPECT);
  }
  if (!rv) gprintf(&human_printops, h, "#unset");
  else rd->ty->dump(rv, rd, 0, &human_printops, h);
  setattr(h, HA_PLAIN); layout_char(&h->lyt, '\n');
}

/* --- @human_etest@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *              @unsigned outcome@ = the test outcome
 *
 * Returns:     ---
 *
 * Use:         Report that a test has finished.
 *
 *              The human driver reactivates the progress display, if
 *              necessary, and adds a new character for the completed test.
 */

static void human_etest(struct tvec_output *o, unsigned outcome)
{
  struct human_output *h = (struct human_output *)o;
  int ch;

  if (h->f&HOF_TTY) {
    show_progress(h);
    switch (outcome) {
      case TVOUT_WIN: ch = HSB_WIN; break;
      case TVOUT_LOSE: ch = HSB_LOSE; break;
      case TVOUT_XFAIL: ch = HSB_XFAIL; break;
      case TVOUT_SKIP: ch = HSB_SKIP; break;
      default: abort();
    }
    dstr_putc(&h->scoreboard, ch);
    write_scoreboard_char(h, ch); fflush(h->lyt.fp);
  }
}

/* --- @human_bbench@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *              @const char *ident@ = identifying register values
 *              @unsigned unit@ = measurement unit (@TVBU_...@)
 *
 * Returns:     ---
 *
 * Use:         Report that a benchmark has started.
 *
 *              The human driver just prints the start of the benchmark
 *              report.
 */

static void human_bbench(struct tvec_output *o,
                         const char *ident, unsigned unit)
{
  struct human_output *h = (struct human_output *)o;
  struct tvec_state *tv = h->tv;

  clear_progress(h);
  fprintf(h->lyt.fp, "%s: %s: ", tv->test->name, ident); fflush(h->lyt.fp);
}

/* --- @human_ebench@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *              @const char *ident@ = identifying register values
 *              @unsigned unit@ = measurement unit (@TVBU_...@)
 *              @const struct bench_timing *tm@ = measurement
 *
 * Returns:     ---
 *
 * Use:         Report a benchmark's results
 *
 *              The human driver just delegates to the default benchmark
 *              reporting, via the layout machinery.
 */

static void human_ebench(struct tvec_output *o,
                         const char *ident, unsigned unit,
                         const struct bench_timing *tm)
{
  struct human_output *h = (struct human_output *)o;

  tvec_benchreport(&human_printops, h->lyt.fp, unit, tm);
  fputc('\n', h->lyt.fp);
}

/* --- @human_report@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *              @unsigned level@ = message level (@TVLEV_...@)
 *              @const char *msg@, @va_list *ap@ = format string and
 *                      arguments
 *
 * Returns:     ---
 *
 * Use:         Report a message to the user.
 *
 *              The human driver arranges to show the message on @stderr@ as
 *              well as the usual output, with a certain amount of
 *              intelligence in case they're both actually the same device.
 */

static void human_report(struct tvec_output *o, unsigned level,
                         const char *msg, va_list *ap)
{
  struct human_output *h = (struct human_output *)o;
  struct tvec_state *tv = h->tv;
  dstr d = DSTR_INIT;

  dstr_vputf(&d, msg, ap); dstr_putc(&d, '\n');

  clear_progress(h); fflush(h->lyt.fp);
  fprintf(stderr, "%s: ", QUIS);
  report_location(h, stderr, tv->infile, tv->lno);
  fwrite(d.buf, 1, d.len, stderr);

  if (h->f&HOF_DUPERR) {
    report_location(h, h->lyt.fp, tv->infile, tv->lno);
    fwrite(d.buf, 1, d.len, h->lyt.fp);
  }
  show_progress(h);
}

/* --- @human_destroy@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      human_output@
 *
 * Returns:     ---
 *
 * Use:         Release the resources held by the output driver.
 */

static void human_destroy(struct tvec_output *o)
{
  struct human_output *h = (struct human_output *)o;

  destroy_layout(&h->lyt,
                 h->lyt.fp == stdout || h->lyt.fp == stderr ? 0 : DLF_CLOSE);
  dstr_destroy(&h->scoreboard);
  xfree(h->outbuf); xfree(h);
}

static const struct tvec_outops human_ops = {
  human_bsession, human_esession,
  human_bgroup, human_skipgroup, human_egroup,
  human_btest, human_skip, human_fail, human_dumpreg, human_etest,
  human_bbench, human_ebench,
  human_report,
  human_destroy
};

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

struct tvec_output *tvec_humanoutput(FILE *fp)
{
  struct human_output *h;
  const char *p;

  h = xmalloc(sizeof(*h)); h->_o.ops = &human_ops;
  h->f = 0; h->attr = 0;

  init_layout(&h->lyt, fp, 0);
  h->outbuf = 0; h->outsz = 0;

  switch (getenv_boolean("TVEC_TTY", -1)) {
    case 1: h->f |= HOF_TTY; break;
    case 0: break;
    default:
      if (isatty(fileno(fp))) h->f |= HOF_TTY;
      break;
  }
  switch (getenv_boolean("TVEC_COLOUR", -1)) {
    case 1: h->f |= HOF_COLOUR; break;
    case 0: break;
    default:
      if (h->f&HOF_TTY) {
        p = getenv("TERM");
        if (p && STRCMP(p, !=, "dumb")) h->f |= HOF_COLOUR;
      }
      break;
  }

  if (fp != stderr && (fp != stdout || !(h->f&HOF_TTY))) h->f |= HOF_DUPERR;
  dstr_create(&h->scoreboard);
  return (&h->_o);
}

/*----- Perl's `Test Anything Protocol' -----------------------------------*/

struct tap_output {
  struct tvec_output _o;                /* output base class */
  struct tvec_state *tv;                /* stashed testing state */
  struct layout lyt;                    /* output layout */
  char *outbuf; size_t outsz;           /* buffer for formatted output */
  unsigned grpix, testix;               /* group and test indices */
  unsigned previx;                      /* previously reported test index */
  int maxlen;                           /* longest register name */
};

/* --- @tap_writech@, @tap_write@, @tap_writef@ --- *
 *
 * Arguments:   @void *go@ = output sink, secretly a @struct tap_output@
 *              @int ch@ = character to write
 *              @const char *@p@, @size_t sz@ = string (with explicit length)
 *                      to write
 *              @const char *p, ...@ = format control string and arguments to
 *                      write
 *
 * Returns:     ---
 *
 * Use:         Write characters, strings, or formatted strings to the
 *              output, applying appropriate layout.
 *
 *              For the TAP output driver, the layout machinery prefixes each
 *              line with `    ## ' and strips trailing spaces.
 */

static int tap_writech(void *go, int ch)
  { struct tap_output *t = go; return (layout_char(&t->lyt, ch)); }

static int tap_writem(void *go, const char *p, size_t sz)
  { struct tap_output *t = go; return (layout_string(&t->lyt, p, sz)); }

static int tap_nwritef(void *go, size_t maxsz, const char *p, ...)
{
  struct tap_output *t = go;
  size_t n;
  va_list ap;

  va_start(ap, p);
  n = gprintf_memputf(&t->outbuf, &t->outsz, maxsz, p, ap);
  va_end(ap);
  return (layout_string(&t->lyt, t->outbuf, n));
}

static const struct gprintf_ops tap_printops =
  { tap_writech, tap_writem, tap_nwritef };

/* --- @tap_bsession@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *              @struct tvec_state *tv@ = the test state producing output
 *
 * Returns:     ---
 *
 * Use:         Begin a test session.
 *
 *              The TAP driver records the test state for later reference,
 *              initializes the group index counter, and prints the version
 *              number.
 */

static void tap_bsession(struct tvec_output *o, struct tvec_state *tv)
{
  struct tap_output *t = (struct tap_output *)o;

  t->tv = tv; t->grpix = 0;
  fputs("TAP version 13\n", t->lyt.fp); /* but secretly 14 really */
}

/* --- @tap_esession@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *
 * Returns:     Suggested exit status.
 *
 * Use:         End a test session.
 *
 *              The TAP driver prints a final summary of the rest results
 *              and returns a suitable exit code.
 */

static int tap_esession(struct tvec_output *o)
{
  struct tap_output *t = (struct tap_output *)o;
  struct tvec_state *tv = t->tv;

  if (tv->f&TVSF_ERROR) {
    fputs("Bail out!  "
          "Errors found in input; tests may not have run correctly\n",
          t->lyt.fp);
    return (2);
  }

  fprintf(t->lyt.fp, "1..%u\n", t->grpix);
  t->tv = 0; return (tv->all[TVOUT_LOSE] ? 1 : 0);
}

/* --- @tap_bgroup@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *
 * Returns:     ---
 *
 * Use:         Begin a test group.
 *
 *              The TAP driver determines the length of the longest
 *              register name, resets the group progress scoreboard, and
 *              activates the progress display.
 */

static void tap_bgroup(struct tvec_output *o)
{
  struct tap_output *t = (struct tap_output *)o;
  struct tvec_state *tv = t->tv;

  t->grpix++; t->testix = t->previx = 0;
  t->maxlen = register_maxnamelen(t->tv);
  fprintf(t->lyt.fp, "# Subtest: %s\n", tv->test->name);
}

/* --- @tap_skipgroup@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *              @const char *excuse@, @va_list *ap@ = reason for skipping the
 *                      group, or null
 *
 * Returns:     ---
 *
 * Use:         Report that a test group is being skipped.
 *
 *              The TAP driver just reports the situation to its output
 *              stream.
 */

static void tap_skipgroup(struct tvec_output *o,
                          const char *excuse, va_list *ap)
{
  struct tap_output *t = (struct tap_output *)o;

  fprintf(t->lyt.fp, "    1..%u\n", t->testix);
  fprintf(t->lyt.fp, "ok %u %s # SKIP", t->grpix, t->tv->test->name);
  if (excuse) { fputc(' ', t->lyt.fp); vfprintf(t->lyt.fp, excuse, *ap); }
  fputc('\n', t->lyt.fp);
}

/* --- @tap_egroup@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *
 * Returns:     ---
 *
 * Use:         Report that a test group has finished.
 *
 *              The TAP driver reports a summary of the group's tests.
 */

static void tap_egroup(struct tvec_output *o)
{
  struct tap_output *t = (struct tap_output *)o;
  struct tvec_state *tv = t->tv;

  fprintf(t->lyt.fp, "    1..%u\n", t->testix);
  fprintf(t->lyt.fp, "%s %u - %s\n",
          tv->curr[TVOUT_LOSE] ? "not ok" : "ok",
          t->grpix, tv->test->name);
}

/* --- @tap_btest@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *
 * Returns:     ---
 *
 * Use:         Report that a test is starting.
 *
 *              The TAP driver advances its test counter.  (We could do this
 *              by adding up up the counters in @tv->curr@, and add on the
 *              current test, but it's easier this way.)
 */

static void tap_btest(struct tvec_output *o)
  { struct tap_output *t = (struct tap_output *)o; t->testix++; }

/* --- @tap_outcome@, @tap_skip@, @tap_fail@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *              @unsigned attr@ = attribute to apply to the outcome
 *              @const char *outcome@ = outcome string to report
 *              @const char *detail@, @va_list *ap@ = a detail message
 *              @const char *excuse@, @va_list *ap@ = reason for skipping the
 *                      test
 *
 * Returns:     ---
 *
 * Use:         Report that a test has been skipped or failed.
 *
 *              The TAP driver reports the situation on its output stream.
 *              TAP only allows us to report a single status for each
 *              subtest, so we notice when we've already reported a status
 *              for the current test and convert the second report as a
 *              comment.  This should only happen in the case of multiple
 *              failures.
 */

static void tap_outcome(struct tvec_output *o,
                        const char *head, const char *tail,
                        const char *detail, va_list *ap)
{
  struct tap_output *t = (struct tap_output *)o;
  struct tvec_state *tv = t->tv;

  fprintf(t->lyt.fp, "    %s %u - %s:%u%s",
          t->testix == t->previx ? "##" : head,
          t->testix, tv->infile, tv->test_lno, tail);
  if (detail)
    { fputc(' ', t->lyt.fp); vfprintf(t->lyt.fp, detail, *ap); }
  fputc('\n', t->lyt.fp);
  t->previx = t->testix;
}

static void tap_skip(struct tvec_output *o, const char *excuse, va_list *ap)
  { tap_outcome(o, "ok", " # SKIP", excuse, ap); }
static void tap_fail(struct tvec_output *o, const char *detail, va_list *ap)
  { tap_outcome(o, "not ok", "", detail, ap); }

/* --- @tap_dumpreg@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *              @unsigned disp@ = register disposition
 *              @const union tvec_regval *rv@ = register value
 *              @const struct tvec_regdef *rd@ = register definition
 *
 * Returns:     ---
 *
 * Use:         Dump a register.
 *
 *              The TAP driver applies highlighting to mismatching output
 *              registers, but otherwise delegates to the register type
 *              handler and the layout machinery.  The result is that the
 *              register dump is marked as a comment and indented.
 */

static void tap_dumpreg(struct tvec_output *o,
                        unsigned disp, const union tvec_regval *rv,
                        const struct tvec_regdef *rd)
{
  struct tap_output *t = (struct tap_output *)o;
  const char *ds = regdisp(disp); int n = strlen(ds) + strlen(rd->name);

  gprintf(&tap_printops, t, "%*s%s %s = ",
          10 + t->maxlen - n, "", ds, rd->name);
  if (!rv) gprintf(&tap_printops, t, "#<unset>");
  else rd->ty->dump(rv, rd, 0, &tap_printops, t);
  layout_char(&t->lyt, '\n');
}

/* --- @tap_etest@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *              @unsigned outcome@ = the test outcome
 *
 * Returns:     ---
 *
 * Use:         Report that a test has finished.
 *
 *              The TAP driver reports the outcome of the test, if that's not
 *              already decided.
 */

static void tap_etest(struct tvec_output *o, unsigned outcome)
{
  switch (outcome) {
    case TVOUT_WIN:
      tap_outcome(o, "ok", "", 0, 0);
      break;
    case TVOUT_XFAIL:
      tap_outcome(o, "not ok", " # TODO expected failure", 0, 0);
      break;
  }
}

/* --- @tap_bbench@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *              @const char *ident@ = identifying register values
 *              @unsigned unit@ = measurement unit (@TVBU_...@)
 *
 * Returns:     ---
 *
 * Use:         Report that a benchmark has started.
 *
 *              The TAP driver does nothing here.  All of the reporting
 *              happens in @tap_ebench@.
 */

static void tap_bbench(struct tvec_output *o,
                       const char *ident, unsigned unit)
  { ; }

/* --- @tap_ebench@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *              @const char *ident@ = identifying register values
 *              @unsigned unit@ = measurement unit (@TVBU_...@)
 *              @const struct bench_timing *tm@ = measurement
 *
 * Returns:     ---
 *
 * Use:         Report a benchmark's results
 *
 *              The TAP driver just delegates to the default benchmark
 *              reporting, via the layout machinery so that the result is
 *              printed as a comment.
 */

static void tap_ebench(struct tvec_output *o,
                       const char *ident, unsigned unit,
                       const struct bench_timing *tm)
{
  struct tap_output *t = (struct tap_output *)o;
  struct tvec_state *tv = t->tv;

  gprintf(&tap_printops, t, "%s: %s: ", tv->test->name, ident);
  tvec_benchreport(&tap_printops, t, unit, tm);
  layout_char(&t->lyt, '\n');
}

/* --- @tap_report@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *              @unsigned level@ = message level (@TVLEV_...@)
 *              @const char *msg@, @va_list *ap@ = format string and
 *                      arguments
 *
 * Returns:     ---
 *
 * Use:         Report a message to the user.
 *
 *              The TAP driver converts error reports into TAP `Bail out!'
 *              errors.  Less critical notices end up as comments.
 */

static void tap_report(struct tvec_output *o, unsigned level,
                       const char *msg, va_list *ap)
{
  struct tap_output *t = (struct tap_output *)o;
  struct tvec_state *tv = t->tv;
  const struct gprintf_ops *gops; void *go;

  if (level >= TVLEV_ERR) {
    fputs("Bail out!  ", t->lyt.fp);
    gops = &file_printops; go = t->lyt.fp;
  } else {
    gops = &tap_printops; go = t;
  }
  if (tv->infile) gprintf(gops, go, "%s:%u: ", tv->infile, tv->lno);
  gprintf(gops, go, msg, ap); gops->putch(go, '\n');
}

/* --- @tap_destroy@ --- *
 *
 * Arguments:   @struct tvec_output *o@ = output sink, secretly a @struct
 *                      tap_output@
 *
 * Returns:     ---
 *
 * Use:         Release the resources held by the output driver.
 */

static void tap_destroy(struct tvec_output *o)
{
  struct tap_output *t = (struct tap_output *)o;

  destroy_layout(&t->lyt,
                 t->lyt.fp == stdout || t->lyt.fp == stderr ? 0 : DLF_CLOSE);
  xfree(t->outbuf); xfree(t);
}

static const struct tvec_outops tap_ops = {
  tap_bsession, tap_esession,
  tap_bgroup, tap_skipgroup, tap_egroup,
  tap_btest, tap_skip, tap_fail, tap_dumpreg, tap_etest,
  tap_bbench, tap_ebench,
  tap_report,
  tap_destroy
};

/* --- @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 14, but pretends
 *              to be version 13.  The driver produces a TAP `test point' --
 *              i.e., a result reported as `ok' or `not ok' -- for each input
 *              test group.  Failure reports and register dumps are produced
 *              as diagnostic messages before the final group result.  (TAP
 *              permits structuerd YAML data after the test-point result,
 *              which could be used to report details, but (a) postponing the
 *              details until after the report is inconvenient, and (b) there
 *              is no standardization for the YAML anyway, so in practice
 *              it's no more useful than the unstructured diagnostics.
 */

struct tvec_output *tvec_tapoutput(FILE *fp)
{
  struct tap_output *t;

  t = xmalloc(sizeof(*t)); t->_o.ops = &tap_ops;
  init_layout(&t->lyt, fp, "    ## ");
  t->outbuf = 0; t->outsz = 0;
  return (&t->_o);
}

/*----- Default output ----------------------------------------------------*/

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

struct tvec_output *tvec_dfltout(FILE *fp)
{
  int ttyp = getenv_boolean("TVEC_TTY", -1);

  if (ttyp == -1) ttyp = isatty(fileno(fp));
  if (ttyp) return (tvec_humanoutput(fp));
  else return (tvec_tapoutput(fp));
}

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