Implement cmd_args block

Library/Homebrew/abstract_command.rb

@@ -4,36 +4,49 @@
 require "command_registry"
 
 module Homebrew
+  # Subclass this to implement a `brew` command. This is preferred to declaring a named function in the `Homebrew`
+  # module, because:
+  # - Each Command lives in an isolated namespace.
+  # - Each Command implements a defined interface.
+  #
+  # To subclass, implement a `run` method and provide a `cmd_args` block to document the command and its allowed args.
   class AbstractCommand
     extend T::Helpers
 
     abstract!
 
     class << self
+      sig { returns(T.nilable(T.proc.void)) }
+      attr_reader :parser_block
+
+      sig { returns(String) }
+      def command_name = T.must(name).split("::").fetch(-1).downcase
+
+      private
+
+      sig { params(block: T.nilable(T.proc.bind(CLI::Parser).void)).void }
+      def cmd_args(&block)
+        @parser_block = T.let(block, T.nilable(T.proc.void))
+      end
+
       # registers subclasses for lookup by command name
       sig { params(subclass: T.class_of(AbstractCommand)).void }
       def inherited(subclass)
         super
         CommandRegistry.register(subclass)
       end
-
-      sig { returns(String) }
-      def command_name = T.must(name).split("::").fetch(-1).downcase
     end
 
     # @note because `Args` makes use `OpenStruct`, subclasses may need to use a tapioca compiler,
     #   hash accessors, args.rbi, or other means to make this work with legacy commands:
-    sig { returns(Homebrew::CLI::Args) }
+    sig { returns(CLI::Args) }
     attr_reader :args
 
     sig { void }
     def initialize
-      @args = T.let(raw_args.parse, Homebrew::CLI::Args)
+      @args = T.let(CLI::Parser.new(&self.class.parser_block).parse, CLI::Args)
     end
 
-    sig { abstract.returns(CLI::Parser) }
-    def raw_args; end
-
     sig { abstract.void }
     def run; end
   end

Library/Homebrew/cmd/list.rb

@@ -13,9 +13,7 @@ module Homebrew
     class List < AbstractCommand
       include SystemCommand::Mixin
 
-      sig { override.returns(CLI::Parser) }
+      cmd_args do
-      def raw_args
-        Homebrew::CLI::Parser.new do
         description <<~EOS
           List all installed formulae and casks.
           If <formula> is provided, summarise the paths within its current keg.
@@ -46,8 +44,8 @@ module Homebrew
                description: "List formulae and/or casks in long format. " \
                             "Has no effect when a formula or cask name is passed as an argument."
         switch "-r",
-                 description: "Reverse the order of the formulae and/or casks sort to list the oldest entries " \
+               description: "Reverse the order of the formulae and/or casks sort to list the oldest entries first. " \
-                              "first. Has no effect when a formula or cask name is passed as an argument."
+                            "Has no effect when a formula or cask name is passed as an argument."
         switch "-t",
                description: "Sort formulae and/or casks by time modified, listing most recently modified first. " \
                             "Has no effect when a formula or cask name is passed as an argument."
@@ -66,7 +64,6 @@ module Homebrew
 
         named_args [:installed_formula, :installed_cask]
       end
-      end
 
       sig { override.void }
       def run

Library/Homebrew/dev-cmd/prof.rb

@@ -7,9 +7,7 @@ require "cli/parser"
 module Homebrew
   module DevCmd
     class Prof < AbstractCommand
-      sig { override.returns(CLI::Parser) }
+      cmd_args do
-      def raw_args
-        Homebrew::CLI::Parser.new do
         description <<~EOS
           Run Homebrew with a Ruby profiler. For example, `brew prof readall`.
         EOS
@@ -18,7 +16,6 @@ module Homebrew
 
         named_args :command, min: 1
       end
-      end
 
       sig { override.void }
       def run