Promote exception/1 as the best mechanism to customize exceptions

The previous mechanism of lazily customizing message/1 was very
dangerous, as you could have errors while calculating the message
and those would shop up just when the exception is printed, leading
to further breakage.

Closes #1747

Author: José Valim

CHANGELOG.md

@@ -1,6 +1,7 @@
 # v0.11.3-dev
 
 * Enhancements
+  * [Exception] Allow `exception/1` to be overriden and promote it as the main mechanism to customize exceptions
   * [Kernel] Add `List.delete_at/2` and `List.updated_at/3`
   * [Kernel] Add `Enum.reverse/2`
   * [Kernel] Implement `defmodule/2`, `@/1`, `def/2` and friends in Elixir itself. `case/2`, `try/2` and `receive/1` have been made special forms. `var!/1`, `var!/2` and `alias!/1` have also been implemented in Elixir and demoted from special forms

lib/elixir/lib/code.ex

@@ -1,7 +1,8 @@
 defmodule Code do
-  defexception LoadError, file: nil do
-    def message(exception) do
-      "could not load #{exception.file}"
+  defexception LoadError, [:file, :message] do
+    def exception(opts) do
+      file = opts[:file]
+      LoadError[message: "could not load #{file}", file: file]
     end
   end
 
@@ -10,7 +11,6 @@ defmodule Code do
 
   This module complements [Erlang's code module](http://www.erlang.org/doc/man/code.html)
   to add behavior which is specific to Elixir.
-
   """
 
   @doc """

lib/elixir/lib/exception.ex

@@ -1,3 +1,7 @@
+# Some exceptions implement `message/1` instead of `exception/1` mostly
+# for bootstrap reasons. It is recommended for applications to implement
+# `exception/1` instead of `message/1` as described in `defexception/3` docs.
+
 defexception RuntimeError,      message: "runtime error"
 defexception ArgumentError,     message: "argument error"
 defexception ArithmeticError,   message: "bad argument in arithmetic expression"
@@ -100,6 +104,22 @@ defexception Enum.OutOfBoundsError, message: "out of bounds error"
 
 defexception Enum.EmptyError, message: "empty error"
 
+defexception File.Error, [reason: nil, action: "", path: nil] do
+  def message(exception) do
+    formatted = iolist_to_binary(:file.format_error(reason exception))
+    "could not #{action exception} #{path exception}: #{formatted}"
+  end
+end
+
+defexception File.CopyError, [reason: nil, action: "", source: nil, destination: nil, on: nil] do
+  def message(exception) do
+    formatted = iolist_to_binary(:file.format_error(reason exception))
+    location  = if on = on(exception), do: ". #{on}", else: ""
+    "could not #{action exception} from #{source exception} to " <>
+      "#{destination exception}#{location}: #{formatted}"
+  end
+end
+
 defmodule Exception do
   @moduledoc """
   Convenience functions to work with and pretty print

lib/elixir/lib/file.ex

@@ -31,22 +31,6 @@ defrecord File.Stat, Record.extract(:file_info, from_lib: "kernel/include/file.h
   """
 end
 
-defexception File.Error, [reason: nil, action: "", path: nil] do
-  def message(exception) do
-    formatted = iolist_to_binary(:file.format_error(reason exception))
-    "could not #{action exception} #{path exception}: #{formatted}"
-  end
-end
-
-defexception File.CopyError, [reason: nil, action: "", source: nil, destination: nil, on: nil] do
-  def message(exception) do
-    formatted = iolist_to_binary(:file.format_error(reason exception))
-    location  = if on = on(exception), do: ". #{on}", else: ""
-    "could not #{action exception} from #{source exception} to " <>
-      "#{destination exception}#{location}: #{formatted}"
-  end
-end
-
 defmodule File do
   @moduledoc """
   This module contains functions to manipulate files.

lib/elixir/lib/io.ex

@@ -1,7 +1,8 @@
-defexception IO.StreamError, reason: nil do
-  def message(exception) do
-    formatted = iolist_to_binary(:file.format_error(reason exception))
-    "error during streaming: #{formatted}"
+defexception IO.StreamError, [:reason, :message] do
+  def exception(opts) do
+    reason    = opts[:reason]
+    formatted = iolist_to_binary(:file.format_error(reason))
+    IO.StreamError[message: "error during streaming: #{formatted}", reason: reason]
   end
 end
 

lib/elixir/lib/kernel.ex

@@ -1466,15 +1466,34 @@ defmodule Kernel do
 
   """
   @spec raise(binary | atom | tuple) :: no_return
-  defmacro raise(msg) when is_binary(msg) do
-    quote do
-      :erlang.error RuntimeError.exception(message: unquote(msg))
+  defmacro raise(msg) do
+    # Try to figure out the type at compilation time
+    # to avoid dead code and make dialyzer happy.
+    msg = case not is_binary(msg) and bootstraped?(Macro.Env) do
+      true  -> Macro.expand(msg, __CALLER__)
+      false -> msg
     end
-  end
 
-  defmacro raise({ tag, _, _ } = exception) when tag == :<<>> or tag == :<> do
-    quote do
-      :erlang.error RuntimeError.exception(message: unquote(exception))
+    case msg do
+      msg when is_binary(msg) ->
+        quote do
+          :erlang.error RuntimeError.exception(message: unquote(msg))
+        end
+      { :<<>>, _, _ } = msg ->
+        quote do
+          :erlang.error RuntimeError.exception(message: unquote(msg))
+        end
+      alias when is_atom(alias) ->
+        quote do
+          :erlang.error unquote(alias).exception([])
+        end
+      _ ->
+        quote do
+          case unquote(msg) do
+            msg when is_binary(msg) -> :erlang.error RuntimeError.exception(message: msg)
+            msg -> :erlang.error msg.exception([])
+          end
+        end
     end
   end
 
@@ -1486,8 +1505,7 @@ defmodule Kernel do
   structure.
 
   Any module defined via `defexception` automatically
-  defines both `exception(args)` and `exception(args, current)`
-  that creates a new and updates the given exception.
+  implements `exception(args)` callback expected by `raise/2`.
 
   ## Examples
 
@@ -1496,35 +1514,9 @@ defmodule Kernel do
 
   """
   @spec raise(tuple | atom, list) :: no_return
-  defmacro raise(exception, args // [])
-
-  defmacro raise({ :{}, _, _ } = exception, args) do
-    quote do
-      :erlang.error unquote(exception).exception(unquote(args))
-    end
-  end
-
-  defmacro raise({ :__aliases__, _, _ } = exception, args) do
-    quote do
-      :erlang.error unquote(exception).exception(unquote(args))
-    end
-  end
-
-  defmacro raise(exception, args) when is_atom(exception) do
-    quote do
-      :erlang.error unquote(exception).exception(unquote(args))
-    end
-  end
-
   defmacro raise(exception, args) do
     quote do
-      exception = unquote(exception)
-      case exception do
-        e when is_binary(e) ->
-          :erlang.error RuntimeError.exception(message: exception)
-        _ ->
-          :erlang.error exception.exception(unquote(args))
-      end
+      :erlang.error unquote(exception).exception(unquote(args))
     end
   end
 
@@ -1551,8 +1543,10 @@ defmodule Kernel do
   may change the `System.stacktrace` value.
   """
   @spec raise(tuple | atom, list, list) :: no_return
-  def raise(exception, args, stacktrace) do
-    :erlang.raise :error, exception.exception(args), stacktrace
+  defmacro raise(exception, args, stacktrace) do
+    quote do
+      :erlang.raise :error, unquote(exception).exception(unquote(args)), unquote(stacktrace)
+    end
   end
 
   @doc """
@@ -3182,18 +3176,47 @@ defmodule Kernel do
     Record.defrecordp(name, Macro.expand(tag, __CALLER__), fields)
   end
 
-  @doc """
+  @doc %S"""
   Defines an exception.
 
-  Exceptions are simply records and therefore `defexception/3` has
-  the same API and similar behavior to `defrecord/3` with two notable
-  differences:
+  Exceptions are simply records with three differences:
+
+  1. Exceptions are required to defined a function `exception/1`
+     that receives keyword arguments and returns the exception.
+     This function is a callback usually invoked by `raise/2`;
+
+  2. Exceptions are required to provide a `message` field.
+     This field must return a String with a formatted error message;
+
+  3. Unlike records, exceptions are documented by default.
+
+  Since exceptions are records, `defexception/3` has exactly
+  the same API as `defrecord/3`.
+
+  ## Raising exceptions
 
-  1) Unlike records, exceptions are documented by default;
+  The most common way to raise an exception is via the raise
+  function:
+
+      defexception MyException, [:message]
+      raise MyException,
+        message: "did not get what expected, got: #{inspect value}"
+
+  In many cases though, it is more convenient to just pass the
+  expected value to raise and generate the message in the `exception/1`
+  callback:
+
+      defexception MyException, [:message] do
+        def exception(opts) do
+          msg = "did not get what expected, got: #{inspect opts[:actual]}"
+          MyException[message: msg]
+        end
+      end
 
-  2) Exceptions **must** implement `message/1` -- a function that returns a
-     string;
+      raise MyException, actual: value
 
+  The example above is the preferred mechanism for customizing
+  exception messages.
   """
   defmacro defexception(name, fields, do_block // []) do
     { fields, do_block } =
@@ -3204,14 +3227,15 @@ defmodule Kernel do
 
     do_block = Keyword.put(do_block, :do, quote do
       @moduledoc nil
-      record_type message: binary
+      record_type message: String.t
 
       @doc false
       def exception(args), do: new(args)
 
       @doc false
       def exception(args, self), do: update(args, self)
 
+      defoverridable exception: 1, exception: 2
       unquote(Keyword.get do_block, :do)
     end)
 

lib/elixir/lib/module.ex

@@ -677,7 +677,12 @@ defmodule Module do
           raise "Cannot make function #{name}/#{arity} overridable because it was not defined"
         clause ->
           :elixir_def.delete_definition(module, tuple)
-          neighbours = Module.DispatchTracker.yank(module, tuple)
+
+          neighbours = if loaded?(Module.DispatchTracker) do
+            Module.DispatchTracker.yank(module, tuple)
+          else
+            []
+          end
 
           old    = get_attribute(module, :__overridable)
           merged = :orddict.update(tuple, fn({ count, _, _, _ }) ->
@@ -942,4 +947,6 @@ defmodule Module do
       raise ArgumentError,
         message: "could not call #{fun} on module #{inspect module} because it was already compiled"
   end
+
+  defp loaded?(module), do: is_tuple :code.is_loaded(module)
 end

lib/elixir/lib/string.ex

@@ -1056,9 +1056,12 @@ defmodule String do
     raise ArgumentError
   end
 
-  defexception UnicodeConversionError, encoded: nil, rest: nil, kind: nil do
-    def message(exception) do
-      "#{exception.kind} #{detail(exception.rest)}"
+  defexception UnicodeConversionError, [:encoded, :message] do
+    def exception(opts) do
+      UnicodeConversionError[
+        encoded: opts[:encoded],
+        message: "#{opts[:kind]} #{detail(opts[:rest])}"
+      ]
     end
 
     defp detail(rest) when is_binary(rest) do

lib/elixir/lib/version.ex

@@ -2,7 +2,7 @@ defmodule Version do
   @moduledoc %S"""
   Functions for parsing and matching versions against requirements.
 
-  A version is a string in a specific format or a `Version.Schema` 
+  A version is a string in a specific format or a `Version.Schema`
   generated after parsing via `Version.parse/1`.
 
   `Version` parsing and requirements follow
@@ -31,7 +31,7 @@ defmodule Version do
 
   Requirements allow you to specify which versions of a given
   dependency you are willing to work against. It supports common
-  operators like `>=`, `<=`, `>`, `==` and friends that 
+  operators like `>=`, `<=`, `>`, `==` and friends that
   work as one would expect:
 
       # Only version 2.0.0
@@ -65,22 +65,25 @@ defmodule Version do
   defrecord Schema, major: 0, minor: 0, patch: 0, pre: nil, build: nil, source: nil
   defrecord Requirement, source: nil, matchspec: nil
 
-  defexception InvalidRequirement, reason: :invalid_requirement do
-    def message(InvalidRequirement[reason: reason]) when is_binary(reason) do
-      { first, rest } = String.next_grapheme(reason)
-      String.downcase(first) <> rest
-    end
+  defexception InvalidRequirement, [:message] do
+    def exception(opts) do
+      message =
+        if is_binary opts[:reason] do
+          { first, rest } = String.next_grapheme(opts[:reason])
+          String.downcase(first) <> rest
+        else
+          "invalid version specification"
+        end
 
-    def message(InvalidRequirement[]) do
-      "invalid version specification"
+      InvalidRequirement[message: message]
     end
   end
 
   @doc """
   Check if the given version matches the specification.
 
   Returns `true` if `version` satisfies `requirement`, `false` otherwise.
-  Raises a `Version.InvalidRequirement` exception if `requirement` is not parseable. 
+  Raises a `Version.InvalidRequirement` exception if `requirement` is not parseable.
 
   ## Examples
 

lib/elixir/src/elixir_def_overridable.erl

@@ -43,7 +43,12 @@ store(Module, Function, GenerateName) ->
         false -> { Kind, Name }
       end,
 
-      'Elixir.Module.DispatchTracker':reattach(Module, Kind, { Name, Arity }, Neighbours),
+      case code:is_loaded('Elixir.Module.DispatchTracker') of
+        { _, _ } ->
+          'Elixir.Module.DispatchTracker':reattach(Module, Kind, { Name, Arity }, Neighbours);
+        _ ->
+          ok
+      end,
 
       Def = { function, Line, FinalName, Arity, Clauses },
       elixir_def:store_each(false, FinalKind, File, Location,