In clap v3, `require_value_delimiter` activated an alternative parse
mode where
- `multiple_values` meant "multiple values within a single arg"
- `number_of_values` having no parse impact, only validation impact
- `value_names` being delimited values
For unbounded `number_of_values`, this is exactly what `value_delimiter`
provides. The only value is if someone wanted `value_name` to be
`<file1>,<file2>,...` which can be useful and we might look into adding
back in.
Alternatively, this could be used for cases like key-value pairs but
that has issues like not allowing the delimiter in the value which might
be ok in some cases but not others. We already instead document that
people should instead use `ValueParser` for this case.
In removing this, we remove points of confusion at how the different
multiple values and delimited value calls interact with each other. I
know I would set `require_value_delimiter(true).multiple_values(true)`
when it turns out all I needed was `value_delimiter(',')`.
This also reduces the API surface area which makes it easier to discover
what features we do provide.
While this isn't big, this is also yet another small step towards
reducing binary size and compile times.
This will allow `num_args(0..=1).value_delimiter(',')` to work properly.
This hacks in support for `require_value_delimiter` until we can remove
it.
This no longer recognzes value terminators in delimited lists.
It looks like there is a bug with recognizing value terminators in
positionals arguments. We'll need to dig into that more.
This reduces ambiguity in how the different "multiple" parts of the API
interact and lowrs the amount of API surface area users have to dig
through to use clap.
For now, this is only a matter of cleaning up the public API. Cleaning
up the implementation is the next step.
In the short term, this just provides a back door to custom actions.
Longer term, we can explore a `SetConst` action that relies on this
behavior. Really, `SetTrue` and `SetFalse` are shortcuts for such an
action but shortcuts can be helpful for usability.
Apparently, this also reduced `.text` size by 1k
With `number_of_values` being per-occurrence now, its doesn't make sense
for `number_of_values(0)` to set `takes_value(true)` or for
`number_of_values(1)` to set `multiple_values(true)`.
In addition, an assert is made if the user works around this
This both simplifies the code and the model we present to the user,
making more sense.
There is room for further exploration of tying flag actions into this.
This changes the default type as well to encourage preserving the full
information for shelling out. If people need UTF-8, then they can
change the value parser.
Fixes#3733
Previous behavior:
- They'd be sorted by default
- They'd derive display order if `DeriveDisplayOrder` was set
- This could be set recursively
- The initial display order value for subcommands was 0
New behavior:
- Sorted order is derived by default
- Sorting is turned on by `cmd.next_display_order(None)`
- This is not recursive, it must be set on each level
- The display order incrementing is mixed with arguments
- This does make it slightly more difficult to predict
