Merge pull request #1975 from thmzlt/ansi_docs

Move IEx.ANSIDocs to IO.ANSI.Docs and decouple it from IEx

Author: José Valim

lib/iex/lib/iex/ansi_docs.ex lib/elixir/lib/io/ansi/docs.exlib/iex/lib/iex/ansi_docs.ex renamed to lib/elixir/lib/io/ansi/docs.ex

@@ -1,75 +1,110 @@
-defmodule IEx.ANSIDocs do
+defmodule IO.ANSI.Docs do
   @moduledoc false
 
   @bullets [?*, ?-, ?+]
 
+  @default_colors [ enabled: true,
+                    doc_code: "cyan,bright",
+                    doc_inline_code: "cyan",
+                    doc_headings: "yellow,bright",
+                    doc_title: "reverse,yellow,bright",
+                    doc_bold: "bright",
+                    doc_underline: "underline" ]
+
+  @shared_print_doc """
+  In addition to the priting string, takes a truth value for whether to use ANSI
+  escape codes, and a keyword list for the printing color settings. Supported
+  keys for the color settings are:
+
+    * `:enabled`         - toggles coloring on and off (true)
+    * `:doc_code`        - code blocks (cyan, bright)
+    * `:doc_inline_code` - inline code (cyan)
+    * `:doc_headings`    - h1 and h2 headings (yellow, bright)
+    * `:doc_title`       - top level heading (reverse, yellow, bright)
+    * `:doc_bold`        - bold text (bright)
+    * `:doc_underline`   - underlined text (underline)
+
+  Values for the color settings are strings with comma-separated attributes.
+  Supported attributes are:
+
+    * Colors:     `black  red  green  yellow  blue  magenta  cyan  white`
+    * Intensity:  `normal  bright`
+    * Decoration: `underline  reverse`
+  """
+
   @doc """
-  Prints the head of the documentation (i.e. the function signature)
+  Prints the head of the documentation (i.e. the function signature).
+
+  #{@shared_print_doc}
   """
-  def print_heading(string, use_ansi // IO.ANSI.terminal?) do
+  def print_heading(string, use_ansi // IO.ANSI.terminal?, colors // @default_colors) do
     if use_ansi do
-      write_doc_heading(string)
+      write_doc_heading(string, colors)
     else
       IO.puts "* #{string}\n"
     end
-    IEx.dont_display_result
+    dont_display_result
   end
 
-  defp write_doc_heading(heading) do
+  defp write_doc_heading(heading, colors) do
     IO.puts IO.ANSI.reset
     width   = column_width()
     padding = div(width + String.length(heading), 2)
     heading = heading |> String.rjust(padding) |> String.ljust(width)
-    write(:doc_title, heading)
+    write(:doc_title, heading, colors)
   end
 
   @doc """
   Prints the documentation body.
+
+  #{@shared_print_doc}
   """
-  def print(doc, use_ansi // IO.ANSI.terminal?) do
+  def print(doc, use_ansi // IO.ANSI.terminal?, colors // @default_colors) do
     if use_ansi do
       doc
       |> String.split(["\r\n","\n"], trim: false)
       |> Enum.map(&String.rstrip/1)
-      |> process("")
+      |> process("", colors)
     else
       IO.puts doc
     end
-    IEx.dont_display_result
+    dont_display_result
   end
 
-  defp process([], _indent), do: nil
+  defp dont_display_result, do: :"do not show this result in output"
 
-  defp process(["# " <> heading | rest], _indent) do
-    write_h1(String.strip(heading))
-    process(rest, "")
+  defp process([], _indent, _colors), do: nil
+
+  defp process(["# " <> heading | rest], _indent, colors) do
+    write_h1(String.strip(heading), colors)
+    process(rest, "", colors)
   end
 
-  defp process(["## " <> heading | rest], _indent) do
-    write_h2(String.strip(heading))
-    process(rest, "")
+  defp process(["## " <> heading | rest], _indent, colors) do
+    write_h2(String.strip(heading), colors)
+    process(rest, "", colors)
   end
 
-  defp process(["### " <> heading | rest], indent) do
-    write_h3(String.strip(heading), indent)
-    process(rest, indent)
+  defp process(["### " <> heading | rest], indent, colors) do
+    write_h3(String.strip(heading), indent, colors)
+    process(rest, indent, colors)
   end
 
-  defp process(["" | rest], indent) do
-    process(rest, indent)
+  defp process(["" | rest], indent, colors) do
+    process(rest, indent, colors)
   end
 
-  defp process(["    " <> line | rest], indent) do
-    process_code(rest, [line], indent)
+  defp process(["    " <> line | rest], indent, colors) do
+    process_code(rest, [line], indent, colors)
   end
 
-  defp process([line | rest], indent) do
+  defp process([line | rest], indent, colors) do
     { stripped, count } = strip_spaces(line, 0)
     case stripped do
       <<bullet, ?\s, item :: binary >> when bullet in @bullets ->
-        process_list(item, rest, count, indent)
+        process_list(item, rest, count, indent, colors)
       _ ->
-        process_text(rest, [line], indent, false)
+        process_text(rest, [line], indent, false, colors)
     end
   end
 
@@ -83,27 +118,27 @@ defmodule IEx.ANSIDocs do
 
   ## Headings
 
-  defp write_h1(heading) do
-    write_h2(String.upcase(heading))
+  defp write_h1(heading, colors) do
+    write_h2(String.upcase(heading), colors)
   end
 
-  defp write_h2(heading) do
-    write(:doc_headings, heading)
+  defp write_h2(heading, colors) do
+    write(:doc_headings, heading, colors)
   end
 
-  defp write_h3(heading, indent) do
+  defp write_h3(heading, indent, colors) do
     IO.write(indent)
-    write(:doc_headings, heading)
+    write(:doc_headings, heading, colors)
   end
 
   ## Lists
 
-  defp process_list(line, rest, count, indent) do
+  defp process_list(line, rest, count, indent, colors) do
     IO.write indent <> "• "
     { contents, rest, done } = process_list_next(rest, count, false, [])
-    process_text(contents, [line], indent <> "  ", true)
+    process_text(contents, [line], indent <> "  ", true, colors)
     if done, do: IO.puts(IO.ANSI.reset)
-    process(rest, indent)
+    process(rest, indent, colors)
   end
 
   # Process the thing after a list item entry. It can be either:
@@ -141,35 +176,35 @@ defmodule IEx.ANSIDocs do
 
   ## Text (paragraphs / lists)
 
-  defp process_text(doc=["" | _], para, indent, from_list) do
-    write_text(Enum.reverse(para), indent, from_list)
-    process(doc, indent)
+  defp process_text(doc=["" | _], para, indent, from_list, colors) do
+    write_text(Enum.reverse(para), indent, from_list, colors)
+    process(doc, indent, colors)
   end
 
-  defp process_text([], para, indent, from_list) do
-    write_text(Enum.reverse(para), indent, from_list)
+  defp process_text([], para, indent, from_list, colors) do
+    write_text(Enum.reverse(para), indent, from_list, colors)
   end
 
-  defp process_text([line | rest], para, indent, true) do
+  defp process_text([line | rest], para, indent, true, colors) do
     { stripped, count } = strip_spaces(line, 0)
     case stripped do
       <<bullet, ?\s, item :: binary>> when bullet in @bullets ->
-        write_text(Enum.reverse(para), indent, true)
-        process_list(item, rest, count, indent)
+        write_text(Enum.reverse(para), indent, true, colors)
+        process_list(item, rest, count, indent, colors)
       _ ->
-        process_text(rest, [line | para], indent, true)
+        process_text(rest, [line | para], indent, true, colors)
     end
   end
 
-  defp process_text([line | rest], para, indent, from_list) do
-    process_text(rest, [line | para], indent, from_list)
+  defp process_text([line | rest], para, indent, from_list, colors) do
+    process_text(rest, [line | para], indent, from_list, colors)
   end
 
-  defp write_text(lines, indent, from_list) do
+  defp write_text(lines, indent, from_list, colors) do
     lines
     |> Enum.join(" ")
     |> handle_links
-    |> handle_inline(nil, [], [])
+    |> handle_inline(nil, [], [], colors)
     |> String.split(%r{\s})
     |> write_with_wrap(column_width() - size(indent), indent, from_list)
 
@@ -178,32 +213,32 @@ defmodule IEx.ANSIDocs do
 
   ## Code blocks
 
-  defp process_code([], code, indent) do
-    write_code(code, indent)
+  defp process_code([], code, indent, colors) do
+    write_code(code, indent, colors)
   end
 
   # Blank line between code blocks
-  defp process_code([ "", "    " <> line | rest ], code, indent) do
-    process_code(rest, [line, "" | code], indent)
+  defp process_code([ "", "    " <> line | rest ], code, indent, colors) do
+    process_code(rest, [line, "" | code], indent, colors)
   end
 
-  defp process_code([ "    " <> line | rest ], code, indent) do
-    process_code(rest, [line|code], indent)
+  defp process_code([ "    " <> line | rest ], code, indent, colors) do
+    process_code(rest, [line|code], indent, colors)
   end
 
-  defp process_code(rest, code, indent) do
-    write_code(code, indent)
-    process(rest, indent)
+  defp process_code(rest, code, indent, colors) do
+    write_code(code, indent, colors)
+    process(rest, indent, colors)
   end
 
-  defp write_code(code, indent) do
-    write(:doc_code, "#{indent}┃ #{Enum.join(Enum.reverse(code), "\n#{indent}┃ ")}")
+  defp write_code(code, indent, colors) do
+    write(:doc_code, "#{indent}┃ #{Enum.join(Enum.reverse(code), "\n#{indent}┃ ")}", colors)
   end
 
   ## Helpers
 
-  defp write(style, string) do
-    IO.puts IEx.color(style, string)
+  defp write(style, string, colors) do
+    IO.puts color(style, colors) <> string <> IO.ANSI.reset
     IO.puts IO.ANSI.reset
   end
 
@@ -280,81 +315,77 @@ defmodule IEx.ANSIDocs do
   @spaced [?_, ?*]
 
   # Clauses for handling spaces
-  defp handle_inline(<<?*, ?*, ?\s, rest :: binary>>, nil, buffer, acc) do
-    handle_inline(rest, nil, [?\s, ?*, ?*|buffer], acc)
+  defp handle_inline(<<?*, ?*, ?\s, rest :: binary>>, nil, buffer, acc, colors) do
+    handle_inline(rest, nil, [?\s, ?*, ?*|buffer], acc, colors)
   end
 
-  defp handle_inline(<<mark, ?\s, rest :: binary>>, nil, buffer, acc) when mark in @spaced do
-    handle_inline(rest, nil, [?\s, mark|buffer], acc)
+  defp handle_inline(<<mark, ?\s, rest :: binary>>, nil, buffer, acc, colors) when mark in @spaced do
+    handle_inline(rest, nil, [?\s, mark|buffer], acc, colors)
   end
 
-  defp handle_inline(<<?\s, ?*, ?*, rest :: binary>>, limit, buffer, acc) do
-    handle_inline(rest, limit, [?*, ?*, ?\s|buffer], acc)
+  defp handle_inline(<<?\s, ?*, ?*, rest :: binary>>, limit, buffer, acc, colors) do
+    handle_inline(rest, limit, [?*, ?*, ?\s|buffer], acc, colors)
   end
 
-  defp handle_inline(<<?\s, mark, rest :: binary>>, limit, buffer, acc) when mark in @spaced do
-    handle_inline(rest, limit, [mark, ?\s|buffer], acc)
+  defp handle_inline(<<?\s, mark, rest :: binary>>, limit, buffer, acc, colors) when mark in @spaced do
+    handle_inline(rest, limit, [mark, ?\s|buffer], acc, colors)
   end
 
   # Clauses for handling escape
-  defp handle_inline(<<?\\, ?\\, rest :: binary>>, limit, buffer, acc) do
-    handle_inline(rest, limit, [?\\|buffer], acc)
+  defp handle_inline(<<?\\, ?\\, rest :: binary>>, limit, buffer, acc, colors) do
+    handle_inline(rest, limit, [?\\|buffer], acc, colors)
   end
 
-  defp handle_inline(<<?\\, ?*, ?*, rest :: binary>>, limit, buffer, acc) do
-    handle_inline(rest, limit, [?*, ?*|buffer], acc)
+  defp handle_inline(<<?\\, ?*, ?*, rest :: binary>>, limit, buffer, acc, colors) do
+    handle_inline(rest, limit, [?*, ?*|buffer], acc, colors)
   end
 
   # A escape is not valid inside `
-  defp handle_inline(<<?\\, mark, rest :: binary>>, limit, buffer, acc)
+  defp handle_inline(<<?\\, mark, rest :: binary>>, limit, buffer, acc, colors)
       when mark in [?_, ?*, ?`] and not(mark == limit and mark == ?`) do
-    handle_inline(rest, limit, [mark|buffer], acc)
+    handle_inline(rest, limit, [mark|buffer], acc, colors)
   end
 
   # Inline start
-  defp handle_inline(<<?*, ?*, rest :: binary>>, nil, buffer, acc) when rest != "" do
-    handle_inline(rest, ?d, ["**"], [Enum.reverse(buffer)|acc])
+  defp handle_inline(<<?*, ?*, rest :: binary>>, nil, buffer, acc, colors) when rest != "" do
+    handle_inline(rest, ?d, ["**"], [Enum.reverse(buffer)|acc], colors)
   end
 
-  defp handle_inline(<<mark, rest :: binary>>, nil, buffer, acc) when rest != "" and mark in @single do
-    handle_inline(rest, mark, [<<mark>>], [Enum.reverse(buffer)|acc])
+  defp handle_inline(<<mark, rest :: binary>>, nil, buffer, acc, colors) when rest != "" and mark in @single do
+    handle_inline(rest, mark, [<<mark>>], [Enum.reverse(buffer)|acc], colors)
   end
 
   # Inline end
-  defp handle_inline(<<?*, ?*, rest :: binary>>, ?d, buffer, acc) do
-    handle_inline(rest, nil, [], [inline_buffer(buffer)|acc])
+  defp handle_inline(<<?*, ?*, rest :: binary>>, ?d, buffer, acc, colors) do
+    handle_inline(rest, nil, [], [inline_buffer(buffer, colors)|acc], colors)
   end
 
-  defp handle_inline(<<mark, rest :: binary>>, mark, buffer, acc) when mark in @single do
-    handle_inline(rest, nil, [], [inline_buffer(buffer)|acc])
+  defp handle_inline(<<mark, rest :: binary>>, mark, buffer, acc, colors) when mark in @single do
+    handle_inline(rest, nil, [], [inline_buffer(buffer, colors)|acc], colors)
   end
 
-  defp handle_inline(<<char, rest :: binary>>, mark, buffer, acc) do
-    handle_inline(rest, mark, [char|buffer], acc)
+  defp handle_inline(<<char, rest :: binary>>, mark, buffer, acc, colors) do
+    handle_inline(rest, mark, [char|buffer], acc, colors)
   end
 
-  defp handle_inline(<<>>, _mark, buffer, acc) do
+  defp handle_inline(<<>>, _mark, buffer, acc, _colors) do
     iolist_to_binary Enum.reverse([Enum.reverse(buffer)|acc])
   end
 
-  defp inline_buffer(buffer) do
+  defp inline_buffer(buffer, colors) do
     [h|t] = Enum.reverse([IO.ANSI.reset|buffer])
-    [color_for(h)|t]
+    [color_for(h, colors)|t]
   end
 
-  defp color_for("`"),  do: color(:doc_inline_code)
-  defp color_for("_"),  do: color(:doc_underline)
-  defp color_for("*"),  do: color(:doc_bold)
-  defp color_for("**"), do: color(:doc_bold)
-
-  defp color(color_name) do
-    colors = IEx.Options.get(:colors)
+  defp color_for("`", colors),  do: color(:doc_inline_code, colors)
+  defp color_for("_", colors),  do: color(:doc_underline, colors)
+  defp color_for("*", colors),  do: color(:doc_bold, colors)
+  defp color_for("**", colors), do: color(:doc_bold, colors)
 
-    if colors[:enabled] do
-      IO.ANSI.escape_fragment("%{#{colors[color_name]}}", true)
-    else
-      ""
-    end
+  defp color(style, colors) do
+    color = colors[style]
+    enabled = colors[:enabled]
+    IO.ANSI.escape_fragment("%{#{color}}", enabled)
   end
 
   defp column_width() do