Finish option handling

Library/Homebrew/cli_parser.rb

@@ -5,7 +5,7 @@
 module Homebrew
   module CLI
     class Parser
-      attr_reader :processed_options
+      attr_reader :processed_options, :hide_from_man_page
 
       def self.parse(args = ARGV, &block)
         new(&block).parse(args)
@@ -29,6 +29,7 @@ def initialize(&block)
         @conflicts = []
         @processed_options = []
         @desc_line_length = 43
+        @hide_from_man_page = false
         instance_eval(&block)
         post_initialize
       end
@@ -163,6 +164,10 @@ def formula_options
         end
       end
 
+      def hide_from_man_page!
+        @hide_from_man_page = true
+      end
+
       private
 
       def enable_switch(*names)

Library/Homebrew/cmd/--cache.rb

@@ -1,15 +1,29 @@
-#:  * `--cache`:
-#:    Display Homebrew's download cache. See also `HOMEBREW_CACHE`.
-#:
-#:  * `--cache` [`--build-from-source`|`-s`] [`--force-bottle`] <formula>:
-#:    Display the file or directory used to cache <formula>.
-
 require "fetch"
+require "cli_parser"
 
 module Homebrew
   module_function
 
+  def __cache_args
+    Homebrew::CLI::Parser.new do
+      usage_banner <<~EOS
+        `--cache` [<options>] [<formula>]
+
+        Display Homebrew's download cache. See also `HOMEBREW_CACHE`.
+
+        If <formula> is provided, display the file or directory used to cache <formula>.
+      EOS
+      switch "-s", "--build-from-source",
+        description: "Show the cache file used when building from source."
+      switch "--force-bottle",
+        description: "Show the cache file used when pouring a bottle."
+      conflicts "--build-from-source", "--force-bottle"
+    end
+  end
+
   def __cache
+    __cache_args.parse
+
     if ARGV.named.empty?
       puts HOMEBREW_CACHE
     else

Library/Homebrew/cmd/--cellar.rb

@@ -1,15 +1,25 @@
-#:  * `--cellar`:
-#:    Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if
-#:    that directory doesn't exist, `$(brew --repository)/Cellar`.
-#:
-#:  * `--cellar` <formula>:
-#:    Display the location in the cellar where <formula> would be installed,
-#:    without any sort of versioned directory as the last path.
+require "cli_parser"
 
 module Homebrew
   module_function
 
+  def __cellar_args
+    Homebrew::CLI::Parser.new do
+      usage_banner <<~EOS
+        `--cache` [<formula>]
+
+        Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if
+        that directory doesn't exist, `$(brew --repository)/Cellar`.
+
+        If <formula> is provided, display the location in the cellar where <formula>
+        would be installed, without any sort of versioned directory as the last path.
+      EOS
+    end
+  end
+
   def __cellar
+    __cellar_args.parse
+
     if ARGV.named.empty?
       puts HOMEBREW_CELLAR
     else

Library/Homebrew/cmd/--env.rb

@@ -1,36 +1,46 @@
-#:  * `--env` [`--shell=`(<shell>|`auto`)|`--plain`]:
-#:    Show a summary of the Homebrew build environment as a plain list.
-#:
-#:    Pass `--shell=`<shell> to generate a list of environment variables for the
-#:    specified shell, or `--shell=auto` to detect the current shell.
-#:
-#:    If the command's output is sent through a pipe and no shell is specified,
-#:    the list is formatted for export to `bash`(1) unless `--plain` is passed.
-
 require "extend/ENV"
 require "build_environment"
 require "utils/shell"
+require "cli_parser"
 
 module Homebrew
   module_function
 
+  def __env_args
+    Homebrew::CLI::Parser.new do
+      usage_banner <<~EOS
+        `--env` [<options>]
+
+        Show a summary of the Homebrew build environment as a plain list.
+
+        If the command's output is sent through a pipe and no shell is specified,
+        the list is formatted for export to `bash`(1) unless `--plain` is passed.
+      EOS
+      flag "--shell=",
+        description: "Generate a list of environment variables for the specified shell, " \
+                     "or `--shell=auto` to detect the current shell."
+      switch "--plain",
+        description: "Plain output even when piped."
+    end
+  end
+
   def __env
+    __env_args.parse
+
     ENV.activate_extensions!
     ENV.deps = ARGV.formulae if superenv?
     ENV.setup_build_environment
     ENV.universal_binary if ARGV.build_universal?
 
-    shell_value = ARGV.value("shell")
-
-    if ARGV.include?("--plain")
-      shell = nil
-    elsif shell_value.nil?
+    shell = if args.plain?
+      nil
+    elsif args.shell.nil?
       # legacy behavior
-      shell = :bash unless $stdout.tty?
-    elsif shell_value == "auto"
-      shell = Utils::Shell.parent || Utils::Shell.preferred
-    elsif shell_value
-      shell = Utils::Shell.from_path(shell_value)
+      :bash unless $stdout.tty?
+    elsif args.shell == "auto"
+      Utils::Shell.parent || Utils::Shell.preferred
+    elsif args.shell
+      Utils::Shell.from_path(args.shell)
     end
 
     env_keys = build_env_keys(ENV)

Library/Homebrew/cmd/--prefix.rb

@@ -1,13 +1,25 @@
-#:  * `--prefix`:
-#:    Display Homebrew's install path. *Default:* `/usr/local` on macOS and `/home/linuxbrew/.linuxbrew` on Linux
-#:
-#:  * `--prefix` <formula>:
-#:    Display the location in the cellar where <formula> is or would be installed.
+require "cli_parser"
 
 module Homebrew
   module_function
 
+  def __prefix_args
+    Homebrew::CLI::Parser.new do
+      usage_banner <<~EOS
+        `--prefix` [<formula>]
+
+        Display Homebrew's install path. *Default:* `/usr/local` on macOS and
+        `/home/linuxbrew/.linuxbrew` on Linux.
+
+        If <formula> is provided, display the location in the cellar where <formula>
+        is or would be installed.
+      EOS
+    end
+  end
+
   def __prefix
+    __prefix_args.parse
+
     if ARGV.named.empty?
       puts HOMEBREW_PREFIX
     else

Library/Homebrew/cmd/--repository.rb

@@ -1,13 +1,23 @@
-#:  * `--repository`:
-#:    Display where Homebrew's `.git` directory is located.
-#:
-#:  * `--repository` <user>`/`<repo>:
-#:    Display where tap <user>`/`<repo>'s directory is located.
+require "cli_parser"
 
 module Homebrew
   module_function
 
+  def __repository_args
+    Homebrew::CLI::Parser.new do
+      usage_banner <<~EOS
+        `--repository` [<formula>]
+
+        Display where Homebrew's `.git` directory is located.
+
+        If <user>`/`<repo> are provided, display where tap <user>`/`<repo>'s directory is located.
+      EOS
+    end
+  end
+
   def __repository
+    __repository_args.parse
+
     if ARGV.named.empty?
       puts HOMEBREW_REPOSITORY
     else

Library/Homebrew/cmd/--version.rb

@@ -1,10 +1,22 @@
-#:  * `--version`:
-#:    Print the version number of Homebrew to standard output and exit.
+require "cli_parser"
 
 module Homebrew
   module_function
 
+  def __version_args
+    Homebrew::CLI::Parser.new do
+      usage_banner <<~EOS
+        `--version`
+
+        Print the version number of Homebrew, Homebrew/homebrew-core and Homebrew/homebrew-cask
+        (if tapped) to standard output and exit.
+      EOS
+    end
+  end
+
   def __version
+    __version_args.parse
+
     odie "This command does not take arguments." if ARGV.any?
 
     puts "Homebrew #{HOMEBREW_VERSION}"

Library/Homebrew/cmd/analytics.rb

@@ -1,13 +1,3 @@
-#:  * `analytics` [`state`]:
-#:    Display anonymous user behaviour analytics state.
-#:    Read more at <https://docs.brew.sh/Analytics>.
-#:
-#:  * `analytics` (`on`|`off`):
-#:    Turn on/off Homebrew's analytics.
-#:
-#:  * `analytics` `regenerate-uuid`:
-#:    Regenerate UUID used in Homebrew's analytics.
-
 require "cli_parser"
 
 module Homebrew

Library/Homebrew/cmd/cat.rb

@@ -1,6 +1,3 @@
-#:  * `cat` <formula>:
-#:    Display the source to <formula>.
-
 require "cli_parser"
 
 module Homebrew

Library/Homebrew/cmd/cleanup.rb

@@ -1,17 +1,3 @@
-#:  * `cleanup` [`--prune=`<days>] [`--dry-run`] [`-s`] [<formulae>|<casks>]:
-#:    Remove stale lock files and outdated downloads for formulae and casks,
-#:    and remove old versions of installed formulae. If arguments are specified,
-#:    only do this for the specified formulae and casks.
-#:
-#:    If `--prune=`<days> is specified, remove all cache files older than <days>.
-#:
-#:    If `--dry-run` or `-n` is passed, show what would be removed, but do not
-#:    actually remove anything.
-#:
-#:    If `-s` is passed, scrub the cache, including downloads for even the latest
-#:    versions. Note downloads for any installed formula or cask will still not
-#:    be deleted. If you want to delete those too: `rm -rf "$(brew --cache)"`
-
 require "cleanup"
 require "cli_parser"
 
@@ -21,8 +7,7 @@ module Homebrew
   def cleanup_args
     Homebrew::CLI::Parser.new do
       usage_banner <<~EOS
-        `cleanup` [<options>] [<formulae>|<casks>]
-
+        `cleanup` [<options>] [<formula>|<cask>]
 
         Remove stale lock files and outdated downloads for formulae and casks,
         and remove old versions of installed formulae. If arguments are specified,

Library/Homebrew/cmd/command.rb

@@ -1,6 +1,3 @@
-#:  * `command` <cmd>:
-#:    Display the path to the file which is used when invoking `brew` <cmd>.
-
 require "commands"
 require "cli_parser"
 

Library/Homebrew/cmd/commands.rb

@@ -1,9 +1,3 @@
-#:  * `commands` [`--quiet` [`--include-aliases`]]:
-#:    Show a list of built-in and external commands.
-#:
-#:    If `--quiet` is passed, list only the names of commands without the header.
-#:    With `--include-aliases`, the aliases of internal commands will be included.
-
 require "cli_parser"
 
 module Homebrew

Library/Homebrew/cmd/config.rb

@@ -1,8 +1,3 @@
-#:  * `config`:
-#:    Show Homebrew and system configuration useful for debugging. If you file
-#:    a bug report, you will likely be asked for this information if you do not
-#:    provide it.
-
 require "system_config"
 require "cli_parser"
 

Library/Homebrew/cmd/deps.rb

@@ -1,60 +1,3 @@
-#:  * `deps` [`--1`] [`-n`] [`--union`] [`--full-name`] [`--installed`] [`--include-build`] [`--include-optional`] [`--skip-recommended`] [`--include-requirements`] <formula>:
-#:    Show dependencies for <formula>. When given multiple formula arguments,
-#:    show the intersection of dependencies for every formula.
-#:
-#:    If `--1` is passed, only show dependencies one level down, instead of
-#:    recursing.
-#:
-#:    If `-n` is passed, show dependencies in topological order.
-#:
-#:    If `--union` is passed, show the union of dependencies for <formula>,
-#:    instead of the intersection.
-#:
-#:    If `--full-name` is passed, list dependencies by their full name.
-#:
-#:    If `--installed` is passed, only list those dependencies that are
-#:    currently installed.
-#:
-#:    By default, `deps` shows required and recommended dependencies for
-#:    <formula>. To include the `:build` type dependencies, pass `--include-build`.
-#:    Similarly, pass `--include-optional` to include `:optional` dependencies or
-#:    `--include-test` to include (non-recursive) `:test` dependencies.
-#:    To skip `:recommended` type dependencies, pass `--skip-recommended`.
-#:    To include requirements in addition to dependencies, pass `--include-requirements`.
-#:
-#:  * `deps` `--tree` [`--1`] [<filters>] [`--annotate`] (<formula>|`--installed`):
-#:    Show dependencies as a tree. When given multiple formula arguments, output
-#:    individual trees for every formula.
-#:
-#:    If `--1` is passed, only one level of children is displayed.
-#:
-#:    If `--installed` is passed, output a tree for every installed formula.
-#:
-#:    The <filters> placeholder is any combination of options `--include-build`,
-#:    `--include-optional`, `--include-test`, `--skip-recommended`, and
-#:    `--include-requirements` as documented above.
-#:
-#:    If `--annotate` is passed, the build, optional, and recommended dependencies
-#:    are marked as such in the output.
-#:
-#:  * `deps` [<filters>] (`--installed`|`--all`):
-#:    Show dependencies for installed or all available formulae. Every line of
-#:    output starts with the formula name, followed by a colon and all direct
-#:    dependencies of that formula.
-#:
-#:    The <filters> placeholder is any combination of options `--include-build`,
-#:    `--include-optional`, `--include-test`, and `--skip-recommended` as
-#:    documented above.
-#:
-#:    Additional options specific to <formula> may be appended to the command,
-#:    and can be listed with `brew options` <formula>.
-
-# The undocumented `--for-each` option will switch into the mode used by `deps --all`,
-# but only list dependencies for specified formula, one specified formula per line.
-# This is used for debugging the `--installed`/`--all` display mode.
-
-# encoding: UTF-8
-
 require "formula"
 require "ostruct"
 require "cli_parser"
@@ -81,11 +24,11 @@ def deps_args
       switch "--installed",
         description: "Only list those dependencies that are currently installed."
       switch "--all",
-        description: "List all the dependencies for all available formuale."
+        description: "List all the dependencies for all available formulae."
       switch "--include-build",
         description: "Show `:build` type dependencies for <formula>."
       switch "--include-optional",
-        description: "Show `:optional` dependecies for <formula>."
+        description: "Show `:optional` dependencies for <formula>."
       switch "--include-test",
         description: "Show `:test` dependencies for <formula> (non-recursive)."
       switch "--skip-recommended",