cuprum-cli 0.1.0 → 0.2.0

data/lib/cuprum/cli/registry.rb

@@ -19,34 +19,107 @@ module Cuprum::Cli
       registered_commands.dup.freeze
     end
 
-    # Registers the command with the registry.
+    # @overload register(*commands, **config, &block)
+    #   Registers the commands with the registry.
     #
-    # @param command [Class] the command class to register.
-    # @param config [Hash] options for configuring the command.
+    #   If given a block, transforms the command using the block. This can be
+    #   used to customize the commands, such as applying a custom prefix or
+    #   configuration options. If the block instead returns nil, that command
+    #   will not be registered.
     #
-    # @option config arguments [Array] arguments to pass to the command on
-    #   initialization.
-    # @option config description [String] the description for the command.
-    # @option config full_description [String] the full description for the
-    #   command.
-    # @option config full_name [String] the name under which to register the
-    #   command. Defaults to the value of command.full_name.
-    # @option config options [Hash] options to pass to the command on
-    #   initialization.
+    #   @param commands [Array<Class>] the command classes to register.
+    #   @param config [Hash] options for configuring the command.
     #
-    # @raise [NameError] if a command is already registered with that name.
+    #   @option config arguments [Array] arguments to pass to the command on
+    #     initialization.
+    #   @option config description [String] the description for the command.
+    #   @option config full_description [String] the full description for the
+    #     command.
+    #   @option config full_name [String] the name under which to register the
+    #     command. Defaults to the value of command.full_name.
+    #   @option config options [Hash] options to pass to the command on
+    #     initialization.
     #
-    # @return [self]
-    def register(command, **config)
-      validate_command(command)
-
-      name = config.fetch(:full_name, command.full_name)
-
-      validate_name(name)
-
-      command = build_command(command, **config) if any_present?(config)
-
-      registered_commands[name] = command
+    #   @yieldparam command [Class] the original command class.
+    #
+    #   @yieldreturn [Class, nil] the command class to register. If nil is
+    #     returned instead, nothing will be registered for the input command.
+    #
+    #   @raise [NameError] if a command is already registered with that name.
+    #
+    #   @return [self]
+    #
+    #   @example Register a command
+    #     registry.register(ExampleCommand)
+    #
+    #     registry.commands.key?('example')
+    #     #=> true
+    #
+    #   @example Register a command with configuration options
+    #     registry.register ExampleCommand,
+    #       full_name: 'scope:custom_command',
+    #       options:   { option: 'value' }
+    #
+    #     registry.commands.key?('example')
+    #     #=> false
+    #     registry.commands.key?('scope:custom_command')
+    #     #=> true
+    #     registry.commands['scope:example_command'].option_values
+    #     #=> { option: 'value' }
+    #
+    #   @example Register multiple commands with configuration options
+    #     registry.register FirstCommand,
+    #       SecondCommand,
+    #       ThirdCommand,
+    #       options: { shared: 'value' }
+    #
+    #     registry.commands.key?('first')
+    #     #=> true
+    #     registry.commands.key?('second')
+    #     #=> true
+    #     registry.commands.key?('third')
+    #     #=> true
+    #     registry.commands['first'].option_values
+    #     #=> { shared: 'value' }
+    #
+    #   @example Register multiple commands and configure with a block
+    #     registry.register(FirstCommand, SecondCommand, ThirdCommand) do |command|
+    #       full_name = "scope:#{command.full_name}"
+    #
+    #       command.with_full_name(full_name)
+    #     end
+    #
+    #     registry.commands.key?('scope:first')
+    #     #=> true
+    #     registry.commands.key?('scope:second')
+    #     #=> true
+    #     registry.commands.key?('scope:third')
+    #     #=> true
+    #
+    #   @example Register multiple commands and filter with a block
+    #     commands = [OneCommand, TwoCommand, ThreeCommand]
+    #
+    #     registry.register(commands) do |command|
+    #       next unless command.full_name.start_with?('t')
+    #
+    #       command
+    #     end
+    #
+    #     registry.commands.key?('one')
+    #     #=> false
+    #     registry.commands.key?('two')
+    #     #=> true
+    #     registry.commands.key?('three')
+    #     #=> true
+    def register(*commands, **config, &block)
+      tools.assertions.validate_presence(commands, as: 'commands')
+
+      commands
+        .flatten
+        .each { |command| validate_command(command) }
+        .map  { |command| build_command(command, **config, &block) }
+        .compact
+        .each { |command| add_registered_command(command) }
 
       self
     end
@@ -54,38 +127,49 @@ module Cuprum::Cli
 
     private
 
-    def any_present?(config)
-      return false if config.empty?
+    def add_registered_command(command)
+      validate_name(command.full_name)
 
-      config.each_value.any? { |value| present?(value) }
+      registered_commands[command.full_name] = command
     end
 
-    def build_command( # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists
-      command,
-      arguments:        nil,
-      description:      nil,
-      full_description: nil,
-      full_name:        nil,
-      options:          nil,
-      **
+    def assign_command_properties( # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+      command_class,
+      parent_class,
+      arguments: nil,
+      options:   nil,
+      **config
     )
-      Class.new(command).tap do |command_class|
-        command_class.description(description) if present?(description)
+      %i[description full_description full_name].each do |property|
+        next unless config.key?(property) || parent_class.send(:"#{property}?")
 
-        command_class.full_name(full_name) if present?(full_name)
+        value = config.fetch(property, parent_class.send(property))
 
-        if present?(full_description)
-          command_class.full_description(full_description)
-        end
+        tools.assertions.validate_presence(value, as: property)
 
-        arguments&.each do |argument|
-          command_class.argument_value(argument)
-        end
+        command_class.send(property, value)
+      end
+
+      arguments&.each do |argument|
+        command_class.argument_value(argument)
+      end
 
-        options&.each do |option, value|
-          command_class.option_value(option, value)
-        end
+      options&.each do |option, value|
+        command_class.option_value(option, value)
       end
+
+      command_class
+    end
+
+    def build_command(parent_class, **config, &block)
+      return parent_class unless block_given? || !config.empty?
+
+      Class
+        .new(parent_class)
+        .then do |klass|
+          assign_command_properties(klass, parent_class, **config)
+        end # rubocop:disable Style/MultilineBlockChain
+        .then { |klass| block_given? ? block.call(klass) : klass }
     end
 
     def command_name(command)
@@ -99,14 +183,6 @@ module Cuprum::Cli
       'full_name does not match format category:sub_category:do_something'
     end
 
-    def present?(value)
-      return false if value.nil?
-
-      return false unless value.respond_to?(:empty?) && !value.empty?
-
-      true
-    end
-
     def registered_commands = @registered_commands ||= {}
 
     def tools = SleepingKingStudios::Tools::Toolbelt.instance