Repository files navigation

Argh is an opinionated Derive-based argument parser optimized for code size

Derive-based argument parsing optimized for code size and conformanceto the Fuchsia commandline tools specification

The public API of this library consists primarily of theFromArgsderive and thefrom_env function, which can be used to producea top-levelFromArgs type from the current program's commandlinearguments.

use argh::FromArgs;#[derive(FromArgs)]/// Reach new heights.structGoUp{/// whether or not to jump#[argh(switch, short ='j')]jump:bool,/// how high to go#[argh(option)]height:usize,/// an optional nickname for the pilot#[argh(option)]pilot_nickname:Option<String>,}fnmain(){let up:GoUp = argh::from_env();}

./some_bin --help will then output the following:

Usage: cmdname [-j] --height <height> [--pilot-nickname <pilot-nickname>]Reach new heights.Options:  -j, --jump        whether or not to jump  --height          how high to go  --pilot-nickname  an optional nickname for the pilot  --help, help      display usage information

The resulting program can then be used in any of these ways:

• ./some_bin --height 5
• ./some_bin -j --height 5
• ./some_bin --jump --height 5 --pilot-nickname Wes

Switches, likejump, are optional and will be set to true if provided.

Options, likeheight andpilot_nickname, can be either required,optional, or repeating, depending on whether they are contained in anOption or aVec. Default values can be provided using the#[argh(default = "<your_code_here>")] attribute, and in this case anoption is treated as optional.

use argh::FromArgs;fndefault_height() ->usize{5}#[derive(FromArgs)]/// Reach new heights.structGoUp{/// an optional nickname for the pilot#[argh(option)]pilot_nickname:Option<String>,/// an optional height#[argh(option,default ="default_height()")]height:usize,/// an optional direction which is "up" by default#[argh(option,default ="String::from(\"only up\")")]direction:String,}fnmain(){let up:GoUp = argh::from_env();}

Custom option types can be deserialized so long as they implement theFromArgValue trait (automatically implemented for allFromStr types).If more customized parsing is required, you can supply a customfn(&str) -> Result<T, String> using thefrom_str_fn attribute:

use argh::FromArgs;#[derive(FromArgs)]/// Goofy thing.structFiveStruct{/// always five#[argh(option, from_str_fn(always_five))]five:usize,}fnalways_five(_value:&str) ->Result<usize,String>{Ok(5)}

Positional arguments can be declared using#[argh(positional)].These arguments will be parsed in order of their declaration inthe structure:

use argh::FromArgs;#[derive(FromArgs,PartialEq,Debug)]/// A command with positional arguments.structWithPositional{#[argh(positional)]first:String,}

The last positional argument may include a default, or be wrapped inOption orVec to indicate an optional or repeating positional argument.

Subcommands are also supported. To use a subcommand, declare a separateFromArgs type for each subcommand as well as an enum that casesover each command:

use argh::FromArgs;#[derive(FromArgs,PartialEq,Debug)]/// Top-level command.structTopLevel{#[argh(subcommand)]nested:MySubCommandEnum,}#[derive(FromArgs,PartialEq,Debug)]#[argh(subcommand)]enumMySubCommandEnum{One(SubCommandOne),Two(SubCommandTwo),}#[derive(FromArgs,PartialEq,Debug)]/// First subcommand.#[argh(subcommand, name ="one")]structSubCommandOne{#[argh(option)]/// how many xx:usize,}#[derive(FromArgs,PartialEq,Debug)]/// Second subcommand.#[argh(subcommand, name ="two")]structSubCommandTwo{#[argh(switch)]/// whether to fooeyfooey:bool,}

NOTE: This is not an officially supported Google product.

Theargh::FromArgs derive macro can be debugged with thecargo-expand crate.

Seeargh/examples/simple_example.rs for the example struct we wish to expand.

First, installcargo-expand by runningcargo install cargo-expand. Note this requires the nightly build of Rust.

Once installed, runcargo expand with in theargh package and you can see the expanded code.