cri 2.11.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc4daab3e3ba10d21d0545fab6a7ab99dc8ad125b3ca3acd3691326b164ba4ca
-  data.tar.gz: 686ac2c2324893fbaabc650fe42858355f643eea90af8b6acff986207fb183ca
+  metadata.gz: e0e63fb09fa1cd1a483f34f9f535adca0ce5f543e975163584ecf43a509e4195
+  data.tar.gz: be17d3d95165270a73992dfa8a819704750d3b73b973a176f2d5c553a1934829
 SHA512:
-  metadata.gz: 0cc8b4aadbde4cae477feb33d2578287d23dc77aea4700dae5115ee06d19e1234ba5625db2f3cd053bfa941e425cc50d0ac0c6836ffcb1b807b92f3aa3055470
-  data.tar.gz: 55c6c0dd76ab840f11f73568de6fa5105dfd934b4602d1fb55bc9f506d4bd001b9bb890110fee0b68bc23ca6824547f33b757855fda126bca27dd72f656d6164
+  metadata.gz: 55dc3514760d66bf2c4a7edf8e06ba37947dc278efaf339ac8de24afc5c6f8ecfa4d651557351433763800327907ec4c25859c335350a95adcb2decad9cd313f
+  data.tar.gz: 3bda1e11790abbe1d2187961a1868ffcb1d255cf4d82a4f514e1a966bf72280fc34a0fe9f41303d7905024b092570220615120386940c7c429bad81ac5bd29ef

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cri (2.11.0)
+    cri (2.12.0)
       colored (~> 1.2)
 
 GEM
@@ -34,7 +34,7 @@ GEM
       rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.0, >= 1.0.1)
-    ruby-progressbar (1.9.0)
+    ruby-progressbar (1.10.0)
     simplecov (0.16.1)
       docile (~> 1.1)
       json (>= 1.8, < 3)
@@ -45,7 +45,7 @@ GEM
     thor (0.19.4)
     tins (1.16.3)
     unicode-display_width (1.4.0)
-    yard (0.9.15)
+    yard (0.9.16)
 
 PLATFORMS
   ruby

data/NEWS.md

@@ -1,6 +1,12 @@
 Cri News
 ========
 
+## 2.12.0
+
+Features:
+
+* Added support for parameter naming and validation (#70)
+
 ## 2.11.0
 
 Features:

data/README.md

@@ -232,6 +232,33 @@ When executing this command with `dostuff --some=value -f yes`, the `opts` hash
 that is passed to your `run` block will be empty and the `args` array will be
 `["--some=value", "-f", "yes"]`.
 
+### Argument parsing
+
+Cri also supports parsing arguments, outside of options. To define the
+parameters of a command, use `#param`, which takes a symbol containing the name
+of the parameter. For example:
+
+```ruby
+command = Cri::Command.define do
+  name        'publish'
+  usage       'publish filename'
+  summary     'publishes the given file'
+  description 'This command does a lot of stuff, but not option parsing.'
+
+  flag :q, :quick, 'publish quicker'
+  param :filename
+
+  run do |opts, args, cmd|
+    puts "Publishing #{args[:filename]}…"
+  end
+end
+```
+
+The command in this example has one parameter named `filename`. This means that
+the command takes a single argument, named `filename`.
+
+(*Why the distinction between argument and parameter?* A parameter is a name, e.g. `filename`, while an argument is a value for a parameter, e.g. `kitten.jpg`.)
+
 ### The run block
 
 The last part of the command defines the execution itself:

data/lib/cri.rb

@@ -23,10 +23,13 @@ require 'set'
 require 'colored'
 
 require_relative 'cri/version'
+require_relative 'cri/argument_list'
 require_relative 'cri/command'
 require_relative 'cri/string_formatter'
 require_relative 'cri/command_dsl'
 require_relative 'cri/command_runner'
 require_relative 'cri/help_renderer'
+require_relative 'cri/option_definition'
 require_relative 'cri/option_parser'
+require_relative 'cri/param_definition'
 require_relative 'cri/platform'

data/lib/cri/argument_list.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Cri
+  # A list of arguments, which can be indexed using either a number or a symbol.
+  class ArgumentList
+    # Error that will be raised when an incorrect number of arguments is given.
+    class ArgumentCountMismatchError < Cri::Error
+      def initialize(expected_count, actual_count)
+        @expected_count = expected_count
+        @actual_count = actual_count
+      end
+
+      def message
+        "incorrect number of arguments given: expected #{@expected_count}, but got #{@actual_count}"
+      end
+    end
+
+    include Enumerable
+
+    def initialize(raw_arguments, param_defns)
+      @raw_arguments = raw_arguments
+      @param_defns = param_defns
+
+      load
+    end
+
+    def [](key)
+      case key
+      when Symbol
+        @arguments_hash[key]
+      when Integer
+        @arguments_array[key]
+      else
+        raise ArgumentError, "argument lists can be indexed using a Symbol or an Integer, but not a #{key.class}"
+      end
+    end
+
+    def each
+      @arguments_array.each { |e| yield(e) }
+      self
+    end
+
+    def method_missing(sym, *args, &block)
+      if @arguments_array.respond_to?(sym)
+        @arguments_array.send(sym, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(sym, include_private = false)
+      @arguments_array.respond_to?(sym) || super
+    end
+
+    def load
+      @arguments_array = @raw_arguments.reject { |a| a == '--' }.freeze
+      @arguments_hash = {}
+
+      if @param_defns.empty?
+        # For now, don’t check arguments when no parameter definitions are given.
+        return
+      end
+
+      if @arguments_array.size != @param_defns.size
+        raise ArgumentCountMismatchError.new(@param_defns.size, @arguments_array.size)
+      end
+
+      @arguments_array.zip(@param_defns).each do |(arg, param_defn)|
+        @arguments_hash[param_defn.name.to_sym] = arg
+      end
+    end
+  end
+end

data/lib/cri/command.rb

@@ -87,9 +87,12 @@ module Cri
     attr_accessor :hidden
     alias hidden? hidden
 
-    # @return [Array<Hash>] The list of option definitions
+    # @return [Array<Cri::OptionDefinition>] The list of option definitions
     attr_accessor :option_definitions
 
+    # @return [Array<Hash>] The list of parameter definitions
+    attr_accessor :parameter_definitions
+
     # @return [Proc] The block that should be executed when invoking this
     #   command (ignored for commands with subcommands)
     attr_accessor :block
@@ -147,6 +150,7 @@ module Cri
       @aliases            = Set.new
       @commands           = Set.new
       @option_definitions = Set.new
+      @parameter_definitions = []
       @default_subcommand_name = nil
     end
 
@@ -167,8 +171,8 @@ module Cri
       self
     end
 
-    # @return [Hash] The option definitions for the command itself and all its
-    #   ancestors
+    # @return [Enumerable<Cri::OptionDefinition>] The option definitions for the
+    #   command itself and all its ancestors
     def global_option_definitions
       res = Set.new
       res.merge(option_definitions)
@@ -312,12 +316,14 @@ module Cri
       else
         # Parse
         parser = Cri::OptionParser.new(
-          opts_and_args, global_option_definitions
+          opts_and_args,
+          global_option_definitions,
+          parameter_definitions,
         )
-        handle_parser_errors_while { parser.run }
+        handle_errors_while { parser.run }
         local_opts  = parser.options
         global_opts = parent_opts.merge(parser.options)
-        args = parser.arguments
+        args = handle_errors_while { parser.arguments }
 
         # Handle options
         handle_options(local_opts)
@@ -357,8 +363,8 @@ module Cri
 
     def handle_options(opts)
       opts.each_pair do |key, value|
-        opt_def = global_option_definitions.find { |o| (o[:long] || o[:short]) == key.to_s }
-        block = opt_def[:block]
+        opt_defn = global_option_definitions.find { |o| (o.long || o.short) == key.to_s }
+        block = opt_defn.block
         block&.call(value, self)
       end
     end
@@ -368,9 +374,13 @@ module Cri
 
       # Parse
       delegate = Cri::Command::OptionParserPartitioningDelegate.new
-      parser = Cri::OptionParser.new(opts_and_args, global_option_definitions)
+      parser = Cri::OptionParser.new(
+        opts_and_args,
+        global_option_definitions,
+        parameter_definitions,
+      )
       parser.delegate = delegate
-      handle_parser_errors_while { parser.run }
+      handle_errors_while { parser.run }
 
       # Extract
       [
@@ -380,7 +390,7 @@ module Cri
       ]
     end
 
-    def handle_parser_errors_while
+    def handle_errors_while
       yield
     rescue Cri::OptionParser::IllegalOptionError => e
       warn "#{name}: unrecognised option -- #{e}"
@@ -391,6 +401,9 @@ module Cri
     rescue Cri::OptionParser::IllegalOptionValueError => e
       warn "#{name}: #{e.message}"
       raise CriExitException.new(is_error: true)
+    rescue Cri::ArgumentList::ArgumentCountMismatchError => e
+      warn "#{name}: #{e.message}"
+      raise CriExitException.new(is_error: true)
     end
   end
 end

data/lib/cri/command_dsl.rb

@@ -128,34 +128,27 @@ module Cri
     #
     # @return [void]
     def option(short, long, desc, params = {}, &block)
-      requiredness = params.fetch(:argument, :forbidden)
-      multiple = params.fetch(:multiple, false)
-      hidden = params.fetch(:hidden, false)
-      default = params.fetch(:default, nil)
-      transform = params.fetch(:transform, nil)
-
-      if short.nil? && long.nil?
-        raise ArgumentError, 'short and long options cannot both be nil'
-      end
-
-      if default && requiredness == :forbidden
-        raise ArgumentError, 'a default value cannot be specified for flag options'
-      end
-
-      @command.option_definitions << {
-        short: short.nil? ? nil : short.to_s,
-        long: long.nil? ? nil : long.to_s,
-        desc: desc,
-        argument: requiredness,
-        multiple: multiple,
-        block: block,
-        hidden: hidden,
-        default: default,
-        transform: transform,
-      }
+      @command.option_definitions << Cri::OptionDefinition.new(
+        short:     short&.to_s,
+        long:      long&.to_s,
+        desc:      desc,
+        argument:  params.fetch(:argument, :forbidden),
+        multiple:  params.fetch(:multiple, false),
+        block:     block,
+        hidden:    params.fetch(:hidden, false),
+        default:   params.fetch(:default, nil),
+        transform: params.fetch(:transform, nil),
+      )
     end
     alias opt option
 
+    # Defines a new parameter for the command.
+    #
+    # @param [Symbol] name The name of the parameter
+    def param(name)
+      @command.parameter_definitions << Cri::ParamDefinition.new(name: name)
+    end
+
     # Adds a new option with a required argument to the command. If a block is
     # given, it will be executed when the option is successfully parsed.
     #

data/lib/cri/help_renderer.rb

@@ -106,18 +106,18 @@ module Cri
       end
     end
 
-    def length_for_opt_defs(opt_defs)
-      opt_defs.map do |opt_def|
+    def length_for_opt_defns(opt_defns)
+      opt_defns.map do |opt_defn|
         string = +''
 
         # Always pretend there is a short option
         string << '-X'
 
-        if opt_def[:long]
-          string << ' --' + opt_def[:long]
+        if opt_defn.long
+          string << ' --' + opt_defn.long
         end
 
-        case opt_def[:argument]
+        case opt_defn.argument
         when :required
           string << '=<value>'
         when :optional
@@ -133,7 +133,7 @@ module Cri
       if @cmd.supercommand
         groups["options for #{@cmd.supercommand.name}"] = @cmd.supercommand.global_option_definitions
       end
-      length = length_for_opt_defs(groups.values.inject(&:+))
+      length = length_for_opt_defns(groups.values.inject(&:+))
       groups.keys.sort.each do |name|
         defs = groups[name]
         append_option_group(text, name, defs, length)
@@ -147,17 +147,17 @@ module Cri
       text << fmt.format_as_title(name.to_s, @io)
       text << "\n"
 
-      ordered_defs = defs.sort_by { |x| x[:short] || x[:long] }
-      ordered_defs.reject { |opt_def| opt_def[:hidden] }.each do |opt_def|
-        text << format_opt_def(opt_def, length)
-        desc = opt_def[:desc] + (opt_def[:default] ? " (default: #{opt_def[:default]})" : '')
+      ordered_defs = defs.sort_by { |x| x.short || x.long }
+      ordered_defs.reject(&:hidden).each do |opt_defn|
+        text << format_opt_defn(opt_defn, length)
+        desc = opt_defn.desc + (opt_defn.default ? " (default: #{opt_defn.default})" : '')
         text << fmt.wrap_and_indent(desc, LINE_WIDTH, length + OPT_DESC_SPACING + DESC_INDENT, true) << "\n"
       end
     end
 
-    def short_value_postfix_for(opt_def)
+    def short_value_postfix_for(opt_defn)
       value_postfix =
-        case opt_def[:argument]
+        case opt_defn.argument
         when :required
           '<value>'
         when :optional
@@ -165,15 +165,15 @@ module Cri
         end
 
       if value_postfix
-        opt_def[:long] ? '' : ' ' + value_postfix
+        opt_defn.long ? '' : ' ' + value_postfix
       else
         ''
       end
     end
 
-    def long_value_postfix_for(opt_def)
+    def long_value_postfix_for(opt_defn)
       value_postfix =
-        case opt_def[:argument]
+        case opt_defn.argument
         when :required
           '=<value>'
         when :optional
@@ -181,30 +181,30 @@ module Cri
         end
 
       if value_postfix
-        opt_def[:long] ? value_postfix : ''
+        opt_defn.long ? value_postfix : ''
       else
         ''
       end
     end
 
-    def format_opt_def(opt_def, length)
-      short_value_postfix = short_value_postfix_for(opt_def)
-      long_value_postfix = long_value_postfix_for(opt_def)
+    def format_opt_defn(opt_defn, length)
+      short_value_postfix = short_value_postfix_for(opt_defn)
+      long_value_postfix = long_value_postfix_for(opt_defn)
 
       opt_text = +''
       opt_text_len = 0
-      if opt_def[:short]
-        opt_text << fmt.format_as_option('-' + opt_def[:short], @io)
+      if opt_defn.short
+        opt_text << fmt.format_as_option('-' + opt_defn.short, @io)
         opt_text << short_value_postfix
         opt_text << ' '
-        opt_text_len += 1 + opt_def[:short].size + short_value_postfix.size + 1
+        opt_text_len += 1 + opt_defn.short.size + short_value_postfix.size + 1
       else
         opt_text << '   '
         opt_text_len += 3
       end
-      opt_text << fmt.format_as_option('--' + opt_def[:long], @io) if opt_def[:long]
+      opt_text << fmt.format_as_option('--' + opt_defn.long, @io) if opt_defn.long
       opt_text << long_value_postfix
-      opt_text_len += 2 + opt_def[:long].size if opt_def[:long]
+      opt_text_len += 2 + opt_defn.long.size if opt_defn.long
       opt_text_len += long_value_postfix.size
 
       '    ' + opt_text + ' ' * (length + OPT_DESC_SPACING - opt_text_len)

data/lib/cri/option_definition.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Cri
+  # The definition of an option.
+  class OptionDefinition
+    attr_reader :short
+    attr_reader :long
+    attr_reader :desc
+    attr_reader :argument
+    attr_reader :multiple
+    attr_reader :block
+    attr_reader :hidden
+    attr_reader :default
+    attr_reader :transform
+
+    def initialize(params = {})
+      @short     = params.fetch(:short)
+      @long      = params.fetch(:long)
+      @desc      = params.fetch(:desc)
+      @argument  = params.fetch(:argument)
+      @multiple  = params.fetch(:multiple)
+      @block     = params.fetch(:block)
+      @hidden    = params.fetch(:hidden)
+      @default   = params.fetch(:default)
+      @transform = params.fetch(:transform)
+
+      if @short.nil? && @long.nil?
+        raise ArgumentError, 'short and long options cannot both be nil'
+      end
+
+      if @default && @argument == :forbidden
+        raise ArgumentError, 'a default value cannot be specified for flag options'
+      end
+    end
+
+    def to_h
+      {
+        short:     @short,
+        long:      @long,
+        desc:      @desc,
+        argument:  @argument,
+        multiple:  @multiple,
+        block:     @block,
+        hidden:    @hidden,
+        default:   @default,
+        transform: @transform,
+      }
+    end
+
+    def formatted_name
+      @long ? '--' + @long : '-' + @short
+    end
+  end
+end