Merge pull request #1106 from alco/iex-opts-1062

Implement IEx.Options per #1062

Author: José Valim

lib/elixir/lib/io/ansi.ex

@@ -136,13 +136,13 @@ defmodule IO.ANSI do
   end
 
   @doc %B"""
-  Escapes a string coverting named ANSI sequences into actual ANSI codes.
+  Escapes a string by converting named ANSI sequences into actual ANSI codes.
 
-  The format for referring sequences is `%{red}` and `%{red,bright}` (for
-  multiple sequences)
+  The format for referring to sequences is `%{red}` and `%{red,bright}` (for
+  multiple sequences).
 
-  It will also force a %{reset} to get appended to every string. If you don't
-  want this behaviour, use `escape_fragment/1` and `escape_fragment/2`.
+  It will also append a %{reset} to the string. If you don't want this
+  behaviour, use `escape_fragment/1` and `escape_fragment/2`.
 
   An optional boolean parameter can be passed to enable or disable
   emitting actual ANSI codes. When false, no ANSI codes will emitted.
@@ -165,10 +165,10 @@ defmodule IO.ANSI do
   end
 
   @doc %B"""
-  Escapes a string coverting named ANSI sequences into actual ANSI codes.
+  Escapes a string by converting named ANSI sequences into actual ANSI codes.
 
-  The format for referring sequences is `%{red}` and `%{red,bright}` (for
-  multiple sequences)
+  The format for referring to sequences is `%{red}` and `%{red,bright}` (for
+  multiple sequences).
 
   An optional boolean parameter can be passed to enable or disable
   emitting actual ANSI codes. When false, no ANSI codes will emitted.
@@ -177,8 +177,10 @@ defmodule IO.ANSI do
 
   ## Example
 
-    iex> IO.ANSI.escape("Hello %{red,bright,green}yes")
-    "Hello \e[31m\e[1m\e[32myes\e[0m"
+    iex> IO.ANSI.escape_fragment("Hello %{red,bright,green}yes")
+    "Hello \e[31m\e[1m\e[32myes"
+    iex> IO.ANSI.escape_fragment("%{reset}bye")
+    "\e[0mbye"
 
   """
   @spec escape_fragment(String.t, emit :: boolean) :: String.t

lib/elixir/lib/kernel.ex

@@ -1892,17 +1892,26 @@ defmodule Kernel do
 
   The following options are supported:
 
-  * :raw - tuples are not formatted as the inspect protocol, they are
-    always shown as tuples, defaults to false;
+  * raw   -- when true, record tuples are not formatted by the inspect protocol,
+             but are printed as just tuples; default: false
 
-  * :limit - the limit of items that are shown in tuples, bitstrings and
-    lists. Does not apply to strings;
+  * limit -- limits the number of items that are printed for tuples, bitstrings,
+             and lists; does not apply to strings
 
   ## Examples
 
       iex> inspect(:foo)
       ":foo"
 
+      iex> inspect [1,2,3,4,5], limit: 3
+      "[1,2,3,...]"
+
+      inspect(ArgumentError[])
+      #=> "ArgumentError[message: \"argument error\"]"
+
+      inspect(ArgumentError[], raw: true)
+      #=> "{ArgumentError,:__exception__,\"argument error\"}"
+
   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:

lib/iex/lib/iex.ex

@@ -90,6 +90,30 @@ defmodule IEx do
   It is possible to override the default loading sequence for .iex file by
   supplying the --dot-iex option to iex. See `iex --help`.
 
+  ## Configuring the shell
+
+  There is a number of customization options provided by the shell. Take a look
+  at the docs for the `IEx.Options` module.
+
+  The main functions there are `IEx.Options.get/1` and `IEx.Options.set/2`. One
+  can also use `IEx.Options.list/0` to get the list of all supported options.
+  `IEx.Options.print_help/1` will print documentation for the given option.
+
+  In particular, it might be convenient to customize those options inside your
+  .iex file like this:
+
+      # .iex
+      IEx.Options.set :inspect, limit: 3
+
+      ### now run the shell ###
+
+      $ iex
+      Erlang R16B (erts-5.10.1) [...]
+
+      Interactive Elixir (0.9.1.dev) - press Ctrl+C to exit (type h() ENTER for help)
+      iex(1)> [1,2,3,4,5]
+      [1,2,3,...]
+
   ## Expressions in IEx
 
   As an interactive shell, IEx evaluates expressions. This has some
@@ -147,19 +171,16 @@ defmodule IEx do
     match?({ :ok, true }, :application.get_env(:iex, :started))
   end
 
-  @doc """
-  Registers options used on inspect.
-  """
+  @doc false
   def inspect_opts(opts) when is_list(opts) do
-    :application.set_env(:iex, :inspect_opts, Keyword.merge(inspect_opts, opts))
+    IO.write "[WARNING] IEx.inspect_opts is deprecated, please use IEx.Options.get/set instead. See `IEx.Options.print_help :inspect`.\n#{Exception.format_stacktrace}"
+    IEx.Options.set :inspect, opts
   end
 
-  @doc """
-  Returns currently registered inspect options.
-  """
+  @doc false
   def inspect_opts do
-    { :ok, opts } = :application.get_env(:iex, :inspect_opts)
-    opts
+    IO.write "[WARNING] IEx.inspect_opts is deprecated, please use IEx.Options.get/set instead. See `IEx.Options.print_help :inspect`.\n#{Exception.format_stacktrace}"
+    IEx.Options.get :inspect
   end
 
   # This is a callback invoked by Erlang shell utilities
@@ -203,7 +224,7 @@ defmodule IEx do
     )
 
     if opts[:inspect_opts] do
-      IEx.inspect_opts(opts[:inspect_opts])
+      IEx.Options.set :inspect, opts[:inspect_opts]
     end
 
     IEx.Config[
@@ -237,4 +258,28 @@ defmodule IEx do
   defp run_after_spawn do
     lc fun inlist Enum.reverse(after_spawn), do: fun.()
   end
+
+  @doc """
+  Returns `string` escaped using the specified color.
+  """
+  def color(color_name, string) do
+    colors = IEx.Options.get(:colors)
+    IO.ANSI.escape "%{#{colors[color_name]}}#{string}", colors[:enabled]
+  end
+
+  @doc """
+  Returns an escaped fragment using the specified color.
+  """
+  def color_fragment(color_name) do
+    colors = IEx.Options.get(:colors)
+    IO.ANSI.escape_fragment "%{#{colors[color_name]}}", colors[:enabled]
+  end
+
+  @doc """
+  Returns an escaped fragment that resets colors and attributes.
+  """
+  def color_reset() do
+    colors = IEx.Options.get(:colors)
+    IO.ANSI.escape_fragment "%{reset}", colors[:enabled]
+  end
 end

lib/iex/lib/iex/helpers.ex

@@ -86,7 +86,7 @@ defmodule IEx.Helpers do
   end
 
   defp print_history(config) do
-    IO.puts IO.ANSI.escape("%{yellow}#{config.counter}: #{config.cache}#=> #{inspect config.result}\n")
+    IO.puts IEx.color(:info, "#{config.counter}: #{config.cache}#=> #{inspect config.result}\n")
   end
 
   @doc """
@@ -294,7 +294,7 @@ defmodule IEx.Helpers do
   Prints the current working directory.
   """
   def pwd do
-    IO.puts IO.ANSI.escape("%{yellow}#{System.cwd!}")
+    IO.puts IEx.color(:info, System.cwd!)
   end
 
   @doc """
@@ -304,7 +304,7 @@ defmodule IEx.Helpers do
     case File.cd(expand_home(directory)) do
       :ok -> pwd
       { :error, :enoent } ->
-        IO.puts IO.ANSI.escape("%{red}No directory #{directory}")
+        IO.puts IEx.color(:error, "No directory #{directory}")
     end
   end
 
@@ -320,10 +320,10 @@ defmodule IEx.Helpers do
         ls_print(path, sorted_items)
 
       { :error, :enoent } ->
-        IO.puts IO.ANSI.escape("%{red}No such file or directory #{path}")
+        IO.puts IEx.color(:error, "No such file or directory #{path}")
 
       { :error, :enotdir } ->
-        IO.puts IO.ANSI.escape("%{yellow}#{Path.absname(path)}")
+        IO.puts IEx.color(:info, Path.absname(path))
     end
   end
 
@@ -365,9 +365,9 @@ defmodule IEx.Helpers do
   defp format_item(path, representation) do
     case File.stat(path) do
       { :ok, File.Stat[type: :device] } ->
-        IO.ANSI.escape("%{green}#{representation}")
+        IEx.color(:device, representation)
       { :ok, File.Stat[type: :directory] } ->
-        IO.ANSI.escape("%{blue}#{representation}")
+        IEx.color(:directory, representation)
       _ ->
         representation
     end

lib/iex/lib/iex/introspection.ex

@@ -9,20 +9,22 @@ defmodule IEx.Introspection do
       { :module, _ } ->
         case module.__info__(:moduledoc) do
           { _, binary } when is_binary(binary) ->
-            IO.puts IO.ANSI.escape("%{yellow}# #{inspect module}\n")
-            IO.write IO.ANSI.escape_fragment("%{yellow}") <> binary <> IO.ANSI.escape_fragment("%{reset}")
+            IO.puts IEx.color(:info, "# #{inspect module}\n")
+            # We use fragments here so that escape sequences in `binary` are
+            # treated literally and don't get converted to ANSI escapes.
+            IO.write IEx.color_fragment(:info) <> binary <> IEx.color_reset()
           { _, _ } ->
-            IO.puts IO.ANSI.escape("%{red}No docs for #{inspect module} have been found")
+            IO.puts IEx.color(:error, "No docs for #{inspect module} have been found")
           _ ->
-            IO.puts IO.ANSI.escape("%{red}#{inspect module} was not compiled with docs")
+            IO.puts IEx.color(:error, "#{inspect module} was not compiled with docs")
         end
       { :error, reason } ->
-        IO.puts IO.ANSI.escape("%{red}Could not load module #{inspect module}: #{reason}")
+        IO.puts IEx.color(:error, "Could not load module #{inspect module}: #{reason}")
     end
   end
 
   def h(_) do
-    IO.puts IO.ANSI.escape("%{red}Invalid arguments for h helper")
+    IO.puts IEx.color(:error, "Invalid arguments for h helper")
   end
 
   @doc false
@@ -34,7 +36,7 @@ defmodule IEx.Introspection do
       end
 
     unless result == :ok, do:
-      IO.puts IO.ANSI.escape("%{red}No docs for #{function} have been found")
+      IO.puts IEx.color(:error, "No docs for #{function} have been found")
 
     :ok
   end
@@ -44,9 +46,9 @@ defmodule IEx.Introspection do
       :ok ->
         :ok
       :no_docs ->
-        IO.puts IO.ANSI.escape("%{red}#{inspect module} was not compiled with docs")
+        IO.puts IEx.color(:error, "#{inspect module} was not compiled with docs")
       :not_found ->
-        IO.puts IO.ANSI.escape("%{red}No docs for #{inspect module}.#{function} have been found")
+        IO.puts IEx.color(:error, "No docs for #{inspect module}.#{function} have been found")
     end
 
     :ok
@@ -57,7 +59,7 @@ defmodule IEx.Introspection do
   end
 
   def h(_, _) do
-    IO.puts IO.ANSI.escape("%{red}Invalid arguments for h helper")
+    IO.puts IEx.color(:error, "Invalid arguments for h helper")
   end
 
   defp h_mod_fun(mod, fun) when is_atom(mod) and is_atom(fun) do
@@ -82,7 +84,7 @@ defmodule IEx.Introspection do
       end
 
     unless result == :ok, do:
-      IO.puts IO.ANSI.escape("%{red}No docs for #{function}/#{arity} have been found")
+      IO.puts IEx.color(:error, "No docs for #{function}/#{arity} have been found")
 
     :ok
   end
@@ -92,16 +94,16 @@ defmodule IEx.Introspection do
       :ok ->
         :ok
       :no_docs ->
-        IO.puts IO.ANSI.escape("%{red}#{inspect module} was not compiled with docs")
+        IO.puts IEx.color(:error, "#{inspect module} was not compiled with docs")
       :not_found ->
-        IO.puts IO.ANSI.escape("%{red}No docs for #{inspect module}.#{function}/#{arity} have been found")
+        IO.puts IEx.color(:error, "No docs for #{inspect module}.#{function}/#{arity} have been found")
     end
 
     :ok
   end
 
   def h(_, _, _) do
-    IO.puts IO.ANSI.escape("%{red}Invalid arguments for h helper")
+    IO.puts IEx.color(:error, "Invalid arguments for h helper")
   end
 
   defp h_mod_fun_arity(mod, fun, arity) when is_atom(mod) and is_atom(fun) and is_integer(arity) do
@@ -147,8 +149,10 @@ defmodule IEx.Introspection do
 
   defp print_doc({ { fun, _ }, _line, kind, args, doc }) do
     args = Enum.map_join(args, ", ", print_doc_arg(&1))
-    IO.puts IO.ANSI.escape("%{yellow}* #{kind} #{fun}(#{args})\n")
-    if doc, do: IO.write IO.ANSI.escape_fragment("%{yellow}") <> doc <> IO.ANSI.escape_fragment("%{reset}")
+    IO.puts IEx.color(:info, "* #{kind} #{fun}(#{args})\n")
+    # We use fragments here so that escape sequences in `doc` are
+    # treated literally and don't get converted to ANSI escapes.
+    if doc, do: IO.write IEx.color_fragment(:info) <> doc <> IEx.color_reset()
   end
 
   defp print_doc_arg({ ://, _, [left, right] }) do
@@ -164,7 +168,7 @@ defmodule IEx.Introspection do
     types = lc type inlist Kernel.Typespec.beam_types(module), do: print_type(type)
 
     if types == [] do
-      IO.puts  IO.ANSI.escape("%{red}No types for #{inspect module} have been found")
+      IO.puts IEx.color(:error, "No types for #{inspect module} have been found")
     end
 
     :ok
@@ -179,7 +183,7 @@ defmodule IEx.Introspection do
     end
 
     if types == [] do
-       IO.puts  IO.ANSI.escape("%{red}No types for #{inspect module}.#{type} have been found")
+       IO.puts  IEx.color(:error, "No types for #{inspect module}.#{type} have been found")
     end
 
     :ok
@@ -192,7 +196,7 @@ defmodule IEx.Introspection do
 
     case types do
      [] ->
-       IO.puts  IO.ANSI.escape("%{red}No types for #{inspect module}.#{type}/#{arity} have been found")
+       IO.puts  IEx.color(:error, "No types for #{inspect module}.#{type}/#{arity} have been found")
      [type] ->
        print_type(type)
     end
@@ -205,7 +209,7 @@ defmodule IEx.Introspection do
     specs = lc spec inlist beam_specs(module), do: print_spec(spec)
 
     if specs == [] do
-      IO.puts  IO.ANSI.escape("%{red}No specs for #{inspect module} have been found")
+      IO.puts  IEx.color(:error, "No specs for #{inspect module} have been found")
     end
 
     :ok
@@ -220,7 +224,7 @@ defmodule IEx.Introspection do
     end
 
     if specs == [] do
-      IO.puts  IO.ANSI.escape("%{red}No specs for #{inspect module}.#{function} have been found")
+      IO.puts  IEx.color(:error, "No specs for #{inspect module}.#{function} have been found")
     end
 
     :ok
@@ -235,7 +239,7 @@ defmodule IEx.Introspection do
     end
 
     if specs == [] do
-      IO.puts  IO.ANSI.escape("%{red}No specs for #{inspect module}.#{function} have been found")
+      IO.puts  IEx.color(:error, "No specs for #{inspect module}.#{function} have been found")
     end
 
     :ok
@@ -249,14 +253,14 @@ defmodule IEx.Introspection do
 
   defp print_type({ kind, type }) do
     ast = Kernel.Typespec.type_to_ast(type)
-    IO.puts IO.ANSI.escape("%{yellow}@#{kind} #{Macro.to_binary(ast)}")
+    IO.puts IEx.color(:info, "@#{kind} #{Macro.to_binary(ast)}")
     true
   end
 
   defp print_spec({kind, { { name, _arity }, specs }}) do
     Enum.each specs, fn(spec) ->
       binary = Macro.to_binary Kernel.Typespec.spec_to_ast(name, spec)
-      IO.puts IO.ANSI.escape("%{yellow}@#{kind} #{binary}")
+      IO.puts IEx.color(:info, "@#{kind} #{binary}")
     end
     true
   end