cmd/options: add flag to list a command's options

Library/Homebrew/cmd/options.rb

@@ -3,6 +3,7 @@
 require "formula"
 require "options"
 require "cli/parser"
+require "commands"
 
 module Homebrew
   module_function
@@ -20,8 +21,10 @@ def options_args
              description: "Show options for formulae that are currently installed."
       switch "--all",
              description: "Show options for all available formulae."
+      flag   "--command=",
+             description: "Show options for the specified <command>."
       switch :debug
-      conflicts "--installed", "--all"
+      conflicts "--installed", "--all", "--command"
     end
   end
 
@@ -32,13 +35,43 @@ def options
       puts_options Formula.to_a.sort
     elsif args.installed?
       puts_options Formula.installed.sort
+    elsif !args.command.nil?
+      path = Commands.path(args.command)
+      odie "Unknown command: #{args.command}" unless path
+      cmd_options = if cmd_parser = CLI::Parser.from_cmd_path(path)
+        cmd_parser.processed_options.map do |short, long, _, desc|
+          [long || short, desc]
+        end
+      else
+        cmd_comment_options(path)
+      end
+      if args.compact?
+        puts cmd_options.sort.map(&:first) * " "
+      else
+        cmd_options.sort.each { |option, desc| puts "#{option}\n\t#{desc}" }
+        puts
+      end
     elsif args.no_named?
       raise FormulaUnspecifiedError
     else
       puts_options args.formulae
     end
   end
 
+  def cmd_comment_options(cmd_path)
+    options = []
+    comment_lines = cmd_path.read.lines.grep(/^#:/)
+    return options if comment_lines.empty?
+
+    # skip the comment's initial usage summary lines
+    comment_lines.slice(2..-1).each do |line|
+      if / (?<option>-[-\w]+) +(?<desc>.*)$/ =~ line
+        options << [option, desc]
+      end
+    end
+    options
+  end
+
   def puts_options(formulae)
     formulae.each do |f|
       next if f.options.empty?

docs/Manpage.md

@@ -340,6 +340,8 @@ Show install options specific to *`formula`*.
   Show options for formulae that are currently installed.
 * `--all`:
   Show options for all available formulae.
+* `--command`:
+  Show options for the specified *`command`*.
 
 ### `outdated` [*`options`*] [*`formula`*]
 

manpages/brew.1

@@ -456,6 +456,10 @@ Show options for formulae that are currently installed\.
 \fB\-\-all\fR
 Show options for all available formulae\.
 .
+.TP
+\fB\-\-command\fR
+Show options for the specified \fIcommand\fR\.
+.
 .SS "\fBoutdated\fR [\fIoptions\fR] [\fIformula\fR]"
 List installed formulae that have an updated version available\. By default, version information is displayed in interactive shells, and suppressed otherwise\.
 .