Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2025-03-04 15:27:16 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #3457 from epage/docs

Browse source 
docs: Update stale references to AppSettings
This commit is contained in:
Ed Page 2022-02-11 16:11:18 -06:00 • committed by GitHub
commit 9f7d2dc041
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
13 changed files with 50 additions and 58 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -151,7 +151,7 @@ Why use the procedural [Builder API](https://github.com/clap-rs/clap/blob/v3.0.1
**Warning:** These may contain breaking changes between minor releases.
* **unstable-replace**: Enable [`App::replace`](https://github.com/clap-rs/clap/issues/2836)
* **unstable-multicall**: Enable [`AppSettings::Multicall`](https://github.com/clap-rs/clap/issues/2861)
* **unstable-multicall**: Enable [`App::multicall`](https://github.com/clap-rs/clap/issues/2861)
* **unstable-grouped**: Enable [`ArgMatches::grouped_values_of`](https://github.com/clap-rs/clap/issues/2924)
## Sponsors

2
clap_complete/src/shells/bash.rs
View file

@ -172,7 +172,7 @@ fn option_details_for_path(app: &App, path: &str) -> String {
}
fn vals_for(o: &Arg) -> String {
debug!("vals_for: o={}", o.get_name());
debug!("vals_for: o={}", o.get_id());
if let Some(vals) = o.get_possible_values() {
format!(

4
clap_complete/src/shells/zsh.rs
View file

@ -442,7 +442,7 @@ fn write_opts_of(p: &App, p_global: Option<&App>) -> String {
let mut ret = vec![];
for o in p.get_opts() {
debug!("write_opts_of:iter: o={}", o.get_name());
debug!("write_opts_of:iter: o={}", o.get_id());
let help = o.get_help().map_or(String::new(), escape_help);
let conflicts = arg_conflicts(p, o, p_global);
@ -626,7 +626,7 @@ fn write_positionals_of(p: &App) -> String {
let mut ret = vec![];
for arg in p.get_positionals() {
debug!("write_positionals_of:iter: arg={}", arg.get_name());
debug!("write_positionals_of:iter: arg={}", arg.get_id());
let cardinality = if arg.is_multiple_values_set() || arg.is_multiple_occurrences_set() {
"*:"

2
examples/derive_ref/README.md
View file

@ -144,7 +144,7 @@ And for `Subcommand` variants:
- `skip`: Ignore this variant
- `flatten`: Delegates to the variant for more subcommands (must implement `Subcommand`)
- `subcommand`: Nest subcommands under the current set of subcommands (must implement `Subcommand`)
- `external_subcommand`: `clap::AppSettings::AllowExternalSubcommand`
- `external_subcommand`: `clap::App::allow_external_subcommand(true)`
- Variant must be either `Variant(Vec<String>)` or `Variant(Vec<OsString>)`
### Arg Attributes

2
examples/multicall-busybox.md
View file

@ -2,7 +2,7 @@
Example of a busybox-style multicall program
See the documentation for clap::AppSettings::Multicall for rationale.
See the documentation for `clap::App::multicall` for rationale.
This example omits every command except true and false,
which are the most trivial to implement,

2
examples/multicall-hostname.md
View file

@ -2,7 +2,7 @@
Example of a `hostname-style` multicall program
See the documentation for clap::AppSettings::Multicall for rationale.
See the documentation for `clap::App::multicall` for rationale.
This example omits the implementation of displaying address config

4
examples/tutorial_builder/README.md
View file

@ -109,9 +109,7 @@ clap [..]
```
You can use `AppSettings` to change the application level behavior of clap. You
can apply the setting to the top level command (`app.setting()`) or to it and
all subcommands (`app.global_setting()`).
You can use `App` methods to change the application level behavior of clap.
[Example:](02_app_settings.rs)
```console

4
examples/tutorial_derive/README.md
View file

@ -111,9 +111,7 @@ clap [..]
```
You can use `AppSettings` to change the application level behavior of clap. You
can apply the setting to the top level command (`app.setting()`) or to it and
all subcommands (`app.global_setting()`).
You can use `App` methods to change the application level behavior of clap.
[Example:](02_app_settings.rs)
```console

34
src/build/app.rs
View file

@ -514,7 +514,7 @@ impl<'help> App<'help> {
/// Parse the specified arguments, exiting on failure.
///
/// **NOTE:** The first argument will be parsed as the binary name unless
/// [`AppSettings::NoBinaryName`] is used.
/// [`App::no_binary_name`] is used.
///
/// # Panics
///
@ -552,7 +552,7 @@ impl<'help> App<'help> {
/// perform a [`std::process::exit`] yourself.
///
/// **NOTE:** The first argument will be parsed as the binary name unless
/// [`AppSettings::NoBinaryName`] is used.
/// [`App::no_binary_name`] is used.
///
/// # Panics
///
@ -597,7 +597,7 @@ impl<'help> App<'help> {
/// perform a [`std::process::exit`] yourself.
///
/// **NOTE:** The first argument will be parsed as the binary name unless
/// [`AppSettings::NoBinaryName`] is used.
/// [`App::no_binary_name`] is used.
///
/// # Panics
///
@ -851,7 +851,7 @@ impl<'help> App<'help> {
/// # Examples
///
/// ```rust
/// # use clap::{App, arg, AppSettings};
/// # use clap::{App, arg};
/// let m = App::new("myprog")
/// .no_binary_name(true)
/// .arg(arg!(<cmd> ... "commands to run"))
@ -1293,7 +1293,7 @@ impl<'help> App<'help> {
/// **CAUTION:** This setting can interfere with [positional/free arguments], take care when
/// designing CLIs which allow inferred subcommands and have potential positional/free
/// arguments whose values could start with the same characters as subcommands. If this is the
/// case, it's recommended to use settings such as [`AppSettings::ArgsNegateSubcommands`] in
/// case, it's recommended to use settings such as [`App::args_conflicts_with_subcommands`] in
/// conjunction with this setting.
///
/// **NOTE:** This choice is propagated to all child subcommands.
@ -2635,7 +2635,7 @@ impl<'help> App<'help> {
/// # Examples
///
/// ```rust
/// # use clap::{App, Arg, AppSettings, };
/// # use clap::{App, Arg};
/// App::new("myprog")
/// .subcommand(
/// App::new("test").hide(true)
@ -2658,7 +2658,7 @@ impl<'help> App<'help> {
/// # Examples
///
/// ```rust
/// # use clap::{App, AppSettings, ErrorKind};
/// # use clap::{App, ErrorKind};
/// let err = App::new("myprog")
/// .subcommand_required(true)
/// .subcommand(App::new("test"))
@ -2689,7 +2689,7 @@ impl<'help> App<'help> {
/// # Examples
///
/// ```rust
/// # use clap::{App, AppSettings};
/// # use clap::App;
/// // Assume there is an external subcommand named "subcmd"
/// let m = App::new("myprog")
/// .allow_external_subcommands(true)
@ -2736,7 +2736,7 @@ impl<'help> App<'help> {
///
#[cfg_attr(not(unix), doc = " ```ignore")]
#[cfg_attr(unix, doc = " ```")]
/// # use clap::{App, AppSettings};
/// # use clap::App;
/// // Assume there is an external subcommand named "subcmd"
/// let m = App::new("myprog")
/// .allow_invalid_utf8_for_external_subcommands(true)
@ -2784,7 +2784,7 @@ impl<'help> App<'help> {
/// # Examples
///
/// ```rust
/// # use clap::{App, AppSettings};
/// # use clap::App;
/// App::new("myprog")
/// .args_conflicts_with_subcommands(true);
/// ```
@ -2824,7 +2824,7 @@ impl<'help> App<'help> {
/// # Examples
///
/// ```rust
/// # use clap::{App, AppSettings, Arg};
/// # use clap::{App, Arg};
/// let app = App::new("app").subcommand(App::new("sub")).arg(
/// Arg::new("arg")
/// .long("arg")
@ -2874,7 +2874,7 @@ impl<'help> App<'help> {
/// This first example shows that it is an error to not use a required argument
///
/// ```rust
/// # use clap::{App, Arg, AppSettings, ErrorKind};
/// # use clap::{App, Arg, ErrorKind};
/// let err = App::new("myprog")
/// .subcommand_negates_reqs(true)
/// .arg(Arg::new("opt").required(true))
@ -2891,7 +2891,7 @@ impl<'help> App<'help> {
/// valid subcommand is used.
///
/// ```rust
/// # use clap::{App, Arg, AppSettings, ErrorKind};
/// # use clap::{App, Arg, ErrorKind};
/// let noerr = App::new("myprog")
/// .subcommand_negates_reqs(true)
/// .arg(Arg::new("opt").required(true))
@ -2926,7 +2926,7 @@ impl<'help> App<'help> {
/// such as deduplicating code across multiple programs
/// without loading a shared library at runtime.
///
/// Multicall can't be used with [`NoBinaryName`] since they interpret
/// Multicall can't be used with [`no_binary_name`] since they interpret
/// the command name in incompatible ways.
///
/// # Examples
@ -2949,7 +2949,7 @@ impl<'help> App<'help> {
/// This does not allow the subcommand to be passed as the first non-path argument.
///
/// ```rust
/// # use clap::{App, AppSettings, ErrorKind};
/// # use clap::{App, ErrorKind};
/// let mut app = App::new("hostname")
/// .multicall(true)
/// .subcommand(App::new("hostname"))
@ -2976,7 +2976,7 @@ impl<'help> App<'help> {
/// and as subcommands of the "main" applet.
///
/// ```rust
/// # use clap::{App, AppSettings};
/// # use clap::App;
/// fn applet_commands() -> [App<'static>; 2] {
/// [App::new("true"), App::new("false")]
/// }
@ -3003,7 +3003,7 @@ impl<'help> App<'help> {
/// so it's recommended to use [`App::subcommand_help_heading`] and
/// [`App::subcommand_value_name`] to change the descriptive text as above.
///
/// [`NoBinaryName`]: crate::AppSettings::NoBinaryName
/// [`no_binary_name`]: crate::App::no_binary_name
/// [`App::subcommand_value_name`]: crate::App::subcommand_value_name
/// [`App::subcommand_help_heading`]: crate::App::subcommand_help_heading
#[inline]

20
src/build/arg.rs
View file

@ -486,8 +486,9 @@ impl<'help> Arg<'help> {
/// **NOTE:** Setting this requires [`Arg::takes_value`]
///
/// **CAUTION:** Using this setting *and* having child subcommands is not
/// recommended with the exception of *also* using [`crate::AppSettings::ArgsNegateSubcommands`]
/// (or [`crate::AppSettings::SubcommandsNegateReqs`] if the argument marked `Last` is also
/// recommended with the exception of *also* using
/// [`crate::App::args_conflicts_with_subcommands`]
/// (or [`crate::App::subcommand_negates_reqs`] if the argument marked `Last` is also
/// marked [`Arg::required`])
///
/// # Examples
@ -1468,9 +1469,9 @@ impl<'help> Arg<'help> {
/// To take a full command line and its arguments (for example, when writing a command wrapper):
///
/// ```
/// # use clap::{App, AppSettings, Arg, ValueHint};
/// # use clap::{App, Arg, ValueHint};
/// App::new("prog")
/// .setting(AppSettings::TrailingVarArg)
/// .trailing_var_arg(true)
/// .arg(
/// Arg::new("command")
/// .takes_value(true)
@ -2333,7 +2334,7 @@ impl<'help> Arg<'help> {
/// ```
///
/// Will result in everything after `--` to be considered one raw argument. This behavior
/// may not be exactly what you are expecting and using [`crate::AppSettings::TrailingVarArg`]
/// may not be exactly what you are expecting and using [`crate::App::trailing_var_arg`]
/// may be more appropriate.
///
/// **NOTE:** Implicitly sets [`Arg::takes_value(true)`] [`Arg::multiple_values(true)`],
@ -2372,9 +2373,6 @@ impl<'help> Arg<'help> {
///
/// **NOTE:** This implicitly sets [`Arg::takes_value(true)`].
///
/// **NOTE:** This setting effectively disables `AppSettings::ArgRequiredElseHelp` if used in
/// conjunction as it ensures that some argument will always be present.
///
/// # Examples
///
/// First we use the default value without providing any value at runtime.
@ -2920,8 +2918,8 @@ impl<'help> Arg<'help> {
/// This can be helpful for arguments with very long or complex help messages.
/// This can also be helpful for arguments with very long flag names, or many/long value names.
///
/// **NOTE:** To apply this setting to all arguments consider using
/// [`crate::AppSettings::NextLineHelp`]
/// **NOTE:** To apply this setting to all arguments and subcommands, consider using
/// [`crate::App::next_line_help`]
///
/// # Examples
///
@ -3018,7 +3016,7 @@ impl<'help> Arg<'help> {
/// **NOTE:** Setting this requires [`Arg::takes_value`]
///
/// To set this for all arguments, see
/// [`AppSettings::HidePossibleValues`][crate::AppSettings::HidePossibleValues].
/// [`App::hide_possible_values`][crate::App::hide_possible_values].
///
/// # Examples
///

4
src/build/value_hint.rs
View file

@ -48,11 +48,11 @@ pub enum ValueHint {
/// common when writing shell wrappers that execute anther command, for example `sudo` or `env`.
///
/// This hint is special, the argument must be a positional argument and have
/// [`.multiple_values(true)`] and App must use [`AppSettings::TrailingVarArg`]. The result is that the
/// [`.multiple_values(true)`] and App must use [`App::trailing_var_arg(true)`]. The result is that the
/// command line `my_app ls -la /` will be parsed as `["ls", "-la", "/"]` and clap won't try to
/// parse the `-la` argument itself.
///
/// [`AppSettings::TrailingVarArg`]: crate::AppSettings::TrailingVarArg
/// [`App::trailing_var_arg(true)`]: crate::App::trailing_var_arg
/// [`.multiple_values(true)`]: crate::Arg::multiple_values()
CommandWithArguments,
/// Name of a local operating system user.

24
src/error/kind.rs
View file

@ -252,15 +252,15 @@ pub enum ErrorKind {
/// ```
MissingRequiredArgument,
/// Occurs when a subcommand is required (as defined by [`AppSettings::SubcommandRequired`]),
/// Occurs when a subcommand is required (as defined by [`App::subcommand_required`]),
/// but the user does not provide one.
///
/// # Examples
///
/// ```rust
/// # use clap::{App, AppSettings, ErrorKind};
/// # use clap::{App, ErrorKind};
/// let err = App::new("prog")
/// .setting(AppSettings::SubcommandRequired)
/// .subcommand_required(true)
/// .subcommand(App::new("test"))
/// .try_get_matches_from(vec![
/// "myprog",
@ -270,7 +270,7 @@ pub enum ErrorKind {
/// # ;
/// ```
///
/// [`AppSettings::SubcommandRequired`]: crate::AppSettings::SubcommandRequired
/// [`App::subcommand_required`]: crate::App::subcommand_required
MissingSubcommand,
/// Occurs when the user provides multiple values to an argument which doesn't allow that.
@ -293,7 +293,7 @@ pub enum ErrorKind {
///
/// To allow arbitrary data
/// - Set [`Arg::allow_invalid_utf8`] for argument values
/// - Set [`AppSettings::AllowInvalidUtf8ForExternalSubcommands`] for external-subcommand
/// - Set [`App::allow_invalid_utf8_for_external_subcommands`] for external-subcommand
/// values
///
/// # Platform Specific
@ -304,7 +304,7 @@ pub enum ErrorKind {
///
#[cfg_attr(not(unix), doc = " ```ignore")]
#[cfg_attr(unix, doc = " ```")]
/// # use clap::{App, Arg, ErrorKind, AppSettings};
/// # use clap::{App, Arg, ErrorKind};
/// # use std::os::unix::ffi::OsStringExt;
/// # use std::ffi::OsString;
/// let result = App::new("prog")
@ -319,7 +319,7 @@ pub enum ErrorKind {
/// ```
///
/// [`Arg::allow_invalid_utf8`]: crate::Arg::allow_invalid_utf8
/// [`AppSettings::AllowInvalidUtf8ForExternalSubcommands`]: crate::AppSettings::AllowInvalidUtf8ForExternalSubcommands
/// [`App::allow_invalid_utf8_for_external_subcommands`]: crate::App::allow_invalid_utf8_for_external_subcommands
InvalidUtf8,
/// Not a true "error" as it means `--help` or similar was used.
@ -340,16 +340,15 @@ pub enum ErrorKind {
DisplayHelp,
/// Occurs when either an argument or a [`Subcommand`] is required, as defined by
/// [`AppSettings::ArgRequiredElseHelp`] and
/// [`AppSettings::SubcommandRequiredElseHelp`], but the user did not provide
/// [`App::arg_required_else_help`] , but the user did not provide
/// one.
///
/// # Examples
///
/// ```rust
/// # use clap::{App, Arg, AppSettings, ErrorKind, };
/// # use clap::{App, Arg, ErrorKind, };
/// let result = App::new("prog")
/// .setting(AppSettings::ArgRequiredElseHelp)
/// .arg_required_else_help(true)
/// .subcommand(App::new("config")
/// .about("Used for configuration")
/// .arg(Arg::new("config_file")
@ -360,8 +359,7 @@ pub enum ErrorKind {
/// ```
///
/// [`Subcommand`]: crate::Subcommand
/// [`AppSettings::ArgRequiredElseHelp`]: crate::AppSettings::ArgRequiredElseHelp
/// [`AppSettings::SubcommandRequiredElseHelp`]: crate::AppSettings::SubcommandRequiredElseHelp
/// [`App::arg_required_else_help`]: crate::App::arg_required_else_help
DisplayHelpOnMissingArgumentOrSubcommand,
/// Not a true "error" as it means `--version` or similar was used.

4
src/parse/matches/arg_matches.rs
View file

@ -962,10 +962,10 @@ impl ArgMatches {
/// with pattern matching!
///
/// ```rust
/// # use clap::{App, AppSettings};
/// # use clap::App;
/// // Assume there is an external subcommand named "subcmd"
/// let app_m = App::new("myprog")
/// .setting(AppSettings::AllowExternalSubcommands)
/// .allow_external_subcommands(true)
/// .get_matches_from(vec![
/// "myprog", "subcmd", "--option", "value", "-fff", "--flag"
/// ]);