Commit graph

69 commits

Author SHA1 Message Date
Ed Page
c9eef44213 fix: Make arg!(--flag <value>) optional by default
This was ported over from the usage parser which modeled after docopt.
We just never got around to implementing the rest of the syntax.

However, when considering this as a standalone feature, an
`arg!(--flag <value>)`, outside of other context, should be optional.
This is how the help would display it.

Fixes #4206
2022-09-12 17:10:01 -05:00
Ed Page
c90a4eabae fix(help): Make output more dense
In looking at other help output, I noticed that they use two spaces, in
place of clap's 4, and it doesn't suffer from legibility.  If it
doesn't make the output worse, let's go ahead and make it as dense so we
fit more content on the screen.

This is a part of #4132
2022-09-07 17:13:55 -05:00
Ed Page
bbb6c38bad fix(help):Be dense on short next line help
If short help is too long for the terminal, clap will automatically
switch to next line help.  As part of next line help for longs, we add a
blank line between args.  This helps make the args clearer when dealing
with multiple paragraphs.  However, its not as much needed for short and
subcommands (always short), so now short matches subcommands.

This was inspired by #3300 and a part of #4132
2022-09-07 14:05:17 -05:00
Ed Page
9a645d2d19 fix(help): Collapse usage to one line
After looking at more examples, I've become more attached to this
briefer format.

Part of #4132
2022-09-07 11:03:57 -05:00
Ed Page
1258f3e5f6 fix: Deprecate Command::allow_negative_numbers
Better to set on individual args
2022-09-07 07:24:42 -05:00
Ed Page
5112372c77 feat(parser): Provide convenience for SetTrue
I wanted to make `bool` a defaulted type parameter but
https://github.com/rust-lang/rust/issues/36887
2022-09-01 19:40:56 -05:00
Ed Page
80ec011b6e feat(parser): Provide convenience accessor for Counts 2022-09-01 19:19:55 -05:00
Ed Page
671914b590 fix(error): Make whitespace consistent with self/help
Sometimes errors would use a tab, sometimes four spaces.  This makes it
always four spaces and shares a definition with help.
2022-08-31 16:02:14 -05:00
Ed Page
65b5b5f7bf fix(help): Remove name/version/author from help
This is to help shorten it and polish it by removing redundant
information.

This is a part of #4132
2022-08-31 15:06:15 -05:00
Ed Page
42c943844c fix(help): Use Command in place of Subcommand
In switching to title case for help headings (#4123), it caused me to
look at "subcommand" in a fresh light.  I can't quite put my finger on
it but "Subcommand" looks a bit sloppy.  I also have recently been
surveying other CLIs and they just use "command" as well.

All of them are commands anyways, just some are children of others
(subcommands) while others are not (root or top-level commands, or just
command).  Context is good enough for clarifying subcommands from root
commands.

This is part of #4132
2022-08-31 08:53:10 -05:00
Ed Page
02d27b5ce3 fix(usage): Make dont_collapse_args_in_usage the default
The setting was added to resolve #769.  The reason it was optional is out
of concern for applications with a lot of positional arguments.  I think
those cases are rare enough that we should just push people to override
the usage.  Positional arguments are generally important enough, even if
optional, to show.

As a side effect, this fixed some bugs with
`dont_collapse_args_in_usage` where it would repeat an argument in a
smart usage.

As a side effect, smart usage now shows `--` when it should
2022-08-30 16:12:49 -05:00
Ed Page
0c9b9d7ec8 fix(parser): Show all required errors at once
This also has the side effect of always using the "smart usage" which is
why the tests changed.
2022-08-29 19:40:35 -05:00
Ed Page
02db3043e2 fix(help): Consistently use [] for positionals
In the usaeg we use `[]` but in the arg list we use `<>`.
2022-08-29 15:34:30 -05:00
Ed Page
83d6add9aa fix(help): Shift focus to subcommands, when present
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.
2022-08-26 10:59:40 -05:00
Ed Page
9b23a09f7a fix(help): Don't rely on ALL CAPS for headers
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.
2022-08-26 10:21:18 -05:00
Ed Page
85f541d789 fix: Switch to owned types
Impact:
- Binary size: 556.6 KiB to 578.4 KiB
- build time: 6.4950 us (7% slower)
- parse time: 7.7256 us
- parse sc time: 8.1580 us (5% faster)

Fixes #1041
Fixes #2150
2022-08-22 14:55:55 -05:00
Ed Page
8cc164dafb fix!: Remove lifetime from PossibleValue
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.
2022-08-19 12:44:29 -05:00
Chris Pryer
8bf39d9275
docs(tutorial): Fix enum example comment 2022-08-13 20:56:27 -04:00
Ed Page
f84e38a4de fix!: Switch from &[] to IntoIterator
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
2022-08-12 15:45:02 -05:00
Ed Page
22c82c7404 docs(tutorial): Further expand on actions 2022-08-09 16:33:02 -05:00
Ed Page
78b2b44b95 docs(tutorial): Focus on actions, not macros 2022-08-09 10:23:23 -05:00
Ed Page
36777e7b6c docs(tutorial): Switch to hand-implemented ValueEnum 2022-08-09 10:23:23 -05:00
Ed Page
571e3a5e15 docs(tutorial): Use arg!s action selection 2022-08-08 14:36:29 -05:00
Ed Page
76bff6f34e fix!: Remove rest of deprecated APIs
Fixes #4009
2022-08-01 15:21:33 -05:00
Ed Page
81bc351cfc fix(help): Show when a flag 'ArgAction::Count's 2022-07-29 09:56:26 -05:00
Ed Page
732a21b1bf test: Make version agnostic 2022-07-23 21:55:30 -05:00
Ed Page
11076a5c70 fix(help)!: Make DeriveDisplayOrder the default, removing it
Force sorting with `next_display_order(None)`

Fixes #2808
2022-07-22 15:52:03 -05:00
Ed Page
389ff4ff21 fix(help): Subcommand display order respects Command::next_display_order
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
2022-07-22 15:03:16 -05:00
Ed Page
a842bd64a0 fix!: Use display_name rather than bin_name in version output 2022-07-22 11:40:30 -05:00
Ed Page
01a3ea425f fix!: Remove unstable-v4 feature gate 2022-07-22 11:34:06 -05:00
Ed Page
d43f1dbf6f docs: Move everything to docs.rs
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
2022-07-19 13:30:38 -05:00
Daniel Saxton
c4612e4c17
docs: Fix typo in derive API README (#3896)
Co-authored-by: Daniel Saxton <dsaxton@pm.me>
2022-07-05 09:49:55 -05:00
Ed Page
9caec5a52d fix(parser): Deprecate ArgMatches::is_present 2022-06-10 14:21:25 -05:00
Ed Page
31b22d1a51 perf(parser): Take up less memory with ArgAction::Count
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
2022-06-09 11:09:38 -05:00
Ed Page
9e38353442 fix(derive): Clarify ArgEnum as ValueEnum
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.
2022-06-08 11:14:09 -05:00
Ed Page
8dde489e3a docs(tutorial): Update for new API 2022-06-08 10:35:06 -05:00
Ed Page
86a162d1bb fix(parser): Deprecate occurrences_of
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`
2022-06-07 13:30:32 -05:00
Ed Page
1428785677 fix(parser): Deprecate args_override_self
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
2022-06-06 14:57:24 -05:00
Ed Page
eda0ca54c1 fix(parser): Simplify the common getter API
Clap has focused on reporting development errors through assertions
rather than mixing user errors with development errors.  Sometimes,
developers need to handle things more flexibly so included in #3732 was
the reporting of value accessor failures as internal errors with a
distinct type.  I've been going back and forth on whether the extra
error pessimises the usability in the common case vs dealing with the
proliferation of different function combinations.  In working on
deprecating the `value_of` functions, I decided that it was going to be
worth duplicating so long as we can keep the documentation focused.
2022-05-25 10:50:42 -05:00
Ed Page
33e94df212 docs(example): Update for value_parser 2022-05-24 14:53:08 -05:00
Ed Page
15616bbd13 fix(error): Remove usage from value validation
When to show usage?  We are currently mixed about it.  For `validator`,
we didn't show it at all.  Sometimes we show the used arguments and
sometimes we don't.

With `ValueParser`, I ran into the problem that we weren't showing the
used arguments like we had previously in some cases.  In deciding how to
solve this, I went with the simplest route for now and removed it as the
usage likely doesn't add much context to help people solve their
problem, more so the recommendation for help.  We'll see how the
feedback is on this and adjust.
2022-05-23 20:56:04 -05:00
Ed Page
253e579781 docs(tutorial): Gradually add concepts for args 2022-05-03 15:40:11 -05:00
Ed Page
dbe8c0c957 docs(tutorial): Prefer custom parsing to validation 2022-03-14 09:31:40 -05:00
Ed Page
14ea156218 docs: Annotate more places with required features 2022-03-03 12:32:29 -06:00
Steve Klabnik
f89c8f4da2 Fix a typo in an example 2022-03-02 08:41:08 -06:00
Ed Page
c55989459f docs(tutorial): Examples as next step 2022-02-22 08:37:13 -06:00
Ed Page
9946579fc9 docs(tutorial): Clarify to debug_assert in tests 2022-02-22 08:29:53 -06:00
Ed Page
360c4d6b8a docs: Update to new command! macro 2022-02-15 08:54:59 -06:00
Ed Page
e8010e79a9 refactor: Update app variables to cmd 2022-02-14 15:55:56 -06:00
Ed Page
c4144d7d6c docs: Update App references to Command 2022-02-14 15:33:49 -06:00