Add :records, :binaries and :char_lists options to inspect/2

Deprecate :raw in favor of :records

Author: ericmj

CHANGELOG.md

@@ -18,6 +18,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`
+  * [Kernel] `Kernel.inspect/2` with `:raw` option is deprecated, use `:records` option instead
 
 * Backwards incompatible changes
 

lib/elixir/lib/inspect.ex

@@ -1,7 +1,13 @@
 import Kernel, except: [inspect: 1]
 import Inspect.Algebra
 
-defrecord Inspect.Opts, raw: false, limit: 50, pretty: false, width: 80
+defrecord Inspect.Opts,
+  records: true,
+  binaries: :infer,
+  char_lists: :infer,
+  limit: 50,
+  pretty: false,
+  width: 80
 
 defprotocol Inspect do
   @moduledoc """
@@ -43,8 +49,8 @@ defprotocol Inspect do
   ## Error handling
 
   In case there is an error while your structure is being inspected,
-  Elixir will automatically default to the raw inspecting. You can
-  however access the underlying error by invoking the Inspect
+  Elixir will automatically fall back to tuple inspection for records.
+  You can however access the underlying error by invoking the Inspect
   implementation directly. For example, to test Inspect.HashSet above,
   you just need to do:
 
@@ -158,8 +164,8 @@ defimpl Inspect, for: BitString do
       "<<0, 1, 2>>"
 
   """
-  def inspect(thing, opts) when is_binary(thing) do
-    if String.printable?(thing) do
+  def inspect(thing, Inspect.Opts[binaries: bins] = opts) when is_binary(thing) do
+    if bins == :as_strings or (bins == :infer and String.printable?(thing)) do
       << ?", escape(thing, ?") :: binary, ?" >>
     else
       inspect_bitstring(thing, opts)
@@ -213,11 +219,29 @@ defimpl Inspect, for: BitString do
   defp escape(<<?\v, t :: binary>>, char, binary) do
     escape(t, char, << binary :: binary, ?\\, ?v >>)
   end
+  defp escape(<<h :: utf8, t :: binary>>, char, binary) do
+    head = << h :: utf8 >>
+    if String.printable?(head) do
+      escape(t, char, append(head, binary))
+    else
+      << byte :: size(8), h :: binary >> = head
+      t = << h :: binary, t :: binary >>
+      escape(t, char, << binary :: binary, octify(byte) :: binary >>)
+    end
+  end
   defp escape(<<h, t :: binary>>, char, binary) do
-    escape(t, char, << binary :: binary, h >>)
+    escape(t, char, << binary :: binary, octify(h) :: binary >>)
   end
   defp escape(<<>>, _char, binary), do: binary
 
+  defp octify(byte) do
+    << hi :: size(2), mi :: size(3), lo :: size(3) >> = << byte >>
+    << ?\\, ?0 + hi, ?0 + mi, ?0 + lo >>
+  end
+
+  defp append(<<h, t :: binary>>, binary), do: append(t, << binary :: binary, h >>)
+  defp append(<<>>, binary), do: binary
+
   ## Bitstrings
 
   defp inspect_bitstring(bitstring, Inspect.Opts[] = opts) do
@@ -270,11 +294,11 @@ defimpl Inspect, for: List do
 
   def inspect([], _opts), do: "[]"
 
-  def inspect(thing, Inspect.Opts[] = opts) do
+  def inspect(thing, Inspect.Opts[char_lists: lists] = opts) do
     cond do
-      :io_lib.printable_list(thing) ->
+      lists == :as_char_lists or (lists == :infer and :io_lib.printable_list(thing)) ->
         << ?', Inspect.BitString.escape(String.from_char_list!(thing), ?') :: binary, ?' >>
-      keyword?(thing) && not opts.raw ->
+      keyword?(thing) ->
         surround_many("[", thing, "]", opts.limit, &keyword(&1, opts))
       true ->
         surround_many("[", thing, "]", opts.limit, &to_doc(&1, opts))
@@ -322,20 +346,24 @@ defimpl Inspect, for: Tuple do
 
   def inspect({}, _opts), do: "{}"
 
-  def inspect(tuple, opts) do
-    unless opts.raw do
+  def inspect(tuple, Inspect.Opts[] = opts) do
+    if opts.records do
       record_inspect(tuple, opts)
-    end || surround_many("{", tuple_to_list(tuple), "}", opts.limit, &to_doc(&1, opts))
+    else
+      surround_many("{", tuple_to_list(tuple), "}", opts.limit, &to_doc(&1, opts))
+    end
   end
 
   ## Helpers
 
-  defp record_inspect(record, opts) do
+  defp record_inspect(record, Inspect.Opts[] = opts) do
     [name|tail] = tuple_to_list(record)
 
     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, &to_doc(&1, opts))
+    else
+      surround_many("{", [name|tail], "}", opts.limit, &to_doc(&1, opts))
+    end
   end
 
   defp record_fields(name) do
@@ -350,7 +378,7 @@ defimpl Inspect, for: Tuple do
     end
   end
 
-  defp surround_record(name, fields, tail, opts) do
+  defp surround_record(name, fields, tail, Inspect.Opts[] = opts) do
     concat(
       Inspect.Atom.inspect(name, opts),
       surround_many("[", zip_fields(fields, tail), "]", opts.limit, &keyword(&1, opts))
@@ -421,8 +449,8 @@ defimpl Inspect, for: Regex do
     concat ["%r", to_doc(Regex.source(regex), opts), Regex.opts(regex)]
   end
 
-  def inspect(other, opts) do
-    to_doc(other, opts.raw(true))
+  def inspect(other, Inspect.Opts[] = opts) do
+    to_doc(other, opts.records(false))
   end
 end
 

lib/elixir/lib/inspect/algebra.ex

@@ -106,19 +106,18 @@ defmodule Inspect.Algebra do
   """
   @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
+    if is_tuple(arg) do
+      if elem(opts, Inspect.Opts.__record__(:index, :records)) do
+        try do
+          Inspect.inspect(arg, opts)
+        catch
+          _, _ -> Inspect.Tuple.inspect(arg, opts)
         end
-      false ->
-        Inspect.inspect(arg, opts)
+      else
+        Inspect.Tuple.inspect(arg, opts)
+      end
+    else
+      Inspect.inspect(arg, opts)
     end
   end
 

lib/elixir/lib/kernel.ex

@@ -1710,8 +1710,20 @@ defmodule Kernel do
 
   The following options are supported:
 
-  * `:raw`   - when true, record tuples are not formatted by the inspect protocol,
-               but are printed as just tuples, defaults to false;
+  * `:records` - when false, records are not formatted by the inspect protocol,
+                 they are instead printed as just tuples, defaults to true;
+
+  * `:binaries` - when `:as_strings` all binaries will be printed as strings,
+                  non-printable bytes will be escaped; when `:as_binaries` all
+                  binaries will be printed in bit syntax; when the default
+                  `:infer`, the binary will be printed as a string if it is
+                  printable, otherwise in bit syntax;
+
+  * `:char_lists` - when `:as_char_lists` all lists will be printed as char lists,
+                    non-printable elements will be escaped; when `:as_lists` all
+                    lists will be printed as lists; when the default `:infer`, the
+                    list will be printed as a char list if it is printable,
+                    otherwise as list;
 
   * `:limit` - limits the number of items that are printed for tuples, bitstrings,
                and lists, does not apply to strings nor char lists, defaults to 50;
@@ -1732,9 +1744,18 @@ defmodule Kernel do
       iex> inspect(ArgumentError[])
       "ArgumentError[message: \"argument error\"]"
 
-      iex> inspect(ArgumentError[], raw: true)
+      iex> inspect(ArgumentError[], records: false)
       "{ArgumentError, :__exception__, \"argument error\"}"
 
+      iex> inspect("josé" <> <<0>>)
+      "<<106, 111, 115, 195, 169, 0>>"
+
+      iex> inspect("josé" <> <<0>>, binaries: :as_strings)
+      "\"josé\\000\""
+
+      iex> inspect("josé", binaries: :as_binaries)
+      "<<106, 111, 115, 195, 169>>"
+
   Note that the inspect protocol does not necessarily return a valid
   representation of an Elixir term. In such cases, the inspected result
   must start with `#`. For example, inspecting a function will return:
@@ -1752,6 +1773,11 @@ defmodule Kernel do
   end
 
   def inspect(arg, opts) when is_list(opts) do
+    unless nil?(raw = opts[:raw]) do
+      IO.write "Kernel.inspect/2 with :raw option is deprecated, please use :records instead\n#{Exception.format_stacktrace}"
+      opts = opts ++ [records: !raw]
+    end
+
     opts  = Inspect.Opts.new(opts)
     limit = case opts.pretty do
       true  -> opts.width
@@ -2956,7 +2982,7 @@ defmodule Kernel do
   the record name, we can get the raw record representation as
   follows:
 
-      inspect User.new, raw: true
+      inspect User.new, records: false
       #=> { User, nil, 0 }
 
   In addition to defining readers and writers for each attribute, Elixir also

lib/elixir/lib/macro.ex

@@ -417,7 +417,7 @@ defmodule Macro do
   end
 
   # All other structures
-  def to_string(other, fun), do: fun.(other, inspect(other, raw: true))
+  def to_string(other, fun), do: fun.(other, inspect(other, records: false))
 
   # Block keywords
   @kw_keywords [:do, :catch, :rescue, :after, :else]
@@ -427,7 +427,7 @@ defmodule Macro do
   end
   defp kw_blocks?(_), do: false
 
-  defp module_to_string(atom, _fun) when is_atom(atom), do: inspect(atom, raw: true)
+  defp module_to_string(atom, _fun) when is_atom(atom), do: inspect(atom, records: false)
   defp module_to_string(other, fun), do: call_to_string(other, fun)
 
   defp call_to_string(atom, _fun) when is_atom(atom), do: atom_to_binary(atom)

lib/elixir/lib/record.ex

@@ -96,9 +96,9 @@ defmodule Record do
 
   Notice that now since the record definition is accessible, Elixir
   shows the record nicely formatted, no longer as a simple tuple. We
-  can get the raw formatting by passing `raw: true` to `inspect`:
+  can get the raw formatting by passing `records: false` to `inspect`:
 
-      inspect user(), raw: true
+      inspect user(), records: false
       { User, "José", 25 }
 
   Since working with external records is common, Elixir allows

lib/elixir/src/elixir_exp.erl

@@ -343,7 +343,7 @@ expand({ _, Meta, Args } = Invalid, E) when is_list(Meta) and is_list(Args) ->
 
 expand({ _, _, _ } = Tuple, E) ->
   compile_error([{line,0}], E#elixir_env.file, "invalid quoted expression: ~ts",
-    ['Elixir.Kernel':inspect(Tuple, [{raw,true}])]);
+    ['Elixir.Kernel':inspect(Tuple, [{records,false}])]);
 
 %% Literals
 

lib/elixir/test/elixir/inspect_test.exs

@@ -71,8 +71,22 @@ defmodule Inspect.BitStringTest do
     assert inspect(" ゆんゆん") == "\" ゆんゆん\""
   end
 
-  test :unprintable do
-    assert inspect(<<193>>) == "<<193>>"
+  test :opt_infer do
+    assert inspect(<<"eric", 193, "mj">>, binaries: :infer) == %s(<<101, 114, 105, 99, 193, 109, 106>>)
+    assert inspect(<<"eric">>, binaries: :infer) == %s("eric")
+    assert inspect(<<193>>, binaries: :infer) == %s(<<193>>)
+  end
+
+  test :opt_as_strings do
+    assert inspect(<<"eric", 193, "mj">>, binaries: :as_strings) == %s("eric\\301mj")
+    assert inspect(<<"eric">>, binaries: :as_strings) == %s("eric")
+    assert inspect(<<193>>, binaries: :as_strings) == %s("\\301")
+  end
+
+  test :opt_as_binaries do
+    assert inspect(<<"eric", 193, "mj">>, binaries: :as_binaries) == "<<101, 114, 105, 99, 193, 109, 106>>"
+    assert inspect(<<"eric">>, binaries: :as_binaries) == "<<101, 114, 105, 99>>"
+    assert inspect(<<193>>, binaries: :as_binaries) == "<<193>>"
   end
 
   test :unprintable_with_opts do
@@ -154,8 +168,8 @@ defmodule Inspect.TupleTest do
     assert inspect({ 1, 2, 3, 4 }, limit: 3) == "{1, 2, 3, ...}"
   end
 
-  test :with_raw do
-    assert inspect(Config.new, raw: true) == "{Inspect.TupleTest.Config, 1, []}"
+  test :with_records_false do
+    assert inspect(Config.new, records: false) == "{Inspect.TupleTest.Config, 1, []}"
   end
 end
 
@@ -181,16 +195,28 @@ defmodule Inspect.ListTest do
            "[foo: [1, 2, 3, :bar],\n bazzz: :bat]"
   end
 
-  test :keyword_with_raw do
-    assert inspect([a: 1], raw: true) == "[{:a, 1}]"
-    assert inspect([a: 1, b: 2], raw: true) == "[{:a, 1}, {:b, 2}]"
-    assert inspect([a: 1, a: 2, b: 2], raw: true) == "[{:a, 1}, {:a, 2}, {:b, 2}]"
-  end
-
   test :non_keyword do
     assert inspect([{ Regex, 1 }]) == "[{Regex, 1}]"
   end
 
+  test :opt_infer do
+    assert inspect('eric' ++ [0] ++ 'mj', char_lists: :infer) == "[101, 114, 105, 99, 0, 109, 106]"
+    assert inspect('eric', char_lists: :infer) == "'eric'"
+    assert inspect([0], char_lists: :infer) == "[0]"
+  end
+
+  test :opt_as_strings do
+    assert inspect('eric' ++ [0] ++ 'mj', char_lists: :as_char_lists) == "'eric\\000mj'"
+    assert inspect('eric', char_lists: :as_char_lists) == "'eric'"
+    assert inspect([0], char_lists: :as_char_lists) == "'\\000'"
+  end
+
+  test :opt_as_lists do
+    assert inspect('eric' ++ [0] ++ 'mj', char_lists: :as_lists) == "[101, 114, 105, 99, 0, 109, 106]"
+    assert inspect('eric', char_lists: :as_lists) == "[101, 114, 105, 99]"
+    assert inspect([0], char_lists: :as_lists) == "[0]"
+  end
+
   test :non_printable do
     assert inspect([{:b, 1}, {:a, 1}]) == "[b: 1, a: 1]"
   end

lib/ex_unit/lib/ex_unit/doc_test.ex

@@ -504,7 +504,7 @@ defmodule ExUnit.DocTest do
   # Finally, parse expected_acc.
   defp extract_tests([expected|lines], line, expr_acc, expected_acc, [test=Test[exprs: exprs]|t]=acc, newtest) do
     if expected =~ %r/^#[A-Z][\w\.]*<.*>$/ do
-      expected = expected_acc <> "\n" <> Inspect.BitString.inspect(expected, [])
+      expected = expected_acc <> "\n" <> inspect(expected)
       test = test.exprs([{ expr_acc, { :inspect, expected } } | exprs])
       extract_tests(lines, line,  "", "", [test|t], newtest)
     else

lib/iex/lib/iex/options.ex

@@ -17,8 +17,8 @@ defmodule IEx.Options do
       iex(1)> ArgumentError[]
       ArgumentError[message: "argument error"]
 
-      iex(2)> IEx.Options.set :inspect, raw: true
-      [limit: 50, raw: false]
+      iex(2)> IEx.Options.set :inspect, records: false
+      [limit: 50, records: true]
 
       iex(3)> ArgumentError[]
       {ArgumentError,:__exception__,"argument error"}