onlyargs_derive 0.1.0

Obsessively tiny argument parsing derive macro
Documentation

Derive macro for onlyargs.

The parser generated by this macro is very opinionated. The implementation attempts to be as light as possible while also being usable for most applications.

Only structs with named fields are supported. Doc comments are used for the generated help text. Argument names are generated automatically from field names with only a few rules:

  • Long argument names start with --, ASCII alphabetic characters are made lowercase, and all _ characters are replaced with -.
  • Short argument names use the first ASCII alphabetic character of the field name following a -. Short arguments are not allowed to be duplicated.
  • This behavior can be suppressed with the #[long] attribute (see below).
  • Alternatively, the #[short('…')] attribute can be used to set a specific short name.

Provided arguments

--help|-h and --version|-V arguments are automatically generated. When the parser encounters either, it will print the help or version message and exit the application with exit code 0.

Field attributes

Parsing options are configurable with the following attributes:

  • #[long]: Only generate long argument names like --help. Short args like -h are generated by default, and this attribute suppresses that behavior.
  • #[short('N')]: Generate a short argument name with the given character. In this example, it will be -N.
  • If #[long] and #[short] are used together, #[long] takes precedence.
  • #[default(T)]: Specify a default value for an argument. Where T is a literal value.

Supported types

Here is the list of supported field "primitive" types:

Type Description
bool Defines a flag.
f32|f64 Floating point number option.
i8|u8 8-bit integer option.
i16|u16 16-bit integer option.
i32|u32 32-bit integer option.
i64|u64 64-bit integer option.
i128|u128 128-bit integer option.
isize|usize Pointer-sized integer option.
OsString A string option with platform-specific encoding.
PathBuf A file system path option.
String UTF-8 encoded string option.

Additionally, some wrapper and composite types are also available, where the type T must be one of the primitive types listed above.

Type Description
Option<T> An optional argument.
Vec<T> Positional arguments (see below).

In argument parsing parlance, "flags" are simple boolean values; the argument does not require a value. For example, the argument --help.

"Options" carry a value and the argument parser requires the value to directly follow the argument name. Arguments can be made optional with Option<T>.

Positional arguments

If the struct contains a field with a vector type, it must be the only vector field. This becomes the "dumping ground" for all positional arguments, which are any args that do not match an existing field, or any arguments following the -- "stop parsing" sentinel.