Review of clap examples in 2.33 and 4.1.4

[kyclark]

First off, thank you for such an amazing crate!

I'm the author of Command-Line Rust (O'Reilly, 2022), a book that challenges readers to write their own versions of 14 existing BSD/GNU utilities like "head" and "comm." I use clap exclusively to handle arguments, but version 2.33 was the latest when I was writing. All the source code and tests are in https://github.com/kyclark/command-line-rust. I've now created a branch showing how to use the builder pattern of v4.1.4 at https://github.com/kyclark/command-line-rust/tree/clap_v4.

I was hoping for two things:

1. Would someone review my v4 code to ensure I'm using the crate to its fullest?
2. Would you like to include these programs as learning examples in your documentation?

[epage]

Would someone review my v4 code to ensure I'm using the crate to its fullest?

Sure!

[epage]

Looks good.

Some thing I saw from a quick glance at the commits

• In one case, you switched to try_get_matches. Any particular reason?
• For one flag, you added Append but still had num_args(0..)? Shouldn't the num_args go away (that allows -t d f l instead of -t d,f,l or -t d -t f -t l)

With the feedback applied

• How are you feeling about clap v4 compared to v2 or argparse?
• Anything you can think of to help in making these suggestions more discoverable for other users? I can't review every program that exists :)

[kyclark]

I can't switch to snapbox right now, but I'm curious to know more about "Tests shouldn't be using const PRG: &str = "cutr" but what assert_cmd/snapbox give you for looking up the binary". I use Command::cargo_bin(PRG) to find the program name. Do you mean something different?

[kyclark]

I've moved programs 2-6 to use derive, and the light bulb really went off. I like this interface a lot, it just took a bit to get used to. I still think that the builder might be easier to teach a beginner, but the ease of derive is pretty amazing. The automatic type conversion to standard types is easy, but why can't I use range on usize? I find I can convert my programs to use u64 or i32, but I was curious about this. I'm stuck on program 7 as I'm not sure how to use ArgGroup.

[kyclark]

• I wasn't sure what I was doing with try_get_matches. I thought I had made a mistake. Just get_matches seems to fulfill my wishes.
• I found I need num_args(0..) to handle -t f d for findr

I stumbled around moving from v2 to v4, but now I'm liking v4. I appreciate the type conversions a la "argparse." I do think more cookbook examples will make things more discoverable. This is astoundingly great work, BTW. Just a fabulous crate. About a 1/3 of the book is just explaining how to use clap to avoid writing a lot of very painful code!

[epage]

I can't switch to snapbox right now, but I'm curious to know more about "Tests shouldn't be using const PRG: &str = "cutr" but what assert_cmd/snapbox give you for looking up the binary". I use Command::cargo_bin(PRG) to find the program name. Do you mean something different?

Sorry, I missed that you were using cargo_bin and thought you were using new. That is an okay-ish solution. The cargo_bin! macro is more resilient but doesn't work in as many situations.

The automatic type conversion to standard types is easy, but why can't I use range on usize?

The problem is the field declaration syntax is unchanged, so instead you need to do #[arg(value_parser = value_parser!(usize).range(3..6))]

I'm stuck on program 7 as I'm not sure how to use ArgGroup.

https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html#argument-relations covers arg groups.

We actually implicitly create arg groups for you with clap v4 but they aren't fully implemented. #4688 will add support for #[group(...)] attributes to customize them. Then once we properly support nesting of groups, #3165 will be done. What I'm excited about is #2621.

I do think more cookbook examples will make things more discoverable.

I've really been liking the "real world program" parts of the cookbook like "git" as people can think "I saw this feature in X but don't know what its called". If you have programs you think highlight what you feel is missing from the cookbook, feel free to mention or contribute them!

[epage]

Would you like to include these programs as learning examples in your documentation?

I'll have to look first to see what would work out. We try to balance providing familiar examples (e.g. our git example) with not overwhelming the user.

[epage]

Some of the examples do do less common things and having a familiar name can make it easier to discover ("Oh, X command does what I want, I can copy that").

The question is whether we should do a straight copy or just point people to your book / repo for further examples.

[kyclark]

I wrote an appendix for my first book (Tiny Python Projects) showing many straightforward examples of using "argparse" for basic programs. I'm happy to email you a PDF if you want to take a look. I think cookbooks are a great way to go, making clear/orthogonal examples of many different scenarios. I do believe the GitHub repo for my command-line book will eventually show lots of examples using 2.33 (published) and the builder and derive patterns for v4.

[epage]

builder pattern

Any particular reason you stuck with the builder API? The builder API is our more advanced, low level API so which you use probably depends on your target audience

[kyclark]

Years ago when I was first coming to Rust from Python, this was the most familiar to Python's "argparse." I'm not sure the derive pattern was even available back then. I guess I find it very straightforward or at least explicit. The derive pattern feels like magic almost, and I worry how I might describe this to beginners in Rust. I will probably create a separate branch to teach myself the derive pattern and compare which I find easiest.

[epage]

I can understand and clap v4 should feel even more like argparse as it was the inspiration for some of the ideas we used to clean up the API.

[kyclark]

I would like to try using derive now. When I try cargo add clap --features derive, I get an error "failed to select a version for once_cell." How do I get past this?

[epage]

I'd have to see the error to know why. It could be because the newest once_cell is too new for your version of rust and you need to downgrade it to a safe version. Another one is something else has a conflicting version requirement. The third is if cargo didn't correctly update enough of your lock file. I usually just deleted my lock file in these cases.

[kyclark]

Removing Cargo.lock fixed my problem. Thanks.