command_kit 0.1.0.pre1

data/lib/command_kit/commands/auto_load/subcommand.rb

@@ -0,0 +1,90 @@
+require 'command_kit/commands/subcommand'
+
+module CommandKit
+  module Commands
+    class AutoLoad < Module
+      class Subcommand < Commands::Subcommand
+
+        # The fully qualified constant of the command class.
+        #
+        # @return [String]
+        attr_reader :constant
+
+        # The path to the file containing the command class.
+        #
+        # @return [String]
+        attr_reader :path
+
+        # A short summary for the sub-command.
+        #
+        # @return [String, nil]
+        attr_reader :summary
+
+        #
+        # Initializes the lazy-loaded subcommand.
+        #
+        # @param [String] path
+        #
+        # @param [String] constant
+        #
+        # @param [String, nil] summary
+        #   A short summary for the subcommand.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Keyword arguments.
+        #
+        # @option kwargs [Array<String>] aliases
+        #   Optional alias names for the subcommand.
+        #
+        def initialize(constant, path, summary: nil, **kwargs)
+          @constant = constant
+          @path     = path
+
+          super(nil, summary: summary, **kwargs)
+        end
+
+        #
+        # Requires the file.
+        #
+        # @return [Boolean]
+        #
+        def require!
+          require(@path)
+        end
+
+        #
+        # Resolves the {#constant} for the command class.
+        #
+        # @return [Class]
+        #   The command class.
+        #
+        # @raise [NameError]
+        #   The command class could not be found.
+        #
+        def const_get
+          Object.const_get("::#{@constant}",false)
+        end
+
+        #
+        # Lazy-loads the command class.
+        #
+        # @return [Class]
+        #   The command class.
+        #
+        # @raise [LoadError]
+        #   Could not load the given {#path}.
+        #
+        # @raise [NameError]
+        #   Could not resolve the {#constant} for the command class.
+        #
+        def command
+          @command ||= (
+            require!
+            const_get
+          )
+        end
+
+      end
+    end
+  end
+end

data/lib/command_kit/commands/auto_require.rb

@@ -0,0 +1,138 @@
+require 'command_kit/commands'
+require 'command_kit/commands/subcommand'
+require 'command_kit/inflector'
+
+module CommandKit
+  module Commands
+    #
+    # Adds a catch-all that attempts to load missing commands from a
+    # directory/namespace.
+    #
+    # ## Examples
+    #
+    #     module Foo
+    #       class CLI
+    #     
+    #         include CommandKit::Commands
+    #         include CommandKit::Commands::AutoRequire.new(
+    #           dir:       'foo/bar/commands',
+    #           namespace: 'Foo::CLI::Commands'
+    #         )
+    #     
+    #       end
+    #     end
+    #
+    class AutoRequire < Module
+
+      # The directory to attempt to require command files within.
+      #
+      # @return [String]
+      attr_reader :dir
+
+      # The namespace to lookup command classes within.
+      #
+      # @return [String]
+      attr_reader :namespace
+
+      #
+      # Initializes.
+      #
+      # @param [String] dir
+      #   The directory to require commands from.
+      #
+      # @param [String] namespace
+      #   The namespace to search for command classes in.
+      #
+      def initialize(dir: , namespace: )
+        @dir       = dir
+        @namespace = namespace
+      end
+
+      #
+      # Returns the path for the given command name.
+      #
+      # @param [String] name
+      #   The given command name.
+      #
+      # @return [String]
+      #   The path to the file that should contain the command.
+      #
+      def join(name)
+        File.join(@dir,name)
+      end
+
+      #
+      # Requires a file within the {#dir}.
+      #
+      # @param [String] file_name
+      #
+      # @return [Boolean]
+      #
+      # @raise [LoadError]
+      #
+      def require(file_name)
+        super(join(file_name))
+      end
+
+      #
+      # Resolves the constant for the command class within the {#namespace}.
+      #
+      # @param [String] constant
+      #   The constant name.
+      #
+      # @return [Class]
+      #   The command class.
+      #
+      # @raise [NameError]
+      #   The command class could not be found within the {#namespace}.
+      #
+      def const_get(constant)
+        Object.const_get("::#{@namespace}::#{constant}",false)
+      end
+
+      #
+      # Attempts to load the command from the {#dir} and {#namespace}.
+      #
+      # @param [String] command_name
+      #   The given command name.
+      #
+      # @return [Class, nil]
+      #   The command's class, or `nil` if the command cannot be loaded from
+      #   {#dir} or found within {#namespace}.
+      #
+      def command(command_name)
+        file_name = Inflector.underscore(command_name)
+
+        begin
+          require(file_name)
+        rescue LoadError
+          return
+        end
+
+        constant = Inflector.camelize(file_name)
+
+        begin
+          const_get(constant)
+        rescue NameError
+          return
+        end
+      end
+
+      #
+      # Includes {Commands} and adds a default proc to
+      # {Commands::ClassMethods#commands .commands}.
+      #
+      # @param [Class] command
+      #   The command class including {AutoRequire}.
+      #
+      def included(command)
+        command.include Commands
+        command.commands.default_proc = ->(hash,key) {
+          hash[key] = if (command_class = command(key))
+                        Commands::Subcommand.new(command_class)
+                      end
+        }
+      end
+    end
+  end
+end

data/lib/command_kit/commands/command.rb

@@ -0,0 +1,12 @@
+require 'command_kit/command'
+require 'command_kit/commands/parent_command'
+
+module CommandKit
+  module Commands
+    class Command < CommandKit::Command
+
+      include ParentCommand
+
+    end
+  end
+end

data/lib/command_kit/commands/help.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'command_kit/command'
+require 'command_kit/commands/parent_command'
+
+module CommandKit
+  module Commands
+    #
+    # The default help command.
+    #
+    class Help < Command
+
+      include ParentCommand
+
+      argument :command, desc: 'Command name to lookup'
+
+      #
+      # Prints the given commands `--help` output or lists registered commands.
+      #
+      # @param [String, nil] command
+      #   The given command name, or `nil` if no command name was given.
+      #
+      def run(command=nil)
+        case command
+        when nil
+          parent_command.help
+        else
+          if (subcommand = parent_command.command(command))
+            unless subcommand.respond_to?(:help)
+              raise(TypeError,"#{subcommand.inspect} must define a #help method")
+            end
+
+            subcommand.help
+          else
+            print_error "#{command_name}: unknown command: #{command}"
+            exit(1)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/command_kit/commands/parent_command.rb

@@ -0,0 +1,21 @@
+module CommandKit
+  module Commands
+    module ParentCommand
+
+      # The parent command instance.
+      #
+      # @return [Object<Commands>]
+      attr_reader :parent_command
+
+      #
+      # Initializes the command and sets {#parent_command}.
+      #
+      def initialize(parent_command: , **kwargs)
+        @parent_command = parent_command
+
+        super(**kwargs)
+      end
+
+    end
+  end
+end

data/lib/command_kit/commands/subcommand.rb

@@ -0,0 +1,51 @@
+module CommandKit
+  module Commands
+    class Subcommand
+
+      # The command class.
+      #
+      # @return [Class]
+      attr_reader :command
+
+      # A short summary for the subcommand.
+      #
+      # @return [String, nil]
+      attr_reader :summary
+
+      # Optional alias names for the subcommand.
+      #
+      # @return [Array<String>]
+      attr_reader :aliases
+
+      #
+      # Initializes the subcommand.
+      #
+      # @param [Class] command
+      #   The command class.
+      #
+      # @param [String, nil] summary
+      #   A short summary for the subcommand. Defaults to the first sentence
+      #   of the command.
+      #
+      # @param [Array<String>] aliases
+      #   Optional alias names for the subcommand.
+      #
+      def initialize(command, summary: self.class.summary(command),
+                                   aliases: [])
+        @command = command
+        @summary = summary
+        @aliases = aliases.map(&:to_s)
+      end
+
+      def self.summary(command)
+        if command.respond_to?(:description)
+          if (desc = command.description)
+            # extract the first sentence
+            desc[/^[^\.]+/]
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/command_kit/console.rb

@@ -0,0 +1,141 @@
+require 'command_kit/stdio'
+require 'command_kit/env'
+
+begin
+  require 'io/console'
+rescue LoadError
+end
+
+module CommandKit
+  #
+  # Provides access to [IO.console] and [IO.console_size].
+  #
+  # ## Environment Variables
+  #
+  # * `LINES` - The explicit number of lines or rows the console should have.
+  # * `COLUMNS` - The explicit number of columns the console should have.
+  #
+  # [IO.console]: https://rubydoc.info/gems/io-console/IO#console-class_method
+  # [IO#winsize]: https://rubydoc.info/gems/io-console/IO#winsize-instance_method
+  #
+  module Console
+    include Stdio
+    include Env
+
+    # The default console height to fallback to.
+    DEFAULT_HEIGHT = 25
+
+    # The default console width to fallback to.
+    DEFAULT_WIDTH = 80
+
+    #
+    # Initializes any console settings.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @note
+    #   If the `$LINES` env variable is set, and is non-zero, it will be
+    #   returned by {#console_height}.
+    #
+    # @note
+    #   If the `$COLUMNS` env variable is set, and is non-zero, it will be
+    #   returned by {#console_width}.
+    #
+    def initialize(**kwargs)
+      super(**kwargs)
+
+      @default_console_height = if (lines = env['LINES'])
+                                  lines.to_i
+                                else
+                                  DEFAULT_HEIGHT
+                                end
+
+      @default_console_width  = if (columns = env['COLUMNS'])
+                                  columns.to_i
+                                else
+                                  DEFAULT_WIDTH
+                                end
+    end
+
+    #
+    # Determines if there is a console present.
+    #
+    # @return [Boolean]
+    #   Specifies whether {Stdio#stdout stdout} is connected to a console.
+    #
+    def console?
+      IO.respond_to?(:console) && stdout.tty?
+    end
+
+    #
+    # Returns the console object, if {Stdio#stdout stdout} is connected to a
+    # console.
+    #
+    # @return [IO, nil]
+    #   The IO objects or `nil` if {Stdio#stdout stdout} is not connected to a
+    #   console.
+    #
+    # @example
+    #   console
+    #   # => #<File:/dev/tty>
+    #
+    def console
+      IO.console if console?
+    end
+
+    #
+    # Returns the console's height in number of lines.
+    #
+    # @return [Integer]
+    #   The console's height in number of lines.
+    #
+    # @example
+    #   console_height
+    #   # => 22
+    #
+    def console_height
+      if (console = self.console)
+        console.winsize[0]
+      else
+        @default_console_height
+      end
+    end
+
+    #
+    # Returns the console's width in number of lines.
+    #
+    # @return [Integer]
+    #   The console's width in number of columns.
+    #
+    # @example
+    #   console_width
+    #   # => 91
+    #
+    def console_width
+      if (console = self.console)
+        console.winsize[1]
+      else
+        @default_console_width
+      end
+    end
+
+    #
+    # The console height (lines) and width (columns).
+    #
+    # @return [(Integer, Integer)]
+    #   Returns the height and width of the console.
+    #
+    # @example
+    #   console_size
+    #   # => [23, 91]
+    #
+    def console_size
+      if (console = self.console)
+        console.winsize
+      else
+        [@default_console_height, @default_console_width]
+      end
+    end
+  end
+end