rake-commander 0.1.2

data/lib/rake-commander/option.rb

@@ -0,0 +1,153 @@
+class RakeCommander
+  @option_struct ||= Struct.new(:short, :name)
+  class Option < @option_struct
+    extend RakeCommander::Base::ClassHelpers
+    extend RakeCommander::Options::Name
+
+    attr_accessor :desc, :default
+    attr_writer :type_coertion, :required
+    attr_reader :name_full
+
+    def initialize(short, name, *args, **kargs, &block)
+      raise ArgumentError, "A short of one letter should be provided. Given: #{short}" unless self.class.valid_short?(short)
+      raise ArgumentError, "A name should be provided. Given: #{name}" unless  self.class.valid_name?(name)
+
+      @name_full = name
+      super(short, name)
+      @default        = kargs[:default]  if kargs.key?(:default)
+      @desc           = kargs[:desc]     if kargs.key?(:desc)
+      @required       = kargs[:required] if kargs.key?(:required)
+      @other_args     = args
+      @original_block = block
+      yield(self) if block_given?
+      configure_other
+    end
+
+    def required?
+      !!@required
+    end
+
+    # @return [Symbol]
+    def short
+      self.class.short_sym(super)
+    end
+
+    # @return [String]
+    def short_hyphen
+      self.class.short_hyphen(short)
+    end
+
+    # @return [Symbol]
+    def name
+      self.class.name_word_sym(super)
+    end
+
+    # @return [String]
+    def name_hyphen
+      self.class.name_hyphen(name_full)
+    end
+
+    # @param [Boolean] whether this option allows an argument
+    def argument?
+      self.class.name_argument?(name_full)
+    end
+
+    # @param [String, Nil] the argument, may it exist
+    def argument
+      return nil unless argument?
+      self.class.name_argument(name_full)
+    end
+
+    # @param [Boolean] If there was an argument, whether it is required
+    def argument_required?
+      self.class.argument_required?(argument)
+    end
+
+    # @return [Class, NilClass]
+    def type_coertion
+      @type_coertion || (default? && default.class)
+    end
+
+    # @return [Boolean]
+    def default?
+      instance_variable_defined?(:@default)
+    end
+
+    # Adds this option's switch to the `OptionParser`
+    # @note it allows to add a `middleware` block that will be called at `parse` runtime
+    def add_switch(opts_parser, where: :base, &middleware)
+      raise "Expecting OptionParser. Given: #{opts_parser.class}" unless opts_parser.is_a?(OptionParser)
+      case where
+      when :head, :top
+        opts_parser.on_head(*switch_args, &option_block(&middleware))
+      when :tail, :end
+        opts_parser.on_tail(*switch_args, &option_block(&middleware))
+      else # :base
+        opts_parser.on(*switch_args, &option_block(&middleware))
+      end
+      opts_parser
+    end
+
+    # @return [Array<Variant>]
+    def switch_args
+      configure_other
+      args = [short_hyphen, name_hyphen]
+      if str = switch_desc
+        args << str
+      end
+      args << type_coertion if type_coertion
+      args
+    end
+
+    private
+
+    # Called on parse runtime
+    def option_block(&middleware)
+      block_extra_args = [default, short, name]
+      proc do |value|
+        args = block_extra_args.dup.unshift(value)
+        @original_block&.call(*args)
+        middleware&.call(*args)
+      end
+    end
+
+    def switch_desc
+      val = "#{desc}#{default_desc}"
+      return nil if val.empty?
+      val
+    end
+
+    def default_desc
+      return nil unless default?
+      str = "Default: '#{default}'"
+      if desc && !desc.downcase.include?('default')
+        str = desc.end_with?('.') ? " #{str}" : ". #{str}"
+      end
+      str
+    end
+
+    def other_args(*args)
+      @other_args ||= []
+      if args.empty?
+        @other_args
+      else
+        @other_args.push(*args)
+      end
+    end
+
+    # It consumes `other_args`, to prevent direct overrides to be overriden by it.
+    def configure_other
+      if type = other_args.find {|arg| arg.is_a?(Class)}
+        self.type_coertion = type
+        other_args.delete(type)
+      end
+      if value = other_args.find {|arg| arg.is_a?(String)}
+        self.desc = value
+        other_args.dup.each do |val|
+          other_args.delete(val) if val.is_a?(String)
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/rake-commander/options/arguments.rb

@@ -0,0 +1,116 @@
+class RakeCommander
+  module Options
+    # Offers helpers to treat `ARGV`
+    module Arguments
+      include RakeCommander::Options::Name
+
+      # Options with arguments should not take another option as value.
+      # `OptionParser` can do this even if the the argument is optional.
+      # This method re-arranges the arguments based on options that receive parameters,
+      # provided that an option is not taken as a value of a previous option that accepts arguments.
+      # If an option with argument is missing the argument, but has a `default` value,
+      # that `default` value will be inserted after the option in the array
+      # to prevent the `OptionParser::MissingArgument` error to stop the parsing process.
+      # @note
+      #   1. Any word or letter with _hypen_ -`` or _double hypen_ `--` is interpreted as option(s)
+      #   2. To overcome this limitation, you may enclose in double quotes and argument with
+      #     that start (i,e, `"--argument"`).
+      # @example
+      #   1. `-abc ARGUMENT` where only `c` receives the argument becomes `-ab -c ARGUMENT`
+      #   3. `-abc ARGUMENT` where `b` and `c` are argument receivers becomes `-a -b nil -c ARGUMENT`
+      #   2. `-acb ARGUMENT` where only `c` receives the argument becomes `-a -c nil -b ARGUMENT`
+      #   4. `-c --some-option ARGUMENT` where both options receive argument, becomes `-c nil --some-option ARGUMENT`
+      #   5. `-c --some-option -d ARGUMENT` where both options receive argument, becomes `-c nil --some-option nil -d ARGUMENT`
+      #   6. `-cd ARGUMENT` where `c` default is `"yeah"`, becomes `-c yeah -d ARGUMENT`
+      # @param argv [Array<String>]
+      # @param options [Hash] the defined `RakeCommander::Option` to re-arrange `argv` with.
+      # @return [Array<String>] the re-arranged `argv`
+      def pre_parse_arguments(argv = ARGV, options)
+        pre_parsed = explicit_argument_options(argv, options)
+        compact_short = ''
+        pre_parsed.each_with_object([]) do |(opt_ref, args), out|
+          next out.push(*args) unless opt_ref.is_a?(Symbol)
+          is_short = opt_ref.to_s.length == 1
+          next compact_short << opt_ref.to_s if is_short && args.empty?
+          out.push("-#{compact_short}") unless compact_short.empty?
+          compact_short = ''
+          opt_str = is_short ? "-#{opt_ref}" : name_hyphen(opt_ref)
+          out.push(opt_str, *args)
+        end.tap do |out|
+          out.push("-#{compact_short}") unless compact_short.empty?
+        end
+      end
+
+      private
+
+      # @example the output is actually a Hash, keyed by the Symbol of the option (short or name)
+      #   1. `-abc ARGUMENT` where only `c` receives the argument becomes `:a :b :c ARGUMENT`
+      #   3. `-abc ARGUMENT` where `b` and `c` are argument receivers becomes `:a :b nil :c ARGUMENT`
+      #   2. `-acb ARGUMENT` where only `c` receives the argument becomes `:a :c nil :b ARGUMENT`
+      #   4. `-c --some-option ARGUMENT` where both options receive argument, becomes `:c nil :some_option ARGUMENT`
+      #   5. `-c --some-option -d ARGUMENT` where first two options receive argument, becomes `:c nil :some_option nil :d ARGUMENT`
+      #   6. `-cd ARGUMENT` where `c` default is `"yeah"`, becomes `:c yeah :d ARGUMENT`
+      # @return [Hash<Symbol, Array>]
+      def explicit_argument_options(argv, options)
+        decoupled  = decluster_shorts_n_names_to_sym(argv)
+        grouped    = group_symbols_with_strings(decoupled)
+        normalized = insert_missing_argument_to_groups(grouped, options)
+        normalized.each_with_object({}) do |group, pre_parsed|
+          opt_ref = group.first.is_a?(Symbol)? group.shift : nil
+          pre_parsed[opt_ref] = group
+        end
+      end
+
+      # It adds the missing argument to options that expect it.
+      # @note it uses `default` if present, and `nil` otherwise.
+      # @param groups [@see #pair_symbols_with_strings]
+      def insert_missing_argument_to_groups(groups, options)
+        groups.each do |group|
+          args = group.dup
+          opt_ref = args.shift
+          next unless args.empty?
+          next unless opt_ref.is_a?(Symbol)
+          next unless opt = options[opt_ref]
+          next unless opt.argument?
+          next group.push(opt.default) if opt.default?
+          group.push(nil)
+        end
+      end
+
+      # @return [Array<Array>] where the first element of each `Array` is a symbol
+      #   followed by one or more `String`.
+      def group_symbols_with_strings(argv)
+        [].tap do |out|
+          curr_ary = nil
+          argv.each do |arg|
+            if arg.is_a?(Symbol)
+              out << (curr_ary = [arg])
+            else # must be `String`
+              out << (curr_ary = []) unless curr_ary
+              curr_ary << arg
+            end
+          end
+        end
+      end
+
+      # It splits `argv` compacted shorts into their `Symbol` version.
+      # Symbolizes option `names` (long version).
+      # @return [Array<String, Symbol>] where symbols are options and strings arguments.
+      def decluster_shorts_n_names_to_sym(argv)
+        argv.each_with_object([]) do |arg, out|
+          if single_hyphen?(arg) # short option(s)
+            options = arg.match(SINGLE_HYPHEN_REGEX)[:options]
+            options.split('').each do |short|
+              out << short_sym(short)
+            end
+          elsif double_hyphen?(arg) # name option
+            name = arg.match(DOUBLE_HYPHEN_REGEX)[:option]
+            out << name_sym(name)
+          else # argument
+            out << arg
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rake-commander/options/error.rb

@@ -0,0 +1,18 @@
+require_relative 'error_rely'
+class RakeCommander
+  module Options
+    class MissingOption < RakeCommander::Options::ErrorRely
+      def initialize(value)
+        super("missing required option: #{to_description(value)}")
+      end
+    end
+
+    class MissingArgument < RakeCommander::Options::ErrorRely
+      OPTION_REGEX = /missing (?:required|) argument: (?<option>.+)/i.freeze
+    end
+
+    class InvalidArgument < RakeCommander::Options::ErrorRely
+      OPTION_REGEX = /invalid argument: (?<option>.+)/i.freeze
+    end
+  end
+end

data/lib/rake-commander/options/error_rely.rb

@@ -0,0 +1,58 @@
+class RakeCommander
+  module Options
+    # Relies between OptionParser and RakeCommander errors
+    class ErrorRely < StandardError
+      extend RakeCommander::Options::Name
+
+      OPTION_REGEX = /(?:argument|option): (?<option>.+)/i.freeze
+
+      def initialize(value)
+        case value
+        when OptionParser::MissingArgument, OptionParser::InvalidArgument
+          super(value.message)
+        when String
+          super(value)
+        else
+          raise ArgumentError, "Expecting String or OptionParser error. Given: #{value.class}"
+        end
+      end
+
+      def name?
+        option_sym.to_s.length > 1
+      end
+
+      def short?
+        option_sym.to_s.length == 1
+      end
+
+      def option_sym
+        return @option_sym if @option_sym
+        return nil unless match = message.match(self.class::OPTION_REGEX)
+        option = match[:option]
+        @option_sym = \
+          if option.length > 1
+            self.class.name_word_sym(option)
+          else
+            self.class.short_sym(option)
+          end
+      end
+
+      private
+
+      def to_description(value)
+        case value
+        when Hash
+          to_description(value.values.uniq)
+        when Array
+          value.map do |v|
+            to_description(v)
+          end.join(', ')
+        when RakeCommander::Option
+          "#{value.name_hyphen} (#{value.short_hyphen})"
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/rake-commander/options/name.rb

@@ -0,0 +1,160 @@
+class RakeCommander
+  module Options
+    module Name
+      # Substitions
+      HYPHEN_START_REGEX  = /^-+/.freeze
+      HYPEN_REGEX         = /-+/.freeze
+      UNDERSCORE_REGEX    = /_+/.freeze
+      SPACE_REGEX         = /\s+/.freeze
+      # Checkers
+      OPTIONAL_REGEX      = /\[\w+\]$/.freeze
+      SINGLE_HYPHEN_REGEX = /^-(?<options>[^- ][^ ]*)/.freeze
+      DOUBLE_HYPHEN_REGEX = /^--(?<option>[^- ][^ ]*)/.freeze
+
+      # @return [Boolean]
+      def single_hyphen?(value)
+        return false unless value.respond_to?(:to_s)
+        !!value.to_s.match(SINGLE_HYPHEN_REGEX)
+      end
+
+      # @return [Boolean]
+      def double_hyphen?(value)
+        return false unless value.respond_to?(:to_s)
+        !!value.to_s.match(DOUBLE_HYPHEN_REGEX)
+      end
+
+      # @param strict [Boolean] whether hyphen is required when declaring an option `short`
+      # @return [Boolean]
+      def valid_short?(value, strict: false)
+        return false unless value.respond_to?(:to_s) && !value.to_s.empty?
+        return false unless !strict || single_hypen(value)
+        short_sym(value).to_s.length == 1
+      end
+
+      # @param strict [Boolean] whether hyphen is required when declaring an option `name`
+      # @return [Boolean]
+      def valid_name?(value, strict: false)
+        return false unless value.respond_to?(:to_s) && !value.to_s.empty?
+        return false unless !strict || double_hyphen?(value)
+        name_sym(value).to_s.length > 1
+      end
+
+      # @param strict [Boolean] whether hyphen is required when declaring an option `short`
+      # @return [Boolean] whether `value` is an hyphened option `short`
+      def short_hyphen?(value, strict: false)
+        short?(value, strict: strict) && single_hypen(value)
+      end
+
+      # @param strict [Boolean] whether hyphen is required when declaring an option `name`
+      # @return [Boolean] whether `value` is an hyphened option `name`
+      def name_hyphen?(value, strict: false)
+        name?(value, strict: strict) && double_hyphen?(value)
+      end
+
+      # Converter
+      # @example
+      #   * `"-d"` becomes `:d`
+      # @return [Symbol, NilClass]
+      def short_sym(value)
+        return nil unless value
+        value = value.to_s.gsub(HYPHEN_START_REGEX, '')
+        return nil unless value = value.chars.first
+        value.to_sym
+      end
+
+      # Converter.
+      # @example
+      #   * `"--there-we-go   ARGUMENT"` becomes `:"there_we_go ARGUMENT"`
+      # @note
+      #   1. It removes the double hyphen start (`--`)
+      #   2. Replaces any intermediate hyphen by underscore `_`
+      #   3. Replaces any multi-spacing by single space ` `
+      # @return [Symbol, NilClass]
+      def name_sym(value)
+        return nil unless value
+        value = value.to_s.gsub(HYPHEN_START_REGEX, '')
+        value = value.gsub(HYPEN_REGEX, '_')
+        value = value.gsub(SPACE_REGEX, ' ')
+        return nil if value.empty?
+        value.to_sym
+      end
+
+      # It's like `#name_sym` but it only gets the option name.
+      # @example
+      #   * `"--there-we-go   ARGUMENT"` becomes `:there_we_go`
+      # @see #name_sym
+      # @return [Symbol, NilClass]
+      def name_word_sym(value)
+        return nil unless value = name_sym(value)
+        return nil unless value = name_words(value).first
+        value.to_sym
+      end
+
+      # @return [String, NilClass] it returns the hyphened (`-`) version of a short `value`
+      def short_hyphen(value)
+        return nil unless value = short_sym(value)
+        "-#{value}"
+      end
+
+      # Gets the actual name of the option. First word.
+      # @example
+      #   * `"--there-we-go   ARGUMENT"` becomes `"--there-we-go"`
+      #   * `"there-we-go"` becomes `"--there-we-go"`
+      #   * `:there_we_go` becomes `"--there-we-go"`
+      # @return [String, NilClass] option `name` alone double hypened (`--`)
+      def name_hyphen(value)
+        return nil unless value = name_sym(value)
+        value = value.to_s.gsub(UNDERSCORE_REGEX, '-')
+        return nil if value.empty?
+        "--#{value}"
+      end
+
+      # @example
+      #   * `"--there-we-go   ARGUMENT"` returns `"ARGUMENT"`
+      # @return [String, NilClass] the argument of `value`, if present
+      def name_argument(value)
+        name_words(value)[1]
+      end
+
+      # @example
+      #   * `"--there-we-go   ARGUMENT"` returns `true`
+      #   * `"--time"` returns `false`
+      # @return [String, NilClass] whether `value` is a name with argument
+      def name_argument?(value)
+        !!name_argument(value)
+      end
+
+      # @example
+      #   * `"--there-we-go   [ARGUMENT]"` returns `false`
+      #   * `"--folder  FOLDER"` returns `true`
+      #   * `"--time"` returns `false`
+      # @return [Boolean] `true` if `value` does NOT end with `[String]`
+      def argument_required?(value)
+        return false unless value
+        !argument_optional?(value)
+      end
+
+      # @example
+      #   * `"--there-we-go   [ARGUMENT]"` returns `true`
+      #   * `"--folder  FOLDER"` returns `false`
+      #   * `"--time"` returns `true`
+      # @note when there is NO argument it evaluates `true`
+      # @return [Boolean] `true` if `value` ends with `[String]`
+      def argument_optional?(value)
+        return true unless value
+        !!value.match(OPTIONAL_REGEX)
+      end
+
+      private
+
+      # @example
+      #   * `"--there-we-go   [ARGUMENT]"` returns `["there-we-go","[ARGUMENT]"]`
+      # @return [Array<String>] the words of `value` without hyphen start
+      def name_words(value)
+        return nil unless value
+        value = value.to_s.gsub(HYPHEN_START_REGEX, '')
+        value.to_s.split(SPACE_REGEX)
+      end
+    end
+  end
+end

data/lib/rake-commander/options/set.rb

@@ -0,0 +1,16 @@
+class RakeCommander
+  module Options
+    class Set
+      include RakeCommander::Options
+
+      class << self
+        include Enumerable
+
+        def each(&block)
+          return to_enum(:each) unless block
+          options.values.each(&block)
+        end
+      end
+    end
+  end
+end

data/lib/rake-commander/options.rb

@@ -0,0 +1,171 @@
+require_relative 'options/name'
+require_relative 'options/arguments'
+require_relative 'option'
+
+class RakeCommander
+  module Options
+    class << self
+      def included(base)
+        super(base)
+        base.extend RakeCommander::Base::ClassHelpers
+        base.extend ClassMethods
+        base.inheritable_attrs :banner, :options_hash, :results_with_all_defaults
+        base.extend RakeCommander::Options::Arguments
+      end
+    end
+
+    module ClassMethods
+      def options_hash
+        @options_hash ||= {}
+      end
+
+      def options
+        options_hash.values.uniq
+      end
+
+      def options?
+        !options.empty?
+      end
+
+      def clear_options!
+        @options_hash = {}
+      end
+
+      # Allows to use a set of options
+      # @param options [Enumerable<RakeCommander::Option>]
+      def use_options(options)
+        options = options.values if options.is_a?(Hash)
+        options.each do |opt|
+          add_to_options(opt)
+        end
+        self
+      end
+
+      # Defines a new option
+      # @note
+      #   - It will override with a Warning options with same `short` or `name`
+      def option(*args, **kargs, &block)
+        opt = RakeCommander::Option.new(*args, **kargs, &block)
+        add_to_options(opt)
+        self
+      end
+
+      # Overrides the auto-generated banner
+      def banner(desc = :not_used)
+        return @banner = desc unless desc == :not_used
+        return @banner if @banner
+        return task_options_banner if respond_to?(:task_options_banner, true)
+      end
+
+      # @return [Boolean] whether results should include options defined
+      #   with a default, regarless if they are invoked
+      def results_with_all_defaults(value = nil)
+        if value.nil?
+          @results_with_all_defaults || false
+        else
+          @results_with_all_defaults = !!value
+        end
+      end
+
+      # It builds the `OptionParser` injecting the `middleware` block.
+      # @return [Hash] with `short` option as `key` and final value as `value`.
+      def parse_options(argv = ARGV, leftovers: [], &middleware)
+        left_overs = []
+        options_parser_with_results(middleware) do |options_parser|
+          argv = pre_parse_arguments(argv, options_hash)
+          leftovers.push(*options_parser.parse(argv))
+        rescue OptionParser::MissingArgument => e
+          raise RakeCommander::Options::MissingArgument, e, cause: nil
+        rescue OptionParser::InvalidArgument => e
+          error = RakeCommander::Options::InvalidArgument
+          error = error.new(e)
+          if (opt = options_hash[error.option_sym]) && opt.argument_required?
+            msg = "missing required argument: #{opt.name_hyphen} (#{opt.short_hyphen})"
+            raise RakeCommander::Options::MissingArgument, msg, cause: nil
+          else
+            raise error, e, cause: nil
+          end
+        end.tap do |results|
+          check_required_presence!(results)
+        end
+      end
+
+      protected
+
+      # @return [OptionParser] the built options parser.
+      def options_parser(&middleware)
+        new_options_parser do |opts|
+          opts.banner = banner if banner
+          options.each {|opt| opt.add_switch(opts, &middleware)}
+        end
+      end
+
+      def new_options_parser(&block)
+        require 'optparse'
+        OptionParser.new(&block)
+      end
+
+      private
+
+      # Expects a block that should do the final call to `#parse`
+      def options_parser_with_results(middleware)
+        result_defaults.tap do |result|
+          results_collector = proc do |value, default, short, name|
+            middleware&.call(value, default, short, name)
+            result[short] = value.nil?? default : value
+          end
+          options_parser = options_parser(&results_collector)
+          yield(options_parser)
+        end
+      end
+
+      # Based on `required` options, it sets the `default`
+      def result_defaults
+        {}.tap do |res_def|
+          options.select do |opt|
+            (results_with_all_defaults && opt.default?) \
+            ||  (opt.required? && opt.default?)
+          end.each do |opt|
+            res_def[opt.short] = opt.default
+          end
+        end
+      end
+
+      # It throws an exception if any of the required options
+      # is missing in results
+      def check_required_presence!(results)
+        missing = options.select do |opt|
+          opt.required?
+        end.reject do |opt|
+          results.key?(opt.short) || results.key?(opt.name)
+        end
+        raise RakeCommander::Options::MissingOption.new(missing) unless missing.empty?
+      end
+
+      def add_to_options(opt)
+        if prev = options_hash[opt.short]
+          puts "Warning: Overriding option with short '#{prev.short}' ('#{prev.name}')"
+          options_hash.delete(prev.short)
+          options_hash.delete(prev.name)
+        end
+        if prev = options_hash[opt.name]
+          puts "Warning: Overriding option with name '#{prev.name}' ('#{prev.short}')"
+          options_hash.delete(prev.short)
+          options_hash.delete(prev.name)
+        end
+        options_hash[opt.name] = options_hash[opt.short] = opt
+      end
+    end
+
+    def options(argv = ARGV)
+      @options ||= self.class.parse_options(argv, leftovers: self.options_leftovers)
+    end
+
+    def options_leftovers
+      @options_leftovers ||= []
+    end
+  end
+end
+
+require_relative 'options/error'
+require_relative 'options/set'