scurvy - rust crate for cli arg parsing. key=value style

scurvy

rust crate for parsing command line arguments using a key=value style. scurvy tries to be nice to use.

Using scurvy

to declare your arguments, so you can give them to scurvy, make a Vec<Argument> first of all.

let args = vec![
    Argument::new(&["input", "in"]).arg("path"),
    Argument::new(&["output", "out"]).arg("path"),
    Argument::new("flag-foo"),
];

The above code declares three options you can pass. When you write something like Argument::new("flag-foo") you are declaring that there is an argument flag-foo. If you pass multiple values in an array, like in Argument::new(&["input", "in"]) you are grouping these arguments for scurvy. You can use either of those names when you attempt to retrieve data.

Those first two lines, for in and out, tell scurvy that there might be an associated value with the arguments.

Now, how do you actually start parsin'?

let scurvy = Scurvy::make(args);

if scurvy.should_print_help() {
    println!("{HELP_STR}");
    return;
}

Just pass the Vec<Argument> in Scurvy::make! That if statement afterwards demonstrates that scurvy will automatically look for some arguments for you. These are -h, --help, and help= for determining if you should print a help message, and -V, --version, version= for determining if you should print version information.

You'll notice that scurvy looks for the getopts style flags for help and version. It does that because, while the author wanted to play with a CLI-thing a la. dd, she did not want to violate helpful standards like -h and --version.

Scurvy does not currently generate a help/usage string for you.

Anyway, how do you actually get data from the CLI?

let input = scurvy.parse_req("in", PathFormula::new());
let output = scurvy.parse_req("out", PathFormula::new());
let flag_foo = scurvy.has("flag-foo");

Those three lines demonstrate the core of scurvy's interface for grabbing argument values.

Let's start easy: has(key: &str) -> bool
looks to see if a flag was set on the command line, and returns you a boolean indicating such.

Not shown, but important: get(key: &str) -> Option<&str>
returns the value belonging to an argument, if it exists.

And, related: get_req(key: &str) -> &str
will return an argument, or die trying. If the argument was not set, scurvy will print (to stderr), that the option is required and then exit.

Before we look at the parse methods, we need to talk about Formula. Not in depth, but enough to understand it.

A Formula is a wrapper around FromStr, essentially, with a few niceties surrounding. It allows you to provide custom strings for failure, when parsing fails, or missing, for when a required argument is missing. Additionally, you can provide a function that validates a value after parsing.

That's the surface level. The parse methods expect to receive a value that conforms to Into<Formula> for the type you are trying to parse into. So if you are parsing a u8, it would look like Into<Formula<u8>>. But that's terrible to write, isn't it? There is a set of provided formula including, not not limited to:
- All integer types U8Formula, I16Formula, etc. etc.
- PathFormula (parses into PathBuf)
- BooleanFormula

Typically, you use formula by just instantiating their zero-size struct. Like this: PathFormula::new or U32Formula::new

So, let's look at parse_req.

let input = scurvy.parse_req("in", PathFormula::new());

input has a type of PathBuf, since PathFormula parses into that type, and it is a required argument. If in is not present, or it's argument fails to parse as a PathBuf, scurvy will print an error and terminate execution.

Features

camino
enable this feature to get the struct Utf8PathFormula which gives you a formula for parsing into Utf8PathBuf.
(camino versioned at 1.2.4)

confindent
enable this feature to get the following methods:
- Scurvy::with_confindent(self, Confindent)
- Scurvy::with_configuration_key(self, key: &str, default: Path)
(confindent versioned at 2.2.1)

These methods allow you to create a ConfigurationPair, which allows you to easily get values from both scurvy and confindent with the priority being on values from scurvy.

with_configuration_key will look for the provided key, parse it's value as a PathBuf, and try to open a configuration file at that path. If the argument is absent, it tries a default. You might use this with the conf key, so your cli would look like this:
example conf=example.conf

ConfigurationPair
This struct implements has, get, get_req, parse, parse_req. You always pass in a value, or a pair. If you pass in just one value, has("key"), it will look for key in scurvy and Key in confindent. If you pass two, has(["key", "ConfKey"]), it will look for key in scurvy and ConfKey in confindent.