Remove magic arg type in Args

[epage]

• Arg::new() creates a positional argument that takes_value(true)
• Args::new().long() creates a named flag (takes_value(false))
• Args::new().long().takes_value(true) is required to created a named arg / option

This requires us to guess the users intent at various stages. kbknapp explained this when trying to explain existing challenges with values vs occurrences:

Keeping in mind that clap has some implied rules that at times contradict one-another in subtle ways. For example Arg::new effectively creates a positional value, i.e. an argument that accepts a single value with flags/switches. Adding either short or long actually removes the value, and turns it into a flag (i.e. switch with no associated value). Then adding takes_value (or any of the value associated methods) implicitly turns it into an option (combined flag/switch with an associated value), so giving it a value again.

Because of how these rules/settings combine, it turns out there are multiple ways to end up at the same final product; some just more explicit while others passively allow the rules to combine. As in the Arg::new example above, that's all that's required to create a positional argument, but doing Arg::new("foo").takes_value(true).index(1) works just as well.

Because of this, clap sometimes has to infer if the user meant to allow the rules to combine. This primarily comes out around the multiple values/occurrences. In other words clap has a default state for many of the settings, and we need to ensure that when a user only sets one (or a few) settings the remaining defaults don't combine to do something surprising.

I'm even running into a problem I'm debugging for #751 that I think comes from this.

Just a small tweak would make clap less brittle for change and I believe make the user experience better, if we switch to

• Arg::new() creates a positional argument that takes_value(true)
• Args::new().long() creates a named arg / option (ie takes_value(true))
• Args::new().long().takes_value(false) is required to created a flag

@kbknapp was open to changing this, though with a different approach (this was before clarifying the approach above, see below for his thoughts on each approach)

I’m not against removing changing the default behavior of Arg::new, the only reason it hasn’t been done before is the only other sensible thing to do (IMO) is to have Arg::new result in a “useless” argument, Further methods would be required to determine this. This would accomplish what you’re speaking about, and solve a few of the issues related to ambiguities. The only reason I didn’t do that before, was I tend to lean towards a contractor should at least make the struct usable to some extent…but I can see how in this case that may not be the case.

We could fix the "always valid object" problem by instead making some helper constructors (positional, flag, and option where the latter take long names since 99% of the time, they are used)

Between flag-opt-in and construct invalid options (I didn't bring up the named constructors), kbknapp said

I think it's almost 50/50 as to which route would be preferred. Opt-in to a flag (takes_value(false)) I think really only has the downside of being different from v2 causing (minimal) churn in that those that currently have Arg::new().long() would auto-magically have all their flags turn into options unless they go in and add takes_value(false) to them all. Whereas the I believe the number of users who are using Arg::new and no other "value based" methods and just relying on it being a positional are few and far between, so less churn. But again, I'm somewhat 50/50 as to which I think is "better" so to speak.

[epage]

@pksunkara is the thumbs up a go-ahead to turn this into an issue and implement?

I lean towards always-valid Arg::new() though we could add convenience helpers later.

[pksunkara]

Arg::new is currently always valid. Not sure when it is not.

I said 👍 because I think this is good idea to do. But I would actually reserve this for 4.0. This is probably the biggest thing we can break in clap and I really don't want to do this for 3.0 because of that.

[epage]

kbnapp was thinking Arg::new would have no flags set, so Arg::new would not be a proper positional argument or named argument.

I'll switch this to an Issue. Feel free to tag with 4.0

[pksunkara]

If we want takes_value to be true by default, Arg::new would have takes_value(true) set, which means it is a valid positional. Which is why I was saying it will be always valid.