hanami-cli 0.0.0 → 0.1.0.beta1

data/Rakefile

@@ -1,2 +1,19 @@
-require "bundler/gem_tasks"
-task :default => :spec
+require 'rake'
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+namespace :spec do
+  RSpec::Core::RakeTask.new(:unit) do |task|
+    file_list = FileList['spec/**/*_spec.rb']
+
+    task.pattern = file_list
+  end
+
+  task :coverage do
+    ENV['COVERAGE'] = 'true'
+    Rake::Task['spec:unit'].invoke
+  end
+end
+
+task default: 'spec:unit'

data/hanami-cli.gemspec

@@ -5,9 +5,10 @@ require 'hanami/cli/version'
 
 Gem::Specification.new do |spec|
   spec.name          = "hanami-cli"
-  spec.version       = Hanami::Cli::VERSION
+  spec.version       = Hanami::CLI::VERSION
   spec.authors       = ["Luca Guidi"]
   spec.email         = ["me@lucaguidi.com"]
+  spec.licenses      = ["MIT"]
 
   spec.summary       = "Hanami CLI"
   spec.description   = "Hanami framework to build command line interfaces with Ruby"
@@ -22,6 +23,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "hanami-utils",    "1.1.0.beta1"
+  spec.add_dependency "concurrent-ruby", "~> 1.0"
+
   spec.add_development_dependency "bundler", "~> 1.14"
   spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.5"
 end

data/lib/hanami/cli.rb

@@ -1,7 +1,123 @@
-require "hanami/cli/version"
-
+# Hanami
+#
+# @since 0.1.0
 module Hanami
-  module Cli
-    # Your code goes here...
+  # General purpose Command Line Interface (CLI) framework for Ruby
+  #
+  # @since 0.1.0
+  class CLI
+    require "hanami/cli/version"
+    require "hanami/cli/command"
+    require "hanami/cli/registry"
+    require "hanami/cli/parser"
+    require "hanami/cli/usage"
+    require "hanami/cli/banner"
+
+    # Check if command
+    #
+    # @param command [Object] the command to check
+    #
+    # @return [TrueClass,FalseClass] true if instance of `Hanami::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 [Hanami::CLI::Registry] a registry
+    #
+    # @return [Hanami::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)
+        command.call(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 [Hanami::CLI::CommandRegistry::LookupResult]
+    # @param out [IO] sta output
+    #
+    # @return [Array<Hanami: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) # rubocop:disable Metrics/MethodLength
+      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 [Hanami::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 `Hanami::CLI::Command`
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @see .command?
+    def command?(command)
+      CLI.command?(command)
+    end
   end
 end

data/lib/hanami/cli/banner.rb

@@ -0,0 +1,121 @@
+require "hanami/cli/program_name"
+
+module Hanami
+  class CLI
+    # Command banner
+    #
+    # @since 0.1.0
+    # @api private
+    module Banner
+      # Prints command banner
+      #
+      # @param command [Hanami::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")}"
+      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?
+        optional = optional_arguments.map { |arg| "[#{arg.name.upcase}]" }.join(' ') if optional_arguments.any?
+        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}"
+        end.join("\n")
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.extended_command_options(command)
+        result = command.options.map do |option|
+          name = 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?
+          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
+    end
+  end
+end

data/lib/hanami/cli/command.rb

@@ -0,0 +1,365 @@
+require "forwardable"
+require "hanami/cli/option"
+require "concurrent/array"
+
+module Hanami
+  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 "hanami/cli"
+      #
+      #   class Echo < Hanami::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 "hanami/cli"
+      #
+      #   class Server < Hanami::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 "hanami/cli"
+      #
+      #   class Hello < Hanami::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 "hanami/cli"
+      #
+      #   class Hello < Hanami::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 "hanami/cli"
+      #
+      #   module Generate
+      #     class Action < Hanami::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 "hanami/cli"
+      #
+      #   class Hello < Hanami::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 "hanami/cli"
+      #
+      #   class Console < Hanami::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 "hanami/cli"
+      #
+      #   class Console < Hanami::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 "hanami/cli"
+      #
+      #   class Console < Hanami::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 "hanami/cli"
+      #
+      #   class Server < Hanami::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 "hanami/cli"
+      #
+      #   class Server < Hanami::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