Exception.normalize/1 is deprecated in favor of Exception.normalize/2

Author: José Valim

CHANGELOG.md

@@ -32,6 +32,7 @@
 
 * Deprecations
   * [Dict] `Dict.empty/1`, `Dict.new/1` and `Dict.new/2` are deprecated
+  * [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)
 

lib/elixir/lib/exception.ex

@@ -139,20 +139,19 @@ end
 
 defmodule Exception do
   @moduledoc """
-  Convenience functions to work with and pretty print
-  exceptions and stacktraces.
-
-  Notice that stacktraces in Elixir are updated on errors.
-  For example, at any given moement, `System.stacktrace`
-  will return the stacktrace for the last error that ocurred
-  in the current process.
-
-  That said, many of the functions in this module will
-  automatically calculate the stacktrace based on the caller,
-  when invoked without arguments, changing the value of
-  `System.stacktrace`. If instead you want to format the
-  stacktrace of the latest error, you should instead explicitly
-  pass the `System.stacktrace` as argument.
+  Functions to work with and pretty print exceptions.
+
+  Note that stacktraces in Elixir are updated on throw,
+  errors and exits. For example, at any given moment,
+  `System.stacktrace` will return the stacktrace for the
+  last throw/error/exit that ocurred in the current process.
+
+  Finally note developers should not rely on the particular
+  format of the `format` functions provided by this module.
+  They may be changed in future releases in order to better
+  suit Elixir's tool chain. In other words, by using the
+  functions in this module it is guarantee you will format
+  exceptions as in the current Elixir version being used.
   """
 
   @type stacktrace :: [stacktrace_entry]
@@ -172,75 +171,75 @@ defmodule Exception do
   normalizes only `:error`, returning the untouched payload
   for others.
   """
-  def normalize(:error, exception), do: normalize(exception)
-  def normalize(_kind, other), do: other
+  def normalize(:error, exception), do: normalize_error(exception)
+  def normalize(_kind, payload),    do: payload
 
-  @doc """
-  Normalizes an exception, converting Erlang exceptions
-  to Elixir exceptions.
+  @doc false
+  def normalize(error) do
+    IO.write :stderr, "Exception.normalize/1 is deprecated, please use Exception.normalize/2 instead\n#{Exception.format_stacktrace}"
+    normalize_error(error)
+  end
 
-  Useful when interfacing Erlang code with Elixir code.
-  """
-  def normalize(exception) when is_exception(exception) do
+  defp normalize_error(exception) when is_exception(exception) do
     exception
   end
 
-  def normalize(:badarg) do
+  defp normalize_error(:badarg) do
     ArgumentError[]
   end
 
-  def normalize(:badarith) do
+  defp normalize_error(:badarith) do
     ArithmeticError[]
   end
 
-  def normalize(:system_limit) do
+  defp normalize_error(:system_limit) do
     SystemLimitError[]
   end
 
-  def normalize({ :badarity, { fun, args } }) do
+  defp normalize_error({ :badarity, { fun, args } }) do
     BadArityError[function: fun, args: args]
   end
 
-  def normalize({ :badfun, term }) do
+  defp normalize_error({ :badfun, term }) do
     BadFunctionError[term: term]
   end
 
-  def normalize({ :badstruct, struct, term }) do
+  defp normalize_error({ :badstruct, struct, term }) do
     BadStructError[struct: struct, term: term]
   end
 
-  def normalize({ :badmatch, term }) do
+  defp normalize_error({ :badmatch, term }) do
     MatchError[term: term]
   end
 
-  def normalize({ :case_clause, term }) do
+  defp normalize_error({ :case_clause, term }) do
     CaseClauseError[term: term]
   end
 
-  def normalize({ :try_clause, term }) do
+  defp normalize_error({ :try_clause, term }) do
     TryClauseError[term: term]
   end
 
-  def normalize(:undef) do
+  defp normalize_error(:undef) do
     { mod, fun, arity } = from_stacktrace(:erlang.get_stacktrace)
     UndefinedFunctionError[module: mod, function: fun, arity: arity]
   end
 
-  def normalize(:function_clause) do
+  defp normalize_error(:function_clause) do
     { mod, fun, arity } = from_stacktrace(:erlang.get_stacktrace)
     FunctionClauseError[module: mod, function: fun, arity: arity]
   end
 
-  def normalize({ :badarg, payload }) do
+  defp normalize_error({ :badarg, payload }) do
     ArgumentError[message: "argument error: #{inspect(payload)}"]
   end
 
-  def normalize(other) do
+  defp normalize_error(other) do
     ErlangError[original: other]
   end
 
   @doc """
-  Receives an stacktrace entry and formats it into a string.
+  Receives a stacktrace entry and formats it into a string.
   """
   @spec format_stacktrace_entry(stacktrace_entry) :: String.t
   def format_stacktrace_entry(entry)
@@ -260,11 +259,11 @@ defmodule Exception do
     format_location(location) <> "(file)"
   end
 
-  def format_stacktrace_entry({module, fun, arity, location}) do
+  def format_stacktrace_entry({ module, fun, arity, location }) do
     format_application(module) <> format_location(location) <> format_mfa(module, fun, arity)
   end
 
-  def format_stacktrace_entry({fun, arity, location}) do
+  def format_stacktrace_entry({ fun, arity, location }) do
     format_location(location) <> format_fa(fun, arity)
   end
 

lib/elixir/src/elixir_try.erl

@@ -42,7 +42,7 @@ each_clause({ rescue, Meta, [{ in, _, [Left, Right]}], Expr }, Return, S) ->
           { FinalClause, _ } = rescue_guards(Meta, ClauseVar, Right, S),
           Match = { '=', Meta, [
             Left,
-            { { '.', Meta, ['Elixir.Exception', normalize] }, Meta, [ClauseVar] }
+            { { '.', Meta, ['Elixir.Exception', normalize] }, Meta, [error, ClauseVar] }
           ] },
           FinalExpr = prepend_to_block(Meta, Match, Expr),
           each_clause({ 'catch', Meta, FinalClause, FinalExpr }, Return, CS)

lib/elixir/test/elixir/exception_test.exs

@@ -14,9 +14,6 @@ defmodule Kernel.ExceptionTest do
   end
 
   test "normalize" do
-    assert is_record Exception.normalize(:badarg), ArgumentError
-    assert is_record Exception.normalize(ArgumentError[]), ArgumentError
-
     assert Exception.normalize(:throw, :badarg) == :badarg
     assert is_record Exception.normalize(:error, :badarg), ArgumentError
     assert is_record Exception.normalize(:error, ArgumentError[]), ArgumentError
@@ -105,7 +102,7 @@ defmodule Kernel.ExceptionTest do
       end
     file = __ENV__.file |> Path.relative_to_cwd |> String.to_char_list!
     assert {Kernel.ExceptionTest, :"test raise preserves the stacktrace", _,
-           [file: ^file, line: 101]} = stacktrace
+           [file: ^file, line: 98]} = stacktrace
   end
 
   test "defexception" do