clap-rs VS trycmd

We will be using the library for Clap - A simple-to-use, efficient, and full-featured library for parsing command line arguments and subcommands.

I recently came across this question (and associated answer) on the clap repository. The answer given is a good one. But I wanted to expand with my own findings and practices, which spurred the motivation for this post.

We can also use tuple-like struct syntax and named-field struct syntax for enum variants within our enum; this is because unlike in other OOP languages, Rust enums are actually sum types. You can read more about how powerful Rust enums are in another article we wrote here. You can have optional arguments by simply wrapping the types in Option, but if you want to add a flag to a command you can use bool, since clap recognises that flags are either there or not there. Let's have a look at what this might look like:

I began by developing a wrapper for the CurseForge API, which turned out to be a lengthy and challenging process but constituted the bulk of the work. Next, I coded the CLI, which was relatively straightforward. Instead of using the clap crate, a Rust tool for generating CLIs, I opted for the following line of code:

By this time I had already gotten tired of parsing arguments by myself and had looked for something to help with that. I found a really dang good argument parsing library called clap. What makes it so cool is it's largely declarative for common uses. You simply mark up a struct with attributes, and the parser automatically generates the usage and all the argument parsing code.

How CLI arguments are handled (using clap).

Is this just referring to wrapping based on the terminal width? That is supported with the wrap_help feature though I have been considering making it a default feature.

CLI, use Clap. If you want to get fancy, use Tui.

As our CLI is getting more complex, we'll use the clap crate to parse the command line arguments.

If needed, here is an example of per-word diffing and highlighting of trailing newline differences.

I see. I would try writing the same name as in your Cargo.toml. For example, if yours was toml [package] name = "caesor_cipher" I would try bin.name = "caesor_cipher" It seems that trycmd might ignore a test if the bin.name field is incorrect: https://github.com/assert-rs/trycmd/issues/105

I find rustdoc lacking for clap. rustdoc does a good job with API reference documentation and is improving in its handling of examples but derive reference and tutorial documentation are a weak point.

For examples, its improving with the example scraping work (e.g. https://docs.rs/clap/latest/clap/struct.ArgMatches.html#meth...) but testing of example is still lacking. I've written trycmd to help (https://github.com/assert-rs/trycmd).

For derive reference and tutorial documentation, your choices are

- A very long, hard to navigate top-level documentation, see https://docs.rs/structopt/latest/structopt/

- External documentation, see https://serde.rs/

- Dummy modules to store your documentation (I've seen this used but can't remember one off the top of my head)

For clap, my documentation examples are best served as programs and we've had a problem with these being broken. The Rust CLI book has a decent strategy for this by pulling in code from external files (https://rust-cli.github.io/book/index.html). I was tempted to do that for clap where example code and output (all verified via trycmd) are pulled into an mdbook site but I've stopped short and just have a README that links out to everything (https://github.com/clap-rs/clap/blob/master/examples/tutoria...). Its not great.

Another problem we found in clap was it was easy for our examples to build but harder to make sure they worked. This is why I wrote trycmd (example "tests").

Would love feedback on on some of the known questions or whatever else is on your mind!

The design is inspired by trybuild with thought given to how mdBook books could pull in content so you can verify a code sample, the command for running it, and the output. In considering how to keep clap's website up-to-date, I had this idea and threw it together to see how well it works. Overall, seems good with room for improvement. I'll have to give this a try on a real world program soon.