Add Macro.escape_quoted instead of Macro.escape with options

Author: José Valim

CHANGELOG.md

@@ -1,14 +1,16 @@
 * enhancements
   * [ExUnit] Use ANSI escape codes in CLI output
   * [ExUnit] Include suite run time on CLI results
+  * [File] Add `File.ls` and `File.ls!`
   * [IEx] Support `pwd` and `cd` helpers
   * [Kernel] Better error reporting for invalid bitstring generators
   * [Kernel] Improve meta-programming by allowing `unquote` on `def/2`, `defp/2`, `defmacro/2` and `defmacrop/2`
-  * [Macro] `Macro.escape` now supports `escape_unquote` as an option
+  * [Macro] Add `Macro.escape_quoted` to escape quoted expressions
   * [Mix] Support `--cover` on mix test and `test_coverage` on Mixfiles
 
 * bug fix
   * [Binary] inspect no longer escapes standalone hash `#`
+  * [IEx] The h helper can now retrieve docs for special forms
   * [Kernel] Record optimizations were not being triggered in functions inside the record module
   * [Kernel] Aliases defined inside macros should be carried over
   * [Path] Fix a bug on `Path.expand` when expanding paths starting with `~`

lib/elixir/lib/kernel.ex

@@ -3144,7 +3144,7 @@ defmodule Kernel do
   """
   defmacro defdelegate(funs, opts) do
     quote do
-      funs = unquote(Macro.escape(funs, escape_unquote: false))
+      funs = unquote(Macro.escape_quoted(funs))
       opts = unquote(opts)
 
       target = Keyword.get(opts, :to) ||

lib/elixir/lib/macro.ex

@@ -52,13 +52,14 @@ defmodule Macro do
   end
 
   @doc """
-  Recursively escapes the given value so it can be inserted
-  into a syntax tree. Structures that are valid syntax nodes
-  (like atoms, integers, binaries) are represented by themselves.
+  Recursively escapes a value so it can be inserted
+  into a syntax tree. This must be used when you have
+  a value that does not represent an AST and you want
+  to introduce it inside a quoted expression.
 
-  ## Options
-
-  * `escape_unquote` - when false, does not escape unquoted calls
+  If you have a AST and you want to introduce it inside
+  a quoted expression in a escaped form, use Macro.escape_quoted
+  instead.
 
   ## Examples
 
@@ -69,8 +70,8 @@ defmodule Macro do
       #=> { :{}, [], [:a, :b, :c] }
 
   """
-  def escape(expr, opts // []) do
-    do_escape(expr, not Keyword.get(opts, :escape_unquote, true))
+  def escape(expr) do
+    do_escape(expr, false)
   end
 
   defp do_escape({ { { :., meta, [left, :unquote] }, _, [expr] }, _, args }, true) do
@@ -138,6 +139,21 @@ defmodule Macro do
   defp do_splice_join(left, []),    do: left
   defp do_splice_join(left, right), do: { :++, [], [left, right] }
 
+  @doc """
+  Recursively escapes a AST so it can be inserted into
+  another tree unmodified. If the given AST has any
+  call to unquote, they are properly evaluated.
+
+  ## Examples
+
+      Macro.escape_quoted({ :+, [], [1,2] })
+      #=> {:"{}",[],[:+,[],[1,2]]}
+
+  """
+  def escape_quoted(expr) do
+    do_escape(expr, true)
+  end
+
   @doc %B"""
   Unescape the given chars. This is the unescaping behavior
   used by default in Elixir single- and double-quoted strings.

lib/elixir/test/elixir/macro_test.exs

@@ -38,14 +38,14 @@ defmodule MacroTest do
 
   test :escape_with_unquote do
     contents = quote unquote: false, do: unquote(1)
-    assert Macro.escape(contents, escape_unquote: false) == 1
+    assert Macro.escape_quoted(contents) == 1
 
     contents = quote unquote: false, do: unquote(x)
-    assert Macro.escape(contents, escape_unquote: false) == { :x, [], MacroTest }
+    assert Macro.escape_quoted(contents) == { :x, [], MacroTest }
   end
 
   defp eval_escaped(contents) do
-    { eval, [] } = Code.eval_quoted(Macro.escape(contents, escape_unquote: false))
+    { eval, [] } = Code.eval_quoted(Macro.escape_quoted(contents))
     eval
   end
 
@@ -71,7 +71,7 @@ defmodule MacroTest do
 
   test :escape_with_splicing do
     contents = quote unquote: false, do: [1,2,3,4,5]
-    assert Macro.escape(contents, escape_unquote: false) == [1,2,3,4,5]
+    assert Macro.escape_quoted(contents) == [1,2,3,4,5]
 
     contents = quote unquote: false, do: [1,2,unquote_splicing([3,4,5])]
     assert eval_escaped(contents) == [1,2,3,4,5]

lib/ex_unit/lib/ex_unit/callbacks.ex

@@ -126,7 +126,7 @@ defmodule ExUnit.Callbacks do
   end
 
   defp escape(contents) do
-    Macro.escape(contents, escape_unquoted: false)
+    Macro.escape_quoted(contents)
   end
 
   defp compile_callbacks(env, kind) do

lib/ex_unit/lib/ex_unit/case.ex

@@ -88,7 +88,7 @@ defmodule ExUnit.Case do
       end
 
       def message, [unquote(Macro.escape var)], [], do:
-        unquote(Macro.escape contents, escape_unquote: false)
+        unquote(Macro.escape_quoted contents)
     end
   end
 end