Volume 11: Enumerations¶

1. Introduction¶

This volume defines enumeration types in the Rethon programming language. It describes enumeration declarations, enumeration names, enumeration cases, simple enumerations, associated values, raw values, enum initialization, pattern matching considerations, methods, static members, visibility, protocol conformance, generic enumerations, equality and hashing, exhaustiveness, memory safety considerations, and future extension points.

This document is part of the official Rethon Language Specification. It is normative rather than descriptive. Implementations, tooling, documentation systems, and other source-processing tools shall treat the rules in this volume as authoritative.

This volume does not define backend representation details, ABI details, or runtime-specific implementation mechanisms. It defines the source-level and language-level behavior of enumeration types as programmer-visible nominal value types.

Rethon is Python-inspired in language philosophy and Python-first in surface syntax where practical. It uses static typing, enums as nominal types, value-oriented design, protocols as behavior contracts, explicit conformance, lowercase primitive types, and public-by-default visibility.

Enumerations shall be nominal value types.

Enumeration cases shall be values of the enumeration type.

2. Enumeration Declarations¶

An enumeration declaration shall introduce a named nominal value type.

An enumeration declaration shall use the enum keyword.

Example:

enum Color:
    red
    green
    blue

An enumeration declaration shall define a nominal type whose values are one of a fixed set of cases.

An enumeration declaration shall introduce a new type name and a new member scope for the cases and members declared within its body.

An enumeration declaration may appear at module scope or within other later-defined type or namespace constructs if the surrounding syntax permits it.

An enumeration body may contain simple cases, cases with associated values, raw-value declarations, methods, static members, and other later-defined member declarations.

An enumeration body shall use indentation-based structure.

An enumeration declaration shall be a declaration in the sense defined by the declarations and bindings volume.

An enumeration shall be a value type.

An enumeration shall not imply object identity by default.

3. Enumeration Names¶

An enumeration name shall be an identifier that names the enumeration declaration.

Enumeration names shall be case-sensitive.

Enumeration names should normally use PascalCase.

Examples:

enum Color:
    red

enum Result:
    success

An enumeration name shall not be reserved solely because it names an enumeration. Ordinary identifier rules shall apply, subject to keyword reservation and any later contextual restrictions defined by the language.

An enumeration name should clearly express the category of values being modeled.

Enumeration names should describe stable domain categories such as state, result, direction, option, kind, phase, or status.

Examples of preferable naming patterns include:

Color
Direction
Result
Status
TokenKind
ParseState

An enumeration name should not obscure meaning through unnecessary abbreviation when a clearer name is available.

4. Enumeration Cases¶

An enumeration case is one of the named values declared by an enumeration.

An enumeration may declare one or more cases.

Example:

enum Color:
    red
    green
    blue

Enumeration cases shall be part of the enumeration's declared value space.

Enumeration cases shall be visible according to the visibility rules established elsewhere in the specification.

Enumeration cases may be simple cases, cases with associated values, or cases that carry a raw value when the language rules permit it.

Enumeration cases shall be values of the enumeration type.

A case shall not be confused with a separate type identity.

A case shall not define storage by itself outside the enumeration value it represents.

5. Simple Enumerations¶

Simple enumerations shall be supported.

A simple enumeration is an enumeration whose cases carry no associated values and no raw values.

Example:

enum Direction:
    north
    south
    east
    west

A simple enumeration shall define a finite set of named values.

Simple enumeration cases shall be values of the enumeration type.

Simple enumerations shall be suitable for fixed categories, state machines, flags that are not bitwise, and other closed sets of named values.

Simple enumerations shall remain nominal and shall not rely on structural similarity.

6. Associated Values¶

Enumeration cases may carry associated values.

Example:

enum Result:
    success
    failure(message: str)

Associated values shall allow a case to store data as part of the enumeration value.

Associated values shall be statically typed.

Associated values shall follow the language's type system rules, including primitive types, value types, reference types, protocol types, nullable types, generic types, and type aliases.

A case with associated values shall remain a case of the enumeration type rather than becoming a separate ad hoc type.

Associated values shall be useful for result types, parse trees, command variants, event kinds, and other discriminated-union-style modeling.

Associated values shall remain compatible with value semantics and memory safety by default.

7. Raw Values¶

Enumeration cases may carry raw values when the language rules permit a raw-value form.

Example:

enum HttpStatus: int:
    ok = 200
    not_found = 404

A raw value shall be a compile-time associated value used to represent a case in a compact, explicit way.

The raw value type shall be explicitly declared and shall use a type expression permitted by the type system.

Raw values shall be carefully constrained and shall remain a source-level convenience rather than a hidden runtime mechanism.

A raw-value enumeration shall not use raw values as a substitute for general associated values.

A raw-value enumeration shall keep the underlying raw value visible in source code.

The language may later restrict raw values to a subset of types if that improves readability or maintainability, but the raw-value model shall remain explicit.

8. Enum Initialization¶

An enumeration shall be initialized by selecting one of its cases.

Example:

let color = Color.red
let result = Result.failure(message: "bad input")

An enumeration value shall be constructed through a case expression or another source-level form that identifies the case unambiguously.

If a case has associated values, those values shall be supplied according to the case's declared structure.

If a case has a raw value, the raw value may be used in a language-defined conversion or initialization form when that form is permitted.

An enumeration value shall be fully determined by its selected case and any associated or raw values.

Enumeration initialization shall not expose partially formed enum values.

9. Pattern Matching Considerations¶

Enumerations shall remain compatible with future pattern matching and destructuring features.

Example:

match result:
    case Result.success:
        ...
    case Result.failure(message: message):
        ...

The exact pattern matching syntax is defined elsewhere or in future specification work.

This volume establishes that enums are closed sets of cases and therefore natural candidates for exhaustive matching.

Pattern matching should eventually support exhaustiveness checking for enumerations when the compiler can determine the full set of cases.

10. Methods¶

Enumerations shall support methods.

A method is a function declared within an enumeration body and associated with that enumeration type.

Example:

enum Color:
    red
    green
    blue

    def is_primary(self) -> bool:
        return True

Methods shall be able to inspect the enumeration value according to the language's source-level rules.

Methods shall be part of the enumeration's source-level API and shall participate in ordinary scope and visibility behavior.

Methods declared inside an enumeration shall remain readable and consistent with the Python-like surface syntax that the language has already chosen.

A method shall not be required to imply hidden runtime behavior beyond the language rules defined in this specification.

11. Static Members¶

Enumerations shall support static members.

Static members shall be suitable for shared constants, helper functions, case collections, and other declarations that conceptually belong to the enumeration type.

Example:

enum Direction:
    north
    south
    east
    west

    static def all() -> list[Direction]:
        return [Direction.north, Direction.south, Direction.east, Direction.west]

A static member shall not require an enumeration value in order to be accessed.

A static member shall be associated with the enumeration type rather than with a specific case.

Static members shall obey the same visibility rules as other enumeration members.

12. Visibility¶

Enumerations and their members shall follow the visibility rules established elsewhere in the specification.

An enumeration declaration shall have a visibility level according to the declarations and bindings volume and the visibility direction ADR.

Enumeration cases, methods, static members, and associated declarations shall also obey visibility rules.

The default visibility for enumeration declarations and cases shall be public unless explicitly marked otherwise.

Private enumeration members shall be accessible only within the lexical region that defines them and any nested regions permitted by the language.

Visibility shall support encapsulation without undermining the readability of value-oriented design.

13. Protocol Conformance¶

Enumerations shall be able to conform to protocols.

Example:

enum Color: Printable:
    red
    green
    blue

    def print(self) -> None:
        ...

Protocol conformance shall be explicit.

An enumeration shall conform to a protocol only when the language's protocol rules are satisfied.

Conformance shall not be inferred merely from surface similarity.

Enumerations shall be able to conform to multiple protocols when their cases and methods satisfy the required contracts.

Protocol conformance shall support value-oriented programming by allowing enumerations to adopt reusable behavior contracts without introducing identity semantics.

14. Generic Enumerations¶

Generic enumerations shall be supported.

Example:

enum Option<T>:
    some(value: T)
    none

A generic enumeration shall remain a value type.

Generic enumerations shall integrate with the type system and generic constraints defined elsewhere in the specification.

A generic enumeration may use protocol-based constraints on its type parameters.

Example:

enum Box<T: Printable>:
    value(item: T)

Generic enumeration values shall preserve value semantics across type instantiations.

Generic enumeration declarations shall remain readable and explicit.

15. Equality and Hashing¶

Equality and hashing for enumerations shall be protocol-based.

An enumeration shall not automatically acquire equality or hashing behavior merely because it is an enumeration.

If an enumeration participates in equality or hashing, it shall do so by conforming to the appropriate protocol or equivalent language-defined contract.

The language may later allow synthesized equality or hashing conformance for straightforward cases, but the source-level model shall remain explicit and protocol-based.

Equality and hashing semantics shall be stable, predictable, and consistent with value semantics.

16. Exhaustiveness¶

Enumerations shall be suitable for exhaustive reasoning.

Because an enumeration defines a closed set of cases, the compiler should eventually be able to determine when all cases have been handled in a pattern match or equivalent branching construct.

Exhaustiveness checking shall be source-level and shall not require backend details.

If the language later introduces additional cases or open-ended enum forms, those forms shall be explicitly marked so that exhaustiveness rules remain understandable.

17. Memory Safety Considerations¶

Enumerations shall participate in the language's memory-safety model.

Enumeration values shall be safe to construct, copy, pass, return, and match according to the value semantics of the language.

Associated values may include references or values of other types, but the enumeration itself shall remain a value type.

Enumeration construction shall not expose partially initialized values.

Raw values, when used, shall remain explicit source-level contracts rather than hidden runtime state.

18. Future Extensions¶

This volume defines the current direction for enumerations in Rethon, but future specification work may refine the model in carefully controlled ways.

Possible future extensions include:

richer pattern matching syntax
additional raw-value constraints
explicit synthesized equality or hashing rules for simple enums
nested enum case syntax refinements
tuple-like case shorthand if later justified
case-specific visibility refinements if needed
additional enum metadata for tooling, provided it remains source-visible and non-semantic unless explicitly defined otherwise

Any future extension shall preserve the current direction:

enumerations are nominal value types
cases are values of the enumeration type
simple and associated-value cases are supported
raw values remain explicit and carefully constrained
protocols remain the preferred behavior-contract mechanism
equality and hashing remain protocol-based by default
exhaustiveness remains a design goal for pattern matching

19. Summary¶

Enumerations shall be nominal value types in Rethon.

Enumeration cases shall be values of the enumeration type.

Simple enumerations, associated values, raw values, methods, static members, protocol conformance, and generic enumerations shall be supported.

Equality and hashing shall remain protocol-based, with future synthesis possible if it remains explicit and contract-based.

Enumerations shall therefore fit Rethon's value-oriented, protocol-oriented, Python-first design while remaining suitable for static typing and future exhaustiveness checking.