command_kit 0.1.0.pre1

data/lib/command_kit/command.rb

@@ -0,0 +1,42 @@
+require 'command_kit/main'
+require 'command_kit/env'
+require 'command_kit/stdio'
+require 'command_kit/printing'
+require 'command_kit/usage'
+require 'command_kit/arguments'
+require 'command_kit/options'
+require 'command_kit/examples'
+require 'command_kit/description'
+require 'command_kit/exception_handler'
+
+module CommandKit
+  #
+  # The command class base-class.
+  #
+  # ## Examples
+  #
+  #     class MyCmd < CommandKit::Command
+  #     
+  #       # ...
+  #     
+  #     end
+  #
+  # @note Command classes are not required to inherit from {Command}. This class
+  # only exists as a convenience.
+  #
+  class Command
+
+    include Main
+    include Env
+    include Stdio
+    include Printing
+    include Help
+    include Usage
+    include Arguments
+    include Options
+    include Examples
+    include Description
+    include ExceptionHandler
+
+  end
+end

data/lib/command_kit/command_name.rb

@@ -0,0 +1,95 @@
+require 'command_kit/inflector'
+
+module CommandKit
+  #
+  # Defines or derives a command class'es command-name.
+  #
+  # ## Examples
+  #
+  # ### Implicit
+  #
+  #     class MyCmd
+  #
+  #       include CommandKit::CommandName
+  #
+  #     end
+  #
+  #     MyCmd.command_name
+  #     # => "my_cmd"
+  #
+  # ### Explicit
+  #
+  #     class MyCmd
+  #
+  #       include CommandKit::CommandName
+  #
+  #       commnad_name 'foo-cmd'
+  #
+  #     end
+  #
+  #     MyCmd.command_name
+  #     # => "foo-cmd"
+  #
+  module CommandName
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+      # {CommandName} is being included into a class or a module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {CommandName}.
+      #
+      def included(context)
+        super(context)
+
+        if context.class == Module
+          context.extend ModuleMethods
+        else
+          context.extend ClassMethods
+        end
+      end
+    end
+
+    extend ModuleMethods
+
+    #
+    # Defines class-level methods.
+    #
+    module ClassMethods
+      #
+      # Derives the command name from the class name.
+      #
+      # @param [String, nil] new_command_name
+      #   If given a command name argument, it will override the derived
+      #   command name.
+      #
+      # @return [String]
+      #
+      def command_name(new_command_name=nil)
+        if new_command_name
+          @command_name = new_command_name.to_s
+        else
+          @command_name || Inflector.underscore(Inflector.demodularize(name))
+        end
+      end
+    end
+
+    # The commands name.
+    #
+    # @return [String]
+    attr_reader :command_name
+
+    #
+    # Initializes command_name.
+    #
+    # @param [String] command_name
+    #   Overrides the command name. Defaults to
+    #   {ClassMethods#command_name self.class.command_name}.
+    #
+    def initialize(command_name: self.class.command_name, **kwargs)
+      @command_name = command_name
+
+      super(**kwargs)
+    end
+  end
+end

data/lib/command_kit/commands.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require 'command_kit/commands/subcommand'
+require 'command_kit/commands/parent_command'
+require 'command_kit/commands/help'
+require 'command_kit/command_name'
+require 'command_kit/usage'
+require 'command_kit/options'
+require 'command_kit/stdio'
+require 'command_kit/env'
+
+module CommandKit
+  #
+  # Adds sub-commands to a command.
+  #
+  # ## Examples
+  #
+  #     class CLI
+  #     
+  #       include CommandKit::Commands
+  #     
+  #       command_name :foo
+  #     
+  #       class Foo < CommandKit::Command
+  #         # ...
+  #       end
+  #     
+  #       class FooBar < CommandKit::Command
+  #         # ...
+  #       end
+  #     
+  #       command Foo
+  #       command 'foo-bar', FooBar
+  #     
+  #     end
+  #
+  module Commands
+    include CommandName
+    include Usage
+    include Options
+    include Stdio
+    include Env
+
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+      # {Commands} is being included into a class or a module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {Commands}.
+      #
+      def included(context)
+        super(context)
+
+        if context.class == Module
+          context.extend ModuleMethods
+        else
+          context.usage "[options] [COMMAND [ARGS...]]"
+          context.extend ClassMethods
+          context.command Help
+        end
+      end
+    end
+
+    extend ModuleMethods
+
+    #
+    # Class-level methods.
+    #
+    module ClassMethods
+      #
+      # The registered sub-commands.
+      #
+      # @return [Hash{String => Subcommand}]
+      #   The Hash of sub-command names and command classes.
+      # 
+      def commands
+        @commands ||= if superclass.kind_of?(ClassMethods)
+                         superclass.commands.dup
+                       else
+                         {}
+                       end
+      end
+
+      #
+      # The registered command aliases.
+      #
+      # @return [Hash{String => String}]
+      #   The Hash of command aliases to primary command names.
+      # 
+      def command_aliases
+        @command_aliases ||= if superclass.kind_of?(ClassMethods)
+                               superclass.command_aliases.dup
+                             else
+                               {}
+                             end
+      end
+
+      #
+      # Mounts a command as a sub-command.
+      #
+      # @param [#to_s] name
+      #   The optional name to mount the command as. Defaults to the command's
+      #   {CommandName::ClassMethods#command_name command_name}.
+      #
+      # @param [Class#main] command_class
+      #   The sub-command class.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Keyword arguments.
+      #
+      # @option kwargs [String, nil] summary
+      #   A short summary for the subcommand. Defaults to the first sentence
+      #   of the command.
+      #
+      # @option kwags [Array<String>] aliases
+      #   Optional alias names for the subcommand.
+      #
+      # @return [Subcommand]
+      #   The registered sub-command class.
+      #
+      # @example
+      #   command Foo
+      #
+      # @example
+      #   command 'foo-bar', FooBar
+      #
+      def command(name=nil, command_class, **kwargs)
+        name = if name then name.to_s
+               else         command_class.command_name
+               end
+
+        subcommand = Subcommand.new(command_class,**kwargs)
+
+        commands[name] = subcommand
+
+        subcommand.aliases.each do |command_alias|
+          command_aliases[command_alias] = name
+        end
+
+        return subcommand
+      end
+
+      #
+      # Gets the command.
+      #
+      # @param [String] name
+      #
+      # @return [Class#main, nil]
+      #
+      def get_command(name)
+        name = name.to_s
+        name = command_aliases.fetch(name,name)
+
+        if (subcommand = commands[name])
+          subcommand.command
+        end
+      end
+    end
+
+    def initialize(**kwargs)
+      super(**kwargs)
+
+      @option_parser.on(/^[^-].*$/) do |command|
+        OptionParser.terminate(command)
+      end
+    end
+
+    #
+    # Looks up the given command name and initializes a subcommand.
+    #
+    # @param [#to_s] name
+    #   The given command name.
+    #
+    # @return [Object#main, nil]
+    #   The initialized subcommand.
+    #
+    def command(name)
+      unless (command_class = self.class.get_command(name))
+        return
+      end
+
+      kwargs = {}
+
+      if command_class.include?(ParentCommand)
+        kwargs[:parent_command] = self
+      end
+
+      if command_class.include?(CommandName)
+        kwargs[:command_name] = "#{command_name} #{command_class.command_name}"
+      end
+
+      if command_class.include?(Stdio)
+        kwargs[:stdin]  = stdin
+        kwargs[:stdout] = stdout
+        kwargs[:stderr] = stderr
+      end
+
+      if command_class.include?(Env)
+        kwargs[:env] = env.dup
+      end
+
+      if command_class.include?(Options)
+        kwargs[:options] = options.dup
+      end
+
+      return command_class.new(**kwargs)
+    end
+
+    #
+    # Invokes the command with the given argv.
+    #
+    # @param [String] name
+    #   The name of the command to invoke.
+    #
+    # @param [Array<String>] argv
+    #   The additional arguments to pass to the command.
+    #
+    # @return [Integer]
+    #   The exit status of the command.
+    #
+    def invoke(name,*argv)
+      if (command = command(name))
+        command.main(argv)
+      else
+        on_unknown_command(name,argv)
+      end
+    end
+
+    #
+    # Prints an error about an unknown command and exits with an error code.
+    #
+    # @param [String] name
+    #
+    def command_not_found(name)
+      print_error "'#{name}' is not a #{command_name} command. See `#{command_name} help`"
+      exit(1)
+    end
+
+    #
+    # Place-holder method that is called when the subcommand is not known.
+    #
+    # @param [String] name
+    #   The given sub-command name.
+    #
+    # @param [Array<String>] argv
+    #   Additional argv.
+    #
+    # @abstract
+    #
+    # @see command_not_found
+    #
+    def on_unknown_command(name,argv=[])
+      command_not_found(name)
+    end
+
+    #
+    # Runs the command or specified subcommand.
+    #
+    # @note If no subcommand is given, {#help} will be called.
+    #
+    def run(command=nil,*argv)
+      if command
+        exit invoke(command,*argv)
+      else
+        help
+      end
+    end
+
+    #
+    # Prints the available commands and their summaries.
+    #
+    def help_commands
+      unless self.class.commands.empty?
+        puts
+        puts "Commands:"
+
+        self.class.commands.sort.each do |name,subcommand|
+          names = [name, *subcommand.aliases].join(', ')
+
+          if subcommand.summary
+            puts "    #{names}\t#{subcommand.summary}"
+          else
+            puts "    #{names}"
+          end
+        end
+      end
+    end
+
+    #
+    # Prints help information and available commands.
+    #
+    def help
+      super
+
+      help_commands
+    end
+  end
+end

data/lib/command_kit/commands/auto_load.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'command_kit/commands'
+require 'command_kit/commands/auto_load/subcommand'
+require 'command_kit/inflector'
+
+module CommandKit
+  module Commands
+    #
+    # Provides lazy-loading access to a directory / module namespace of
+    # command classes.
+    #
+    # ## Examples
+    #
+    #     class CLI
+    #     
+    #       include CommandKit::Commands::AutoLoad.new(
+    #         dir:       "#{__dir__}/cli/commands",
+    #         namespace: 'CLI::Commands'
+    #       )
+    #     
+    #     end
+    #
+    # ### Explicit Mapping
+    #
+    #     class CLI
+    #     
+    #       include CommandKit::Commands::AutoLoad.new(
+    #         dir:       "#{__dir__}/cli/commands",
+    #         namespace: 'CLI::Commands'
+    #       ) { |autoload|
+    #         autoload.command 'foo', 'Foo', 'foo.rb', summary: 'Foo command'
+    #         autoload.command 'bar', 'Bar', 'bar.rb', summary: 'Bar command'
+    #       }
+    #     
+    #     end
+    #
+    class AutoLoad < Module
+
+      # The auto-load subcommands.
+      #
+      # @return [Hash{String => Subcommand}]
+      attr_reader :commands
+
+      # The path to the directory containing the command files.
+      #
+      # @return [String]
+      attr_reader :dir
+
+      # The namespace that the will contain the command classes.
+      #
+      # @return [String]
+      attr_reader :namespace
+
+      #
+      # Initializes the namespace.
+      #
+      # @param [String] dir
+      #   The path to the directory containing the command files.
+      #
+      # @param [Module, Class, String] namespace
+      #   The namespace constant that contains the command classes.
+      #
+      # @yield [self]
+      #   If a block is given, it will be used to explicitly map the files
+      #   within {#dir} as commands.
+      #
+      def initialize(dir: , namespace: )
+        @commands  = {}
+
+        @dir       = dir
+        @namespace = namespace
+
+        if block_given?
+          yield self
+        else
+          files.each do |path|
+            base_name    = File.basename(path)
+            file_name    = base_name.chomp('.rb')
+            command_name = Inflector.dasherize(file_name)
+            class_name   = Inflector.camelize(file_name)
+
+            command command_name, class_name, base_name
+          end
+        end
+      end
+
+      #
+      # Defines an auto-loaded command mapping.
+      #
+      # @param [#to_s] name
+      #   The name of the command.
+      #
+      # @param [String] constant
+      #   The constant name of the command class.
+      #
+      # @param [String] file
+      #   The file name of the command class.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Keyword arguments.
+      #
+      # @option kwargs [String, nil] summary
+      #   An optional summary for the command.
+      #
+      # @option kwargs [Array<String>] aliases
+      #   Optional alias names for the subcommand.
+      #
+      def command(name, constant, file, **kwargs)
+        @commands[name.to_s] = Subcommand.new(
+          "#{@namespace}::#{constant}",
+          join(file),
+          **kwargs
+        )
+      end
+
+      #
+      # Joins a relative path with {#dir}.
+      #
+      # @param [String] path
+      #   The relative path.
+      #
+      # @return [String]
+      #   The joined absolute path.
+      #
+      def join(path)
+        File.join(@dir,path)
+      end
+
+      #
+      # Returns the files within given directory.
+      #
+      # @return [Array<String>]
+      #   The paths to the `.rb` files in the directory.
+      #
+      def files
+        Dir.glob(join('*.rb'))
+      end
+
+      #
+      # Includes {Commands} and registers all files within the namespace
+      # as lazy-loaded subcommands.
+      #
+      # @param [Class] command
+      #   The command class including {AutoLoad}.
+      #
+      def included(command)
+        command.include Commands
+        command.commands.merge!(@commands)
+      end
+    end
+  end
+end