dry-cli 0.4.0

data/lib/dry/cli/program_name.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    # Program name
+    #
+    # @since 0.1.0
+    # @api private
+    module ProgramName
+      # @since 0.1.0
+      # @api private
+      SEPARATOR = ' '
+
+      # @since 0.1.0
+      # @api private
+      def self.call(names = [], program_name: $PROGRAM_NAME)
+        [File.basename(program_name), names].flatten.join(SEPARATOR)
+      end
+    end
+  end
+end

data/lib/dry/cli/registry.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+require 'dry/cli/command_registry'
+
+module Dry
+  class CLI
+    # Registry mixin
+    #
+    # @since 0.1.0
+    module Registry
+      # @since 0.1.0
+      # @api private
+      def self.extended(base)
+        base.class_eval do
+          @commands = CommandRegistry.new
+        end
+      end
+
+      # Register a command
+      #
+      # @param name [String] the command name
+      # @param command [NilClass,Dry::CLI::Command] the optional command
+      # @param aliases [Array<String>] an optional list of aliases
+      # @param options [Hash] a set of options
+      #
+      # @since 0.1.0
+      #
+      # @example Register a command
+      #   require "dry/cli"
+      #
+      #   module Foo
+      #     module Commands
+      #       extend Dry::CLI::Registry
+      #
+      #       class Hello < Dry::CLI::Command
+      #       end
+      #
+      #       register "hi", Hello
+      #     end
+      #   end
+      #
+      # @example Register a command with aliases
+      #   require "dry/cli"
+      #
+      #   module Foo
+      #     module Commands
+      #       extend Dry::CLI::Registry
+      #
+      #       class Hello < Dry::CLI::Command
+      #       end
+      #
+      #       register "hello", Hello, aliases: ["hi", "ciao"]
+      #     end
+      #   end
+      #
+      # @example Register a group of commands
+      #   require "dry/cli"
+      #
+      #   module Foo
+      #     module Commands
+      #       extend Dry::CLI::Registry
+      #
+      #       module Generate
+      #         class App < Dry::CLI::Command
+      #         end
+      #
+      #         class Action < Dry::CLI::Command
+      #         end
+      #       end
+      #
+      #       register "generate", aliases: ["g"] do |prefix|
+      #         prefix.register "app",    Generate::App
+      #         prefix.register "action", Generate::Action
+      #       end
+      #     end
+      #   end
+      def register(name, command = nil, aliases: [], **options)
+        if block_given?
+          yield Prefix.new(@commands, name, aliases)
+        else
+          @commands.set(name, command, aliases, **options)
+        end
+      end
+
+      # Register a before callback.
+      #
+      # @param command_name [String] the name used for command registration
+      # @param callback [Class, #call] the callback object. If a class is given,
+      #   it MUST respond to `#call`.
+      # @param blk [Proc] the callback espressed as a block
+      #
+      # @raise [Dry::CLI::UnknownCommandError] if the command isn't registered
+      # @raise [Dry::CLI::InvalidCallbackError] if the given callback doesn't
+      #   implement the required interface
+      #
+      # @since 0.2.0
+      #
+      # @example
+      #   require "dry/cli"
+      #
+      #   module Foo
+      #     module Commands
+      #       extend Dry::CLI::Registry
+      #
+      #       class Hello < Dry::CLI::Command
+      #         def call(*)
+      #           puts "hello"
+      #         end
+      #       end
+      #
+      #       register "hello", Hello
+      #       before "hello", -> { puts "I'm about to say.." }
+      #     end
+      #   end
+      #
+      # @example Register an object as callback
+      #   require "dry/cli"
+      #
+      #   module Callbacks
+      #     class Hello
+      #       def call(*)
+      #         puts "world"
+      #       end
+      #     end
+      #   end
+      #
+      #   module Foo
+      #     module Commands
+      #       extend Dry::CLI::Registry
+      #
+      #       class Hello < Dry::CLI::Command
+      #         def call(*)
+      #           puts "I'm about to say.."
+      #         end
+      #       end
+      #
+      #       register "hello", Hello
+      #       before "hello", Callbacks::Hello.new
+      #     end
+      #   end
+      #
+      # @example Register a class as callback
+      #   require "dry/cli"
+      #
+      #   module Callbacks
+      #     class Hello
+      #       def call(*)
+      #         puts "world"
+      #       end
+      #     end
+      #   end
+      #
+      #   module Foo
+      #     module Commands
+      #       extend Dry::CLI::Registry
+      #
+      #       class Hello < Dry::CLI::Command
+      #         def call(*)
+      #           puts "I'm about to say.."
+      #         end
+      #       end
+      #
+      #       register "hello", Hello
+      #       before "hello", Callbacks::Hello
+      #     end
+      #   end
+      def before(command_name, callback = nil, &blk)
+        command(command_name).before_callbacks.append(&_callback(callback, blk))
+      end
+
+      # Register an after callback.
+      #
+      # @param command_name [String] the name used for command registration
+      # @param callback [Class, #call] the callback object. If a class is given,
+      #   it MUST respond to `#call`.
+      # @param blk [Proc] the callback espressed as a block
+      #
+      # @raise [Dry::CLI::UnknownCommandError] if the command isn't registered
+      # @raise [Dry::CLI::InvalidCallbackError] if the given callback doesn't
+      #   implement the required interface
+      #
+      # @since 0.2.0
+      #
+      # @example
+      #   require "dry/cli"
+      #
+      #   module Foo
+      #     module Commands
+      #       extend Dry::CLI::Registry
+      #
+      #       class Hello < Dry::CLI::Command
+      #         def call(*)
+      #           puts "hello"
+      #         end
+      #       end
+      #
+      #       register "hello", Hello
+      #       after "hello", -> { puts "world" }
+      #     end
+      #   end
+      #
+      # @example Register an object as callback
+      #   require "dry/cli"
+      #
+      #   module Callbacks
+      #     class World
+      #       def call(*)
+      #         puts "world"
+      #       end
+      #     end
+      #   end
+      #
+      #   module Foo
+      #     module Commands
+      #       extend Dry::CLI::Registry
+      #
+      #       class Hello < Dry::CLI::Command
+      #         def call(*)
+      #           puts "hello"
+      #         end
+      #       end
+      #
+      #       register "hello", Hello
+      #       after "hello", Callbacks::World.new
+      #     end
+      #   end
+      #
+      # @example Register a class as callback
+      #   require "dry/cli"
+      #
+      #   module Callbacks
+      #     class World
+      #       def call(*)
+      #         puts "world"
+      #       end
+      #     end
+      #   end
+      #
+      #   module Foo
+      #     module Commands
+      #       extend Dry::CLI::Registry
+      #
+      #       class Hello < Dry::CLI::Command
+      #         def call(*)
+      #           puts "hello"
+      #         end
+      #       end
+      #
+      #       register "hello", Hello
+      #       after "hello", Callbacks::World
+      #     end
+      #   end
+      def after(command_name, callback = nil, &blk)
+        command(command_name).after_callbacks.append(&_callback(callback, blk))
+      end
+
+      # @since 0.1.0
+      # @api private
+      def get(arguments)
+        @commands.get(arguments)
+      end
+
+      private
+
+      COMMAND_NAME_SEPARATOR = ' '
+
+      # @since 0.2.0
+      # @api private
+      def command(command_name)
+        get(command_name.split(COMMAND_NAME_SEPARATOR)).tap do |result|
+          raise UnknownCommandError, command_name unless result.found?
+        end
+      end
+
+      # @since 0.2.0
+      # @api private
+      #
+      def _callback(callback, blk)
+        return blk if blk.respond_to?(:to_proc)
+
+        case callback
+        when ->(c) { c.respond_to?(:call) }
+          callback.method(:call)
+        when Class
+          begin
+            _callback(callback.new, blk)
+          rescue ArgumentError
+            raise InvalidCallbackError, callback
+          end
+        else
+          raise InvalidCallbackError, callback
+        end
+      end
+
+      # Command name prefix
+      #
+      # @since 0.1.0
+      class Prefix
+        # @since 0.1.0
+        # @api private
+        def initialize(registry, prefix, aliases)
+          @registry = registry
+          @prefix   = prefix
+
+          registry.set(prefix, nil, aliases)
+        end
+
+        # @since 0.1.0
+        #
+        # @see Dry::CLI::Registry#register
+        def register(name, command, aliases: [], **options)
+          command_name = "#{prefix} #{name}"
+          registry.set(command_name, command, aliases, **options)
+        end
+
+        private
+
+        # @since 0.1.0
+        # @api private
+        attr_reader :registry
+
+        # @since 0.1.0
+        # @api private
+        attr_reader :prefix
+      end
+    end
+  end
+end

data/lib/dry/cli/usage.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'dry/cli/program_name'
+
+module Dry
+  class CLI
+    # Command(s) usage
+    #
+    # @since 0.1.0
+    # @api private
+    module Usage
+      # @since 0.1.0
+      # @api private
+      SUBCOMMAND_BANNER = ' [SUBCOMMAND]'
+
+      # @since 0.1.0
+      # @api private
+      def self.call(result, out)
+        out.puts 'Commands:'
+        max_length, commands = commands_and_arguments(result)
+
+        commands.each do |banner, node|
+          usage = description(node.command) if node.leaf?
+          out.puts "#{justify(banner, max_length, usage)}#{usage}"
+        end
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.commands_and_arguments(result)
+        max_length = 0
+        ret        = commands(result).each_with_object({}) do |(name, node), memo|
+          args = if node.leaf?
+                   arguments(node.command)
+                 else
+                   SUBCOMMAND_BANNER
+                 end
+
+          partial       = "  #{command_name(result, name)}#{args}"
+          max_length    = partial.bytesize if max_length < partial.bytesize
+          memo[partial] = node
+        end
+
+        [max_length, ret]
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.arguments(command)
+        return unless CLI.command?(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.description(command)
+        return unless CLI.command?(command)
+
+        " # #{command.description}" unless command.description.nil?
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.justify(string, padding, usage)
+        return string.chomp(' ') if usage.nil?
+
+        string.ljust(padding + padding / 2)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.commands(result)
+        result.children.sort_by { |name, _| name }
+      end
+
+      # @since 0.1.0
+      # @api private
+      def self.command_name(result, name)
+        ProgramName.call([result.names, name])
+      end
+    end
+  end
+end

data/lib/dry/cli/utils/files.rb

@@ -0,0 +1,443 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'fileutils'
+
+module Dry
+  class CLI
+    module Utils
+      # Files utilities
+      #
+      # @since 0.3.1
+      module Files # rubocop:disable Metrics/ModuleLength
+        # Creates an empty file for the given path.
+        # All the intermediate directories are created.
+        # If the path already exists, it doesn't change the contents
+        #
+        # @param path [String,Pathname] the path to file
+        #
+        # @since 0.3.1
+        def self.touch(path)
+          mkdir_p(path)
+          FileUtils.touch(path)
+        end
+
+        # Creates a new file or rewrites the contents
+        # of an existing file for the given path and content
+        # All the intermediate directories are created.
+        #
+        # @param path [String,Pathname] the path to file
+        # @param content [String, Array<String>] the content to write
+        #
+        # @since 0.3.1
+        def self.write(path, *content)
+          mkdir_p(path)
+          open(path, ::File::CREAT | ::File::WRONLY | ::File::TRUNC, *content) # rubocop:disable LineLength, Security/Open - this isn't a call to `::Kernel.open`, but to `self.open`
+        end
+
+        # Copies source into destination.
+        # All the intermediate directories are created.
+        # If the destination already exists, it overrides the contents.
+        #
+        # @param source [String,Pathname] the path to the source file
+        # @param destination [String,Pathname] the path to the destination file
+        #
+        # @since 0.3.1
+        def self.cp(source, destination)
+          mkdir_p(destination)
+          FileUtils.cp(source, destination)
+        end
+
+        # Creates a directory for the given path.
+        # It assumes that all the tokens in `path` are meant to be a directory.
+        # All the intermediate directories are created.
+        #
+        # @param path [String,Pathname] the path to directory
+        #
+        # @since 0.3.1
+        #
+        # @see .mkdir_p
+        #
+        # @example
+        #   require "dry/cli/utils/files"
+        #
+        #   Dry::CLI::Utils::Files.mkdir("path/to/directory")
+        #     # => creates the `path/to/directory` directory
+        #
+        #   # WRONG this isn't probably what you want, check `.mkdir_p`
+        #   Dry::CLI::Utils::Files.mkdir("path/to/file.rb")
+        #     # => creates the `path/to/file.rb` directory
+        def self.mkdir(path)
+          FileUtils.mkdir_p(path)
+        end
+
+        # Creates a directory for the given path.
+        # It assumes that all the tokens, but the last, in `path` are meant to be
+        # a directory, whereas the last is meant to be a file.
+        # All the intermediate directories are created.
+        #
+        # @param path [String,Pathname] the path to directory
+        #
+        # @since 0.3.1
+        #
+        # @see .mkdir
+        #
+        # @example
+        #   require "dry/cli/utils/files"
+        #
+        #   Dry::CLI::Utils::Files.mkdir_p("path/to/file.rb")
+        #     # => creates the `path/to` directory, but NOT `file.rb`
+        #
+        #   # WRONG it doesn't create the last directory, check `.mkdir`
+        #   Dry::CLI::Utils::Files.mkdir_p("path/to/directory")
+        #     # => creates the `path/to` directory
+        def self.mkdir_p(path)
+          Pathname.new(path).dirname.mkpath
+        end
+
+        # Deletes given path (file).
+        #
+        # @param path [String,Pathname] the path to file
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        #
+        # @since 0.3.1
+        def self.delete(path)
+          FileUtils.rm(path)
+        end
+
+        # Deletes given path (directory).
+        #
+        # @param path [String,Pathname] the path to file
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        #
+        # @since 0.3.1
+        def self.delete_directory(path)
+          FileUtils.remove_entry_secure(path)
+        end
+
+        # Adds a new line at the top of the file
+        #
+        # @param path [String,Pathname] the path to file
+        # @param line [String] the line to add
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        #
+        # @see .append
+        #
+        # @since 0.3.1
+        def self.unshift(path, line)
+          content = ::File.readlines(path)
+          content.unshift("#{line}\n")
+
+          write(path, content)
+        end
+
+        # Adds a new line at the bottom of the file
+        #
+        # @param path [String,Pathname] the path to file
+        # @param contents [String] the contents to add
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        #
+        # @see .unshift
+        #
+        # @since 0.3.1
+        def self.append(path, contents)
+          mkdir_p(path)
+
+          content = ::File.readlines(path)
+          content << "\n" unless content.last.end_with?("\n")
+          content << "#{contents}\n"
+
+          write(path, content)
+        end
+
+        # Replace first line in `path` that contains `target` with `replacement`.
+        #
+        # @param path [String,Pathname] the path to file
+        # @param target [String,Regexp] the target to replace
+        # @param replacement [String] the replacement
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        # @raise [ArgumentError] if `target` cannot be found in `path`
+        #
+        # @see .replace_last_line
+        #
+        # @since 0.3.1
+        def self.replace_first_line(path, target, replacement)
+          content = ::File.readlines(path)
+          content[index(content, path, target)] = "#{replacement}\n"
+
+          write(path, content)
+        end
+
+        # Replace last line in `path` that contains `target` with `replacement`.
+        #
+        # @param path [String,Pathname] the path to file
+        # @param target [String,Regexp] the target to replace
+        # @param replacement [String] the replacement
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        # @raise [ArgumentError] if `target` cannot be found in `path`
+        #
+        # @see .replace_first_line
+        #
+        # @since 0.3.1
+        def self.replace_last_line(path, target, replacement)
+          content = ::File.readlines(path)
+          content[-index(content.reverse, path, target) - 1] = "#{replacement}\n"
+
+          write(path, content)
+        end
+
+        # Inject `contents` in `path` before `target`.
+        #
+        # @param path [String,Pathname] the path to file
+        # @param target [String,Regexp] the target to replace
+        # @param contents [String] the contents to inject
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        # @raise [ArgumentError] if `target` cannot be found in `path`
+        #
+        # @see .inject_line_after
+        # @see .inject_line_before_last
+        # @see .inject_line_after_last
+        #
+        # @since 0.3.1
+        def self.inject_line_before(path, target, contents)
+          _inject_line_before(path, target, contents, method(:index))
+        end
+
+        # Inject `contents` in `path` after last `target`.
+        #
+        # @param path [String,Pathname] the path to file
+        # @param target [String,Regexp] the target to replace
+        # @param contents [String] the contents to inject
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        # @raise [ArgumentError] if `target` cannot be found in `path`
+        #
+        # @see .inject_line_before
+        # @see .inject_line_after
+        # @see .inject_line_after_last
+        #
+        # @since 1.3.0
+        def self.inject_line_before_last(path, target, contents)
+          _inject_line_before(path, target, contents, method(:rindex))
+        end
+
+        # Inject `contents` in `path` after `target`.
+        #
+        # @param path [String,Pathname] the path to file
+        # @param target [String,Regexp] the target to replace
+        # @param contents [String] the contents to inject
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        # @raise [ArgumentError] if `target` cannot be found in `path`
+        #
+        # @see .inject_line_before
+        # @see .inject_line_before_last
+        # @see .inject_line_after_last
+        #
+        # @since 0.3.1
+        def self.inject_line_after(path, target, contents)
+          _inject_line_after(path, target, contents, method(:index))
+        end
+
+        # Inject `contents` in `path` after last `target`.
+        #
+        # @param path [String,Pathname] the path to file
+        # @param target [String,Regexp] the target to replace
+        # @param contents [String] the contents to inject
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        # @raise [ArgumentError] if `target` cannot be found in `path`
+        #
+        # @see .inject_line_before
+        # @see .inject_line_after
+        # @see .inject_line_before_last
+        # @see .inject_line_after_last
+        #
+        # @since 1.3.0
+        def self.inject_line_after_last(path, target, contents)
+          _inject_line_after(path, target, contents, method(:rindex))
+        end
+
+        # Removes line from `path`, matching `target`.
+        #
+        # @param path [String,Pathname] the path to file
+        # @param target [String,Regexp] the target to remove
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        # @raise [ArgumentError] if `target` cannot be found in `path`
+        #
+        # @since 0.3.1
+        def self.remove_line(path, target)
+          content = ::File.readlines(path)
+          i       = index(content, path, target)
+
+          content.delete_at(i)
+          write(path, content)
+        end
+
+        # Removes `target` block from `path`
+        #
+        # @param path [String,Pathname] the path to file
+        # @param target [String] the target block to remove
+        #
+        # @raise [Errno::ENOENT] if the path doesn't exist
+        # @raise [ArgumentError] if `target` cannot be found in `path`
+        #
+        # @since 0.3.1
+        #
+        # @example
+        #   require "dry/cli/utils/files"
+        #
+        #   puts File.read("app.rb")
+        #
+        #   # class App
+        #   #   configure do
+        #   #     root __dir__
+        #   #   end
+        #   # end
+        #
+        #   Dry::CLI::Utils::Files.remove_block("app.rb", "configure")
+        #
+        #   puts File.read("app.rb")
+        #
+        #   # class App
+        #   # end
+        def self.remove_block(path, target)
+          content  = ::File.readlines(path)
+          starting = index(content, path, target)
+          line     = content[starting]
+          size     = line[/\A[[:space:]]*/].bytesize
+          closing  = (' ' * size) + (target.match?(/{/) ? '}' : 'end')
+          ending   = starting + index(content[starting..-1], path, closing)
+
+          content.slice!(starting..ending)
+          write(path, content)
+
+          remove_block(path, target) if match?(content, target)
+        end
+
+        # Checks if `path` exist
+        #
+        # @param path [String,Pathname] the path to file
+        #
+        # @return [TrueClass,FalseClass] the result of the check
+        #
+        # @since 0.3.1
+        #
+        # @example
+        #   require "dry/cli/utils/files"
+        #
+        #   Dry::CLI::Utils::Files.exist?(__FILE__) # => true
+        #   Dry::CLI::Utils::Files.exist?(__dir__)  # => true
+        #
+        #   Dry::CLI::Utils::Files.exist?("missing_file") # => false
+        def self.exist?(path)
+          File.exist?(path)
+        end
+
+        # Checks if `path` is a directory
+        #
+        # @param path [String,Pathname] the path to directory
+        #
+        # @return [TrueClass,FalseClass] the result of the check
+        #
+        # @since 0.3.1
+        #
+        # @example
+        #   require "dry/cli/utils/files"
+        #
+        #   Dry::CLI::Utils::Files.directory?(__dir__)  # => true
+        #   Dry::CLI::Utils::Files.directory?(__FILE__) # => false
+        #
+        #   Dry::CLI::Utils::Files.directory?("missing_directory") # => false
+        def self.directory?(path)
+          File.directory?(path)
+        end
+
+        # private
+
+        # @since 0.3.1
+        # @api private
+        def self.match?(content, target)
+          !line_number(content, target).nil?
+        end
+
+        private_class_method :match?
+
+        # @since 0.3.1
+        # @api private
+        def self.open(path, mode, *content)
+          ::File.open(path, mode) do |file|
+            file.write(Array(content).flatten.join)
+          end
+        end
+
+        private_class_method :open
+
+        # @since 0.3.1
+        # @api private
+        def self.index(content, path, target)
+          line_number(content, target) ||
+            raise(ArgumentError, "Cannot find `#{target}' inside `#{path}'.")
+        end
+
+        private_class_method :index
+
+        # @since 1.3.0
+        # @api private
+        def self.rindex(content, path, target)
+          line_number(content, target, finder: content.method(:rindex)) ||
+            raise(ArgumentError, "Cannot find `#{target}' inside `#{path}'.")
+        end
+
+        private_class_method :rindex
+
+        # @since 1.3.0
+        # @api private
+        def self._inject_line_before(path, target, contents, finder)
+          content = ::File.readlines(path)
+          i       = finder.call(content, path, target)
+
+          content.insert(i, "#{contents}\n")
+          write(path, content)
+        end
+
+        private_class_method :_inject_line_before
+
+        # @since 1.3.0
+        # @api private
+        def self._inject_line_after(path, target, contents, finder)
+          content = ::File.readlines(path)
+          i       = finder.call(content, path, target)
+
+          content.insert(i + 1, "#{contents}\n")
+          write(path, content)
+        end
+
+        private_class_method :_inject_line_after
+
+        # @since 0.3.1
+        # @api private
+        def self.line_number(content, target, finder: content.method(:index))
+          finder.call do |l|
+            case target
+            when ::String
+              l.include?(target)
+            when Regexp
+              l =~ target
+            end
+          end
+        end
+
+        private_class_method :line_number
+      end
+    end
+  end
+end