Instead of just renaming it, I reconsidered what the API should look
like. A custom separator for author does not make sense positionally
but accepting a name, and defaulting it, does fit with what someone
would expect.
I removed the `_from_crate` suffix because it doesn't seem necessary.
We don't have this kind of naming for the derive. I feel it cleans
things up this way.
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.
Now that we can use `SubcommandRequired |
ArgRequiredElseHelp`, this setting offers little value but requires we
track required subcommands with two different settings. Deprecating as
the cost is not worth the benefit anymore.
Issue #3280 will see the derive updated
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.
This is inspired by cargo which allows you to run `cargo test --test`
and it will list the possible tests (obviously we can't support that atm
because that requires a lot of runtime processing). When we do have a
static list of possible values, we can at least show those.
Fixes#3320
For some errors, we use the unroll logic to get the list of required
arguments. The usage then does the same, but without a matcher. This
was causing the lists to not match.
As a side effect, this fixed an ordering issue where we were putting the
present arg after the not-present arg. I assume its because we ended up
reporting the items twice but the first time is correctly ordered and
gets precedence.
This was split out of #3020
When an Arg uses .min_values(0), that arg's value(s) are effectively
optional. This is conventionaly denoted in help messages by wrapping the
arg's values in square brackets. For example:
--foo[=value]
--bar [value]
This kind of argument can be seen in the wild in many git commands; e.g.
git-status(1).
Signed-off-by: Peter Grayson <pete@jpgrayson.net>
We were only tracking the last value source (default, env, cli, etc).
This works for args because they only come from one source. Groups
however can come from multiple sources and this was making us treat a
group with a default value as being completely from defaults despite
some values maybe being from the commandline.
We now track the highest precedence value for a group.
Fixes#3330
I thought I was adding a test in #3305. Maybe I considered the
clap_complete changes sufficient for this. Doing more `debug_assert`s
would be good also.
Unsetting `PropagateVersion` helps in some cases but we need to unset it
globally to override the global propagation.
Fixes#3310
The error was when doing `#[clap(arg_enum, default_value_t = ...)]`.
Good example of why we should minimize `use`, at least in tests
(besides reducing merge conflicts, code churn, etc).
This reverts commit 333b993481.
PR #1810's motivation was effectively "this is redundant with `\n`".
That is a fine motivation. Unfortunately, we don't have a way to force
a hard break in `clap_derive`. #2389 should help with this eventually
but we shouldn't hold up 3.0 to get that ready. So in the mean time, we
are restoring `{n}`.
We have #3230 for tracking the re-removal of it.
This allows two overriding args to interact with each other mid-line.
This was broken in 7673dfc / #1154. Before that, we duplicated the override
logic in several places.
Now we plug into the start of a new arg which allows us to do this
incrementally without making the logic complex or inefficient, thanks to
prior refactors.
Fixes#3217
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 main care about is that when we override a `flatten` / `subcommand`
doc comment in a parent container, that we make sure we take nothing
from the child container, rather than implicitly taking one `about` ut
not `long_about`.
To do this, and to play the most safe with long help detection, we reset
`long_about` to default when there is no doc comment body to use for
`long_about`.
Fixes#2983
We have two ways of fixing this
- Making `--help` work
- Don't put `--help` in the help output
For now, I went with the latter. I tried to make it clear what the
actual requirement is so we can pivot if needed.
Fixes#2892
This happens to also fix the interaction of `DisableHelpFlag` with the
help subcommand and complcations. I've added a test to help catch if we
break this by changing how we fixed the original issue.
Fixes#2724
These issues were reported against clap3. I've not tried to reproduce
these in clap2 to see if they should show up in the release notes.
I'm assuming we won't have a negative performance impact by removing
`impl Copy for Id` because the compiler would inline the `clone()`s and
turn them into copies.
Addresses problems from #3164
Adding in a `StructOpt` derive with `structopt` attributes, with
deprecation notices. Unofrtunately, not as many deprecation warnings as
I would like. Apparently, you can't do them for a `use` of a derive? I
also wanted to inject code that would trigger a deprecation notice for
attributes but that would require enough of a refactor that I didn't
consider it worth it. We are at least providing a transition window
even if it means we'll have to remvoe it next major release without a
deprecation warning.
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 is prep for moving the derive tests. Besides organizing the test
folder for each API, this should reduce link time at the cost of
re-compiling more when a test changes.
This both distances itself from our 'require' terminology and aligns
itself with `Option::expect`, making it more likely for people to guess
the intended behavior.
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"
This is intended to replace the runtime usage parser and is not meant to
be a complete API in of itself, like `clap_app!`. What is in scope is
everything that visually makes sense as in a usage string (see
[docopt](http://docopt.org/) for inspiration). General setting of
attributes is out of scope.
This deviates from both `clap_app` and the runtime usage parser
- `clap_app` supported multiple values but has a bug because we made
`Arg::value_name` non-appending, so we aren't supporting this yet
- We do not yet support optional flags that take a value
- In both, `...` is multiple occurrences and values while its only
multiple occurrences for us
- We explicitly support optional values for flags
- Unlike `clap_app`, our name is optional
- Unlike runtime usage parser, our name syntax is simpler
- Unlike runtime usage parser, our name syntax does not allow modifiers
Its more limited than I would like. Hopefully some people better with
macros can expand the feature set and turn more runtime errors into
compile-time errors.
This is to prepare for deprecating the runtime usage parser (#8).
