Before, we had the focus on attributes and how they were impacted by
various features. Now we separate out language items and put both magic
and raw attributes under the type of attribute (command, arg, etc)
This is part of the `App` rename.
Previously, I was concerned about not being able to deprecate
For backwards compatibility, we still expose the `IntoApp` name.
No good solution for transitioning the trate name, unfortnately, since
we can't mark `use`s as deprecated (we can, it just does nothing).
I got rid of the `into` prefix because that implies a `self` parameter
that doesn't exist.
Like was said in #2435, this is what people would expect.
While we should note this in a compatibility section in the changelog, I
do not consider this a breaking change since we should be free to adjust
the help output as needed. We are cautious when people might build up
their own content around it (like #3312) but apps should already handle
this with `--help` so this shouldn't be a major change.
We aren't offering a way for people to disable this, assuming people
won't need to. Longer term, we are looking at support "Actions" (#3405)
and expect those to help customize the flags. We'll need something
similar for the `help` subcommand.
Fixes#3440
This is a part of #2717
Some settings didn't get getters because
- They are transient parse settings (e.g. ignore errors)
- They get propagated to args and should be checked there
`is_allow_hyphen_values_set` is a curious case. In some cases, we only
check the app and not an arg. This seems suspicious.
For the derive API, you can only call `next_display_order` when dealing
with a flatten. Until we offer app attributes on arguments, the user can workaround with
this no-op flattens.
This is a part of #1807
This clarifies the intent and prepares for other functions doing the
same, like `next_display_order`. This will then open us to name
`subcommand_help_heading` and `display_order` similar.
The deprecation is waiting on 3.1.
This is part of #1807 and #1553.
`#[clap(about)]` only overrides `about`. If the doc comment also sets
`long_about`, it won't be overridden. This change is to help raise
visibility of reseting `long_about` in these cases.
This just affects how it's rendered; rather than attempting to highlight
these blocks as a shell script, they'll get highlighted as console
output.
See the rendered versions for a better comparison.
While I'm unsure how much type specialization we should do, we
intentionally have the `arg_enum` attribute for doing special behavior
based on it, so let's take advantage of it.
Fixes#3185
The extra whitespace was targeted at machine processing for a subset of
users for a subset of runs of CLIs. On the other hand, there is a lot
of concern over the extra verbose output.
A user can set the help template for man, if desired. They can even do
something (env? feature flag?) to make it only run when doing man
generation. We also have #3174 in the works.
So let's focus on the end-user reading `--help`. People wanting to use
`help2man` have workarounds to do what they need.
Fixes#3096
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.
