In surveying various tools and CLI parsers, I noticed they list the
subcommands first. This puts an emphasis on them which makes sense
because that is most likely what an end user is supposed to pass in
next.
Listing them last aligns with the usage order but it probably doesn't
outweigh the value of getting a user moving forward.
I see them fulfilling two roles
- A form of bolding
- As a callback to their placeholder in usage
However, it is a bit of an unpolished look and no other CLI seems to do
it. This looks a bit more proefessional. We have colored help for
formatting and I think the sections relation to usage will be clear
enough.
Another step towards #1041
This isn't the long term type for `PossibleValue::help`, I just wanted
to get the lifetime out of the way first before figuring out how help
will work.
This is a part of #2870 and is prep for #1041
Oddly enough, this dropped the binary size by 200 Bytes
Compared to `HEAD~` on `06_rustup`:
- build: 6.21us -> 6.23us
- parse: 7.55us -> 8.17us
- parse_sc: 7.95us -> 7.65us
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.
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
A couple of things happened when preparing to release 3.0
- We needed derive documentation
- I had liked how serde handled theres
- I had bad experiences finding things in structopt's documentation
- The examples were broken and we needed tests
- The examples seemed to follow a pattern of having tutorial content and
cookbook content
- We had been getting bug reports from people looking at master and
thinking they were looking at what is currently released
- We had gotten feedback to keep down the number of places that
documentation was located
From this, we went with a mix of docs.rs and github
- We kept the number of content locations at 2 rather than 3 by not
having an external site like serde
- We rewrote the examples into explicit tutorials and cookbooks to align
with the 4 styles of documentation
- We could test our examples by running `console` code blocks with
trycmd
- Documentation was versioned and the README pointed to the last release
This had downsides
- The tutorials didn't have the code inlined
- Users still had a hard time finding and navigating between the
different forms of documentation
- In practice, we were less likely to cross-link between the different
types of documentation
Moving to docs.rs would offer a lot of benefits, even if it is only
designed for Rust-reference documentation and isn't good for Rust derive
reference documentation, tutorials, cookbooks, etc. The big problem was
keeping the examples tested to keep maintenance costs down. Maybe its
just me but its easy to overlook
- You can pull documentation from a file using `#[doc = "path"]`
- Repeated doc attributes get concatenated rather than first or last
writer winning
Remember these when specifically thinking about Rust documentation made
me realize that we could get everything into docs.rs.
When doing this
- Tutorial code got brought in as was one of the aims
- We needed to split the lib documentation and the README to have all of
the linking work. This allowed us to specialize them according to
their rule (user vs contributor)
- We needed to avoid users getting caught up in making a decision
between Derive and Builder APIs so we put the focus on the derive API
with links to the FAQ to help users decide when to use one or the
other.
- Improved cross-referencing between different parts of the
documentation
- Limited inline comments were added to example code
- Introductory example code intentionally does not have teaching
comments in it as its meant to give a flavor or sense of things and
not meant to teach on its own.
This is a first attempt. There will be a lot of room for further
improvement. Current know downsides:
- Content source is more split up for the tutorials
This hopefully addresses #3189
Someone should not reasonably expect a coun flag to go up to billions,
millions, or even thousands. 255 should be sufficient for anyone,
right?
The original type was selected to be consistent with
`ArgMatches::occurrences_of` but that is also used for tracking how
many values appear which can be large with `xargs`.
I'm still conflicted on what the "right type" is an wish we could
support any numeric type. When I did a search on github though, every
case was for debug/quiet flags and only supported 2-3 occurrences,
making a `u8` overkill.
This came out of a discussion on #3792
We aren't enumerating arguments but values for an argument, so the name
should reflect that.
This will be important as part of #1807 when we have more specific
attribute names.
This mostly exist for
- Knowing of the value came from the command-line but we now have
`ArgMatches::source`
- Counting the number of flags but we now have `ArgAction::Count`
This shouldn't be needed anymore now that this is effectively the new
behavior for the non-deprecated actions.
This was briefly talked about in
https://github.com/clap-rs/clap/discussions/2627 but I wasn't familiar
enough with the implementation to know how safe it is. Now, maintainrs
and users can be more confident because they are explicitly opting into
it.
See also #3795
This is the derive support for #3774 (see also #3775, #3777)
This combined with `value_parser` replaces `parser`. The main
frustration with this is that `ArgAction::Count` (the replacement for
`parse(from_occurrences)` must be a `u64`. We could come up with a
magic attribute that is meant to be the value parser's parsed type. We
could then use `TryFrom` to convert the parsed type to the user's type
to allow more. That is an exercise for the future. Alternatively, we
have #3792.
Prep for this included
- #3782
- #3783
- #3786
- #3789
- #3793
