Allow explicit enum values

[harrisi]

This PR adds the ability to set values for enums, so this type of C code can be generated:

enum Foo {
  FOO_A = 1,
  FOO_B,
  FOO_C = 4
};

The syntax I went with is the following:

type foo :: {:a, 1} | :b | {:c, 4}

The only real alternative I could think of would be something like this:

type foo :: :a = 1 | :b | :c = 4

I don't like this, since it's nonsensical in normal Elixir.

I originally thought a list would be okay, something like this:

type foo :: [a: 1, b: 2, c: 3]

But this doesn't allow for partially explicit definitions, unless all the explicit definitions are at the end (to make it a valid keyword list), so the above definition isn't possible:

type foo :: [a: 1, :b, c: 3] # this doesn't work

I think the desugared pseudo-keyword list is a decent option. It seems less weird than writing :a = 1 to me, anyway. It could also be defined as a list (e.g., [:a, 1] | :b), but that seems confusing since [type] is meaningful elsewhere.

[mat-hek]

👋 thanks for the PR 😉 Personally I find quite unobvious that the alternative of tuples maps to an enum 🤔 What about

@type foo :: enum(a: 1, b: 2)
@type foo :: enum({:a, 1} | {:b, 2})
@type foo :: enum_value(:a, 1) | enum_value(:b, 2)

I like the last one the most, except that enum_value is extremely long. WDYT @FelonEkonom?

[harrisi]

I agree it's not the best syntax, so I'm happy to see more suggestions.

Something all three of your suggestions highlight is the use of the word "enum". I think it would be helpful to change the spec dsl to use enum instead of type in general.

[FelonEkonom]

@type foo :: enum_value(:a, 1) | enum_value(:b, 2)

I think this option is the best of the three you mentioned.

@harrisi even if we would introduce @enum, we have to still support @type, because of the backwards compatibility.

The general disadvantage of using names with enum is that it might make an impression that it has something to do with Enum from Elixir standard library, while it doesn't.

WDYT about something like

@type my_type :: (:a :: 1) | :b | (:c :: 100)

[harrisi]

The general disadvantage of using names with enum is that it might make an impression that it has something to do with Enum from Elixir standard library, while it doesn't.

I hadn't thought about this, but good point. Having two ways of defining enums (with type and enum) doesn't seem worth it.

The main issue I have with using something like enum_value(:a, 1) is what happens if I define a function called enum_value already? It probably won't break anything, but it's certainly weird.

@type my_type :: (:a :: 1) | :b | (:c :: 100)

The precedence makes it so that parsing this is either very strange, or the parentheses are mandatory, which seems weird.

Without parentheses:

{:@, [context: Elixir, imports: [{1, Kernel}]],
 [
   {:type, [context: Elixir],
    [
      {:"::", [],
       [
         {:my_type, [], Elixir},
         {:"::", [],
          [:a, {:"::", [], [{:|, [], [1, {:|, [], [:b, :c]}]}, 100]}]}
       ]}
    ]}
 ]}

with parentheses:

{:@, [context: Elixir, imports: [{1, Kernel}]],
 [
   {:type, [context: Elixir],
    [
      {:"::", [],
       [
         {:my_type, [], Elixir},
         {:|, [],
          [{:"::", [], [:a, 1]}, {:|, [], [:b, {:"::", [], [:c, 100]}]}]}
       ]}
    ]}
 ]}

[mat-hek]

Right, another idea:

@typemap a: 1, c: 100
@type my_type :: :a | :b | :c

[harrisi]

Having the definitions be separate seems weird, since there's a whole new type of errors to handle. What if the typemap includes extra keys? Should the order matter? Etc.

I'm not sure how y'all feel about it, but I'm kind of coming back around to the :a = 1 | :b | :c = 4 option. Any thoughts on that?

[mat-hek]

Yeah, unfortunately, all the approaches are a bit weird, because we're trying to connect two totally different worlds :P I'd lean towards the typemap thing, as it's not using syntax that has very different semantics in regular Elixir/specs, cc @FelonEkonom

What if the typemap includes extra keys?

I think it's ok to raise an error

Should the order matter?

The order would be as in the @type, just like it is now. The order in the typemap doesn't seem to matter.

[harrisi]

I think it's ok to raise an error

Yeah, I was more just bringing up that there exists a new class of error with a separate "typemap" that needs to be considered.

The order would be as in the @type, just like it is now. The order in the typemap doesn't seem to matter.

What I mean is typemap could be defined in any order, technically, which can cause issues with the enum generation if type is of a different order:

type foo :: :a | :b | :c
typemap foo :: [a: 1, c: 4]

# later on: "huh, you know, I think `b` should be defined after `c`, actually.."
type foo :: :a | :c | :b

# uh oh, the enum changed from `1, 2, or 4` to `1, 4, or 5`.

Obviously changing the order of enums requires care anyway, but having the definition be separated in two calls isn't something that's familiar in C, so it seems easier to miss and have weird things happen.

The fix for this would be to enforce typemap to be in the same order as type, which is fine, but makes implementing this more work.

I'm not too concerned about the syntax, so I'll just say my preference is either {:a, 1} or :a = 1. Happy to implement any option, though. Maybe over the weekend someone will figure out the best choice :)

[FelonEkonom]

@harrisi good point about paying attention to the order of fields in enum 👍

[FelonEkonom]

@harrisi after internal discussion we decided that we like the option with @type foo :: enum_value(:a, 1) | ... the most, so if you have time and will, you can implement this one. We would release it just after merging this PR.

Thanks 👍

[harrisi]

How would y'all feel about using a keyword list? Either instead of a 2-arity "function", or in addition to? So,

type foo :: enum_value(a: 1) | :b | enum_value(:c, 4)

would be valid if both are allowed? I don't love having two ways to define it, but the single element keyword list kind of feels better to me. It doesn't really make parsing meaningfully more complex to allow both.

[FelonEkonom]

IMO it seems weird to make enum_value accept keyword list with only one argument. Usually if a function in Elixir accepts a keyword list with unrestricted keys, there is no boundary on the length of this list (e.g. struct/2, maybe creating a new map doesn't require creating a keyword list, but the syntax is kind of similar, and there is no such a boundary there as well).

Personally I would stay with enum_value(:atom, 1) only

[harrisi]

Sounds good! Let me know if there's anything else to add.

[FelonEkonom]

@harrisi I don't see a need for anything else right now. Is this PR ready to review?

[harrisi]

Should be! :)

[FelonEkonom]

1. Fix failing tests, probably you will have to update fixture files.
2. Fix credo, try mix deps.update credo and see if it helps.

[harrisi]

Merged the credo update from #115, fixed a few errors, updated test fixtures.

Sorry, I thought I did those things already. Forgot where things were at in the few weeks break there!

Hopefully that resolves everything.

[FelonEkonom]

Beyond one comment to the docs everything looks fine

[FelonEkonom]

Please mention, that second argument passed to enum_value/2 can be used only in the code in C/C++ while Elixir API still supports only atoms