Crate larpa 

The Lousy Argument Parser.

Larpa is intended to be a simple #[derive]-based CLI option parser, in a similar vein to clap and argh.

Larpa aims for the following goals:

• Stay relatively lightweight in terms of binary size impact, while still providing the bells and whistles users expect.
• Provide a vastly simpler and easier to understand interface than Clap.

Larpa is still in development and is missing many features. Feel free to contribute!

Current Features

• Automatic generation of styled usage strings, --help and --version output.
• Introspectable command description (CommandDesc).
• Decent IDE support (completion and hover docs for attributes).
• About ~100 KB of binary size overhead (compared to ~500 KB for clap and ~30 KB for argh).

Usage

The main entry point into the library is the Command trait.

• Command::from_args parses env::args_os and exits the process when parsing fails.
• Command::try_from_args parses env::args_os and returns an Error on failure.
• Command::from_iter and Command::try_from_iter work the same way, except they accept a user-provided iterator to parse arguments from.

The Command trait cannot be implemented by hand. The only way to create an implementation is by using #[derive(Command)].

The derive macro accepts several #[larpa] attributes, which are separately documented in attrs. It is strongly recommended to read the documentation in that module for detailed information about the attributes.

Examples

Arguments

A simple CLI that accepts a few standard flags and a path to a configuration file.

It demonstrates named and positional arguments, required and optional arguments, arguments with custom default values, as well as Flags and inverted flags.

use larpa::Command;
use larpa::types::{Verbosity, PrintHelp, PrintVersion};
use std::path::PathBuf;
use std::num::NonZeroU8;

/// Data frobnication tool.
#[derive(Command)]
#[larpa(name = "frobnicator", version = "1.2.3")]
struct Args {
    /// Print version information.
    #[larpa(flag, name = "--version")]
    version: PrintVersion,

    /// Output more information.
    #[larpa(flag, name = ["-v", "--verbose"])]
    verbosity: Verbosity,

    /// Output less information.
    #[larpa(flag, name = ["-q", "--quiet"], inverse_of = "verbosity")]
    quiet: (),

    /// How many times to frobnicate the data (at least 1).
    #[larpa(name = "-n", default = "5")]
    iterations: NonZeroU8,

    /// Path to the configuration file.
    #[larpa(name = "--config")]
    config: Option<PathBuf>,

    /// The object to frobnicate (mandatory).
    object: String,
}

$ frobnicator --help
Data frobnication tool.

frobnicator [-vq] [--version] [--verbose] [--quiet] [--help] [-n <ITERATIONS>]
            [--config=<CONFIG>] <OBJECT>

ARGUMENTS:
  OBJECT  The object to frobnicate (mandatory).

OPTIONS:
      --version        Print version information.
  -v, --verbose        Output more information.
  -q, --quiet          Output less information.
  -n ITERATIONS        How many times to frobnicate the data (at least 1). [default: 5]
      --config=CONFIG  Path to the configuration file.
      --help           Print help information.

$ frobnicator --version
frobnicator 1.2.3

An error will be returned when the mandatory OBJECT argument is missing:

$ frobnicator
error: missing argument `OBJECT`

usage: frobnicator [-vq] [--version] [--verbose] [--quiet] [--help] [-n <ITERATIONS>]
                   [--config=<CONFIG>] <OBJECT>

Similarly, an error will be returned if a value cannot be parsed into the target type:

$ frobnicator -n 0
error: invalid value for argument `-n`: number would be zero for non-zero type

usage: frobnicator [-vq] [--version] [--verbose] [--quiet] [--help] [-n <ITERATIONS>]
                   [--config=<CONFIG>] <OBJECT>

Subcommands

Subcommands can be created by using #[derive(Command)] on an enum.

#[larpa(fallback)] and #[larpa(discover)] can be used on a variant to implement external subcommands.

An enum of subcommands can be embedded in a struct by marking a field with #[larpa(subcommand)].

use larpa::Command;
use larpa::types::PrintVersion;
use std::ffi::OsString;
use std::path::PathBuf;

#[derive(Command)]
enum Subcommand {
    // Variants can have fields that work just like they do in a `struct`.

    /// Push changes.
    Push {
        /// Force-overwrite the remote ref.
        #[larpa(flag, name = ["-f", "--force"])]
        force: bool,
    },

    // Alternatively, a tuple variant will use the inner type's `Command` implementation.

    /// Pull changes.
    Pull(PullArgs),

    // A variant without data is just a plain subcommand.

    /// Show file status.
    Status,

    // A catch-all variant can be created with `#[larpa(fallback)]`, to catch any subcommands
    // that don't match any of the other variants.

    #[larpa(fallback)]
    Other(Vec<OsString>),
}

#[derive(Command)]
struct PullArgs {
    #[larpa(flag, name = "--autostash")]
    autostash: bool,
}

/// The gritty content tracker.
#[derive(Command)]
#[larpa(name = "grit", version = "1.0.0")]
struct Grit {
    /// Path to the configuration file.
    #[larpa(name = ["-c", "--config"])]
    config: Option<PathBuf>,

    /// Print version information.
    #[larpa(name = "--version", flag)]
    version: PrintVersion,

    #[larpa(subcommand)]
    subcommand: Subcommand,
}

$ grit --help
The gritty content tracker.

grit [--version] [--help] [-c/--config <CONFIG>] push|pull|status|...

OPTIONS:
  -c, --config=CONFIG  Path to the configuration file.
      --version        Print version information.
      --help           Print help information.

SUBCOMMANDS:
  push    Push changes.
  pull    Pull changes.
  status  Show file status.

$ grit push --help
Push changes.

grit push [-f] [--force] [--help]

OPTIONS:
  -f, --force  Force-overwrite the remote ref.
      --help   Print help information.

$ grit pull --help
Pull changes.

grit pull [--autostash] [--help]

OPTIONS:
      --autostash
      --help       Print help information.

Modules

attrsdocsrs

Documentation for attributes accepted by Larpa (only available on docs.rs).

desc

Introspectable command description.

types

Built-in argument value types.

Structs

Context

A parsing context.

Error

Indicates that a Command could not be parsed.

Reporter

Writes an Error to a destination.

Usage

A usage string generator.

Traits

Command

A CLI command.

Flag

Types that track the presence of a command-line flag without argument.

Derive Macros

Command

A #[derive] macro for larpa’s Command trait.