rake-commander 0.1.2 → 0.2.0

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

@@ -0,0 +1,106 @@
+class RakeCommander
+  module Options
+    module Error
+      module Handling
+        class << self
+          def included(base)
+            super(base)
+            base.extend RakeCommander::Base::ClassHelpers
+            base.extend RakeCommander::Base::ClassInheritable
+            base.extend ClassMethods
+            base.attr_inheritable :error_on_options, :error_on_options_handler
+          end
+        end
+
+        module ClassMethods
+          attr_reader :options_latest_error
+
+          # Whether it should trigger an error when there are `ARGV` option errors during `parse_options`
+          # @note
+          #   1. It triggers error by default when there are parsing option errors.
+          #   2. Even if a `handler` block is defined, if action is `false` it won't trigger error.
+          #   3. When specific errors are NOT specified, they will **fallback** to the action defined
+          #     on the parent class `RakeCommander::Options::Error::Base`. This means that you can define
+          #     a default behaviour for this.
+          # @raise [RakeCommander::Options::Error::Base] the specific option error that was raised.
+          #   1. when `action` is `true` (default)
+          #   2. when the `handler` is defined and returns `true`.
+          # @yield [error, argv, results, leftovers] do some stuff and decide if an error should be raised.
+          # @yieldparam error [RakeCommander::Options::Error::Base] the specific error.
+          # @yieldparam argv [Array<String>] arguments that were being parsed.
+          # @yieldparam results [Hash] the parsed options.
+          # @yieldparam leftovers [Array<String>] arguments of `argv` that the parser could not identify.
+          # @yieldreturn [Boolean] whether this should trigger an error or not.
+          # @param action [Boolean, Symbol] possible values are:
+          #   1. `:not_used`      -> it will retrieve the currect action value
+          #   2. `true` (default) -> it switches `on` the exception triggering
+          #   3. `false`          -> it will **print** the error and **exit** with status `1`
+          #   4. `:continue`      -> it will continue with whatver it got (**use this at your own risk**)
+          # @param error [RakeCommander::Options::Error::Base:Class] or children thereof.
+          # @return [Boolean] whether this error is enabled.
+          def error_on_options(action = :not_used, error: RakeCommander::Options::Error::Base, &handler)
+            RakeCommander::Options::Error::Base.require_argument!(error, :error, accept_children: true)
+            @options_latest_error       = nil
+            @error_on_options         ||= {}
+            @error_on_options[error]    = action if action != :not_used
+
+            if block_given?
+              error_on_options_handler(error, &handler)
+              @error_on_options[error] ||= true
+            end
+
+            return self unless block_given? || action != :not_used
+            # default value
+            @error_on_options[error] = true unless @error_on_options[error] == false
+            @error_on_options[error]
+          end
+
+          # @see #error_on_options
+          def error_on_leftovers(action = :not_used, &handler)
+            error_on_options(action, error: RakeCommander::Options::Error::UnknownArgument, &handler)
+          end
+
+          # @return [Boolean] whether there is an error `action` defined for `error`
+          def error_on_options?(error = RakeCommander::Options::Error::Base)
+            RakeCommander::Options::Error::Base.require_argument!(error, :error, accept_children: true)
+            _default_action = error_on_options
+            @error_on_options.key?(error) || error_on_options_handler.key?(error)
+          end
+
+          protected
+
+          # Provide error for the given block.
+          # @return [String<Array>] the result of `yield` or `leftovers` if there was an error
+          #   where the `action` was defined as `:continue`
+          def with_error_handling(argv, results, leftovers)
+            yield
+          rescue RakeCommander::Options::Error::Base => e
+            @options_latest_error = e
+            eklass                = e.class
+            # Fallback to generic error handling if specific error action is not defined
+            eklass = eklass.superclass unless error_on_options?(eklass)
+            action = error_on_options(error: eklass)
+
+            # here is where we ignore the handler (when !action == `true`)
+            raise            unless !action || handler = error_on_options_handler(eklass)
+            raise            if handler&.call(e, argv, results, leftovers)
+            return leftovers if action == :continue
+            puts e.message
+            # https://stackoverflow.com/a/23340693/4352306
+            exit 1
+          end
+
+          private
+
+          def error_on_options_handler(error = :not_used, &handler)
+            @error_on_options_handler        ||= {}
+            return @error_on_options_handler if error == :not_used
+            RakeCommander::Options::Error::Base.require_argument!(error, :error, accept_children: true)
+            @error_on_options_handler[error] = handler if block_given?
+            @error_on_options_handler[error]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+class RakeCommander
+  module Options
+    module Error
+      class InvalidArgument < RakeCommander::Options::Error::Base
+        option_regex(/invalid argument: (?<option>.+)/i.freeze)
+
+        private
+
+        def to_message(value)
+          return super unless opt = option
+          case value
+          when OptionParser::InvalidArgument
+            super("invalid option argument: #{opt.name_hyphen} (#{opt.short_hyphen})")
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+class RakeCommander
+  module Options
+    module Error
+      class InvalidOption < RakeCommander::Options::Error::Base
+        option_regex(/invalid option: (?<option>.+)/i.freeze)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+class RakeCommander
+  module Options
+    module Error
+      # Relates to options with missing required argument (when there's no `default` value)
+      class MissingArgument < RakeCommander::Options::Error::Base
+        option_regex(/missing(?: required|) argument: (?<option>.+)/i.freeze)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+class RakeCommander
+  module Options
+    module Error
+      # Relates to the `required` parameter when defining an option.
+      class MissingOption < RakeCommander::Options::Error::Base
+        def initialize(value = nil, from: nil)
+          super("missing required option: #{to_message(value)}", from: from)
+        end
+
+        def options
+          super | to_options(@value)
+        end
+
+        protected
+
+        def to_message(value)
+          case value
+          when RakeCommander::Option
+            "#{value.name_hyphen} (#{value.short_hyphen})"
+          when Hash
+            to_message(value.values.uniq)
+          when Array
+            value.map do |v|
+              v.is_a?(RakeCommander::Option)? to_message(v) : v
+            end.join(', ')
+          else
+            super
+          end
+        end
+
+        private
+
+        def to_options(value)
+          case value
+          when RakeCommander::Option
+            [value]
+          when Array
+            value.select {|v| v.is_a?(RakeCommander::Option)}
+          when Hash
+            to_options(value.values)
+          else
+            []
+          end.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+class RakeCommander
+  module Options
+    module Error
+      # Relates to `OptionParser#parse` output (**leftovers**)
+      class UnknownArgument < RakeCommander::Options::Error::Base
+        def initialize(value = nil, from: nil)
+          super("unknown arguments: #{to_message(value)}", from: from)
+        end
+
+        def leftovers
+          case @value
+          when Array
+            @value
+          else
+            []
+          end
+        end
+
+        private
+
+        def to_message(value)
+          case value
+          when Array
+            value.map {|v| "'#{v}'"}.join(', ')
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,18 +1,83 @@
-require_relative 'error_rely'
+require_relative 'error/base'
+require_relative 'error/missing_argument'
+require_relative 'error/invalid_argument'
+require_relative 'error/invalid_option'
+require_relative 'error/missing_option'
+require_relative 'error/unknown_argument'
+require_relative 'error/handling'
+
 class RakeCommander
   module Options
-    class MissingOption < RakeCommander::Options::ErrorRely
-      def initialize(value)
-        super("missing required option: #{to_description(value)}")
+    module Error
+      class << self
+        def included(base)
+          super(base)
+          base.send :include, RakeCommander::Options::Error::Handling
+          base.extend ClassMethods
+        end
       end
-    end
 
-    class MissingArgument < RakeCommander::Options::ErrorRely
-      OPTION_REGEX = /missing (?:required|) argument: (?<option>.+)/i.freeze
-    end
+      module ClassMethods
+        # Re-open method to add all the error handling.
+        # @see RakeCommander::Options::Result
+        def parse_options(argv = ARGV, results: {}, leftovers: [], &block)
+          with_error_handling(argv, results, leftovers) do
+            super.tap do |_|
+              check_on_leftovers(leftovers)
+              check_required_presence(results)
+            end
+          rescue OptionParser::InvalidOption => e
+            eklass = RakeCommander::Options::Error::InvalidOption
+            raise eklass.new(e, from: self), nil, cause: nil
+          rescue OptionParser::MissingArgument => e
+            eklass = RakeCommander::Options::Error::MissingArgument
+            opt    = error_option(e, eklass)
+            msg    = e.message
+            msg    = "missing required argument: #{opt.name_hyphen} (#{opt.short_hyphen})" if opt
+            raise eklass.new(from: self, option: opt), msg, cause: nil
+          rescue OptionParser::InvalidArgument => e
+            eklass = RakeCommander::Options::Error::InvalidArgument
+            opt    = error_option(e, eklass)
+            raise eklass.new(e, from: self, option: opt), nil, cause: nil unless opt&.argument_required?
+            eklass = RakeCommander::Options::Error::MissingArgument
+            msg = "missing required argument in option: #{opt.name_hyphen} (#{opt.short_hyphen})"
+            raise eklass.new(from: self, option: opt), msg, cause: nil
+          end
+        end
+
+        protected
 
-    class InvalidArgument < RakeCommander::Options::ErrorRely
-      OPTION_REGEX = /invalid argument: (?<option>.+)/i.freeze
+        # Helper to retrieve an existing `RakeCommander::Option` out of a
+        # `OptionParser` error.
+        # @param e [OptionParser:Error] containing the original error `message`
+        # @param eklass [RakeCommander::Options::Error:Base::Class] the error class to retrive the option key
+        # @return [RakeCommander::Option, NilClass]
+        def error_option(err, eklass)
+          return false unless option_sym = eklass.option_sym(err.message)
+          options_hash(with_implicit: true)[option_sym]
+        end
+
+        private
+
+        # It implements the logic defined by `error_on_leftovers`.
+        # @param leftovers [Array<String>]
+        # @param results [Hash] the parsed options
+        # @return [Hash] the results (same object)
+        def check_on_leftovers(leftovers)
+          return if leftovers.empty?
+          eklass = RakeCommander::Options::Error::UnknownArgument
+          raise eklass.new(leftovers, from: self)
+        end
+
+        # It throws an exception if any of the required options
+        # is missing in results
+        def check_required_presence(results)
+          missing = options.select(&:required?).reject do |opt|
+            results.key?(opt.short) || results.key?(opt.name)
+          end
+          raise RakeCommander::Options::Error::MissingOption.new(missing, from: self) unless missing.empty?
+        end
+      end
     end
   end
 end

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

@@ -1,15 +1,17 @@
 class RakeCommander
   module Options
     module Name
+      BOOLEAN_TOKEN       = '[no-]'.freeze
       # Substitions
       HYPHEN_START_REGEX  = /^-+/.freeze
       HYPEN_REGEX         = /-+/.freeze
       UNDERSCORE_REGEX    = /_+/.freeze
-      SPACE_REGEX         = /\s+/.freeze
-      # Checkers
+      WORD_DELIMITER      = /[\s=]+/.freeze
+      # Checkers / Capturers
       OPTIONAL_REGEX      = /\[\w+\]$/.freeze
       SINGLE_HYPHEN_REGEX = /^-(?<options>[^- ][^ ]*)/.freeze
-      DOUBLE_HYPHEN_REGEX = /^--(?<option>[^- ][^ ]*)/.freeze
+      DOUBLE_HYPHEN_REGEX = /^(?:--\[?no-\]?|--)(?<option>[^- ][^ \r\n]*).*$/.freeze
+      BOOLEAN_NAME_REGEX  = /^[^ ]*#{Regexp.escape(BOOLEAN_TOKEN)}[^ ]{2,}/.freeze
 
       # @return [Boolean]
       def single_hyphen?(value)
@@ -23,32 +25,68 @@ class RakeCommander
         !!value.to_s.match(DOUBLE_HYPHEN_REGEX)
       end
 
+      # @return [Boolean] whether the name has the boolean switch `[no-]`
+      def boolean_name?(value)
+        return false unless value.respond_to?(:to_s)
+        !!value.to_s.match(BOOLEAN_NAME_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
+        return false unless value.respond_to?(:to_s)
+        value = value.to_s.strip
+        return false if value.empty?
+        return false if strict && !single_hyphen?(value)
+        value = value.gsub(HYPHEN_START_REGEX, '')
+        value.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)
+        return false unless value.respond_to?(:to_s)
+        value = value.to_s.strip
+        return false if value.empty?
+        return false if 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)
+      # Modifies `args` and returns the short candidate
+      # @param args [Array<String, Symbol>]
+      # @return [String, Symbol] the short candidate
+      def capture_arguments_short!(args, strict: true, symbol: false)
+        capture_argument_with!(args) do |arg|
+          next false unless arg.is_a?(String) || arg.is_a?(Symbol)
+          next false if symbol && !arg.is_a?(Symbol)
+          valid_short?(arg, strict: strict)
+        end
+      end
+
+      # Modifies `args` and returns the name candidate
+      # @param args [Array<String, Symbol>]
+      # @return [String, Symbol] the name candidate
+      def capture_arguments_name!(args, strict: true, symbol: false)
+        capture_argument_with!(args) do |arg|
+          next false unless arg.is_a?(String) || arg.is_a?(Symbol)
+          next false if symbol && !arg.is_a?(Symbol)
+          valid_name?(arg, strict: strict)
+        end
+      end
+
+      # Modifies `args` and returns the arg candidate
+      # @param args [Array<String, Symbol>]
+      # @return [String, Symbol, NilClass] the arg candidate
+      def capture_argument_with!(args)
+        raise ArgumentError, "Expecting Array. Given: #{args.class}" unless args.is_a?(Array)
+        args.dup.find.with_index do |arg, i|
+          yield(arg).tap do |valid|
+            next unless valid
+            args.slice!(i)
+            return arg
+          end
+        end
+        nil
       end
 
       # Converter
@@ -57,7 +95,8 @@ class RakeCommander
       # @return [Symbol, NilClass]
       def short_sym(value)
         return nil unless value
-        value = value.to_s.gsub(HYPHEN_START_REGEX, '')
+        value = value.to_s.gsub(BOOLEAN_TOKEN, '')
+        value = value.gsub(HYPHEN_START_REGEX, '')
         return nil unless value = value.chars.first
         value.to_sym
       end
@@ -74,20 +113,25 @@ class RakeCommander
         return nil unless value
         value = value.to_s.gsub(HYPHEN_START_REGEX, '')
         value = value.gsub(HYPEN_REGEX, '_')
-        value = value.gsub(SPACE_REGEX, ' ')
+        value = value.gsub(WORD_DELIMITER, ' ')
         return nil if value.empty?
         value.to_sym
       end
 
       # It's like `#name_sym` but it only gets the option name.
+      # @note
+      #   1. It also removes the boolean token `[no-]`
       # @example
       #   * `"--there-we-go   ARGUMENT"` becomes `:there_we_go`
+      #   * `"--[no]-verbose"` becomes `:verbose`
       # @see #name_sym
       # @return [Symbol, NilClass]
       def name_word_sym(value)
         return nil unless value = name_sym(value)
+        value = value.to_s.gsub(BOOLEAN_TOKEN, '')
+
         return nil unless value = name_words(value).first
-        value.to_sym
+        value.downcase.to_sym
       end
 
       # @return [String, NilClass] it returns the hyphened (`-`) version of a short `value`
@@ -98,7 +142,7 @@ class RakeCommander
 
       # Gets the actual name of the option. First word.
       # @example
-      #   * `"--there-we-go   ARGUMENT"` becomes `"--there-we-go"`
+      #   * `"--there-we-go   ARGUMENT"` becomes `"--there-we-go ARGUMENT"`
       #   * `"there-we-go"` becomes `"--there-we-go"`
       #   * `:there_we_go` becomes `"--there-we-go"`
       # @return [String, NilClass] option `name` alone double hypened (`--`)
@@ -153,7 +197,7 @@ class RakeCommander
       def name_words(value)
         return nil unless value
         value = value.to_s.gsub(HYPHEN_START_REGEX, '')
-        value.to_s.split(SPACE_REGEX)
+        value.to_s.split(WORD_DELIMITER)
       end
     end
   end

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

@@ -0,0 +1,107 @@
+class RakeCommander
+  module Options
+    module Result
+      class << self
+        def included(base)
+          super(base)
+          base.extend ClassMethods
+          base.attr_inheritable :options_with_defaults
+        end
+      end
+
+      module ClassMethods
+        # Configuration Setting.
+        # @return [Boolean] whether results should include options defined
+        #   with a default, regarless if they are invoked
+        def options_with_defaults(value = nil)
+          if value.nil?
+            @options_with_defaults || false
+          else
+            @options_with_defaults = !!value
+          end
+        end
+
+        # It **re-opens** the method and adds a middleware to gather and return
+        # the results of the parsing (including the `leftovers`)
+        # @note this extends the method parameters and changes the returned value.
+        # @param leftovers [Array<String>] see RakeCommander::Options#parse_options`
+        # @param results [Hash] with `short` option as `key` and final value as `value`.
+        # @see `RakeCommander::Options#parse_options`
+        def parse_options(argv = ARGV, results: {}, leftovers: [], &middleware)
+          leftovers.push(*super(argv, &results_collector(results, &middleware)))
+        end
+
+        # **Extend** method to ensure options are parsed before calling task.
+        # This only happens if `task_method` has it's context (binding) with
+        # an instance object of this class.
+        # @note
+        #   1. This allows stop before invoking the task, may there be options
+        #     that have this effect (i.e. `-h`)
+        #   2. We use `task_context` to open up extensibility.
+        # @todo think if it should rather raise an `ArgumentError` when the task
+        #   was not defined in an instance object of his class.
+        def install_task(&task_method)
+          super(&task_context(&task_method))
+        end
+
+        protected
+
+        # Invoke `options` parsing before calling the task.
+        # @return [Proc] our wrapped task block.
+        def task_context(&task_method)
+          instance = eval('self', task_method.binding, __FILE__, __LINE__)
+          return task_method unless instance.is_a?(self)
+          proc do |*task_args|
+            # launch `ARGV` parsing
+            instance.options
+            task_method.call(*task_args)
+          end
+        end
+
+        private
+
+        # Expects a block that should do the final call to `OptionParser#parse`.
+        # It is invoked on each option parsing (so only when that option is invoked).
+        # @note if an invoked option comes empty (`nil`), it uses the `default` value.
+        # @return [Proc] the results collector that wraps the middleware.
+        def results_collector(results, &middleware)
+          results = result_defaults(results)
+          proc do |value, default, short, name|
+            middleware&.call(value, default, short, name)
+            results[short] = value.nil?? default : value
+          end
+        end
+
+        # Based on `required` options, it sets the `default`
+        def result_defaults(results = {})
+          results.tap do |res_def|
+            options.select do |opt|
+              (options_with_defaults && opt.default?) \
+              || (opt.required? && opt.default?)
+            end.each do |opt|
+              res_def[opt.short] = opt.default
+            end
+          end
+        end
+      end
+
+      # Launches the options parsing of this class.
+      # @return [Hash] keyed by short.
+      def options(argv = ARGV, &block)
+        return @options if instance_variable_defined?(:@options)
+        @options = {}
+        self.class.parse_options(argv, results: @options, leftovers: options_leftovers, &block)
+        @options
+      end
+
+      # The options part (so after `--`) that was NOT processed
+      # by the `OptionParser`. They are therefore unknown parameters.
+      # @note an unknown option (i.e. `-f something`, `--foo something`) would trigger an invalid option error.
+      #   This means that the `leftovers` can only refer to arguments not paired to options that receive
+      #   parameters (i.e. `--no-foo something`).
+      def options_leftovers
+        @options_leftovers ||= []
+      end
+    end
+  end
+end

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

@@ -6,9 +6,15 @@ class RakeCommander
       class << self
         include Enumerable
 
+        # Name of the `Options::Set`
+        def name(value = :not_used)
+          return @name if value == :not_used
+          @name = value.to_sym
+        end
+
         def each(&block)
           return to_enum(:each) unless block
-          options.values.each(&block)
+          options.each(&block)
         end
       end
     end