Document (and possibly improve) how to create commands without options with the combinatoric API

[mks-h]

Hi! This is my first time using this library, and I find it pretty cool and useful. The docs are great, too — although I wish the library was a little bit more self-explanatory, but you can't have it all.

Anyway, I've spent quite some time reading docs to no avail, searching for issues and discussions, experimenting with code, and was in the middle of writing a discussion post of my own when I finally realized how to make a command parser without any options of its own using the combinatoric API.

The first solution was to have a pure value as the only option, like so:

enum Command {
	Run { _placeholder: () },
	// ...
}

fn run() -> impl bpaf::Parser<Command> {
	let _placeholder = bpaf::pure(());

	bpaf::construct!(Command::Run { _placeholder })
		.to_options()
		.descr("Run something")
		.command("run")
}

This made it work, but I still had to destructure a useless value when using it:

match inv.command {
	cmd::Command::Run { _placeholder } => {}
	// ...
}

However the real solution was much closer to what I tried naturally, just needed somewhat unexpected changes:

#[derive(Clone)]
enum Command {
	Run,
	// ...
}

fn run() -> impl bpaf::Parser<Command> {
	bpaf::construct!(Command::Run {})
		.to_options()
		.descr("Run something")
		.command("run")
}

The first unexpected thing is that the construct! macro didn't work with just Command::Run — failing with "unexpected token in input" from rust-analyzer, and this build error:

error: no rules expected `::`
   --> src/cmd.rs:50:26
    |
50  |     bpaf::construct!(Command::Run)
    |                             ^^ no rules expected this token in macro call
    |
note: while trying to match `(`
   --> /home/mks/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/bpaf-0.9.19/src/lib.rs:418:52
    |
418 |     (@prepare $ty:tt [$($fields:tt)*] $field:ident () $(, $($rest:tt)*)? ) => {{
    |                                                    ^

So I had to add empty curly braces {} which gave me a different error that suggested adding #[derive(Clone)] to the Command enum.

Regular error on `.to_options()` suggesting I derive Clone on my enum

error[E0599]: the method `to_options` exists for struct `ParsePure<Command>`, but its trait bounds were not satisfied
   --> src/cmd.rs:48:4
    |
8   |   pub enum Command {
    |   ---------------- doesn't satisfy `cmd::Command: Clone`
...
47  | /     bpaf::construct!(Command::Run {})
48  | |         .to_options()
    | |         -^^^^^^^^^^ method cannot be called on `ParsePure<Command>` due to unsatisfied trait bounds
    | |_________|
    |
    |
   ::: /home/mks/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/bpaf-0.9.19/src/structs.rs:852:1
    |
852 |   pub struct ParsePure<T>(pub(crate) T);
    |   ----------------------- doesn't satisfy `_: Parser<Command>`
    |
    = note: the following trait bounds were not satisfied:
            `cmd::Command: Clone`
            which is required by `bpaf::structs::ParsePure<cmd::Command>: Parser<cmd::Command>`
help: consider annotating `cmd::Command` with `#[derive(Clone)]`
    |
8   + #[derive(Clone)]
9   | pub enum Command {
    |

And adding the derive made it finally work!

So, I think it would be really cool to add documentation on how to properly do this to the appropriate tutorial page, and the command method.

Bonus points if the library could be made to support the proper syntax to construct empty enum variants (remove the need for curly braces).

P.S. Now I know that all struct members must implement Clone, I just didn't notice it before since most things implement it, and I didn't need to use pure values of enums.
P.P.S. I did find a discussion which showed how to achieve the same setup with the derive API, and it seems much more self-explanatory (whether it is documented or not — I haven't checked).

[pacak]

So... There's nothing special about construct! macro. All it does is taking several parsers and giving you something that is impl Parser<Foo>. You can use .to_options().command("foo") on any other parser - and you almost got it yourself! Just make whatever you actually want with pure and use that.

use bpaf::*;

#[derive(Debug, Clone, Copy)]
enum Commands {
    Unus,
}

fn main() {
    let unus = pure(Commands::Unus).to_options().command("unus");
    let parser = unus.to_options();
    println!("{:?}", parser.run());
}

[pacak]

But you are right, I'll update the construct! macro to work with field-less enums and structs - this behavior totally makes sense,

[mplanchard]

Just adding a note that this took me ages to figure out, too, so seconding the request for an example in the Commands docs or elsewhere.

I had already made a subcommand for a data variant, following the docs, and then I moved on to a dataless variant.

I intuitively tried construct!(Command::Whatever {}) but, since I hadn't derived Clone on my enum, the LSP didn't suggest .to_options(), which led to me thinking it didn't work rather than trying it and seeing the trait bounds error. I had the same issue when I also tried the pure option. Definitely first-timer error, but could be avoided with examples in the docs I think

[pacak]

Yeah, I guess I'll add it when I have some time.

FWIW I tried to make construct! to work with pure variants - and that's not possible due to macro_rules! limitations: without access to type information I can't tell if construct!(Foo) tries to make a parser that just returns FooorFooitself is a parser and should be called. While it's possible to special case a single element construct to always bepure` - it would change current behavior and I don't want to break existing code that might rely on it.