Missing feature for parsing and validation of options and arguments about cri

[denisdefreyne]

The block passed to #option (and variants) is currently executed when the corresponding option is found, but I am not sure that it can be repurposed (in a backwards-compatible way) to verify and transform the value. It can break existing usage that relies on the option value not to change.

I believe that there are three common actions that Cri could/should support:

• run a block (useful for e.g. --help, --version; currently supported)

• validate (useful for e.g. verifying that a port number is an integer in the 0–65535 range; not currently explicitly supported)

• transform (useful for e.g. transforming input into an integer; not currently explicitly supported)

Some use cases:

• Specify any number
• Specify a number with requirements (e.g. --port >0 and <65535)
• Specify a string with requirements (e.g. --seed length ≥ 20)

I am unsure in which order validation and transformation should happen. Validate-then-transform, or transform-then-validate?

Perhaps a transformer that can raise an exception, followed by additional validation, could work:

option :p, :port, 'Specify port to listen on',
  transform: ->(n) { Integer(n) },
  validate: ->(n) { (1..65535).include?(n) }

option :c, :'config-file', 'Specify configuration file',
  transform: ->(fn) { ConfigFile.read(fn) }
  validate: &:valid?

Any callable would be supported (not just procs), so this would also work:

…
  transform: method(:Integer)

or perhaps even

class IntegerTransformer
  def initialize(min: nil, max: nil)
    @min = min
    @max = max
  end

  def validate(n)
    Integer(n).tap do |parsed_n|
      (min ? parsed_n >= min : true) &&
      (min ? parsed_n >= min : true)
    end
  end
end

…
  transform: IntegerTransformer.new

… though at this point it might be worth looking into already-existing validation solutions out there (dry-validation comes to mind, but it might be overkill.)

---

As for argument validation, here are some ideas:

• Fixed number:

  num_arguments 1

• Range:

  num_arguments 1..3

• Callable:

  num_arguments -> (n) { n > 3 || n % 5 == 1 }

i.e. essentially anything that implements #===. WDYT?

[denisdefreyne]

FYI, I have deprecated #optional and #required as their names are far too confusing.

[denisdefreyne]

@eguzki I’ve implemented transform: support in #68. Can you take a look and check whether it makes sense, and fits your use case?

(Option validation is not explicitly implemented yet, although transform: could be reused for that purpose for now. Argument validation is pending too.)

[denisdefreyne]

The option value transformation is implemented and released in Cri 2.11. Can you take a look and confirm that it fits your needs?

[eguzki]

After, quick review, it seems this change allow us to "inject" configuration objects into options object. So every command can get configuration object instead of getting config file and create themselves configuration object.

I have not checked yet actually using this new feature. Will do it ASAP.

[eguzki]

I think this a good progress 👍

Still missing the issue about validation and positional argument validation ;)

[denisdefreyne]

After, quick review, it seems this change allow us to "inject" configuration objects into options object. So every command can get configuration object instead of getting config file and create themselves configuration object.

I believe the transformers should remain stateless; the configuration object is something you could construct afterwards, e.g.

option :p, :port, 'set port', argument: :required, transform: method(:Integer)

# options is a hash, e.g. { port: 12345 }
config = Config.new(options)

---

As for argument validation: it’d be nice to be able to name them, e.g. arguments[:filename] rather than arguments[0].

Some ideas for the API:

• Example:

  arguments [:host, :port]

  Two positional arguments.

• Example:

  argument :host
  argument :port

  Two positional arguments. This API might not make it clear enough that the list of arguments is ordered, however.

• Example:

  argument 0 => :host
  argument 1 => :port

  Two positional arguments. Perhaps a bit verbose.

• Example:

  argument host: 0
  argument port: 1

  Two positional arguments. Perhaps a bit verbose and/or confusing.

• Example:

  argument host: 0
  argument port: 1
  argument filenames: 2..-1

  Several positional arguments, with :filenames being a list of arguments rather than a single one.

  Note that the range 2..-1 does not actually make sense in Ruby (it’s an empty range), but there’s no easy way to express an open-ended range in Ruby 2.5. It’s possible to use 2..Float::INFINITY, but that’s icky. This will change in Ruby 2.6, which will allow ranges like 2.. which represents an open-ended range from 2 on.

• Example:

  argument :host, pos: 0
  argument :port, pos: 1
  argument :filenames, from: 2

  Alternative to the above, with a cleaner syntax for open-ended ranges.

More thoughts:

• Are there other requirements for argument validation? Other nice-to-haves?
• parameter or argument?

[denisdefreyne]

The same transformation would be used for arguments, e.g.

argument :ports, from: 0, transform: method(:Integer)

… to specify a list of ports and convert them to integers.

[eguzki]

I believe the transformers should remain stateless; the configuration object is something you could construct afterwards, e.g.

Makes sense. This is something very specific for our needs and will think about that. thnx.

WRT positional arguments, I would expect simple validation of existence. Any further support for transformation or keyword based access API is nice to have.

The most flexible way seems your last example

argument :ports, from: 0, transform: method(:Integer)

Allows extension for validation or running a block. I would call it argument for consistency's sake.

[denisdefreyne]

As the MVP, I’d like to implement something a bit simpler:

param :port, transform: method(:Integer)

• I renamed argument to param. An argument is a value, e.g. 8080, while a parameter is a name, e.g. port. I like to make that distinction.

• transform: (same as before)

• No more from/pos — at least not for the MVP. For now, don’t support a variable number of arguments, and assume that the arguments are given in exactly the order of param calls.

Additionally, if no params are specified, Cri will assume that there is no argument validation needed. The no_params directive will tell Cri to do validation and check that there are indeed no arguments passed.

---

Later on:

• Implement from: and pos: (though at: might be a better name than pos:)
• Implement default:

[denisdefreyne]

Very basic parameter checking is now implemented in master. It includes (for now) only parameters without support for transform, from/at, or default — just the name.

For example:

param :source
param :target

% ./sync . hydra:/srv/data
Syncing…
%

% ./sync hydra:/srv/data
sync: incorrect number of arguments given: expected 2, but got 1
%

[denisdefreyne]

The released version 2.12.0 has the basic param support. Further improvements are in the pipeline.

[denisdefreyne]

Cri v2.13.0 has support for explicitly specifying zero parameters using no_params, e.g.

command = Cri::Command.define do
  name        'reset'
  usage       'reset'
  summary     'resets the site'
  description '…'
  no_params

  run do |opts, args, cmd|
    puts "Resetting…"
  end
end

% my-tool reset x
reset: incorrect number of arguments given: expected 0, but got 1
% my-tool reset
Resetting…
%

[denisdefreyne]

The just-released Cri v2.15.0 has parameter transformation support, e.g.

param :id, transform: ->(a) { a.upcase }

When given abc123 as argument, arguments[:id] will be ABC123.

This can also be used for validation (raise an exception in the transform block).

[denisdefreyne]

I’ve created #74 (varargs) and #75 (params with default values) to track non-implemented features. Both feature requests have low priority at the moment, but if you have use cases where they could be useful, do let me know.

I believe that, apart from these, there’s nothing left that needs to be implemented, so I’ll close this ticket.

Thanks for your valuable feedback! I think it has made Cri a considerably better product, and I’ve also benefited from the new features that I’ve added to it.