[subRFC] Discriminated Unions / Enums

[lachlansneff]

Discriminated Unions / Enums

This (sub)RFC builds on #697. As proposed in #697, first-class discriminated unions could be very useful.

Motivation

While discriminated/tagged unions can be built on top of data.Struct and data.Union, first-class support may improve readability and correctness of code.

Overview and Examples

from amaranth import *
from amaranth.lib import data

# Declare a discriminated union.
class Op(data.Enum):
    Add: unsigned(16)
    Mul: unsigned(16)

# Creating an `Op` signal can only be done through one of its variants.
op_a = Op.Add()
# Or
op_b = Op.Add(42)

# Enums can be accessed with `m.IfLet`.
with m.IfLet(op_a, Op.Add) as imm:
    m.d.sync += op_a.eq(Op.Mul(imm + 1))

# Enums can be equated as well.
with m.If(op_a == Op.Mul(43)):
    ...

# Or, it can be accessed with `m.Match`.
with m.Match(op_a):
    with m.Case(Op.Mul) as imm:
        m.d.sync += imm.eq(3)

# If the data associated with multiple variants is the same, you can match multiple.
with m.Match(op_a):
    with m.Case(Op.Mul | Op.Add) as imm:
        ...

# An enum with no annotations has no associated data and and the tag values can be specified
class Animal(data.Enum):
    Elephant = 0
    Cat = 1

Detailed Design

This subRFC proposes several language and library additions:

• A new data.Enum class.
• Two new methods on Module: m.Match and m.IfLet.

Alternatives

• Don't add this because it adds complexity and links between amaranth.hdl and amaranth.lib.
• Simplify this to remove some features (or-ing and data-less enums would probably be the best to remove).

Open Questions

• Should there be a fancy way to descend/match into nested Enums?
• Is Enum a good name for this? It conflicts with the built-in enum.Enum. DiscriminatedUnion or TaggedUnion would both be precise, but they're pretty wordy.
• Should there be a way to access the tag/discriminant by itself? Related to this: Should there be a way to set particular tag values?

[whitequark]

Thank you for submitting this RFC, @lachlansneff! We have extensively discussed it during the 2023-02-20 weekly meeting; see the transcript.

The resolution was close, as there are several major concerns with this RFC:

1. The "Detailed design" section unfortunately does not include the detailed design.
2. It is not clear whether Op.Add(42) returns a view of a Signal with 42 included in the reset value, or a Const. If it is the latter, we do not currently have precedent for such polymorphism. (by @jfng)
3. The lack of ability to perform nested matching with the proposed syntax greatly limits usefulness compared to e.g. Rust's match construct. The equivalent of e.g. match x { Foo { a: A(y), b: B(z) } => ... } in Rust would require three nested matches to bind all the variables, and six levels of indentation. Similarly, the RFC does not explain how constructing variants where the payload is a structure would work; if the answer to point (2) is that it returns a Const, then how is the type of the return value determined when the payload is a structure?
4. It is not clear why the proposed mechanism should be restricted to discriminated unions with a layout specified by Amaranth. A general purpose matching mechanism could be useful, and may also handle cases where the dependencies between fields are determined by something other than a dedicated discriminant; for example, a data field could be valid only if length != 0. (by @rroohhh)

A follow-up RFC that proposes a general purpose pattern matching construct and addresses all of the concerns raised during the meeting could be useful. However, it is not clear that such a construct can be implemented within the constraints of Python.