Tidy up new record API

Author: José Valim

CHANGELOG.md

@@ -35,6 +35,7 @@
   * [Exception] `Exception.normalize/1` is deprecated in favor of `Exception.normalize/2`
   * [Kernel] `lc` and `bc` comprehensions are deprecated in favor of `for` (this is a soft deprecation, no warning will be emitted)
   * [ListDict] `ListDict` is deprecated in favor of `Map` (this is a soft deprecation, no warning will be emitted)
+  * [Record] `defrecord/2`, `defrecordp/3`, `is_record/1` and `is_record/2` macros in Kernel are deprecated. Instead, use the new macros and API defined in the `Record` module (this is a soft deprecation, no warnings will be emitted)
 
 * Backwards incompatible changes
   * [ExUnit] Formatters are now required to be a GenEvent and `ExUnit.run/2` returns a map with results

lib/elixir/lib/file.ex

@@ -1,3 +1,5 @@
+require Record
+
 defrecord File.Stat, Record.extract(:file_info, from_lib: "kernel/include/file.hrl") do
   @moduledoc """
   A record responsible to hold file information. Its fields are:

lib/elixir/lib/kernel.ex

@@ -3234,6 +3234,9 @@ defmodule Kernel do
   defmacro defstruct(kv) do
     kv = Macro.escape(kv, unquote: true)
     quote bind_quoted: [kv: kv] do
+      # Expand possible macros that return KVs.
+      kv = Macro.expand(kv, __ENV__)
+
       # TODO: Use those types once we support maps typespecs.
       { fields, _types } = Record.Backend.split_fields_and_types(:defstruct, kv)
 

lib/elixir/lib/record.ex

@@ -1,8 +1,35 @@
 defmodule Record do
+  @moduledoc """
+  Module to work, define and import records.
+
+  Records are simply tuples where the first element is an atom:
+
+      iex> Record.record? { User, "jose", 27 }
+      true
+
+  This module provides conveniences for working with records at
+  compilation time, where compile-time field names are used to
+  manipulate the tuples, providing fast operations on top of
+  the tuples compact structure.
+
+  In Elixir, records are used in two situations:
+
+  1. To work with short, internal data. See `Inspect.Algebra`
+     implementation for a good example;
+
+  2. To interface with Erlang records;
+
+  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.
+  """
+
   @doc """
   Extracts record information from an Erlang file.
 
-  Returns the fields as a list of tuples.
+  Returns a quoted expression containing the fields as a list
+  of tuples. It expects the record name to be an atom and the
+  library path to be a string at expansion time.
 
   ## Examples
 
@@ -13,8 +40,8 @@ defmodule Record do
        uid: :undefined, gid: :undefined]
 
   """
-  def extract(name, opts) do
-    Record.Extractor.extract(name, opts)
+  defmacro extract(name, opts) when is_atom(name) and is_list(opts) do
+    Macro.escape Record.Extractor.extract(name, opts)
   end
 
   @doc """
@@ -24,7 +51,8 @@ defmodule Record do
 
   ## Examples
 
-      iex> Record.record?({ User, "jose", 27 }, User)
+      iex> record = { User, "jose", 27 }
+      iex> Record.record?(record, User)
       true
 
   """
@@ -51,8 +79,10 @@ defmodule Record do
 
   ## Examples
 
-      iex> Record.record?({ User, "jose", 27 })
+      iex> record = { User, "jose", 27 }
+      iex> Record.record?(record)
       true
+      iex> integer = 13
       iex> Record.record?(13)
       false
 
@@ -87,4 +117,83 @@ defmodule Record do
   def deffunctions(values, env) do
     Record.Deprecated.deffunctions(values, env)
   end
+
+  @doc """
+  Defines a set of macros to create and access a record.
+
+  The macros are going to have `name`, a tag (which defaults)
+  to the name if none is given, and a set of fields given by
+  `kv`.
+
+  ## Examples
+
+      defmodule User do
+        Record.defrecord :user, [name: "José", age: "25"]
+      end
+
+  In the example above, a set of macros named `user` but with different
+  arities will be defined to manipulate the underlying record:
+
+      # To create records
+      user()        #=> { :user, "José", 25 }
+      user(age: 26) #=> { :user, "José", 26 }
+
+      # To get a field from the record
+      user(record, :name) #=> "José"
+
+      # To update the record
+      user(record, age: 26) #=> { :user, "José", 26 }
+
+  By default, Elixir uses the record name as the first element of
+  the tuple (the tag). But it can be changed to something else:
+
+      defmodule User do
+        Record.defrecord :user, User, name: nil
+      end
+
+      user() #=> { User, nil }
+
+  """
+  defmacro defrecord(name, tag \\ nil, kv) do
+    kv = Macro.escape(kv, unquote: true)
+
+    quote bind_quoted: [name: name, tag: tag, kv: kv] do
+      tag = tag || name
+      kv  = Macro.expand(kv, __ENV__)
+
+      { fields, _types } = Record.Backend.split_fields_and_types(:defrecord, kv)
+      fields = Macro.escape(fields)
+
+      defmacro(unquote(name)(args \\ [])) do
+        Record.Backend.access(unquote(tag), unquote(fields), args, __CALLER__)
+      end
+
+      defmacro(unquote(name)(record, args)) do
+        Record.Backend.access(unquote(tag), unquote(fields), record, args, __CALLER__)
+      end
+    end
+  end
+
+  @doc """
+  Same as `defrecord/3` but generates private macros.
+  """
+  defmacro defrecordp(name, tag \\ nil, kv) do
+    kv = Macro.escape(kv, unquote: true)
+
+    quote bind_quoted: [name: name, tag: tag, kv: kv] do
+      tag = tag || name
+      kv  = Macro.expand(kv, __ENV__)
+
+      { fields, _types } = Record.Backend.split_fields_and_types(:defrecordp, kv)
+      fields = Macro.escape(fields)
+
+      defmacrop(unquote(name)(args \\ [])) do
+        Record.Backend.access(unquote(tag), unquote(fields), args, __CALLER__)
+      end
+
+      defmacrop(unquote(name)(record, args)) do
+        Record.Backend.access(unquote(tag), unquote(fields), record, args, __CALLER__)
+      end
+    end
+  end
 end

lib/elixir/lib/record/backend.ex

@@ -34,4 +34,113 @@ defmodule Record.Backend do
   defp split_fields_and_types(_tag, [], fields, types) do
     { :lists.reverse(fields), :lists.reverse(types) }
   end
+
+  @doc """
+  Callback invoked from record/0 and record/1 macros.
+  """
+  def access(atom, fields, args, caller) do
+    cond do
+      is_atom(args) ->
+        index(atom, fields, args)
+      Keyword.keyword?(args) ->
+        create(atom, fields, args, caller)
+      true ->
+        raise ArgumentError,
+          message: "expected arguments to be a compile time atom or keywords, got: #{Macro.to_string args}"
+    end
+  end
+
+  @doc """
+  Callback invoked from the record/2 macro.
+  """
+  def access(atom, fields, record, args, caller) do
+    cond do
+      is_atom(args) ->
+        get(atom, fields, record, args)
+      Keyword.keyword?(args) ->
+        update(atom, fields, record, args, caller)
+      true ->
+        raise ArgumentError,
+          message: "expected arguments to be a compile time atom or keywords, got: #{Macro.to_string args}"
+    end
+  end
+
+  @doc """
+  Gets the index of field.
+  """
+  def index(atom, fields, field) do
+    if index = find_index(fields, field, 0) do
+      index - 1 # Convert to Elixir index
+    else
+      raise ArgumentError, message: "record #{inspect atom} does not have the key: #{inspect field}"
+    end
+  end
+
+  @doc """
+  Creates a new record with the given default fields and keyword values.
+  """
+  def create(atom, fields, keyword, caller) do
+    in_match = caller.in_match?
+
+    { match, remaining } =
+      Enum.map_reduce(fields, keyword, fn({ field, default }, each_keyword) ->
+        new_fields =
+          case Keyword.has_key?(each_keyword, field) do
+            true  -> Keyword.get(each_keyword, field)
+            false ->
+              case in_match do
+                true  -> { :_, [], nil }
+                false -> Macro.escape(default)
+              end
+          end
+
+        { new_fields, Keyword.delete(each_keyword, field) }
+      end)
+
+    case remaining do
+      [] ->
+        { :{}, [], [atom|match] }
+      _  ->
+        keys = for { key, _ } <- remaining, do: key
+        raise ArgumentError, message: "record #{inspect atom} does not have the key: #{inspect hd(keys)}"
+    end
+  end
+
+  @doc """
+  Updates a record given by var with the given keyword.
+  """
+  def update(atom, fields, var, keyword, caller) do
+    if caller.in_match? do
+      raise ArgumentError, message: "cannot invoke update style macro inside match"
+    end
+
+    Enum.reduce keyword, var, fn({ key, value }, acc) ->
+      index = find_index(fields, key, 0)
+      if index do
+        quote do
+          :erlang.setelement(unquote(index), unquote(acc), unquote(value))
+        end
+      else
+        raise ArgumentError, message: "record #{inspect atom} does not have the key: #{inspect key}"
+      end
+    end
+  end
+
+  @doc """
+  Gets a record key from the given var.
+  """
+  def get(atom, fields, var, key) do
+    index = find_index(fields, key, 0)
+    if index do
+      quote do
+        :erlang.element(unquote(index), unquote(var))
+      end
+    else
+      raise ArgumentError, message: "record #{inspect atom} does not have the key: #{inspect key}"
+    end
+  end
+
+  defp find_index([{ k, _ }|_], k, i), do: i + 2
+  defp find_index([{ _, _ }|t], k, i), do: find_index(t, k, i + 1)
+  defp find_index([], _k, _i), do: nil
 end

lib/elixir/test/elixir/deprecated_record/private_test.exs

@@ -3,6 +3,8 @@ Code.require_file "../test_helper.exs", __DIR__
 defmodule Record.PrivateTest do
   use ExUnit.Case, async: true
 
+  require Record
+
   defmodule Macros do
     defrecordp :_user, __MODULE__, name: "José", age: 25
     defrecordp :_my_user, :my_user, name: "José", age: 25

lib/elixir/test/elixir/deprecated_record/record_test.exs

@@ -1,5 +1,7 @@
 Code.require_file "../test_helper.exs", __DIR__
 
+require Record
+
 defrecord RecordTest.FileInfo,
   Record.extract(:file_info, from_lib: "kernel/include/file.hrl")
 

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

@@ -255,28 +255,6 @@ defmodule Kernel.TypespecTest do
     assert [{:t, {:type, 251, :map, []}, []}] = types
   end
 
-  test "@type from records" do
-    types = test_module do
-      defrecordp :user, name: nil, age: 0 :: integer
-      @opaque user :: user_t
-      @type
-    end
-
-    assert [{:user_t, {:type, _, :tuple,
-             [{:atom, _, :user}, {:type, _, :term, []}, {:type, _, :integer, []}]}, []}] = types
-  end
-
-  test "@type from records with custom tag" do
-    {types, module} = test_module do
-      defrecordp :user, __MODULE__, name: nil, age: 0 :: integer
-      @opaque user :: user_t
-      {@type, __MODULE__}
-    end
-
-    assert [{:user_t, {:type, _, :tuple,
-             [{:atom, _, ^module}, {:type, _, :term, []}, {:type, _, :integer, []}]}, []}] = types
-  end
-
   test "@type unquote fragment" do
     spec = test_module do
       quoted = quote unquote: false do

lib/elixir/test/elixir/record_test.exs

@@ -19,6 +19,15 @@ defmodule RecordTest do
     assert elem(namespace, 0) == :xmlNamespace
   end
 
+  test "extract/2 with defstruct" do
+    defmodule StructExtract do
+      defstruct Record.extract(:file_info, from_lib: "kernel/include/file.hrl")
+    end
+
+    assert %{ __struct__: StructExtract, size: :undefined } =
+           StructExtract.__struct__
+  end
+
   # We need indirection to avoid warnings
   defp record?(data, kind) do
     Record.record?(data, kind)
@@ -40,4 +49,36 @@ defmodule RecordTest do
     refute record?({ "jose", 27 })
     refute record?(13)
   end
+
+  Record.defrecord  :user, __MODULE__, name: "José", age: 25
+  Record.defrecordp :file_info, Record.extract(:file_info, from_lib: "kernel/include/file.hrl")
+
+  test "records generates macros that generates tuples" do
+    record = user()
+    assert user(record, :name) == "José"
+    assert user(record, :age)  == 25
+
+    record = user(record, name: "Eric")
+    assert user(record, :name) == "Eric"
+
+    assert elem(record, user(:name)) == "Eric"
+    assert elem(record, 0) == RecordTest
+
+    user(name: name) = record
+    assert name == "Eric"
+  end
+
+  test "records with no tag" do
+    assert elem(file_info(), 0) == :file_info
+  end
+
+  test "records with dynamic arguments" do
+    record = file_info()
+    assert file_info(record, :size) == :undefined
+  end
+
+  test "records visibility" do
+    assert macro_exported?(__MODULE__, :user, 0)
+    refute macro_exported?(__MODULE__, :file_info, 1)
+  end
 end