command_kit 0.1.0.pre1

data/lib/command_kit/options/option.rb

@@ -0,0 +1,171 @@
+require 'command_kit/options/option_value'
+
+require 'optparse'
+require 'date'
+require 'time'
+require 'uri'
+require 'shellwords'
+
+module CommandKit
+  module Options
+    #
+    # Represents a defined option.
+    #
+    class Option
+
+      # @return [Symbol]
+      attr_reader :name
+
+      # @return [String, nil]
+      attr_reader :short
+
+      # @return [String]
+      attr_reader :long
+
+      # @return [Boolean]
+      attr_reader :equals
+
+      # @return [OptionValue, nil]
+      attr_reader :value
+
+      # @return [String]
+      attr_reader :desc
+
+      # @return [Proc, nil]
+      attr_reader :block
+
+      #
+      # Initializes the option.
+      #
+      # @param [Symbol] name
+      #
+      # @param [String, nil] short
+      #
+      # @param [String, nil] long
+      #
+      # @param [Boolean] equals
+      #
+      # @param [Hash{Symbol => Object}, nil] value
+      #   Keyword arguments for {OptionValue#initialize}, or `nil` if the option
+      #   has no additional value.
+      #
+      # @option value [Class, Hash, Array, Regexp] type
+      #
+      # @option value [String, nil] usage
+      #
+      # @param [String] desc
+      #
+      # @yield [(value)]
+      #
+      # @yieldparam [Object, nil] value
+      #
+      def initialize(name, short:   nil,
+                           long:    self.class.default_long_opt(name),
+                           equals:  false,
+                           value:   nil,
+                           desc:    ,
+                           &block)
+        @name    = name
+        @short   = short
+        @long    = long
+        @equals  = equals
+        @value   = OptionValue.new(**value) if value
+        @desc    = desc
+        @block   = block
+      end
+
+      #
+      # The default long option (ex: `--long-opt`) for the given option name
+      # (ex: `:long_opt`).
+      #
+      # @param [Symbol] name
+      #
+      # @return [String]
+      #
+      def self.default_long_opt(name)
+        "--#{Inflector.dasherize(name)}"
+      end
+
+      #
+      # Specifies if the option is of the form `--opt=VALUE`.
+      #
+      # @return [Boolean]
+      #
+      def equals?
+        @equals
+      end
+
+      #
+      # The separator characer between the option and option value.
+      #
+      # @return ['=', ' ', nil]
+      #
+      def separator
+        if @value
+          if equals? then '='
+          else            ' '
+          end
+        end
+      end
+
+      #
+      # Usage strings for the option.
+      #
+      # @return [Array<String>]
+      #   The usage strings.
+      #
+      def usage
+        [*@short, "#{@long}#{separator}#{@value && @value.usage}"]
+      end
+
+      #
+      # Determines if the option has a value.
+      #
+      # @return [Boolean]
+      #
+      def value?
+        !@value.nil?
+      end
+
+      #
+      # The option value's type.
+      #
+      # @return [Class, nil]
+      #
+      # @see OptionValue#type
+      #
+      def type
+        @value && @value.type
+      end
+
+      #
+      # The option value's default value.
+      #
+      # @return [Object, nil]
+      #
+      # @see OptionValue#default_value
+      #
+      def default_value
+        @value && @value.default_value
+      end
+
+      #
+      # The option description.
+      #
+      # @return [String]
+      #
+      # @note
+      #   If {#default_value} returns a value, the description will contain the
+      #   `Default:` value the option will be initialized with.
+      #
+      def desc
+        if (value = default_value)
+          "#{@desc} (Default: #{value})"
+        else
+          @desc
+        end
+      end
+
+    end
+  end
+end

data/lib/command_kit/options/option_value.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'command_kit/arguments/argument_value'
+require 'command_kit/inflector'
+
+require 'optparse'
+require 'date'
+require 'time'
+require 'uri'
+require 'shellwords'
+
+module CommandKit
+  module Options
+    #
+    # Represents an additional argument associated with an option flag.
+    #
+    class OptionValue < Arguments::ArgumentValue
+
+      USAGES = {
+        # NOTE: NilClass and Object are intentionally omitted
+        Date       => 'DATE',
+        DateTime   => 'DATE_TIME',
+        Time       => 'TIME',
+        URI        => 'URI',
+        Shellwords => 'STR',
+        String     => 'STR',
+        Integer    => 'INT',
+        Float      => 'DEC',
+        Numeric    => 'NUM',
+        OptionParser::DecimalInteger => 'INT',
+        OptionParser::OctalInteger   => 'OCT',
+        OptionParser::DecimalNumeric => 'NUM|DEC',
+        TrueClass  => 'BOOL',
+        FalseClass => 'BOOL',
+        Array      => 'LIST[,...]',
+        Regexp     => '/REGEXP/'
+      }
+
+      #
+      # Initializes the option value.
+      #
+      # @param [Class, Hash, Array, Regexp] type
+      #
+      # @param [String, nil] usage
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #
+      def initialize(type: String,
+                     usage: self.class.default_usage(type),
+                     **kwargs)
+        super(type: type, usage: usage, **kwargs)
+      end
+
+      #
+      # Returns the default option value usage for the given type.
+      #
+      # @param [Class, Hash, Array, Regexp] type
+      #
+      # @return [String, nil]
+      #
+      # @raise [TypeError]
+      #   The given type was not a Class, Hash, Array, or Regexp.
+      #
+      def self.default_usage(type)
+        USAGES.fetch(type) do
+          case type
+          when Class  then Inflector.underscore(type.name).upcase
+          when Hash   then type.keys.join('|')
+          when Array  then type.join('|')
+          when Regexp then type.source
+          else
+            raise(TypeError,"unsupported option type: #{type.inspect}")
+          end
+        end
+      end
+
+      #
+      # The usage string for the argument.
+      #
+      # @return [String, nil]
+      #
+      def usage
+        string = @usage
+        string = "[#{string}]" if optional?
+        string
+      end
+
+    end
+  end
+end

data/lib/command_kit/options/parser.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require 'command_kit/main'
+require 'command_kit/usage'
+require 'command_kit/printing'
+
+require 'optparse'
+
+module CommandKit
+  module Options
+    #
+    # Adds an [OptionParser] to the command class and automatically parses options
+    # before calling `main`.
+    #
+    # [OptionParser]: https://rubydoc.info/stdlib/optparse/OptionParser
+    #
+    #     include CommandKit::OptParser
+    #     
+    #     def initialize
+    #       @opts.on('-c','--custom','Custom option') do
+    #         @custom = true
+    #       end
+    #     end
+    #     
+    #     def main(*argv)
+    #       if @custom
+    #         puts "Custom mode enabled"
+    #       end
+    #     end
+    #
+    module Parser
+      include Usage
+      include Main
+      include Printing
+
+      module ModuleMethods
+        #
+        # Sets {CommandKit::Usage::ClassMethods#usage .usage} or extends
+        # {ModuleMethods}, depending on whether {Options::Parser} is being
+        # included into a class or a module.
+        #
+        # @param [Class, Module] context
+        #   The class or module including {Parser}.
+        #
+        def included(context)
+          super
+
+          if context.class == Module
+            context.extend ModuleMethods
+          else
+            context.usage '[options]'
+          end
+        end
+      end
+
+      extend ModuleMethods
+
+      # The option parser.
+      #
+      # @return [OptionParser]
+      attr_reader :option_parser
+
+      #
+      # The option parser.
+      #
+      # @return [OptionParser]
+      #
+      def initialize(**kwargs)
+        super(**kwargs)
+
+        @option_parser = OptionParser.new do |opts|
+          opts.banner = "Usage: #{usage}"
+
+          opts.separator ''
+          opts.separator 'Options:'
+
+          opts.on_tail('-h','--help','Print help information') do
+            help
+            exit(0)
+          end
+        end
+      end
+
+      #
+      # Parses the options and passes any additional non-option arguments
+      # to the superclass'es `#main` method.
+      #
+      # @param [Array<String>] argv
+      #   The given arguments Array.
+      #
+      # @return [Integer]
+      #   The exit status code.
+      #
+      def main(argv=[])
+        super(parse_options(argv))
+      rescue SystemExit => system_exit
+        system_exit.status
+      end
+
+      #
+      # Parses the given options.
+      #
+      # @param [Array<String>] argv
+      #   The given command-line arguments.
+      #
+      # @return [Array<String>]
+      #   The remaining non-option arguments.
+      #
+      def parse_options(argv)
+        begin
+          option_parser.parse(argv)
+        rescue OptionParser::InvalidOption => error
+          on_invalid_option(error)
+        rescue OptionParser::AmbiguousOption => error
+          on_ambiguous_option(error)
+        rescue OptionParser::InvalidArgument => error
+          on_invalid_argument(error)
+        rescue OptionParser::MissingArgument => error
+          on_missing_argument(error)
+        rescue OptionParser::NeedlessArgument => error
+          on_needless_argument(error)
+        rescue OptionParser::AmbiguousArgument => error
+          on_ambiguous_argument(error)
+        rescue OptionParser::ParseError => error
+          on_parse_error(error)
+        end
+      end
+
+      #
+      # Prints an option parsing error.
+      #
+      # @param [OptionParser::ParseError] error
+      #   The error from `OptionParser`.
+      #
+      def on_parse_error(error)
+        print_error("#{command_name}: #{error.message}")
+        print_error("Try '#{command_name} --help' for more information.")
+        exit(1)
+      end
+
+      #
+      # Place-holder method for handling `OptionParser::InvalidOption` exceptions.
+      #
+      # @param [OptionParser::InvalidOption] error
+      #
+      # @see on_parse_error
+      #
+      def on_invalid_option(error)
+        on_parse_error(error)
+      end
+
+      #
+      # Place-holder method for handling `OptionParser::AmbiguousOption`
+      # exceptions.
+      #
+      # @param [OptionParser::AmbiguousOption] error
+      #
+      # @see on_parse_error
+      #
+      def on_ambiguous_option(error)
+        on_parse_error(error)
+      end
+
+      #
+      # Place-holder method for handling `OptionParser::InvalidArgument`
+      # exceptions.
+      #
+      # @param [OptionParser::InvalidArgument] error
+      #
+      # @see on_parse_error
+      #
+      def on_invalid_argument(error)
+        on_parse_error(error)
+      end
+
+      #
+      # Place-holder method for handling `OptionParser::MissingArgument`
+      # exceptions.
+      #
+      # @param [OptionParser::MissingArgument] error
+      #
+      # @see on_parse_error
+      #
+      def on_missing_argument(error)
+        on_parse_error(error)
+      end
+
+      #
+      # Place-holder method for handling `OptionParser::NeedlessArgument`
+      # exceptions.
+      #
+      # @param [OptionParser::NeedlessArgument] error
+      #
+      # @see on_parse_error
+      #
+      def on_needless_argument(error)
+        on_parse_error(error)
+      end
+
+      #
+      # Place-holder method for handling `OptionParser::AmbiguousArgument`
+      # exceptions.
+      #
+      # @param [OptionParser::AmbiguousArgument] error
+      #
+      # @see on_parse_error
+      #
+      def on_ambiguous_argument(error)
+        on_parse_error(error)
+      end
+
+      #
+      # Prints the `--help` output.
+      #
+      def help_options
+        puts option_parser
+      end
+
+      #
+      # @see #help_options
+      #
+      def help
+        help_options
+      end
+    end
+  end
+end