Enum design

[vladfaust]

By default, a enum is a thin wrapper around <SSize>, which is the word size of target machine.
An integral element token doesn't have a determined integral counterpart by default, it is defined during compilation.
Explicitly setting an element value entangles it with the outer world, mapping it 1:1 to the integral counterpart.
An attempt to construct a enum with a specific integer may throw if the value is untangled.

To allow members in a enum type, an element shall be defined in the manner similar to a field definition.
Keyword erata (https://en.wiktionary.org/wiki/erata) is used to define a element.

The syntax enables methods for a enum type.
Within a enum method, this is a calller copy.
By default, a enum defines ==(arg : self) : Bool and numeric() : Type.
A enum may inherit another enum of the same underyling type (conflicting element values would panic), or derive from one or more traits.

A enum instance may be switched upon its element token, which can be symbolized and then tokenized back.
A symbolized name may only be tokenized if its unambiguous in the context of the tokenization site (not on the caller site).

import { print } from "std/terminal"
import { assert } from "std/test"

enum Foo {      # Implicitly `enum Foo<SSize>`
  erata Bar     # The value is unknown
  erata Baz = 1 # Implicitly `SSize(1)`
  erata Qux
  erata Quux = -1

  # NOTE: I like `: T` over `-> T`, because it's more intuitive.
  def to<T : String>() : T {
    switch (this) {
      case Bar then return "Bar" # Directly accessible in this scope
      case Foo::Bar {       # Otherwise accessed like so
        return "Bar"
      }

      # Tokenize to `Qux` and `Quux`, which exist in this scope.
      # NOTE: Square brackets are bad choice due to container (i.e. array) literals used in compile-time?
      case :qux, :quux {
        return "Qux or Quux"
      }

      # some_code() # => Panic! Expected `case` or `}`
    }
  }
}

try {
  # NOTE: `==(arg : self) : Bool` is defined implicitly, i.e. no other types.
  # This allows to tokenize `:baz` here.
  # NOTE: `|.` is the self-pipe operator [1].
  assert(Foo(1) == Foo::Baz |.== Foo(:baz) |.== :baz) # OK
  assert(Foo(0) == Foo::Bar)                          # Would throw
} catch ((e ~ EnumError) => {
  print("#{ \e }: #{ e.value }) # -> EnumError<Foo>: 0 (`:bar` is free)
})

# Note how `:baz` can be tokenized because of
# `def Foo::Bar.==(arg : self) : Bool`.
# `!(Foo::Bar.==(Foo(:baz)))` is implied.
assert(Foo::Bar != :baz)

# :bar.to<String>()                    # => Panic! `:bar` can't be tokenized
assert(Foo::Bar.to<String>() == "Bar") # OK

final foo = Foo(-1)
assert(foo.to() == "Qux or Quux") # OK (`to<String>` is inferred)

1. See https://github.com/fancysofthq/onyx-ref/blob/57aee8bbc7f4a82c385586ab5220562b0520ff43/index.adoc#piping

Alternatively, if a enum body begins with a token, then the whole body is expected to consist of comma-separated element definitions with erata keyword implied.
Similar concept exists in struct-record difference.

A enum type may be defined with a bitwise keyword instead, which would ensure its tokens only have values of power of two.
(TIP: Think of it as if it was def integral enum and def bitwise enum).

A bitwise enum is implcitly <USize> by default.
Bitwise arithmetic is defined for a bitwise enum type.

bitwise Access {   # Implicitly `bitwise Access<Usize>`
  Read,            # Value is unknown
  erata Write = 1, # May be explicit
  Delete = 128
}

(Access::Read | :delete).numeric()                 # The result is undefined, but it works
assert((Access::Write | :delete).numeric() == 129) # OK

A enum type may also be used as literal restriction, whereas a enum token may be used as a template argument.

class User {
  final name : String
  static self(name) -> self({ name })

  def open<CallAccess ~ \Access>(path : String) {
    \{%
      if nx["CallAccess"] ^ :read # Would work in Ruby!
        emit "this.check_admin() # May throw"
      end
    %}
  }

  def check_admin() -> if (this.name == "John") then throw "Nope"
}

# Ensure access in compile time!
final name = "John"
User(name).open<:write | :delete>("/") # -> Exception! Nope

[vladfaust]

I feel like erate is better than erata.

[vladfaust]

Per discussion in the Telegram chat, untangled values are rarely usable.
Therefore rules similar to Crystal's shall be applied, i.e. begin with zero and auto-increment by one.
Extending a enum isn't a way to go due to dependency on extension order.
Enum inheritance is still valuable, though.

enum Foo {   # Implicitly `Foo<SSize>`
  Bar,       # Implicitly 0
  Baz = 2,   # Explicitly 2
  Qux,       # Implicitly 3
  Quux = -1, # Explicitly -1
  Quuux      # -2 or 4?
}

# Out-of-scope definition of a method.
def Foo.to<T: String>() : String {
  switch (this) {
    # NOTE: Experimenting w/ waterfall.
    case Bar: 
    case Baz:
      return "Bar or Baz"
    case :qux: { # Does it look good?
      return "Qux"
    }
    
    # NOTE: It looks weird without a newline.
    case Quux, :quuux: return "Quux or Quuux"

    default:
      @unreachable()
  }
}

assert(Foo::Bar.to() == "Bar or Baz") # OK

enum NewFoo : Foo {
  Kaex # Implicitly -3 or 5?
}

# NewFoo::Bar.to<String>() # => Panic! Unreachable intrinsic is reached

Disallowing enum extension would however prohibit deriving a trait later.
Do we want a enum to derive a trait at all?
Deriving some Stringifyable trait does make sense.

What if a enum extension disallowed to define new elements, but only methods and static members?
The main issue is undefined extension ordering; with an undefined ordering you can't predict an element value.

extend Foo : Stringifyable {
  impl ~Stringifyable.to() {
    # ...
  }
}

Having an ability to derive from a trait implies the need to be able to operate on member ions within the original enum definition as well.
For that to work, some way to distinctively define an element shall be defined.
That's where the new keyword proposal comes into play: erata?

enum Foo : Stringifyable {
  erata Bar
  erata Baz
  erata Qux

  impl ~Stringifyable.to() {
    switch (this) {
      # Macros would allow the enum to be inherited without code breaking.
      \{% nx["self"].eratas.each do |erata| %}
        \{{ "case #{ erata.token }: return #{ erata.token.stringify }" }}
      \{% end %}
    }
  }
}

[vladfaust]

erata enables documentation and annotation application.

enum Foo {
  # A documentation for `Bar`.
  @[SomeAnnotation]
  erata Bar # Just a comment
}