commit | d14ce7ae4d7c8748dc4046100bc38ecb724fe9a2 | [log] [tgz] |
---|---|---|
author | Bob Badour <bbadour@google.com> | Thu Jan 27 23:09:01 2022 +0000 |
committer | Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com> | Thu Jan 27 23:09:01 2022 +0000 |
tree | 19cb5d61a64c0f1aeb6ad2a0cbd1f79ba23acd03 | |
parent | f7ca4eb7b79f0161e0e6050286c5832234f0ce3c [diff] | |
parent | 365247a18dfd441a87dbbf29acd532456afcf292 [diff] |
[LSC] Add LOCAL_LICENSE_KINDS to external/rust/crates/argh_shared am: d8f2c9e913 am: f291252ee2 am: 365247a18d Original change: https://android-review.googlesource.com/c/platform/external/rust/crates/argh_shared/+/1963840 Change-Id: Ib8147d8ad201bcd9abec5d25e03df85d4370b73a
Argh is an opinionated Derive-based argument parser optimized for code size
Derive-based argument parsing optimized for code size and conformance to the Fuchsia commandline tools specification
The public API of this library consists primarily of the FromArgs
derive and the from_env
function, which can be used to produce a top-level FromArgs
type from the current program's commandline arguments.
use argh::FromArgs; #[derive(FromArgs)] /// Reach new heights. struct GoUp { /// 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>, } fn main() { 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 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, like jump
, are optional and will be set to true if provided.
Options, like height
and pilot_nickname
, can be either required, optional, or repeating, depending on whether they are contained in an Option
or a Vec
. Default values can be provided using the #[argh(default = "<your_code_here>")]
attribute, and in this case an option is treated as optional.
use argh::FromArgs; fn default_height() -> usize { 5 } #[derive(FromArgs)] /// Reach new heights. struct GoUp { /// 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, } fn main() { let up: GoUp = argh::from_env(); }
Custom option types can be deserialized so long as they implement the FromArgValue
trait (automatically implemented for all FromStr
types). If more customized parsing is required, you can supply a custom fn(&str) -> Result<T, String>
using the from_str_fn
attribute:
use argh::FromArgs; #[derive(FromArgs)] /// Goofy thing. struct FiveStruct { /// always five #[argh(option, from_str_fn(always_five))] five: usize, } fn always_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 in the structure:
use argh::FromArgs; #[derive(FromArgs, PartialEq, Debug)] /// A command with positional arguments. struct WithPositional { #[argh(positional)] first: String, }
The last positional argument may include a default, or be wrapped in Option
or Vec
to indicate an optional or repeating positional argument.
Subcommands are also supported. To use a subcommand, declare a separate FromArgs
type for each subcommand as well as an enum that cases over each command:
use argh::FromArgs; #[derive(FromArgs, PartialEq, Debug)] /// Top-level command. struct TopLevel { #[argh(subcommand)] nested: MySubCommandEnum, } #[derive(FromArgs, PartialEq, Debug)] #[argh(subcommand)] enum MySubCommandEnum { One(SubCommandOne), Two(SubCommandTwo), } #[derive(FromArgs, PartialEq, Debug)] /// First subcommand. #[argh(subcommand, name = "one")] struct SubCommandOne { #[argh(option)] /// how many x x: usize, } #[derive(FromArgs, PartialEq, Debug)] /// Second subcommand. #[argh(subcommand, name = "two")] struct SubCommandTwo { #[argh(switch)] /// whether to fooey fooey: bool, }
NOTE: This is not an officially supported Google product.