Swift's argument parser library has an OpenCLI draft PR

[cmcgee1024]

The swift-argument-parser has a draft PR up to add OpenCLI support. It's still in draft at the moment because there's still some details to be worked out about some differences in the way that arguments are determined to be values of options. In SAP this is configurable per option. But, with OpenCLI this is a global convention. Also, it's not quite clear when there will be an official point release of OpenCLI so that it can adopt that with a level of stability.

apple/swift-argument-parser#814

[patriksvensson]

@cmcgee1024 This is very cool! Implementations of the spec is really what drives the spec, so I'm very excited that you have a PR for an actual implementation.

It's still in draft at the moment because there's still some details to be worked out about some differences in the way that arguments are determined to be values of options. In SAP this is configurable per option. But, with OpenCLI this is a global convention.

I'm not sure if I understand. Can you elaborate a bit?

Also, it's not quite clear when there will be an official point release of OpenCLI so that it can adopt that with a level of stability.

I completely understand this. My goal was to have some kind of official non-draft version out soon. The only problem is knowing exactly what we can omit for a first version and still make it usable. I very much would want to have your input on this.

[cmcgee1024]

I'm not sure if I understand. Can you elaborate a bit?

The SAP has a concept called a "parsing strategy" that's in place for arguments, and options.

For example, here's a parsing strategy that you apply to a particular option called "upToNextOption" that for an arity > 1 that will include everything into the first option until it encounters something that looks like another option: https://swiftpackageindex.com/apple/swift-argument-parser/1.6.1/documentation/argumentparser/arrayparsingstrategy/uptonextoption

--files foo bar --verbose would also set files to the array ["foo", "bar"]

Here's another one that would require that you repeat the option name to add multiple values to the option:

--read foo --read bar would result in the array ["foo", "bar"]. The same would be true for the input --read=foo --read=bar

If an option only accepts a single value (arity == 1) then there are some other parsing strategies, like this one that scan ahead of other options/flags in the stream for the value:

--foo --bar bar would be parsed such that the value bar is used for --foo

For arguments there are other parsing strategies, such as captureForPassthrough that's useful for capturing everything as the command-line arguments for another command, such as docker run or ssh:

$ example --verbose one two -- --other
one
two
--
--other

This is a bit orthogonal to the idea of options having arity, and there being a standard option value separator. I'm not entirely sure how to map some of these parsing strategies into those OpenCLI concepts. It could be that we use an imperfect modelling of them, and specifically omit the intermixing cases. SAP is flexible in the options separator with either a space or a glued option with the equal sign, so the default convention of the space separator will work, but it doesn't model the true capabilities of the tool's command-line.

[patriksvensson]

I see what you mean (I think), and if I understand correctly, there are really two things we need to solve.

1. Multiple values

How should we handle option values that appear multiple times but have an arity of 1? We’ve discussed this a bit in #34, and one possible solution would be to specify a strategy like firstOneWins, lastOneWins, or error.

2. Parsing option values

The second problem is explaining how option values are parsed:

• Consecutive? --read foo bar => read = [foo bar] for arity > 1

• Separate? --read foo --read bar => read = [foo bar] for arity > 1

• First value? --read --lol bar => read = bar for arity 1 (or does it work with more values?)
  (I have to admit I don’t recall seeing this before, and I don’t think any CLI parser framework I’ve used supports this)

I have a feeling this doesn’t need to be defined per option, though, but rather something that should be declared in, for example, the Convention Object?

[cmcgee1024]

How should we handle option values that appear multiple times but have an arity of 1?

I think that this is an interesting question. I suppose that by assigning options an arity it is distinct from whether it supports repetition. Here's an example of an option with an arity of 1, but can be repeating:

--foo=1 --foo=2

However, this would be invalid:

--foo 1 2

Another question I have about OpenCLI is the idea of the option separator, which defaults to spaces right now. What does it look like to have another separator, like ","? Maybe it looks like this, assuming that the arity is > 1.

--foo 1,2

If my understanding is correct then the separator only makes sense for options that have an arity > 1. Arity is only about the number of values consumed after the --option token.

[patriksvensson]

Regarding --foo 1,2, all CLI parsers I've encountered treat this as a single value to foo, which is later deconstructed into multiple, but does not support having , as a separator per se.

[cmcgee1024]

What's the purpose of the optionArgumentSeparator if not for this case of custom separators?

[patriksvensson]

That's for separators between options and their arguments --foo bar (space), --foo=bar (=), --foo:bar (:) etc.