cuprum-cli 0.1.0

data/lib/cuprum/cli/option.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+require 'cuprum/cli/options'
+
+module Cuprum::Cli # rubocop:disable Metrics/ModuleLength
+  # Data object representing a command option.
+  Option = Data.define(
+    :aliases,
+    :default,
+    :description,
+    :name,
+    :parameter_name,
+    :required,
+    :type,
+    :variadic
+  ) do
+    # @param name [String, Symbol] the name of the option.
+    # @param aliases [Array<String, Symbol>] aliases for the option when parsing
+    #   options from the command line.
+    # @param default [Object, Proc] the default value for the option. If given
+    #   and the value of the option is nil, sets the option value to the default
+    #   value.
+    # @param description [String] a short, human-readable description of the
+    #   option.
+    # @param parameter_name [String] a representation of the possible values for
+    #   the option.
+    # @param required [true, false] if true, raises an exception if the option
+    #   is not provided to the command.
+    # @param type [Class, String, Symbol] the expected type of the option value
+    #   as a Class or class name. If given, raises an exception if the option
+    #   value is not an instance of the type. Defaults to :string.
+    # @param variadic [true, false] if true, the option is variadic and
+    #   represents an hash of options provided to the command. Defaults to
+    #   false.
+    def initialize( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+      name:,
+      aliases:        [],
+      default:        nil,
+      description:    nil,
+      parameter_name: nil,
+      required:       false,
+      type:           :string,
+      variadic:       false
+    )
+      name     = name.to_sym
+      aliases  = Array(aliases).compact.map { |obj| obj.to_s.tr('_', '-') }
+      required = required ? true : false
+      type     = type.to_sym if type.is_a?(String)
+      variadic = variadic ? true : false
+
+      super(
+        aliases:,
+        default:,
+        description:,
+        name:,
+        parameter_name:,
+        required:,
+        type:,
+        variadic:
+      )
+    end
+
+    alias_method :required?, :required
+
+    alias_method :variadic?, :variadic
+
+    # @overload def resolve(value)
+    #   Validates the value for the current option.
+    #
+    #   If the value is nil, applies the option default (if any).
+    #
+    #   @param value [Object] the value to validate.
+    #
+    #   @return [Object] the validated option value.
+    #
+    #   @raise [Cuprum::Cli::Options::InvalidOptionError] if the value is
+    #     missing (for a required option) or invalid.
+    def resolve(original_value)
+      value = original_value
+      value = default_value if blank?(value)
+      value = value.to_s    if value.is_a?(Symbol)
+
+      return default_value_for_type if value.nil? && !required?
+      return value                  if valid_option?(value)
+
+      raise Cuprum::Cli::Options::InvalidOptionError,
+        invalid_option_message(original_value)
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def default_value
+      default.is_a?(Proc) ? default.call : default
+    end
+
+    def default_value_for_type
+      return {} if variadic?
+
+      return false if type == :boolean && !required?
+
+      nil
+    end
+
+    def expected_hash_type
+      message = required? ? 'a non-empty Hash of' : 'a Hash of'
+
+      return "#{message} true or false values" if type == :boolean
+
+      plural_type =
+        tools.string_tools.pluralize(type.is_a?(Class) ? type.name : type)
+
+      "#{message} #{tools.string_tools.camelize(plural_type)}"
+    end
+
+    def expected_type
+      return expected_hash_type if variadic?
+
+      case type
+      when :boolean
+        'true or false'
+      when Class
+        "an instance of #{type.name}"
+      else
+        "an instance of #{tools.string_tools.camelize(type.to_s)}"
+      end
+    end
+
+    def invalid_option_message(value)
+      "invalid value for option :#{name} - expected #{expected_type}, " \
+        "received #{value.inspect}"
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def valid_option?(value)
+      return validate_option(value) unless variadic?
+
+      return false unless value.is_a?(Hash)
+      return false if required? && value.empty?
+
+      value.each_value.all? { |item| validate_option(item) }
+    end
+
+    def validate_option(value) # rubocop:disable Naming/PredicateMethod
+      case type
+      when :boolean
+        value == true || value == false # rubocop:disable Style/MultipleComparison
+      when Class
+        value.is_a?(type)
+      else
+        expected = tools.string_tools.camelize(type.to_s)
+        expected = Object.const_get(expected)
+
+        value.is_a?(expected)
+      end
+    end
+  end
+end

data/lib/cuprum/cli/options/class_methods.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'weakref'
+
+require 'cuprum/cli/option'
+require 'cuprum/cli/options'
+
+module Cuprum::Cli::Options
+  # Methods used to extend command class functionality for defining options.
+  module ClassMethods
+    # Helper class for defining command options.
+    class Builder
+      # @param command_class [Class] the command class.
+      # @param defined_options [Hash{Symbol => Cuprum::Cli::Option}] the options
+      #   defined for the command.
+      def initialize(command_class:, defined_options:)
+        @command_class   = command_class
+        @defined_options = defined_options
+      end
+
+      # @return [Class] the command class.
+      attr_reader :command_class
+
+      # @return [Hash{Symbol => Cuprum::Cli::Option}] the options
+      #   defined for the command.
+      attr_reader :defined_options
+
+      # (see Cuprum::Cli::Options::ClassMethods#option)
+      def call(name, define_method: nil, define_predicate: nil, **options)
+        option = Cuprum::Cli::Option.new(name:, **options)
+
+        defined_options[option.name] = option
+
+        boolean_option = options[:type] == :boolean && !options[:variadic]
+
+        define_method    = !boolean_option if define_method.nil?
+        define_predicate = boolean_option  if define_predicate.nil?
+
+        define_method_for(option)    if define_method
+        define_predicate_for(option) if define_predicate
+
+        option.name
+      end
+
+      private
+
+      def define_method_for(option)
+        command_class.define_method(option.name) { @options[option.name] }
+      end
+
+      def define_predicate_for(option)
+        command_class.define_method(:"#{option.name}?") do
+          value = @options[option.name]
+
+          return false if value.nil? || value == false
+
+          !(value.respond_to?(:empty?) && value.empty?)
+        end
+      end
+    end
+
+    # @overload option(name, aliases: [], default: nil, description: nil, required: false, type: :string, **options)
+    #   Defines an option for the command class.
+    #
+    #   @param name [String, Symbol] the name of the option.
+    #   @param aliases [Array<String, Symbol>] aliases for the option when
+    #     parsing options from the command line.
+    #   @param default [Object, Proc] the default value for the option. If given
+    #     and the value of the option is nil, sets the option value to the
+    #     default value.
+    #   @param description [String] a short, human-readable description of the
+    #     option.
+    #   @param required [true, false] if true, raises an exception if the option
+    #     is not provided to the command.
+    #   @param type [Class, String, Symbol] the expected type of the option
+    #     value as a Class or class name. If given, raises an exception if the
+    #     option value is not an instance of the type. Defaults to :string.
+    #   @param options [Hash] additional options for defining the option.
+    #
+    #   @option options define_method [true, false] if true, defines a reader
+    #     method for the option. Defaults to false for boolean options and true
+    #     for all other options.
+    #   @option options define_predicate [true, false] if true, defines a
+    #     predicate method for the option, which returns true if the option is
+    #     not nil and not empty. Defaults to true for boolean options and false
+    #     for all other options.
+    def option(name, define_method: nil, define_predicate: nil, **)
+      handle_multiple_variadic_options(**)
+
+      options_builder
+        .call(name, define_method:, define_predicate:, **)
+    end
+
+    # Assigns a predefined option value for the command.
+    #
+    # @param option [String, Symbol] the option to set.
+    # @param value [Object] the option value to append.
+    #
+    # @return [void]
+    def option_value(option, value)
+      defined_option_values[option.to_sym] = value
+
+      nil
+    end
+
+    # @return [Hash{Symbol => Object}] predefined option values for the command.
+    def option_values = inherited_option_values.merge(defined_option_values)
+
+    # The defined options, including options defined on ancestor classes.
+    #
+    # @return [Hash{Symbol => Cuprum::Cli::Option}] the defined options.
+    def options
+      ancestors.reduce({}) do |hsh, ancestor|
+        return hsh if     ancestor == Cuprum::Cli::Command
+        next   hsh unless ancestor.respond_to?(:defined_options, true)
+
+        hsh.merge(ancestor.defined_options)
+      end
+    end
+
+    # Validates the given option values against the defined class options.
+    #
+    # Also applies any default values from the defined options.
+    #
+    # @param values [Hash] the option values to resolve.
+    #
+    # @return [Hash] the option values with applied defaults.
+    #
+    # @raise [Cuprum::Cli::Options::UnknownOptionError] if any value does not
+    #   have a corresponding defined option.
+    # @raise [Cuprum::Cli::Options::InvalidOptionError] if any value does not
+    #   match the expected option type, or any required value is missing.
+    def resolve_options(**values)
+      values                  = option_values.merge(values)
+      defined_options         = options
+      values, unknown_options = resolve_variadic_values(values)
+
+      unless unknown_options.empty?
+        raise Cuprum::Cli::Options::UnknownOptionError,
+          unknown_options_message(defined_options:, unknown_options:)
+      end
+
+      defined_options.to_h do |key, option|
+        [key, option.resolve(values[key])]
+      end
+    end
+
+    protected
+
+    def defined_options
+      @defined_options ||= {}
+    end
+
+    def defined_option_values = @defined_option_values ||= {}
+
+    def inherited_option_values
+      return {} unless superclass.respond_to?(:inherited_option_values, true)
+
+      superclass.inherited_option_values.merge(superclass.defined_option_values)
+    end
+
+    private
+
+    def handle_multiple_variadic_options(variadic: false, **)
+      return unless variadic
+
+      matching = defined_options.each_value.find(&:variadic?)
+
+      return unless matching
+
+      message = "command already defines variadic option :#{matching.name}"
+
+      raise ArgumentError, message
+    end
+
+    def options_builder
+      (
+        @options_builder ||= WeakRef.new(
+          Builder.new(command_class: self, defined_options:)
+        )
+      ).__getobj__
+    rescue RefError
+      # :nocov:
+      @options_builder = WeakRef.new(
+        Builder.new(command_class: self, defined_options:)
+      )
+      @arguments_builder.__getobj__
+      # :nocov:
+    end
+
+    def resolve_variadic_values(values) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      defined_options = options
+      unknown_options = values.keys - options.keys
+
+      return [values, unknown_options] if unknown_options.empty?
+
+      variadic_key = defined_options.find { |_, value| value.variadic? }&.first
+
+      return [values, unknown_options] unless variadic_key
+
+      variadic_value = values.fetch(variadic_key, {})
+
+      unless variadic_value.is_a?(Hash)
+        return [values.except(*unknown_options), []]
+      end
+
+      variadic_value = values.slice(*unknown_options).merge(variadic_value)
+
+      values =
+        values.except(*unknown_options).merge(variadic_key => variadic_value)
+
+      [values, []]
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def unknown_options_message(defined_options:, unknown_options:)
+      counted =
+        tools.integer_tools.pluralize(unknown_options.size, 'option')
+      unknown = unknown_options.map(&:inspect).join(', ')
+      message = "unrecognized #{counted} #{unknown} for #{name}"
+
+      return message if defined_options.empty?
+
+      valid_options = defined_options.keys.sort.map(&:inspect).join(', ')
+
+      "#{message} - valid options are #{valid_options}"
+    end
+  end
+end

data/lib/cuprum/cli/options/quiet.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/options'
+
+module Cuprum::Cli::Options
+  # Defines --quiet option, which silences non-essential output.
+  module Quiet
+    DESCRIPTION = 'Silences non-essential console outputs.'
+    private_constant :DESCRIPTION
+
+    class << self
+      private
+
+      def included(other)
+        super
+
+        other.option   :quiet,
+          type:        :boolean,
+          aliases:     :q,
+          default:     false,
+          description: DESCRIPTION
+      end
+    end
+
+    # (see Cuprum::Cli::Dependencies::StandardIo::Helpers#say)
+    def say(message, quiet: false, **)
+      return if options.fetch(:quiet, false) && !quiet
+
+      super
+    end
+  end
+end

data/lib/cuprum/cli/options/verbose.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli/options'
+
+module Cuprum::Cli::Options
+  # Defines --verbose option, which enables optional console outputs.
+  module Verbose
+    DESCRIPTION = 'Enables optional console outputs.'
+    private_constant :DESCRIPTION
+
+    class << self
+      private
+
+      def included(other)
+        super
+
+        other.option   :verbose,
+          type:        :boolean,
+          aliases:     :v,
+          default:     false,
+          description: DESCRIPTION
+      end
+    end
+
+    # (see Cuprum::Cli::Dependencies::StandardIo::Helpers#say)
+    def say(message, verbose: false, **)
+      return if verbose && !options.fetch(:verbose, false)
+
+      super
+    end
+  end
+end

data/lib/cuprum/cli/options.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+module Cuprum::Cli
+  # Namespace for functionality that implements command options.
+  module Options
+    autoload :ClassMethods, 'cuprum/cli/options/class_methods'
+    autoload :Quiet,        'cuprum/cli/options/quiet'
+    autoload :Verbose,      'cuprum/cli/options/verbose'
+
+    # Exception raised when a command receives an invalid value for an option.
+    class InvalidOptionError < StandardError; end
+
+    # Exception raised when a command receives an unrecognized option.
+    class UnknownOptionError < StandardError; end
+  end
+end

data/lib/cuprum/cli/registry.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'cuprum/cli'
+
+module Cuprum::Cli
+  # Registers CLI commands by name.
+  class Registry
+    # @return [Class, nil] the command registered with the given name, if any.
+    def [](name)
+      tools.assertions.validate_name(name, as: 'full_name')
+
+      registered_commands[name]
+    end
+
+    # Returns a copy of the commands registered with the registry.
+    #
+    # @return [Hash{String => Class}] the registered commands.
+    def commands
+      registered_commands.dup.freeze
+    end
+
+    # Registers the command with the registry.
+    #
+    # @param command [Class] the command class to register.
+    # @param config [Hash] options for configuring the command.
+    #
+    # @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.
+    #
+    # @raise [NameError] if a command is already registered with that name.
+    #
+    # @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
+
+      self
+    end
+    alias add register
+
+    private
+
+    def any_present?(config)
+      return false if config.empty?
+
+      config.each_value.any? { |value| present?(value) }
+    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,
+      **
+    )
+      Class.new(command).tap do |command_class|
+        command_class.description(description) if present?(description)
+
+        command_class.full_name(full_name) if present?(full_name)
+
+        if present?(full_description)
+          command_class.full_description(full_description)
+        end
+
+        arguments&.each do |argument|
+          command_class.argument_value(argument)
+        end
+
+        options&.each do |option, value|
+          command_class.option_value(option, value)
+        end
+      end
+    end
+
+    def command_name(command)
+      command
+        .ancestors
+        .find { |ancestor| ancestor.is_a?(Class) && ancestor.name }
+        .name
+    end
+
+    def invalid_name_format_message
+      '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
+
+    def validate_command(command)
+      tools.assertions.validate_class(command, as: 'command')
+      tools.assertions.validate_inherits_from(
+        command,
+        as:       'command',
+        expected: Cuprum::Cli::Command
+      )
+    end
+
+    def validate_name(name) # rubocop:disable Metrics/MethodLength
+      tools.assertions.validate_name(name, as: 'full_name')
+      tools.assertions.validate_matches(
+        name,
+        as:       'full_name',
+        expected: Cuprum::Cli::Metadata::FULL_NAME_FORMAT,
+        message:  invalid_name_format_message
+      )
+
+      return unless registered_commands.key?(name)
+
+      command = registered_commands[name]
+      message =
+        "command already registered as #{name} - #{command_name(command)}"
+
+      raise NameError, message
+    end
+  end
+end