cri 2.11.0 → 2.12.0

data/lib/cri/option_parser.rb

@@ -71,8 +71,7 @@ module Cri
       end
 
       def message
-        name = @definition[:long] ? '--' + @definition[:long] : '-' + @definition[:short]
-        "invalid value #{value.inspect} for #{name} option"
+        "invalid value #{value.inspect} for #{@definition.formatted_name} option"
       end
     end
 
@@ -99,38 +98,26 @@ module Cri
     # @return [Hash] The already parsed options.
     attr_reader :options
 
-    # @return [Array] The arguments that have already been parsed, including
-    #   the -- separator.
-    attr_reader :raw_arguments
-
     # The options and arguments that have not yet been processed. If the
     # parser wasn’t stopped (using {#stop}), this list will be empty.
     #
     # @return [Array] The not yet parsed options and arguments.
     attr_reader :unprocessed_arguments_and_options
 
-    # Parses the command-line arguments. See the instance `parse` method for
-    # details.
-    #
-    # @param [Array<String>] arguments_and_options An array containing the
-    #   command-line arguments (will probably be `ARGS` for a root command)
-    #
-    # @param [Array<Hash>] definitions An array of option definitions
-    #
-    # @return [Cri::OptionParser] The option parser self
-    def self.parse(arguments_and_options, definitions)
-      new(arguments_and_options, definitions).run
-    end
-
     # Creates a new parser with the given options/arguments and definitions.
     #
     # @param [Array<String>] arguments_and_options An array containing the
     #   command-line arguments (will probably be `ARGS` for a root command)
     #
-    # @param [Array<Hash>] definitions An array of option definitions
-    def initialize(arguments_and_options, definitions)
+    # @param [Array<Cri::OptionDefinition>] option_defns An array of option
+    #   definitions
+    #
+    # @param [Array<Cri::ParamDefinition>] param_defns An array of parameter
+    #   definitions
+    def initialize(arguments_and_options, option_defns, param_defns)
       @unprocessed_arguments_and_options = arguments_and_options.dup
-      @definitions = definitions
+      @option_defns = option_defns
+      @param_defns = param_defns
 
       @options       = {}
       @raw_arguments = []
@@ -139,17 +126,6 @@ module Cri
       @no_more_options = false
     end
 
-    # Returns the arguments that have already been parsed.
-    #
-    # If the parser was stopped before it finished, this will not contain all
-    # options and `unprocessed_arguments_and_options` will contain what is
-    # left to be processed.
-    #
-    # @return [Array] The already parsed arguments.
-    def arguments
-      @raw_arguments.reject { |a| a == '--' }.freeze
-    end
-
     # @return [Boolean] true if the parser is running, false otherwise.
     def running?
       @running
@@ -200,10 +176,16 @@ module Cri
       @running = false
     end
 
+    # @return [Cri::ArgumentList] The list of arguments that have already been
+    #   parsed, excluding the -- separator.
+    def arguments
+      ArgumentList.new(@raw_arguments, @param_defns)
+    end
+
     private
 
     def add_defaults
-      @definitions.each { |d| add_default_option(d) }
+      @option_defns.each { |d| add_default_option(d) }
     end
 
     def handle_dashdash(elem)
@@ -222,20 +204,20 @@ module Cri
       end
 
       # Find definition
-      definition = @definitions.find { |d| d[:long] == option_key }
-      raise IllegalOptionError.new(option_key) if definition.nil?
+      option_defn = @option_defns.find { |d| d.long == option_key }
+      raise IllegalOptionError.new(option_key) if option_defn.nil?
 
-      if %i[required optional].include?(definition[:argument])
+      if %i[required optional].include?(option_defn.argument)
         # Get option value if necessary
         if option_value.nil?
-          option_value = find_option_value(definition, option_key)
+          option_value = find_option_value(option_defn, option_key)
         end
 
         # Store option
-        add_option(definition, option_value)
+        add_option(option_defn, option_value)
       else
         # Store option
-        add_option(definition, true)
+        add_option(option_defn, true)
       end
     end
 
@@ -246,28 +228,28 @@ module Cri
       # For each key
       option_keys.each do |option_key|
         # Find definition
-        definition = @definitions.find { |d| d[:short] == option_key }
-        raise IllegalOptionError.new(option_key) if definition.nil?
+        option_defn = @option_defns.find { |d| d.short == option_key }
+        raise IllegalOptionError.new(option_key) if option_defn.nil?
 
-        if %i[required optional].include?(definition[:argument])
+        if %i[required optional].include?(option_defn.argument)
           # Get option value
-          option_value = find_option_value(definition, option_key)
+          option_value = find_option_value(option_defn, option_key)
 
           # Store option
-          add_option(definition, option_value)
+          add_option(option_defn, option_value)
         else
           # Store option
-          add_option(definition, true)
+          add_option(option_defn, true)
         end
       end
     end
 
-    def find_option_value(definition, option_key)
+    def find_option_value(option_defn, option_key)
       option_value = @unprocessed_arguments_and_options.shift
       if option_value.nil? || option_value =~ /^-/
-        if definition[:argument] == :optional && definition[:default]
-          option_value = definition[:default]
-        elsif definition[:argument] == :required
+        if option_defn.argument == :optional && option_defn.default
+          option_value = option_defn.default
+        elsif option_defn.argument == :required
           raise OptionRequiresAnArgumentError.new(option_key)
         else
           @unprocessed_arguments_and_options.unshift(option_value)
@@ -277,12 +259,12 @@ module Cri
       option_value
     end
 
-    def add_option(definition, value, transform: true)
-      key = key_for(definition)
+    def add_option(option_defn, value, transform: true)
+      key = key_for(option_defn)
 
-      value = transform ? transform_value(definition, value) : value
+      value = transform ? transform_value(option_defn, value) : value
 
-      if definition[:multiple]
+      if option_defn.multiple
         options[key] ||= []
         options[key] << value
       else
@@ -292,32 +274,32 @@ module Cri
       delegate&.option_added(key, value, self)
     end
 
-    def add_default_option(definition)
-      key = key_for(definition)
+    def add_default_option(option_defn)
+      key = key_for(option_defn)
       return if options.key?(key)
 
-      value = definition[:default]
+      value = option_defn.default
       return unless value
 
-      add_option(definition, value, transform: false)
+      add_option(option_defn, value, transform: false)
     end
 
-    def transform_value(definition, value)
-      transformer = definition[:transform]
+    def transform_value(option_defn, value)
+      transformer = option_defn.transform
 
       if transformer
         begin
           transformer.call(value)
         rescue StandardError
-          raise IllegalOptionValueError.new(definition, value)
+          raise IllegalOptionValueError.new(option_defn, value)
         end
       else
         value
       end
     end
 
-    def key_for(definition)
-      (definition[:long] || definition[:short]).to_sym
+    def key_for(option_defn)
+      (option_defn.long || option_defn.short).to_sym
     end
 
     def add_argument(value)

data/lib/cri/param_definition.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Cri
+  # The definition of a parameter.
+  class ParamDefinition
+    attr_reader :name
+
+    def initialize(name:)
+      @name = name
+    end
+  end
+end

data/lib/cri/version.rb

@@ -2,5 +2,5 @@
 
 module Cri
   # The current Cri version.
-  VERSION = '2.11.0'
+  VERSION = '2.12.0'
 end

data/test/test_argument_list.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'helper'
+
+module Cri
+  class ArgumentListTestCase < Cri::TestCase
+    def test_empty
+      args = Cri::ArgumentList.new([], [])
+
+      assert_equal([], args.to_a)
+      assert(args.empty?)
+      assert_equal(0, args.size)
+      assert_equal(nil, args[0])
+      assert_equal(nil, args[:abc])
+    end
+
+    def test_no_param_defns
+      args = Cri::ArgumentList.new(%w[a b c], [])
+
+      assert_equal(%w[a b c], args.to_a)
+      refute(args.empty?)
+      assert_equal(3, args.size)
+      assert_equal('a', args[0])
+      assert_equal('b', args[1])
+      assert_equal('c', args[2])
+      assert_equal(nil, args[3])
+      assert_equal(nil, args[:abc])
+    end
+
+    def test_enum
+      args = Cri::ArgumentList.new(%w[a b c], [])
+
+      assert_equal(%w[A B C], args.map(&:upcase))
+    end
+
+    def test_no_method_error
+      args = Cri::ArgumentList.new(%w[a b c], [])
+
+      refute args.respond_to?(:oink)
+      assert_raises(NoMethodError, 'x') do
+        args.oink
+      end
+    end
+
+    def test_dash_dash
+      args = Cri::ArgumentList.new(%w[a -- b -- c], [])
+
+      assert_equal(%w[a b c], args.to_a)
+    end
+
+    def test_one_param_defn_matched
+      param_defns = [Cri::ParamDefinition.new(name: 'filename')]
+      args = Cri::ArgumentList.new(%w[notbad.jpg], param_defns)
+
+      assert_equal(['notbad.jpg'], args.to_a)
+      assert_equal(1, args.size)
+      assert_equal('notbad.jpg', args[0])
+      assert_equal('notbad.jpg', args[:filename])
+    end
+
+    def test_one_param_defn_too_many
+      param_defns = [Cri::ParamDefinition.new(name: 'filename')]
+
+      exception = assert_raises(Cri::ArgumentList::ArgumentCountMismatchError) do
+        Cri::ArgumentList.new(%w[notbad.jpg verybad.jpg], param_defns)
+      end
+      assert_equal('incorrect number of arguments given: expected 1, but got 2', exception.message)
+    end
+
+    def test_one_param_defn_too_few
+      param_defns = [Cri::ParamDefinition.new(name: 'filename')]
+
+      exception = assert_raises(Cri::ArgumentList::ArgumentCountMismatchError) do
+        Cri::ArgumentList.new(%w[], param_defns)
+      end
+      assert_equal('incorrect number of arguments given: expected 1, but got 0', exception.message)
+    end
+  end
+end

data/test/test_command.rb

@@ -479,8 +479,8 @@ module Cri
 
       # Check option definitions
       assert_equal 1, cmd.option_definitions.size
-      opt_def = cmd.option_definitions.to_a[0]
-      assert_equal 'help', opt_def[:long]
+      opt_defn = cmd.option_definitions.to_a[0]
+      assert_equal 'help', opt_defn.long
 
       # Check subcommand
       assert_equal 1,      cmd.subcommands.size
@@ -697,5 +697,22 @@ module Cri
 
       assert_equal "opts={:aaa=>\"test\"} args=--test,value\n", out
     end
+
+    def test_wrong_number_of_args
+      cmd = Cri::Command.define do
+        name 'publish'
+        param :filename
+      end
+
+      out, err = capture_io_while do
+        err = assert_raises SystemExit do
+          cmd.run([])
+        end
+        assert_equal 1, err.status
+      end
+
+      assert_equal [], lines(out)
+      assert_equal ['publish: incorrect number of arguments given: expected 1, but got 0'], lines(err)
+    end
   end
 end

data/test/test_command_dsl.rb

@@ -49,7 +49,7 @@ module Cri
             { short: 'f', long: 'fff', desc: 'opt f', argument: :forbidden, multiple: false, hidden: true,  block: nil, default: nil, transform: nil },
           ],
         )
-      actual_option_definitions = Set.new(command.option_definitions)
+      actual_option_definitions = Set.new(command.option_definitions.map(&:to_h))
       assert_equal expected_option_definitions, actual_option_definitions
     end
 
@@ -84,7 +84,7 @@ module Cri
             { short: nil, long: 'long', desc: 'long',  argument: :forbidden, multiple: false, hidden: false, block: nil, default: nil, transform: nil },
           ],
         )
-      actual_option_definitions = Set.new(command.option_definitions)
+      actual_option_definitions = Set.new(command.option_definitions.map(&:to_h))
       assert_equal expected_option_definitions, actual_option_definitions
     end
 
@@ -109,7 +109,7 @@ module Cri
             { short: 'o', long: 'optional', desc: 'opt',  argument: :optional,  multiple: true, hidden: false, block: nil, default: nil, transform: nil },
           ],
         )
-      actual_option_definitions = Set.new(command.option_definitions)
+      actual_option_definitions = Set.new(command.option_definitions.map(&:to_h))
       assert_equal expected_option_definitions, actual_option_definitions
     end
 
@@ -134,7 +134,7 @@ module Cri
             { short: 'o', long: 'optional', desc: 'opt',  argument: :optional,  multiple: false, hidden: true, block: nil, default: nil, transform: nil },
           ],
         )
-      actual_option_definitions = Set.new(command.option_definitions)
+      actual_option_definitions = Set.new(command.option_definitions.map(&:to_h))
       assert_equal expected_option_definitions, actual_option_definitions
     end
 
@@ -240,5 +240,33 @@ module Cri
       command.run(%w[certainly])
       assert_equal 'certainly', $did_it_work
     end
+
+    def test_params
+      # Define
+      dsl = Cri::CommandDSL.new
+      dsl.instance_eval do
+        name        'moo'
+        usage       'dunno whatever'
+        summary     'does stuff'
+        description 'This command does a lot of stuff.'
+
+        param :foo
+        param :bar
+        param :qux
+
+        run do |_opts, args|
+          $args_num = { foo: args[0], bar: args[1], qux: args[2] }
+          $args_sym = { foo: args[:foo], bar: args[:bar], qux: args[:qux] }
+        end
+      end
+      command = dsl.command
+
+      # Run
+      $args_num = '???'
+      $args_sym = '???'
+      command.run(%w[a b c])
+      assert_equal({ foo: 'a', bar: 'b', qux: 'c' }, $args_num)
+      assert_equal({ foo: 'a', bar: 'b', qux: 'c' }, $args_sym)
+    end
   end
 end

data/test/test_option_parser.rb

@@ -5,431 +5,432 @@ require 'helper'
 module Cri
   class OptionParserTestCase < Cri::TestCase
     def test_parse_without_options
-      input       = %w[foo bar baz]
-      definitions = []
+      input = %w[foo bar baz]
+      opt_defns = []
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({}, parser.options)
-      assert_equal(%w[foo bar baz], parser.arguments)
+      assert_equal(%w[foo bar baz], parser.arguments.to_a)
     end
 
     def test_parse_with_invalid_option
-      input       = %w[foo -x]
-      definitions = []
+      input = %w[foo -x]
+      opt_defns = []
 
       assert_raises(Cri::OptionParser::IllegalOptionError) do
-        Cri::OptionParser.parse(input, definitions)
+        Cri::OptionParser.new(input, opt_defns, []).run
       end
     end
 
     def test_parse_with_unused_options
-      input       = %w[foo]
-      definitions = [
+      input = %w[foo]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :forbidden },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert(!parser.options[:aaa])
     end
 
     def test_parse_with_long_valueless_option
-      input       = %w[foo --aaa bar]
-      definitions = [
+      input = %w[foo --aaa bar]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :forbidden },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert(parser.options[:aaa])
-      assert_equal(%w[foo bar], parser.arguments)
+      assert_equal(%w[foo bar], parser.arguments.to_a)
     end
 
     def test_parse_with_long_valueful_option
-      input       = %w[foo --aaa xxx bar]
-      definitions = [
+      input = %w[foo --aaa xxx bar]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :required },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ aaa: 'xxx' }, parser.options)
-      assert_equal(%w[foo bar], parser.arguments)
+      assert_equal(%w[foo bar], parser.arguments.to_a)
     end
 
     def test_parse_with_long_valueful_equalsign_option
-      input       = %w[foo --aaa=xxx bar]
-      definitions = [
+      input = %w[foo --aaa=xxx bar]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :required },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ aaa: 'xxx' }, parser.options)
-      assert_equal(%w[foo bar], parser.arguments)
+      assert_equal(%w[foo bar], parser.arguments.to_a)
     end
 
     def test_parse_with_long_valueful_option_with_missing_value
-      input       = %w[foo --aaa]
-      definitions = [
+      input = %w[foo --aaa]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :required },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
       assert_raises(Cri::OptionParser::OptionRequiresAnArgumentError) do
-        Cri::OptionParser.parse(input, definitions)
+        Cri::OptionParser.new(input, opt_defns, []).run
       end
     end
 
     def test_parse_with_two_long_valueful_options
-      input       = %w[foo --all --port 2]
-      definitions = [
+      input = %w[foo --all --port 2]
+      opt_defns = [
         { long: 'all',  short: 'a', argument: :required },
         { long: 'port', short: 'p', argument: :required },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
       assert_raises(Cri::OptionParser::OptionRequiresAnArgumentError) do
-        Cri::OptionParser.parse(input, definitions)
+        Cri::OptionParser.new(input, opt_defns, []).run
       end
     end
 
     def test_parse_with_long_valueless_option_with_optional_value
-      input       = %w[foo --aaa]
-      definitions = [
+      input = %w[foo --aaa]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :optional },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert(parser.options[:aaa])
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_long_valueful_option_with_optional_value
-      input       = %w[foo --aaa xxx]
-      definitions = [
+      input = %w[foo --aaa xxx]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :optional },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ aaa: 'xxx' }, parser.options)
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_long_valueless_option_with_optional_value_and_more_options
-      input       = %w[foo --aaa -b -c]
-      definitions = [
+      input = %w[foo --aaa -b -c]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :optional  },
         { long: 'bbb', short: 'b', argument: :forbidden },
         { long: 'ccc', short: 'c', argument: :forbidden },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert(parser.options[:aaa])
       assert(parser.options[:bbb])
       assert(parser.options[:ccc])
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_short_valueless_options
-      input       = %w[foo -a bar]
-      definitions = [
+      input = %w[foo -a bar]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :forbidden },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert(parser.options[:aaa])
-      assert_equal(%w[foo bar], parser.arguments)
+      assert_equal(%w[foo bar], parser.arguments.to_a)
     end
 
     def test_parse_with_short_valueful_option_with_missing_value
-      input       = %w[foo -a]
-      definitions = [
+      input = %w[foo -a]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :required },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
       assert_raises(Cri::OptionParser::OptionRequiresAnArgumentError) do
-        Cri::OptionParser.parse(input, definitions)
+        Cri::OptionParser.new(input, opt_defns, []).run
       end
     end
 
     def test_parse_with_short_combined_valueless_options
-      input       = %w[foo -abc bar]
-      definitions = [
+      input = %w[foo -abc bar]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :forbidden },
         { long: 'bbb', short: 'b', argument: :forbidden },
         { long: 'ccc', short: 'c', argument: :forbidden },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert(parser.options[:aaa])
       assert(parser.options[:bbb])
       assert(parser.options[:ccc])
-      assert_equal(%w[foo bar], parser.arguments)
+      assert_equal(%w[foo bar], parser.arguments.to_a)
     end
 
     def test_parse_with_short_combined_valueful_options_with_missing_value
-      input       = %w[foo -abc bar qux]
-      definitions = [
+      input = %w[foo -abc bar qux]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :required  },
         { long: 'bbb', short: 'b', argument: :forbidden },
         { long: 'ccc', short: 'c', argument: :forbidden },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal('bar', parser.options[:aaa])
       assert(parser.options[:bbb])
       assert(parser.options[:ccc])
-      assert_equal(%w[foo qux], parser.arguments)
+      assert_equal(%w[foo qux], parser.arguments.to_a)
     end
 
     def test_parse_with_two_short_valueful_options
-      input       = %w[foo -a -p 2]
-      definitions = [
+      input = %w[foo -a -p 2]
+      opt_defns = [
         { long: 'all',  short: 'a', argument: :required },
         { long: 'port', short: 'p', argument: :required },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
       assert_raises(Cri::OptionParser::OptionRequiresAnArgumentError) do
-        Cri::OptionParser.parse(input, definitions)
+        Cri::OptionParser.new(input, opt_defns, []).run
       end
     end
 
     def test_parse_with_short_valueless_option_with_optional_value
-      input       = %w[foo -a]
-      definitions = [
+      input = %w[foo -a]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :optional },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert(parser.options[:aaa])
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_short_valueful_option_with_optional_value
-      input       = %w[foo -a xxx]
-      definitions = [
+      input = %w[foo -a xxx]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :optional },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ aaa: 'xxx' }, parser.options)
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_short_valueless_option_with_optional_value_and_more_options
-      input       = %w[foo -a -b -c]
-      definitions = [
+      input = %w[foo -a -b -c]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :optional  },
         { long: 'bbb', short: 'b', argument: :forbidden },
         { long: 'ccc', short: 'c', argument: :forbidden },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert(parser.options[:aaa])
       assert(parser.options[:bbb])
       assert(parser.options[:ccc])
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_single_hyphen
-      input       = %w[foo - bar]
-      definitions = []
+      input = %w[foo - bar]
+      opt_defns = []
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({}, parser.options)
-      assert_equal(['foo', '-', 'bar'], parser.arguments)
+      assert_equal(['foo', '-', 'bar'], parser.arguments.to_a)
     end
 
     def test_parse_with_end_marker
-      input       = %w[foo bar -- -x --yyy -abc]
-      definitions = []
+      input = %w[foo bar -- -x --yyy -abc]
+      opt_defns = []
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({}, parser.options)
-      assert_equal(['foo', 'bar', '-x', '--yyy', '-abc'], parser.arguments)
+      assert_equal(['foo', 'bar', '-x', '--yyy', '-abc'], parser.arguments.to_a)
     end
 
     def test_parse_with_end_marker_between_option_key_and_value
-      input       = %w[foo --aaa -- zzz]
-      definitions = [
+      input = %w[foo --aaa -- zzz]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :required },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
       assert_raises(Cri::OptionParser::OptionRequiresAnArgumentError) do
-        Cri::OptionParser.parse(input, definitions)
+        Cri::OptionParser.new(input, opt_defns, []).run
       end
     end
 
     def test_parse_with_multiple_options
       input = %w[foo -o test -o test2 -v -v -v]
-      definitions = [
+      opt_defns = [
         { long: 'long', short: 'o', argument: :required, multiple: true },
         { long: 'verbose', short: 'v', multiple: true },
-      ]
-      parser = Cri::OptionParser.parse(input, definitions)
+      ].map { |hash| make_opt_defn(hash) }
+
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal(%w[test test2], parser.options[:long])
       assert_equal(3, parser.options[:verbose].size)
     end
 
     def test_parse_with_default_required_unspecified
-      input       = %w[foo]
-      definitions = [
+      input = %w[foo]
+      opt_defns = [
         { long: 'animal', short: 'a', argument: :required, default: 'donkey' },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ animal: 'donkey' }, parser.options)
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_default_required_no_value
-      input       = %w[foo -a]
-      definitions = [
+      input = %w[foo -a]
+      opt_defns = [
         { long: 'animal', short: 'a', argument: :required, default: 'donkey' },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
       assert_raises(Cri::OptionParser::OptionRequiresAnArgumentError) do
-        Cri::OptionParser.parse(input, definitions)
+        Cri::OptionParser.new(input, opt_defns, []).run
       end
     end
 
     def test_parse_with_default_required_value
-      input       = %w[foo -a giraffe]
-      definitions = [
+      input = %w[foo -a giraffe]
+      opt_defns = [
         { long: 'animal', short: 'a', argument: :required, default: 'donkey' },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ animal: 'giraffe' }, parser.options)
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_default_optional_unspecified
-      input       = %w[foo]
-      definitions = [
+      input = %w[foo]
+      opt_defns = [
         { long: 'animal', short: 'a', argument: :optional, default: 'donkey' },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ animal: 'donkey' }, parser.options)
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_default_optional_no_value
-      input       = %w[foo -a]
-      definitions = [
+      input = %w[foo -a]
+      opt_defns = [
         { long: 'animal', short: 'a', argument: :optional, default: 'donkey' },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ animal: 'donkey' }, parser.options)
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_default_optional_value
-      input       = %w[foo -a giraffe]
-      definitions = [
+      input = %w[foo -a giraffe]
+      opt_defns = [
         { long: 'animal', short: 'a', argument: :optional, default: 'donkey' },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ animal: 'giraffe' }, parser.options)
-      assert_equal(['foo'], parser.arguments)
+      assert_equal(['foo'], parser.arguments.to_a)
     end
 
     def test_parse_with_default_optional_value_and_arg
-      input       = %w[foo -a gi raffe]
-      definitions = [
+      input = %w[foo -a gi raffe]
+      opt_defns = [
         { long: 'animal', short: 'a', argument: :optional, default: 'donkey' },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ animal: 'gi' }, parser.options)
-      assert_equal(%w[foo raffe], parser.arguments)
+      assert_equal(%w[foo raffe], parser.arguments.to_a)
     end
 
     def test_parse_with_combined_required_options
-      input       = %w[foo -abc xxx yyy zzz]
-      definitions = [
+      input = %w[foo -abc xxx yyy zzz]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :forbidden },
         { long: 'bbb', short: 'b', argument: :required },
         { long: 'ccc', short: 'c', argument: :required },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ aaa: true, bbb: 'xxx', ccc: 'yyy' }, parser.options)
-      assert_equal(%w[foo zzz], parser.arguments)
+      assert_equal(%w[foo zzz], parser.arguments.to_a)
     end
 
     def test_parse_with_combined_optional_options
-      input       = %w[foo -abc xxx yyy zzz]
-      definitions = [
+      input = %w[foo -abc xxx yyy zzz]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :forbidden },
         { long: 'bbb', short: 'b', argument: :optional },
         { long: 'ccc', short: 'c', argument: :required },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ aaa: true, bbb: 'xxx', ccc: 'yyy' }, parser.options)
-      assert_equal(%w[foo zzz], parser.arguments)
+      assert_equal(%w[foo zzz], parser.arguments.to_a)
     end
 
     def test_parse_with_combined_optional_options_with_missing_value
-      input       = %w[foo -abc xxx]
-      definitions = [
+      input = %w[foo -abc xxx]
+      opt_defns = [
         { long: 'aaa', short: 'a', argument: :forbidden },
         { long: 'bbb', short: 'b', argument: :required },
         { long: 'ccc', short: 'c', argument: :optional, default: 'c default' },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ aaa: true, bbb: 'xxx', ccc: 'c default' }, parser.options)
-      assert_equal(%w[foo], parser.arguments)
+      assert_equal(%w[foo], parser.arguments.to_a)
     end
 
     def test_parse_with_transform_proc
-      input       = %w[--port 123]
-      definitions = [
+      input = %w[--port 123]
+      opt_defns = [
         { long: 'port', short: 'p', argument: :required, transform: ->(x) { Integer(x) } },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ port: 123 }, parser.options)
-      assert_equal([], parser.arguments)
+      assert_equal([], parser.arguments.to_a)
     end
 
     def test_parse_with_transform_method
-      input       = %w[--port 123]
-      definitions = [
+      input = %w[--port 123]
+      opt_defns = [
         { long: 'port', short: 'p', argument: :required, transform: method(:Integer) },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ port: 123 }, parser.options)
-      assert_equal([], parser.arguments)
+      assert_equal([], parser.arguments.to_a)
     end
 
     def test_parse_with_transform_object
@@ -439,15 +440,15 @@ module Cri
         end
       end.new
 
-      input       = %w[--port 123]
-      definitions = [
+      input = %w[--port 123]
+      opt_defns = [
         { long: 'port', short: 'p', argument: :required, transform: port },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ port: 123 }, parser.options)
-      assert_equal([], parser.arguments)
+      assert_equal([], parser.arguments.to_a)
     end
 
     def test_parse_with_transform_default
@@ -458,27 +459,108 @@ module Cri
         end
       end.new
 
-      input       = %w[]
-      definitions = [
+      input = %w[]
+      opt_defns = [
         { long: 'port', short: 'p', argument: :required, default: 8080, transform: port },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
-      parser = Cri::OptionParser.parse(input, definitions)
+      parser = Cri::OptionParser.new(input, opt_defns, []).run
 
       assert_equal({ port: 8080 }, parser.options)
-      assert_equal([], parser.arguments)
+      assert_equal([], parser.arguments.to_a)
     end
 
     def test_parse_with_transform_exception
-      input       = %w[--port one_hundred_and_twenty_three]
-      definitions = [
+      input = %w[--port one_hundred_and_twenty_three]
+      opt_defns = [
         { long: 'port', short: 'p', argument: :required, transform: method(:Integer) },
-      ]
+      ].map { |hash| make_opt_defn(hash) }
 
       exception = assert_raises(Cri::OptionParser::IllegalOptionValueError) do
-        Cri::OptionParser.parse(input, definitions)
+        Cri::OptionParser.new(input, opt_defns, []).run
       end
       assert_equal('invalid value "one_hundred_and_twenty_three" for --port option', exception.message)
     end
+
+    def test_parse_with_param_defns
+      input       = %w[localhost]
+      param_defns = [
+        { name: 'host' },
+      ].map { |hash| Cri::ParamDefinition.new(hash) }
+
+      parser = Cri::OptionParser.new(input, [], param_defns).run
+      assert_equal({}, parser.options)
+      assert_equal('localhost', parser.arguments[0])
+      assert_equal('localhost', parser.arguments[:host])
+    end
+
+    def test_parse_with_param_defns_too_few_args
+      input       = []
+      param_defns = [
+        { name: 'host' },
+      ].map { |hash| Cri::ParamDefinition.new(hash) }
+
+      parser = Cri::OptionParser.new(input, [], param_defns).run
+      exception = assert_raises(Cri::ArgumentList::ArgumentCountMismatchError) do
+        parser.arguments
+      end
+      assert_equal('incorrect number of arguments given: expected 1, but got 0', exception.message)
+    end
+
+    def test_parse_with_param_defns_too_many_args
+      input       = %w[localhost oink]
+      param_defns = [
+        { name: 'host' },
+      ].map { |hash| Cri::ParamDefinition.new(hash) }
+
+      parser = Cri::OptionParser.new(input, [], param_defns).run
+      exception = assert_raises(Cri::ArgumentList::ArgumentCountMismatchError) do
+        parser.arguments
+      end
+      assert_equal('incorrect number of arguments given: expected 1, but got 2', exception.message)
+    end
+
+    def test_parse_with_param_defns_invalid_key
+      input       = %w[localhost]
+      param_defns = [
+        { name: 'host' },
+      ].map { |hash| Cri::ParamDefinition.new(hash) }
+
+      parser = Cri::OptionParser.new(input, [], param_defns).run
+
+      exception = assert_raises(ArgumentError) do
+        parser.arguments['oink']
+      end
+      assert_equal('argument lists can be indexed using a Symbol or an Integer, but not a String', exception.message)
+    end
+
+    def test_parse_with_param_defns_two_params
+      input       = %w[localhost example.com]
+      param_defns = [
+        { name: 'source' },
+        { name: 'target' },
+      ].map { |hash| Cri::ParamDefinition.new(hash) }
+
+      parser = Cri::OptionParser.new(input, [], param_defns).run
+      assert_equal({}, parser.options)
+      assert_equal('localhost', parser.arguments[0])
+      assert_equal('localhost', parser.arguments[:source])
+      assert_equal('example.com', parser.arguments[1])
+      assert_equal('example.com', parser.arguments[:target])
+    end
+
+    def make_opt_defn(hash)
+      Cri::OptionDefinition.new(
+        short:     hash.fetch(:short, nil),
+        long:      hash.fetch(:long, nil),
+        desc:      hash.fetch(:desc, nil),
+        argument:  hash.fetch(:argument, nil),
+        multiple:  hash.fetch(:multiple, nil),
+        block:     hash.fetch(:block, nil),
+        hidden:    hash.fetch(:hidden, nil),
+        default:   hash.fetch(:default, nil),
+        transform: hash.fetch(:transform, nil),
+      )
+    end
   end
 end