command_kit 0.1.0.pre1

data/gemspec.yml

@@ -0,0 +1,14 @@
+name: command_kit
+summary: A toolkit for building Ruby CLI commands
+description:
+  A Ruby toolkit for building clean, correct, and robust CLI commands as
+  Ruby classes.
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://github.com/postmodern/command_kit#readme
+
+required_ruby_version: ">= 2.7.0"
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/command_kit.rb

@@ -0,0 +1 @@
+require 'command_kit/version'

data/lib/command_kit/arguments.rb

@@ -0,0 +1,161 @@
+require 'command_kit/help'
+require 'command_kit/arguments/argument'
+
+module CommandKit
+  #
+  # Provides a thin DSL for defining arguments as attributes.
+  #
+  # ## Examples
+  #
+  #     include CommandKit::Arguments
+  #     
+  #     argument :output, type: String,
+  #                       desc: 'The output file'
+  #     
+  #     argument :input, type: Array,
+  #                      desc: 'The input file(s)'
+  #
+  module Arguments
+    include Help
+
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+      # {Arguments} is being included into a class or module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {Arguments}.
+      #
+      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
+      #
+      # All defined arguments for the class.
+      #
+      # @return [Hash{Symbol => Argument}]
+      #   The defined argument for the class and it's superclass.
+      #
+      def arguments
+        @arguments ||= if superclass.kind_of?(ClassMethods)
+                         superclass.arguments.dup
+                       else
+                         {}
+                       end
+      end
+
+      #
+      # Defines an argument for the class.
+      #
+      # @param [Symbol] name
+      #   The argument name.
+      #
+      # @yield [(arg)]
+      #   If a block is given, it will be passed the parsed argument.
+      #
+      # @yieldparam [Object, nil] arg
+      #   The parsed argument.
+      #
+      # @return [Argument]
+      #   The newly defined argument.
+      #
+      # @example Define an argument:
+      #     argument :bar, desc: "Bar argument"
+      #
+      # @example With a custom usage string:
+      #     option :bar, usage: 'BAR',
+      #                  desc: "Bar argument"
+      #
+      # @example With a custom block:
+      #     argument :bar, desc: "Bar argument" do |bar|
+      #       # ...
+      #     end
+      #
+      # @example With a custom type:
+      #     argument :bar, type: Integer,
+      #                    desc: "Bar argument"
+      #
+      # @example With a default value:
+      #     argument :bar, default: "bar.txt",
+      #                    desc: "Bar argument"
+      #
+      # @example An optional argument:
+      #     argument :bar, required: true,
+      #                    desc: "Bar argument"
+      #
+      # @example A repeating argument:
+      #     argument :bar, repeats: true,
+      #                    desc: "Bar argument"
+      #
+      def argument(name,**kwargs,&block)
+        arguments[name] = Argument.new(name,**kwargs,&block)
+      end
+    end
+
+    #
+    # Checks the minimum/maximum number of arguments, then calls the
+    # superclass'es `#main`.
+    #
+    # @param [Array<String>] argv
+    #   The arguments passed to the program.
+    #
+    # @return [Integer]
+    #   The exit status code. If too few or too many arguments are given, then
+    #   an error message is printed and `1` is returned.
+    #
+    def main(argv=[])
+      required_args   = self.class.arguments.each_value.count(&:required?)
+      optional_args   = self.class.arguments.each_value.count(&:optional?)
+      has_repeats_arg = self.class.arguments.each_value.any?(&:repeats?)
+
+      if argv.length < required_args
+        print_error("insufficient number of arguments.")
+        help_usage
+        return 1
+      elsif argv.length > (required_args + optional_args) && !has_repeats_arg
+        print_error("too many arguments given")
+        help_usage
+        return 1
+      end
+
+      super(argv)
+    end
+
+    #
+    # Prints any defined arguments, along with the usual `--help` information.
+    #
+    def help_arguments
+      unless (arguments = self.class.arguments).empty?
+        puts
+        puts 'Arguments:'
+
+        self.class.arguments.each_value do |arg|
+          puts "    #{arg.usage.ljust(33)}#{arg.desc}"
+        end
+      end
+    end
+
+    #
+    # Calls the superclass'es `#help` method, if it's defined, then calls
+    # {#help_arguments}.
+    #
+    def help
+      super if defined?(super)
+
+      help_arguments
+    end
+  end
+end

data/lib/command_kit/arguments/argument.rb

@@ -0,0 +1,111 @@
+require 'command_kit/arguments/argument_value'
+
+module CommandKit
+  module Arguments
+    #
+    # Represents a defined argument.
+    #
+    class Argument < ArgumentValue
+
+      # @return [Symbol]
+      attr_reader :name
+
+      # @return [Boolean]
+      attr_reader :repeats
+
+      # @return [String, nil]
+      attr_reader :desc
+
+      # @return [Regexp, nil]
+      attr_reader :pattern
+
+      # @return [Proc, nil]
+      attr_reader :parser
+
+      # @return [Proc, nil]
+      attr_reader :block
+
+      #
+      # Initializes the argument.
+      #
+      # @param [Symbol] name
+      #
+      # @param [Class, Hash, Array, Regexp] type
+      #
+      # @param [String, nil] usage
+      #
+      # @param [Object, Proc, nil] default
+      #
+      # @param [Boolean] required
+      #
+      # @param [Boolean] repeats
+      #
+      # @param [String] desc
+      #
+      # @note `usage` will be assigned a default value based on `type` and
+      # `name`.
+      #
+      # @yield [(value)]
+      #
+      # @yieldparam [Object, nil] value
+      #
+      def initialize(name, type:     String,
+                           usage:    name.to_s.upcase,
+                           default:  nil,
+                           required: true,
+                           repeats:  false,
+                           desc:     ,
+                           &block)
+        super(
+          type:     type,
+          usage:    usage,
+          default:  default,
+          required: required
+        )
+
+        @name    = name
+        @repeats = repeats
+        @desc    = desc
+
+        @pattern, @parser = self.class.parser(@type)
+
+        @block = block
+      end
+
+      #
+      # Looks up the option parser for the given `OptionParser` type.
+      #
+      # @param [Class] type
+      #   The `OptionParser` type class.
+      #
+      # @return [(Regexp, Proc), nil]
+      #   The matching pattern and converter proc.
+      #
+      def self.parser(type)
+        OptionParser::DefaultList.search(:atype,type)
+      end
+
+      #
+      # Specifies whether the argument can be repeated repeat times.
+      #
+      # @return [Boolean]
+      #
+      def repeats?
+        @repeats
+      end
+
+      #
+      # The usage string for the argument.
+      #
+      # @return [String]
+      #
+      def usage
+        string = @usage
+        string = "#{string} ..." if repeats?
+        string = "[#{string}]" if optional?
+        string
+      end
+
+    end
+  end
+end

data/lib/command_kit/arguments/argument_value.rb

@@ -0,0 +1,81 @@
+module CommandKit
+  module Arguments
+    #
+    # Represents an individual argument value.
+    #
+    class ArgumentValue
+
+      # The desired type of the argument value.
+      #
+      # @return [Class, Hash, Array, Regexp, nil]
+      attr_reader :type
+
+      # The default parsed value for the argument value.
+      #
+      # @return [Object, Proc, nil]
+      attr_reader :default
+
+      # Specifies whether the argument value is required or optional.
+      #
+      # @return [Boolean]
+      attr_reader :required
+
+      # The usage string to describe the argument value.
+      #
+      # @return [String]
+      attr_reader :usage
+
+      #
+      # Initializes the argument value.
+      #
+      # @param [Class, Hash, Array, Regexp] type
+      #   The type of the argument value.
+      #
+      # @param [Boolean] required
+      #   Specifies whether the argument value is required or optional.
+      #
+      # @param [String] usage
+      #   The usage string to represent the argument value.
+      #
+      # @param [Object, Proc, nil] default
+      #   The default parsed value for the argument value.
+      #
+      def initialize(type: nil, required: true, default: nil, usage: )
+        @type     = type
+        @required = required
+        @default  = default
+        @usage    = usage
+      end
+
+      #
+      # Determines if the argument is required or not.
+      #
+      # @return [Boolean]
+      #
+      def required?
+        @required
+      end
+
+      #
+      # Determines whether the argument can be omitted.
+      #
+      # @return [Boolean]
+      #
+      def optional?
+        !@required
+      end
+
+      #
+      # Returns a new default value.
+      #
+      # @return [Object]
+      #
+      def default_value
+        if @default.respond_to?(:call) then @default.call
+        else                                @default.dup
+        end
+      end
+
+    end
+  end
+end

data/lib/command_kit/arguments/usage.rb

@@ -0,0 +1,6 @@
+module CommandKit
+  module Arguments
+    module Usage
+    end
+  end
+end

data/lib/command_kit/colors.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require 'command_kit/stdio'
+require 'command_kit/env'
+
+module CommandKit
+  #
+  # Defines ANSI color codes.
+  #
+  # ## Examples
+  #
+  #     include CommandKit::Colors
+  #
+  #     def run
+  #       puts colors.green("hello world")
+  #     end
+  #
+  # ### Printing color error messages
+  #
+  #     stderr.puts colors(stderr).red("error!")
+  #
+  # ## Environment Variables
+  #
+  # * `TERM` - Specifies the type of terminal. When set to `DUMB`, it will
+  #   disable color output.
+  #
+  # ## Alternatives
+  #
+  # * [ansi](http://rubyworks.github.io/ansi/)
+  # * [colorize](https://github.com/fazibear/colorize#readme)
+  #
+  # @see https://en.wikipedia.org/wiki/ANSI_escape_code
+  #
+  module Colors
+
+    include Stdio
+    include Env
+
+    #
+    # Applies ANSI formatting to text.
+    #
+    module ANSI
+      # ANSI reset code
+      RESET = "\e[0m"
+
+      # @see RESET
+      CLEAR = RESET
+
+      # ANSI code for bold text
+      BOLD = "\e[1m"
+
+      # ANSI code to disable boldness
+      RESET_INTENSITY = "\e[22m"
+
+      # ANSI color code for black
+      BLACK = "\e[30m"
+
+      # ANSI color code for red
+      RED = "\e[31m"
+
+      # ANSI color code for green
+      GREEN = "\e[32m"
+
+      # ANSI color code for yellow
+      YELLOW = "\e[33m"
+
+      # ANSI color code for blue
+      BLUE = "\e[34m"
+
+      # ANSI color code for megenta
+      MAGENTA = "\e[35m"
+
+      # ANSI color code for cyan
+      CYAN = "\e[36m"
+
+      # ANSI color code for white
+      WHITE = "\e[37m"
+
+      # ANSI color for the default foreground color
+      RESET_COLOR = "\e[39m"
+
+      module_function
+
+      #
+      # Resets text formatting.
+      #
+      # @return [RESET]
+      #
+      # @see RESET
+      #
+      def reset
+        RESET
+      end
+
+      #
+      # @see reset
+      #
+      def clear
+        reset
+      end
+
+      #
+      # Bolds the text.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, BOLD]
+      #   The bolded string or just {BOLD} if no arguments were given.
+      #
+      # @see BOLD
+      #
+      def bold(string=nil)
+        if string then "#{BOLD}#{string}#{RESET_INTENSITY}"
+        else           BOLD
+        end
+      end
+
+      #
+      # Sets the text color to black.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, BLACK]
+      #   The colorized string or just {BLACK} if no arguments were given.
+      #
+      # @see BLACK
+      #
+      def black(string=nil)
+        if string then "#{BLACK}#{string}#{RESET_COLOR}"
+        else           BLACK
+        end
+      end
+
+      #
+      # Sets the text color to red.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, RED]
+      #   The colorized string or just {RED} if no arguments were given.
+      #
+      # @see RED
+      #
+      def red(string=nil)
+        if string then "#{RED}#{string}#{RESET_COLOR}"
+        else           RED
+        end
+      end
+
+      #
+      # Sets the text color to green.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, GREEN]
+      #   The colorized string or just {GREEN} if no arguments were given.
+      #
+      # @see GREEN
+      #
+      def green(string=nil)
+        if string then "#{GREEN}#{string}#{RESET_COLOR}"
+        else           GREEN
+        end
+      end
+
+      #
+      # Sets the text color to yellow.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, YELLOW]
+      #   The colorized string or just {YELLOW} if no arguments were given.
+      #
+      # @see YELLOW
+      #
+      def yellow(string=nil)
+        if string then "#{YELLOW}#{string}#{RESET_COLOR}"
+        else           YELLOW
+        end
+      end
+
+      #
+      # Sets the text color to blue.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, BLUE]
+      #   The colorized string or just {BLUE} if no arguments were given.
+      #
+      # @see BLUE
+      #
+      def blue(string=nil)
+        if string then "#{BLUE}#{string}#{RESET_COLOR}"
+        else           BLUE
+        end
+      end
+
+      #
+      # Sets the text color to magenta.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, MAGENTA]
+      #   The colorized string or just {MAGENTA} if no arguments were given.
+      #
+      # @see MAGENTA
+      #
+      def magenta(string=nil)
+        if string then "#{MAGENTA}#{string}#{RESET_COLOR}"
+        else           MAGENTA
+        end
+      end
+
+      #
+      # Sets the text color to cyan.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, CYAN]
+      #   The colorized string or just {CYAN} if no arguments were given.
+      #
+      # @see CYAN
+      #
+      def cyan(string=nil)
+        if string then "#{CYAN}#{string}#{RESET_COLOR}"
+        else           CYAN
+        end
+      end
+
+      #
+      # Sets the text color to white.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, WHITE]
+      #   The colorized string or just {WHITE} if no arguments were given.
+      #
+      # @see WHITE
+      #
+      def white(string=nil)
+        if string then "#{WHITE}#{string}#{RESET_COLOR}"
+        else           WHITE
+        end
+      end
+    end
+
+    #
+    # Dummy module with the same interface as {ANSI}, but for when ANSI is not
+    # supported.
+    #
+    module PlainText
+      RESET = \
+        CLEAR = \
+        BOLD = \
+        RESET_INTENSITY = \
+        BLACK = \
+        RED = \
+        GREEN = \
+        YELLOW = \
+        BLUE = \
+        MAGENTA = \
+        CYAN = \
+        WHITE = \
+        RESET_COLOR = ''
+
+      module_function
+
+      def reset
+        RESET
+      end
+
+      def clear
+        reset
+      end
+
+      def bold(string=nil)
+        string || ''
+      end
+
+      def black(string=nil)
+        string || ''
+      end
+
+      def red(string=nil)
+        string || ''
+      end
+
+      def green(string=nil)
+        string || ''
+      end
+
+      def yellow(string=nil)
+        string || ''
+      end
+
+      def blue(string=nil)
+        string || ''
+      end
+
+      def magenta(string=nil)
+        string || ''
+      end
+
+      def cyan(string=nil)
+        string || ''
+      end
+
+      def white(string=nil)
+        string || ''
+      end
+    end
+
+    #
+    # Checks if the stream supports ANSI output.
+    #
+    # @param [IO] stream
+    #
+    # @return [Boolean]
+    #
+    # @note
+    #   When the env variable `TERM` is set to `dumb`, it will disable color
+    #   output. Color output will also be disabled if the given stream is not
+    #   a TTY.
+    #
+    def ansi?(stream=stdout)
+      env['TERM'] != 'dumb' && stream.tty?
+    end
+
+    #
+    # Returns the colors available for the given stream.
+    #
+    # @param [IO] stream
+    #
+    # @return [ANSI, PlainText]
+    #   The ANSI module or PlainText dummy module.
+    #
+    def colors(stream=stdout)
+      color = if ansi?(stream) then ANSI
+              else                  PlainText
+              end
+
+      yield color if block_given?
+      return color
+    end
+  end
+end