full help when subcommand is missing?

[scottlamb]

I'm playing with a port of my old clap 2 / structopt code to bpaf. It shrinks my binary from 12.3 MiB to 11.9 MiB (great!) but I want to fully match the user friendliness of the original. My outer OptionParser expects a subcommand. Current code here. Draft bpaf code below:

/// Moonfire NVR: security camera network video recorder.
#[derive(Bpaf, Debug)]
#[bpaf(options, version)]
enum Args {
    /// Checks database integrity (like fsck).
    #[bpaf(command)]
    Check(#[bpaf(external(cmds::check::args))] cmds::check::Args),

    /// Interactively edits configuration.
    #[bpaf(command)]
    Config(#[bpaf(external(cmds::config::args))] cmds::config::Args),

    // ...several other variants...
}

Before with clap, if I ran it without a subcommand, I'd see full help output:

$ moonfire-nvr
moonfire-nvr 0.7.5
security camera network video recorder

USAGE:
    moonfire-nvr <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    check      Checks database integrity (like fsck)
    config     Interactively edits configuration
    help       Prints this message or the help of the given subcommand(s)
    init       Initializes a database
    login      Logs in a user, returning the session cookie
    run        Runs the server, saving recordings and allowing web access
    sql        Runs a SQLite3 shell on Moonfire NVR's index database
    ts         Translates between integer and human-readable timestamps
    upgrade    Upgrades to the latest database schema

Now with bpaf, I see only this:

$ moonfire-nvr
Expected COMMAND ..., pass --help for usage information

If I add --help, I get roughly similar output (below), but I'd rather present this information up-front rather than have the terse instruction to run another command. Can I make full --help the default? I don't see an easy way to do this.

The best idea I've got is to have a #[bpaf(fallback(Arg::Help))] where that variant is hidden via #[bpaf(hide)], and then runs something like args().run_inner(bpaf::Args::from(&["--help"])) (and does what the bpaf::ParseFailure says to do). It might work, but it seems super gross.

$ moonfire-nvr --help
Moonfire NVR: security camera network video recorder.

Usage: COMMAND ...

Available options:
    -h, --help     Prints help information
    -V, --version  Prints version information

Available commands:
    check    Checks database integrity (like fsck).
    config   Interactively edits configuration.
    init     Initializes a database.
    login    Logs in a user, returning the session cookie.
             This is a privileged command that directly accesses the database. It doesn't check the
             user's password and even can be used to create sessions with permissions the user doesn't
             have.
    run      Runs the server, saving recordings and allowing web access.
    sql      Runs a SQLite3 shell on Moonfire NVR's index database.
             Note this locks the database to prevent simultaneous access with a running server. The
             server maintains cached state which could be invalidated otherwise.
    ts       Translates between integer and human-readable timestamps.
    upgrade  Upgrades to the latest database schema.

[pacak]

The best idea I've got is to have a #[bpaf(fallback(Arg::Help))] where that variant is hidden via #[bpaf(hide)], and then runs something like args().run_inner(bpaf::Args::from(&["--help"])) (and does what the bpaf::ParseFailure says to do).

This is how I would write it right now

It might work, but it seems super gross.

Sort of and I'm planning to revisit help customization within a month or two to take advantage of longer help generated by #159. If it helps - I can add ParseFailure::run right now that would return a value or exit with corresponding code, it should simplify your code a bit.

[scottlamb]

Thanks! I look forward to that, and yeah, ParseFailure::run would help a bit.

A few other things I noticed, btw:

• seems weird that the Usage: line doesn't have the program name (argv[0]) in it. Every other program I've tried (e.g. GNU utilities, clap-based Rust stuff) does, so folks are used to it. Looks like I can add this myself but I think it should be there by default.
• looks like the optional arguments' defaults (fallbacks in bpaf terms, I guess) aren't shown in the help output? I'll have to do that manually also, which is a bit of duplication I'd like to avoid if there's a good way to do so.
• it'd be a bit more clear IMHO to say SUBCOMMAND rather than COMMAND in usage output, but looks like the latter is hardcoded here.

None of these are deal-breakers for me, I think. bpaf is a very nice crate, and I appreciate how much it will let me shrink my binary, so I think I'll make the switch shortly...

[pacak]

I can add something like this to batteries module so ugly bits are contained inside, gimme an hour or so :)

fn print_usage<T>(parser: OptionParser<T>) {
    std::process::exit(parser.run_inner(Args::from(&["--help"]))).unwrap_err().exit_code())
}

[pacak]

pushed the exit_code branch

[scottlamb]

pushed the exit_code branch

Thanks! Using it now: scottlamb/moonfire-nvr@b1a46cf

[pacak]

You can also try to enable batteries feature and use print_usage from there. Not sure which one fits better. I'll release a new version after I add a way to customize usage string in derive macro, should be today/tomorrow.

[scottlamb]

seems weird that the Usage: line doesn't have the program name (argv[0]) in it. Every other program I've tried (e.g. GNU utilities, clap-based Rust stuff) does, so folks are used to it. Looks like I can add this myself but I think it should be there by default.

Actually, not straightforward with subcommands I think. e.g. moonfire-nvr run --help should say Usage: moonfire-nvr run .... With the derive macro, I'm not sure how to plumb the modified usage to the subcommand.

[pacak]

It looks like I still can't override the usage on a subcommand?

Should be easy to implement, will make something shortly

For my outer enum, I could omit the #[bpaf(options)] and set up what I want by something like .to_options().usage(Box::leak(format!("...").into_boxed_str())

You can keep the #[bpaf(options)] and simply add .usage(Box::leak(format!("...").into_boxed_str()) to a generated name to make your own. I'm trying to keep derive macro to be a very thin layer of syntactic sugar on top of combinatoric API, you can take a look at what code gets generated with and without #[bpaf(options)]

For the inner commands, I don't think there's any way for me to mutate it once after it's constructed from the outer derive macro?

You can do this if you make cmd::check::Args to be a command itself... I'll check the examples and if they are missing - will add something.

[pacak]

pushed to exit_code branch also added an example - https://github.com/pacak/bpaf/blob/exit_code/examples/very_custom_usage.rs - still need to update the docs a bit but I think it should do what you want.

[scottlamb]

Ahh! Yes, that does the trick, thank you!

IMHO, this style of usage should be the default, but it being possible is good enough anyway.

[pacak]

IMHO, this style of usage should be the default, but it being possible is good enough anyway.

Using argv[0] works most of the cases but not always - in case of using it as a cargo command argv[0] is going to be cargo even if binary name is cargo-asm, having deeply nested commands requires specifying the full sequence of commands sometimes with extra flags. All of this is hard to detect automatically. The way it is implemented right now I'm relying on user mentally filling in missing details which seems to work, also keeps usage line tidier.

Anyway, will try to release today.

[scottlamb]

Yeah, good point. Seems like it should be doable though to have a default that produces GNU utility-style output for "normal" commands by default and is still easy to override for the cargo-style utilities. Maybe...

• OptionParser has a notion of command_path that defaults to basename(argv[0]) and can be overridden between construction and run
• the outer usage string defaults to Usage: {command_path} {usage}
• ...my intuition and experience with clap suggests a subcommand "belongs" to a parent and thus its command path can be just the parent's plus the command name. but looking over bpaf's docs, it seems like subcommands don't really belong to the outer OptionParser? so I'm a little fuzzy on how this part would work...I guess it "belongs" to the composition created by construct!? that can take its own path from the OptionParser and plumb the full path through to any supplied commands?

anyway, again, just my two cents, not something I need to use bpaf.

[pacak]

Released, you should be able to switch to published version.

Also I noticed you have this defined in multiple places:

    /// Directory holding the SQLite3 index database.      
    ///                                                                               
    ///                                                                          
    /// default: `/var/lib/moonfire-nvr/db`.                                              
    #[bpaf(argument("PATH"), fallback_with(crate::default_db_dir))]    
    db_dir: std::path::PathBuf,                                   

Argument sharing between multiple different parsers was one of the motivations to make the library. You can make a parser for db and then share it across multiple parser:

fn parse_db_dir() -> impl Parser<PathBuf> {
    argument("PATH").help("Directory holding the SQLite3 index database.\nDefault: `{}`", default_db_dir()).fallback_with(default_db_dir)
}

and use it via external

    /// Directory holding the SQLite3 index database.       // <- this comment is not used by the parser now
    #[bpaf(external(parse_db_dir))]    
    db_dir: std::path::PathBuf,                                   

[scottlamb]

Yeah, I suppose that makes more sense to extract that whole thing than just the default_db_dir part. Thanks!

[pacak]

You can use OptionParser::fallback_to_usage, see https://github.com/pacak/bpaf/blob/bc42de419b15aba586bd4cd2f0b7874f3f915d38/examples/basic.rs