rake-commander 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a73808173b38457d53944c3dc6d62f739746133a6d42f0b306a5d4bb40b3d23
-  data.tar.gz: 9f2d2754d5464e0d34fe3db2f2fcddba471652936d8e8ea73106cb33bd044e02
+  metadata.gz: 5593c671006f7e7e95feee9f6b173e0d9df9ce37e39c965b12a9c4c8970d7a06
+  data.tar.gz: f64990b6d2ef3eef976ca3b77cf712b5dfaa038677ca796ef59267c522c3a878
 SHA512:
-  metadata.gz: caf48388e42c830e15d761a97354291c9354b94652de4e7b0f059f10303d57467970769497980cae1f2aa7eaf7559e4c5f404e9e98e34cc094ee67b256627cf1
-  data.tar.gz: 41e1c1afd1cb0613a9fc2c10348e7b0bb2c54c1abbbfb8d839c60edd10c827400a8777adf74f84fe54694489103a5b89f580e2b4d0d8a586b1a8ec132bc4ce72
+  metadata.gz: 4e6e9f6f3a57344ffa8d730d0025977f541a38881559899b0944f1c7658fd306b03f8e5942eb84a114368075597c4c813fc82def9e692ffba56070d844146bd4
+  data.tar.gz: 911d733c2665c9cf708fe1f65c11131973b1693321b3404cf1cf403f79a120ef6f6bbb9db79089d0b7bcaa4e9b1d6bfdc628762c0670334273e8f5d918dd636c

data/CHANGELOG.md

@@ -31,7 +31,7 @@ All notable changes to this project will be documented in this file.
   - Example: `on_options(:t, :s, present: true) {|options| do-stuff}` <- block to be called only when the option `:t` and `:s` are both present in the parsed `options` result.
   - Once this has been done,  think about it being a hash-alike object with methods for the option names (i.e. `options.debug?`)
 
-## [0.4.1] - 2023-08-xx
+## [0.4.3] - 2025-02-xx
 
 ### Added
 
@@ -39,6 +39,26 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
+## [0.4.2] - 2025-02-25
+
+### Fixed
+
+- `Option#type_coercion` should be dupped on inheritance.
+
+## [0.4.1] - 2025-02-20
+
+### Added
+
+- Predefined values cohertion (i.e. `Enum`)
+
+### Fixed
+
+- Description: break lines should be respected.
+
+### Changed
+
+- Allow multiple `desc` declarations to be aligned with `OptsParser` behaviour.
+
 ## [0.4.0] - 2023-08-01
 
 ### Changed

data/examples/01_basic_example.rb

@@ -8,11 +8,13 @@ class RakeCommander::Custom::BasicExample < RakeCommander
   option '-w', :show_time, TrueClass, desc: 'Displays the local time'
   option :z, '--timezone', TrueClass, default: false, required: true
   option :o, '--hello NAME', String, desc: 'It greets.'
-  option '-s', '--say [SOMETHING]', "It says 'something'", default: %q(I don't know what to "say"...)
+  option '-s', '--say [SOMETHING]', "It says 'something'", 'But it comes with default',
+    default: %q(I don't know what to "say"...)
   option :d, '--folder NAME', default: '.', desc: 'Source local folder', required: true
   option '-e', :'--enviro ENV', 'The target environment to run this task', required: true
   option :v, :debug, TrueClass, 'Shows the parsed options'
   option :V, '[no-]verbose', 'Verbosity', TrueClass
+  option :l, '--colour COLOUR', "Choose a colour", type: %i[red yellow green blue]
   #option :f, :folder, required: false, reopen: true
 
   def task(*_args)

data/examples/03_a_chainer_plus_example.rb

@@ -10,8 +10,9 @@ class RakeCommander::Custom::ChainerPlus < RakeCommander::Custom::Chainer
   # Update option description
   option_reopen :chain, desc: "Calls: '< rake|raked > #{TARGET_TASK} task'"
   # Extend with new options
-  option :e, '--exit-on-error', TrueClass, \
-         desc: "Whether #{TARGET_TASK} should just exit on 'missing argument' error (or raise an exception)"
+  option \
+    :e, '--exit-on-error', TrueClass,
+    desc: "Whether #{TARGET_TASK} should just exit on 'missing argument' error (or raise an exception)"
   option :o, '--hello NAME', String, desc: 'It greets.'
 
   # Make it default to `exit 1` when there are errors

data/lib/rake-commander/base/class_auto_loader.rb

@@ -50,17 +50,20 @@ class RakeCommander
       # @return [Boolean] determines if a given namespace is entitled for autoloading
       def autoload_class?(constant)
         constants = constant.to_s.split("::").compact
-        autoload = true
+        autoload  = true
+
         unless autoloaded_namespaces(:include).empty?
           autoload = autoloaded_namespaces(:include).any? do |ns|
             ns.to_s.split("::").compact.zip(constants).all? {|(r, c)| r == c}
           end
         end
+
         unless autoloaded_namespaces(:ignore).empty?
           autoload &&= autoloaded_namespaces(:ignore).none? do |ns|
             ns.to_s.split("::").compact.zip(constants).all? {|(r, c)| r == c}
           end
         end
+
         autoload
       end
 
@@ -90,8 +93,10 @@ class RakeCommander
       # Children classes of `autoloader_class` that have not been created an instance of.
       def unloaded_children
         return [] unless autoloaded_class
+
         new_detected = new_classes
         known_class!(*new_detected)
+
         descendants(parent_class: autoloaded_class, scope: new_detected).select do |child_class|
           !autoloaded_children.include?(child_class) && \
             !excluded_children.include?(child_class) && \
@@ -105,9 +110,12 @@ class RakeCommander
       # @return [Boolean] `true` if there were children loaded, `false` otherwise.
       def autoload_children(object = nil)
         return false if !autoloaded_class || @loading_children
+
         pending_children = unloaded_children
         return false if pending_children.empty?
+
         @loading_children = true
+
         pending_children.each do |klass|
           exclude = false
           child   = object ? klass.new(object) : klass.new
@@ -119,6 +127,7 @@ class RakeCommander
         ensure
           autoloaded_children.push(klass) unless exclude
         end
+
         @loading_children = false
         true
       end

data/lib/rake-commander/base/class_inheritable.rb

@@ -15,11 +15,14 @@ class RakeCommander
         attrs = attrs.map(&:to_sym)
         inheritable_class_var(*attrs, deep_dup: deep_dup, &block)
         return unless add_accessors
+
         attrs.each do |attr|
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
-            class << self; attr_accessor :#{attr} end
+            # class << self; attr_accessor :class_var; end
+            class << self; attr_accessor :#{attr}; end
           RUBY
         end
+
         self
       end
 
@@ -35,7 +38,8 @@ class RakeCommander
       #   that should NOT be inheritable.
       def attr_not_inheritable(*attrs)
         attrs.each do |attr|
-          next unless method = inheritable_class_var_method(attr)
+          next unless (method = inheritable_class_var_method(attr))
+
           inheritable_class_var[method].delete(attr)
         end
         self
@@ -86,6 +90,7 @@ class RakeCommander
         }.tap do |hash|
           hash[:deep_dup][:inheritable_class_var] = :default
         end
+
         @inheritable_class_var.tap do |_methods|
           vars.each {|var| inheritable_class_var_add(var, deep_dup: deep_dup, &block)}
         end
@@ -97,7 +102,9 @@ class RakeCommander
         # Remove previous definition if present
         attr_not_inheritable(var)
         method = deep_dup || block ? :deep_dup : :mirror
+
         inheritable_class_var[method][var] = block || :default
+
         self
       end
 

data/lib/rake-commander/base/custom_error.rb

@@ -11,6 +11,7 @@ class RakeCommander
       # just return @message
       def to_s
         return @message if @message
+
         unclassed(super)
       end
 
@@ -18,6 +19,7 @@ class RakeCommander
       # just return @message
       def message
         return @message if @message
+
         to_message(unclassed(super))
       end
 
@@ -30,9 +32,7 @@ class RakeCommander
         case value
         when StandardError
           to_message(value.message)
-        when String
-          value
-        when NilClass
+        when String, NilClass
           value
         else
           raise ArgumentError, "Expecting String, StandardError or NilClass. Given: #{value.class}"

data/lib/rake-commander/base/object_helpers.rb

@@ -20,21 +20,26 @@ class RakeCommander
         return yield(value)   if block_given?
         return value          unless dup_objects
         return value.deep_dup if value.respond_to?(:deep_dup)
+
         value.dup
       end
 
       # Custom Hash#deep_dup for rake commander
       def custom_hash_deep_dup(original, dup_objects: true, &dup_block)
         raise ArgumentError, "Expecting Hash. Given: #{original.class}" unless original.is_a?(Hash)
+
         hash = original.dup
+
         original.each_pair do |key, value|
           unless key.frozen? && key.is_a?(::String)
             hash.delete(key)
             key = custom_deep_dup(key, dup_objects: dup_objects, &dup_block) if dup_objects
           end
-          value     = dup_objects ? custom_deep_dup(value, dup_objects: dup_objects, &dup_block) : value
+
+          value     = custom_deep_dup(value, dup_objects: dup_objects, &dup_block) if dup_objects
           hash[key] = value
         end
+
         hash
       end
     end

data/lib/rake-commander/base.rb

@@ -10,7 +10,8 @@ class RakeCommander
   module Base
     class << self
       def included(base)
-        super(base)
+        super
+
         base.extend RakeCommander::Base::ClassAutoLoader
         base.autoloads_children_of RakeCommander
 

data/lib/rake-commander/option.rb

@@ -4,6 +4,7 @@ class RakeCommander
     extend RakeCommander::Base::ClassHelpers
     extend RakeCommander::Options::Name
     include RakeCommander::Options::Description
+    include RakeCommander::Options::Type
 
     attr_reader :name_full, :desc, :default
 
@@ -13,12 +14,14 @@ class RakeCommander
 
       @name_full  = name.freeze
       super(short.freeze, @name_full)
+
       @default        = kargs[:default]  if kargs.key?(:default)
       @desc           = kargs[:desc]     if kargs.key?(:desc)
       @required       = kargs[:required] if kargs.key?(:required)
       @type_coercion  = kargs[:type]     if kargs.key?(:type)
       @other_args     = args
       @original_block = block
+
       configure_other
     end
 
@@ -33,7 +36,9 @@ class RakeCommander
     # Creates a new option, result of merging this `opt` with this option,
     # @return [RakeCommander::Option] where opt has been merged
     def merge(opt, **kargs)
-      raise "Expecting RakeCommander::Option. Given: #{opt.class}" unless opt.is_a?(RakeCommander::Option)
+      msg = "Expecting RakeCommander::Option. Given: #{opt.class}"
+      raise msg unless opt.is_a?(RakeCommander::Option)
+
       dup(**opt.dup_key_arguments.merge(kargs), &opt.original_block)
     end
 
@@ -81,7 +86,8 @@ class RakeCommander
 
     # @param [String, Nil] the argument, may it exist
     def argument
-      return nil unless argument?
+      return unless argument?
+
       self.class.name_argument(name_full)
     end
 
@@ -93,10 +99,23 @@ class RakeCommander
     # @return [Class, NilClass]
     def type_coercion
       value = @type_coercion || (default? && default.class)
-      return nil unless value.is_a?(Class)
+      return unless allowed_type?(value)
+
       value
     end
 
+    # @return [Boolean] whether the option is an enum with fixed values.
+    def enum?
+      type_coercion.is_a?(Array)
+    end
+
+    # @return [Array, NilClass] the valid options when is `enum?`
+    def enum_options
+      return unless enum?
+
+      type_coercion
+    end
+
     # @return [Boolean]
     def default?
       instance_variable_defined?(:@default)
@@ -107,9 +126,12 @@ class RakeCommander
     # @param opt_parser [OptionParser] the option parser to add this option's switch.
     # @param implicit_short [Boolean] whether the implicit short of this option is active in the opts_parser.
     def add_switch(opts_parser, where: :base, implicit_short: false, &middleware)
-      raise "Expecting OptionParser. Given: #{opts_parser.class}" unless opts_parser.is_a?(OptionParser)
+      msg = "Expecting OptionParser. Given: #{opts_parser.class}"
+      raise msg unless opts_parser.is_a?(OptionParser)
+
       args  = switch_args(implicit_short: implicit_short)
       block = option_block(&middleware)
+
       case where
       when :head, :top
         opts_parser.on_head(*args, &block)
@@ -127,13 +149,14 @@ class RakeCommander
 
     # @return [Hash] keyed arguments to create a new object
     def dup_key_arguments
-      configure_other
       {}.tap do |kargs|
-        kargs.merge!(short:    short.dup.freeze)      if short
-        kargs.merge!(name:     name_full.dup.freeze)  if name_full
-        kargs.merge!(desc:     @desc.dup)             if @desc
-        kargs.merge!(default:  @default.dup)          if default?
-        kargs.merge!(type:     @type_coercion)        if @type_coercion.is_a?(Class)
+        configure_other
+
+        kargs.merge!(short:    short.dup.freeze)     if short
+        kargs.merge!(name:     name_full.dup.freeze) if name_full
+        kargs.merge!(desc:     @desc.dup)            if @desc
+        kargs.merge!(default:  @default.dup)         if default?
+        kargs.merge!(type:     dupped_type)          if allowed_type?(@type_coercion)
         kargs.merge!(required: required?)
       end
     end
@@ -141,6 +164,7 @@ class RakeCommander
     # @return [Array<Variant>]
     def switch_args(implicit_short: false)
       configure_other
+
       args = [short_hyphen, name_hyphen]
       args.push(*switch_desc(implicit_short: implicit_short))
       args << type_coercion if type_coercion
@@ -152,10 +176,13 @@ class RakeCommander
     # Called on parse runtime
     def option_block(&middleware)
       block_extra_args = [default, short, name, self]
+
       proc do |value|
         value = !value if type_coercion == FalseClass
         args  = block_extra_args.dup.unshift(value)
+
         original_block&.call(*args)
+
         middleware&.call(*args)
       end
     end
@@ -165,8 +192,9 @@ class RakeCommander
     # @return [Array<String>]
     def switch_desc(implicit_short: false, line_width: DESC_MAX_LENGTH)
       ishort = implicit_short ? "( -#{short_implicit} ) " : ''
-      str    = "#{required_desc}#{ishort}#{desc}#{default_desc}"
+      str    = "#{required_desc}#{ishort}#{desc}#{enum_desc}#{default_desc}"
       return [] if str.empty?
+
       string_to_lines(str, max: line_width)
     end
 
@@ -175,12 +203,15 @@ class RakeCommander
     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
+      return unless default?
+
+      " { Default: '#{default}' }"
+    end
+
+    def enum_desc
+      return unless enum?
+
+      " Options: [ #{enum_options.join(' | ')} ]."
     end
 
     # Helper to simplify `short` and `name` capture from arguments and keyed arguments.
@@ -191,8 +222,11 @@ class RakeCommander
       name  ||= capture_arguments_name!(args, sample_n_short: sample && short)
 
       unless sample
-        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)
+        msg = "A short of one letter should be provided. Given: #{short}"
+        raise ArgumentError, msg unless self.class.valid_short?(short)
+
+        msg = "A name should be provided. Given: #{name}"
+        raise ArgumentError, msg unless self.class.valid_name?(name)
       end
 
       [short, name]
@@ -213,41 +247,52 @@ class RakeCommander
     # @note if found it removes it from args.
     # @return [String, Symbol, NilClass]
     def capture_arguments_name!(args, sample_n_short: false)
-      name = nil
+      name   = nil
       name ||= self.class.capture_arguments_name!(args, symbol: true)
       name ||= self.class.capture_arguments_name!(args, symbol: true, strict: false)
       name ||= self.class.capture_arguments_name!(args)
-      name || self.class.capture_arguments_name!(args, strict: false) unless sample_n_short
+      name ||= self.class.capture_arguments_name!(args, strict: false) unless sample_n_short
+      name
     end
 
     # The remaining `args` received in the initialization
     def other_args(*args)
       @other_args ||= []
-      if args.empty?
-        @other_args
-      else
-        @other_args.push(*args)
-      end
+      return @other_args if args.empty?
+
+      @other_args.push(*args)
     end
 
     # It consumes `other_args`, to prevent direct overrides to be overriden by it.
+    # @note at the end we will pass the switch arguments to OptsParser.
     def configure_other
-      @type_coercion ||= fetch_type_from_other
-      @desc          ||= fetch_desc_from_other
+      @type_coercion = fetch_type_from_other(@type_coercion)
+      @desc          = fetch_desc_from_other(@desc)
       nil
     end
 
-    def fetch_type_from_other
-      return nil unless type = other_args.find {|arg| arg.is_a?(Class)}
-      type.tap { other_args.delete(type) }
+    def fetch_type_from_other(original = nil)
+      other_type = fetch_type!(other_args)
+
+      return original if original
+
+      other_type
+    end
+
+    def fetch_desc_from_other(original = nil)
+      joined_lines(original, fetch_desc!(other_args))
     end
 
-    def fetch_desc_from_other
-      return nil unless value = other_args.find {|arg| arg.is_a?(String)}
-      other_args.dup.each do |val|
-        other_args.delete(val) if val.is_a?(String)
+    def dupped_type
+      return @type_coercion if @type_coercion.is_a?(Class)
+      return @type_coercion unless @type_coercion.is_a?(Array)
+
+      @type_coercion.map do |value|
+        next value if value.is_a?(Class)
+        next value unless value.respond_to?(:dup)
+
+        value.dup
       end
-      value
     end
   end
 end

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

@@ -3,12 +3,12 @@ class RakeCommander
     # Offers helpers to treat `ARGV`
     module Arguments
       RAKE_COMMAND_EXTENDED_OPTIONS_START = '--'.freeze
-      NAME_ARGUMENT    = /^--(?<option>[\w_-]*).*?$/.freeze
-      BOOLEAN_ARGUMENT = /(?:^|--)no-(?<option>[\w_-]*).*?$/.freeze
+      NAME_ARGUMENT    = /^--(?<option>[\w_-]*).*?$/
+      BOOLEAN_ARGUMENT = /(?:^|--)no-(?<option>[\w_-]*).*?$/
 
       class << self
         def included(base)
-          super(base)
+          super
           base.extend ClassMethods
         end
       end
@@ -20,6 +20,7 @@ class RakeCommander
         # @return [Boolean] whether enhanced parsing should be switched on or off.
         def argv_with_enhanced_syntax?(argv = ARGV)
           return false unless argv.is_a?(Array)
+
           argv.include?(RAKE_COMMAND_EXTENDED_OPTIONS_START)
         end
 
@@ -41,6 +42,7 @@ class RakeCommander
         def argv_cropping_for_rake(value = :not_used)
           @argv_cropping_for_rake = true if @argv_cropping_for_rake.nil?
           return @argv_cropping_for_rake if value == :not_used
+
           @argv_cropping_for_rake = !!value
         end
 
@@ -51,8 +53,8 @@ class RakeCommander
         # @param argv [Array<String>] the command line arguments array.
         # @return [Array<String>] the target arguments to be parsed by `RakeCommander::Options`
         def argv_extended_options(argv = ARGV.dup)
-          if idx = argv.index(RAKE_COMMAND_EXTENDED_OPTIONS_START)
-            argv[idx+1..-1]
+          if (idx = argv.index(RAKE_COMMAND_EXTENDED_OPTIONS_START))
+            argv[idx + 1..]
           else
             []
           end
@@ -63,9 +65,11 @@ class RakeCommander
         # @return [Array<String>] the argv without the extended options of this gem.
         def argv_rake_native_arguments(argv = ARGV.dup)
           return argv unless argv_cropping_for_rake
-          if idx = argv.index(RAKE_COMMAND_EXTENDED_OPTIONS_START)
+
+          if (idx = argv.index(RAKE_COMMAND_EXTENDED_OPTIONS_START))
             argv = argv[0..idx]
           end
+
           argv
         end
 
@@ -77,10 +81,10 @@ class RakeCommander
         #     - So some tidy up is necessary and the head of the command (i.e. `rake some:task --`)
         #       should be excluded from arguments to input to the options parser.
         # @see `RakeCommander::Options#parse_options`
-        def parse_options(argv = ARGV, *args, **kargs, &block)
+        def parse_options(argv = ARGV, *_args, **_kargs)
           argv = argv_extended_options(argv)
           argv = argv_pre_parsed(argv, options: options_hash(with_implicit: true))
-          super(argv, *args, **kargs, &block)
+          super
         end
 
         # Options with arguments should not take another option as value.
@@ -95,22 +99,31 @@ class RakeCommander
         #   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`
+        #   1. `-abc ARGUMENT` where only `c` receives the argument
+        #     becomes `-ab -c ARGUMENT`
+        #   2. `-abc ARGUMENT` where `b` and `c` are argument receivers
+        #     becomes `-a -b nil -c ARGUMENT`
+        #   3. `-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 argv_pre_parsed(argv = ARGV, options:)
-          pre_parsed = explicit_argument_options(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)
@@ -139,17 +152,24 @@ class RakeCommander
         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`
+        #   1. `-abc ARGUMENT` where only `c` receives the argument
+        #     becomes `:a :b :c ARGUMENT`
+        #   2. `-abc ARGUMENT` where `b` and `c` are argument receivers
+        #     becomes `:a :b nil :c ARGUMENT`
+        #   3. `-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
@@ -163,14 +183,17 @@ class RakeCommander
         # @param groups [@see #pair_symbols_with_strings]
         def insert_missing_argument_to_groups(groups, options)
           groups.each do |group|
-            args = group.dup
+            args    = group.dup
             opt_ref = args.shift
+
             next unless args.empty?
             next unless opt_ref.is_a?(Symbol)
-            next unless opt = _retrieve_option_ref(opt_ref, options)
+            next unless (opt = _retrieve_option_ref(opt_ref, options))
             next unless opt.argument?
+
             next group.push(opt.default) if opt.default?
-            next unless opt.argument_required?
+            next                         unless opt.argument_required?
+
             group.push(nil)
           end
         end
@@ -180,11 +203,13 @@ class RakeCommander
         # @return [RakeCommander::Option, NilClass]
         def _retrieve_option_ref(opt_ref, options)
           opt = options[opt_ref]
-          return opt if     opt
-          return nil unless match   = opt_ref.to_s.match(BOOLEAN_ARGUMENT)
-          return nil unless opt_ref = match[:option]
-          return nil unless opt     = options[opt_ref.to_sym]
-          return nil unless opt.boolean_name?
+
+          return opt if opt
+          return     unless (match   = opt_ref.to_s.match(BOOLEAN_ARGUMENT))
+          return     unless (opt_ref = match[:option])
+          return     unless (opt     = options[opt_ref.to_sym])
+          return     unless opt.boolean_name?
+
           opt
         end
 
@@ -193,6 +218,7 @@ class RakeCommander
         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])