Deprecate IO.ANSI.escape/2 and IO.ANSI.escape_fragment/2

Author: José Valim

CHANGELOG.md

@@ -22,6 +22,7 @@
 
 * Deprecations
   * [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.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`
   * [Kernel] `0B` for binaries is deprecated in favor of `0b`

lib/elixir/lib/io/ansi.ex

@@ -152,8 +152,9 @@ defmodule IO.ANSI do
 
       iex> IO.ANSI.format(["Hello, ", :red, :bright, "world!"], true)
       [[[[[[], "Hello, "], "\e[31m"], "\e[1m"], "world!"] | "\e[0m"]
+
   """
-  def format(chardata, emit \\ terminal?) do
+  def format(chardata, emit \\ terminal?) when is_boolean(emit) do
     do_format(chardata, [], [], emit, :maybe)
   end
 
@@ -172,8 +173,9 @@ defmodule IO.ANSI do
 
       iex> IO.ANSI.format_fragment([:bright, 'Word'], true)
       [[[[[[], "\e[1m"], 87], 111], 114], 100]
+
   """
-  def format_fragment(chardata, emit \\ terminal?) do
+  def format_fragment(chardata, emit \\ terminal?) when is_boolean(emit) do
     do_format(chardata, [], [], emit, false)
   end
 
@@ -210,27 +212,7 @@ defmodule IO.ANSI do
     acc
   end
 
-  @doc ~S"""
-  Escapes a string by converting named ANSI sequences into actual ANSI codes.
-
-  The format for referring to sequences is `%{red}` and `%{red,bright}` (for
-  multiple sequences).
-
-  It will also append a `%{reset}` to the string. If you don't want this
-  behaviour, use `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.
-  By default, standard output will be checked if it is a terminal capable
-  of handling these sequences (using `terminal?/1` function)
-
-  ## Examples
-
-      iex> IO.ANSI.escape("Hello %{red,bright,green}yes", true)
-      "Hello \e[31m\e[1m\e[32myes\e[0m"
-
-  """
-  @spec escape(String.t, emit :: boolean) :: String.t
+  @doc false
   def escape(string, emit \\ terminal?) when is_binary(string) and is_boolean(emit) do
     {rendered, emitted} = do_escape(string, emit, false, nil, [])
     if emitted do
@@ -240,27 +222,7 @@ defmodule IO.ANSI do
     end
   end
 
-  @doc ~S"""
-  Escapes a string by converting named ANSI sequences into actual ANSI codes.
-
-  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.
-  By default, standard output will be checked if it is a terminal capable
-  of handling these sequences (using `terminal?/1` function)
-
-  ## Examples
-
-      iex> IO.ANSI.escape_fragment("Hello %{red,bright,green}yes", true)
-      "Hello \e[31m\e[1m\e[32myes"
-
-      iex> IO.ANSI.escape_fragment("%{reset}bye", true)
-      "\e[0mbye"
-
-  """
-  @spec escape_fragment(String.t, emit :: boolean) :: String.t
+  @doc false
   def escape_fragment(string, emit \\ terminal?) when is_binary(string) and is_boolean(emit) do
     {escaped, _emitted} = do_escape(string, emit, false, nil, [])
     escaped

lib/elixir/src/elixir_dispatch.erl

@@ -523,5 +523,9 @@ deprecation('Elixir.System', 'cmd', 1) ->
   "use System.cmd/3 instead";
 deprecation('Elixir.Inspect.Algebra', 'pretty', 2) ->
   "use Inspect.Algebra.format/2 instead";
+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(_, _, _) ->
   false.

lib/elixir/test/elixir/io/ansi_test.exs

@@ -91,53 +91,4 @@ defmodule IO.ANSITest do
       IO.ANSI.format([:brigh, "Hello!"], true)
     end
   end
-
-  test :escape_single do
-    assert IO.ANSI.escape("Hello, %{red}world!", true) ==
-           "Hello, #{IO.ANSI.red}world!#{IO.ANSI.reset}"
-    assert IO.ANSI.escape("Hello, %{red}world!", true) ==
-           "Hello, #{IO.ANSI.red}world!#{IO.ANSI.reset}"
-  end
-
-  test :escape_non_attribute do
-    assert IO.ANSI.escape("Hello %{clear}world!", true) ==
-           "Hello #{IO.ANSI.clear}world!#{IO.ANSI.reset}"
-    assert IO.ANSI.escape("Hello %{home}world!", true) ==
-           "Hello #{IO.ANSI.home}world!#{IO.ANSI.reset}"
-  end
-
-  test :escape_multiple do
-    assert IO.ANSI.escape("Hello, %{red,bright}world!", true) ==
-           "Hello, #{IO.ANSI.red}#{IO.ANSI.bright}world!#{IO.ANSI.reset}"
-    assert IO.ANSI.escape("Hello, %{red, bright}world!", true) ==
-           "Hello, #{IO.ANSI.red}#{IO.ANSI.bright}world!#{IO.ANSI.reset}"
-    assert IO.ANSI.escape("Hello, %{red , bright}world!", true) ==
-           "Hello, #{IO.ANSI.red}#{IO.ANSI.bright}world!#{IO.ANSI.reset}"
-  end
-
-  test :escape_no_emit do
-    assert IO.ANSI.escape("Hello, %{}world!", false) ==
-           "Hello, world!"
-
-    assert IO.ANSI.escape("Hello, %{red,bright}world!", false) ==
-           "Hello, world!"
-  end
-
-  test :escape_fragment do
-    assert IO.ANSI.escape("%{red}", true) == "#{IO.ANSI.red}#{IO.ANSI.reset}"
-    assert IO.ANSI.escape_fragment("", true) == ""
-  end
-
-  test :escape_noop do
-    assert IO.ANSI.escape("") == ""
-  end
-
-  test :escape_invalid do
-    assert_raise ArgumentError, "invalid ANSI sequence specification: brigh", fn ->
-      IO.ANSI.escape("%{brigh}, yes")
-    end
-    assert_raise ArgumentError, "invalid ANSI sequence specification: brigh", fn ->
-      IO.ANSI.escape("%{brigh,red}, yes")
-    end
-  end
 end

lib/iex/test/iex/interaction_test.exs

@@ -104,17 +104,6 @@ defmodule IEx.InteractionTest do
              == "\e[34mhello\e[0m\n\e[31m:ok\e[0m"
       assert capture_iex("IO.puts IO.ANSI.escape(\"%{blue}hello\", true)", [colors: [enabled: false]])
              == "\e[34mhello\e[0m\n:ok"
-
-      # Test that ANSI escapes in the docs are left alone
-      opts = [colors: [enabled: true]]
-      assert capture_iex("h IO.ANSI.escape_fragment", opts)
-             =~ ~r"%\{red\}"
-
-      # Test that ANSI escapes in iex output are left alone
-      opts = [colors: [enabled: true, eval_result: "red", eval_info: "red"]]
-      assert capture_iex("\"%{red} %{blue}\"", opts) == "\e[31m\"%{red} %{blue}\"\e[0m"
-      assert capture_iex("IO.puts IEx.color(:eval_info, \"%{red} %{blue}\")", opts)
-             == "\e[31m%{red} %{blue}\e[0m\n\e[31m:ok\e[0m"
     end
   end