Crate onlyargs_derive

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.

Example

use onlyargs_derive::OnlyArgs;

/// Doc comments will appear in your application's help text.
///
/// Features:
///   - Supports multi-line strings.
///   - Supports indentation.
#[derive(Debug, OnlyArgs)]
#[footer = "Footer attributes will be included at the bottom of the help message."]
#[footer = ""]
#[footer = "Features:"]
#[footer = "  - Also supports multi-line strings."]
#[footer = "  - Also supports indentation."]
struct Args {
    /// Optional output path.
    output: Option<std::path::PathBuf>,

    /// Enable verbose output.
    verbose: bool,
}

let args: Args = onlyargs::parse()?;

if let Some(output) = args.output {
    if args.verbose {
        eprintln!("Creating file: `{path}`", path = output.display());
    }

    // Do something with `output`...
}

DSL reference

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.

Footer

The #[footer = "..."] attribute on the argument struct will add lines to the bottom of the help message. It can be used multiple times.

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.
  • Accepts string literals for PathBuf.
  • Accepts numeric literals for numeric types.
  • Accepts true and false idents and "true" and "false" string literals for boolean.
• #[required]: Can be used on Vec<T> to require at least one value. This ensures the vector is never empty.
• #[positional]: Makes a Vec<T> the dumping ground for positional arguments.

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 (except bool).

Type	Description
Option<T>	An optional argument.
Vec<T>	Multivalue and positional arguments (see #[positional]).

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>.

Multivalue arguments can be passed on the command line by using the same argument multiple times.

Derive Macros

• OnlyArgs
  See the root module documentation for the DSL specification.