Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(builder): Describe current sort semantics #4973

Merged
merged 1 commit into from
Jun 19, 2023
Merged

docs(builder): Describe current sort semantics #4973

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 25 additions & 21 deletions clap_builder/src/builder/arg.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2175,12 +2175,15 @@ impl Arg {

/// Allows custom ordering of args within the help message.
///
/// Args with a lower value will be displayed first in the help message. This is helpful when
/// one would like to emphasise frequently used args, or prioritize those towards the top of
/// the list. Args with duplicate display orders will be displayed in the order they are
/// defined.
/// `Arg`s with a lower value will be displayed first in the help message.
/// Those with the same display order will be sorted.
///
/// **NOTE:** The default is 999 for all arguments.
/// `Arg`s are automatically assigned a display order based on the order they are added to the
/// [`Command`][crate::Command].
/// Overriding this is helpful when the order arguments are added in isn't the same as the
/// display order, whether in one-off cases or to automatically sort arguments.
///
/// To change, see [`Command::next_display_order`][crate::Command::next_display_order].
///
/// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in
/// [index] order.
Expand All @@ -2192,22 +2195,23 @@ impl Arg {
/// # use clap_builder as clap;
/// # use clap::{Command, Arg, ArgAction};
/// let m = Command::new("prog")
/// .arg(Arg::new("a") // Typically args are grouped alphabetically by name.
/// // Args without a display_order have a value of 999 and are
/// // displayed alphabetically with all other 999 valued args.
/// .long("long-option")
/// .short('o')
/// .arg(Arg::new("boat")
/// .short('b')
/// .long("boat")
/// .action(ArgAction::Set)
/// .display_order(0) // Sort
/// .help("Some help and text"))
/// .arg(Arg::new("b")
/// .long("other-option")
/// .short('O')
/// .arg(Arg::new("airplane")
/// .short('a')
/// .long("airplane")
/// .action(ArgAction::Set)
/// .display_order(1) // In order to force this arg to appear *first*
/// // all we have to do is give it a value lower than 999.
/// // Any other args with a value of 1 will be displayed
/// // alphabetically with this one...then 2 values, then 3, etc.
/// .display_order(0) // Sort
/// .help("I should be first!"))
/// .arg(Arg::new("custom-help")
/// .short('?')
/// .action(ArgAction::Help)
/// .display_order(100) // Don't sort
/// .help("Alt help"))
/// .get_matches_from(vec![
/// "prog", "--help"
/// ]);
Expand All @@ -2222,10 +2226,10 @@ impl Arg {
/// Usage: cust-ord [OPTIONS]
///
/// Options:
/// -h, --help Print help information
/// -V, --version Print version information
/// -O, --other-option <b> I should be first!
/// -o, --long-option <a> Some help and text
/// -a, --airplane <airplane> I should be first!
/// -b, --boat <boar> Some help and text
/// -h, --help Print help information
/// -? Alt help
/// ```
/// [positional arguments]: Arg::index()
/// [index]: Arg::index()
Expand Down
31 changes: 13 additions & 18 deletions clap_builder/src/builder/command.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2598,13 +2598,13 @@ impl Command {

/// Set the placement of this subcommand within the help.
///
/// Subcommands with a lower value will be displayed first in the help message. Subcommands
/// with duplicate display orders will be displayed in order they are defined.
/// Subcommands with a lower value will be displayed first in the help message.
/// Those with the same display order will be sorted.
///
/// This is helpful when one would like to emphasize frequently used subcommands, or prioritize
/// those towards the top of the list.
///
/// **NOTE:** The default is 999 for all subcommands.
/// `Command`s are automatically assigned a display order based on the order they are added to
/// their parent [`Command`].
/// Overriding this is helpful when the order commands are added in isn't the same as the
/// display order, whether in one-off cases or to automatically sort commands.
///
/// # Examples
///
Expand All @@ -2613,17 +2613,11 @@ impl Command {
/// # use clap_builder as clap;
/// # use clap::{Command, };
/// let m = Command::new("cust-ord")
/// .subcommand(Command::new("alpha") // typically subcommands are grouped
/// // alphabetically by name. Subcommands
/// // without a display_order have a value of
/// // 999 and are displayed alphabetically with
/// // all other 999 subcommands
/// .about("Some help and text"))
/// .subcommand(Command::new("beta")
/// .display_order(1) // In order to force this subcommand to appear *first*
/// // all we have to do is give it a value lower than 999.
/// // Any other subcommands with a value of 1 will be displayed
/// // alphabetically with this one...then 2 values, then 3, etc.
/// .display_order(0) // Sort
/// .about("Some help and text"))
/// .subcommand(Command::new("alpha")
/// .display_order(0) // Sort
/// .about("I should be first!"))
/// .get_matches_from(vec![
/// "cust-ord", "--help"
Expand All @@ -2639,8 +2633,9 @@ impl Command {
/// Usage: cust-ord [OPTIONS]
///
/// Commands:
/// beta I should be first!
/// alpha Some help and text
/// alpha I should be first!
/// beta Some help and text
/// help Print help for the subcommand(s)
///
/// Options:
/// -h, --help Print help
Expand Down