dry-cli 0.4.0

data/dry-cli.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'dry/cli/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'dry-cli'
+  spec.version       = Dry::CLI::VERSION
+  spec.authors       = ['Luca Guidi']
+  spec.email         = ['me@lucaguidi.com']
+  spec.licenses      = ['MIT']
+
+  spec.summary       = 'Dry CLI'
+  spec.description   = 'Common framework to build command line interfaces with Ruby'
+  spec.homepage      = 'http://dry-rb.org'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['source_code_uri'] = 'https://github.com/dry-rb/dry-cli'
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.add_dependency 'concurrent-ruby', '~> 1.0'
+  spec.add_dependency 'hanami-utils',    '~> 1.3'
+
+  spec.add_development_dependency 'bundler', '>= 1.6', '< 3'
+  spec.add_development_dependency 'rake',  '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.7'
+  spec.add_development_dependency 'simplecov', '~> 0.17.1'
+end

data/lib/dry/cli.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# Dry
+#
+# @since 0.1.0
+module Dry
+  # General purpose Command Line Interface (CLI) framework for Ruby
+  #
+  # @since 0.1.0
+  class CLI
+    require 'dry/cli/version'
+    require 'dry/cli/errors'
+    require 'dry/cli/command'
+    require 'dry/cli/registry'
+    require 'dry/cli/parser'
+    require 'dry/cli/usage'
+    require 'dry/cli/banner'
+
+    # Check if command
+    #
+    # @param command [Object] the command to check
+    #
+    # @return [TrueClass,FalseClass] true if instance of `Dry::CLI::Command`
+    #
+    # @since 0.1.0
+    # @api private
+    def self.command?(command)
+      case command
+      when Class
+        command.ancestors.include?(Command)
+      else
+        command.is_a?(Command)
+      end
+    end
+
+    # Create a new instance
+    #
+    # @param registry [Dry::CLI::Registry] a registry
+    #
+    # @return [Dry::CLI] the new instance
+    # @since 0.1.0
+    def initialize(registry)
+      @commands = registry
+    end
+
+    # Invoke the CLI
+    #
+    # @param arguments [Array<string>] the command line arguments (defaults to `ARGV`)
+    # @param out [IO] the standard output (defaults to `$stdout`)
+    #
+    # @since 0.1.0
+    def call(arguments: ARGV, out: $stdout)
+      result = commands.get(arguments)
+
+      if result.found?
+        command, args = parse(result, out)
+
+        result.before_callbacks.run(command, args)
+        command.call(args)
+        result.after_callbacks.run(command, args)
+      else
+        usage(result, out)
+      end
+    end
+
+    private
+
+    # @since 0.1.0
+    # @api private
+    attr_reader :commands
+
+    # Parse arguments for a command.
+    #
+    # It may exit in case of error, or in case of help.
+    #
+    # @param result [Dry::CLI::CommandRegistry::LookupResult]
+    # @param out [IO] sta output
+    #
+    # @return [Array<Dry:CLI::Command, Array>] returns an array where the
+    #   first element is a command and the second one is the list of arguments
+    #
+    # @since 0.1.0
+    # @api private
+    def parse(result, out)
+      command = result.command
+      return [command, result.arguments] unless command?(command)
+
+      result = Parser.call(command, result.arguments, result.names)
+
+      if result.help?
+        Banner.call(command, out)
+        exit(0)
+      end
+
+      if result.error?
+        out.puts(result.error)
+        exit(1)
+      end
+
+      [command, result.arguments]
+    end
+
+    # Prints the command usage and exit.
+    #
+    # @param result [Dry::CLI::CommandRegistry::LookupResult]
+    # @param out [IO] sta output
+    #
+    # @since 0.1.0
+    # @api private
+    def usage(result, out)
+      Usage.call(result, out)
+      exit(1)
+    end
+
+    # Check if command
+    #
+    # @param command [Object] the command to check
+    #
+    # @return [TrueClass,FalseClass] true if instance of `Dry::CLI::Command`
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @see .command?
+    def command?(command)
+      CLI.command?(command)
+    end
+  end
+end

data/lib/dry/cli/banner.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'dry/cli/program_name'
+
+module Dry
+  class CLI
+    # Command banner
+    #
+    # @since 0.1.0
+    # @api private
+    module Banner
+      # Prints command banner
+      #
+      # @param command [Dry::CLI::Command] the command
+      # @param out [IO] standard output
+      #
+      # @since 0.1.0
+      # @api private
+      def self.call(command, out)
+        output = [
+          command_name(command),
+          command_name_and_arguments(command),
+          command_description(command),
+          command_arguments(command),
+          command_options(command),
+          command_examples(command)
+        ].compact.join("\n")
+
+        out.puts output
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.command_name(command)
+        "Command:\n  #{full_command_name(command)}"
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.command_name_and_arguments(command)
+        "\nUsage:\n  #{full_command_name(command)}#{arguments(command)}"
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.command_examples(command)
+        return if command.examples.empty?
+
+        "\nExamples:\n#{command.examples.map { |example| "  #{full_command_name(command)} #{example}" }.join("\n")}" # rubocop:disable Metrics/LineLength
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.command_description(command)
+        return if command.description.nil?
+
+        "\nDescription:\n  #{command.description}"
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.command_arguments(command)
+        return if command.arguments.empty?
+
+        "\nArguments:\n#{extended_command_arguments(command)}"
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.command_options(command)
+        "\nOptions:\n#{extended_command_options(command)}"
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.full_command_name(command)
+        ProgramName.call(command.command_name)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.arguments(command)
+        required_arguments = command.required_arguments
+        optional_arguments = command.optional_arguments
+
+        required = required_arguments.map { |arg| arg.name.upcase }.join(' ') if required_arguments.any? # rubocop:disable Metrics/LineLength
+        optional = optional_arguments.map { |arg| "[#{arg.name.upcase}]" }.join(' ') if optional_arguments.any? # rubocop:disable Metrics/LineLength
+        result = [required, optional].compact
+
+        " #{result.join(' ')}" unless result.empty?
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.extended_command_arguments(command)
+        command.arguments.map do |argument|
+          "  #{argument.name.to_s.upcase.ljust(20)}\t# #{'REQUIRED ' if argument.required?}#{argument.desc}" # rubocop:disable Metrics/LineLength
+        end.join("\n")
+      end
+
+      # @since 0.1.0
+      # @api private
+      #
+      # rubocop:disable Metrics/AbcSize
+      def self.extended_command_options(command)
+        result = command.options.map do |option|
+          name = Hanami::Utils::String.dasherize(option.name)
+          name = if option.boolean?
+                   "[no-]#{name}"
+                 else
+                   "#{name}=VALUE"
+                 end
+
+          name = "#{name}, #{option.aliases.map { |a| a.start_with?('--') ? "#{a}=VALUE" : "#{a} VALUE" }.join(', ')}" unless option.aliases.empty? # rubocop:disable Metrics/LineLength
+          name = "  --#{name.ljust(30)}"
+          name = "#{name}\t# #{option.desc}"
+          name = "#{name}, default: #{option.default.inspect}" unless option.default.nil?
+          name
+        end
+
+        result << "  --#{'help, -h'.ljust(30)}\t# Print this help"
+        result.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize
+    end
+  end
+end

data/lib/dry/cli/command.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'concurrent/array'
+require 'dry/cli/option'
+
+module Dry
+  class CLI
+    # Base class for commands
+    #
+    # @since 0.1.0
+    class Command
+      # @since 0.1.0
+      # @api private
+      def self.inherited(base)
+        super
+        base.extend ClassMethods
+      end
+
+      # @since 0.1.0
+      # @api private
+      module ClassMethods
+        # @since 0.1.0
+        # @api private
+        def self.extended(base)
+          super
+
+          base.class_eval do
+            @description  = nil
+            @examples     = Concurrent::Array.new
+            @arguments    = Concurrent::Array.new
+            @options      = Concurrent::Array.new
+          end
+        end
+
+        # @since 0.1.0
+        # @api private
+        attr_reader :description
+
+        # @since 0.1.0
+        # @api private
+        attr_reader :examples
+
+        # @since 0.1.0
+        # @api private
+        attr_reader :arguments
+
+        # @since 0.1.0
+        # @api private
+        attr_reader :options
+      end
+
+      # Set the description of the command
+      #
+      # @param description [String] the description
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require "dry/cli"
+      #
+      #   class Echo < Dry::CLI::Command
+      #     desc "Prints given input"
+      #
+      #     def call(*)
+      #       # ...
+      #     end
+      #   end
+      def self.desc(description)
+        @description = description
+      end
+
+      # Describe the usage of the command
+      #
+      # @param examples [Array<String>] one or more examples
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require "dry/cli"
+      #
+      #   class Server < Dry::CLI::Command
+      #     example [
+      #       "                    # Basic usage (it uses the bundled server engine)",
+      #       "--server=webrick    # Force `webrick` server engine",
+      #       "--host=0.0.0.0      # Bind to a host",
+      #       "--port=2306         # Bind to a port",
+      #       "--no-code-reloading # Disable code reloading"
+      #     ]
+      #
+      #     def call(*)
+      #       # ...
+      #     end
+      #   end
+      #
+      #   # $ foo server --help
+      #   #   # ...
+      #   #
+      #   #   Examples:
+      #   #     foo server                     # Basic usage (it uses the bundled server engine)
+      #   #     foo server --server=webrick    # Force `webrick` server engine
+      #   #     foo server --host=0.0.0.0      # Bind to a host
+      #   #     foo server --port=2306         # Bind to a port
+      #   #     foo server --no-code-reloading # Disable code reloading
+      def self.example(*examples)
+        @examples += examples.flatten
+      end
+
+      # Specify an argument
+      #
+      # @param name [Symbol] the argument name
+      # @param options [Hash] a set of options
+      #
+      # @since 0.1.0
+      #
+      # @example Optional argument
+      #   require "dry/cli"
+      #
+      #   class Hello < Dry::CLI::Command
+      #     argument :name
+      #
+      #     def call(name: nil, **)
+      #       if name.nil?
+      #         puts "Hello, stranger"
+      #       else
+      #         puts "Hello, #{name}"
+      #       end
+      #     end
+      #   end
+      #
+      #   # $ foo hello
+      #   #   Hello, stranger
+      #
+      #   # $ foo hello Luca
+      #   #   Hello, Luca
+      #
+      # @example Required argument
+      #   require "dry/cli"
+      #
+      #   class Hello < Dry::CLI::Command
+      #     argument :name, required: true
+      #
+      #     def call(name:, **)
+      #       puts "Hello, #{name}"
+      #     end
+      #   end
+      #
+      #   # $ foo hello Luca
+      #   #   Hello, Luca
+      #
+      #   # $ foo hello
+      #   #   ERROR: "foo hello" was called with no arguments
+      #   #   Usage: "foo hello NAME"
+      #
+      # @example Multiple arguments
+      #   require "dry/cli"
+      #
+      #   module Generate
+      #     class Action < Dry::CLI::Command
+      #       argument :app,    required: true
+      #       argument :action, required: true
+      #
+      #       def call(app:, action:, **)
+      #         puts "Generating action: #{action} for app: #{app}"
+      #       end
+      #     end
+      #   end
+      #
+      #   # $ foo generate action web home
+      #   #   Generating action: home for app: web
+      #
+      #   # $ foo generate action
+      #   #   ERROR: "foo generate action" was called with no arguments
+      #   #   Usage: "foo generate action APP ACTION"
+      #
+      # @example Description
+      #   require "dry/cli"
+      #
+      #   class Hello < Dry::CLI::Command
+      #     argument :name, desc: "The name of the person to greet"
+      #
+      #     def call(name: nil, **)
+      #       # ...
+      #     end
+      #   end
+      #
+      #   # $ foo hello --help
+      #   #   Command:
+      #   #     foo hello
+      #   #
+      #   #   Usage:
+      #   #     foo hello [NAME]
+      #   #
+      #   #   Arguments:
+      #   #     NAME                # The name of the person to greet
+      #   #
+      #   #   Options:
+      #   #     --help, -h          # Print this help
+      def self.argument(name, options = {})
+        @arguments << Argument.new(name, options)
+      end
+
+      # Command line option (aka optional argument)
+      #
+      # @param name [Symbol] the param name
+      # @param options [Hash] a set of options
+      #
+      # @since 0.1.0
+      #
+      # @example Basic usage
+      #   require "dry/cli"
+      #
+      #   class Console < Dry::CLI::Command
+      #     param :engine
+      #
+      #     def call(engine: nil, **)
+      #       puts "starting console (engine: #{engine || :irb})"
+      #     end
+      #   end
+      #
+      #   # $ foo console
+      #   # starting console (engine: irb)
+      #
+      #   # $ foo console --engine=pry
+      #   # starting console (engine: pry)
+      #
+      # @example List values
+      #   require "dry/cli"
+      #
+      #   class Console < Dry::CLI::Command
+      #     param :engine, values: %w(irb pry ripl)
+      #
+      #     def call(engine: nil, **)
+      #       puts "starting console (engine: #{engine || :irb})"
+      #     end
+      #   end
+      #
+      #   # $ foo console
+      #   # starting console (engine: irb)
+      #
+      #   # $ foo console --engine=pry
+      #   # starting console (engine: pry)
+      #
+      #   # $ foo console --engine=foo
+      #   # Error: Invalid param provided
+      #
+      # @example Description
+      #   require "dry/cli"
+      #
+      #   class Console < Dry::CLI::Command
+      #     param :engine, desc: "Force a console engine"
+      #
+      #     def call(engine: nil, **)
+      #       # ...
+      #     end
+      #   end
+      #
+      #   # $ foo console --help
+      #   # # ...
+      #   #
+      #   # Options:
+      #   #   --engine=VALUE                  # Force a console engine: (irb/pry/ripl)
+      #   #   --help, -h                      # Print this help
+      #
+      # @example Boolean
+      #   require "dry/cli"
+      #
+      #   class Server < Dry::CLI::Command
+      #     param :code_reloading, type: :boolean, default: true
+      #
+      #     def call(code_reloading:, **)
+      #       puts "staring server (code reloading: #{code_reloading})"
+      #     end
+      #   end
+      #
+      #   # $ foo server
+      #   # starting server (code reloading: true)
+      #
+      #   # $ foo server --no-code-reloading
+      #   # starting server (code reloading: false)
+      #
+      #   # $ foo server --help
+      #   # # ...
+      #   #
+      #   # Options:
+      #   #   --[no]-code-reloading
+      #
+      # @example Aliases
+      #   require "dry/cli"
+      #
+      #   class Server < Dry::CLI::Command
+      #     param :port, aliases: ["-p"]
+      #
+      #     def call(options)
+      #       puts "staring server (port: #{options.fetch(:port, 2300)})"
+      #     end
+      #   end
+      #
+      #   # $ foo server
+      #   # starting server (port: 2300)
+      #
+      #   # $ foo server --port=2306
+      #   # starting server (port: 2306)
+      #
+      #   # $ foo server -p 2306
+      #   # starting server (port: 2306)
+      #
+      #   # $ foo server --help
+      #   # # ...
+      #   #
+      #   # Options:
+      #   #   --port=VALUE, -p VALUE
+      def self.option(name, options = {})
+        @options << Option.new(name, options)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.params
+        (@arguments + @options).uniq
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.default_params
+        params.each_with_object({}) do |param, result|
+          result[param.name] = param.default unless param.default.nil?
+        end
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.required_arguments
+        arguments.select(&:required?)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.optional_arguments
+        arguments.reject(&:required?)
+      end
+
+      extend Forwardable
+
+      delegate %i[
+        description
+        examples
+        arguments
+        options
+        params
+        default_params
+        required_arguments
+        optional_arguments
+      ] => 'self.class'
+
+      # @since 0.1.0
+      # @api private
+      attr_reader :command_name
+
+      # @since 0.1.0
+      # @api private
+      def initialize(command_name:, **)
+        @command_name = command_name
+      end
+    end
+  end
+end