Feedback on groovy.cli.Option annotation

[Remko Popma <re...@gmail.com>]

The groovy.cli.Option annotation currently has three attributes for
modeling the number of arguments (arity) of an option:


   - boolean optionalArg() default false
   - int numberOfArguments() default 1
   - String numberOfArgumentsString() default ""


Are we open to changing this to a single attribute where the number of
arguments can be expressed as a range?

For example, "0..1" for a single optional argument, "0..*" (or simply "*")
for an option with any number of arguments, "1..*" (or "+") for one or more
arguments. This would also allow users specifying ranges like "2..4" for an
option that has at least 2 but at most 4 arguments.

Having a single attribute instead of three is cleaner and simpler IMO. Is
it too late to make this change?

Thoughts?

Re: Feedback on groovy.cli.Option annotation

[Remko Popma <re...@gmail.com>]

Understood, thanks for the clarification.


On Sat, Mar 24, 2018 at 12:23 PM, Paul King <pa...@asert.com.au> wrote:

>
> We'd consider streamlining but with caveats.
>
> On the one hand, those attributes are influenced a little by what Commons
> CLI supports. It doesn't support ranges like "2..4" at all. However,
> CliBuilder is meant to be an abstraction layer above the CLI
> implementation, so we should assume we have some freedom to present the
> best possible api to CliBuilder users.
>
> On the other hand, we have backward compatibility constraints:
> * We have several 2.5 (albeit beta) releases already in the wild, so our
> preference would be to deprecate rather than remove any existing
> functionality. The desire to maintain backwards compatibility is slightly
> lower because it has only been betas so far but not by much.
> * More importantly, CliBuilder is meant to provide a similar feel whether
> using it via annotations or directly via the api. The api usage is much
> older and we'd probably prefer not to even deprecate functionality offered
> there (and hence via the annotations) without some big improvements. Any
> improvements would be offset by possible negatives, e.g. some users are
> going to prefer the tiny bit of extra type safety offered by an Integer vs
> a String. But I'd note that the direct api doesn't even support setting
> number of arguments via a String so we'd expect some evolution in the api.
>
> So, see how it unfolds, but my gut feel is that so long as the semantics
> are crystal clear, we'd want to keep the other alternatives even if we
> discourage there use a little via appropriate wording in the documentation.
> If it's looking extremely unwieldy, then the 2.5 release would be an
> appropriate streamlining point.
>
> Cheers, Paul.
>
>
> On Sat, Mar 24, 2018 at 11:46 AM, Remko Popma <re...@gmail.com>
> wrote:
>
>> The groovy.cli.Option annotation currently has three attributes for
>> modeling the number of arguments (arity) of an option:
>>
>>
>>    - boolean optionalArg() default false
>>    - int numberOfArguments() default 1
>>    - String numberOfArgumentsString() default ""
>>
>>
>> Are we open to changing this to a single attribute where the number of
>> arguments can be expressed as a range?
>>
>> For example, "0..1" for a single optional argument, "0..*" (or simply "*")
>> for an option with any number of arguments, "1..*" (or "+") for one or
>> more arguments. This would also allow users specifying ranges like "2..4"
>> for an option that has at least 2 but at most 4 arguments.
>>
>> Having a single attribute instead of three is cleaner and simpler IMO. Is
>> it too late to make this change?
>>
>> Thoughts?
>>
>
>

Re: Feedback on groovy.cli.Option annotation

[Paul King <pa...@asert.com.au>]

We'd consider streamlining but with caveats.

On the one hand, those attributes are influenced a little by what Commons
CLI supports. It doesn't support ranges like "2..4" at all. However,
CliBuilder is meant to be an abstraction layer above the CLI
implementation, so we should assume we have some freedom to present the
best possible api to CliBuilder users.

On the other hand, we have backward compatibility constraints:
* We have several 2.5 (albeit beta) releases already in the wild, so our
preference would be to deprecate rather than remove any existing
functionality. The desire to maintain backwards compatibility is slightly
lower because it has only been betas so far but not by much.
* More importantly, CliBuilder is meant to provide a similar feel whether
using it via annotations or directly via the api. The api usage is much
older and we'd probably prefer not to even deprecate functionality offered
there (and hence via the annotations) without some big improvements. Any
improvements would be offset by possible negatives, e.g. some users are
going to prefer the tiny bit of extra type safety offered by an Integer vs
a String. But I'd note that the direct api doesn't even support setting
number of arguments via a String so we'd expect some evolution in the api.

So, see how it unfolds, but my gut feel is that so long as the semantics
are crystal clear, we'd want to keep the other alternatives even if we
discourage there use a little via appropriate wording in the documentation.
If it's looking extremely unwieldy, then the 2.5 release would be an
appropriate streamlining point.

Cheers, Paul.


On Sat, Mar 24, 2018 at 11:46 AM, Remko Popma <re...@gmail.com> wrote:

> The groovy.cli.Option annotation currently has three attributes for
> modeling the number of arguments (arity) of an option:
>
>
>    - boolean optionalArg() default false
>    - int numberOfArguments() default 1
>    - String numberOfArgumentsString() default ""
>
>
> Are we open to changing this to a single attribute where the number of
> arguments can be expressed as a range?
>
> For example, "0..1" for a single optional argument, "0..*" (or simply "*")
> for an option with any number of arguments, "1..*" (or "+") for one or
> more arguments. This would also allow users specifying ranges like "2..4"
> for an option that has at least 2 but at most 4 arguments.
>
> Having a single attribute instead of three is cleaner and simpler IMO. Is
> it too late to make this change?
>
> Thoughts?
>