What is the current stance on ArgSettings vs binary methods?

[epage]

Early in clap3 history, it looks like the plan was to deprecate binary methods on args (e.g. arg.takes_value(true)) in favor of arg settings (e.g. arg.setting(ArgSettings::TakesValue)) in clap2 with them removed in clap3 (see 6fc70d8 and #1037). This was reverted in 82ffb82 to ease the transition.

It looks like all of the method docs were ported to the arg settings and it was then reverted by hand, copying them back over. Now, the examples for binary methods are a mixture of using the method vs using the setting.

What should the expectation be moving forward?

Ideas:

• All docs use binary methods
• All docs use ArgSettings
• All docs use ArgSettings except for the function the example is for
• Move the docs back and put in a deprecation notice for clap 3 which will have them removed in clap4+

And for whatever route we expect the future to be, it seems like we should set the example in all other docs and in clap_derive.

For example

    /// ```rust
    /// # use clap::{App, Arg, ErrorKind, ArgSettings};
    /// let res = App::new("prog")
    ///     .arg(Arg::new("first"))
    ///     .arg(Arg::new("second"))
    ///     .arg(Arg::new("third")
    ///         .setting(ArgSettings::TakesValue)
    ///         .setting(ArgSettings::Last))
    ///     .try_get_matches_from(vec![
    ///         "prog", "one", "two", "three"
    ///     ]);
    ///
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
    /// ```
    /// [index]: Arg::index()
    /// [`UnknownArgument`]: crate::ErrorKind::UnknownArgument
    #[inline]
    pub fn last(self, l: bool) -> Self {

vs

    /// ```rust
    /// # use clap::{App, Arg, ErrorKind, ArgSettings};
    /// let res = App::new("prog")
    ///     .arg(Arg::new("cfg")
    ///         .long("config")
    ///         .short('v')
    ///         .takes_value(true)
    ///         .forbid_empty_values(true))
    ///     .try_get_matches_from(vec![
    ///         "prog", "--config="
    ///     ]);
    ///
    /// assert!(res.is_err());
    /// assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue);
    /// ```
    #[inline]
    pub fn forbid_empty_values(self, empty: bool) -> Self {

[pksunkara]

This is one of the things that is making the current settings audit harder. Some of the settings have pre-requisites on other settings.

This is what I am aiming for:

• All docs use ArgSettings
• When settings depend on others, we provide a convenience method.

[pksunkara]

And how do you want to deal with AppSettings?

[epage]

My comments applied equally to AppSettings and ArgSettings, they should both have functions and both go away. Color is an example of a case where what should be an enum is shoehorned into being 3 settings.

[epage]

Are we agreed on this for it to be worth creating an Issue so this can be tracked as part of the 4.0 milestone?

[pksunkara]

Yes please.

[epage]

#2717
(since creating an issue from a comment in a discussion didn't auto-link it)