command_kit 0.1.0.pre1

data/lib/command_kit/description.rb

@@ -0,0 +1,89 @@
+require 'command_kit/help'
+
+module CommandKit
+  #
+  # Allows adding a description to a command's class.
+  #
+  # ## Examples
+  #
+  #     include CommandKit::Description
+  #
+  #     description "Does things and stuff"
+  #
+  module Description
+    include Help
+
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+      # {Description} is being included into a class or a module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {Description}.
+      #
+      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
+      #
+      # Gets or sets the description string.
+      #
+      # @param [String, nil] new_description
+      #   If a String is given, the class'es description will be set.
+      #
+      # @return [String, nil]
+      #   The class'es or superclass'es description.
+      #
+      # @example
+      #   description "Does things and stuff"
+      #
+      def description(new_description=nil)
+        if new_description
+          @description = new_description
+        else
+          @description || (superclass.description if superclass.kind_of?(ClassMethods))
+        end
+      end
+    end
+
+    #
+    # @see ClassMethods#description
+    #
+    def description
+      self.class.description
+    end
+
+    #
+    # Prints the {ClassMethods#description description}, if set.
+    #
+    def help_description
+      if (description = self.description)
+        puts
+        puts description
+      end
+    end
+
+    #
+    # Calls the superclass'es `#help` method, if it's defined, then calls
+    # {#help_description}.
+    #
+    def help
+      super if defined?(super)
+
+      help_description
+    end
+  end
+end

data/lib/command_kit/env.rb

@@ -0,0 +1,43 @@
+module CommandKit
+  #
+  # Provides access to environment variables.
+  #
+  # ## Examples
+  #
+  #     class MyCmd
+  #       include CommandKit::Env
+  #
+  #       def main
+  #         home = env['HOME']
+  #         # ...
+  #       end
+  #     end
+  #
+  # ## Testing
+  #
+  # Can be initialized with a custom `env` hash for testing purposes.
+  #
+  #     MyCmd.new(env: {...})
+  #
+  module Env
+    # The environment variables hash.
+    #
+    # @return [Hash{String => String}]
+    attr_reader :env
+
+    #
+    # Initializes {#env}.
+    #
+    # @param [Hash{String => String}] env
+    #   The given environment for the command. Defaults to the global `ENV`.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    def initialize(env: ENV, **kwargs)
+      @env = env
+
+      super(**kwargs)
+    end
+  end
+end

data/lib/command_kit/env/home.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'command_kit/env'
+
+module CommandKit
+  module Env
+    #
+    # Provides access to the `HOME` environment variable.
+    #
+    # ## Environment Variables
+    #
+    # * `HOME` - The absolute path to the user's home directory.
+    #
+    module Home
+      include Env
+
+      module ModuleMethods
+        #
+        # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+        # {Env::Home} is being included into a class or a module..
+        #
+        # @param [Class, Module] context
+        #   The class or module which is including {Home}.
+        #
+        def included(context)
+          super(context)
+
+          if context.class == Module
+            context.extend ModuleMethods
+          else
+            context.extend ClassMethods
+          end
+        end
+      end
+
+      extend ModuleMethods
+
+      #
+      # Class-level methods.
+      #
+      module ClassMethods
+        #
+        # The default home directory.
+        #
+        # @return [String]
+        #
+        def home_dir
+          Gem.user_home
+        end
+      end
+
+      # The home directory.
+      #
+      # @return [String]
+      attr_reader :home_dir
+
+      #
+      # Initializes {#home_dir} to either `env['HOME']` or
+      # {ClassMethods#home_dir self.class.home_dir}.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
+      #
+      def initialize(**kwargs)
+        super(**kwargs)
+
+        @home_dir = env.fetch('HOME') { self.class.home_dir }
+      end
+    end
+  end
+end

data/lib/command_kit/env/path.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'command_kit/env'
+
+module CommandKit
+  module Env
+    #
+    # Provides access to the `PATH` environment variable.
+    #
+    # ## Environment Variables
+    #
+    # * `PATH` - The list of directories to search for commands within.
+    #
+    module Path
+      include Env
+
+      # The home directory.
+      #
+      # @return [String]
+      attr_reader :path_dirs
+
+      #
+      # Initializes {#path_dirs} using `env['PATH']`.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
+      #
+      def initialize(**kwargs)
+        super(**kwargs)
+
+        @path_dirs = env.fetch('PATH','').split(File::PATH_SEPARATOR)
+      end
+
+      #
+      # Searches for the command in {#path_dirs}.
+      #
+      # @param [String, Symbol] name
+      #   The command name.
+      #
+      # @return [String, nil]
+      #   The absolute path to the executable file, or `nil` if the command
+      #   could not be found in any of the {#path_dirs}.
+      #
+      def find_command(name)
+        name = name.to_s
+
+        @path_dirs.each do |dir|
+          file = File.join(dir,name)
+
+          return file if File.file?(file) && File.executable?(file)
+        end
+
+        return nil
+      end
+
+      #
+      # Determines if the command is present on the system.
+      #
+      # @param [String, Symbol] name
+      #   The command name.
+      #
+      # @return [Boolean]
+      #   Specifies whether a command with the given name exists in one of the
+      #   {#path_dirs}.
+      #
+      def command_installed?(name)
+        !find_command(name).nil?
+      end
+    end
+  end
+end

data/lib/command_kit/examples.rb

@@ -0,0 +1,99 @@
+require 'command_kit/help'
+require 'command_kit/command_name'
+
+module CommandKit
+  #
+  # Allows defining example commands for the command class.
+  #
+  # ## Examples
+  #
+  #     include CommandKit::Examples
+  #     
+  #     examples [
+  #       "my_cmd -o output.txt  path/to/file"
+  #     ]
+  #
+  module Examples
+    include Help
+    include CommandName
+
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+      # {Examples} is being included into a class or a module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {Examples}.
+      #
+      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
+      #
+      # Gets or sets the example commands.
+      #
+      # @param [Array<String>, String, nil] new_examples
+      #   If a String or Array of Strings is given, it will set the class'es
+      #   example commands.
+      #
+      # @return [Array<String>, nil]
+      #   The class'es or superclass'es example commands.
+      #
+      # @example
+      #   examples [
+      #     "-o output.txt path/to/file"
+      #   ]
+      #   
+      def examples(new_examples=nil)
+        if new_examples
+          @examples = Array(new_examples)
+        else
+          @examples || (superclass.examples if superclass.kind_of?(ClassMethods))
+        end
+      end
+    end
+
+    #
+    # @see ClassMethods#examples
+    #
+    def examples
+      self.class.examples
+    end
+
+    #
+    # Prints the command class'es example commands.
+    #
+    def help_examples
+      if (examples = self.examples)
+        puts
+        puts "Examples:"
+        examples.each do |command|
+          puts "    #{command_name} #{command}"
+        end
+      end
+    end
+
+    #
+    # Calls the superclass'es `#help` method, if it's defined, then calls
+    # {#help_examples}.
+    #
+    def help
+      super if defined?(super)
+
+      help_examples
+    end
+  end
+end

data/lib/command_kit/exception_handler.rb

@@ -0,0 +1,55 @@
+require 'command_kit/main'
+require 'command_kit/printing'
+
+module CommandKit
+  #
+  # Adds exception handling and printing.
+  #
+  # ## Examples
+  #
+  #     include CommandKit::Main
+  #     include CommandKit::ExceptionHandler
+  #
+  # ### Custom Exception Handling
+  #
+  #     include CommandKit::Main
+  #     include CommandKit::ExceptionHandler
+  #     
+  #     def on_exception(error)
+  #       print_error "error: #{error.message}"
+  #       exit(1)
+  #     end
+  #
+  module ExceptionHandler
+    include Printing
+
+    #
+    # Calls superclass'es `#main` method, but rescues any uncaught exceptions
+    # and passes them to {#on_exception}.
+    #
+    # @param [Array<String>] argv
+    #   The given arguments Array.
+    #
+    # @return [Integer]
+    #   The exit status of the command.
+    #
+    def main(argv=[])
+      super(argv)
+    rescue Interrupt, Errno::EPIPE => error
+      raise(error)
+    rescue Exception => error
+      on_exception(error)
+    end
+
+    #
+    # Default method for handling when an exception is raised by `#main`.
+    #
+    # @param [Exception] error
+    #   The raised exception.
+    #
+    def on_exception(error)
+      print_exception(error)
+      exit(1)
+    end
+  end
+end

data/lib/command_kit/help.rb

@@ -0,0 +1,62 @@
+module CommandKit
+  #
+  # Defines a place-holder {Help#help help} method.
+  #
+  # ## Examples
+  #
+  #     class MyCmd
+  #       include CommandKit::Help
+  #     
+  #       def help
+  #         puts "..."
+  #       end
+  #     end
+  #     
+  #     MyCmd.help
+  #
+  module Help
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether {Help}
+      # is being included into a class or a module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is extending {ClassMethods}.
+      #
+      def included(context)
+        super(context)
+
+        if context.class == Module
+          context.extend ModuleMethods
+        else
+          context.extend ClassMethods
+        end
+      end
+    end
+
+    extend ModuleMethods
+
+    module ClassMethods
+      #
+      # Prints `--help` information.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments for `#initialize`.
+      #
+      # @see Help#help
+      #
+      def help(**kwargs)
+        new(**kwargs).help
+      end
+    end
+
+    #
+    # Prints `--help` information.
+    #
+    # @abstract
+    #
+    def help
+      super if defined?(super)
+    end
+  end
+end