How stable is the atom representation of gleam types, alternativly atom litterals?

[erlend-axelsson]

tldr: is it a safe assumption that this

Ok(SomeValue)

will be represented as this in Erlang?

{ok, SomeValue}

I've been playing around a bit with ffi in gleam, and I feel it's a bit cumbersome when dealing with return types, especially when it comes to tuples and atoms. From what I can tell gleam seems to handle {snake_case_atom, SomeValue} -> SnakeCaseAtom(SomeValue) which means I can do stuff like:

-spec is_one(MaybeOne) -> {ok, binary()} | {error, binary()} when MaybeOne :: integer().
is_one(MaybeOne) ->
  case MaybeOne of
    1 -> {ok, <<"it is one"/utf8>>};
    _ -> {error, <<"it is not one"/utf8>>}
  end.

@external(erlang, "my_module", "is_one")
fn is_one(maybe_one: Int) -> Result(String, String)

But it feels quite hacky, because as far as I know this is internal implementation details and not part of "language contract", which means I can't rely on it still working in future versions.

But on the other hand doing this the 'right way' also feels quite cumbersome especially since we can't really pattern match on atoms which are more or less ubiquitous in Erlang-Land:

// lets pretend the inner types has some stuff in them
pub type InnerFooType {
  InnerFooType
}

pub type InnerBarType {
  InnerBarType
}

pub type MyNestedType {
  NestedFooType(foo_type: InnerFooType)
  NestedBarType(bar_type: InnerBarType)
}

pub fn my_pub_gleam_function(a: a, b: b) {
  let dynamic_return_value = my_priv_gleam_function(a, b)

  use partial_decoded <- result.try(dynamic.tuple2(
    atom.from_dynamic,
    dynamic.dynamic,
  )(dynamic_return_value))
  let foo_atom = get_atom("foo")
  let bar_atom = get_atom("bar")
  case partial_decoded {
    #(atm, dyn_value) if atm == foo_atom ->
      decode_inner_foo(dyn_value)
      |> result.map(fn(inner_foo) { Ok(NestedFooType(inner_foo)) })
    #(atm, dyn_value) if atm == bar_atom ->
      decode_inner_bar(dyn_value)
      |> result.map(fn(inner_bar) { Ok(NestedBarType(inner_bar)) })
    _ -> Error([dynamic.DecodeError("unknown atom", "foo | bar", [])])
  }
}

fn get_atom(string_rep: String) -> atom.Atom {
  case atom.from_string(string_rep) {
    Ok(atm) -> atm
    Error(atom.AtomNotLoaded) -> atom.create_from_string(string_rep)
  }
}

fn decode_inner_foo(
  _dyn_value: dynamic.Dynamic,
) -> Result(InnerFooType, List(dynamic.DecodeError)) {
  // bunch of decoding logic
  // ...
  Ok(InnerFooType)
}

fn decode_inner_bar(
  _dyn_value: dynamic.Dynamic,
) -> Result(InnerBarType, List(dynamic.DecodeError)) {
  // bunch of decoding logic
  // ...
  Ok(InnerBarType)
}

@external(erlang, "my_module", "my_erl_function")
fn my_priv_gleam_function(a: a, b: b) -> dynamic.Dynamic

@external(erlang, "my_module", "my_erl_function_using_undefined_behaviour")
fn my_priv_gleam_function_using_undefined_behaviour(a: a, b: b) -> MyNestedType

There are probably good reasons why not, but right now I feel like I really want to have language support for atom litterals and a way to pattern match on dynamic.Dynamic.

fn stuff_i_think_i_want(some_dynamic_value: dynamic.Dynamic) {
  case some_dynamic_value {
    #(:a_literal_atom, value) -> Ok(some_func(value))
    _ -> Error("oh no!")
  }
}

[lpil]

Hello! Yes, the representation is part of the Gleam's API.

Atoms will not be added to the language, they encourage very poor type design (being strings at the end of the day) and should be kept as an implementation detail.

[erlend-axelsson]

Ok, thanks for clearing that up. I might submit a small pr to the website repo documenting some of this once I figure out how to make ruby actually cooperate with my system.

IE. something along the lines of 'Runtime representation of Gleam types' or something.

[lpil]

There's an issue for an FFI writing guide, but it has not been started yet

[erlend-axelsson]

I've been writing some stuff, so far I've covered built-ins, and the non-opaque standard lib types up to iterator.Step.
The remaining bits are the rest of the standard lib, some examples with custom types and some written explanations as at the moment it's only a bunch of code snippets.
Pretty sure it'll also need some proofreading and writing-style adjustments to make it fit better in with what is on the website already.

Format as of now:

[section header (built-in | Standard library | Custom-types)]
--[sub header ($TYPE)]
----[gleam snippet using type]
----[javascript implementation snippet]
----[erlang implementation snippet]

So far I've attempted not to lean too much on the stdlib functions in the javascript and erlang examples as I feel that somewhat defeats the purpose of showing how the types work 'under the hood'.

Ie.

% 'native' example
example_one() ->
  #{<<"gleam"/utf8>> => <<"lang"/utf8>>}.

% stdlib example
example_two() ->
  Dict = gleam@dict:new(),
  gleam@dict:insert(Dict, <<"gleam"/utf8>>, <<"lang"/utf8>>).

[lpil]

I don't think we would want to on the website have an exhaustive overview of all the stdlib, rather we would want to explain the rules for each kind of datatype and then have guidance on how to use externals well in libraries and applications.

An exhaustive document could be a good community reference though!

[erlend-axelsson]

Sure, I'll share what I've written once I'm done, and you guys can decide if/when/how to use it after that.
Seeing that it's simply a .md file I might as well put it in a public Gist and ping you when it's done.