Add the ability to hide command from "usage" output (#137)

dry-rb · Sep 21, 2024 · d4d1343 · d4d1343
1 parent e15b0ad
commit d4d1343
Show file tree

Hide file tree

Showing 7 changed files with 62 additions and 20 deletions.
diff --git a/Gemfile b/Gemfile
@@ -9,6 +9,5 @@ gemspec
 gem "backports", "~> 3.15.0", require: false
 
 unless ENV["CI"]
-  gem "byebug", require: false, platforms: :mri
   gem "yard",   require: false
 end
diff --git a/changelog.yml b/changelog.yml
@@ -1,4 +1,9 @@
 ---
+- version: 1.1.1
+  date: 2024-08-09
+  added:
+    - |-
+      Added `:hidden` option to register commands that should not be shown in the help output. (@benoittgt in #137)
 - version: 1.1.0
   date: 2024-07-14
   added:

diff --git a/docsite/source/index.html.md b/docsite/source/index.html.md
@@ -94,6 +94,16 @@ module Foo
         end
       end
 
+      class Completion < Dry::CLI::Command
+        desc "Generate completion"
+
+        option :shell, default: "bash", values: %w[bash zsh]
+
+        def call(shell:, **)
+          puts "generated completion - shell: #{shell}"
+        end
+      end
+
       module Generate
         class Configuration < Dry::CLI::Command
           desc "Generate configuration"
@@ -116,11 +126,12 @@ module Foo
         end
       end
 
-      register "version", Version, aliases: ["v", "-v", "--version"]
-      register "echo",    Echo
-      register "start",   Start
-      register "stop",    Stop
-      register "exec",    Exec
+      register "version",    Version, aliases: ["v", "-v", "--version"]
+      register "echo",       Echo
+      register "start",      Start
+      register "stop",       Stop
+      register "exec",       Exec
+      register "completion", Completion, hidden: true
 
       register "generate", aliases: ["g"] do |prefix|
         prefix.register "config", Generate::Configuration
@@ -148,6 +159,8 @@ Commands:
   foo version                            # Print version
 ```
 
+You can choose to hide a command from the help output by setting the `hidden` option to `true` when registering the command.
+
 ### Help
 
 It is also possible to get help for a particular command using the `--help` flag:

diff --git a/lib/dry/cli/command_registry.rb b/lib/dry/cli/command_registry.rb
@@ -18,14 +18,15 @@ def initialize
 
       # @since 0.1.0
       # @api private
-      def set(name, command, aliases)
+      def set(name, command, aliases, hidden)
         @_mutex.synchronize do
           node = @root
           name.split(/[[:space:]]/).each do |token|
             node = node.put(node, token)
           end
 
           node.aliases!(aliases)
+          node.hidden!(hidden)
           if command
             node.leaf!(command)
             node.subcommands!(command)
@@ -91,6 +92,10 @@ class Node
         # @api private
         attr_reader :aliases
 
+        # @since 1.1.1
+        # @api private
+        attr_reader :hidden
+
         # @since 0.1.0
         # @api private
         attr_reader :command
@@ -109,6 +114,7 @@ def initialize(parent = nil)
           @parent   = parent
           @children = {}
           @aliases  = {}
+          @hidden   = hidden
           @command  = nil
 
           @before_callbacks = Chain.new
@@ -154,6 +160,12 @@ def aliases!(aliases)
           end
         end
 
+        # @since 1.1.1
+        # @api private
+        def hidden!(hidden)
+          @hidden = hidden
+        end
+
         # @since 0.1.0
         # @api private
         def leaf?

diff --git a/lib/dry/cli/registry.rb b/lib/dry/cli/registry.rb
@@ -75,11 +75,11 @@ def self.extended(base)
       #       end
       #     end
       #   end
-      def register(name, command = nil, aliases: [], &block)
-        @commands.set(name, command, aliases)
+      def register(name, command = nil, aliases: [], hidden: false, &block)
+        @commands.set(name, command, aliases, hidden)
 
         if block_given?
-          prefix = Prefix.new(@commands, name, aliases)
+          prefix = Prefix.new(@commands, name, aliases, hidden)
           if block.arity.zero?
             prefix.instance_eval(&block)
           else
@@ -308,19 +308,19 @@ def _callback(callback, blk)
       class Prefix
         # @since 0.1.0
         # @api private
-        def initialize(registry, prefix, aliases)
+        def initialize(registry, prefix, aliases, hidden)
           @registry = registry
           @prefix   = prefix
 
-          registry.set(prefix, nil, aliases)
+          registry.set(prefix, nil, aliases, hidden)
         end
 
         # @since 0.1.0
         #
         # @see Dry::CLI::Registry#register
-        def register(name, command, aliases: [])
+        def register(name, command, aliases: [], hidden: false)
           command_name = "#{prefix} #{name}"
-          registry.set(command_name, command, aliases)
+          registry.set(command_name, command, aliases, hidden)
         end
 
         private

diff --git a/lib/dry/cli/usage.rb b/lib/dry/cli/usage.rb
@@ -21,9 +21,11 @@ def self.call(result)
         max_length, commands = commands_and_arguments(result)
 
         commands.map do |banner, node|
+          next if node.hidden
+
           usage = description(node.command) if node.leaf?
           "#{justify(banner, max_length, usage)}#{usage}"
-        end.unshift(header).join("\n")
+        end.compact.unshift(header).join("\n")
       end
 
       # @since 0.1.0

diff --git a/spec/support/fixtures/foo b/spec/support/fixtures/foo
@@ -331,6 +331,16 @@ module Foo
         end
       end
 
+      class Completion < Dry::CLI::Command
+        desc "Generate completion script"
+
+        option :shell, desc: "Shell to generate completion script for", default: "bash"
+
+        def call(shell:, **)
+          puts "completion - shell: #{shell}"
+        end
+      end
+
       class Exec < Dry::CLI::Command
         desc "Execute a task"
 
@@ -454,11 +464,12 @@ Foo::CLI::Commands.register "generate", aliases: ["g"] do |prefix|
   prefix.register "model",     Foo::CLI::Commands::Generate::Model
   prefix.register "secret",    Foo::CLI::Commands::Generate::Secret
 end
-Foo::CLI::Commands.register "new",     Foo::CLI::Commands::New
-Foo::CLI::Commands.register "routes",  Foo::CLI::Commands::Routes
-Foo::CLI::Commands.register "server",  Foo::CLI::Commands::Server,  aliases: ["s"]
-Foo::CLI::Commands.register "version", Foo::CLI::Commands::Version, aliases: ["v", "-v", "--version"]
-Foo::CLI::Commands.register "exec",    Foo::CLI::Commands::Exec
+Foo::CLI::Commands.register "new",        Foo::CLI::Commands::New
+Foo::CLI::Commands.register "routes",     Foo::CLI::Commands::Routes
+Foo::CLI::Commands.register "server",     Foo::CLI::Commands::Server,  aliases: ["s"]
+Foo::CLI::Commands.register "version",    Foo::CLI::Commands::Version, aliases: ["v", "-v", "--version"]
+Foo::CLI::Commands.register "completion", Foo::CLI::Commands::Completion, hidden: true
+Foo::CLI::Commands.register "exec",       Foo::CLI::Commands::Exec
 
 Foo::CLI::Commands.register "hello",       Foo::CLI::Commands::Hello
 Foo::CLI::Commands.register "greeting",    Foo::CLI::Commands::Greeting