Use IO.ANSI.Docs to format mix help

Author: José Valim

lib/eex/mix.exs

@@ -2,6 +2,8 @@ defmodule EEx.Mixfile do
   use Mix.Project
 
   def project do
-    [app: :eex, version: System.version, build_per_environment: false]
+    [app: :eex,
+     version: System.version,
+     build_per_environment: false]
   end
 end

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

@@ -3,23 +3,42 @@ defmodule IO.ANSI.Docs do
 
   @bullets [?*, ?-, ?+]
 
-  @default_options [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",
-                    width: 80]
+  @doc """
+  The default options used by this module.
+
+  The supported values 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)
+  * `:width`           - the width to format the text (80)
+
+  Values for the color settings are strings with
+  comma-separated ANSI values.
+  """
+  def default_options do
+    [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",
+     width: 80]
+  end
 
   @doc """
   Prints the head of the documentation (i.e. the function signature).
 
-  See `print/3` for docs on the supported options.
+  See `default_options/0` for docs on the supported options.
   """
   def print_heading(heading, options \\ []) do
     IO.puts IO.ANSI.reset
-    options = Keyword.merge(@default_options, options)
+    options = Keyword.merge(default_options, options)
     width   = options[:width]
     padding = div(width + String.length(heading), 2)
     heading = heading |> String.rjust(padding) |> String.ljust(width)
@@ -29,25 +48,11 @@ defmodule IO.ANSI.Docs do
   @doc """
   Prints the documentation body.
 
-  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
-  options 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)
-  * `:width`           - the width to format the text
-
-  Values for the color settings are strings with comma-separated
-  ansi values.
-
+  In addition to the priting string, takes a set of options
+  defined in `default_options/1`.
   """
   def print(doc, options \\ []) do
-    options = Keyword.merge(@default_options, options)
+    options = Keyword.merge(default_options, options)
     doc
     |> String.split(["\r\n","\n"], trim: false)
     |> Enum.map(&String.rstrip/1)

lib/elixir/mix.exs

@@ -2,11 +2,11 @@ defmodule Elixir.Mixfile do
   use Mix.Project
 
   def project do
-    [ app: :elixir,
-      version: System.version,
-      build_per_environment: false,
-      escript_embed_elixir: false,
-      escript_main_module: :elixir,
-      escript_emu_args: "%%! -noshell\n" ]
+    [app: :elixir,
+     version: System.version,
+     build_per_environment: false,
+     escript_embed_elixir: false,
+     escript_main_module: :elixir,
+     escript_emu_args: "%%! -noshell\n"]
   end
 end

lib/elixir/test/elixir/io/ansi/docs_test.exs

@@ -4,20 +4,12 @@ defmodule IO.ANSI.DocsTest do
   use ExUnit.Case, async: true
   import ExUnit.CaptureIO
 
-  @colors [ enabled: true,
-            doc_code: "cyan,bright",
-            doc_inline_code: "cyan",
-            doc_bold: "bright",
-            doc_underline: "underline",
-            doc_headings: "yellow,bright",
-            doc_title: "reverse,yellow,bright" ]
-
   def format_heading(str) do
-    capture_io(fn -> IO.ANSI.Docs.print_heading(str, @colors) end) |> String.strip
+    capture_io(fn -> IO.ANSI.Docs.print_heading(str, []) end) |> String.strip
   end
 
   def format(str) do
-    capture_io(fn -> IO.ANSI.Docs.print(str, @colors) end) |> String.strip
+    capture_io(fn -> IO.ANSI.Docs.print(str, []) end) |> String.strip
   end
 
   test "heading is formatted" do

lib/ex_unit/mix.exs

@@ -2,17 +2,19 @@ defmodule ExUnit.Mixfile do
   use Mix.Project
 
   def project do
-    [app: :ex_unit, version: System.version, build_per_environment: false]
+    [app: :ex_unit,
+     version: System.version,
+     build_per_environment: false]
   end
 
   def application do
-    [ registered: [ExUnit.Server],
-      mod: {ExUnit, []},
-      env: [
-        autorun: true,
-        trace: false,
-        formatters: [ExUnit.CLIFormatter],
-        include: [],
-        exclude: [] ] ]
+    [registered: [ExUnit.Server],
+     mod: {ExUnit, []},
+     env: [
+       autorun: true,
+       trace: false,
+       formatters: [ExUnit.CLIFormatter],
+       include: [],
+       exclude: []]]
   end
 end

lib/iex/mix.exs

@@ -2,7 +2,9 @@ defmodule IEx.Mixfile do
   use Mix.Project
 
   def project do
-    [app: :iex, version: System.version, build_per_environment: false]
+    [app: :iex,
+     version: System.version,
+     build_per_environment: false]
   end
 
   def application do

lib/mix/lib/mix/project.ex

@@ -138,7 +138,7 @@ defmodule Mix.Project do
   def config_files do
     [Mix.Dep.Lock.manifest] ++
       case Mix.ProjectStack.peek do
-        {name, config, file} ->
+        {_name, config, file} ->
           configs = config[:config_path] || "config/config.exs"
                     |> Path.dirname
                     |> Path.join("*.exs")

lib/mix/lib/mix/tasks/help.ex

@@ -41,30 +41,44 @@ defmodule Mix.Tasks.Help do
 
   def run([task]) do
     module = Mix.Task.get!(task)
-    shell  = Mix.shell
-    shell.info "%{bright}# mix help #{task}\n"
+    doc    = Mix.Task.moduledoc(module) || "There is no documentation for this task"
 
-    if doc = Mix.Task.moduledoc(module) do
-      shell.info doc
+    if IO.ANSI.terminal? do
+      options = [width: width] ++ Application.get_env(:mix, :colors)
+      IO.ANSI.Docs.print_heading("mix help #{task}", options)
+      IO.ANSI.Docs.print(doc, options)
     else
-      shell.info "There is no documentation for this task"
+      IO.puts "# mix help #{task}\n"
+      IO.puts doc
     end
 
-    shell.info "Location: #{where_is_file(module)}"
+    IO.puts "Location: #{where_is_file(module)}"
   end
 
   def run(_) do
     raise Mix.Error, message: "Unexpected arguments, expected `mix help` or `mix help TASK`"
   end
 
+  defp width() do
+    case :io.columns(:standard_input) do
+      {:ok, width} -> min(width, 80)
+      {:error, _}  -> 80
+    end
+  end
+
   defp format_task(task, max, doc) do
     String.ljust(task, max) <> " # " <> doc
   end
 
   defp where_is_file(module) do
     case :code.where_is_file(atom_to_list(module) ++ '.beam') do
-      :non_existing -> "not available"
-      location -> Path.expand(Path.dirname(location))
+      :non_existing ->
+        "not available"
+      location ->
+        location
+        |> Path.dirname
+        |> Path.expand
+        |> Path.relative_to_cwd
     end
   end
 

lib/mix/mix.exs

@@ -2,17 +2,18 @@ defmodule Mix.Mixfile do
   use Mix.Project
 
   def project do
-    [ app: :mix,
-      build_per_environment: false,
-      version: System.version,
-      escript_main_module: Mix.CLI ]
+    [app: :mix,
+     build_per_environment: false,
+     version: System.version,
+     escript_main_module: Mix.CLI]
   end
 
   def application do
-    [ registered: [Mix.TasksServer, Mix.ProjectStack],
-      mod: {Mix, []},
-      env: [shell: Mix.Shell.IO,
-            env: :dev,
-            scm: [Mix.SCM.Git, Mix.SCM.Path]] ]
+    [registered: [Mix.TasksServer, Mix.ProjectStack],
+     mod: {Mix, []},
+     env: [shell: Mix.Shell.IO,
+           env: :dev,
+           scm: [Mix.SCM.Git, Mix.SCM.Path],
+           colors: []]]
   end
 end

lib/mix/test/mix/tasks/help_test.exs

@@ -3,6 +3,8 @@ Code.require_file "../../test_helper.exs", __DIR__
 defmodule Mix.Tasks.HelpTest do
   use MixTest.Case
 
+  import ExUnit.CaptureIO
+
   test "help lists all tasks" do
     in_fixture "no_mixfile", fn ->
       Mix.Tasks.Help.run []
@@ -24,18 +26,13 @@ defmodule Mix.Tasks.HelpTest do
 
   test "help TASK" do
     in_fixture "no_mixfile", fn ->
-      Mix.Tasks.Help.run ["compile"]
+      output =
+        capture_io fn ->
+          Mix.Tasks.Help.run ["compile"]
+        end
 
-      {_, _, [output]} =
-        assert_received {:mix_shell, :info, [_]}
       assert output =~ "# mix help compile"
-
-      {_, _, [output]} =
-        assert_received {:mix_shell, :info, [_]}
       assert output =~ "## Command line options"
-
-      {_, _, [output]} =
-        assert_received {:mix_shell, :info, [_]}
       assert output =~ ~r/^Location:/m
     end
   end