Simplify the takes_value API

[epage]

Currently, we have

• takes_value
• multiple_values
• min_values
• max_values

We then have to clarify how these are related to each other, for example:

NOTE: This does not implicitly set Arg::multiple(true). This is because -o val -o val is multiple occurrences but a single value and -o val1 val2 is a single occurrence with multiple values. For positional arguments this does set Arg::multiple(true) because there is no way to determine the difference between multiple occurrences and multiple values.

(taken from docs.rs, since updated to say multiple_occurrences).

I had already been brainstorming on this idea when kbknapp mentioned

I think the crux of the problem is that we previously didn’t do a good job of articulating the difference between multiple_values, multiple_occurrences, and max_values_per_occurrence.

I think we can simplify this problem down to

• takes_values(num: impl clap::IntoRange) with
  • impl IntoRange for usize
  • impl IntoRange for ...each range type

So you can do take_values(0), take_values(2), take_values(1..), take_values(0..=1)

• Really, the motivation is to support all the various range types. Taking in a number is just a convenience while we are at it. I considered taking in a bool, but I think that is making it too magical and isn't as needed.
• This was named based on Remove magic arg type in `Args` #2674 going through and takes_values(1) being the default.

While I was already talking with kbknapp, I brought this up and is thoughts were:

That is an interesting idea! It feels like it might incur some cognitive load to understand, although once you see it it makes total sense. I'd love to find a way to play with this idea without throwing it front and center and in the API all of a sudden.

Notes

For the question from kbknapp

For example, which makes more sense for a positional argument; multiple_values or multiple_occurrences? I think you and I would say multiple_values, but I can totally see how someone may try multiple_occurrences. This was papered over by having just multiple previously and things just working. However, we’ve seen that strategy didn’t work in the long run as it created more ambiguity than it solved.

I would say occurrences, actually. This would leave room for the two features to compose, like multiple_occurrences(true).takes_values(2). Not a common pattern but I think it speaks to an API when the features compose together in a natural way which this allows.

RE Delimiters

I would posit that common cases for multiple values are

• 0..=1
• 2
• 0.. or 1.. with a delimiter

We should raise awareness of require_delimiter in the docs for take_values.

Benefits

• Clarifies our messaging on these settings plus occurrences since the focus is on fixed number of values or delimiters
• Reduces the number of interrelated settings that a user has to understand (and we have to document in hopes it helps the user understand)
• Uses higher level Rust types rather than a bool and numbers just hanging around (which ties into the Rust API guidelines)
• I suspect this will also help us towards a more maintainable value/occurrence/inferring behavior.

[pksunkara]

takes_values(num: impl clap::IntoRange)

Great idea! We can do this after 3.0 since it's not a breaking change.

I would say occurrences, actually. This would leave room for the two features to compose, like multiple_occurrences(true).takes_values(2)

How would that work for positional args?

delimiters

I don't know why they are being discussed here, because if you use delimiter, I don't think you can use multiple values. It's just 1 value during parsing which uses delimiter to get more values in the ArgMatches.

[epage]

I would say occurrences, actually. This would leave room for the two features to compose, like multiple_occurrences(true).takes_values(2)
How would that work for positional args?

Why would it act any different than named args?

I don't know why they are being discussed here, because if you use delimiter, I don't think you can use multiple values. It's just 1 value during parsing which uses delimiter to get more values in the ArgMatches.

I brought it up because I was exploring the use case for multiple_values and the use case of "indeterminate amount", we should be encouraging this route instead as a safe, common practice.

Also, from the users perspective, they are different ways of taking multiple values. If a user wants to require at least one, I suspect we should use this rule to validate that.

[pksunkara]

Why would it act any different than named args?

I thought about this and you are right.

I would say occurrences, actually.

Can you please create a separate issue for this? I think we need to fix this for 3.0

[epage]

Can you please create a separate issue for this? I think we need to fix this for 3.0

So we are on the same page, what all do you see needing to be changed because of this?

[pksunkara]

#2692