#define TVEC_GREG(vec, i, regsz) \
((struct tvec_reg *)((unsigned char *)(vec) + (i)*(regsz)))
-/*------ Serialization utilities ------------------------------------------*/
-
-/* --- @tvec_serialize@ --- *
- *
- * Arguments: @const struct tvec_reg *rv@ = vector of registers
- * @buf *b@ = buffer to write on
- * @const struct tvec_regdef *regs@ = vector of register
- * descriptions, terminated by an entry with a null
- * @name@ slot
- * @unsigned nr@ = number of entries in the @rv@ vector
- * @size_t regsz@ = true size of each element of @rv@
- *
- * Returns: Zero on success, @-1@ on failure.
- *
- * Use: Serialize a collection of register values.
- *
- * The `candidate register definitions' are those entries @r@ in
- * the @regs@ vector whose index @r.i@ is strictly less than
- * @nr@. The `selected register definitions' are those
- * candidate register definitions @r@ for which the indicated
- * register @rv[r.i]@ has the @TVRF_LIVE@ flag set. The
- * serialized output begins with a header bitmap: if there are
- * %$n$% candidate register definitions then the header bitmap
- * consists of %$\lceil n/8 \rceil$% bytes. Bits are ordered
- * starting from the least significant bit of the first byte,
- * end ending at the most significant bit of the final byte.
- * The bit corresponding to a candidate register definition is
- * set if and only if that register defintion is selected. The
- * header bitmap is then followed by the serializations of the
- * selected registers -- i.e., for each selected register
- * definition @r@, the serialized value of register @rv[r.i]@ --
- * simply concatenated together, with no padding or alignment.
- *
- * The serialized output is written to the buffer @b@. Failure
- * can be caused by running out of buffer space, or a failing
- * type handler.
- */
-
-extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/,
- const struct tvec_regdef */*regs*/,
- unsigned /*nr*/, size_t /*regsz*/);
-
-/* --- @tvec_deserialize@ --- *
- *
- * Arguments: @struct tvec_reg *rv@ = vector of registers
- * @buf *b@ = buffer to write on
- * @const struct tvec_regdef *regs@ = vector of register
- * descriptions, terminated by an entry with a null
- * @name@ slot
- * @unsigned nr@ = number of entries in the @rv@ vector
- * @size_t regsz@ = true size of each element of @rv@
- *
- * Returns: Zero on success, @-1@ on failure.
- *
- * Use: Deserialize a collection of register values.
- *
- * The size of the register vector @nr@ and the register
- * definitions @regs@ must match those used when producing the
- * serialization. For each serialized register value,
- * deserialize and store the value into the appropriate register
- * slot, and set the @TVRF_LIVE@ flag on the register. See
- * @tvec_serialize@ for a description of the format.
- *
- * On successful completion, store the address of the first byte
- * after the serialized data in @*end_out@ if @end_out@ is not
- * null. Failure results only from a failing register type
- * handler.
- */
-
-extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
- const struct tvec_regdef */*regs*/,
- unsigned /*nr*/, size_t /*regsz*/);
-
/*----- Test state --------------------------------------------------------*/
enum {
*/
#define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->regsz)
+struct tvec_config {
+ /* An overall test configuration. */
+
+ const struct tvec_test *tests; /* the tests to be performed */
+ unsigned nrout, nreg; /* number of output/total regs */
+ size_t regsz; /* size of a register */
+};
+
+/*----- Output formatting -------------------------------------------------*/
+
+struct tvec_output {
+ /* An output formatter. */
+ const struct tvec_outops *ops; /* pointer to operations */
+};
+
+/* Benchmarking details. */
+enum {
+ TVBU_OP, /* counting operations of some kind */
+ TVBU_BYTE /* counting bytes (@rbuf >= 0@) */
+};
+struct bench_timing; /* forward declaration */
+
+struct tvec_outops {
+ /* Output operations. */
+
+ void (*bsession)(struct tvec_output */*o*/, struct tvec_state */*tv*/);
+ /* Begin a test session. The output driver will probably want to
+ * save @tv@, because this isn't provided to any other methods.
+ */
+
+ int (*esession)(struct tvec_output */*o*/);
+ /* End a session, and return the suggested exit code. */
+
+ void (*bgroup)(struct tvec_output */*o*/);
+ /* Begin a test group. The test group description is @tv->test@. */
+
+ void (*skipgroup)(struct tvec_output */*o*/,
+ const char */*excuse*/, va_list */*ap*/);
+ /* The group is being skipped; @excuse@ may be null or a format
+ * string explaining why. The @egroup@ method will not be called
+ * separately.
+ */
+
+ void (*egroup)(struct tvec_output */*o*/);
+ /* End a test group. At least one test was attempted or @skipgroup@
+ * would have been called instead. If @tv->curr[TVOUT_LOSE]@ is
+ * nonzero then the test group as a whole failed; otherwise it
+ * passed.
+ */
+
+ void (*btest)(struct tvec_output */*o*/);
+ /* Begin a test case. */
+
+ void (*skip)(struct tvec_output */*o*/,
+ const char */*excuse*/, va_list */*ap*/);
+ /* The test case is being skipped; @excuse@ may be null or a format
+ * string explaining why. The @etest@ function will still be called
+ * (so this works differently from @skipgroup@ and @egroup@). A test
+ * case can be skipped at most once, and, if skipped, it cannot fail.
+ */
+
+ void (*fail)(struct tvec_output */*o*/,
+ const char */*detail*/, va_list */*ap*/);
+ /* The test case failed.
+ *
+ * The output driver should preferably report the filename (@infile@)
+ * and line number (@test_lno@, not @lno@) for the failing test.
+ *
+ * The @detail@ may be null or a format string describing detail
+ * about how the failing test was run which can't be determined from
+ * the registers; a @detail@ is usually provided when (and only when)
+ * the test environment potentially invokes the test function more
+ * than once.
+ *
+ * A single test case can fail multiple times!
+ */
+
+ void (*dumpreg)(struct tvec_output */*o*/,
+ unsigned /*disp*/, const union tvec_regval */*rv*/,
+ const struct tvec_regdef */*rd*/);
+ /* Dump a register. The `disposition' @disp@ explains what condition
+ * the register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes.
+ * The register value is at @rv@, and its definition, including its
+ * type, at @rd@. Note that this function may be called on virtual
+ * registers which aren't in either of the register vectors or
+ * mentioned by the test description.
+ */
+
+ void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/);
+ /* The test case concluded with the given @outcome@ (one of the
+ * @TVOUT_...@ codes.
+ */
+
+ void (*bbench)(struct tvec_output */*o*/,
+ const char */*ident*/, unsigned /*unit*/);
+ /* Begin a benchmark. The @ident@ is a formatted string identifying
+ * the benchmark based on the values of the input registered marked
+ * @TVRF_ID@; the output driver is free to use this or come up with
+ * its own way to identify the test, e.g., by inspecting the register
+ * values for itself. The @unit@ is one of the @TVBU_...@ constants
+ * explaining what sort of thing is being measured.
+ */
+
+ void (*ebench)(struct tvec_output */*o*/,
+ const char */*ident*/, unsigned /*unit*/,
+ const struct bench_timing */*tm*/);
+ /* End a benchmark. The @ident@ and @unit@ arguments are as for
+ * @bbench@. If @tm@ is zero then the measurement failed; otherwise
+ * @tm->n@ counts total number of things (operations or bytes, as
+ * indicated by @unit@) processed in the indicated time.
+ */
+
+ void (*error)(struct tvec_output */*o*/,
+ const char */*msg*/, va_list */*ap*/);
+ /* Report an error. The driver should ideally report the filename
+ * (@infile@) and line number (@lno@) prompting the error.
+ */
+
+ void (*notice)(struct tvec_output */*o*/,
+ const char */*msg*/, va_list */*ap*/);
+ /* Report a miscellaneous message. The driver should ideally report
+ * the filename (@infile@) and line number (@lno@) prompting the
+ * error.
+ */
+
+ void (*destroy)(struct tvec_output */*o*/);
+ /* Release any resources acquired by the driver. */
+};
+
/*----- Test descriptions -------------------------------------------------*/
typedef void tvec_testfn(const struct tvec_reg */*in*/,
int (*setup)(struct tvec_state */*tv*/, const struct tvec_env */*env*/,
void */*pctx*/, void */*ctx*/);
- /* Initialize the context; called at the start of a test group. Return
- * zero on success, or @-1@ on failure. If setup fails, the context is
- * freed, and the test group is skipped.
+ /* Initialize the context; called at the start of a test group; @pctx@ is
+ * null for environments called by the core, but may be non-null for
+ * subordinate environments. Return zero on success, or @-1@ on failure.
+ * If setup fails, the context is freed, and the test group is skipped.
*/
int (*set)(struct tvec_state */*tv*/, const char */*var*/,
TVRD_EXPECT /* mismatching input register */
};
-/* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- * @const char *excuse@, @va_list *ap@ = reason why skipped
- *
- * Returns: ---
- *
- * Use: Skip the current group. This should only be called from a
- * test environment @setup@ function; a similar effect occurs if
- * the @setup@ function fails.
- */
-
-extern void PRINTF_LIKE(2, 3)
- tvec_skipgroup(struct tvec_state */*tv*/, const char */*excuse*/, ...);
-extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
- const char */*excuse*/, va_list */*ap*/);
-
-/* --- @tvec_skip@, @tvec_skip_v@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- * @const char *excuse@, @va_list *ap@ = reason why test skipped
- *
- * Returns: ---
- *
- * Use: Skip the current test. This should only be called from a
- * test environment @run@ function; a similar effect occurs if
- * the @before@ function fails.
- */
+/*----- Register types ----------------------------------------------------*/
-extern void PRINTF_LIKE(2, 3)
- tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
-extern void tvec_skip_v(struct tvec_state */*tv*/,
- const char */*excuse*/, va_list */*ap*/);
+struct tvec_regty {
+ /* A register type. */
-/* --- @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.
- */
+ void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
+ /* Initialize the value in @*rv@. This will be called before any
+ * other function acting on the value, including @release@.
+ */
-extern void tvec_resetoutputs(struct tvec_state */*tv*/);
+ void (*release)(union tvec_regval */*rv*/,
+ const struct tvec_regdef */*rd*/);
+ /* Release any resources associated with the value in @*rv@. */
-/* --- @tvec_checkregs@ --- *
- *
+ int (*eq)(const union tvec_regval */*rv0*/,
+ const union tvec_regval */*rv1*/,
+ const struct tvec_regdef */*rd*/);
+ /* Return nonzero if @*rv0@ and @*rv1@ are equal values.
+ * Asymmetric criteria are permitted: @tvec_checkregs@ calls @eq@
+ * with the input register as @rv0@ and the output as @rv1@.
+ */
+
+ int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
+ const struct tvec_regdef */*rd*/);
+ /* Serialize the value @*rv@, writing the result to @b@. Return
+ * zero on success, or @-1@ on error.
+ */
+
+ int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
+ const struct tvec_regdef */*rd*/);
+ /* Deserialize a value from @b@, storing it in @*rv@. Return zero on
+ * success, or @-1@ on error.
+ */
+
+ int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
+ struct tvec_state */*tv*/);
+ /* Parse a value from @tv->fp@, storing it in @*rv@. Return zero on
+ * success, or @-1@ on error, having reported one or more errors via
+ * @tvec_error@ or @tvec_syntax@. A successful return should leave
+ * the input position at the start of the next line; the caller will
+ * flush the remainder of the line itself.
+ */
+
+ void (*dump)(const union tvec_regval */*rv*/,
+ const struct tvec_regdef */*rd*/,
+ unsigned /*style*/,
+ const struct gprintf_ops */*gops*/, void */*go*/);
+#define TVSF_COMPACT 1u
+ /* Write a human-readable representation of the value @*rv@ using
+ * @gprintf@ on @gops@ and @go@. The @style@ is a collection of
+ * flags: if @TVSF_COMPACT@ is set, then output should be minimal,
+ * and must fit on a single line; otherwise, output may consist of
+ * multiple lines and may contain redundant information if that is
+ * likely to be useful to a human reader.
+ */
+};
+
+/*----- Session lifecycle -------------------------------------------------*/
+
+/* Here's the overall flow for a testing session.
+ *
+ * @tvec_begin@
+ * -> output @bsession@
+ * @tvec_read@
+ * -> output @bgroup@
+ * -> env @setup@
+ * one or more tests
+ * -> type @init@ (input and output)
+ * -> type @parse@ (input)
+ * -> output @btest@
+ * -> env @before@
+ * -> env @run@
+ * -> @tvec_skip@
+ * -> output @skip@
+ * -> test @fn@
+ * -> @tvec_checkregs@
+ * -> type @eq@
+ * -> @tvec_fail@
+ * -> output @fail@
+ * -> @tvec_mismatch@
+ * -> output @dumpreg@
+ * -> type @dump@
+ * -> env @after@
+ * -> output @etest@
+ * or
+ * -> output @skipgroup@
+ * finally
+ * -> output @egroup@
+ * -> env @teardown@
+ *
+ * @tvec_adhoc@
+ * @tvec_begingroup@
+ * -> output @bgroup@
+ * -> env @setup@
+ * @tvec_begintest@
+ * -> output @btest@
+ * @tvec_skip@
+ * -> output @skip@
+ * @tvec_claimeq@
+ * -> @tvec_fail@
+ * -> output @fail@
+ * -> @tvec_mismatch@
+ * -> output @dumpreg@
+ * -> type @dump@
+ * @tvec_endtest@
+ * -> output @etest@
+ * or @tvec_skipgroup@
+ * -> output @skipgroup@
+ * @tvec_endgroup@
+ * -> output @egroup@
+ *
+ * @tvec_end@
+ * -> output @esession@
+ * -> output @destroy@
+ *
+ * @tvec_benchrun@
+ * -> type @dump@ (compact style)
+ * -> output @bbench@
+ * -> subenv @run@
+ * -> test @fn@
+ * -> output @ebench@
+ * -> @tvec_benchreport@
+ *
+ * The output functions @error@ and @notice@ can be called at arbitrary
+ * times.
+ */
+
+/* --- @tvec_begin@ --- *
+ *
+ * Arguments: @struct tvec_state *tv_out@ = state structure to fill in
+ * @const struct tvec_config *config@ = test configuration
+ * @struct tvec_output *o@ = output driver
+ *
+ * Returns: ---
+ *
+ * Use: Initialize a state structure ready to do some testing.
+ */
+
+extern void tvec_begin(struct tvec_state */*tv_out*/,
+ const struct tvec_config */*config*/,
+ struct tvec_output */*o*/);
+
+/* --- @tvec_end@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: A proposed exit code.
+ *
+ * Use: Conclude testing and suggests an exit code to be returned to
+ * the calling program. (The exit code comes from the output
+ * driver's @esession@ method.)
+ */
+
+extern int tvec_end(struct tvec_state */*tv*/);
+
+/* --- @tvec_read@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *infile@ = the name of the input file
+ * @FILE *fp@ = stream to read from
+ *
+ * Returns: Zero on success, @-1@ on error.
+ *
+ * Use: Read test vector data from @fp@ and exercise test functions.
+ * THe return code doesn't indicate test failures: it's only
+ * concerned with whether there were problems with the input
+ * file or with actually running the tests.
+ */
+
+extern int tvec_read(struct tvec_state */*tv*/,
+ const char */*infile*/, FILE */*fp*/);
+
+/*----- Command-line interface --------------------------------------------*/
+
+extern const struct tvec_config tvec_adhocconfig;
+/* A special @struct tvec_config@ to use for programs which perform ad-hoc
+ * testing.
+ */
+
+/* --- @tvec_parseargs@ --- *
+ *
+ * Arguments: @int argc@ = number of command-line arguments
+ * @char *argv[]@ = vector of argument strings
+ * @struct tvec_state *tv_out@ = test vector state to initialize
+ * @int *argpos_out@ = where to leave unread argument index
+ * @const struct tvec_config *cofig@ = test vector configuration
+ *
+ * Returns: ---
+ *
+ * Use: Parse arguments and set up the test vector state @*tv_out@.
+ * If errors occur, print messages to standard error and exit
+ * with status 2.
+ */
+
+extern void tvec_parseargs(int /*argc*/, char */*argv*/[],
+ struct tvec_state */*tv_out*/,
+ int */*argpos_out*/,
+ const struct tvec_config */*config*/);
+
+/* --- @tvec_readstdin@, @tvec_readfile@, @tvec_readarg@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test vector state
+ * @const char *file@ = pathname of file to read
+ * @const char *arg@ = argument to interpret
+ *
+ * Returns: Zero on success, @-1@ on error.
+ *
+ * Use: Read test vector data from stdin or a named file. The
+ * @tvec_readarg@ function reads from stdin if @arg@ is `%|-|%',
+ * and from the named file otherwise.
+ */
+
+extern int tvec_readstdin(struct tvec_state */*tv*/);
+extern int tvec_readfile(struct tvec_state */*tv*/, const char */*file*/);
+extern int tvec_readarg(struct tvec_state */*tv*/, const char */*arg*/);
+
+/* --- @tvec_readdflt@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test vector state
+ * @const char *dflt@ = defsault filename or null
+ *
+ * Returns: Zero on success, @-1@ on error.
+ *
+ * Use: Reads from the default test vector data. If @file@ is null,
+ * then read from standard input, unless that's a terminal; if
+ * @file@ is not null, then read the named file, looking in the
+ * directory named by the `%|srcdir|%' environment variable if
+ * that's set, or otherwise in the current directory.
+ */
+
+extern int tvec_readdflt(struct tvec_state */*tv*/, const char */*file*/);
+
+/* --- @tvec_readargs@ --- *
+ *
+ * Arguments: @int argc@ = number of command-line arguments
+ * @char *argv[]@ = vector of argument strings
+ * @struct tvec_state *tv@ = test vector state
+ * @int *argpos_inout@ = current argument position (updated)
+ * @const char *dflt@ = default filename or null
+ *
+ * Returns: Zero on success, @-1@ on error.
+ *
+ * Use: Reads from the sources indicated by the command-line
+ * arguments, in order, interpreting each as for @tvec_readarg@;
+ * if no arguments are given then read from @dflt@ as for
+ * @tvec_readdflt@.
+ */
+
+extern int tvec_readargs(int /*argc*/, char */*argv*/[],
+ struct tvec_state */*tv*/,
+ int */*argpos_inout*/, const char */*dflt*/);
+
+/* --- @tvec_main@ --- *
+ *
+ * Arguments: @int argc@ = number of command-line arguments
+ * @char *argv[]@ = vector of argument strings
+ * @const struct tvec_config *cofig@ = test vector configuration
+ * @const char *dflt@ = default filename or null
+ *
+ * Returns: Exit code.
+ *
+ * Use: All-in-one test vector front-end. Parse options from the
+ * command-line as for @tvec_parseargs@, and then process the
+ * remaining positional arguments as for @tvec_readargs@. The
+ * function constructs and disposes of a test vector state.
+ */
+
+extern int tvec_main(int /*argc*/, char */*argv*/[],
+ const struct tvec_config */*config*/,
+ const char */*dflt*/);
+
+/*----- Test processing ---------------------------------------------------*/
+
+/* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *excuse@, @va_list *ap@ = reason why skipped
+ *
+ * Returns: ---
+ *
+ * Use: Skip the current group. This should only be called from a
+ * test environment @setup@ function; a similar effect occurs if
+ * the @setup@ function fails.
+ */
+
+extern void PRINTF_LIKE(2, 3)
+ tvec_skipgroup(struct tvec_state */*tv*/, const char */*excuse*/, ...);
+extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
+ const char */*excuse*/, va_list */*ap*/);
+
+/* --- @tvec_skip@, @tvec_skip_v@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *excuse@, @va_list *ap@ = reason why test skipped
+ *
+ * Returns: ---
+ *
+ * Use: Skip the current test. This should only be called from a
+ * test environment @run@ function; a similar effect occurs if
+ * the @before@ function fails.
+ */
+
+extern void PRINTF_LIKE(2, 3)
+ tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
+extern void tvec_skip_v(struct tvec_state */*tv*/,
+ const char */*excuse*/, va_list */*ap*/);
+
+/* --- @tvec_resetoutputs@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: ---
+ *
+ * Use: Reset (releases and reinitializes) the output registers in
+ * the test state. This is mostly of use to test environment
+ * @run@ functions, between invocations of the test function.
+ */
+
+extern void tvec_resetoutputs(struct tvec_state */*tv*/);
+
+/* --- @tvec_checkregs@ --- *
+ *
* Arguments: @struct tvec_state *tv@ = test-vector state
*
* Returns: Zero on success, @-1@ on mismatch.
extern void tvec_check_v(struct tvec_state */*tv*/,
const char */*detail*/, va_list */*ap*/);
-/*----- Session lifecycle -------------------------------------------------*/
-
-struct tvec_config {
- /* An overall test configuration. */
-
- const struct tvec_test *tests; /* the tests to be performed */
- unsigned nrout, nreg; /* number of output/total regs */
- size_t regsz; /* size of a register */
-};
+/*----- Ad-hoc testing ----------------------------------------------------*/
-/* --- @tvec_begin@ --- *
+/* --- @tvec_adhoc@ --- *
*
- * Arguments: @struct tvec_state *tv_out@ = state structure to fill in
- * @const struct tvec_config *config@ = test configuration
- * @struct tvec_output *o@ = output driver
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @struct tvec_test *t@ = space for a test definition
*
* Returns: ---
*
- * Use: Initialize a state structure ready to do some testing.
+ * Use: Begin ad-hoc testing, i.e., without reading a file of
+ * test-vector data.
+ *
+ * The structure at @t@ will be used to record information about
+ * the tests underway, which would normally come from a static
+ * test definition. The other functions in this section assume
+ * that @tvec_adhoc@ has been called.
*/
-extern void tvec_begin(struct tvec_state */*tv_out*/,
- const struct tvec_config */*config*/,
- struct tvec_output */*o*/);
+extern void tvec_adhoc(struct tvec_state */*tv*/, struct tvec_test */*t*/);
-/* --- @tvec_end@ --- *
+/* --- @tvec_begingroup@, @TVEC_BEGINGROUP@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *name@ = name for this test group
+ * @const char *file@, @unsigned @lno@ = calling file and line
*
- * Returns: A proposed exit code.
+ * Returns: ---
*
- * 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.)
+ * Use: Begin an ad-hoc test group with the given name. The @file@
+ * and @lno@ can be anything, but it's usually best if they
+ * refer to the source code performing the test: the macro
+ * @TVEC_BEGINGROUP@ does this automatically.
*/
-extern int tvec_end(struct tvec_state */*tv*/);
+extern void tvec_begingroup(struct tvec_state */*tv*/, const char */*name*/,
+ const char */*file*/, unsigned /*lno*/);
+#define TVEC_BEGINGROUP(tv, name) \
+ do tvec_begingroup(tv, name, __FILE__, __LINE__); while (0)
-/* --- @tvec_read@ --- *
+/* --- @tvec_endgroup@ --- *
*
* 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.
+ * Returns: ---
*
- * Use: Read test vector data from @fp@ and exercise test functions.
- * THe return code doesn't indicate test failures: it's only
- * concerned with whether there were problems with the input
- * file or with actually running the tests.
- */
-
-extern int tvec_read(struct tvec_state */*tv*/,
- const char */*infile*/, FILE */*fp*/);
-
-/*----- Input utilities ---------------------------------------------------*/
-
-/* These are provided by the core for the benefit of type @parse@ methods,
- * and test-environment @set@ functions, which get to read from the test
- * input file. The latter are usually best implemented by calling on the
- * former.
- *
- * The two main rules are as follows.
- *
- * * Leave the file position at the beginning of the line following
- * whatever it was that you read.
- *
- * * When you read and consume a newline (which you do at least once, by
- * the previous rule), then increment @tv->lno@ to keep track of the
- * current line number.
- */
-
-/* --- @tvec_skipspc@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- *
- * Returns: ---
- *
- * Use: Advance over any whitespace characters other than newlines.
- * This will stop at `;', end-of-file, or any other kind of
- * non-whitespace; and it won't consume a newline.
- */
-
-extern void tvec_skipspc(struct tvec_state */*tv*/);
-
-/* --- @tvec_syntax@, @tvec_syntax_v@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- * @int ch@ = the character found (in @fgetc@ format)
- * @const char *expect@, @va_list ap@ = what was expected
- *
- * Returns: @-1@
- *
- * Use: Report a syntax error quoting @ch@ and @expect@. If @ch@ is
- * a newline, then back up so that it can be read again (e.g.,
- * by @tvec_flushtoeol@ or @tvec_nexttoken@, which will also
- * advance the line number).
- */
-
-extern int PRINTF_LIKE(3, 4)
- tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
- const char */*expect*/, ...);
-extern int tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/,
- const char */*expect*/, va_list */*ap*/);
-
-/* --- @tvec_flushtoeol@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- * @unsigned f@ = flags (@TVFF_...@)
- *
- * Returns: Zero on success, @-1@ on error.
- *
- * Use: Advance to the start of the next line, consuming the
- * preceding newline.
- *
- * A syntax error is reported if no newline character is found,
- * i.e., the file ends in mid-line. A syntax error is also
- * reported if material other than whitespace or a comment is
- * found before the end of the line end, and @TVFF_ALLOWANY@ is
- * not set in @f@. The line number count is updated
- * appropriately.
- */
-
-#define TVFF_ALLOWANY 1u
-extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);
-
-/* --- @tvec_nexttoken@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- *
- * Returns: Zero if there is a next token which can be read; @-1@ if no
- * token is available.
- *
- * Use: Advance to the next whitespace-separated token, which may be
- * on the next line.
- *
- * Tokens are separated by non-newline whitespace, comments, and
- * newlines followed by whitespace; a newline /not/ followed by
- * whitespace instead begins the next assignment, and two
- * newlines separated only by whitespace terminate the data for
- * a test.
- *
- * If this function returns zero, then the next character in the
- * file begins a suitable token which can be read and
- * processed. If it returns @-1@ then there is no such token,
- * and the file position is left correctly. The line number
- * count is updated appropriately.
- */
-
-extern int tvec_nexttoken(struct tvec_state */*tv*/);
-
-/* --- @tvec_readword@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- * @dstr *d@ = string to append the word to
- * @const char *delims@ = additional delimiters to stop at
- * @const char *expect@, @va_list ap@ = what was expected
- *
- * Returns: Zero on success, @-1@ on failure.
- *
- * Use: A `word' consists of characters other than whitespace, null
- * characters, and other than those listed in @delims@;
- * furthermore, a word does not begin with a `;'. (If you want
- * reading to stop at comments not preceded by whitespace, then
- * include `;' in @delims@. This is a common behaviour.)
- *
- * If there is no word beginning at the current file position,
- * then return @-1@; furthermore, if @expect@ is not null, then
- * report an appropriate error via @tvec_syntax@.
- *
- * Otherwise, the word is accumulated in @d@ and zero is
- * returned; if @d@ was not empty at the start of the call, the
- * newly read word is separated from the existing material by a
- * single space character. Since null bytes are never valid
- * word constituents, a null terminator is written to @d@, and
- * it is safe to treat the string in @d@ as being null-
- * terminated.
- */
-
-extern int PRINTF_LIKE(4, 5)
- tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
- const char */*delims*/, const char */*expect*/, ...);
-extern int tvec_readword_v(struct tvec_state */*tv*/, dstr */*d*/,
- const char */*delims*/, const char */*expect*/,
- va_list */*ap*/);
-
-/*----- Ad-hoc testing ----------------------------------------------------*/
-
-/* --- @tvec_adhoc@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- * @struct tvec_test *t@ = space for a test definition
- *
- * Returns: ---
- *
- * Use: Begin ad-hoc testing, i.e., without reading a file of
- * test-vector data.
- *
- * The structure at @t@ will be used to record information about
- * the tests underway, which would normally come from a static
- * test definition. The other functions in this section assume
- * that @tvec_adhoc@ has been called.
- */
-
-extern void tvec_adhoc(struct tvec_state */*tv*/, struct tvec_test */*t*/);
-
-/* --- @tvec_begingroup@, @TVEC_BEGINGROUP@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- * @const char *name@ = name for this test group
- * @const char *file@, @unsigned @lno@ = calling file and line
- *
- * Returns: ---
- *
- * Use: Begin an ad-hoc test group with the given name. The @file@
- * and @lno@ can be anything, but it's usually best if they
- * refer to the source code performing the test: the macro
- * @TVEC_BEGINGROUP@ does this automatically.
- */
-
-extern void tvec_begingroup(struct tvec_state */*tv*/, const char */*name*/,
- const char */*file*/, unsigned /*lno*/);
-#define TVEC_BEGINGROUP(tv, name) \
- do tvec_begingroup(tv, name, __FILE__, __LINE__); while (0)
-
-/* --- @tvec_endgroup@ --- *
- *
- * Arguments: @struct tvec_state *tv@ = test-vector state
- *
- * Returns: ---
- *
- * Use: End an ad-hoc test group. The statistics are updated and the
- * outcome is reported to the output formatter.
+ * Use: End an ad-hoc test group. The statistics are updated and the
+ * outcome is reported to the output formatter.
*/
extern void tvec_endgroup(struct tvec_state */*tv*/);
const char */*file*/, unsigned /*lno*/,
const char */*expr*/);
-/*----- Output formatting -------------------------------------------------*/
+/*----- Benchmarking ------------------------------------------------------*/
-struct tvec_output {
- /* An output formatter. */
- const struct tvec_outops *ops; /* pointer to operations */
+struct tvec_bench {
+ struct tvec_env _env; /* benchmarking is an environment */
+ struct bench_state **bst; /* benchmark state anchor or null */
+ unsigned long niter; /* iterations done per unit */
+ int riter, rbuf; /* iterations and buffer registers */
+ const struct tvec_env *env; /* subordinate environment */
};
+#define TVEC_BENCHENV \
+ { sizeof(struct tvec_benchctx), \
+ tvec_benchsetup, \
+ tvec_benchset, \
+ tvec_benchbefore, \
+ tvec_benchrun, \
+ tvec_benchafter, \
+ tvec_benchteardown }
+#define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate
-/* Benchmarking details. */
-enum {
- TVBU_OP, /* counting operations of some kind */
- TVBU_BYTE /* counting bytes (@RBUF >= 0@) */
+struct tvec_benchctx {
+ const struct tvec_bench *b;
+ struct bench_state *bst;
+ double dflt_target;
+ void *subctx;
};
-struct bench_timing; /* forward declaration */
-struct tvec_outops {
- /* Output operations. */
+extern struct bench_state *tvec_benchstate;
- void (*bsession)(struct tvec_output */*o*/, struct tvec_state */*tv*/);
- /* Begin a test session. The output driver will probably want to
- * save @tv@, because this isn't provided to any other methods.
- */
+/* --- @tvec_benchsetup@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test vector state
+ * @const struct tvec_env *env@ = environment description
+ * @void *pctx@ = parent context (ignored)
+ * @void *ctx@ = context pointer to initialize
+ *
+ * Returns: Zero on success, @-1@ on failure.
+ *
+ * Use: Initialize a benchmarking environment context.
+ *
+ * The environment description must really be a @struct
+ * tvec_bench@. If the @bst@ slot is null, then a temporary
+ * benchmark state is allocated for the current test group and
+ * released at the end. Otherwise, it must be the address of a
+ * pointer to a benchmark state: if the pointer is null, then a
+ * fresh state is allocated and initialized and the pointer is
+ * updated; otherwise, the pointer is assumed to refer to an
+ * existing valid benchmark state.
+ */
- int (*esession)(struct tvec_output */*o*/);
- /* End a session, and return the suggested exit code. */
+extern int tvec_benchsetup(struct tvec_state */*tv*/,
+ const struct tvec_env */*env*/,
+ void */*pctx*/, void */*ctx*/);
- void (*bgroup)(struct tvec_output */*o*/);
- /* Begin a test group. The test group description is @tv->test@. */
+/* --- @tvec_benchset@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test vector state
+ * @const char *var@ = variable name to set
+ * @const struct tvec_env *env@ = environment description
+ * @void *ctx@ = context pointer
+ *
+ * Returns: Zero on success, @-1@ on failure.
+ *
+ * Use: Set a special variable. The following special variables are
+ * supported.
+ *
+ * * %|@target|% is the (approximate) number of seconds to run
+ * the benchmark.
+ *
+ * Unrecognized variables are passed to the subordinate
+ * environment, if there is one.
+ */
- void (*skipgroup)(struct tvec_output */*o*/,
- const char */*excuse*/, va_list */*ap*/);
- /* The group is being skipped; @excuse@ may be null or a format
- * string explaining why. The @egroup@ method will not be called
- * separately.
- */
+extern int tvec_benchset(struct tvec_state */*tv*/, const char */*var*/,
+ const struct tvec_env */*env*/, void */*ctx*/);
- void (*egroup)(struct tvec_output */*o*/);
- /* End a test group. At least one test was attempted or @skipgroup@
- * would have been called instead. If @tv->curr[TVOUT_LOSE]@ is
- * nonzero then the test group as a whole failed; otherwise it
- * passed.
- */
+/* --- @tvec_benchbefore@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test vector state
+ * @void *ctx@ = context pointer
+ *
+ * Returns: Zero on success, @-1@ on failure.
+ *
+ * Use: Invoke the subordinate environment's @before@ function to
+ * prepare for the benchmark.
+ */
- void (*btest)(struct tvec_output */*o*/);
- /* Begin a test case. */
+extern int tvec_benchbefore(struct tvec_state */*tv*/, void */*ctx*/);
- void (*skip)(struct tvec_output */*o*/,
- const char */*excuse*/, va_list */*ap*/);
- /* The test case is being skipped; @excuse@ may be null or a format
- * string explaining why. The @etest@ function will still be called
- * (so this works differently from @skipgroup@ and @egroup@). A test
- * case can be skipped at most once, and, if skipped, it cannot fail.
- */
+/* --- @tvec_benchrun@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test vector state
+ * @tvec_testfn *fn@ = test function to run
+ * @void *ctx@ = context pointer for the test function
+ *
+ * Returns: ---
+ *
+ * Use: Measures and reports the performance of a test function.
+ *
+ *
+ */
- void (*fail)(struct tvec_output */*o*/,
- const char */*detail*/, va_list */*ap*/);
- /* The test case failed.
- *
- * The output driver should preferably report the filename (@infile@)
- * and line number (@test_lno@, not @lno@) for the failing test.
- *
- * The @detail@ may be null or a format string describing detail
- * about how the failing test was run which can't be determined from
- * the registers; a @detail@ is usually provided when (and only when)
- * the test environment potentially invokes the test function more
- * than once.
- *
- * A single test case can fail multiple times!
- */
+extern void tvec_benchrun(struct tvec_state */*tv*/,
+ tvec_testfn */*fn*/, void */*ctx*/);
- void (*dumpreg)(struct tvec_output */*o*/,
- unsigned /*disp*/, const union tvec_regval */*rv*/,
- const struct tvec_regdef */*rd*/);
- /* Dump a register. The `disposition' @disp@ explains what condition
- * the register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes.
- * The register value is at @rv@, and its definition, including its
- * type, at @rd@. Note that this function may be called on virtual
- * registers which aren't in either of the register vectors or
- * mentioned by the test description.
- */
+/* --- @tvec_benchafter@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test vector state
+ * @void *ctx@ = context pointer
+ *
+ * Returns: ---
+ *
+ * Use: Invoke the subordinate environment's @after@ function to
+ * clean up after the benchmark.
+ */
- void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/);
- /* The test case concluded with the given @outcome@ (one of the
- * @TVOUT_...@ codes.
- */
+extern void tvec_benchafter(struct tvec_state */*tv*/, void */*ctx*/);
- void (*bbench)(struct tvec_output */*o*/,
- const char */*ident*/, unsigned /*unit*/);
- /* Begin a benchmark. The @ident@ is a formatted string identifying
- * the benchmark based on the values of the input registered marked
- * @TVRF_ID@; the output driver is free to use this or come up with
- * its own way to identify the test, e.g., by inspecting the register
- * values for itself. The @unit@ is one of the @TVBU_...@ constants
- * explaining what sort of thing is being measured.
- */
+/* --- @tvec_benchteardown@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test vector state
+ * @void *ctx@ = context pointer
+ *
+ * Returns: ---
+ *
+ * Use: Tear down the benchmark environment.
+ */
- void (*ebench)(struct tvec_output */*o*/,
- const char */*ident*/, unsigned /*unit*/,
- const struct bench_timing */*tm*/);
- /* End a benchmark. The @ident@ and @unit@ arguments are as for
- * @bbench@. If @tm@ is zero then the measurement failed; otherwise
- * @tm->n@ counts total number of things (operations or bytes, as
- * indicated by @unit@) processed in the indicated time.
- */
+extern void tvec_benchteardown(struct tvec_state */*tv*/, void */*ctx*/);
- void (*error)(struct tvec_output */*o*/,
- const char */*msg*/, va_list */*ap*/);
- /* Report an error. The driver should ideally report the filename
- * (@infile@) and line number (@lno@) prompting the error.
- */
+/* --- @tvec_benchreport@ --- *
+ *
+ * Arguments: @const struct gprintf_ops *gops@ = print operations
+ * @void *go@ = print destination
+ * @unsigned unit@ = the unit being measured (~TVBU_...@)
+ * @const struct bench_timing *tm@ = the benchmark result
+ *
+ * Returns: ---
+ *
+ * Use: Formats a report about the benchmark performance. This
+ * function is intended to be called on by an output
+ * @ebench@ function.
+ */
- void (*notice)(struct tvec_output */*o*/,
- const char */*msg*/, va_list */*ap*/);
- /* Report a miscellaneous message. The driver should ideally report
- * the filename (@infile@) and line number (@lno@) prompting the
- * error.
- */
+extern void tvec_benchreport
+ (const struct gprintf_ops */*gops*/, void */*go*/,
+ unsigned /*unit*/, const struct bench_timing */*tm*/);
- void (*destroy)(struct tvec_output */*o*/);
- /* Release any resources acquired by the driver. */
-};
+/*----- Output functions --------------------------------------------------*/
/* --- @tvec_error@, @tvec_error_v@ --- *
*
extern struct tvec_output *tvec_dfltout(FILE */*fp*/);
-/*----- Register types ----------------------------------------------------*/
+/*------ Serialization utilities ------------------------------------------*/
-struct tvec_regty {
- /* A register type. */
+/* --- @tvec_serialize@ --- *
+ *
+ * Arguments: @const struct tvec_reg *rv@ = vector of registers
+ * @buf *b@ = buffer to write on
+ * @const struct tvec_regdef *regs@ = vector of register
+ * descriptions, terminated by an entry with a null
+ * @name@ slot
+ * @unsigned nr@ = number of entries in the @rv@ vector
+ * @size_t regsz@ = true size of each element of @rv@
+ *
+ * Returns: Zero on success, @-1@ on failure.
+ *
+ * Use: Serialize a collection of register values.
+ *
+ * The `candidate register definitions' are those entries @r@ in
+ * the @regs@ vector whose index @r.i@ is strictly less than
+ * @nr@. The `selected register definitions' are those
+ * candidate register definitions @r@ for which the indicated
+ * register @rv[r.i]@ has the @TVRF_LIVE@ flag set. The
+ * serialized output begins with a header bitmap: if there are
+ * %$n$% candidate register definitions then the header bitmap
+ * consists of %$\lceil n/8 \rceil$% bytes. Bits are ordered
+ * starting from the least significant bit of the first byte,
+ * end ending at the most significant bit of the final byte.
+ * The bit corresponding to a candidate register definition is
+ * set if and only if that register defintion is selected. The
+ * header bitmap is then followed by the serializations of the
+ * selected registers -- i.e., for each selected register
+ * definition @r@, the serialized value of register @rv[r.i]@ --
+ * simply concatenated together, with no padding or alignment.
+ *
+ * The serialized output is written to the buffer @b@. Failure
+ * can be caused by running out of buffer space, or a failing
+ * type handler.
+ */
- void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
- /* Initialize the value in @*rv@. This will be called before any
- * other function acting on the value, including @release@.
- */
+extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/,
+ const struct tvec_regdef */*regs*/,
+ unsigned /*nr*/, size_t /*regsz*/);
- void (*release)(union tvec_regval */*rv*/,
- const struct tvec_regdef */*rd*/);
- /* Release any resources associated with the value in @*rv@. */
+/* --- @tvec_deserialize@ --- *
+ *
+ * Arguments: @struct tvec_reg *rv@ = vector of registers
+ * @buf *b@ = buffer to write on
+ * @const struct tvec_regdef *regs@ = vector of register
+ * descriptions, terminated by an entry with a null
+ * @name@ slot
+ * @unsigned nr@ = number of entries in the @rv@ vector
+ * @size_t regsz@ = true size of each element of @rv@
+ *
+ * Returns: Zero on success, @-1@ on failure.
+ *
+ * Use: Deserialize a collection of register values.
+ *
+ * The size of the register vector @nr@ and the register
+ * definitions @regs@ must match those used when producing the
+ * serialization. For each serialized register value,
+ * deserialize and store the value into the appropriate register
+ * slot, and set the @TVRF_LIVE@ flag on the register. See
+ * @tvec_serialize@ for a description of the format.
+ *
+ * On successful completion, store the address of the first byte
+ * after the serialized data in @*end_out@ if @end_out@ is not
+ * null. Failure results only from a failing register type
+ * handler.
+ */
- int (*eq)(const union tvec_regval */*rv0*/,
- const union tvec_regval */*rv1*/,
- const struct tvec_regdef */*rd*/);
- /* Return nonzero if @*rv0@ and @*rv1@ are equal values.
- * Asymmetric criteria are permitted: @tvec_checkregs@ calls @eq@
- * with the input register as @rv0@ and the output as @rv1@.
- */
+extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
+ const struct tvec_regdef */*regs*/,
+ unsigned /*nr*/, size_t /*regsz*/);
- int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
- const struct tvec_regdef */*rd*/);
- /* Serialize the value @*rv@, writing the result to @b@. Return
- * zero on success, or @-1@ on error.
- */
+/*----- Input utilities ---------------------------------------------------*/
+
+/* These are provided by the core for the benefit of type @parse@ methods,
+ * and test-environment @set@ functions, which get to read from the test
+ * input file. The latter are usually best implemented by calling on the
+ * former.
+ *
+ * The two main rules are as follows.
+ *
+ * * Leave the file position at the beginning of the line following
+ * whatever it was that you read.
+ *
+ * * When you read and consume a newline (which you do at least once, by
+ * the previous rule), then increment @tv->lno@ to keep track of the
+ * current line number.
+ */
+
+/* --- @tvec_skipspc@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: ---
+ *
+ * Use: Advance over any whitespace characters other than newlines.
+ * This will stop at `;', end-of-file, or any other kind of
+ * non-whitespace; and it won't consume a newline.
+ */
+
+extern void tvec_skipspc(struct tvec_state */*tv*/);
+
+/* --- @tvec_syntax@, @tvec_syntax_v@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @int ch@ = the character found (in @fgetc@ format)
+ * @const char *expect@, @va_list ap@ = what was expected
+ *
+ * Returns: @-1@
+ *
+ * Use: Report a syntax error quoting @ch@ and @expect@. If @ch@ is
+ * a newline, then back up so that it can be read again (e.g.,
+ * by @tvec_flushtoeol@ or @tvec_nexttoken@, which will also
+ * advance the line number).
+ */
+
+extern int PRINTF_LIKE(3, 4)
+ tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
+ const char */*expect*/, ...);
+extern int tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/,
+ const char */*expect*/, va_list */*ap*/);
+
+/* --- @tvec_flushtoeol@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @unsigned f@ = flags (@TVFF_...@)
+ *
+ * Returns: Zero on success, @-1@ on error.
+ *
+ * Use: Advance to the start of the next line, consuming the
+ * preceding newline.
+ *
+ * A syntax error is reported if no newline character is found,
+ * i.e., the file ends in mid-line. A syntax error is also
+ * reported if material other than whitespace or a comment is
+ * found before the end of the line end, and @TVFF_ALLOWANY@ is
+ * not set in @f@. The line number count is updated
+ * appropriately.
+ */
+
+#define TVFF_ALLOWANY 1u
+extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);
+
+/* --- @tvec_nexttoken@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: Zero if there is a next token which can be read; @-1@ if no
+ * token is available.
+ *
+ * Use: Advance to the next whitespace-separated token, which may be
+ * on the next line.
+ *
+ * Tokens are separated by non-newline whitespace, comments, and
+ * newlines followed by whitespace; a newline /not/ followed by
+ * whitespace instead begins the next assignment, and two
+ * newlines separated only by whitespace terminate the data for
+ * a test.
+ *
+ * If this function returns zero, then the next character in the
+ * file begins a suitable token which can be read and
+ * processed. If it returns @-1@ then there is no such token,
+ * and the file position is left correctly. The line number
+ * count is updated appropriately.
+ */
- int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
- const struct tvec_regdef */*rd*/);
- /* Deserialize a value from @b@, storing it in @*rv@. Return zero on
- * success, or @-1@ on error.
- */
+extern int tvec_nexttoken(struct tvec_state */*tv*/);
- int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
- struct tvec_state */*tv*/);
- /* Parse a value from @tv->fp@, storing it in @*rv@. Return zero on
- * success, or @-1@ on error, having reported one or more errors via
- * @tvec_error@ or @tvec_syntax@. A successful return should leave
- * the input position at the start of the next line; the caller will
- * flush the remainder of the line itself.
- */
+/* --- @tvec_readword@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @dstr *d@ = string to append the word to
+ * @const char *delims@ = additional delimiters to stop at
+ * @const char *expect@, @va_list ap@ = what was expected
+ *
+ * Returns: Zero on success, @-1@ on failure.
+ *
+ * Use: A `word' consists of characters other than whitespace, null
+ * characters, and other than those listed in @delims@;
+ * furthermore, a word does not begin with a `;'. (If you want
+ * reading to stop at comments not preceded by whitespace, then
+ * include `;' in @delims@. This is a common behaviour.)
+ *
+ * If there is no word beginning at the current file position,
+ * then return @-1@; furthermore, if @expect@ is not null, then
+ * report an appropriate error via @tvec_syntax@.
+ *
+ * Otherwise, the word is accumulated in @d@ and zero is
+ * returned; if @d@ was not empty at the start of the call, the
+ * newly read word is separated from the existing material by a
+ * single space character. Since null bytes are never valid
+ * word constituents, a null terminator is written to @d@, and
+ * it is safe to treat the string in @d@ as being null-
+ * terminated.
+ */
- void (*dump)(const union tvec_regval */*rv*/,
- const struct tvec_regdef */*rd*/,
- unsigned /*style*/,
- const struct gprintf_ops */*gops*/, void */*go*/);
-#define TVSF_COMPACT 1u
- /* Write a human-readable representation of the value @*rv@ using
- * @gprintf@ on @gops@ and @go@. The @style@ is a collection of
- * flags: if @TVSF_COMPACT@ is set, then output should be minimal,
- * and must fit on a single line; otherwise, output may consist of
- * multiple lines and may contain redundant information if that is
- * likely to be useful to a human reader.
- */
-};
+extern int PRINTF_LIKE(4, 5)
+ tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
+ const char */*delims*/, const char */*expect*/, ...);
+extern int tvec_readword_v(struct tvec_state */*tv*/, dstr */*d*/,
+ const char */*delims*/, const char */*expect*/,
+ va_list */*ap*/);
-/*----- Integer types: signed and unsigned ------------------------------- */
+/*----- Integer types: signed and unsigned --------------------------------*/
/* Integers may be input in decimal, hex, binary, or octal, following
* approximately usual conventions.
tvrange_uchar, tvrange_ushort, tvrange_uint, tvrange_ulong, tvrange_size,
tvrange_byte, tvrange_u16, tvrange_u32;
-/* --- tvec_claimeq_int@, @TVEC_CLAIMEQ_INT@ --- *
+/* --- @tvec_claimeq_int@, @TVEC_CLAIMEQ_INT@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
* @long i0, i1@ = two signed integers
/*----- Enumerated types --------------------------------------------------*/
-/* There is a distinct enumerated type for each of the branches of
+/* An enumeration describes a set of values of some underlying type, each of
+ * which has a symbolic name. Values outside of the defined set can occur --
+ * on output, because of bugs in the tested code, or on input to test
+ * handling of unexpected values.
+ *
+ * There is a distinct enumerated type for each of the branches of
* @tvec_misc@. In the following, we write @t@ for the type code, which is
* @i@ for signed integer, @u@ for unsigned integer, @f@ for floating-point,
* and @p@ for pointer.
+ *
+ * On input, an enumerated value may be given by name or as a literal value.
+ * For enumerations based on numeric types, the literal values can be written
+ * in the same syntax as the underlying values. For enumerations based on
+ * pointers, the only permitted literal is `#nil', which denotes a null
+ * pointer. On output, names are preferred (with the underlying value given
+ * in a comment).
*/
#define DEFENUMTY(tag, ty, slot) \
TVEC_MISCSLOTS(DEFASSOC)
#undef DEFASSOC
+#define TVEC_ENDENUM { 0, 0 }
+
/* Information about an enumerated type. */
#define DEFINFO(tag, ty, slot) \
struct tvec_##slot##enuminfo { \
/* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const struct tvec_typeenuminfo *ei@ = enumeration type info
* @ty t0, t1@ = two values
* @const char *file@, @unsigned @lno@ = calling file and line
* @const char *expr@ = the expression to quote on failure
* @tvec_claim@ above, a test case is automatically begun and
* ended if none is already underway. If the values are
* unequal, then @tvec_fail@ is called, quoting @expr@, and the
- * mismatched values are dumped: @u0@ is printed as the output
- * value and @u1@ is printed as the input reference.
+ * mismatched values are dumped: @t0@ is printed as the output
+ * value and @t1@ is printed as the input reference.
*
* The @TVEC_CLAIM_TENUM@ macro is similar, only it (a)
* identifies the file and line number of the call site
* automatically, and (b) implicitly quotes the source text of
- * the @u0@ and @u1@ arguments in the failure message.
+ * the @t0@ and @t1@ arguments in the failure message.
*/
#define DECLCLAIM(tag, ty, slot) \
(tvec_claimeq_penum(tv, ei, p0, p1, \
__FILE__, __LINE__, #p0 " /= " #p1))
-/*----- Flags type -------------------------------------------------------*/
+/*----- Flags type --------------------------------------------------------*/
+
+/* A flags value packs a number of fields into a single nonnegative integer.
+ * Symbolic names are associated with the possible values of the various
+ * fields; more precisely, each name is associated with a value and a
+ * covering bitmask.
+ *
+ * The input syntax is a sequence of items separated by `|' signs. Each item
+ * may be the symbolic name of a field value, or a literal unsigned integer.
+ * The masks associated with the given symbolic names must be disjoint. The
+ * resulting numerical value is simply the bitwise OR of the given values.
+ *
+ * On output, the table of symbolic names and their associated values and
+ * masks is repeatedly scanned, in order, to find disjoint matches -- i.e.,
+ * entries whose value matches the target value in the bit positions
+ * indicated by the mask, and whose mask doesn't overlap with any previously
+ * found matches; the names are then output, separated by `|'. Any remaining
+ * nonzero bits not covered by any of the matching masks are output as a
+ * single literal integer, in hex.
+ */
extern const struct tvec_regty tvty_flags;
/* Definition of a single flag or bitfield value.
*
* Each named setting comes with a value @v@ and a mask @m@; the mask
- * should cover all of the value bits, i.e., @(v&~m) == 0@. On input,
- * exactly
+ * should cover all of the value bits, i.e., @(v&~m) == 0@.
*/
const char *tag; /* name */
unsigned long m, v; /* mask and value */
};
+#define TVEC_ENDFLAGS { 0, 0, 0 }
+
struct tvec_flaginfo {
- const char *name;
- const struct tvec_flag *fv;
- const struct tvec_urange *range;
+ /* Information about a flags type. */
+
+ const char *name; /* type name for diagnostics */
+ const struct tvec_flag *fv; /* name/mask/value mappings */
+ const struct tvec_urange *range; /* permitted range for literals */
};
+/* --- @tvec_claimeq_flags@, @TVEC_CLAIMEQ_FLAGS@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const struct tvec_flaginfo *fi@ = flags type info
+ * @unsigned long f0, f1@ = two values
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @f0@ and @f1@ are equal, otherwise zero.
+ *
+ * Use: Check that values of @f0@ and @f1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @f0@ is printed as the output
+ * value and @f1@ is printed as the input reference.
+ *
+ * The @TVEC_CLAIM_FLAGS@ macro is similar, only it (a)
+ * identifies the file and line number of the call site
+ * automatically, and (b) implicitly quotes the source text of
+ * the @f0@ and @f1@ arguments in the failure message.
+ */
+
extern int tvec_claimeq_flags(struct tvec_state */*tv*/,
const struct tvec_flaginfo */*fi*/,
unsigned long /*f0*/, unsigned long /*f1*/,
(tvec_claimeq_flags(tv, fi, f0, f1, \
__FILE__, __LINE__, #f0 " /= " #f1))
+/*----- Character type ----------------------------------------------------*/
+
+/* A character value holds a character, as read by @fgetc@. The special
+ * @EOF@ value can also be represented.
+ *
+ * On input, a character value can be given by name, with a leading `%|#|%';
+ * or a character or `%|\|%'-escape sequence, optionally in single quotes.
+ *
+ * The following escape sequences and character names are recognized.
+ *
+ * * `%|#eof|%' is the special end-of-file marker.
+ *
+ * * `%|#nul|%' is the NUL character, sometimes used to terminate strings.
+ *
+ * * `%|bell|%', `%|bel|%', `%|ding|%', or `%|\a|%' is the BEL character
+ * used to ring the terminal bell (or do some other thing to attract the
+ * user's attention).
+ *
+ * * %|#backspace|%, %|#bs|%, or %|\b|% is the backspace character, used to
+ * move the cursor backwords by one cell.
+ *
+ * * %|#escape|% %|#esc|%, or%|\e|% is the escape character, used to
+ * introduce special terminal commands.
+ *
+ * * %|#formfeed|%, %|#ff|%, or %|\f|% is the formfeed character, used to
+ * separate pages of text.
+ *
+ * * %|#newline|%, %|#linefeed|%, %|#lf|%, %|#nl|%, or %|\n|% is the
+ * newline character, used to terminate lines of text or advance the
+ * cursor to the next line (perhaps without returning it to the start of
+ * the line).
+ *
+ * * %|#return|%, %|#carriage-return|%, %|#cr|%, or %|\r|% is the
+ * carriage-return character, used to return the cursor to the start of
+ * the line.
+ *
+ * * %|#tab|%, %|#horizontal-tab|%, %|#ht|%, or %|\t|% is the tab
+ * character, used to advance the cursor to the next tab stop on the
+ * current line.
+ *
+ * * %|#vertical-tab|%, %|#vt|%, %|\v|% is the vertical tab character.
+ *
+ * * %|#space|%, %|#spc|% is the space character.
+ *
+ * * %|#delete|%, %|#del|% is the delete character, used to erase the most
+ * recent character.
+ *
+ * * %|\'|% is the single-quote character.
+ *
+ * * %|\\|% is the backslash character.
+ *
+ * * %|\"|% is the double-quote character.
+ *
+ * * %|\NNN|% or %|\{NNN}|% is the character with code NNN in octal. The
+ * NNN may be up to three digits long.
+ *
+ * * %|\xNN|% or %|\x{NN}|% is the character with code NNN in hexadecimal.
+ */
+
extern const struct tvec_regty tvty_char;
+
+/* --- @tvec_claimeq_char@, @TVEC_CLAIMEQ_CHAR@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @int ch0, ch1@ = two character codes
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @ch0@ and @ch1@ are equal, otherwise zero.
+ *
+ * Use: Check that values of @ch0@ and @ch1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @ch0@ is printed as the output
+ * value and @ch1@ is printed as the input reference.
+ *
+ * The @TVEC_CLAIM_CHAR@ macro is similar, only it (a)
+ * identifies the file and line number of the call site
+ * automatically, and (b) implicitly quotes the source text of
+ * the @ch0@ and @ch1@ arguments in the failure message.
+ */
+
extern int tvec_claimeq_char(struct tvec_state */*tv*/,
int /*ch0*/, int /*ch1*/,
const char */*file*/, unsigned /*lno*/,
#define TVEC_CLAIMEQ_CHAR(tv, c0, c1) \
(tvec_claimeq_char(tv, c0, c1, __FILE__, __LINE__, #c0 " /= " #c1))
+/*----- Text and binary string types --------------------------------------*/
+
+/* A string is a sequence of octets. Text and binary strings differ
+ * primarily in presentation: text strings are shown as raw characters where
+ * possible; binary strings are shown as hex dumps with an auxiliary text
+ * display.
+ *
+ * The input format for both kinds of strings is basically the same: a
+ * `compound string', consisting of
+ *
+ * * single-quoted strings, which are interpreted entirely literally, but
+ * can't contain single quotes or newlines;
+ *
+ * * double-quoted strings, in which `%|\|%'-escapes are interpreted as for
+ * characters;
+ *
+ * * character names, marked by an initial `%|#|%' sign;
+ *
+ * * special tokens marked by an initial `%|!|%' sign; or
+ *
+ * * barewords interpreted according to the current coding scheme.
+ *
+ * The special tokens are
+ *
+ * * `%|!bare|%', which causes subsequent sequences of barewords to be
+ * treated as plain text;
+ *
+ * * `%|!hex|%', `%|!base32|%', `%|!base64|%', which cause subsequent
+ * barewords to be decoded in the requested manner.
+ *
+ * * `%|!repeat|% %$n$% %|{|% %%\textit{string}%% %|}|%', which includes
+ * %$n$% copies of the (compound) string.
+ *
+ * Either kind of string can contain internal nul characters. A trailing nul
+ * is appended -- beyond the stated input length -- to input strings as a
+ * convenience to test functions. Test functions may include such a nul
+ * character on output but this is not checked by the equality test.
+ *
+ * A @struct tvec_urange@ may be supplied as an argument: the length of the
+ * string (in bytes) will be checked against the permitted range.
+ */
+
extern const struct tvec_regty tvty_string, tvty_bytes;
+/* --- @tvec_claimeq_string@, @TVEC_CLAIMEQ_STRING@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *p0@, @size_t sz0@ = first string with length
+ * @const char *p1@, @size_t sz1@ = second string with length
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
+ * zero.
+ *
+ * Use: Check that strings at @p0@ and @p1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @p0@ is printed as the output
+ * value and @p1@ is printed as the input reference.
+ *
+ * The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
+ * identifies the file and line number of the call site
+ * automatically, and (b) implicitly quotes the source text of
+ * the @ch0@ and @ch1@ arguments in the failure message.
+ */
+
extern int tvec_claimeq_string(struct tvec_state */*tv*/,
const char */*p0*/, size_t /*sz0*/,
const char */*p1*/, size_t /*sz1*/,
const char */*file*/, unsigned /*lno*/,
const char */*expr*/);
+#define TVEC_CLAIMEQ_STRING(tv, p0, sz0, p1, sz1) \
+ (tvec_claimeq_string(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
+ #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
+
+/* --- @tvec_claimeq_strz@, @TVEC_CLAIMEQ_STRZ@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *p0, *p1@ = two strings to compare
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
+ * zero.
+ *
+ * Use: Check that strings at @p0@ and @p1@ are equal, as for
+ * @tvec_claimeq_string@, except that the strings are assumed
+ * null-terminated, so their lengths don't need to be supplied
+ * explicitly. The macro is similarly like
+ * @TVEC_CLAIMEQ_STRING@.
+ */
+
extern int tvec_claimeq_strz(struct tvec_state */*tv*/,
const char */*p0*/, const char */*p1*/,
const char */*file*/, unsigned /*lno*/,
const char */*expr*/);
+#define TVEC_CLAIMEQ_STRZ(tv, p0, p1) \
+ (tvec_claimeq_strz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
+
+/* --- @tvec_claimeq_bytes@, @TVEC_CLAIMEQ_BYTES@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const void *p0@, @size_t sz0@ = first string with length
+ * @const void *p1@, @size_t sz1@ = second string with length
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
+ * zero.
+ *
+ * Use: Check that binary strings at @p0@ and @p1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @p0@ is printed as the output
+ * value and @p1@ is printed as the input reference.
+ *
+ * The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
+ * identifies the file and line number of the call site
+ * automatically, and (b) implicitly quotes the source text of
+ * the @ch0@ and @ch1@ arguments in the failure message.
+ */
+
extern int tvec_claimeq_bytes(struct tvec_state */*tv*/,
const void */*p0*/, size_t /*sz0*/,
const void */*p1*/, size_t /*sz1*/,
const char */*file*/, unsigned /*lno*/,
const char */*expr*/);
-#define TVEC_CLAIMEQ_STRING(tv, p0, sz0, p1, sz1) \
- (tvec_claimeq_string(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
- #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
-#define TVEC_CLAIMEQ_STRZ(tv, p0, p1) \
- (tvec_claimeq_strz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
#define TVEC_CLAIMEQ_BYTES(tv, p0, sz0, p1, sz1) \
(tvec_claimeq(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
#p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
-extern const struct tvec_regty tvty_buffer;
+/* --- @tvec_allocstring@, @tvec_allocbytes@ --- *
+ *
+ * Arguments: @union tvec_regval *rv@ = register value
+ * @size_t sz@ = required size
+ *
+ * Returns: ---
+ *
+ * Use: Allocated space in a text or binary string register. If the
+ * current register size is sufficient, its buffer is left
+ * alone; otherwise, the old buffer, if any, is freed and a
+ * fresh buffer allocated. These functions are not intended to
+ * be used to adjust a buffer repeatedly, e.g., while building
+ * output incrementally: (a) they will perform badly, and (b)
+ * the old buffer contents are simply discarded if reallocation
+ * is necessary. Instead, use a @dbuf@ or @dstr@.
+ *
+ * The @tvec_allocstring@ function sneakily allocates an extra
+ * byte for a terminating zero. The @tvec_allocbytes@ function
+ * doesn't do this.
+ */
extern void tvec_allocstring(union tvec_regval */*rv*/, size_t /*sz*/);
extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);
-/*----- Benchmarking ------------------------------------------------------*/
-
-struct tvec_bench {
- struct tvec_env _env; /* benchmarking is an environment */
- struct bench_state **bst; /* benchmark state anchor or null */
- unsigned long niter; /* iterations done per unit */
- int riter, rbuf; /* iterations and buffer registers */
- const struct tvec_env *env; /* environment (per test, not grp) */
-};
-#define TVEC_BENCHENV \
- { sizeof(struct tvec_benchctx), \
- tvec_benchsetup, \
- tvec_benchset, \
- tvec_benchbefore, \
- tvec_benchrun, \
- tvec_benchafter, \
- tvec_benchteardown }
-#define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate
-
-struct tvec_benchctx {
- const struct tvec_bench *b;
- struct bench_state *bst;
- double dflt_target;
- void *subctx;
-};
-
-extern struct bench_state *tvec_benchstate;
-
-extern int tvec_benchsetup(struct tvec_state */*tv*/,
- const struct tvec_env */*env*/,
- void */*pctx*/, void */*ctx*/);
-extern int tvec_benchset(struct tvec_state */*tv*/, const char */*var*/,
- const struct tvec_env */*env*/, void */*ctx*/);
-extern int tvec_benchbefore(struct tvec_state */*tv*/, void */*ctx*/);
-extern void tvec_benchrun(struct tvec_state */*tv*/,
- tvec_testfn */*fn*/, void */*ctx*/);
-extern void tvec_benchafter(struct tvec_state */*tv*/, void */*ctx*/);
-extern void tvec_benchteardown(struct tvec_state */*tv*/, void */*ctx*/);
-
-extern void tvec_benchreport
- (const struct gprintf_ops */*gops*/, void */*go*/,
- unsigned /*unit*/, const struct bench_timing */*tm*/);
-
-/*----- Command-line interface --------------------------------------------*/
-
-extern const struct tvec_config tvec_adhocconfig;
-
-extern void tvec_parseargs(int /*argc*/, char */*argv*/[],
- struct tvec_state */*tv_out*/,
- int */*argpos_out*/,
- const struct tvec_config */*config*/);
-
-extern int tvec_readstdin(struct tvec_state */*tv*/);
-extern int tvec_readfile(struct tvec_state */*tv*/, const char */*file*/);
-extern int tvec_readdflt(struct tvec_state */*tv*/, const char */*file*/);
-extern int tvec_readarg(struct tvec_state */*tv*/, const char */*arg*/);
+/*----- Buffer type -------------------------------------------------------*/
-extern int tvec_readargs(int /*argc*/, char */*argv*/[],
- struct tvec_state */*tv*/,
- int */*argpos_inout*/, const char */*dflt*/);
+/* Buffer registers are primarily used for benchmarking. Only a buffer's
+ * size is significant: its contents are ignored on comparison and output,
+ * and unspecified on input.
+ *
+ * The input is simply the buffer size, as an integer, optionally suffixed
+ * with a unit `kB', `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or
+ * without the `B') denoting a power of 1024. Units are used on output only
+ * when the size would be expressed exactly.
+ */
-extern int tvec_main(int /*argc*/, char */*argv*/[],
- const struct tvec_config */*config*/,
- const char */*dflt*/);
+extern const struct tvec_regty tvty_buffer;
/*----- That's all, folks -------------------------------------------------*/
~mdw / mLib / blobdiff