generics: sum-type Variants + unified Match/When/Otherwise

One Match/When/Otherwise now drives both static type dispatch and by-value sum
types, with fail-fast on a non-exhaustive match.

- Include/Misra/Generics/Variant.h (new): `Variant(N, T...)` generates a
  per-variant tag enum (namespaced `N_<T>` -- no global registry, two variants
  sharing a payload type never collide), the tagged union, and a typed
  `N_from_<T>` constructor each. Reuses Types.h's `APPLY_MACRO_FOREACH` plus a
  context-threading sibling `APPLY_MACRO_FOREACH_C`; the `__VA_OPT__` engine
  caps payloads at ~256 (a loud compile error past that, not truncation).
- Include/Misra/Generics/TypeMatch.h: `When` is `OVERLOAD`-based -- `When(T)`
  keeps the static type arm (it = the value), `When(N, T)` adds a variant arm
  (it = the typed payload). `Match` binds the scrutinee as `MisraSubject`. A
  non-exhaustive match (no arm, no Otherwise) aborts via `ASSERT_OR_FATAL`
  instead of falling through -- the runtime-fail-fast stance. The static API is
  unchanged and backward compatible.

Dispatch stays a flat if-chain, which the optimiser lowers to an O(1) jump
table for dense variant tags. Naming follows the no-MISRA-prefix convention
(internal macros are VARIANT_* / APPLY_MACRO_*).

Tests: Generics/TypeMatch.c (7 + deadend) and a new Generics/Variant.c
(7 + deadend asserting the non-exhaustive abort), wired into Tests/meson.build.

Author: brightprogrammer

Include/Misra/Generics.h

@@ -3,8 +3,9 @@
 /// This is free and unencumbered software released into the public domain.
 ///
 /// Generics subsystem umbrella. Header-only metaprogramming built on
-/// `_Generic` -- currently a compile-time type match (`Match` / `When` /
-/// `Otherwise`).
+/// `_Generic` and the `__VA_OPT__` foreach engine: a compile-time type match
+/// and by-value sum types, sharing one `Match` / `When` / `Otherwise`
+/// (`When(T)` on a static type, `When(N, T)` on a `Variant(N, ...)` value).
 ///
 /// Deliberately NOT pulled through the top-level `Misra.h` umbrella: the
 /// public macros here use short, ergonomic names (`Match`, `When`, `it`,
@@ -17,5 +18,6 @@
 #define MISRA_GENERICS_H
 
 #include <Misra/Generics/TypeMatch.h>
+#include <Misra/Generics/Variant.h>
 
 #endif // MISRA_GENERICS_H

Include/Misra/Generics/TypeMatch.h

@@ -10,13 +10,16 @@
 /// arms.
 ///
 /// This is type DISPATCH, not value destructuring: arms select on a value's
-/// type only -- there is no taking-apart of structs, no literal or nested
-/// matching, and no exhaustiveness check. Arms are mutually exclusive; an
-/// optional trailing `Otherwise` catches the rest.
+/// type only -- there is no taking-apart of structs, and no literal or nested
+/// matching. Arms are mutually exclusive; an optional trailing `Otherwise`
+/// catches the rest. A non-exhaustive match -- no `When` hit and no
+/// `Otherwise` -- does NOT fall through silently: it aborts via `LOG_FATAL` at
+/// runtime, matching the project's fail-fast-for-correctness stance.
 
 #ifndef MISRA_GENERICS_TYPEMATCH_H
 #define MISRA_GENERICS_TYPEMATCH_H
 
+#include <Misra/Std/Log.h>
 #include <Misra/Types.h>
 
 #ifdef __cplusplus
@@ -53,8 +56,10 @@ extern "C" {
 /// SUCCESS : Runs the body of the single arm whose type matches `x` (or
 ///           `Otherwise` if none), with `it` bound to `x`. Block exits after
 ///           one arm.
-/// FAILURE : Macro cannot fail. A `When` body that misuses `it`'s static type
-///           is a compile error (every arm is type-checked).
+/// FAILURE : If no `When` matches and there is no `Otherwise`, the match is
+///           non-exhaustive and aborts via `LOG_FATAL` -- it never silently
+///           falls through. A `When` body that misuses `it`'s static type is a
+///           compile error (every arm is type-checked).
 ///
 /// USAGE:
 ///   Match(value) {
@@ -66,19 +71,37 @@ extern "C" {
 /// TAGS: Generics, Match, Type, Dispatch, Compile-Time
 ///
 #define Match(x)                                                                                                       \
-    for (TYPE_OF(x) it = (x), *UNPL(tm_loop) = &it; UNPL(tm_loop); UNPL(tm_loop) = NULL)                               \
-        for (bool MisraMatched = false; !MisraMatched; MisraMatched = true)
+    for (bool MisraMatched = false, UNPL(tm_once) = true; UNPL(tm_once); UNPL(tm_once) = false,                        \
+              ASSERT_OR_FATAL(MisraMatched, "Match: no arm matched and no Otherwise (non-exhaustive)"))                \
+        for (TYPE_OF(x) MisraSubject = (x), *UNPL(tm_loop) = &MisraSubject; UNPL(tm_loop); UNPL(tm_loop) = NULL)
 
 ///
-/// An arm of a `Match`. Runs its body iff no earlier arm matched and `it`'s
-/// static type is `T`.
+/// An arm of a `Match`, in one of two forms (selected by argument count):
 ///
-/// SUCCESS : Body runs at most once, only for the matching type.
-/// FAILURE : Macro cannot fail. Usable only inside a `Match`.
+///   * `When(T)`    -- static: runs iff no earlier arm matched and the
+///                     subject's static type is `T`; binds `it` to the value.
+///   * `When(N, T)` -- variant: runs iff no earlier arm matched and the
+///                     subject's runtime tag is `Variant(N, ...)`'s `T`; binds
+///                     `it` to the T-typed payload.
+///
+/// SUCCESS : Body runs at most once, only on a match, with `it` bound.
+/// FAILURE : Macro cannot fail. Usable only inside a `Match`. `When(N, T)` for
+///           a `T` the variant cannot hold is a compile error (no `as_T`
+///           member).
 ///
-/// TAGS: Generics, Match, Type, Arm
+/// TAGS: Generics, Match, Type, Variant, Arm
 ///
-#define When(T) if (!MisraMatched && Is(it, T) && (MisraMatched = true))
+#define When(...) OVERLOAD(When, __VA_ARGS__)
+
+/* static arm: it = the value (its static type). */
+#define When_1(T)                                                                                                      \
+    if (!MisraMatched && Is(MisraSubject, T) && (MisraMatched = true))                                                 \
+        for (TYPE_OF(MisraSubject) it = MisraSubject, *UNPL(tm_bind) = &it; UNPL(tm_bind); UNPL(tm_bind) = NULL)
+
+/* variant arm: it = the T-typed payload of a Variant(N, ...) subject. */
+#define When_2(N, T)                                                                                                   \
+    if (!MisraMatched && MisraSubject.tag == N##_##T && (MisraMatched = true))                                         \
+        for (T it = MisraSubject.u.as_##T, *UNPL(tm_bind) = &it; UNPL(tm_bind); UNPL(tm_bind) = NULL)
 
 ///
 /// The fallback arm of a `Match`. Runs iff no earlier arm matched.

Include/Misra/Generics/Variant.h

@@ -0,0 +1,95 @@
+/// file      : generics/variant.h
+/// author    : Siddharth Mishra (admin@brightprogrammer.in)
+/// This is free and unencumbered software released into the public domain.
+///
+/// By-value tagged-union sum types. `Variant(Name, T...)` generates a
+/// per-variant tag enum, the tagged union, and a typed constructor per
+/// payload. Pair with `Match` / `When` from `Generics/TypeMatch.h`:
+/// `When(Name, T)` dispatches on the runtime tag and binds the T-typed
+/// payload as `it`.
+///
+/// Self-contained -- no global registration. Two variants sharing a payload
+/// type never collide (each tag enum is namespaced by the variant name). Up
+/// to 256 payload types (the foreach-expansion ceiling); exceeding it is a
+/// loud compile error, not silent truncation. Payload type names must each be
+/// a single token -- `typedef` compound types (`unsigned int`, `char *`)
+/// before listing them.
+
+#ifndef MISRA_GENERICS_VARIANT_H
+#define MISRA_GENERICS_VARIANT_H
+
+#include <Misra/Types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// A generated constructor is rarely called for every payload type, so mark
+// them maybe-unused. clang's `-Wunused-function` fires for `static inline`
+// definitions emitted into a source file; MSVC has no such attribute.
+#if defined(__GNUC__) || defined(__clang__)
+#    define VARIANT_UNUSED __attribute__((unused))
+#else
+#    define VARIANT_UNUSED
+#endif
+
+// Context-threading sibling of `APPLY_MACRO_FOREACH` (Types.h): applies
+// `gen(ctx, elem)` to each element, reusing the same `__VA_OPT__` trampoline
+// (`TRICK_EXPAND` / `TRICK_PARENS`) and therefore the same ~256-element
+// ceiling. `ctx` is the variant name, threaded so the generators can
+// namespace the tag constants and constructors.
+#define APPLY_MACRO_FOREACH_C(gen, ctx, ...)                                                                           \
+    __VA_OPT__(TRICK_EXPAND(APPLY_MACRO_FOREACH_C_HELPER(gen, ctx, __VA_ARGS__)))
+#define APPLY_MACRO_FOREACH_C_HELPER(gen, ctx, a1, ...)                                                                \
+    gen(ctx, a1) __VA_OPT__(APPLY_MACRO_FOREACH_C_AGAIN TRICK_PARENS(gen, ctx, __VA_ARGS__))
+#define APPLY_MACRO_FOREACH_C_AGAIN() APPLY_MACRO_FOREACH_C_HELPER
+
+// Per-payload code generators (internal).
+#define VARIANT_ENUMERATOR(N, T) N##_##T,
+#define VARIANT_FIELD(T)         T as_##T;
+#define VARIANT_CTOR(N, T)                                                                                             \
+    static inline VARIANT_UNUSED N N##_from_##T(T value) {                                                             \
+        N out;                                                                                                         \
+        out.tag      = N##_##T;                                                                                        \
+        out.u.as_##T = value;                                                                                          \
+        return out;                                                                                                    \
+    }
+
+///
+/// Declare a by-value tagged-union sum type `N` over the listed payload types.
+/// Emits a per-variant tag enum `enum N##_Tag` with one namespaced constant
+/// `N##_<T>` per type, the tagged union, and a `static inline N N##_from_<T>`
+/// constructor per type. No global registration -- matchable directly with
+/// `Match` / `When(N, T)`.
+///
+/// SUCCESS : Defines `enum N##_Tag { N_<T>, ... }`, `typedef struct { enum
+///           N##_Tag tag; union { T as_<T>; ... } u; } N;`, and a typed
+///           constructor per payload. A trailing `;` after the macro is
+///           required and consumed.
+/// FAILURE : Macro cannot fail. More than 256 payloads is a compile error
+///           (the foreach ceiling). Payload type names must each be a single
+///           token; compound types must be `typedef`-d first.
+///
+/// USAGE:
+///   Variant(Number, int, float, double);
+///   Number n = Number_from_int(7);
+///   // match with: Match(n) { When(Number, int) { ... it ... } ... }
+///
+/// TAGS: Generics, Variant, SumType, Constructor
+///
+#define Variant(N, ...)                                                                                                \
+    enum N##_Tag {APPLY_MACRO_FOREACH_C(VARIANT_ENUMERATOR, N, __VA_ARGS__)};                                          \
+    typedef struct {                                                                                                   \
+        enum N##_Tag tag;                                                                                              \
+        union {                                                                                                        \
+            APPLY_MACRO_FOREACH(VARIANT_FIELD, __VA_ARGS__)                                                            \
+        } u;                                                                                                           \
+    } N;                                                                                                               \
+    APPLY_MACRO_FOREACH_C(VARIANT_CTOR, N, __VA_ARGS__)                                                                \
+    struct N##_variant_force_semicolon /* swallow the trailing `;` */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // MISRA_GENERICS_VARIANT_H

Tests/Generics/TypeMatch.c

@@ -115,6 +115,16 @@ bool test_is_predicate(void) {
     return Is(i, int) == 1 && Is(i, double) == 0 && Is(d, double) == 1 && Is(d, int) == 0;
 }
 
+// Deadend: a non-exhaustive match (no arm matches, no Otherwise) must abort
+// rather than fall through silently.
+bool deadend_match_nonexhaustive(void) {
+    Position2D p = {1.0f, 2.0f};
+    Match(p) {
+        When(int)(void) it; // never matches Position2D, and there is no Otherwise
+    }
+    return true;            // unreachable -- the match aborts first
+}
+
 int main(void) {
     WriteFmt("[INFO] Starting Generics.TypeMatch tests\n\n");
     TestFunction tests[] = {
@@ -126,6 +136,10 @@ int main(void) {
         test_nested_match_shadows_it,
         test_is_predicate,
     };
-    int total = sizeof(tests) / sizeof(tests[0]);
-    return run_test_suite(tests, total, NULL, 0, "Generics.TypeMatch");
+    TestFunction deadend_tests[] = {
+        deadend_match_nonexhaustive,
+    };
+    int total   = sizeof(tests) / sizeof(tests[0]);
+    int deadend = sizeof(deadend_tests) / sizeof(deadend_tests[0]);
+    return run_test_suite(tests, total, deadend_tests, deadend, "Generics.TypeMatch");
 }

Tests/Generics/Variant.c

@@ -0,0 +1,144 @@
+#include <Misra/Generics.h>
+#include <Misra/Std/Io.h>
+#include <Misra/Types.h>
+
+#include "../Util/TestRunner.h"
+
+// Self-contained variants -- no global registration; two variants sharing a
+// payload type do not collide.
+Variant(Number, int, double);
+Variant(Cell, int, char);
+Variant(Tri, int, float, char);
+
+// ---------------------------------------------------------------------------
+// Variant construction + Match / When (variant arms) / Otherwise
+// ---------------------------------------------------------------------------
+
+bool test_variant_construct_and_match(void) {
+    Number n   = Number_from_int(42);
+    bool   hit = false;
+    Match(n) {
+        When(Number, int) hit    = (it == 42);
+        When(Number, double) hit = false;
+    }
+
+    Number m  = Number_from_double(2.5);
+    bool   hd = false;
+    Match(m) {
+        When(Number, int) hd    = false;
+        When(Number, double) hd = (it == 2.5);
+    }
+    return hit && hd;
+}
+
+bool test_variant_it_is_typed_payload(void) {
+    Number a  = Number_from_int(10);
+    Number b  = Number_from_double(1.5);
+    int    ai = 0;
+    double bd = 0.0;
+    Match(a) {
+        When(Number, int) ai    = it * 2; // it : int
+        When(Number, double) bd = it;
+    }
+    Match(b) {
+        When(Number, int) ai    = it;
+        When(Number, double) bd = it * 2.0; // it : double
+    }
+    return ai == 20 && bd == 3.0;
+}
+
+// value in, value out -- no pointers
+static Number twice(Number n) {
+    Match(n) {
+        When(Number, int) return Number_from_int(it * 2);
+        When(Number, double) return Number_from_double(it * 2.0);
+    }
+    return n;
+}
+
+bool test_variant_by_value_flow(void) {
+    Number r  = twice(Number_from_int(21));
+    bool   ok = false;
+    Match(r) {
+        When(Number, int) ok    = (it == 42);
+        When(Number, double) ok = false;
+    }
+    return ok;
+}
+
+bool test_variant_rvalue_and_otherwise(void) {
+    bool ok = false;
+    // Match directly on a function-return rvalue; float-less Number -> Otherwise unused.
+    Match(twice(Number_from_double(1.5))) {
+        When(Number, int) ok    = false;
+        When(Number, double) ok = (it == 3.0);
+        Otherwise ok            = false;
+    }
+    return ok;
+}
+
+bool test_two_variants_independent(void) {
+    Cell c  = Cell_from_char('Z');
+    bool ok = false;
+    Match(c) {
+        When(Cell, int) ok  = false;
+        When(Cell, char) ok = (it == 'Z');
+    }
+    return ok;
+}
+
+bool test_variant_three_payloads(void) {
+    Tri  vals[] = {Tri_from_int(7), Tri_from_float(1.5f), Tri_from_char('A')};
+    int  seen   = 0;
+    bool ok     = true;
+    for (int k = 0; k < 3; k++) {
+        Match(vals[k]) {
+            When(Tri, int) ok = ok && (it == 7), seen |= 1;
+            When(Tri, float) ok = ok && (it == 1.5f), seen |= 2;
+            When(Tri, char) ok = ok && (it == 'A'), seen |= 4;
+        }
+    }
+    return ok && seen == 7;
+}
+
+bool test_variant_arms_are_exclusive(void) {
+    Number n     = Number_from_int(7);
+    int    count = 0;
+    Match(n) {
+        When(Number, int) count++;
+        When(Number, double) count++;
+        Otherwise count++;
+    }
+    return count == 1;
+}
+
+// ---------------------------------------------------------------------------
+// Deadend: a non-exhaustive variant match aborts rather than fall through.
+// ---------------------------------------------------------------------------
+
+bool deadend_variant_nonexhaustive(void) {
+    Number n = Number_from_double(9.0); // holds double, only int handled, no Otherwise
+    Match(n) {
+        When(Number, int)(void) it;
+    }
+    return true; // unreachable -- the match aborts first
+}
+
+int main(void) {
+    WriteFmt("[INFO] Starting Generics.Variant tests\n\n");
+    TestFunction tests[] = {
+        test_variant_construct_and_match,
+        test_variant_it_is_typed_payload,
+        test_variant_by_value_flow,
+        test_variant_rvalue_and_otherwise,
+        test_two_variants_independent,
+        test_variant_three_payloads,
+        test_variant_arms_are_exclusive,
+    };
+    TestFunction deadend_tests[] = {
+        deadend_variant_nonexhaustive,
+    };
+    int total   = sizeof(tests) / sizeof(tests[0]);
+    int deadend = sizeof(deadend_tests) / sizeof(deadend_tests[0]);
+    return run_test_suite(tests, total, deadend_tests, deadend, "Generics.Variant");
+}

Tests/meson.build

@@ -796,6 +796,7 @@ endforeach
 
 generics_tests = [
     ['Generics.TypeMatch', 'Generics/TypeMatch.c'],
+    ['Generics.Variant', 'Generics/Variant.c'],
 ]
 
 foreach test_info : generics_tests