tag | 51f66f31aba30993b28830bb632dcf961ab27336 | |
---|---|---|
tagger | The Android Open Source Project <initial-contribution@android.com> | Tue May 07 10:55:53 2024 -0700 |
object | bb2c777e962a18bb25a415ddf1dad99bbdfbfcfe |
Android 14.0.0 release 34
commit | bb2c777e962a18bb25a415ddf1dad99bbdfbfcfe | [log] [tgz] |
---|---|---|
author | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | Sat Oct 21 03:13:35 2023 +0000 |
committer | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | Sat Oct 21 03:13:35 2023 +0000 |
tree | 7172743335c922d6d663300ad9c3f818cbee246a | |
parent | 68bfe25021cb35b1059e7df7b16bd13f60a79f98 [diff] | |
parent | 24a1e567d57b886f024eeda9a020a11cce143c2f [diff] |
Snap for 10985023 from 24a1e567d57b886f024eeda9a020a11cce143c2f to 24Q1-release Change-Id: I4b4607c1acee4bb7cf7225389ad640c95aabeb26
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.
argh
The argh::FromArgs
derive macro can be debugged with the cargo-expand crate.
examples/simple_example.rs
See argh/examples/simple_example.rs for the example struct we wish to expand.
First, install cargo-expand
by running cargo install cargo-expand
. Note this requires the nightly build of Rust.
Once installed, run cargo expand
with in the argh
package and you can see the expanded code.