Allow :binding as an option in quote

This commit also adds Macro.expand_once/2 and Macro.expand_all/2.

Author: José Valim

CHANGELOG.md

@@ -7,6 +7,8 @@
   * [Kernel] Warn on undefined module attributes
   * [Kernel] Emit warning for 'x in []' in guards
   * [Kernel] Add `binding/0` and `binding/1` for retrieving bindings
+  * [Kernel] `quote` now allows a binding as an option
+  * [Macro] Add `Macro.expand_once/2` and `Macro.expand_all/2`
   * [Mix] Implement `Mix.Version` for basic versioniong semantics
   * [Mix] Support creation and installation of archives (.ez files)
   * [Mix] `github: ...` shortcut now uses the faster `git` schema instead of `https`
@@ -30,6 +32,7 @@
   * [Bitwise] Precedence of operators used by the Bitwise module were changed. Check `elixir_parser.yrl` for more information.
   * [File] `rm_rf` and `cp_r` now returns a tuple with three elements on failures
   * [Kernel] The quoted representation for `->` clauses changed from a tuple with two elements to a tuple with three elements to support metadata
+  * [Macro] `Macro.expand/2` now expands until final form. Although this is backwards incompatible, it is **very** likely your code should expand the node until its final form, particularly if you are expecting an atom out of it
   * [Mix] No longer support beam files on `mix local`
 
 # v0.9.2 (2013-06-13)

lib/elixir/lib/kernel/special_forms.ex

@@ -388,6 +388,8 @@ defmodule Kernel.SpecialForms do
                   Read the Stacktrace information section below for more information;
   * `:hygiene` - Allows a developer to disable hygiene selectively;
   * `:context` - Sets the context resolution happens at;
+  * `:binding` - Passes a binding to the macro. Whenever a binding is given,
+                 unquote is automatically disabled;
 
   ## Macro literals
 
@@ -629,6 +631,79 @@ defmodule Kernel.SpecialForms do
   code as if it was defined inside `GenServer.Behaviour` file, in
   particular, the macro `__FILE__` and exceptions happening inside
   the quote will always point to `GenServer.Behaviour` file.
+
+  ## Binding and unquote fragments
+
+  Elixir quote/unquote mechanisms provides a functionality called
+  unquote fragments. Unquote fragments provide an easy to generate
+  functions on the fly. Consider this example:
+
+      kv = [foo: 1, bar: 2]
+      Enum.each kv, fn { k, v } ->
+        def unquote(k)(), do: unquote(v)
+      end
+
+  In the example above, we have generated the function `foo/0` and
+  `bar/0` dynamically. Now, imagine that, we want to convert this
+  functionality into a macro:
+
+      defmacro defkv(kv) do
+        Enum.each kv, fn { k, v } ->
+          quote do
+            def unquote(k)(), do: unquote(v)
+          end
+        end
+      end
+
+  We can invoke this macro as:
+
+      defkv [foo: 1, bar: 2]
+
+  However, we can't invoke it as follows:
+
+      kv = [foo: 1, bar: 2]
+      defkv kv
+
+  This is because the macro is expecting its arguments to be a
+  key-value at **compilation** time. Since in the example above
+  we are passing the representation of the variable `kv`, our
+  code fails.
+
+  This is actually a common pitfall when developing macros. In
+  practive, we want to avoid doing work at compilation time as
+  much as we can. That said, let's attempt to improve our macro:
+
+      defmacro defkv(kv) do
+        quote do
+          Enum.each unquote(kv), fn { k, v } ->
+            def unquote(k)(), do: unquote(v)
+          end
+        end
+      end
+
+  If you try to run our new macro, you will notice it won't
+  even compile, complaining that the variables `k` and `v`
+  do not exist. This is because of the ambiguity: `unquote(k)`
+  can either be an unquote fragment, as previously, or a regular
+  unquote as in `unquote(kv)`.
+
+  One solution for this problem is to disable unquoting in the
+  macro, however, doing that would make it impossible to inject
+  `kv` representation into the tree. That's when the `:binding`
+  option comes to the rescue. By using `:binding`, we can
+  automatically disable unquoting while still injecting the
+  desired variables into the tree:
+
+      defmacro defkv(kv) do
+        quote binding: [kv: kv] do
+          Enum.each kv, fn { k, v } ->
+            def unquote(k)(), do: unquote(v)
+          end
+        end
+      end
+
+  In fact, the `:binding` option is recommended every time one
+  desires to inject a value into the quote.
   """
   defmacro quote(opts, block)
 

lib/elixir/lib/macro.ex

@@ -365,31 +365,18 @@ defmodule Macro do
   end
 
   @doc """
-  Receives an expression representation and expands it. The following
-  contents are expanded:
+  Receives a AST node and expands it once. The following contents are expanded:
 
   * Macros (local or remote);
   * Aliases are expanded (if possible) and return atoms;
   * All pseudo-variables (__FILE__, __MODULE__, etc);
   * Module attributes reader (@foo);
 
-  In case the expression cannot be expanded, it returns the expression itself.
-
-  Notice that `Macro.expand` is not recursive and it does not
-  expand child expressions. In this example:
-
-    Macro.expand(quote(do: var && some_macro), __ENV__)
-
-  `var && some_macro` will expand to something like:
-
-      case var do
-        _ in [false, nil] -> var
-        _ -> some_macro
-      end
-
-  Notice that the `&&` operator is a macro that expands to a case.
-  Even though `some_macro` is also a macro, it is not expanded
-  because it is a child expression given to `&&` as argument.
+  In case the expression cannot be expanded, it returns the expression
+  itself. Notice that `Macro.expand_once/2` performs the expansion just
+  once and it is not recursive. Check `Macro.expand/2` for expansion
+  until the node no longer represents a macro and `Macro.expand_all/2`
+  for recursive expansion.
 
   ## Examples
 
@@ -452,46 +439,50 @@ defmodule Macro do
       end
 
   """
-  def expand(aliases, env) do
-    expand(aliases, env, nil)
+  def expand_once(aliases, env) do
+    expand_once(aliases, env, nil) |> elem(0)
   end
 
-  defp expand({ :__aliases__, _, _ } = original, env, cache) do
+  defp expand_once({ :__aliases__, _, _ } = original, env, cache) do
     case :elixir_aliases.expand(original, env.aliases, env.macro_aliases) do
-      atom when is_atom(atom) -> atom
+      atom when is_atom(atom) -> { atom, true, cache }
       aliases ->
-        aliases = lc alias inlist aliases, do: expand(alias, env, cache)
+        aliases = lc alias inlist aliases, do: (expand_once(alias, env, cache) |> elem(0))
 
         case :lists.all(is_atom(&1), aliases) do
-          true  -> :elixir_aliases.concat(aliases)
-          false -> original
+          true  -> { :elixir_aliases.concat(aliases), true, cache }
+          false -> { original, false, cache }
         end
     end
   end
 
   # Expand @ calls
-  defp expand({ :@, _, [{ name, _, args }] } = original, env, _cache) when is_atom(args) or args == [] do
+  defp expand_once({ :@, _, [{ name, _, args }] } = original, env, cache) when is_atom(args) or args == [] do
     case (module = env.module) && Module.open?(module) do
-      true  -> Module.get_attribute(module, name)
-      false -> original
+      true  -> { Module.get_attribute(module, name), true, cache }
+      false -> { original, false, cache }
     end
   end
 
   # Expand pseudo-variables
-  defp expand({ :__MODULE__, _, atom }, env, _cache) when is_atom(atom), do: env.module
-  defp expand({ :__FILE__, _, atom }, env, _cache)   when is_atom(atom), do: env.file
-  defp expand({ :__DIR__, _, atom }, env, _cache)    when is_atom(atom), do: :filename.dirname(env.file)
-  defp expand({ :__ENV__, _, atom }, env, _cache)    when is_atom(atom), do: env
+  defp expand_once({ :__MODULE__, _, atom }, env, cache) when is_atom(atom),
+    do: { env.module, true, cache }
+  defp expand_once({ :__FILE__, _, atom }, env, cache)   when is_atom(atom),
+    do: { env.file, true, cache }
+  defp expand_once({ :__DIR__, _, atom }, env, cache)    when is_atom(atom),
+    do: { :filename.dirname(env.file), true, cache }
+  defp expand_once({ :__ENV__, _, atom }, env, cache)    when is_atom(atom),
+    do: { env, true, cache }
 
   # Expand possible macro import invocation
-  defp expand({ atom, line, args } = original, env, cache) when is_atom(atom) do
+  defp expand_once({ atom, line, args } = original, env, cache) when is_atom(atom) do
     args = case is_atom(args) do
       true  -> []
       false -> args
     end
 
     case not is_partial?(args) do
-      false -> original
+      false -> { original, false, cache }
       true  ->
         module = env.module
 
@@ -501,43 +492,103 @@ defmodule Macro do
           []
         end
 
+        cache  = to_erl_env(env, cache)
         expand = :elixir_dispatch.expand_import(line, { atom, length(args) }, args,
-          env.module, extra, to_erl_env(env, cache))
+          env.module, extra, cache)
+
         case expand do
-          { :ok, _, expanded } -> expanded
-          { :error, _ }     -> original
+          { :ok, _, expanded } -> { expanded, true, cache }
+          { :error, _ }        -> { original, false, cache }
         end
     end
   end
 
   # Expand possible macro require invocation
-  defp expand({ { :., _, [left, right] }, line, args } = original, env, cache) when is_atom(right) do
-    receiver = expand(left, env)
+  defp expand_once({ { :., _, [left, right] }, line, args } = original, env, cache) when is_atom(right) do
+    { receiver, _, _ } = expand_once(left, env, cache)
 
     case is_atom(receiver) and not is_partial?(args) do
-      false -> original
+      false -> { original, false, cache }
       true  ->
+        cache  = to_erl_env(env, cache)
         expand = :elixir_dispatch.expand_require(line, receiver, { right, length(args) },
-          args, env.module, to_erl_env(env, cache))
+          args, env.module, cache)
+
         case expand do
-          { :ok, _receiver, expanded } -> expanded
-          { :error, _ }                -> original
+          { :ok, _receiver, expanded } -> { expanded, true, cache }
+          { :error, _ }                -> { original, false, cache }
         end
     end
   end
 
   # Anything else is just returned
-  defp expand(other, _env, _cache), do: other
+  defp expand_once(other, _env, cache), do: { other, false, cache }
 
   defp to_erl_env(env, nil),    do: :elixir_scope.to_erl_env(env)
   defp to_erl_env(_env, cache), do: cache
 
-  ## Helpers
-
   defp is_partial?(args) do
     :lists.any(match?({ :&, _, [_] }, &1), args)
   end
 
+  @doc """
+  Receives a AST node and expands it until it no longer represents
+  a macro. Check `Macro.expand_once/2` for more information on how
+  expansion works and `Macro.expand_all/2` for recursive expansion.
+  """
+  def expand(tree, env) do
+    expand(tree, env, nil) |> elem(0)
+  end
+
+  @doc false # Used internally by Elixir
+  def expand(tree, env, cache) do
+    expand_until({ tree, true, cache }, env)
+  end
+
+  defp expand_until({ tree, true, cache }, env) do
+    expand_until(expand_once(tree, env, cache), env)
+  end
+
+  defp expand_until({ tree, false, cache }, _env) do
+    { tree, cache }
+  end
+
+  @doc """
+  Receives a AST node and expands it until it no longer represents
+  a macro. Then it expands all of its children recursively.
+
+  Check `Macro.expand_once/2` for more information on how expansion
+  works.
+  """
+  def expand_all(tree, env) do
+    expand_all(tree, env, nil) |> elem(0)
+  end
+
+  @doc false # Used internally by Elixir
+  def expand_all(tree, env, cache) do
+    expand_all_until(expand(tree, env, cache), env)
+  end
+
+  defp expand_all_until({ { left, meta, right }, cache }, env) do
+    { left, cache }  = expand_all(left, env, cache)
+    { right, cache } = expand_all(right, env, cache)
+    { { left, meta, right }, cache }
+  end
+
+  defp expand_all_until({ { left, right }, cache }, env) do
+    { left, cache }  = expand_all(left, env, cache)
+    { right, cache } = expand_all(right, env, cache)
+    { { left, right }, cache }
+  end
+
+  defp expand_all_until({ list, cache }, env) when is_list(list) do
+    :lists.mapfoldl(expand_all(&1, env, &2), cache, list)
+  end
+
+  defp expand_all_until({ other, cache }, _env) do
+    { other, cache }
+  end
+
   @doc """
   Recurs the quoted expression checking if all sub terms are
   safe (i.e. they represented data structured and don't actually