Announcing ClapMe

Hi all,

I'd like to announce the 0.1.3 release of clapme. The big new feature of this release is a guide to clapme.

ClapMe is a non-customizable, typesafe, easy-to-use, and DRY way to specify the command-line flags for your executable. You just create a type (typically a struct), derive the ClapMe trait, and then call a method on that type to parse your flags, which returns an object of the desired type. Internally, ClapMe uses clap, which gives great error messages and other neat features (thus the name of the ClapMe trait).

4 Likes

Just thought I'd send out announcement that clapme version 0.1.11 just went out. Clapme is a crate that derives a set of command-line arguments from the definition of a type (typically a struct).

There haven't been any drastic changes, but I've fixed a number of bugs that showed up when you had weird combinations of enums nested in structs nested in enums. Most recently, I changed clapme to allow scientific notation for integers, which makes a huge usability difference when specifying the number of iterations desired in a Monte Carlo simulation.

2 Likes

How does clapme compare to structopt?

That's answered in the README.

The main difference is that clapme doesn't require (or support) any attributes to be defined, but instead attempts to interpret any struct or enum you give it in a reasonable way. This makes the definition considerably less verbose, but also gives you less flexibility.

Relating to this, currently clapme has no way to specify subcommands. Structopt interprets enums as representing subcommands, but that means that is doesn't allow you to have more than one enum at a given level of hierarchy. I've thought about teaching clapme to recognize pattern involving a single enum as meaning a subcommand, but haven't (yet?) bothered to figure out a good heuristic that would indicate when a subcommand might be always an improvement.

Incidentally, I've now released version 0.1.13, which additionally supports arithmetic in numerical values, so you can specify --T '5*sqrt(2)', which is considerably nicer than having to copy a whole lot of digits. Thanks to meval for making that easy!

For a language so focused on "safety" in all aspects, we sure have a lot of ways to get the clap! :drum: :musical_note:
/off-topic

I want to note that ClapMe almost always produces long flags. This is because I feel that long flags are generally the easiest to use.

I really like this idea, just do one sensible default, without too much woods to get lost in; after all, the programmer has bigger things to worry about than the best short-form of his command-line option.
When doing my own scripting, I also usually go for the long-form, as they are far more self-documenting. I am always annoyed when I open something from a colleague, and I first spend two minutes deciphering "sometool -aGrTnFf input-file'
Future-me thanks you for reducing the possibilities for crypticness!

Comparing this wider: I find it interesting to see the many different trade-offs the community is experimenting with: One the one end of the spectrum: low-level and custom attributes to define every niggly little detail, help text and handling-logic, and on the other end high-level "does-what-you-mean" like ClapMe here.
I'm curious how that spectrum will end up being used in practice!

We add help information simply by adding ordinary doc comments to our struct.

Great usability!

In most of this documentation I'll avoid adding help text, just to keep the page short, but I would always add it for actual projects!

Since your guide is the primary example of best-practices (and probably copy-paste coding too :stuck_out_tongue_winking_eye: ), I'd advise differently; include at least a minimum one-liner in all cases to set the proper precedent!

Flattened nesting types

This idea is just inspired :slight_smile:
I really like that this creates the option to keep different concerns (e.g. log levels vs. algorithm parameters) separated at the code-level, while still presenting a unified interface. :+1:

3 Likes

Good advice. I've edited the guide to have help information for all the flags. Note that the docs.rs guide is not yet updated, as I didn't think this change worth a version bump and cargo publish.

And while doing so I was reminded that I never posted up the fun trick I came up with to include library output in the guide: The guide is written as a test program that reads itself and writes a copy with the help information inserted in appropriate locations. The output is a git-managed file, which enables it to be handled by docs.rs.

It's more than a little hokey, but really makes it easier to ensure that the crate is in sync.

Indeed, this is one of the huge benefits for the project for which I wrote clapme, which is a research Monte Carlo simulation code that isn't yet public. It's so nice to have this separation of concerns, and I'm optimistic that undergrad physicists will be able to pick up how to use clapme pretty easily.

1 Like

We rustaceans value good documentation more than anyone.
Better docs are definitely worth a (minor) bump in my humble opinion! Don't be afraid to show your work! :smile:
(Also, I believe there's a population that uses docs.rs as their only stop for documentation..)

Ooh! Recursive programs! One of the hallmarks of genius at work! :smile:

Great niche to target! I'm a bioinformatician myself, and when I see how many of my colleagues have great scientific ideas, but little programming background... Crates like these definitely help raise the quality of work they can produce!