Kernel.inspect/2 with Inspect.Opts[] is deprecated

In favor of `Inspect.Algebra.to_doc/2`. Closes #1965.

Author: José Valim

CHANGELOG.md

@@ -14,6 +14,7 @@
 
 * Deprecations
   * [Kernel] `is_alive/0` is deprecated in favor of `Node.alive?`
+  * [Kernel] `Kernel.inspect/2` with `Inspect.Opts[]` is deprecated in favor of `Inspect.Algebra.to_doc/2`
 
 * Backwards incompatible changes
 

lib/elixir/lib/inspect.ex

@@ -13,11 +13,7 @@ defprotocol Inspect do
   followed by the inspecting options, represented by the record
   `Inspect.Opts`.
 
-  Inspection is done using the functions available in
-  `Inspect.Algebra` and by calling `Kernel.inspect/2` recursively
-  passing the `Inspect.Opts` as an argument. When `Kernel.inspect/2`
-  receives an `Inspect.Opts` record as the second argument, it returns
-  the underlying algebra document instead of the formatted string.
+  Inspection is done using the functions available in `Inspect.Algebra`.
 
   ## Examples
 
@@ -29,15 +25,15 @@ defprotocol Inspect do
         import Inspect.Algebra
 
         def inspect(dict, opts) do
-          concat ["#HashSet<", Kernel.inspect(HashSet.to_list(dict), opts), ">"]
+          concat ["#HashSet<", to_doc(HashSet.to_list(dict), opts), ">"]
         end
       end
 
   The `concat` function comes from `Inspect.Algebra` and it
   concatenates algebra documents together. In the example above,
   it is concatenating the string `"HashSet<"` (all strings are
   valid algebra documents that keep their formatting when pretty
-  printed), the document returned by `Kernel.inspect/2` and the
+  printed), the document returned by `Inspect.Algebra.to_doc/2` and the
   other string `">"`.
 
   Since regular strings are valid entities in an algebra document,
@@ -281,14 +277,14 @@ defimpl Inspect, for: List do
       keyword?(thing) && not opts.raw ->
         surround_many("[", thing, "]", opts.limit, &keyword(&1, opts))
       true ->
-        surround_many("[", thing, "]", opts.limit, &Kernel.inspect(&1, opts))
+        surround_many("[", thing, "]", opts.limit, &to_doc(&1, opts))
     end
   end
 
   defp keyword({key, value}, opts) do
     concat(
       key_to_binary(key) <> ": ",
-      Kernel.inspect(value, opts)
+      to_doc(value, opts)
     )
   end
 
@@ -329,7 +325,7 @@ defimpl Inspect, for: Tuple do
   def inspect(tuple, opts) do
     unless opts.raw do
       record_inspect(tuple, opts)
-    end || surround_many("{", tuple_to_list(tuple), "}", opts.limit, &Kernel.inspect(&1, opts))
+    end || surround_many("{", tuple_to_list(tuple), "}", opts.limit, &to_doc(&1, opts))
   end
 
   ## Helpers
@@ -339,7 +335,7 @@ defimpl Inspect, for: Tuple do
 
     if is_atom(name) && (fields = record_fields(name)) && (length(fields) == size(record) - 1) do
       surround_record(name, fields, tail, opts)
-    end || surround_many("{", [name|tail], "}", opts.limit, &Kernel.inspect(&1, opts))
+    end || surround_many("{", [name|tail], "}", opts.limit, &to_doc(&1, opts))
   end
 
   defp record_fields(name) do
@@ -373,7 +369,7 @@ defimpl Inspect, for: Tuple do
   end
 
   defp keyword({ k, v }, opts) do
-    concat(k <> ": ", Kernel.inspect(v, opts))
+    concat(k <> ": ", to_doc(v, opts))
   end
 end
 
@@ -422,11 +418,11 @@ defimpl Inspect, for: Regex do
 
   """
   def inspect(regex, opts) when size(regex) == 5 do
-    concat ["%r", Kernel.inspect(Regex.source(regex), opts), Regex.opts(regex)]
+    concat ["%r", to_doc(Regex.source(regex), opts), Regex.opts(regex)]
   end
 
   def inspect(other, opts) do
-    Kernel.inspect(other, opts.raw(true))
+    to_doc(other, opts.raw(true))
   end
 end
 

lib/elixir/lib/inspect/algebra.ex

@@ -100,6 +100,28 @@ defmodule Inspect.Algebra do
     end
   end
 
+  @doc """
+  Converts an Elixir structure to an algebra document
+  according to the inspect protocol.
+  """
+  @spec to_doc(any, Inspect.Opts.t) :: t
+  def to_doc(arg, opts) when is_record(opts, Inspect.Opts) do
+    case is_tuple(arg) do
+      true ->
+        case elem(opts, 1) do
+          true  -> Inspect.Tuple.inspect(arg, opts)
+          false ->
+            try do
+              Inspect.inspect(arg, opts)
+            catch
+              _, _ -> Inspect.Tuple.inspect(arg, opts)
+            end
+        end
+      false ->
+        Inspect.inspect(arg, opts)
+    end
+  end
+
   @doc """
   Returns `:doc_nil` which is a document entity used to represent
   nothingness. Takes no arguments.

lib/elixir/lib/kernel.ex

@@ -1712,11 +1712,6 @@ defmodule Kernel do
   The second argument is a keywords list with options to control
   inspection.
 
-  The second argument may also be an instance of the `Inspect.Opts`
-  record and, in such cases, instead of returning a string, it
-  returns an algebra document which can be converted to a string
-  via `Inspect.Algebra`.
-
   ## Options
 
   The following options are supported:
@@ -1754,35 +1749,21 @@ defmodule Kernel do
       #=> #Function<...>
 
   """
-  @spec inspect(Inspect.t, Inspect.Opts.t) :: Inspect.Algebra.t
   @spec inspect(Inspect.t, Keyword.t) :: String.t
   def inspect(arg, opts // [])
 
-  def inspect(arg, opts) when is_tuple(opts) and tuple_size(opts) > 0 and
-      elem(opts, 0) == Inspect.Opts do
-    case is_tuple(arg) do
-      true ->
-        case elem(opts, 1) do
-          true  -> Inspect.Tuple.inspect(arg, opts)
-          false ->
-            try do
-              Inspect.inspect(arg, opts)
-            catch
-              _, _ -> Inspect.Tuple.inspect(arg, opts)
-            end
-        end
-      false ->
-        Inspect.inspect(arg, opts)
-    end
+  def inspect(arg, opts) when is_tuple(opts) and tuple_size(opts) > 0 and elem(opts, 0) == Inspect.Opts do
+    IO.write "Kernel.inspect/2 with Inspect.Opts is deprecated, please use Inspect.Algebra.to_doc/2 instead\n#{Exception.format_stacktrace}"
+    Inspect.Algebra.to_doc(arg, opts)
   end
 
   def inspect(arg, opts) when is_list(opts) do
-    opts = Inspect.Opts.new(opts)
-
-    case opts.pretty do
-      true  -> Inspect.Algebra.pretty(inspect(arg, opts), opts.width)
-      false -> Inspect.Algebra.pretty(inspect(arg, opts), :infinity)
+    opts  = Inspect.Opts.new(opts)
+    limit = case opts.pretty do
+      true  -> opts.width
+      false -> :infinity
     end
+    Inspect.Algebra.pretty(Inspect.Algebra.to_doc(arg, opts), limit)
   end
 
   @doc """

lib/elixir/lib/range.ex

@@ -73,7 +73,9 @@ defimpl Range.Iterator, for: Integer do
 end
 
 defimpl Inspect, for: Range do
+  import Inspect.Algebra
+
   def inspect(Range[first: first, last: last], opts) do
-    Inspect.Algebra.concat [Kernel.inspect(first, opts), "..", Kernel.inspect(last, opts)]
+    concat [to_doc(first, opts), "..", to_doc(last, opts)]
   end
 end