Deprecate IO.ANSI.terminal? and tidy up colors

Author: José Valim

CHANGELOG.md

@@ -22,6 +22,7 @@
 * Deprecations
   * [IEx] IEx color configuration expects a list of atoms instead of a string with colors separated by comma
   * [Inspect] `Inspect.Algebra.pretty/2` is deprecated in favor of `Inspect.Algebra.format/2` that instead returns iodata. This function was used only by documentation examples and it is unlikely to affect actual code
+  * [IO] `IO.ANSI.terminal?` is deprecated in favor of `IO.ANSI.enabled?`
   * [IO] `IO.ANSI.escape/2` and `IO.ANSI.escape_fragment/2` is deprecated in favor of `IO.ANSI.format/2` and `IO.ANSI.format_fragment/2`
   * [Kernel] Leading `0` for octals is deprecated in favor of `0o`
   * [Kernel] `0X` for hexadecimals is deprecated in favor of `0x`

lib/elixir/lib/io/ansi.ex

@@ -32,21 +32,27 @@ defmodule IO.ANSI do
   @typep ansilist :: maybe_improper_list(char() | ansicode() | binary() | ansilist(), binary() | ansicode() | [])
   @type  ansidata :: ansilist() | ansicode() | binary()
 
-  @doc """
-  Checks whether the default I/O device is a terminal or a file.
-
-  Used to identify whether printing ANSI escape sequences will likely
-  be displayed as intended. This is checked by sending a message to
-  the group leader. In case the group leader does not support the message,
-  it will likely lead to a timeout (and a slow down on execution time).
-  """
-  @spec terminal? :: boolean
-  @spec terminal?(:io.device) :: boolean
+  @doc false
   def terminal?(device \\ :erlang.group_leader) do
     !match?({:win32, _}, :os.type()) and
       match?({:ok, _}, :io.columns(device))
   end
 
+  @doc """
+  Checks if ANSI coloring is supported and enabled on this machine.
+
+  By default, ANSI is only enabled on UNIX machines. Enabling or
+  disabling ANSI escapes can be done by configuring the
+  `:ansi_enabled` value in the `:elixir` application.
+  """
+  @spec enabled? :: boolean
+  def enabled? do
+    case Application.fetch_env(:elixir, :ansi_enabled) do
+      {:ok, boolean} when is_boolean(boolean) -> boolean
+      :error -> !match?({:win32, _}, :os.type())
+    end
+  end
+
   @doc "Resets all attributes"
   defsequence :reset, 0
 
@@ -157,16 +163,15 @@ defmodule IO.ANSI do
 
   An optional boolean parameter can be passed to enable or disable
   emitting actual ANSI codes. When `false`, no ANSI codes will emitted.
-  By default, standard output will be checked if it is a terminal capable
-  of handling these sequences (using `terminal?/1` function)
+  By default checks if ANSI is enabled using the `enabled?/0` function.
 
   ## Examples
 
       iex> IO.ANSI.format(["Hello, ", :red, :bright, "world!"], true)
       [[[[[[], "Hello, "] | "\e[31m"] | "\e[1m"], "world!"] | "\e[0m"]
 
   """
-  def format(chardata, emit \\ terminal?) when is_boolean(emit) do
+  def format(chardata, emit \\ enabled?) when is_boolean(emit) do
     do_format(chardata, [], [], emit, :maybe)
   end
 
@@ -178,16 +183,15 @@ defmodule IO.ANSI do
 
   An optional boolean parameter can be passed to enable or disable
   emitting actual ANSI codes. When `false`, no ANSI codes will emitted.
-  By default, standard output will be checked if it is a terminal capable
-  of handling these sequences (using `terminal?/1` function)
+  By default checks if ANSI is enabled using the `enabled?/0` function.
 
   ## Examples
 
       iex> IO.ANSI.format_fragment([:bright, 'Word'], true)
       [[[[[[] | "\e[1m"], 87], 111], 114], 100]
 
   """
-  def format_fragment(chardata, emit \\ terminal?) when is_boolean(emit) do
+  def format_fragment(chardata, emit \\ enabled?) when is_boolean(emit) do
     do_format(chardata, [], [], emit, false)
   end
 

lib/elixir/lib/io/ansi/docs.ex

@@ -21,7 +21,8 @@ defmodule IO.ANSI.Docs do
   comma-separated ANSI values.
   """
   def default_options do
-    [doc_code: [:cyan, :bright],
+    [enabled: true,
+     doc_code: [:cyan, :bright],
      doc_inline_code: [:cyan],
      doc_headings: [:yellow, :bright],
      doc_title: [:reverse, :yellow, :bright],
@@ -374,6 +375,6 @@ defmodule IO.ANSI.Docs do
                        "they now must be a list of atoms, got #{inspect color} for #{inspect style}"
       color = String.split(color, ",") |> Enum.map(&String.to_atom/1)
     end
-    IO.ANSI.format_fragment(color, true)
+    IO.ANSI.format_fragment(color, !!colors[:enabled])
   end
 end

lib/elixir/src/elixir_dispatch.erl

@@ -527,5 +527,7 @@ deprecation('Elixir.IO.ANSI', 'escape', _) ->
   "use the new API in IO.ANSI.format/2 instead";
 deprecation('Elixir.IO.ANSI', 'escape_fragment', _) ->
   "use the new API in IO.ANSI.format_fragment/2 instead";
+deprecation('Elixir.IO.ANSI', 'terminal?', _) ->
+  "use IO.ANSI.enabled?/0 instead";
 deprecation(_, _, _) ->
   false.

lib/ex_unit/lib/ex_unit.ex

@@ -158,8 +158,8 @@ defmodule ExUnit do
 
   ExUnit supports the following options:
 
-    * `:color` - when color should be used by specific formatters;
-      defaults to the result of `IO.ANSI.terminal?/1`
+    * `:colors` - a keyword list of colors to be used by some formatters.
+      The only option so far is `[enabled: boolean]` which defaults to `IO.ANSI.enabled?/1`
 
     * `:formatters` - the formatters that will print results;
       defaults to `[ExUnit.CLIFormatter]`

lib/ex_unit/lib/ex_unit/cli_formatter.ex

@@ -13,7 +13,7 @@ defmodule ExUnit.CLIFormatter do
     config = %{
       seed: opts[:seed],
       trace: opts[:trace],
-      color: opts[:color],
+      colors: Keyword.put_new(opts[:colors], :enabled, IO.ANSI.enabled?),
       width: get_terminal_width(),
       tests_counter: 0,
       failures_counter: 0,
@@ -166,10 +166,11 @@ defmodule ExUnit.CLIFormatter do
 
   # Color styles
 
-  defp colorize(escape, string, %{color: color}) do
-    [IO.ANSI.format_fragment(escape, color),
+  defp colorize(escape, string, %{colors: colors}) do
+    enabled = colors[:enabled]
+    [IO.ANSI.format_fragment(escape, enabled),
      string,
-     IO.ANSI.format_fragment(:reset, color)] |> IO.iodata_to_binary
+     IO.ANSI.format_fragment(:reset, enabled)] |> IO.iodata_to_binary
   end
 
   defp success(msg, config) do

lib/ex_unit/lib/ex_unit/runner.ex

@@ -46,7 +46,6 @@ defmodule ExUnit.Runner do
     opts
     |> Keyword.put(:exclude, exclude)
     |> Keyword.put(:include, include)
-    |> Keyword.put_new(:color, IO.ANSI.terminal?)
     |> Keyword.put_new(:max_cases, :erlang.system_info(:schedulers_online))
     |> Keyword.put_new(:seed, :erlang.now |> elem(2))
   end

lib/ex_unit/mix.exs

@@ -13,10 +13,10 @@ defmodule ExUnit.Mixfile do
      env: [
        # Calculated on demand
        # max_cases: :erlang.system_info(:schedulers_online),
-       # color: IO.ANSI.terminal?,
        # seed: rand(),
 
        autorun: true,
+       colors: [],
        trace: false,
        formatters: [ExUnit.CLIFormatter],
        include: [],

lib/ex_unit/test/ex_unit/doc_test_test.exs

@@ -204,7 +204,7 @@ defmodule ExUnit.DocTestTest do
       doctest ExUnit.DocTestTest.Invalid
     end
 
-    ExUnit.configure(seed: 0)
+    ExUnit.configure(seed: 0, colors: [enabled: false])
     output = capture_io(fn -> ExUnit.run end)
 
     assert output =~ """

lib/iex/lib/iex.ex

@@ -473,8 +473,8 @@ defmodule IEx do
       {:ok, _} = Application.ensure_all_started(:iex)
       Application.put_env(:iex, :started, true)
 
-      colors = [enabled: IO.ANSI.terminal?] ++
-               Application.get_env(:iex, :colors)
+      colors = Application.get_env(:iex, :colors)
+               |> Keyword.put_new(:enabled, IO.ANSI.enabled?)
       Application.put_env(:iex, :colors, colors)
     end