Merge pull request #2562 from thmzlt/ansi

Implement IO.ANSI format/2 and format_fragment/2

Author: José Valim

lib/elixir/lib/io/ansi.ex

@@ -134,6 +134,82 @@ defmodule IO.ANSI do
     raise ArgumentError, "invalid ANSI sequence specification: #{other}"
   end
 
+  @doc ~S"""
+  Formats a chardata-like argument by converting named ANSI sequences into actual
+  ANSI codes.
+
+  The named sequences are represented by atoms.
+
+  It will also append an `IO.ANSI.reset` to the chardata when a conversion is
+  performed. If you don't want this behaviour, use `format_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.format(["Hello, ", :red, :bright, "world!"], true)
+      [[[[[[], "Hello, "], "\e[31m"], "\e[1m"], "world!"] | "\e[0m"]
+  """
+  def format(chardata, emit \\ terminal?) do
+    do_format(chardata, [], [], emit, :maybe)
+  end
+
+  @doc ~S"""
+  Formats a chardata-like argument by converting named ANSI sequences into actual
+  ANSI codes.
+
+  The named sequences are represented by atoms.
+
+  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.format_fragment([:bright, 'Word'], true)
+      [[[[[[], "\e[1m"], 87], 111], 114], 100]
+  """
+  def format_fragment(chardata, emit \\ terminal?) do
+    do_format(chardata, [], [], emit, false)
+  end
+
+  defp do_format([term | rest], rem, acc, emit, append_reset) do
+    do_format(term, [rest | rem], acc, emit, append_reset)
+  end
+
+  defp do_format(term, rem, acc, true, append_reset) when is_atom(term) do
+    try do
+      do_format([], rem, [acc | [apply(IO.ANSI, term, [])]], true, !!append_reset)
+    rescue
+      _ in UndefinedFunctionError ->
+        raise ArgumentError, message: "invalid ANSI sequence specification: #{term}"
+    end
+  end
+
+  defp do_format(term, rem, acc, false, append_reset) when is_atom(term) do
+    do_format([], rem, acc, false, append_reset)
+  end
+
+  defp do_format(term, rem, acc, emit, append_reset) when not is_list(term) do
+    do_format([], rem, [acc | [term]], emit, append_reset)
+  end
+
+  defp do_format([], [next | rest], acc, emit, append_reset) do
+    do_format(next, rest, acc, emit, append_reset)
+  end
+
+  defp do_format([], [], acc, true, true) do
+    [acc | IO.ANSI.reset]
+  end
+
+  defp do_format([], [], acc, _emit, _append_reset) do
+    acc
+  end
+
   @doc ~S"""
   Escapes a string by converting named ANSI sequences into actual ANSI codes.
 

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

@@ -3,6 +3,95 @@ Code.require_file "../test_helper.exs", __DIR__
 defmodule IO.ANSITest do
   use ExUnit.Case, async: true
 
+  test :format_ansicode do
+    assert IO.chardata_to_string(IO.ANSI.format(:green, true)) ==
+           "#{IO.ANSI.green}#{IO.ANSI.reset}"
+    assert IO.chardata_to_string(IO.ANSI.format(:green, false)) ==
+           ""
+  end
+
+  test :format_binary do
+    assert IO.chardata_to_string(IO.ANSI.format("Hello, world!", true)) ==
+           "Hello, world!"
+    assert IO.chardata_to_string(IO.ANSI.format("A map: %{foo: :bar}", false)) ==
+           "A map: %{foo: :bar}"
+  end
+
+  test :format_empty_list do
+    assert IO.chardata_to_string(IO.ANSI.format([], true)) ==
+           ""
+    assert IO.chardata_to_string(IO.ANSI.format([], false)) ==
+           ""
+  end
+
+  test :format_ansicode_list do
+    assert IO.chardata_to_string(IO.ANSI.format([:red, :bright], true)) ==
+           "#{IO.ANSI.red}#{IO.ANSI.bright}#{IO.ANSI.reset}"
+    assert IO.chardata_to_string(IO.ANSI.format([:red, :bright], false)) ==
+           ""
+  end
+
+  test :format_binary_list do
+    assert IO.chardata_to_string(IO.ANSI.format(["Hello, ", "world!"], true)) ==
+           "Hello, world!"
+    assert IO.chardata_to_string(IO.ANSI.format(["Hello, ", "world!"], false)) ==
+           "Hello, world!"
+  end
+
+  test :format_char_list do
+    assert IO.chardata_to_string(IO.ANSI.format('Hello, world!', true)) ==
+           "Hello, world!"
+    assert IO.chardata_to_string(IO.ANSI.format('Hello, world!', false)) ==
+           "Hello, world!"
+  end
+
+  test :format_mixed_list do
+    data = ["Hello", ?,, 32, :red, "world!"]
+
+    assert IO.chardata_to_string(IO.ANSI.format(data, true)) ==
+           "Hello, #{IO.ANSI.red}world!#{IO.ANSI.reset}"
+    assert IO.chardata_to_string(IO.ANSI.format(data, false)) ==
+           "Hello, world!"
+  end
+
+  test :format_nested_list do
+    data = ["Hello, ", ["nested", 32, :red, "world!"]]
+
+    assert IO.chardata_to_string(IO.ANSI.format(data, true)) ==
+           "Hello, nested #{IO.ANSI.red}world!#{IO.ANSI.reset}"
+    assert IO.chardata_to_string(IO.ANSI.format(data, false)) ==
+           "Hello, nested world!"
+  end
+
+  test :format_improper_list do
+    data = ["Hello, ", :red, "world" | "!"]
+
+    assert IO.chardata_to_string(IO.ANSI.format(data, true)) ==
+           "Hello, #{IO.ANSI.red}world!#{IO.ANSI.reset}"
+    assert IO.chardata_to_string(IO.ANSI.format(data, false)) ==
+           "Hello, world!"
+  end
+
+  test :format_nested_improper_list do
+    data = [["Hello, " | :red], "world!" | :green]
+
+    assert IO.chardata_to_string(IO.ANSI.format(data, true)) ==
+           "Hello, #{IO.ANSI.red}world!#{IO.ANSI.green}#{IO.ANSI.reset}"
+    assert IO.chardata_to_string(IO.ANSI.format(data, false)) ==
+           "Hello, world!"
+  end
+
+  test :format_fragment do
+    assert IO.chardata_to_string(IO.ANSI.format_fragment([:red, "Hello!"], true)) ==
+           "#{IO.ANSI.red}Hello!"
+  end
+
+  test :format_invalid_sequence do
+    assert_raise ArgumentError, "invalid ANSI sequence specification: brigh", fn ->
+      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}"
@@ -26,24 +115,24 @@ defmodule IO.ANSITest do
            "Hello, #{IO.ANSI.red}#{IO.ANSI.bright}world!#{IO.ANSI.reset}"
   end
 
-  test :no_emit do
+  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 :fragment do
+  test :escape_fragment do
     assert IO.ANSI.escape("%{red}", true) == "#{IO.ANSI.red}#{IO.ANSI.reset}"
     assert IO.ANSI.escape_fragment("", true) == ""
   end
 
-  test :noop do
+  test :escape_noop do
     assert IO.ANSI.escape("") == ""
   end
 
-  test :invalid do
+  test :escape_invalid do
     assert_raise ArgumentError, "invalid ANSI sequence specification: brigh", fn ->
       IO.ANSI.escape("%{brigh}, yes")
     end