Deprecate Code.eval in favor of Code.eval_string, closes #953

Author: José Valim

CHANGELOG.md

@@ -32,6 +32,7 @@
   * [URI] Downcase host and scheme and URIs
 
 * deprecations
+  * [Code] `Code.eval` is deprecated in favor of `Code.eval_string`
   * [ExUnit] `assert left inlist right` is deprecated in favor of `assert left in right`
   * [IO] `IO.getb` is deprecated in favor of `IO.getn`
   * [List] `List.member?/2` is deprecated in favor of `Enum.member?/2`

lib/elixir/lib/code.ex

@@ -57,6 +57,12 @@ defmodule Code do
     :code.del_path(Path.expand to_char_list(path))
   end
 
+  @doc false
+  def eval(string, binding // [], opts // []) do
+    IO.write "[WARNING] Code.eval is deprecated, please use Code.eval_string instead\n#{Exception.format_stacktrace}"
+    eval_string(string, binding, opts)
+  end
+
   @doc """
   Evalutes the contents given by string. The second argument is the
   binding (which should be a keyword) followed by a keyword list of
@@ -84,24 +90,24 @@ defmodule Code do
 
   ## Examples
 
-      iex> Code.eval("a + b", [a: 1, b: 2], file: __ENV__.file, line: __ENV__.line)
+      iex> Code.eval_string("a + b", [a: 1, b: 2], file: __ENV__.file, line: __ENV__.line)
       { 3, [ {:a, 1}, {:b, 2} ] }
 
   For convenience, you can my pass `__ENV__` as argument and
   all imports, requires and aliases will be automatically carried
   over:
 
-      iex> Code.eval("a + b", [a: 1, b: 2], __ENV__)
+      iex> Code.eval_string("a + b", [a: 1, b: 2], __ENV__)
       { 3, [ {:a, 1}, {:b, 2} ] }
 
   """
-  def eval(string, binding // [], opts // [])
+  def eval_string(string, binding // [], opts // [])
 
-  def eval(string, binding, Macro.Env[] = env) do
-    eval(string, binding, env.to_keywords)
+  def eval_string(string, binding, Macro.Env[] = env) do
+    eval_string(string, binding, env.to_keywords)
   end
 
-  def eval(string, binding, opts) do
+  def eval_string(string, binding, opts) do
     { value, binding, _scope } =
       :elixir.eval :unicode.characters_to_list(string), binding, opts
     { value, binding }
@@ -111,7 +117,7 @@ defmodule Code do
   Evalutes the quoted contents.
 
   This function accepts a list of environment options.
-  Check `Code.eval` for more information.
+  Check `Code.eval_string` for more information.
 
   ## Examples
 
@@ -153,6 +159,11 @@ defmodule Code do
   * `:existing_atoms_only` - When true, raises an error
     when non-existing atoms are found by the tokenizer.
 
+  ## Macro.to_binary/1
+
+  The opposite of converting a string to its AST is
+  `Macro.to_binary`, which converts a AST to a binary
+  representation.
   """
   def string_to_ast(string, opts // []) do
     file = Keyword.get opts, :file, "nofile"

lib/elixir/lib/kernel/cli.ex

@@ -224,7 +224,7 @@ defmodule Kernel.CLI do
   end
 
   defp process_command({:eval, expr}, _config) when is_binary(expr) do
-    Code.eval(expr, [])
+    Code.eval_string(expr, [])
     :ok
   end
 

lib/elixir/lib/module.ex

@@ -31,7 +31,7 @@ defmodule Module do
   Evalutes the quotes contents in the given module context.
 
   A list of environment options can also be given as argument.
-  Check `Code.eval` for more information.
+  Check `Code.eval_string` for more information.
 
   Raises an error if the module was already compiled.
 

lib/elixir/test/elixir/code_test.exs

@@ -14,17 +14,17 @@ defmodule CodeTest do
 
   Code.eval_quoted contents, [], file: "sample.ex", line: 13
 
-  test :eval do
-    assert Code.eval("1 + 2") == { 3, [] }
-    assert { 3, _ } = Code.eval("a + b", [a: 1, b: 2], __ENV__.location)
+  test :eval_string do
+    assert Code.eval_string("1 + 2") == { 3, [] }
+    assert { 3, _ } = Code.eval_string("a + b", [a: 1, b: 2], __ENV__.location)
   end
 
   test :eval_with_scope do
-    assert Code.eval("one", [], delegate_locals_to: __MODULE__) == { 1, [] }
+    assert Code.eval_string("one", [], delegate_locals_to: __MODULE__) == { 1, [] }
   end
 
   test :eval_with_requires do
-    assert Code.eval("Kernel.if true, do: :ok", [], requires: [Z, Kernel]) == { :ok, [] }
+    assert Code.eval_string("Kernel.if true, do: :ok", [], requires: [Z, Kernel]) == { :ok, [] }
   end
 
   test :eval_quoted do

lib/elixir/test/elixir/kernel/cli_test.exs

@@ -19,7 +19,7 @@ defmodule Kernel.CLI.OptionParsingTest do
   test :path do
     root = fixture_path("../../..") |> to_char_list
     list = elixir('-pa "#{root}/*" -pz "#{root}/lib/*" -e "IO.inspect :code.get_path"')
-    { path, _ } = Code.eval list, []
+    { path, _ } = Code.eval_string list, []
 
     # pa
     assert Path.expand('ebin', root) in path

lib/elixir/test/elixir/system_test.exs

@@ -39,7 +39,7 @@ defmodule SystemTest do
 
   test :argv do
     list = elixir('-e "IO.inspect System.argv" -- -o opt arg1 arg2 --long-opt 10')
-    { args, _ } = Code.eval list, []
+    { args, _ } = Code.eval_string list, []
     assert args == ["-o", "opt", "arg1", "arg2", "--long-opt", "10"]
   end
 

lib/mix/lib/mix/deps/lock.ex

@@ -15,7 +15,7 @@ defmodule Mix.Deps.Lock do
   def read() do
     case File.read(lockfile) do
       { :ok, info } ->
-        { value, _binding } = Code.eval(info)
+        { value, _binding } = Code.eval_string(info)
         value || []
       { :error, _ } ->
         []

lib/mix/lib/mix/tasks/run.ex

@@ -44,7 +44,7 @@ defmodule Mix.Tasks.Run do
     end
 
     Mix.Task.run "app.start", args
-    if head != [], do: Code.eval Enum.join(head, " ")
+    if head != [], do: Code.eval_string Enum.join(head, " ")
     if opts[:no_halt], do: :timer.sleep(:infinity)
   end