The executable suffix is unconditionally stripped off the file path
so that the file name matches subcommands names
without having to add the EXE suffix on different platforms.
mitsuhiko immediately jumped into the examples and got tripped up by the
lack of documentation on feature flags needed.
I limited this to just the root ones because the rest are in a more
proper tutorial that steps through it all.
This is carried over from the clap_derive examples. Looking over the
other examples, I feel like they are covered by other examples or by the
derive reference. We should call out deny missing docs though.
This creates distinct tutorial examples from complex feature examples
(more how-tos). Both sets are getting builder / derive versions (at
least the critical ones).
This ports our example testing over to [trycmd](https://docs.rs/) so
we can:
- More thoroughly test our examples
- Provide always-up-to-date example usage
The old way of testing automatically picked up examples. This new way
requires we have a `.md` file that uses the example in some way.
Notes:
- Moved overall example description to the `.md` file
- I added cross-linking between related examples
- `14_groups` had a redundant paragraph (twice talked about "one and
only one"
Since usage parser and yaml are on the way to being deprecated (#8, #9),
doing a rename also seems excessive, so rolling it back.
Past relevant PRs:
- clap-rs/clap#1157
- clap-rs/clap#1257
This reverts commits 24cb8b1..d0abb37 from clap-rs/clap#1840
This is part of #16. clap-rs/clap#1840 wasn't the right call but we
don't have time to make the decision now, so instead of having one
option and changing it in 4.0, this reverts back to clap2 behavior.
Not seeing what this example adds over the other ones. We've already
shown subcommands and shown that `App` has extra behavior for when
definint subcommands.
This better models what users should be doing and makes it so all
comments are more clear. In a prior commit, when a changed an `exit` to
`unwrap`, I disliked the fact that I was mixing an unwrap explanatory
comment in with another comment. This makes them stand apart.
The subcommand examples focus on the various ways of looking up
subcommands except for the main one people should be using. This has
previously caused confusion, see https://github.com/clap-rs/clap/discussions/3000
To keep the examples focused, I only show `ArgMatches::subcommand`. I
figure the examples are not exhaustive and that for the cases when
someone wants to do something more specialized, they can pull up the
API reference.
The comments in these examples say that a `conflicts_with` should
override `required`. This seems to be true one way but not the other,
causing these examples to error out at runtime.
This consolidates two `crate_*!` macro examples into a `app_from_crate`
example.
- This is more of what we expect users to use
- We've talked about splitting the `crate_*` macros out into their own
crate. This shifts the focus to what clap would be providing long
term
This reverts commit 6898fbde33.
PR #2144 added the `license` field but no consumer has been added since
the (like Issue #1768). Since this is not ready yet, I am pulling it
from the 3.0 release.
So far, our main route for pulling a feature from the release has
been to put it behind a `unstable-*` feature flag and to create a
stablization tracking issue. I chose to instead remove the feature
because a write-only field with no effect does not provide values for
people to use in as an early access and so doesn't outweight the cost of
the extra documentation noise and code noise it creates. Additionally,
keeping an `unstable-` feature around when it has such an unknown path
(and time table) to stalbization feels like it violates YAGNI. I'm
uncertain how much of this feature we can implement and not create a
legal trap for users because the crate's license is insufficient for the
final artifact's license. I feel our stabliazation process sshould be
about iteration and collecting user feedback which this doesn't line up
with.
When someone is ready to tackle #1768, it will be easy to revert this
commit and pick up the work again.
Fixes#3001
