Algebraic Enums module

This module provides macros for declaring algebraic datatypes called algebraic Enums, similar to Rust's Enum, and pattern matching on their variants.

A Cnx Enum is an algebraic data type similar to tagged unions, but with additional capabilities and related abstractions that make working with them simple and pleasant, with no boilerplate.

Enum declarations consist of a type name, followed by one or more variant layouts, followed by zero or more additional member declarations. Variant layouts are tuples of the form (VariantName, MemberTypes...) where VariantName is required, and MemberTypes can be zero or more type names (such as int, CnxString, or struct timespec). Enum declarations may alternately use a predefined enum type for identifying their variants. In this case, the enum members' identifiers must exactly match the names of the Enum's variants.

Example:

// An `Enum` declaration consisting of three variants
Enum(Example1, (E1Variant1, i32, i32), (E1Variant2, u32), (E1Variant3));
// An `Enum` declaration consisting of two variants and one additional member
Enum(Example2, (E2Variant1, i32), (E2Variant2, f32), float E2_member);

typedef enum Example3Enum {
    E3Variant1 = 0,
    E3Variant2
}

// An `Enum` declaration with two variants, using an existing enum to tag its variants.
// Note that the variant names exactly match the `enum` members, as they must
EnumWithTag(Example3, Example3Enum, (E3Variant1, i32), (E3Variant2, f64));

There are several abstractions that make working with Enums simple and concise, such as pattern matching and conditional binding. Pattern matching is semantically similar to switch statements, but unlike switch, does not require the break keyword to prevent cascading. Binding abstractions allow for extracting an enum variant's constituent members and assigning them to new variables. Binding is always done by value; to discourage mutating an enum in place, reference binding must be done manually.

Example:

// we recommend `#define`ing constructor-macros to simplify creating `Enum` variants
#define E1Variant2(first_int, second_int) \
    (Example){                            \
        .tag = E1Variant1,                \
        .variant_identifier(E1Variant2) = {  \
            (first_int),                  \
            (second_int)},                \
        },                                \
    }

// take an `Example1` `Enum` from above as a function parameter
void example1(Example1 var) {

    // pattern match on the variant `var` currently is.
    // Note that while some branches bind variables to variant members in this example,
    // binding is optional, and pattern matching without binding is perfectly valid
    match(var) {
        // if `var` is the `E1Variant1` variant, this branch will be taken and `first_int` and
        // `second_int` will be bound to the members of the variant
        variant(E1Variant1, first_int, second_int) {
            println("E1Variant1: [first_int: {}, second_int: {}]", first_int, second_int);
        }
        // if `var` is the `E1Variant2` variant, this branch will be taken and `u32_value`
        // will be bound to the member of the variant
        variant(E1Variant2, u32_value) {
            println("E1Variant2: [u32_value: {}]", u32_value);
        }
        // if `var` is the `E1Variant3` variant, this branch will be taken. As `E1Variant3` has
        // no members, we can't bind any variables with this branch.
        variant(E1Variant3) {
            println("E1Variant3");
        }
    }
}

void example2(Example1 var) {
    // variants we don't care about explicitly matching can be globbed with `wildcard()`
    match(var) {
        variant(E1Variant1) {
            println("E1Variant1");
        }
        wildcard() {
            println("Not E1Variant1");
        }
    }
}

void example3(Example1 var) {
    // conditionally bind if `var` is the specified variant
    match_let(var, E1Variant1, first_int, second_int) {
        println("E1Variant1: [first_int: {}, second_int: {}]", first_int, second_int);
    }
    else {
        println("Not E1Variant1");
    }
}

void example3(Example1 var) {
    // can `match_let` without binding
    match_let(var, E1Variant1) {
        println("Is E1Variant1");
    }
    else {
        println("Not E1Variant1");
    }
}

void example4(Example1 var) {
    // check is `var` is the specifier variant
    if(is_variant(var, E1Variant1)) {
        println("Is E1Variant1");
    }
    else {
        println("Not E1Variant1");
    }
}

Defines

#define Enum(Type, ...)
Declares and defines an Enum, Type, with the given variants and additional members.
#define EnumWithTag(Type, TagType, ...)
Declares and defines an Enum, Type, using an existing C-style enum, TagType, to tag/identify its variants.
#define match(x)
Pattern matches on the given Enum, x Pattern matching works similarly to switch statements, but with slightly different semantics. First off, pattern cases are declared with variant(...), which can, in addition to match the variant, optionally decompose the variant into one or more bound variables. Bound variables are bound by value, as decomposing a variant during pattern matching is intended to be consuming, so mutating the Enum variant's members in place is not possible without manually doing so. Second, fallthrough is not possible, so breaking to prevent it is not necessary.
#define variant(...)
Declares a pattern-matching case in a match statement Pattern-matching cases declare a variant to match against and, in addition, can optionally decompose the variant into one or more bound variables. Bound variables are bound by value, as decomposing a variant during pattern matching is intended to be consuming, so mutating the Enum variant's members in place is not possible without manually doing so. Unlike switch statements, fallthrough is not possible in match statements, so breaking between variant(...)s is not necessary.
#define wildcard()
Declares a catch-all pattern-matching case in a match statement This will match all variants that have not been explicitly matched against prior. Unlike switch statements, fallthrough is not possible in match statements, so breaking between variant(...)s is not necessary.
#define match_let(self, ...)
Conditionally pattern matches on the given Enum, self match_let works similarly to an if statement, but with slightly different semantics. First off, in addition to conditionally branching if self is the given variant, it can optionally decompose the variant into one or more bound variables. Bound variables are bound by value, as decomposing a variant during pattern matching is intended to be consuming, so mutating the Enum variant's members in place is not possible without manually doing so.
#define is_variant(self, Variant)
Determines if self is the Enum variant Variant
#define extract_variant(self, Variant)
Extracts the internal value of self as the variant Variant
#define variant_identifier(Variant)
Generates the member identifier for an Enum variant, Variant, used in the struct definition of an Enum

Define documentation

#define Enum(Type, ...)
#include <include/Cnx/Enum.h>

Declares and defines an Enum, Type, with the given variants and additional members.

Parameters
Type - The name for the Enum
... - The list of variant tuples and additional members

Enum declarations consist of a type name, followed by one or more variant layouts, followed by zero or more additional member declarations. Variant layouts are tuples of the form (VariantName, MemberTypes...) where VariantName is required, and MemberTypes can be zero or more type names (such as int, CnxString, or struct timespec).

#define EnumWithTag(Type, TagType, ...)
#include <include/Cnx/Enum.h>

Declares and defines an Enum, Type, using an existing C-style enum, TagType, to tag/identify its variants.

Parameters
Type - The name for the Enum
TagType - The C-style enum to use to identify the Enums variants. The enum's members' identifiers must exactly match the names of the Enum's variants.
... - The list of variant tuples and additional members

Enum declarations consist of a type name, followed by one or more variant layouts, followed by zero or more additional member declarations. Variant layouts are tuples of the form (VariantName, MemberTypes...) where VariantName is required, and MemberTypes can be zero or more type names (such as int, CnxString, or struct timespec). Enum declarations may alternately use a predefined C-style enum type for identifying their variants. In this case, the C-style enum's members' identifiers must exactly match the names of the Enum's variants.

#define match(x)
#include <include/Cnx/Enum.h>

Pattern matches on the given Enum, x Pattern matching works similarly to switch statements, but with slightly different semantics. First off, pattern cases are declared with variant(...), which can, in addition to match the variant, optionally decompose the variant into one or more bound variables. Bound variables are bound by value, as decomposing a variant during pattern matching is intended to be consuming, so mutating the Enum variant's members in place is not possible without manually doing so. Second, fallthrough is not possible, so breaking to prevent it is not necessary.

Parameters
x - The Enum to pattern match on

Example:

Enum(Example, (Variant1, i32, i32), (Variant2, f32, f32), (Variant3));

void example(Example var) {
    match(var) {
        variant(Variant1, first_i32, second_i32) {
            println("Variant1: [first: {}, second: {}]", first_i32, second_i32);
        }
        variant(Variant2, first_f32, second_f32) {
            println("Variant2: [first: {e}, second: {e}]", first_f32, second_f32);
        }
        variant(Variant3) {
            println("Variant3");
        }
    }
}

#define variant(...)
#include <include/Cnx/Enum.h>

Declares a pattern-matching case in a match statement Pattern-matching cases declare a variant to match against and, in addition, can optionally decompose the variant into one or more bound variables. Bound variables are bound by value, as decomposing a variant during pattern matching is intended to be consuming, so mutating the Enum variant's members in place is not possible without manually doing so. Unlike switch statements, fallthrough is not possible in match statements, so breaking between variant(...)s is not necessary.

Parameters
... - The variant name, followed by any decomposition variable names to bind the variant's members to

Example:

Enum(Example, (Variant1, i32, i32), (Variant2, f32, f32), (Variant3));

void example(Example var) {
    match(var) {
        variant(Variant1, first_i32, second_i32) {
            println("Variant1: [first: {}, second: {}]", first_i32, second_i32);
        }
        variant(Variant2, first_f32, second_f32) {
            println("Variant2: [first: {e}, second: {e}]", first_f32, second_f32);
        }
        variant(Variant3) {
            println("Variant3");
        }
    }
}

#define wildcard()
#include <include/Cnx/Enum.h>

Declares a catch-all pattern-matching case in a match statement This will match all variants that have not been explicitly matched against prior. Unlike switch statements, fallthrough is not possible in match statements, so breaking between variant(...)s is not necessary.

Example:

    Enum(Example, (Variant1, i32, i32), (Variant2, f32, f32), (Variant3));
   
    void example(Example var) {
        match(var) {
            variant(Variant1, first_i32, second_i32) {
                println("Variant1: [first: {}, second: {}]", first_i32, second_i32);
            }
            wildcard() {
                println("Not Variant1");
// }
        }
    }

#define match_let(self, ...)
#include <include/Cnx/Enum.h>

Conditionally pattern matches on the given Enum, self match_let works similarly to an if statement, but with slightly different semantics. First off, in addition to conditionally branching if self is the given variant, it can optionally decompose the variant into one or more bound variables. Bound variables are bound by value, as decomposing a variant during pattern matching is intended to be consuming, so mutating the Enum variant's members in place is not possible without manually doing so.

Parameters
self - The Enum to pattern match on
... - The variables to bind the enum variant's members to

Example:

Enum(Example, (Variant1, i32, i32), (Variant2, f32, f32), (Variant3));

void example(Example var) {
    match(var) {
        variant(Variant1, first_i32, second_i32) {
            println("Variant1: [first: {}, second: {}]", first_i32, second_i32);
        }
        variant(Variant2, first_f32, second_f32) {
            println("Variant2: [first: {e}, second: {e}]", first_f32, second_f32);
        }
        variant(Variant3) {
            println("Variant3");
        }
    }
}

#define is_variant(self, Variant)
#include <include/Cnx/Enum.h>

Determines if self is the Enum variant Variant

Parameters
self - The Enum to check
Variant - The variant to check if self is
Returns whether self is the Variant variant

Example:

Enum(Example, (Variant1, i32, i32), (Variant2, f32, f32), (Variant3));

void example(Example var) {
    if(is_variant(self, Variant2)) {
        println("Is Variant2");
    }
    else {
        println("Not Variant2");
    }
}

#define extract_variant(self, Variant)
#include <include/Cnx/Enum.h>

Extracts the internal value of self as the variant Variant

Parameters
self - The Enum to extract
Variant - The Enum variant to extract self as
Returns self's internal value, as Variant

If self is the variant Variant, extracts the internal value of self as that variant, so it can be used for further processing.

Example:

Enum(Example, (Variant1, i32, i32), (Variant2, f32, f32), (Variant3));

void example(Example var) {
    let variant2 = extract_variant(var, Variant2);
    println("first: {}, second: {}", variant2._1, variant2._2);
}

#define variant_identifier(Variant)
#include <include/Cnx/Enum.h>

Generates the member identifier for an Enum variant, Variant, used in the struct definition of an Enum

Parameters
Variant - The name of the Enum variant
Returns The identifier used for Variant in an Enum struct definition