Merge pull request #2521 from ericmj/record-typespecs

Add typespec syntax for records

Author: José Valim

lib/elixir/lib/kernel/typespec.ex

@@ -77,9 +77,11 @@ defmodule Kernel.Typespec do
            | %{Keyword}
            | %{Pairs}
 
-      Tuple :: tuple     # a tuple of any size
-             | {}        # empty tuple
+      Tuple :: tuple                 # a tuple of any size
+             | {}                    # empty tuple
              | {TList}
+             | record(Atom)          # record (see Record)
+             | record(Atom, Keyword)
 
       Keyword :: ElixirAtom: Type
                | ElixirAtom: Type, Keyword
@@ -851,6 +853,34 @@ defmodule Kernel.Typespec do
     typespec({:%{}, meta, fields}, vars, caller)
   end
 
+  # Handle records
+  defp typespec({:record, meta, [atom]}, vars, caller) do
+    typespec({:record, meta, [atom, []]}, vars, caller)
+  end
+
+  defp typespec({:record, meta, [atom, fields]}, vars, caller) do
+    case Macro.expand({atom, [], [{atom, [], []}]}, caller) do
+      keyword when is_list(keyword) ->
+        keyword =
+          :lists.map(fn {field, _} ->
+            {field, quote do: term()}
+          end, keyword)
+
+        :lists.foreach(fn {field, _} ->
+          unless Keyword.has_key?(keyword, field) do
+            compile_error(caller, "undefined field #{field} on record #{inspect atom}")
+          end
+        end, fields)
+
+        fields = Keyword.merge(keyword, fields)
+        types = Keyword.values(fields)
+
+        typespec({:{}, meta, [atom|types]}, vars, caller)
+      _ ->
+        compile_error(caller, "unknown record #{inspect atom}")
+    end
+  end
+
   # Handle ranges
   defp typespec({:.., meta, args}, vars, caller) do
     typespec({:range, meta, args}, vars, caller)

lib/elixir/lib/macro.ex

@@ -867,7 +867,7 @@ defmodule Macro do
       end
 
       expand = :elixir_dispatch.expand_import(meta, {atom, length(args)}, args,
-                                              env, extra)
+                                              env, extra, true)
 
       case expand do
         {:ok, receiver, quoted} ->

lib/elixir/lib/record.ex

@@ -20,6 +20,20 @@ defmodule Record do
   The macros `defrecord/3` and `defrecordp/3` can be used to create
   records while `extract/2` can be used to extract records from Erlang
   files.
+
+  ## Types
+
+  Types can be defined for tuples with the `record/2` macro (only available
+  in typespecs). Like with the generated record macros it will expand to
+  a tuple.
+
+      defmodule MyModule do
+        require Record
+        Record.defrecord :user name: "José", age: 25
+
+        @type user :: record(:user, name: String.t, age: integer)
+        # expands to: `@type user :: {:user, String.t, integer}`
+      end
   """
 
   @doc """
@@ -195,7 +209,15 @@ defmodule Record do
       Keyword.keyword?(args) ->
         create(atom, fields, args, caller)
       true ->
-        quote do: Record.__keyword__(unquote(atom), unquote(fields), unquote(args))
+        case Macro.expand(args, caller) do
+          {:{}, _, [^atom|list]} when length(list) == length(fields) ->
+            record = List.to_tuple([atom|list])
+            Macro.escape(Record.__keyword__(atom, fields, record))
+          {^atom, arg} when length(fields) == 1 ->
+            Macro.escape(Record.__keyword__(atom, fields, {atom, arg}))
+          _ ->
+            quote do: Record.__keyword__(unquote(atom), unquote(fields), unquote(args))
+        end
     end
   end
 
@@ -291,7 +313,7 @@ defmodule Record do
       [_tag|values] = Tuple.to_list(record)
       join_keyword(fields, values, [])
     else
-      msg = "expected argument to be a literal atom, literal keyword or a #{atom}() record, got runtime: #{inspect record}"
+      msg = "expected argument to be a literal atom, literal keyword or a #{inspect atom} record, got runtime: #{inspect record}"
       raise ArgumentError, msg
     end
   end

lib/elixir/src/elixir_dispatch.erl

@@ -4,7 +4,7 @@
 -module(elixir_dispatch).
 -export([dispatch_import/5, dispatch_require/6,
   require_function/5, import_function/4,
-  expand_import/5, expand_require/5,
+  expand_import/6, expand_require/5,
   default_functions/0, default_macros/0, default_requires/0,
   find_import/4, format_error/1]).
 -include("elixir.hrl").
@@ -88,7 +88,7 @@ remote_function(Meta, Receiver, Name, Arity, E) ->
 
 dispatch_import(Meta, Name, Args, E, Callback) ->
   Arity = length(Args),
-  case expand_import(Meta, {Name, Arity}, Args, E, []) of
+  case expand_import(Meta, {Name, Arity}, Args, E, [], false) of
     {ok, Receiver, Quoted} ->
       expand_quoted(Meta, Receiver, Name, Arity, Quoted, E);
     {ok, Receiver, NewName, NewArgs} ->
@@ -115,12 +115,12 @@ dispatch_require(_Meta, Receiver, Name, Args, _E, Callback) ->
 
 %% Macros expansion
 
-expand_import(Meta, {Name, Arity} = Tuple, Args, E, Extra) ->
-  Module   = ?m(E, module),
-  Dispatch = find_dispatch(Meta, Tuple, Extra, E),
-  Function = ?m(E, function),
-  Local    = (Function /= nil) andalso (Function /= Tuple) andalso
-              elixir_locals:macro_for(Module, Name, Arity),
+expand_import(Meta, {Name, Arity} = Tuple, Args, E, Extra, External) ->
+  Module      = ?m(E, module),
+  Dispatch    = find_dispatch(Meta, Tuple, Extra, E),
+  Function    = ?m(E, function),
+  AllowLocals = External orelse ((Function /= nil) andalso (Function /= Tuple)),
+  Local       = AllowLocals andalso elixir_locals:macro_for(Module, Name, Arity),
 
   case Dispatch of
     %% In case it is an import, we dispatch the import.

lib/elixir/test/elixir/kernel/typespec_test.exs

@@ -214,6 +214,52 @@ defmodule Kernel.TypespecTest do
     end
   end
 
+  test "@type with public record" do
+    module = test_module do
+      require Record
+      Record.defrecord :timestamp, [date: 1, time: 2]
+      @type mytype :: record(:timestamp, time: :foo)
+    end
+
+    assert [type: {:mytype,
+             {:type, _, :tuple, [
+               {:atom, 0, :timestamp}, {:atom, 0, :foo}, {:type, 0, :term, []}
+             ]},
+            []}] = types(module)
+  end
+
+  test "@type with private record" do
+    module = test_module do
+      require Record
+      Record.defrecordp :timestamp, [date: 1, time: 2]
+      @type mytype :: record(:timestamp, time: :foo)
+    end
+
+    assert [type: {:mytype,
+             {:type, _, :tuple, [
+               {:atom, 0, :timestamp}, {:atom, 0, :foo}, {:type, 0, :term, []}
+             ]},
+            []}] = types(module)
+  end
+
+  test "@type with undefined record" do
+    assert_raise CompileError, ~r"unknown record :this_record_does_not_exist", fn ->
+      test_module do
+        @type mytype :: record(:this_record_does_not_exist, [])
+      end
+    end
+  end
+
+  test "@type with a record with undefined field" do
+    assert_raise CompileError, ~r"undefined field no_field on record :timestamp", fn ->
+      test_module do
+        require Record
+        Record.defrecord :timestamp, [date: 1, time: 2]
+        @type mytype :: record(:timestamp, no_field: :foo)
+      end
+    end
+  end
+
   test "@type with list shortcuts" do
     module = test_module do
       @type mytype :: []

lib/elixir/test/elixir/record_test.exs

@@ -81,8 +81,9 @@ defmodule RecordTest do
 
     record = user()
     assert user(record) == [name: "José", age: 25]
+    assert user(user()) == [name: "José", age: 25]
 
-    msg = "expected argument to be a literal atom, literal keyword or a file_info() record, " <>
+    msg = "expected argument to be a literal atom, literal keyword or a :file_info record, " <>
           "got runtime: {RecordTest, \"José\", 25}"
     assert_raise ArgumentError, msg, fn ->
       file_info(record)