3 * Test vector processing framework
5 * (c) 2023 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of the mLib utilities library.
12 * mLib is free software: you can redistribute it and/or modify it under
13 * the terms of the GNU Library General Public License as published by
14 * the Free Software Foundation; either version 2 of the License, or (at
15 * your option) any later version.
17 * mLib is distributed in the hope that it will be useful, but WITHOUT
18 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
20 * License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with mLib. If not, write to the Free Software
24 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
35 /* Here's the overall flow for a testing session.
38 * -> output @bsession@
43 * -> type @init@ (input and output)
44 * -> type @parse@ (input)
48 * -> output @skipgroup@
83 * -> output @skipgroup@
88 * -> output @esession@
92 * -> type @dump@ (compact style)
97 * -> @tvec_benchreport@
99 * The output functions @error@ and @notice@ can be called at arbitrary
103 /*----- Header files ------------------------------------------------------*/
114 #ifndef MLIB_CONTROL_H
115 # include "control.h"
122 #ifndef MLIB_GPRINTF_H
123 # include "gprintf.h"
130 #ifndef MLIB_MACROS_H
134 /*----- Miscellaneous values ----------------------------------------------*/
136 /* These are attached to structures which represent extension points, as a
137 * way to pass an opaque parameter to whatever things are hooked onto them.
140 #define TVEC_MISCSLOTS(_) \
141 _(PTR, const void *, p) /* arbitrary pointer */ \
142 _(INT, long, i) /* signed integer */ \
143 _(UINT, unsigned long, u) /* signed integer */ \
144 _(FLT, double, f) /* floating point */
147 #define TVEC_DEFSLOT(tag, ty, slot) ty slot;
148 TVEC_MISCSLOTS(TVEC_DEFSLOT)
152 #define TVEC_DEFCONST(tag, ty, slot) TVMISC_##tag,
153 TVEC_MISCSLOTS(TVEC_DEFCONST)
157 /*----- Register values ---------------------------------------------------*/
159 /* The framework doesn't have a preconceived idea about what's in a register
160 * value: it just allocates them and accesses them through the register type
161 * functions. It doesn't even have a baked-in idea of how big a register
162 * value is: instead, it gets that via the `regsz' slot in `struct
163 * tvec_testinfo'. So, as far as the framework is concerned, it's safe to
164 * add new slots to this union, even if they make the overall union larger.
165 * This can be done by defining the preprocessor macro `TVEC_REGSLOTS' to be
166 * a `union' fragment defining any additional union members.
168 * This creates a distinction between code which does and doesn't know the
169 * size of a register value. Code which does, which typically means the test
170 * functions, benchmarking setup and teardown functions, and tightly-bound
171 * runner functions, is free to index the register vectors directly. Code
172 * which doesn't, which means the framework core itself and output formatting
173 * machinery, must use the `TVEC_REG' macro (or its more general `TVEC_GREG'
174 * companion) for indexing register vectors. (In principle, register type
175 * handlers also fit into this category, but they have no business peering
176 * into register values other than the one's they're given.)
180 /* The actual register value. This is what the type handler sees.
181 * Additional members can be added by setting `TVEC_REGSLOTS' before
182 * including this file.
184 * A register value can be /initialized/, which simply means that its
185 * contents represent a valid value according to its type -- the
186 * register can be compared, dumped, serialized, parsed into, etc.
187 * You can't do anything safely to an uninitialized register value
188 * other than initialize it.
191 long i; /* signed integer */
192 unsigned long u; /* unsigned integer */
193 void *p; /* pointer */
194 double f; /* floating point */
195 struct { unsigned char *p; size_t sz; } bytes; /* binary string of bytes */
196 struct { char *p; size_t sz; } str; /* text string */
205 * Note that all of the registers listed as being used by a
206 * particular test group are initialized at all times[1] while that
207 * test group is being processed. (The other register slots don't
208 * even have types associated with them, so there's nothing useful we
209 * could do with them.)
211 * The `TVRF_LIVE' flag indicates that the register was assigned a
212 * value by the test vector file: it's the right thing to use to
213 * check whether an optional register is actually present. Even
214 * `dead' registers are still initialized, though.
216 * [1] This isn't quite true. Between individual tests, the
217 * registers are released and reinitialized in order to reset
218 * them to known values ready for the next test. But you won't
219 * see them at this point.
222 unsigned f; /* flags */
223 #define TVRF_LIVE 1u /* used in current test */
224 union tvec_regval v; /* register value */
228 /* A register definition. Register definitions list the registers
229 * which are used by a particular test group (see `struct tvec_test'
232 * A vector of register definitions is terminated by a definition
233 * whose `name' slot is null.
236 const char *name; /* register name (for input files) */
237 unsigned i; /* register index */
238 const struct tvec_regty *ty; /* register type descriptor */
239 unsigned f; /* flags */
240 #define TVRF_OPT 1u /* optional register */
241 #define TVRF_ID 2u /* part of test identity */
242 union tvec_misc arg; /* extra detail for the type */
244 #define TVEC_ENDREGS { 0, 0, 0, 0, { 0 } }
246 /* @TVEC_GREG(vec, i, regsz)@
248 * If @vec@ is a data pointer which happens to contain the address of a
249 * vector of @struct tvec_reg@ objects, @i@ is an integer, and @regsz@ is the
250 * size of a @struct tvec_reg@, then this evaluates to the address of the
251 * @i@th element of the vector.
253 * This is the general tool you need for accessing register vectors when you
254 * don't have absolute knowledge of the size of a @union tvec_regval@.
255 * Usually you want to access one of the register vectors in a @struct
256 * tvec_state@, and @TVEC_REG@ will be more convenient.
258 #define TVEC_GREG(vec, i, regsz) \
259 ((struct tvec_reg *)((unsigned char *)(vec) + (i)*(regsz)))
261 /*----- Register types ----------------------------------------------------*/
263 struct tvec_state; /* forward declaration */
266 /* A register type. */
268 void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
269 /* Initialize the value in @*rv@. This will be called before any
270 * other function acting on the value, including @release@.
273 void (*release)(union tvec_regval */*rv*/,
274 const struct tvec_regdef */*rd*/);
275 /* Release any resources associated with the value in @*rv@. */
277 int (*eq)(const union tvec_regval */*rv0*/,
278 const union tvec_regval */*rv1*/,
279 const struct tvec_regdef */*rd*/);
280 /* Return nonzero if @*rv0@ and @*rv1@ are equal values.
281 * Asymmetric criteria are permitted: @tvec_checkregs@ calls @eq@
282 * with the input register as @rv0@ and the output as @rv1@.
285 int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
286 const struct tvec_regdef */*rd*/);
287 /* Serialize the value @*rv@, writing the result to @b@. Return
288 * zero on success, or @-1@ on error.
291 int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
292 const struct tvec_regdef */*rd*/);
293 /* Deserialize a value from @b@, storing it in @*rv@. Return zero on
294 * success, or @-1@ on error.
297 int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
298 struct tvec_state */*tv*/);
299 /* Parse a value from @tv->fp@, storing it in @*rv@. Return zero on
300 * success, or @-1@ on error, having reported one or more errors via
301 * @tvec_error@ or @tvec_syntax@. A successful return should leave
302 * the input position at the start of the next line; the caller will
303 * flush the remainder of the line itself.
306 void (*dump)(const union tvec_regval */*rv*/,
307 const struct tvec_regdef */*rd*/,
309 const struct gprintf_ops */*gops*/, void */*go*/);
310 #define TVSF_COMPACT 1u
311 /* Write a human-readable representation of the value @*rv@ using
312 * @gprintf@ on @gops@ and @go@. The @style@ is a collection of
313 * flags: if @TVSF_COMPACT@ is set, then output should be minimal,
314 * and must fit on a single line; otherwise, output may consist of
315 * multiple lines and may contain redundant information if that is
316 * likely to be useful to a human reader.
320 /*----- Test descriptions -------------------------------------------------*/
322 typedef void tvec_testfn(const struct tvec_reg */*in*/,
323 struct tvec_reg */*out*/,
325 /* A test function. It should read inputs from @in@ and write outputs to
326 * @out@. The @TVRF_LIVE@ is set on inputs which are actually present, and
327 * on outputs which are wanted to test. A test function can set additional
328 * `gratuitous outputs' by setting @TVRF_LIVE@ on them; clearing
329 * @TVRF_LIVE@ on a wanted output causes a mismatch.
331 * A test function may be called zero or more times by the environment. In
332 * particular, it may be called multiple times, though usually by prior
333 * arrangement with the environment.
335 * The @ctx@ is supplied by the environment's @run@ function (see below).
336 * The default environment calls the test function once, with a null
337 * @ctx@. There is no expectation that the environment's context has
338 * anything to do with the test function's context.
343 typedef void tvec_envsetupfn(struct tvec_state */*tv*/,
344 const struct tvec_env */*env*/,
345 void */*pctx*/, void */*ctx*/);
346 /* Initialize the context; called at the start of a test group; @pctx@ is
347 * null for environments called by the core, but may be non-null for
348 * subordinate environments. If setup fails, the function should call
349 * @tvec_skipgroup@ with a suitable excuse. The @set@ and @teardown@ entry
350 * points will still be called, but @before@, @run@, and @after@ will not.
353 typedef int tvec_envsetfn(struct tvec_state */*tv*/, const char */*var*/,
354 const struct tvec_env */*env*/, void */*ctx*/);
355 /* Called when the parser finds a %|@var|%' setting to parse and store the
356 * value. If @setup@ failed, this is still called (so as to skip the
357 * value), but @ctx@ is null.
360 typedef void tvec_envbeforefn(struct tvec_state */*tv*/, void */*ctx*/);
361 /* Called prior to running a test. This is the right place to act on any
362 * `%|@var|%' settings. If preparation fails, the function should call
363 * @tvec_skip@ with a suitable excuse. This function is never called if
364 * the test group is skipped.
367 typedef void tvec_envrunfn(struct tvec_state */*tv*/,
368 tvec_testfn */*fn*/, void */*ctx*/);
369 /* Run the test. It should either call @tvec_skip@, or run @fn@ one or
370 * more times. In the latter case, it is responsible for checking the
371 * outputs, and calling @tvec_fail@ as necessary; @tvec_checkregs@ will
372 * check the register values against the supplied test vector, while
373 * @tvec_check@ does pretty much everything necessary. This function is
374 * never called if the test group is skipped.
377 typedef void tvec_envafterfn(struct tvec_state */*tv*/, void */*ctx*/);
378 /* Called after running or skipping a test. Typical actions involve
379 * resetting whatever things were established by @set@. This function is
380 * never called if the test group is skipped.
383 typedef void tvec_envteardownfn(struct tvec_state */*tv*/, void */*ctx*/);
384 /* Tear down the environment: called at the end of a test group. */
388 /* A test environment sets things up for and arranges to run the test.
390 * The caller is responsible for allocating storage for the environment's
391 * context, based on the @ctxsz@ slot, and freeing it later; this space is
392 * passed in as the @ctx@ parameter to the remaining functions; if @ctxsz@
393 * is zero then @ctx@ is null.
396 size_t ctxsz; /* environment context size */
398 tvec_envsetupfn *setup; /* setup for group */
399 tvec_envsetfn *set; /* set variable */
400 tvec_envbeforefn *before; /* prepare for test */
401 tvec_envrunfn *run; /* run test function */
402 tvec_envafterfn *after; /* clean up after test */
403 tvec_envteardownfn *teardown; /* tear down after group */
407 /* A test description. */
409 const char *name; /* name of the test */
410 const struct tvec_regdef *regs; /* descriptions of the registers */
411 const struct tvec_env *env; /* environment to run test in */
412 tvec_testfn *fn; /* test function */
414 #define TVEC_ENDTESTS { 0, 0, 0, 0 }
417 /* Register output dispositions. */
419 TVRD_INPUT, /* input-only register */
420 TVRD_OUTPUT, /* output-only (input is dead) */
421 TVRD_MATCH, /* matching (equal) registers */
422 TVRD_FOUND, /* mismatching output register */
423 TVRD_EXPECT, /* mismatching input register */
424 TVRD_LIMIT /* (number of dispositions) */
427 /*----- Test state --------------------------------------------------------*/
430 /* Possible test outcomes. */
432 TVOUT_LOSE, /* test failed */
433 TVOUT_SKIP, /* test skipped */
434 TVOUT_WIN, /* test passed */
435 TVOUT_XFAIL, /* test passed, but shouldn't have */
436 TVOUT_LIMIT /* (number of possible outcomes) */
440 /* The primary state structure for the test vector machinery. */
442 unsigned f; /* flags */
443 #define TVSF_SKIP 0x0001u /* skip this test group */
444 #define TVSF_OPEN 0x0002u /* test is open */
445 #define TVSF_ACTIVE 0x0004u /* test is active */
446 #define TVSF_ERROR 0x0008u /* an error occurred */
447 #define TVSF_OUTMASK 0x00f0u /* test outcome (@TVOUT_...@) */
448 #define TVSF_OUTSHIFT 4 /* shift applied to outcome */
449 #define TVSF_XFAIL 0x0100u /* test expected to fail */
451 /* Registers. Available to execution environments. */
452 unsigned nrout, nreg; /* number of output/total registers */
453 size_t regsz; /* size of register entry */
454 struct tvec_reg *in, *out; /* register vectors */
456 /* Test groups state. Available to output formatters. */
457 const struct tvec_test *tests, *test; /* all tests and current test */
459 /* Test scoreboard. Available to output formatters. */
460 unsigned curr[TVOUT_LIMIT], all[TVOUT_LIMIT], grps[TVOUT_LIMIT];
462 /* Output machinery. */
463 struct tvec_output *output; /* output formatter */
465 /* Input machinery. Available to type parsers. */
466 const char *infile; unsigned lno, test_lno; /* input file name, line */
467 FILE *fp; /* input file stream */
470 /* @TVEC_REG(tv, vec, i)@
472 * If @tv@ is a pointer to a @struct tvec_state@, @vec@ is either @in@ or
473 * @out@, and @i@ is an integer, then this evaluates to the address of the
474 * @i@th register in the selected vector.
476 #define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->regsz)
479 /* An overall test configuration. */
481 const struct tvec_test *tests; /* the tests to be performed */
482 unsigned nrout, nreg; /* number of output/total regs */
483 size_t regsz; /* size of a register */
486 /*----- Output formatting -------------------------------------------------*/
489 /* An output formatter. */
490 const struct tvec_outops *ops; /* pointer to operations */
493 /* Benchmarking details. */
495 TVBU_OP, /* counting operations of some kind */
496 TVBU_BYTE, /* counting bytes (@rbuf >= 0@) */
497 TVBU_LIMIT /* (number of units) */
499 struct bench_timing; /* forward declaration */
502 /* Output operations. */
504 void (*bsession)(struct tvec_output */*o*/, struct tvec_state */*tv*/);
505 /* Begin a test session. The output driver will probably want to
506 * save @tv@, because this isn't provided to any other methods.
509 int (*esession)(struct tvec_output */*o*/);
510 /* End a session, and return the suggested exit code. */
512 void (*bgroup)(struct tvec_output */*o*/);
513 /* Begin a test group. The test group description is @tv->test@. */
515 void (*skipgroup)(struct tvec_output */*o*/,
516 const char */*excuse*/, va_list */*ap*/);
517 /* The group is being skipped; @excuse@ may be null or a format
518 * string explaining why. The @egroup@ method will not be called
522 void (*egroup)(struct tvec_output */*o*/);
523 /* End a test group. At least one test was attempted or @skipgroup@
524 * would have been called instead. If @tv->curr[TVOUT_LOSE]@ is
525 * nonzero then the test group as a whole failed; otherwise it
529 void (*btest)(struct tvec_output */*o*/);
530 /* Begin a test case. */
532 void (*skip)(struct tvec_output */*o*/,
533 const char */*excuse*/, va_list */*ap*/);
534 /* The test case is being skipped; @excuse@ may be null or a format
535 * string explaining why. The @etest@ function will still be called
536 * (so this works differently from @skipgroup@ and @egroup@). A test
537 * case can be skipped at most once, and, if skipped, it cannot fail.
540 void (*fail)(struct tvec_output */*o*/,
541 const char */*detail*/, va_list */*ap*/);
542 /* The test case failed.
544 * The output driver should preferably report the filename (@infile@)
545 * and line number (@test_lno@, not @lno@) for the failing test.
547 * The @detail@ may be null or a format string describing detail
548 * about how the failing test was run which can't be determined from
549 * the registers; a @detail@ is usually provided when (and only when)
550 * the test environment potentially invokes the test function more
553 * A single test case can fail multiple times!
556 void (*dumpreg)(struct tvec_output */*o*/,
557 unsigned /*disp*/, const union tvec_regval */*rv*/,
558 const struct tvec_regdef */*rd*/);
559 /* Dump a register. The `disposition' @disp@ explains what condition
560 * the register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes.
561 * The register value is at @rv@, and its definition, including its
562 * type, at @rd@. Note that this function may be called on virtual
563 * registers which aren't in either of the register vectors or
564 * mentioned by the test description. It may also be called with
565 * @rv@ null, indicating that the register is not live.
568 void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/);
569 /* The test case concluded with the given @outcome@ (one of the
573 void (*bbench)(struct tvec_output */*o*/,
574 const char */*ident*/, unsigned /*unit*/);
575 /* Begin a benchmark. The @ident@ is a formatted string identifying
576 * the benchmark based on the values of the input registered marked
577 * @TVRF_ID@; the output driver is free to use this or come up with
578 * its own way to identify the test, e.g., by inspecting the register
579 * values for itself. The @unit@ is one of the @TVBU_...@ constants
580 * explaining what sort of thing is being measured.
583 void (*ebench)(struct tvec_output */*o*/,
584 const char */*ident*/, unsigned /*unit*/,
585 const struct bench_timing */*tm*/);
586 /* End a benchmark. The @ident@ and @unit@ arguments are as for
587 * @bbench@. If @tm@ is zero then the measurement failed; otherwise
588 * @tm->n@ counts total number of things (operations or bytes, as
589 * indicated by @unit@) processed in the indicated time.
592 void (*report)(struct tvec_output */*o*/, unsigned /*level*/,
593 const char */*msg*/, va_list */*ap*/);
594 /* Report a message. The driver should ideally report the filename
595 * (@infile@) and line number (@lno@) prompting the error.
598 void (*destroy)(struct tvec_output */*o*/);
599 /* Release any resources acquired by the driver. */
603 TVLEV_NOTE = 4, /* notice */
604 TVLEV_ERR = 8 /* error */
607 /*----- Session lifecycle -------------------------------------------------*/
609 /* --- @tvec_begin@ --- *
611 * Arguments: @struct tvec_state *tv_out@ = state structure to fill in
612 * @const struct tvec_config *config@ = test configuration
613 * @struct tvec_output *o@ = output driver
617 * Use: Initialize a state structure ready to do some testing.
620 extern void tvec_begin(struct tvec_state */*tv_out*/,
621 const struct tvec_config */*config*/,
622 struct tvec_output */*o*/);
624 /* --- @tvec_end@ --- *
626 * Arguments: @struct tvec_state *tv@ = test-vector state
628 * Returns: A proposed exit code.
630 * Use: Conclude testing and suggests an exit code to be returned to
631 * the calling program. (The exit code comes from the output
632 * driver's @esession@ method.)
635 extern int tvec_end(struct tvec_state */*tv*/);
637 /* --- @tvec_read@ --- *
639 * Arguments: @struct tvec_state *tv@ = test-vector state
640 * @const char *infile@ = the name of the input file
641 * @FILE *fp@ = stream to read from
643 * Returns: Zero on success, @-1@ on error.
645 * Use: Read test vector data from @fp@ and exercise test functions.
646 * THe return code doesn't indicate test failures: it's only
647 * concerned with whether there were problems with the input
648 * file or with actually running the tests.
651 extern int tvec_read(struct tvec_state */*tv*/,
652 const char */*infile*/, FILE */*fp*/);
654 /*----- Command-line interface --------------------------------------------*/
656 extern const struct tvec_config tvec_adhocconfig;
657 /* A special @struct tvec_config@ to use for programs which perform ad-hoc
661 /* --- @tvec_parseargs@ --- *
663 * Arguments: @int argc@ = number of command-line arguments
664 * @char *argv[]@ = vector of argument strings
665 * @struct tvec_state *tv_out@ = test vector state to initialize
666 * @int *argpos_out@ = where to leave unread argument index
667 * @const struct tvec_config *cofig@ = test vector configuration
671 * Use: Parse arguments and set up the test vector state @*tv_out@.
672 * If errors occur, print messages to standard error and exit
676 extern void tvec_parseargs(int /*argc*/, char */*argv*/[],
677 struct tvec_state */*tv_out*/,
679 const struct tvec_config */*config*/);
681 /* --- @tvec_readstdin@, @tvec_readfile@, @tvec_readarg@ --- *
683 * Arguments: @struct tvec_state *tv@ = test vector state
684 * @const char *file@ = pathname of file to read
685 * @const char *arg@ = argument to interpret
687 * Returns: Zero on success, @-1@ on error.
689 * Use: Read test vector data from stdin or a named file. The
690 * @tvec_readarg@ function reads from stdin if @arg@ is `%|-|%',
691 * and from the named file otherwise.
694 extern int tvec_readstdin(struct tvec_state */*tv*/);
695 extern int tvec_readfile(struct tvec_state */*tv*/, const char */*file*/);
696 extern int tvec_readarg(struct tvec_state */*tv*/, const char */*arg*/);
698 /* --- @tvec_readdflt@ --- *
700 * Arguments: @struct tvec_state *tv@ = test vector state
701 * @const char *dflt@ = defsault filename or null
703 * Returns: Zero on success, @-1@ on error.
705 * Use: Reads from the default test vector data. If @file@ is null,
706 * then read from standard input, unless that's a terminal; if
707 * @file@ is not null, then read the named file, looking in the
708 * directory named by the `%|srcdir|%' environment variable if
709 * that's set, or otherwise in the current directory.
712 extern int tvec_readdflt(struct tvec_state */*tv*/, const char */*file*/);
714 /* --- @tvec_readargs@ --- *
716 * Arguments: @int argc@ = number of command-line arguments
717 * @char *argv[]@ = vector of argument strings
718 * @struct tvec_state *tv@ = test vector state
719 * @int *argpos_inout@ = current argument position (updated)
720 * @const char *dflt@ = default filename or null
722 * Returns: Zero on success, @-1@ on error.
724 * Use: Reads from the sources indicated by the command-line
725 * arguments, in order, interpreting each as for @tvec_readarg@;
726 * if no arguments are given then read from @dflt@ as for
730 extern int tvec_readargs(int /*argc*/, char */*argv*/[],
731 struct tvec_state */*tv*/,
732 int */*argpos_inout*/, const char */*dflt*/);
734 /* --- @tvec_main@ --- *
736 * Arguments: @int argc@ = number of command-line arguments
737 * @char *argv[]@ = vector of argument strings
738 * @const struct tvec_config *cofig@ = test vector configuration
739 * @const char *dflt@ = default filename or null
741 * Returns: Exit code.
743 * Use: All-in-one test vector front-end. Parse options from the
744 * command-line as for @tvec_parseargs@, and then process the
745 * remaining positional arguments as for @tvec_readargs@. The
746 * function constructs and disposes of a test vector state.
749 extern int tvec_main(int /*argc*/, char */*argv*/[],
750 const struct tvec_config */*config*/,
751 const char */*dflt*/);
753 /*----- Test processing ---------------------------------------------------*/
755 /* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- *
757 * Arguments: @struct tvec_state *tv@ = test-vector state
758 * @const char *excuse@, @va_list *ap@ = reason why skipped
762 * Use: Skip the current group. This should only be called from a
763 * test environment @setup@ function; a similar effect occurs if
764 * the @setup@ function fails.
767 extern void PRINTF_LIKE(2, 3)
768 tvec_skipgroup(struct tvec_state */*tv*/, const char */*excuse*/, ...);
769 extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
770 const char */*excuse*/, va_list */*ap*/);
772 /* --- @tvec_skip@, @tvec_skip_v@ --- *
774 * Arguments: @struct tvec_state *tv@ = test-vector state
775 * @const char *excuse@, @va_list *ap@ = reason why test skipped
779 * Use: Skip the current test. This should only be called from a
780 * test environment @run@ function; a similar effect occurs if
781 * the @before@ function fails.
784 extern void PRINTF_LIKE(2, 3)
785 tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
786 extern void tvec_skip_v(struct tvec_state */*tv*/,
787 const char */*excuse*/, va_list */*ap*/);
789 /* --- @tvec_resetoutputs@ --- *
791 * Arguments: @struct tvec_state *tv@ = test-vector state
795 * Use: Reset (releases and reinitializes) the output registers in
796 * the test state. This is mostly of use to test environment
797 * @run@ functions, between invocations of the test function.
800 extern void tvec_resetoutputs(struct tvec_state */*tv*/);
802 extern void tvec_initregs(struct tvec_state */*tv*/);
803 extern void tvec_releaseregs(struct tvec_state */*tv*/);
805 /* --- @tvec_checkregs@ --- *
807 * Arguments: @struct tvec_state *tv@ = test-vector state
809 * Returns: Zero on success, @-1@ on mismatch.
811 * Use: Compare the active output registers (according to the current
812 * test group definition) with the corresponding input register
813 * values. A mismatch occurs if the two values differ
814 * (according to the register type's @eq@ method), or if the
815 * input is live but the output is dead.
817 * This function only checks for a mismatch and returns the
818 * result; it takes no other action. In particular, it doesn't
819 * report a failure, or dump register values.
822 extern int tvec_checkregs(struct tvec_state */*tv*/);
824 /* --- @tvec_fail@, @tvec_fail_v@ --- *
826 * Arguments: @struct tvec_state *tv@ = test-vector state
827 * @const char *detail@, @va_list *ap@ = description of test
831 * Use: Report the current test as a failure. This function can be
832 * called multiple times for a single test, e.g., if the test
833 * environment's @run@ function invokes the test function
834 * repeatedly; but a single test that fails repeatedly still
835 * only counts as a single failure in the statistics. The
836 * @detail@ string and its format parameters can be used to
837 * distinguish which of several invocations failed; it can
838 * safely be left null if the test function is run only once.
841 extern void PRINTF_LIKE(2, 3)
842 tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...);
843 extern void tvec_fail_v(struct tvec_state */*tv*/,
844 const char */*detail*/, va_list */*ap*/);
846 /* --- @tvec_dumpreg@ --- *
848 * Arguments: @struct tvec_state *tv@ = test-vector state
849 * @unsigned disp@ = the register disposition (@TVRD_...@)
850 * @const union tvec_regval *tv@ = register value, or null
851 * @const struct tvec_regdef *rd@ = register definition
855 * Use: Dump a register value to the output. This is the lowest-
856 * level function for dumping registers, and calls the output
857 * formatter directly.
859 * Usually @tvec_mismatch@ is much more convenient. Low-level
860 * access is required for reporting `virtual' registers
861 * corresponding to test environment settings.
864 extern void tvec_dumpreg(struct tvec_state */*tv*/,
865 unsigned /*disp*/, const union tvec_regval */*rv*/,
866 const struct tvec_regdef */*rd*/);
868 /* --- @tvec_mismatch@ --- *
870 * Arguments: @struct tvec_state *tv@ = test-vector state
871 * @unsigned f@ = flags (@TVMF_...@)
875 * Use: Dumps registers suitably to report a mismatch. The flag bits
876 * @TVMF_IN@ and @TVF_OUT@ select input-only and output
877 * registers. If both are reset then nothing happens.
878 * Suppressing the output registers may be useful, e.g., if the
879 * test function crashed rather than returning outputs.
884 extern void tvec_mismatch(struct tvec_state */*tv*/, unsigned /*f*/);
886 /* --- @tvec_check@, @tvec_check_v@ --- *
888 * Arguments: @struct tvec_state *tv@ = test-vector state
889 * @const char *detail@, @va_list *ap@ = description of test
893 * Use: Check the register values, reporting a failure and dumping
894 * the registers in the event of a mismatch. This just wraps up
895 * @tvec_checkregs@, @tvec_fail@ and @tvec_mismatch@ in the
899 extern void PRINTF_LIKE(2, 3)
900 tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
901 extern void tvec_check_v(struct tvec_state */*tv*/,
902 const char */*detail*/, va_list */*ap*/);
904 /*----- Ad-hoc testing ----------------------------------------------------*/
906 /* --- @tvec_adhoc@ --- *
908 * Arguments: @struct tvec_state *tv@ = test-vector state
909 * @struct tvec_test *t@ = space for a test definition
913 * Use: Begin ad-hoc testing, i.e., without reading a file of
916 * The structure at @t@ will be used to record information about
917 * the tests underway, which would normally come from a static
918 * test definition. The other functions in this section assume
919 * that @tvec_adhoc@ has been called.
922 extern void tvec_adhoc(struct tvec_state */*tv*/, struct tvec_test */*t*/);
924 /* --- @tvec_begingroup@, @TVEC_BEGINGROUP@ --- *
926 * Arguments: @struct tvec_state *tv@ = test-vector state
927 * @const char *name@ = name for this test group
928 * @const char *file@, @unsigned @lno@ = calling file and line
932 * Use: Begin an ad-hoc test group with the given name. The @file@
933 * and @lno@ can be anything, but it's usually best if they
934 * refer to the source code performing the test: the macro
935 * @TVEC_BEGINGROUP@ does this automatically.
938 extern void tvec_begingroup(struct tvec_state */*tv*/, const char */*name*/,
939 const char */*file*/, unsigned /*lno*/);
940 #define TVEC_BEGINGROUP(tv, name) \
941 do tvec_begingroup(tv, name, __FILE__, __LINE__); while (0)
943 /* --- @tvec_endgroup@ --- *
945 * Arguments: @struct tvec_state *tv@ = test-vector state
949 * Use: End an ad-hoc test group. The statistics are updated and the
950 * outcome is reported to the output formatter.
953 extern void tvec_endgroup(struct tvec_state */*tv*/);
955 /* --- @TVEC_TESTGROUP@, @TVEC_TESTGROUP_TAG@ --- *
957 * Arguments: @tag@ = label-disambiguation tag
958 * @const struct tvec_state *tv = test-vector state
959 * @const char *name@ = test-group name
963 * Use: Control-structure macro: @TVEC_TESTGROUP(tv, name) stmt@
964 * establishes a test group with the given @name@ (attributing
965 * it to the source file and lie number), executes @stmt@, and
966 * ends the test group. If @stmt@ invokes @break@ then the test
967 * group is skipped. @TVEC_TESTGROUP_TAG@ is the same, with an
968 * additional @tag@ argument for use in higher-level macros.
971 #define TVEC_TESTGROUP_TAG(tag, tv, name) \
972 MC_WRAP(tag##__around, \
973 { TVEC_BEGINGROUP(tv, name); }, \
974 { tvec_endgroup(tv); }, \
975 { if (!((tv)->f&TVSF_SKIP)) tvec_skipgroup(tv, 0); \
976 tvec_endgroup(tv); })
977 #define TVEC_TESTGROUP(tv, name) TVEC_TESTGROUP_TAG(grp, tv, name)
979 /* --- @tvec_begintest@, @TVEC_BEGINTEST@ --- *
981 * Arguments: @struct tvec_state *tv@ = test-vector state
982 * @const char *file@, @unsigned @lno@ = calling file and line
986 * Use: Begin an ad-hoc test case. The @file@ and @lno@ can be
987 * anything, but it's usually best if they refer to the source
988 * code performing the test: the macro @TVEC_BEGINGROUP@ does
989 * this automatically.
992 extern void tvec_begintest(struct tvec_state */*tv*/,
993 const char */*file*/, unsigned /*lno*/);
994 #define TVEC_BEGINTEST(tv) \
995 do tvec_begintest(tv, __FILE__, __LINE__); while (0)
997 /* --- *tvec_endtest@ --- *
999 * Arguments: @struct tvec_state *tv@ = test-vector state
1003 * Use: End a ad-hoc test case, The statistics are updated and the
1004 * outcome is reported to the output formatter.
1007 extern void tvec_endtest(struct tvec_state */*tv*/);
1009 /* --- @TVEC_TEST@, @TVEC_TEST_TAG@ --- *
1011 * Arguments: @tag@ = label-disambiguation tag
1012 * @struct tvec_test *t@ = space for a test definition
1016 * Use: Control-structure macro: @TVEC_TEST(tv) stmt@ begins a test
1017 * case, executes @stmt@, and ends the test case. If @stmt@
1018 * invokes @break@ then the test case is skipped.
1019 * @TVEC_TEST_TAG@ is the same, with an additional @tag@ argumet
1020 * for use in higher-level macros.
1023 #define TVEC_TEST_TAG(tag, tv) \
1024 MC_WRAP(tag##__around, \
1025 { TVEC_BEGINTEST(tv); }, \
1026 { tvec_endtest(tv); }, \
1027 { if ((tv)->f&TVSF_ACTIVE) tvec_skip((tv), 0); \
1028 tvec_endtest(tv); })
1029 #define TVEC_TEST(tv) TVEC_TEST_TAG(test, tv)
1031 /* --- @tvec_claim@, @tvec_claim_v@, @TVEC_CLAIM@ --- *
1033 * Arguments: @struct tvec_state *tv@ = test-vector state
1035 * @const char *file@, @unsigned @lno@ = calling file and line
1036 * @const char *msg@, @va_list *ap@ = message to report on
1039 * Returns: The value @ok@.
1041 * Use: Check that a claimed condition holds, as (part of) a test.
1042 * If no test case is underway (i.e., if @TVSF_OPEN@ is reset in
1043 * @tv->f@), then a new test case is begun and ended. The
1044 * @file@ and @lno@ are passed to the output formatter to be
1045 * reported in case of a failure. If @ok@ is nonzero, then
1046 * nothing else happens; so, in particular, if @tvec_claim@
1047 * established a new test case, then the test case succeeds. If
1048 * @ok@ is zero, then a failure is reported, quoting @msg@.
1050 * The @TVEC_CLAIM@ macro is similar, only it (a) identifies the
1051 * file and line number of the call site automatically, and (b)
1052 * implicitly quotes the source text of the @ok@ condition in
1053 * the failure message.
1056 extern int PRINTF_LIKE(5, 6)
1057 tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
1058 const char */*file*/, unsigned /*lno*/,
1059 const char */*msg*/, ...);
1060 extern int tvec_claim_v(struct tvec_state */*tv*/, int /*ok*/,
1061 const char */*file*/, unsigned /*lno*/,
1062 const char */*msg*/, va_list */*ap*/);
1063 #define TVEC_CLAIM(tv, cond) \
1064 (tvec_claim(tv, !!(cond), __FILE__, __LINE__, "%s untrue", #cond))
1066 /* --- @tvec_claimeq@ --- *
1068 * Arguments: @struct tvec_state *tv@ = test-vector state
1069 * @const struct tvec_regty *ty@ = register type
1070 * @const union tvec_misc *arg@ = register type argument
1071 * @const char *file@, @unsigned @lno@ = calling file and line
1072 * @const char *expr@ = the expression to quote on failure
1074 * Returns: Nonzero if the input and output values of register 0 are
1075 * equal, zero if they differ.
1077 * Use: Check that the input and output values of register 0 are
1078 * equal (according to the register type @ty@). As for
1079 * @tvec_claim@ above, a test case is automatically begun and
1080 * ended if none is already underway. If the values are
1081 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1082 * mismatched values are dumped.
1084 * This function is not expected to be called directly, but
1085 * through type-specific wrapper functions or macros such as
1086 * @TVEC_CLAIMEQ_INT@.
1089 extern int tvec_claimeq(struct tvec_state */*tv*/,
1090 const struct tvec_regty */*ty*/,
1091 const union tvec_misc */*arg*/,
1092 const char */*file*/, unsigned /*lno*/,
1093 const char */*expr*/);
1095 /*----- Benchmarking ------------------------------------------------------*/
1097 struct tvec_benchenv {
1098 struct tvec_env _env; /* benchmarking is an environment */
1099 struct bench_state **bst; /* benchmark state anchor or null */
1100 unsigned long niter; /* iterations done per unit */
1101 int riter, rbuf; /* iterations and buffer registers */
1102 const struct tvec_env *env; /* subordinate environment */
1105 struct tvec_benchctx {
1106 const struct tvec_benchenv *be; /* environment configuration */
1107 struct bench_state *bst; /* benchmark state */
1108 double dflt_target; /* default time in seconds */
1109 void *subctx; /* subsidiary environment context */
1112 extern struct bench_state *tvec_benchstate;
1114 /* --- Environment implementation --- *
1116 * The following special variables are supported.
1118 * * %|@target|% is the (approximate) number of seconds to run the
1121 * Unrecognized variables are passed to the subordinate environment, if there
1122 * is one. Other events are passed through to the subsidiary environment.
1125 extern tvec_envsetupfn tvec_benchsetup;
1126 extern tvec_envsetfn tvec_benchset;
1127 extern tvec_envbeforefn tvec_benchbefore;
1128 extern tvec_envrunfn tvec_benchrun;
1129 extern tvec_envafterfn tvec_benchafter;
1130 extern tvec_envteardownfn tvec_benchteardown;
1132 #define TVEC_BENCHENV \
1133 { sizeof(struct tvec_benchctx), \
1139 tvec_benchteardown }
1140 #define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate
1142 /* --- @tvec_benchreport@ --- *
1144 * Arguments: @const struct gprintf_ops *gops@ = print operations
1145 * @void *go@ = print destination
1146 * @unsigned unit@ = the unit being measured (~TVBU_...@)
1147 * @const struct bench_timing *tm@ = the benchmark result
1151 * Use: Formats a report about the benchmark performance. This
1152 * function is intended to be called on by an output
1153 * @ebench@ function.
1156 extern void tvec_benchreport
1157 (const struct gprintf_ops */*gops*/, void */*go*/,
1158 unsigned /*unit*/, const struct bench_timing */*tm*/);
1160 /*----- Remote execution --------------------------------------------------*/
1162 struct tvec_remotecomms {
1163 int infd, outfd; /* input and output descriptors */
1164 dbuf bin, bout; /* input and output buffers */
1165 unsigned f; /* flags */
1166 #define TVRF_BROKEN 0x0001u /* communications have failed */
1167 /* bits 8--15 for upper layer */
1169 #define TVEC_REMOTECOMMS_INIT { -1, -1, DBUF_INIT, DBUF_INIT, 0 }
1171 struct tvec_remotectx {
1172 struct tvec_state *tv; /* test vector state */
1173 struct tvec_remotecomms rc; /* communication state */
1174 const struct tvec_remoteenv *re; /* environment configuration */
1175 unsigned ver; /* protocol version */
1176 pid_t kid; /* child process id */
1177 int errfd; /* child stderr descriptor */
1178 lbuf errbuf; /* child stderr line buffer */
1179 dstr prgwant, progress; /* progress: wanted/reported */
1180 unsigned exwant, exit; /* exit status wanted/reported */
1181 #define TVRF_RCNMASK 0x0300u /* reconnection behaviour: */
1182 #define TVRCN_SKIP 0x0000u /* skip unless connected */
1183 #define TVRCN_DEMAND 0x0100u /* connect on demand */
1184 #define TVRCN_FORCE 0x0200u /* force reconnection */
1185 #define TVRF_MUFFLE 0x0400u /* muffle child stderr */
1188 typedef int tvec_connectfn(pid_t */*kid_out*/, int */*infd_out*/,
1189 int */*outfd_out*/, int */*errfd_out*/,
1190 struct tvec_state */*tv*/,
1191 const struct tvec_remoteenv */*env*/);
1193 struct tvec_remoteenv_slots {
1194 tvec_connectfn *connect; /* connection function */
1195 const struct tvec_env *env; /* subsidiary environment */
1198 struct tvec_remoteenv {
1199 struct tvec_env _env;
1200 struct tvec_remoteenv_slots r;
1203 struct tvec_remotefork_slots {
1204 const struct tvec_test *tests; /* child tests (or null) */
1207 struct tvec_remotefork {
1208 struct tvec_env _env;
1209 struct tvec_remoteenv_slots r;
1210 struct tvec_remotefork_slots f;
1213 struct tvec_remoteexec_slots {
1214 const char *const *args; /* command line to execute */
1217 struct tvec_remoteexec {
1218 struct tvec_env _env;
1219 struct tvec_remoteenv_slots r;
1220 struct tvec_remoteexec_slots x;
1223 union tvec_remoteenv_subclass_kludge {
1224 struct tvec_env _env;
1225 struct tvec_remoteenv renv;
1226 struct tvec_remotefork fork;
1227 struct tvec_remoteexec exec;
1230 extern tvec_envsetupfn tvec_remotesetup;
1231 extern tvec_envsetfn tvec_remoteset;
1232 extern tvec_envrunfn tvec_remoterun;
1233 extern tvec_envafterfn tvec_remoteafter;
1234 extern tvec_envteardownfn tvec_remoteteardown;
1235 #define TVEC_REMOTEENV \
1236 { sizeof(struct tvec_remotectx), \
1242 tvec_remoteteardown }
1244 extern int tvec_setprogress(const char */*status*/);
1246 extern int tvec_remoteserver(int /*infd*/, int /*outfd*/,
1247 const struct tvec_config */*config*/);
1249 extern tvec_connectfn tvec_fork, tvec_exec;
1251 #define TVEC_REMOTEFORK( subenv, tests) \
1252 TVEC_REMOTEENV, { tvec_fork, subenv }, { tests }
1254 #define TVEC_REMOTEEXEC(subenv, args) \
1255 TVEC_REMOTEENV, { tvec_exec, subenv }, { args }
1257 /*----- Output functions --------------------------------------------------*/
1259 /* --- @tvec_report@, @tvec_report_v@ --- *
1261 * Arguments: @struct tvec_state *tv@ = test-vector state
1262 * @const char *msg@, @va_list ap@ = error message
1266 * Use: Report an message with a given severity. Messages with level
1267 * @TVLEV_ERR@ or higher force a nonzero exit code.
1270 extern void PRINTF_LIKE(3, 4)
1271 tvec_report(struct tvec_state */*tv*/, unsigned /*level*/,
1272 const char */*msg*/, ...);
1273 extern void tvec_report_v(struct tvec_state */*tv*/, unsigned /*level*/,
1274 const char */*msg*/, va_list */*ap*/);
1276 /* --- @tvec_error@, @tvec_notice@ --- *
1278 * Arguments: @struct tvec_state *tv@ = test-vector state
1279 * @const char *msg@, @va_list ap@ = error message
1281 * Returns: The @tvec_error@ function returns @-1@ as a trivial
1282 * convenience; @tvec_notice@ does not return a value.
1284 * Use: Report an error or a notice. Errors are distinct from test
1285 * failures, and indicate that a problem was encountered which
1286 * compromised the activity of testing. Notices are important
1287 * information which doesn't fit into any other obvious
1291 extern int PRINTF_LIKE(2, 3)
1292 tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
1293 extern void PRINTF_LIKE(2, 3)
1294 tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
1296 /* --- @tvec_humanoutput@ --- *
1298 * Arguments: @FILE *fp@ = output file to write on
1300 * Returns: An output formatter.
1302 * Use: Return an output formatter which writes on @fp@ with the
1303 * expectation that a human will be watching and interpreting
1304 * the output. If @fp@ denotes a terminal, the display shows a
1305 * `scoreboard' indicating the outcome of each test case
1306 * attempted, and may in addition use colour and other
1310 extern struct tvec_output *tvec_humanoutput(FILE */*fp*/);
1312 /* --- @tvec_tapoutput@ --- *
1314 * Arguments: @FILE *fp@ = output file to write on
1316 * Returns: An output formatter.
1318 * Use: Return an output formatter which writes on @fp@ in `TAP'
1319 * (`Test Anything Protocol') format.
1321 * TAP comes from the Perl community, but has spread rather
1322 * further. This driver produces TAP version 14, but pretends
1323 * to be version 13. The driver produces a TAP `test point' --
1324 * i.e., a result reported as `ok' or `not ok' -- for each input
1325 * test group. Failure reports and register dumps are produced
1326 * as diagnostic messages before the final group result. (TAP
1327 * permits structuerd YAML data after the test-point result,
1328 * which could be used to report details, but (a) postponing the
1329 * details until after the report is inconvenient, and (b) there
1330 * is no standardization for the YAML anyway, so in practice
1331 * it's no more useful than the unstructured diagnostics.
1334 extern struct tvec_output *tvec_tapoutput(FILE */*fp*/);
1336 /* --- @tvec_dfltoutput@ --- *
1338 * Arguments: @FILE *fp@ = output file to write on
1340 * Returns: An output formatter.
1342 * Use: Selects and instantiates an output formatter suitable for
1343 * writing on @fp@. The policy is subject to change, but
1344 * currently the `human' output format is selected if @fp@ is
1345 * interactive (i.e., if @isatty(fileno(fp))@ is true), and
1346 * otherwise the `tap' format is used.
1349 extern struct tvec_output *tvec_dfltout(FILE */*fp*/);
1351 /*------ Serialization utilities ------------------------------------------*/
1353 /* Serialization format.
1355 * The `candidate register definitions' are those entries @r@ in the @regs@
1356 * vector whose index @r.i@ is strictly less than @nr@. The `selected
1357 * register definitions' are those candidate register definitions @r@ for
1358 * which the indicated register @rv[r.i]@ has the @TVRF_LIVE@ flag set. The
1359 * serialized output begins with a header bitmap: if there are %$n$%
1360 * candidate register definitions then the header bitmap consists of %$\lceil
1361 * n/8 \rceil$% bytes. Bits are ordered starting from the least significant
1362 * bit of the first byte, end ending at the most significant bit of the final
1363 * byte. The bit corresponding to a candidate register definition is set if
1364 * and only if that register defintion is selected. The header bitmap is
1365 * then followed by the serializations of the selected registers -- i.e., for
1366 * each selected register definition @r@, the serialized value of register
1367 * @rv[r.i]@ -- simply concatenated together, with no padding or alignment.
1370 /* --- @tvec_serialize@ --- *
1372 * Arguments: @const struct tvec_reg *rv@ = vector of registers
1373 * @buf *b@ = buffer to write on
1374 * @const struct tvec_regdef *regs@ = vector of register
1375 * descriptions, terminated by an entry with a null
1377 * @unsigned nr@ = number of entries in the @rv@ vector
1378 * @size_t regsz@ = true size of each element of @rv@
1380 * Returns: Zero on success, @-1@ on failure.
1382 * Use: Serialize a collection of register values.
1384 * The serialized output is written to the buffer @b@. Failure
1385 * can be caused by running out of buffer space, or a failing
1389 extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/,
1390 const struct tvec_regdef */*regs*/,
1391 unsigned /*nr*/, size_t /*regsz*/);
1393 /* --- @tvec_deserialize@ --- *
1395 * Arguments: @struct tvec_reg *rv@ = vector of registers
1396 * @buf *b@ = buffer to write on
1397 * @const struct tvec_regdef *regs@ = vector of register
1398 * descriptions, terminated by an entry with a null
1400 * @unsigned nr@ = number of entries in the @rv@ vector
1401 * @size_t regsz@ = true size of each element of @rv@
1403 * Returns: Zero on success, @-1@ on failure.
1405 * Use: Deserialize a collection of register values.
1407 * The size of the register vector @nr@ and the register
1408 * definitions @regs@ must match those used when producing the
1409 * serialization. For each serialized register value,
1410 * deserialize and store the value into the appropriate register
1411 * slot, and set the @TVRF_LIVE@ flag on the register. See
1412 * @tvec_serialize@ for a description of the format.
1414 * Failure results only from a failing register type handler.
1417 extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
1418 const struct tvec_regdef */*regs*/,
1419 unsigned /*nr*/, size_t /*regsz*/);
1421 /*----- Input utilities ---------------------------------------------------*/
1423 /* These are provided by the core for the benefit of type @parse@ methods,
1424 * and test-environment @set@ functions, which get to read from the test
1425 * input file. The latter are usually best implemented by calling on the
1428 * The two main rules are as follows.
1430 * * Leave the file position at the beginning of the line following
1431 * whatever it was that you read.
1433 * * When you read and consume a newline (which you do at least once, by
1434 * the previous rule), then increment @tv->lno@ to keep track of the
1435 * current line number.
1438 /* --- @tvec_skipspc@ --- *
1440 * Arguments: @struct tvec_state *tv@ = test-vector state
1444 * Use: Advance over any whitespace characters other than newlines.
1445 * This will stop at `;', end-of-file, or any other kind of
1446 * non-whitespace; and it won't consume a newline.
1449 extern void tvec_skipspc(struct tvec_state */*tv*/);
1451 /* --- @tvec_syntax@, @tvec_syntax_v@ --- *
1453 * Arguments: @struct tvec_state *tv@ = test-vector state
1454 * @int ch@ = the character found (in @fgetc@ format)
1455 * @const char *expect@, @va_list ap@ = what was expected
1459 * Use: Report a syntax error quoting @ch@ and @expect@. If @ch@ is
1460 * a newline, then back up so that it can be read again (e.g.,
1461 * by @tvec_flushtoeol@ or @tvec_nexttoken@, which will also
1462 * advance the line number).
1465 extern int PRINTF_LIKE(3, 4)
1466 tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
1467 const char */*expect*/, ...);
1468 extern int tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/,
1469 const char */*expect*/, va_list */*ap*/);
1471 /* --- @tvec_flushtoeol@ --- *
1473 * Arguments: @struct tvec_state *tv@ = test-vector state
1474 * @unsigned f@ = flags (@TVFF_...@)
1476 * Returns: Zero on success, @-1@ on error.
1478 * Use: Advance to the start of the next line, consuming the
1479 * preceding newline.
1481 * A syntax error is reported if no newline character is found,
1482 * i.e., the file ends in mid-line. A syntax error is also
1483 * reported if material other than whitespace or a comment is
1484 * found before the end of the line end, and @TVFF_ALLOWANY@ is
1485 * not set in @f@. The line number count is updated
1489 #define TVFF_ALLOWANY 1u
1490 extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);
1492 /* --- @tvec_nexttoken@ --- *
1494 * Arguments: @struct tvec_state *tv@ = test-vector state
1496 * Returns: Zero if there is a next token which can be read; @-1@ if no
1497 * token is available.
1499 * Use: Advance to the next whitespace-separated token, which may be
1502 * Tokens are separated by non-newline whitespace, comments, and
1503 * newlines followed by whitespace; a newline /not/ followed by
1504 * whitespace instead begins the next assignment, and two
1505 * newlines separated only by whitespace terminate the data for
1508 * If this function returns zero, then the next character in the
1509 * file begins a suitable token which can be read and
1510 * processed. If it returns @-1@ then there is no such token,
1511 * and the file position is left correctly. The line number
1512 * count is updated appropriately.
1515 extern int tvec_nexttoken(struct tvec_state */*tv*/);
1517 /* --- @tvec_readword@ --- *
1519 * Arguments: @struct tvec_state *tv@ = test-vector state
1520 * @dstr *d@ = string to append the word to
1521 * @const char *delims@ = additional delimiters to stop at
1522 * @const char *expect@, @va_list ap@ = what was expected
1524 * Returns: Zero on success, @-1@ on failure.
1526 * Use: A `word' consists of characters other than whitespace, null
1527 * characters, and other than those listed in @delims@;
1528 * furthermore, a word does not begin with a `;'. (If you want
1529 * reading to stop at comments not preceded by whitespace, then
1530 * include `;' in @delims@. This is a common behaviour.)
1532 * If there is no word beginning at the current file position,
1533 * then return @-1@; furthermore, if @expect@ is not null, then
1534 * report an appropriate error via @tvec_syntax@.
1536 * Otherwise, the word is accumulated in @d@ and zero is
1537 * returned; if @d@ was not empty at the start of the call, the
1538 * newly read word is separated from the existing material by a
1539 * single space character. Since null bytes are never valid
1540 * word constituents, a null terminator is written to @d@, and
1541 * it is safe to treat the string in @d@ as being null-
1545 extern int PRINTF_LIKE(4, 5)
1546 tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
1547 const char */*delims*/, const char */*expect*/, ...);
1548 extern int tvec_readword_v(struct tvec_state */*tv*/, dstr */*d*/,
1549 const char */*delims*/, const char */*expect*/,
1552 /*----- Integer types: signed and unsigned --------------------------------*/
1554 /* Integers may be input in decimal, hex, binary, or octal, following
1555 * approximately usual conventions.
1557 * * Signed integers may be preceded with a `+' or `-' sign.
1559 * * Decimal integers are just a sequence of decimal digits `0' ... `9'.
1561 * * Octal integers are a sequence of digits `0' ... `7', preceded by `0o'
1564 * * Hexadecimal integers are a sequence of digits `0' ... `9', `a'
1565 * ... `f', or `A' ... `F', preceded by `0x' or `0X'.
1567 * * Radix-B integers are a sequence of digits `0' ... `9', `a' ... `f', or
1568 * `A' ... `F', each with value less than B, preceded by `Br' or `BR',
1569 * where 0 < B < 36 is expressed in decimal without any leading `0' or
1570 * internal underscores `_'.
1572 * * A digit sequence may contain internal underscore `_' separators, but
1573 * not before or after all of the digits; and two consecutive `_'
1574 * characters are not permitted.
1577 extern const struct tvec_regty tvty_int, tvty_uint;
1579 /* The @arg.p@ slot may be null or a pointer to @struct tvec_irange@ or
1580 * @struct tvec_urange@ as appropriate. The bounds are inclusive; use, e.g.,
1581 * @LONG_MAX@ explicitly if one or the other bound is logically inapplicable.
1583 struct tvec_irange { long min, max; };
1584 struct tvec_urange { unsigned long min, max; };
1586 /* Bounds corresponding to common integer types. */
1587 extern const struct tvec_irange
1588 tvrange_schar, tvrange_short, tvrange_int, tvrange_long,
1589 tvrange_sbyte, tvrange_i16, tvrange_i32;
1590 extern const struct tvec_urange
1591 tvrange_uchar, tvrange_ushort, tvrange_uint, tvrange_ulong, tvrange_size,
1592 tvrange_byte, tvrange_u16, tvrange_u32;
1594 /* --- @tvec_claimeq_int@, @TVEC_CLAIMEQ_INT@ --- *
1596 * Arguments: @struct tvec_state *tv@ = test-vector state
1597 * @long i0, i1@ = two signed integers
1598 * @const char *file@, @unsigned @lno@ = calling file and line
1599 * @const char *expr@ = the expression to quote on failure
1601 * Returns: Nonzero if @i0@ and @i1@ are equal, otherwise zero.
1603 * Use: Check that values of @i0@ and @i1@ are equal. As for
1604 * @tvec_claim@ above, a test case is automatically begun and
1605 * ended if none is already underway. If the values are
1606 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1607 * mismatched values are dumped: @i0@ is printed as the output
1608 * value and @i1@ is printed as the input reference.
1610 * The @TVEC_CLAIM_INT@ macro is similar, only it (a) identifies
1611 * the file and line number of the call site automatically, and
1612 * (b) implicitly quotes the source text of the @i0@ and @i1@
1613 * arguments in the failure message.
1616 extern int tvec_claimeq_int(struct tvec_state */*tv*/,
1617 long /*i0*/, long /*i1*/,
1618 const char */*file*/, unsigned /*lno*/,
1619 const char */*expr*/);
1620 #define TVEC_CLAIMEQ_INT(tv, i0, i1) \
1621 (tvec_claimeq_int(tv, i0, i1, __FILE__, __LINE__, #i0 " /= " #i1))
1623 /* --- @tvec_claimeq_uint@, @TVEC_CLAIMEQ_UINT@ --- *
1625 * Arguments: @struct tvec_state *tv@ = test-vector state
1626 * @unsigned long u0, u1@ = two unsigned integers
1627 * @const char *file@, @unsigned @lno@ = calling file and line
1628 * @const char *expr@ = the expression to quote on failure
1630 * Returns: Nonzero if @u0@ and @u1@ are equal, otherwise zero.
1632 * Use: Check that values of @u0@ and @u1@ are equal. As for
1633 * @tvec_claim@ above, a test case is automatically begun and
1634 * ended if none is already underway. If the values are
1635 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1636 * mismatched values are dumped: @u0@ is printed as the output
1637 * value and @u1@ is printed as the input reference.
1639 * The @TVEC_CLAIM_UINT@ macro is similar, only it (a)
1640 * identifies the file and line number of the call site
1641 * automatically, and (b) implicitly quotes the source text of
1642 * the @u0@ and @u1@ arguments in the failure message.
1645 extern int tvec_claimeq_uint(struct tvec_state */*tv*/,
1646 unsigned long /*u0*/, unsigned long /*u1*/,
1647 const char */*file*/, unsigned /*lno*/,
1648 const char */*expr*/);
1649 #define TVEC_CLAIMEQ_UINT(tv, u0, u1) \
1650 (tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))
1652 /*----- Floating-point type -----------------------------------------------*/
1654 /* Floating-point are either NaN (`#nan', if supported by the platform);
1655 * positive or negative infinity (`#inf', `+#inf', or, preferred, `#+inf',
1656 * and `-#inf' or, preferred, `#-inf', if supported by the platform), or a
1657 * number in strtod(3) syntax.
1659 * The comparison rules for floating-point numbers are complex: see
1660 * @tvec_claimeqish_float@ for details.
1663 extern const struct tvec_regty tvty_float;
1665 struct tvec_floatinfo {
1666 /* Details about acceptable floating-point values. */
1668 unsigned f; /* flags (@TVFF_...@ bits) */
1669 #define TVFF_NOMIN 1u /* ignore @min@ (allow -inf) */
1670 #define TVFF_NOMAX 2u /* ignore @max@ (allow +inf) */
1671 #define TVFF_NANOK 4u /* permit NaN */
1672 #define TVFF_EQMASK 0xf0 /* how to compare */
1673 #define TVFF_EXACT 0x00 /* must equal exactly */
1674 #define TVFF_ABSDELTA 0x10 /* must be within @delta@ */
1675 #define TVFF_RELDELTA 0x20 /* diff < @delta@ fraction */
1676 double min, max; /* smallest/largest value allowed */
1677 double delta; /* maximum tolerable difference */
1680 /* --- @tvec_claimeqish_float@, @TVEC_CLAIMEQISH_FLOAT@ --- *
1682 * Arguments: @struct tvec_state *tv@ = test-vector state
1683 * @double f0, f1@ = two floating-point numbers
1684 * @unsigned f@ = flags (@TVFF_...@)
1685 * @double delta@ = maximum tolerable difference
1686 * @const char *file@, @unsigned @lno@ = calling file and line
1687 * @const char *expr@ = the expression to quote on failure
1689 * Returns: Nonzero if @f0@ and @u1@ are sufficiently close, otherwise
1692 * Use: Check that values of @f0@ and @f1@ are sufficiently close.
1693 * As for @tvec_claim@ above, a test case is automatically begun
1694 * and ended if none is already underway. If the values are
1695 * too far apart, then @tvec_fail@ is called, quoting @expr@,
1696 * and the mismatched values are dumped: @f0@ is printed as the
1697 * output value and @f1@ is printed as the input reference.
1699 * The details for the comparison are as follows.
1701 * * A NaN value matches any other NaN, and nothing else.
1703 * * An infinity matches another infinity of the same sign,
1706 * * If @f&TVFF_EQMASK@ is @TVFF_EXACT@, then any
1707 * representable number matches only itself: in particular,
1708 * positive and negative zero are considered distinct.
1709 * (This allows tests to check that they land on the correct
1710 * side of branch cuts, for example.)
1712 * * If @f&TVFF_EQMASK@ is @TVFF_ABSDELTA@, then %$x$% matches
1713 * %$y$% when %$|x - y| < \delta$%.
1715 * * If @f&TVFF_EQMASK@ is @TVFF_RELDELTA@, then %$x$% matches
1716 * %$y$% when %$|1 - y/x| < \delta$%. (Note that this
1717 * criterion is asymmetric FIXME
1719 * The @TVEC_CLAIM_FLOAT@ macro is similar, only it (a)
1720 * identifies the file and line number of the call site
1721 * automatically, and (b) implicitly quotes the source text of
1722 * the @f0@ and @f1@ arguments (and @delta@) in the failure
1726 extern int tvec_claimeqish_float(struct tvec_state */*tv*/,
1727 double /*f0*/, double /*f1*/,
1728 unsigned /*f*/, double /*delta*/,
1729 const char */*file*/, unsigned /*lno*/,
1730 const char */*expr*/);
1731 #define TVEC_CLAIMEQISH_FLOAT(tv, f0, f1, f, delta) \
1732 (tvec_claimeqish_float(tv, f0, f1, f, delta, , __FILE__, __LINE__, \
1733 #f0 " /= " #f1 " (+/- " #delta ")"))
1735 /* --- @tvec_claimeq_float@, @TVEC_CLAIMEQ_FLOAT@ --- *
1737 * Arguments: @struct tvec_state *tv@ = test-vector state
1738 * @double f0, f1@ = two floating-point numbers
1739 * @const char *file@, @unsigned @lno@ = calling file and line
1740 * @const char *expr@ = the expression to quote on failure
1742 * Returns: Nonzero if @f0@ and @u1@ are identical, otherwise zero.
1744 * Use: Check that values of @f0@ and @f1@ are identical. The
1745 * function is exactly equivalent to @tvec_claimeqish_float@
1746 * with @f == TVFF_EXACT@; the macro is similarly like
1747 * @TVEC_CLAIMEQISH_FLOAT@ with @f == TVFF_EXACT@, except that
1748 * it doesn't bother to quote a delta.
1751 extern int tvec_claimeq_float(struct tvec_state */*tv*/,
1752 double /*f0*/, double /*f1*/,
1753 const char */*file*/, unsigned /*lno*/,
1754 const char */*expr*/);
1755 #define TVEC_CLAIMEQ_FLOAT(tv, f0, f1) \
1756 (tvec_claimeq_float(tv, f0, f1, __FILE__, __LINE__, #f0 " /= " #f1))
1758 /*----- Enumerated types --------------------------------------------------*/
1760 /* An enumeration describes a set of values of some underlying type, each of
1761 * which has a symbolic name. Values outside of the defined set can occur --
1762 * on output, because of bugs in the tested code, or on input to test
1763 * handling of unexpected values.
1765 * There is a distinct enumerated type for each of the branches of
1766 * @tvec_misc@. In the following, we write @t@ for the type code, which is
1767 * @i@ for signed integer, @u@ for unsigned integer, @f@ for floating-point,
1768 * and @p@ for pointer.
1770 * On input, an enumerated value may be given by name or as a literal value.
1771 * For enumerations based on numeric types, the literal values can be written
1772 * in the same syntax as the underlying values. For enumerations based on
1773 * pointers, the only permitted literal is `#nil', which denotes a null
1774 * pointer. On output, names are preferred (with the underlying value given
1778 #define DEFENUMTY(tag, ty, slot) \
1779 extern const struct tvec_regty tvty_##slot##enum;
1780 TVEC_MISCSLOTS(DEFENUMTY)
1783 /* A @struct tvec_tassoc@ associates a string tag with a value. */
1784 #define DEFASSOC(tag_, ty, slot) \
1785 struct tvec_##slot##assoc { const char *tag; ty slot; };
1786 TVEC_MISCSLOTS(DEFASSOC)
1789 #define TVEC_ENDENUM { 0, 0 }
1791 /* Information about an enumerated type. */
1792 #define DEFINFO(tag, ty, slot) \
1793 struct tvec_##slot##enuminfo { \
1794 const char *name; /* type name for diagnostics */ \
1795 const struct tvec_##slot##assoc *av; /* name/value mappings */ \
1796 EXTRA_##tag##_INFOSLOTS /* type-specific extra info */ \
1799 #define EXTRA_INT_INFOSLOTS \
1800 const struct tvec_irange *ir; /* allowed range of raw values */
1802 #define EXTRA_UINT_INFOSLOTS \
1803 const struct tvec_urange *ur; /* allowed range of raw values */
1805 #define EXTRA_FLT_INFOSLOTS \
1806 const struct tvec_floatinfo *fi; /* range and matching policy */
1808 #define EXTRA_PTR_INFOSLOTS /* (nothing) */
1810 TVEC_MISCSLOTS(DEFINFO)
1812 #undef EXTRA_INT_INFOSLOTS
1813 #undef EXTRA_UINT_INFOSLOTS
1814 #undef EXTRA_FLT_INFOSLOTS
1815 #undef EXTRA_PTR_INFOSLOTS
1819 /* Standard enumerations. */
1820 extern const struct tvec_ienuminfo tvenum_bool;
1821 extern const struct tvec_ienuminfo tvenum_cmp;
1823 /* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- *
1825 * Arguments: @struct tvec_state *tv@ = test-vector state
1826 * @const struct tvec_typeenuminfo *ei@ = enumeration type info
1827 * @ty t0, t1@ = two values
1828 * @const char *file@, @unsigned @lno@ = calling file and line
1829 * @const char *expr@ = the expression to quote on failure
1831 * Returns: Nonzero if @t0@ and @t1@ are equal, otherwise zero.
1833 * Use: Check that values of @t0@ and @t1@ are equal. As for
1834 * @tvec_claim@ above, a test case is automatically begun and
1835 * ended if none is already underway. If the values are
1836 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1837 * mismatched values are dumped: @t0@ is printed as the output
1838 * value and @t1@ is printed as the input reference.
1840 * The @TVEC_CLAIM_TENUM@ macro is similar, only it (a)
1841 * identifies the file and line number of the call site
1842 * automatically, and (b) implicitly quotes the source text of
1843 * the @t0@ and @t1@ arguments in the failure message.
1846 #define DECLCLAIM(tag, ty, slot) \
1847 extern int tvec_claimeq_##slot##enum \
1848 (struct tvec_state */*tv*/, \
1849 const struct tvec_##slot##enuminfo */*ei*/, \
1850 ty /*t0*/, ty /*t1*/, \
1851 const char */*file*/, unsigned /*lno*/, const char */*expr*/);
1852 TVEC_MISCSLOTS(DECLCLAIM)
1854 #define TVEC_CLAIMEQ_IENUM(tv, ei, i0, i1) \
1855 (tvec_claimeq_ienum(tv, ei, i0, i1, \
1856 __FILE__, __LINE__, #i0 " /= " #i1))
1857 #define TVEC_CLAIMEQ_UENUM(tv, ei, u0, u1) \
1858 (tvec_claimeq_uenum(tv, ei, u0, u1, \
1859 __FILE__, __LINE__, #u0 " /= " #u1))
1860 #define TVEC_CLAIMEQ_FENUM(tv, ei, f0, f1) \
1861 (tvec_claimeq_fenum(tv, ei, f0, f1, \
1862 __FILE__, __LINE__, #f0 " /= " #f1))
1863 #define TVEC_CLAIMEQ_PENUM(tv, ei, p0, p1) \
1864 (tvec_claimeq_penum(tv, ei, p0, p1, \
1865 __FILE__, __LINE__, #p0 " /= " #p1))
1867 /*----- Flags type --------------------------------------------------------*/
1869 /* A flags value packs a number of fields into a single nonnegative integer.
1870 * Symbolic names are associated with the possible values of the various
1871 * fields; more precisely, each name is associated with a value and a
1874 * The input syntax is a sequence of items separated by `|' signs. Each item
1875 * may be the symbolic name of a field value, or a literal unsigned integer.
1876 * The masks associated with the given symbolic names must be disjoint. The
1877 * resulting numerical value is simply the bitwise OR of the given values.
1879 * On output, the table of symbolic names and their associated values and
1880 * masks is repeatedly scanned, in order, to find disjoint matches -- i.e.,
1881 * entries whose value matches the target value in the bit positions
1882 * indicated by the mask, and whose mask doesn't overlap with any previously
1883 * found matches; the names are then output, separated by `|'. Any remaining
1884 * nonzero bits not covered by any of the matching masks are output as a
1885 * single literal integer, in hex.
1888 extern const struct tvec_regty tvty_flags;
1891 /* Definition of a single flag or bitfield value.
1893 * Each named setting comes with a value @v@ and a mask @m@; the mask
1894 * should cover all of the value bits, i.e., @(v&~m) == 0@.
1897 const char *tag; /* name */
1898 unsigned long m, v; /* mask and value */
1901 #define TVEC_ENDFLAGS { 0, 0, 0 }
1903 struct tvec_flaginfo {
1904 /* Information about a flags type. */
1906 const char *name; /* type name for diagnostics */
1907 const struct tvec_flag *fv; /* name/mask/value mappings */
1908 const struct tvec_urange *range; /* permitted range for literals */
1911 /* --- @tvec_claimeq_flags@, @TVEC_CLAIMEQ_FLAGS@ --- *
1913 * Arguments: @struct tvec_state *tv@ = test-vector state
1914 * @const struct tvec_flaginfo *fi@ = flags type info
1915 * @unsigned long f0, f1@ = two values
1916 * @const char *file@, @unsigned @lno@ = calling file and line
1917 * @const char *expr@ = the expression to quote on failure
1919 * Returns: Nonzero if @f0@ and @f1@ are equal, otherwise zero.
1921 * Use: Check that values of @f0@ and @f1@ are equal. As for
1922 * @tvec_claim@ above, a test case is automatically begun and
1923 * ended if none is already underway. If the values are
1924 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1925 * mismatched values are dumped: @f0@ is printed as the output
1926 * value and @f1@ is printed as the input reference.
1928 * The @TVEC_CLAIM_FLAGS@ macro is similar, only it (a)
1929 * identifies the file and line number of the call site
1930 * automatically, and (b) implicitly quotes the source text of
1931 * the @f0@ and @f1@ arguments in the failure message.
1934 extern int tvec_claimeq_flags(struct tvec_state */*tv*/,
1935 const struct tvec_flaginfo */*fi*/,
1936 unsigned long /*f0*/, unsigned long /*f1*/,
1937 const char */*file*/, unsigned /*lno*/,
1938 const char */*expr*/);
1939 #define TVEC_CLAIMEQ_FLAGS(tv, fi, f0, f1) \
1940 (tvec_claimeq_flags(tv, fi, f0, f1, \
1941 __FILE__, __LINE__, #f0 " /= " #f1))
1943 /*----- Character type ----------------------------------------------------*/
1945 /* A character value holds a character, as read by @fgetc@. The special
1946 * @EOF@ value can also be represented.
1948 * On input, a character value can be given by name, with a leading `%|#|%';
1949 * or a character or `%|\|%'-escape sequence, optionally in single quotes.
1951 * The following escape sequences and character names are recognized.
1953 * * `%|#eof|%' is the special end-of-file marker.
1955 * * `%|#nul|%' is the NUL character, sometimes used to terminate strings.
1957 * * `%|bell|%', `%|bel|%', `%|ding|%', or `%|\a|%' is the BEL character
1958 * used to ring the terminal bell (or do some other thing to attract the
1959 * user's attention).
1961 * * %|#backspace|%, %|#bs|%, or %|\b|% is the backspace character, used to
1962 * move the cursor backwords by one cell.
1964 * * %|#escape|% %|#esc|%, or%|\e|% is the escape character, used to
1965 * introduce special terminal commands.
1967 * * %|#formfeed|%, %|#ff|%, or %|\f|% is the formfeed character, used to
1968 * separate pages of text.
1970 * * %|#newline|%, %|#linefeed|%, %|#lf|%, %|#nl|%, or %|\n|% is the
1971 * newline character, used to terminate lines of text or advance the
1972 * cursor to the next line (perhaps without returning it to the start of
1975 * * %|#return|%, %|#carriage-return|%, %|#cr|%, or %|\r|% is the
1976 * carriage-return character, used to return the cursor to the start of
1979 * * %|#tab|%, %|#horizontal-tab|%, %|#ht|%, or %|\t|% is the tab
1980 * character, used to advance the cursor to the next tab stop on the
1983 * * %|#vertical-tab|%, %|#vt|%, %|\v|% is the vertical tab character.
1985 * * %|#space|%, %|#spc|% is the space character.
1987 * * %|#delete|%, %|#del|% is the delete character, used to erase the most
1990 * * %|\'|% is the single-quote character.
1992 * * %|\\|% is the backslash character.
1994 * * %|\"|% is the double-quote character.
1996 * * %|\NNN|% or %|\{NNN}|% is the character with code NNN in octal. The
1997 * NNN may be up to three digits long.
1999 * * %|\xNN|% or %|\x{NN}|% is the character with code NNN in hexadecimal.
2002 extern const struct tvec_regty tvty_char;
2004 /* --- @tvec_claimeq_char@, @TVEC_CLAIMEQ_CHAR@ --- *
2006 * Arguments: @struct tvec_state *tv@ = test-vector state
2007 * @int ch0, ch1@ = two character codes
2008 * @const char *file@, @unsigned @lno@ = calling file and line
2009 * @const char *expr@ = the expression to quote on failure
2011 * Returns: Nonzero if @ch0@ and @ch1@ are equal, otherwise zero.
2013 * Use: Check that values of @ch0@ and @ch1@ are equal. As for
2014 * @tvec_claim@ above, a test case is automatically begun and
2015 * ended if none is already underway. If the values are
2016 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2017 * mismatched values are dumped: @ch0@ is printed as the output
2018 * value and @ch1@ is printed as the input reference.
2020 * The @TVEC_CLAIM_CHAR@ macro is similar, only it (a)
2021 * identifies the file and line number of the call site
2022 * automatically, and (b) implicitly quotes the source text of
2023 * the @ch0@ and @ch1@ arguments in the failure message.
2026 extern int tvec_claimeq_char(struct tvec_state */*tv*/,
2027 int /*ch0*/, int /*ch1*/,
2028 const char */*file*/, unsigned /*lno*/,
2029 const char */*expr*/);
2030 #define TVEC_CLAIMEQ_CHAR(tv, c0, c1) \
2031 (tvec_claimeq_char(tv, c0, c1, __FILE__, __LINE__, #c0 " /= " #c1))
2033 /*----- Text and binary string types --------------------------------------*/
2035 /* A string is a sequence of octets. Text and binary strings differ
2036 * primarily in presentation: text strings are shown as raw characters where
2037 * possible; binary strings are shown as hex dumps with an auxiliary text
2040 * The input format for both kinds of strings is basically the same: a
2041 * `compound string', consisting of
2043 * * single-quoted strings, which are interpreted entirely literally, but
2044 * can't contain single quotes or newlines;
2046 * * double-quoted strings, in which `%|\|%'-escapes are interpreted as for
2049 * * character names, marked by an initial `%|#|%' sign;
2051 * * special tokens marked by an initial `%|!|%' sign; or
2053 * * barewords interpreted according to the current coding scheme.
2055 * The special tokens are
2057 * * `%|!bare|%', which causes subsequent sequences of barewords to be
2058 * treated as plain text;
2060 * * `%|!hex|%', `%|!base32|%', `%|!base64|%', which cause subsequent
2061 * barewords to be decoded in the requested manner.
2063 * * `%|!repeat|% %$n$% %|{|% %%\textit{string}%% %|}|%', which includes
2064 * %$n$% copies of the (compound) string.
2066 * Either kind of string can contain internal nul characters. A trailing nul
2067 * is appended -- beyond the stated input length -- to input strings as a
2068 * convenience to test functions. Test functions may include such a nul
2069 * character on output but this is not checked by the equality test.
2071 * A @struct tvec_urange@ may be supplied as an argument: the length of the
2072 * string (in bytes) will be checked against the permitted range.
2075 extern const struct tvec_regty tvty_string, tvty_bytes;
2077 /* --- @tvec_claimeq_string@, @TVEC_CLAIMEQ_STRING@ --- *
2079 * Arguments: @struct tvec_state *tv@ = test-vector state
2080 * @const char *p0@, @size_t sz0@ = first string with length
2081 * @const char *p1@, @size_t sz1@ = second string with length
2082 * @const char *file@, @unsigned @lno@ = calling file and line
2083 * @const char *expr@ = the expression to quote on failure
2085 * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
2088 * Use: Check that strings at @p0@ and @p1@ are equal. As for
2089 * @tvec_claim@ above, a test case is automatically begun and
2090 * ended if none is already underway. If the values are
2091 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2092 * mismatched values are dumped: @p0@ is printed as the output
2093 * value and @p1@ is printed as the input reference.
2095 * The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
2096 * identifies the file and line number of the call site
2097 * automatically, and (b) implicitly quotes the source text of
2098 * the @ch0@ and @ch1@ arguments in the failure message.
2101 extern int tvec_claimeq_string(struct tvec_state */*tv*/,
2102 const char */*p0*/, size_t /*sz0*/,
2103 const char */*p1*/, size_t /*sz1*/,
2104 const char */*file*/, unsigned /*lno*/,
2105 const char */*expr*/);
2106 #define TVEC_CLAIMEQ_STRING(tv, p0, sz0, p1, sz1) \
2107 (tvec_claimeq_string(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
2108 #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
2110 /* --- @tvec_claimeq_strz@, @TVEC_CLAIMEQ_STRZ@ --- *
2112 * Arguments: @struct tvec_state *tv@ = test-vector state
2113 * @const char *p0, *p1@ = two strings to compare
2114 * @const char *file@, @unsigned @lno@ = calling file and line
2115 * @const char *expr@ = the expression to quote on failure
2117 * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
2120 * Use: Check that strings at @p0@ and @p1@ are equal, as for
2121 * @tvec_claimeq_string@, except that the strings are assumed
2122 * null-terminated, so their lengths don't need to be supplied
2123 * explicitly. The macro is similarly like
2124 * @TVEC_CLAIMEQ_STRING@.
2127 extern int tvec_claimeq_strz(struct tvec_state */*tv*/,
2128 const char */*p0*/, const char */*p1*/,
2129 const char */*file*/, unsigned /*lno*/,
2130 const char */*expr*/);
2131 #define TVEC_CLAIMEQ_STRZ(tv, p0, p1) \
2132 (tvec_claimeq_strz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
2134 /* --- @tvec_claimeq_bytes@, @TVEC_CLAIMEQ_BYTES@ --- *
2136 * Arguments: @struct tvec_state *tv@ = test-vector state
2137 * @const void *p0@, @size_t sz0@ = first string with length
2138 * @const void *p1@, @size_t sz1@ = second string with length
2139 * @const char *file@, @unsigned @lno@ = calling file and line
2140 * @const char *expr@ = the expression to quote on failure
2142 * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
2145 * Use: Check that binary strings at @p0@ and @p1@ are equal. As for
2146 * @tvec_claim@ above, a test case is automatically begun and
2147 * ended if none is already underway. If the values are
2148 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2149 * mismatched values are dumped: @p0@ is printed as the output
2150 * value and @p1@ is printed as the input reference.
2152 * The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
2153 * identifies the file and line number of the call site
2154 * automatically, and (b) implicitly quotes the source text of
2155 * the @ch0@ and @ch1@ arguments in the failure message.
2158 extern int tvec_claimeq_bytes(struct tvec_state */*tv*/,
2159 const void */*p0*/, size_t /*sz0*/,
2160 const void */*p1*/, size_t /*sz1*/,
2161 const char */*file*/, unsigned /*lno*/,
2162 const char */*expr*/);
2163 #define TVEC_CLAIMEQ_BYTES(tv, p0, sz0, p1, sz1) \
2164 (tvec_claimeq(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
2165 #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
2167 /* --- @tvec_allocstring@, @tvec_allocbytes@ --- *
2169 * Arguments: @union tvec_regval *rv@ = register value
2170 * @size_t sz@ = required size
2174 * Use: Allocated space in a text or binary string register. If the
2175 * current register size is sufficient, its buffer is left
2176 * alone; otherwise, the old buffer, if any, is freed and a
2177 * fresh buffer allocated. These functions are not intended to
2178 * be used to adjust a buffer repeatedly, e.g., while building
2179 * output incrementally: (a) they will perform badly, and (b)
2180 * the old buffer contents are simply discarded if reallocation
2181 * is necessary. Instead, use a @dbuf@ or @dstr@.
2183 * The @tvec_allocstring@ function sneakily allocates an extra
2184 * byte for a terminating zero. The @tvec_allocbytes@ function
2188 extern void tvec_allocstring(union tvec_regval */*rv*/, size_t /*sz*/);
2189 extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);
2191 /*----- Buffer type -------------------------------------------------------*/
2193 /* Buffer registers are primarily used for benchmarking. Only a buffer's
2194 * size is significant: its contents are ignored on comparison and output,
2195 * and unspecified on input.
2197 * The input is simply the buffer size, as an integer, optionally suffixed
2198 * with a unit `kB', `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or
2199 * without the `B') denoting a power of 1024. Units are used on output only
2200 * when the size would be expressed exactly.
2203 extern const struct tvec_regty tvty_buffer;
2205 /*----- That's all, folks -------------------------------------------------*/
~mdw / mLib / blob