Typespec for Enumerable

Questions / Help
, ,
1

I wrapped an API using pagination with Stream.unfold so that it returns Enum.t (Enumerable.t).

Is it possible to specify @spec of values that will be yield from the Enumerable struct?

2

You can of course write a spec for your function, where you say what type of values are returned. But you cannot derive it from the type spec of the enumerable or the stream itself. This has two reasons: First, the type of an enumerable, Enum.t has no type parameter, which would constraint an enumerable to, say an enum of integers. Secondly, the missing strict static typing of Elixir allows for putting all kinds of values into an enumeration. That is the reason why in the API of Enumerable the type element is only an alias of any.

What you can do is to spec your function in way to say it returns a list of a specific element type, e.g. list(integer). The diaylzer can then check, whether this specification is fulfilled in your program.

3

Oh, list(integer) trick would do the trick. Thanks!

However, I think then it gives incorrect info. For example, as I use Stream, it does not have all functions of List.

Enum.t is just Enumerable.t (ref) and I guess Enumerable.t is defined from Protocol (ref). It looks like it is possible to pass @t when using defprotocol - but I’m not sure it is possible to pass type parameter down to that part. Hm.

4

It depends what you want to do with the type specification. If it should be a help for the reader or programmer, than you can define your enumeration type for your API, e.g. something like

@opaque my_enum(t) :: list(t) | Enum.t

This compiles, reveals no details about the internal of type (thus @opaque) and you communicate your intention. But the dialyzer cannot help at finding type errors. The following snippet is wrong, but dialyzer does not complain:

  @opaque my_enum(t) :: Enum.t | Enumerable.t | list(t)

  @spec take_ten(integer) :: my_enum(integer)
  def take_ten(max) do
    max
    |> Stream.unfold(fn 0 -> nil; n -> {n, n-1} end)
    |> Stream.take(10)
  end

  @spec ten_ints() :: list(atom)
  def ten_ints() do
    take_ten(20) |> Enum.to_list()
  end

I assume that it comes from type union. It could be a list of atoms, because the stream functions are allowed to return enumerable of any type. And you cannot use Enum.t(integer) because it is not defined in the Enum module. This could be an interesting bug report and PR for the Enum module, because you could define type t this way:

@type t :: t(any)
@type t(x) :: Enumerable.t(x)

You need to specify properly all enum functions to take parameterized types. But I am unsure how the type definition on the protocol level works, in particular since Enumerable.t is not defined explicitly but seems to generated by defprotocol.

1 Like