Commits on Nov 5, 2021

1. fix(derive): Define multiple policy for Special Types …

   Before:
   - `bool`: a flag
   - `Option<_>`: not required
   - `Option<Option<_>>` is not required and when it is present, the value
     is not required
   - `Vec<_>`: multiple values, optional
   - `Option<Vec<_>>`: multiple values, min values of 0, optional
   
   After:
   - `bool`: a flag
   - `Option<_>`: not required
   - `Option<Option<_>>` is not required and when it is present, the value
     is not required
   - `Vec<_>`: multiple occurrences, optional
     - optional: `Vec` implies 0 or more, so should not imply required
   - `Option<Vec<_>>`: multiple occurrences, optional
     - optional: Use over `Vec` to detect when no option being present when
       using multiple values
   
   Motivations:
   
   My priorities were:
   1. Are we getting in the users way?
   2. Does the API make sense?
   3. Does the API encourage best practices?
   
   I was originally concerned about the lack of composability with
   `Option<Option<_>>` and `Option<Vec<_>>` (and eventually `Vec<Vec<_>>`).
   It prescribes special meaning to each type depending on where it shows
   up, rather than providing a single meaning for a type generally.  You
   then can't do things like have `Option<_>` mean "required argument with
   optional value" without hand constructing it.  However, in practice the
   outer type correlates with the argument occurrence and the inner type with the
   value.   It is rare to want the value behavior without also the
   occurrence behavior.  So I figure it is probably fine as long as people
   can set the flags to manually get the behavior they want.
   
   `Vec<_>` implies multiple occurrences, rather than multiple values.
   Anecdotally, whenever I've used the old `Arg::multiple`, I thought I was
   getting `Arg::multiple_occurrences` only.  `Arg::multiple_values`,
   without any bounds or delimiter requirement, can lead to a confusing
   user experience and isn't a good default for these.  On top of that, if
   someone does have an unbounded or a delimiter multiple values, they are
   probably also using multiple occurrences.
   
   `Vec<_>` is optional because a `Vec` implies 0 or more, so we stick to
   the meaning of the rust type.  At least for me, I also rarely need a
   required with multiple occurrences argument but more often need optional
   with multiple occurrences.
   
   `Option<Vec<_>>` ends up matching `Vec<_>` which can raise the question
   of why have it.  Some users might prefer the type.  Otherwise, this is
   so users can detect whether the argument is present or not when using
   `min_values(0)`.  Rather than defining an entire policy around this and
   having users customize it, or setting `min_values(0)` without the rest
   of a default policy, this gives people a blank slate to work from.
   
   Another design option would have been to not infer any special-type
   settings if someone sets a handful of settings manually, which would
   have avoided the confusion in Issue clap-rs#2599 but I see that being confusing
   (for someone who knows the default, they will be expecting it to be
   additive; which flags disable inferred settings?) and brittle (as flags
   are added or changed, how do we ensure we keep this up?).
   
   Tests were added to ensure we support people customizing the behavior to
   match their needs.
   
   This is not solving:
   - `Vec<Vec<_>>`, see clap-rs#2924
   - `(T1, T2)`, `Vec<(T1, T2)>`, etc, see clap-rs#1717
   - `Vec<Option<_>>` and many other potential combinations
   
   Fixes clap-rs#1772
   Fixes clap-rs#2599
   See also clap-rs#2195

   

   epage committed Nov 5, 2021
   Configuration menu

   • View commit details
   • Copy full SHA for e6dd339
   • Browse repository at this point

   Copy the full SHA

   e6dd339 View commit details

   Browse the repository at this point in the history