This is inline with all of our other help-related functions that return
strings.
This is a part of #2164
BREAKING CHANEG: `App::generate_usage` (added in v3) ->
`App::render_usage`.
PR #1211 originally added `help_heading` with the current priority
(`App::help_heading` wins).
In #1958, the author had proposed to change this
> Note that I made the existing arg's heading a priority over the one in App::help_heading
This was reverted on reviewer request because
> Thanks for the priority explanation. Yes, please make the app's help
> heading a priority. I can see how it would be useful when people might
> want to reuse args.
Re-using args is an important use case but this makes life difficult
for anyone using `help_heading` with `clap_derive` because the user
can only call `App::help_heading` once per struct. Derive users can't get
per-field granularity with `App::help_heading` like the builder API.
As a bonus, I think this will be the least surpising to users. Users
generally expect the more generic specification (App) to be overridden by the
more specific specification (Arg). Honestly, I had thought this PR is
how `help_heading` worked until I dug into the code with #2872.
In the argument re-use cases, a workaround is for the reusable arguments
to **not** set their help_heading and require the caller to set it as
needed.
Fixes#2873
2871: Better positional checks r=epage a=pksunkara
2872: Iterate on help_heading to prepare for derive support r=pksunkara a=epage
2876: Generate/bash: add possible_values to completion when available r=pksunkara a=nstinus
Co-authored-by: Pavan Kumar Sunkara <pavan.sss1991@gmail.com>
Co-authored-by: Ed Page <eopage@gmail.com>
Co-authored-by: Nicolas Stinus <nstinus@latourtrading.com>
In part, this is just fixing a papercut where someone will try to use
the API in the same way between the two but it fails and they'll have to
consult the docs / rust-analyzer.
The bigger reason is that this is more derive-friendly for dealing with #2803
since we will be able to just ask for the current help heading
before running the app and then restore it back, rather than having to
conditionalize the revert logic.
For those that want the original behavior, you can usxe
`arg.help_heading(Some("FLAGS"))` on your flags. Limitations:
- This will not give you a special sort order
- This will not get a `[FLAGS]` added to usage
For templates, we removed `{unified}` and `{flags}`. To help people
catch these, a debug_assert was added.
I'm unsure but I think there might be a change in behavior in calcuating
when to show `[OPTION]` in usage. The old code only looked at
`required` while flags looked only at arg groups. We now look at both.
Ideally we'd add these in `_build` and remove special casing for
no-groups except in the sort order of groups. I feel like thats best
left for later.
This also reduced the scope of `App`s public API.
`get_*_with_no_heading` seemed a bit specialized to be in the public
API. #2853 looks at splitting it out into its own PR.
BREAKING CHANGE: Multiple
- `UnifiedHelpMessage` removed
- `{flags}` and `{unified}` are removed and will assert when present.
- `get_*_with_no_heading` removed
Fixes#2807
This partially reverts commit 7f627fc.
This reverts the error code change but not the `ErrorKind` change. I
was mixed on whether we should do that or not. The benefit is it makes
it so people can check the Kind for cases like #2021. On the other
hand, it doesn't seem that hard to re-implement the feature.
Fixes#2767
This was changed in #1989 without an explanation:
- In the help template, there isn't a way to expose with help_headings,
so show all.
- In usage, we don't know whether the user wants to see `[FLAGS]` /
`[OPTIONS]` or not, so let's default to showing them.
* Check for `DisableHelpFlag` along with `NoAutoHelp`
Also applies for `DisableHelpSubcommand` and `DisableVersionFlag` with `NoAutoVersion`
* Add tests for overriding help and version, and disabling version.
These override by disabling the default and adding a new one.
* Don't use `default_missing_value` for `override_version_using_short`
* Check errors by the API.
This changes the `disabled_version_long` and `disabled_version_short` tests.
This is opposed to comparing the stderr output.
* feat(arg_value): ArgValue can be used for possible_values
Through the ArgValue it is possible:
* `hide` possible_values from showing in completion, help and validation
* add `about` to possible_values in completion
* Resolved a few change-requests by epage
* make clippy happy
* add ArgValue::get_visible_value
* remove verbose destructering
* rename ArgValue::get_hidden to ArgValue::is_hidden
* add test for help output of hidden ArgValues
* Documentation for ArgValue
There is an issue that required to implement From<&ArgValue> for
ArgValue. We should probably find a solution without that.
* fix requested changes by epage
* fix formatting
* add deref in possible_values call to remove From<&&str>
* make clippy happy
* use copied() instad of map(|v|*v)
* Finishing up for merge, hopefully
* changes requested by pksunkara
This addresses a bug that causes duplicate flags reported in user-facing
error messages when two flags require one-another but also are required
under other conditions. The fix involves removing duplicates in unrolled
requirements, which addresses the user-facing aspect of this bug.
* Don't suggest `help` or `--help` when not applicable
* Apply suggestions from code review
Co-authored-by: Pavan Kumar Sunkara <pavan.sss1991@gmail.com>
* Update test usage to match intended
Co-authored-by: Pavan Kumar Sunkara <pavan.sss1991@gmail.com>
Because we gradually build the `ArgGroup` as we parse the YAML, we don't
use `ArgGroup::new`. Clap3 introduced an internal `id` in addition to
the public `name` and it appears that this custom initialization code
was not updated.
This shows the problem with publically exposing `impl Default`.
Choices:
- Remove `impl Default`
- Always valid
- Requires spreading invariants
- Callers can't implement code the same way we do
- Add `ArgGroup::name`
- Can be constructed in an invalid state
- Centralizes invariants
- A caller could implement code like the yaml logic
I decided to go with `ArgGroup::name`.
Fixes#2719
Before, validating UTF-8 was all-or-nothing and would cause a `panic` if
someone used the right API with non-UTF-8 input.
Now, all arguments are validated for UTF-8, unless opted-out. This
ensures a non-panicing path forward at the cost of people using the
builder API that previously did `value_of_os` need to now set this flag.
Fixes#751
Improved the `impl`s of `From` for `&'help Yaml` to use expects with useful messages instead of unwraps. Also made changes to avoid potentially fetching redundant data from YAML hashes and unwrapping the same data multiple times. Finally, there are tests to ensure the panics are correct.
* add a new arg option for the max_occurrences
* check ErrorKind in tests
* Updated grammer in doc comments
Co-authored-by: Pavan Kumar Sunkara <pavan.sss1991@gmail.com>
* assert is_err() before unwraping
Co-authored-by: Pavan Kumar Sunkara <pavan.sss1991@gmail.com>
* fix(wip): add necessary debugging prints for analysis
* fix(wip): implement the fix, take 1
* docs: add docstring for `Parser::flag_subcmd_at` and `Parser::flag_subcmd_skip`
* test: make `flag_subcommand_short_after_long_arg` test more realistic
Refactoring and better test cases
Refactored SubcommandHelpShowsLongForm to
UseLongFormatForHelpSubcommand.
Tests and docuemntation examples use about and long_about instead of
(before/after)_help.
Removed commented out tests
Linting: Fix trailing new line
Updated change log, refactored tests and doc str
Reordered items in the Changelog
New test added and old tests removed that were redundant
Doc string for AppSettings::UseLongFormatForHelpSubcommand fixed
Change default help template:
- The new template introduce new lines before and after
author/about sections.
- Add help template placeholders:
- about-section
- author-section
- Documentation of new placeholders in clap::App::help_template
- Update all unit tests by incorporating new lines
Add the suggested changes
Fix test issue_1050_num_vals_and_defaults
It used a required which isn't needed for the purpose of the test.
Add tests for the default+required assertions
Add test for positional args with long or short
Some more fixes in addition to 594c535ba2
* Some I noticed manually.
* Some were found by Topy (https://github.com/intgr/topy), either new
rules from Typo or new code in clap.
* `etc.` and `e.g.` rules were disabled during the last run.
Argument prefixed by `-` will never inferred as a subcommand
Suggest using subcommand when supplied after `--`
Cargo fmt, adding test for wrongly using subcommand after `--`
Fix test
Fix clippy
This commit introduces a new feature called `"regex"`. It adds a new
function `validator_regex` to `Arg` and was inspired by the discussion
in #1968. The name `validator_regex` was chosen instead of
`regex_validator` to make sure that the developer keeps in mind that
there may only be a single `Validator` on an `Arg`.
The feature can be used with YAML files, however there is no proper
pattern in `clap_app!` (yet).
2109: fix: detect if space should be added before spec_vals r=CreepySkeleton a=knidarkness
Co-authored-by: knidarkness <knidarkness@gmail.com>
Co-authored-by: Sergey Dubovyk <knidarkness@gmail.com>
Using `App::get_matches` from the integration tests meant that any
CLI arguments passed to libtest would also be captured by clap, often
causing the tests to fail.
For example, running `cargo test --test help -- --nocapture` would
result in several failed tests, even though `cargo test --test help`
worked fine. This was very surprising/confusing.
This commit makes the tests no longer implicitly rely on the value of
`env::args_os()`, which means developers can now provide arguments to
libtest without failures.
The YAML null value is called `null` in YAML, not `Null`. yaml-rust
handles those values according to spec, so we should use the correct
capitalization.
See https://yaml.org/spec/1.2/spec.html#id2803362 for more
information.
While reading the code for the yaml translation, I've noticed that
there is a bug in the macro `yaml_opt_str` as well as a wrong `null`
value in the test fixture.
These tests add the expected behaviour on the given fixture, e.g.
prog
and
prog <WRONG>
where `<WRONG>` is **not** `other` should yield `None` for
`"positional2"`, whereas
prog other
should yield "something" and
prog --flag ARBITRARY_VALUE
should yield "some". The first two tests
- default_value_if_not_triggered
- default_value_if_not_triggered_by_argument
fail, as the second positional arguments *gets set*, although its
conditions aren't fulfilled.
Adds new method/attribute `Arg::value_hint`, taking a `ValueHint` enum
as argument. The hint can denote accepted values, for example: paths,
usernames, hostnames, commands, etc.
This initial implementation supports hints for the zsh and fish
completion generators, support for other shells can be added later.
Tests to check for conflicts between flag subcommands long and short and
their aliases and args both long and short and their aliases. Tests to
handle self conflicts, where a flag subcommand short or long with have a
corresponding alias with the same value.
Instead of a `FlagSubCommand` struct the addition of two simple methods
to `App`. `App::long_flag` and `App::short_flag` that cover all the
bases of the many methods that were provided in `FlagSubCommand`. This
API is far simpler to use and more akin to the present `Arg::long` and `Arg::short`.
this implements Arg::short_alias, Arg::short_aliases,
Arg::short_visible_alias, and Arg::short_visible_aliases in addition to
adding their associated tests
These are similar to the tests backported to the 2.x branch in
https://github.com/clap-rs/clap/pull/1907. These are more comprehensive,
because the OsStr splitting methods are more robust now.
