Dynamically generate typespecs from module attribute list

I was hoping I could get something like this working:

defmodule FooRegistry do
  @foos [
    FirstFoo,
    SecondFoo,
    ThirdFoo
  ]
  
  @foos_by_another_name Enum.into(foos, %{}, fn foo -> {foo.another_name(), foo} end)

  @type foo [Enum.map(@foos, fn foo -> foo.t end)]

  @spec list_foos() :: [foo]
  def list_foos() do
    @foos
  end

  @spec foo_from_another_name(atom) :: foo | nil
  def foo_from_another_name(name) do
    Map.get(@foos_by_another_name, name)
  end
end

I’m not really worried about the exact syntax, but how might I go about dynamically generating a type like this?

Thanks!

1 Like

I guess the type declaration would somehow need to actually be separated by | so that Enum.map would naturally not work.

@zachdaniel: You need to write helper module with some macros and then call them to generate ast for special module attributes like @type.
For @type you need to return ast in format:

# root element in case @foos count greater than 2:
{
  :|,
  [],
  children
}
# root element in case @foos count is equal to 2:
{
  :|,
  [],
  [FirstFoo.t, SecondFoo.t]
}
# root element in case @foos count is equal to 1:
FirstFoo.t
# root element in case @foos count is equal to 0:
raise error

Where for children you have same rules as for root element, so for 3 foos:

{
  :|,
  [],
  [
    FirstFoo.t,
    {
      :|,
      [],
      [
        SecondFoo.t,
        ThirdFoo.t
      ]
    }
  ]
}

and this ast for you will look like:
FirstFoo.t | SecondFoo.t | ThirdFoo.t
What you need is to write recursive function that retruns Elixir AST in Tuple notation.

2 Likes

Woah. Thanks for the tip! I wonder if people would wnat to do this more often if it was provided by dialyzer.

@type foo :: @foos.t

for shorthand or something. I’ll look into implementing something like this. Thanks!

For posterity:

defmodule Test do
  @keys ~w(a b c)a
  @type key :: unquote(Enum.reduce(@keys, &{:|, [], [&1, &2]}))
end
20 Likes

Is there a way to wrap that in a macro, ex. union_type/1, so that one could write:

@type key :: union_type(@keys)

I haven’t been able to figure out how to write such a macro. This is the best I’ve been able to do so far:

defmodule UnionType do

  def union_type_ast(literals) do
    literals
    |> Enum.reverse()
    |> Enum.reduce(&{:|, [], [&1, &2]})
  end

end
defmodule TestDynamicType do

  require UnionType

  @keys ~w(a b c)a

  @type key :: unquote( UnionType.union_type_ast(@keys) )

end

(I added the Enum.reverse/1 call so that the order of the literal values, e.g. in @keys, matches the typespec for the generated type key.)

First of all instead of reverse + reduce (2 iterations) you should use [head | tail] (1 iteration) like:

defmodule Example do
  def sample([item]), do: item
  def sample([head | tail]), do: {:|, [], [head, sample(tail)]}
end

list = ~w(a b c)a
Example.sample(list)
# {:|, [], [:a, {:|, [], [:b, :c]}]}

Secondly you can use @type directly in macro, for example:

defmodule Example do
  defmacro __using__(list: list, name: name) do
    quote bind_quoted: [list: list, name: name] do
      @type unquote({name, [], Elixir}) :: unquote(Example.sample(list))
    end
  end

  def sample([item]), do: item
  def sample([head | tail]), do: {:|, [], [head, sample(tail)]}
end

defmodule Test do
  @list ~w(a b c)a
  use Example, list: @list, name: :key
end

with this you have:

$ iex -S mix
iex> t Test.key
@type key() :: :a | :b | :c
2 Likes

Thanks @Eiji!

I like your recursive definition but I’m not sure it’s much clearer – it doesn’t seem particularly sensible to support a single type for a ‘union type’ macro. Avoiding two iterations tho is pretty nice! And the function could always be made private anyways.

I suspected that it would be much easier to write a macro for the entire type definition – I couldn’t get one for just the ‘spec’ portion to work and suspect, if it is possible, that it would involve much more convoluted code.

Is it necessary to do the above in a __using__ macro specifically? (I’ll test that myself when I get a chance.)

In both @spec and @type you need to wrap everything in unquote call. Without that instead of calling function/macro the AST of such call would be stored:

iex> quote do
iex>   union_type(@keys)
iex> end
{:union_type, [],
  [{:@, [context: Elixir, import: Kernel], [{:keys, [context: Elixir], Elixir}]}]}

__using__/1 macro is as same as any other macro. use MyModule works like require MyModule + MyModule.__using__([]).

You can also write a macro like this one:

defmodule UnionType do
  defmacro union_type({:"::", _, [{name, _, _}, data]}) do
    quote bind_quoted: [data: data, name: name] do
      @type unquote({name, [], Elixir}) :: unquote(UnionType.union_type_ast(data))
    end
  end

  def union_type_ast([item]), do: item
  def union_type_ast([head | tail]), do: {:|, [], [head, union_type_ast(tail)]}
end

defmodule Example do
  import UnionType
  @keys ~w(a b c)a
  union_type key :: @keys
end

However for this you need to add this option:

[
  # …
  locals_without_parens: [union_type: 1]
]

to .formatter.exs, because otherwise it would format your code to:

defmodule Example do
  import UnionType
  @keys ~w(a b c)a
  union_type(key :: @keys)
end
4 Likes

That’s the conclusion I tentatively had reached myself but do you know why exactly this is? I’d guess it has to do with the details of how, and when, the compiler parses the @spec and @type declarations, but I haven’t found any info about what those details might be. I’m just curious!

Thank you for all of your help with this! I really appreciate it :slight_smile:

What’s your personal preference for doing this kind of thing? Do you not do anything like this in your own code?

I kind of think that the ‘original’ is clearest (even if a bit more verbose):

@type key :: unquote( UnionType.union_type_ast(@keys) )

But your union_type/1 macro is really nice too! I’d be a little worried that it’d be harder to read, e.g. easier to skip when scanning code that uses it and not notice that it’s declaring a type.

The pattern matching trick that effectively allows you to use the x :: y syntax is brilliant! That seems like a really useful trick generally for writing nice macros.

Depends on situation … in private API I would use just unquote call in @spec for simplicity. However in order to create a nice public API I would write a simple macro and document it as this way is easier to read and understand for other developers.

That’s why I mean … private == verbose and public == nice API

Good documentation is solution for most problems. :smiling_imp: If you or somebody else from your team would not like to remember such details then simply list all things like that in special markdown file. With that if you fail to find something take a look at such file and remind what you forgot. For example nobody needs to understand what ~> operator is doing, but documenting that your project uses ok hex library forces current developers to remind about it and every new developer to read concepts of such library.

If you want to generate something firstly check how to do it using quote call:

iex> quote do
iex>   i_wanna :: inspect_you
iex> end
{:"::", [], [{:i_wanna, [], Elixir}, {:inspect_you, [], Elixir}]}

:077:

1 Like

Great points!

With respect to documenting types declared with this kind of code, one could add a @typedoc attribute, or, possibly even better, add a ‘types’ section-comment for the relevant module.

I’m pretty satisfied with all of the identified options now.

But I’m still curious as to whether it’s possible (somehow) to write a union_type/1 macro that would work like this:

@type key :: union_type(@keys)

It did seem tricky and maybe because we’re passing a module attribute to the macro instead of literals.

As said it’s not possible …

@spec and @type accepts any valid expression and stores it’s AST representation. No matter what you call they would store an AST of call.

iex> quote do
iex>   my_func()
iex> end
{:my_func, [], []}
# this is just tuple (AST of call)
# since it's not call there is nothing called

Since we are working on quoted expressions to add something inside quoted expression you need to use unquote(expr) call.

1 Like

In both @spec and @type you need to wrap everything in unquote call. Without that instead of calling function/macro the AST of such call would be stored:

@spec and @type accepts any valid expression and stores it’s AST representation. No matter what you call they would store an AST of call.

Ahhh – that makes sense!

Thanks for repeating yourself, with enough of a different emphasis, for me to appreciate your original point. :slight_smile:

This is a great snippet! Here’s a function form of this:

defmodule TypeUtils do
  # https://elixirforum.com/t/dynamically-generate-typespecs-from-module-attribute-list/7078/5
  def list_to_typespec(list) when is_list(list) do
    Enum.reduce(list, &{:|, [], [&1, &2]})
  end
end

Usage example:

  @statuses [:not_started, :completed]
  @type status :: unquote(TypeUtils.list_to_typespec(@statuses))
4 Likes