+ 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@ --- *
+ *
~mdw / mLib / blobdiff