Crate cargho[−][src]
Expand description
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.
Basic Example
use cargho::FromArgs; #[derive(FromArgs)] /// Reach new heights. struct GoUp { /// whether or not to jump #[cargho(switch, short = 'j')] jump: bool, /// how high to go #[cargho(option)] height: usize, /// an optional nickname for the pilot #[cargho(option)] pilot_nickname: Option<String>, } fn main() { let up: GoUp = cargho::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
#[cargho(default = "<your_code_here>")]
attribute, and in this case an
option is treated as optional.
use cargho::FromArgs; fn default_height() -> usize { 5 } #[derive(FromArgs)] /// Reach new heights. struct GoUp { /// an optional nickname for the pilot #[cargho(option)] pilot_nickname: Option<String>, /// an optional height #[cargho(option, default = "default_height()")] height: usize, /// an optional direction which is "up" by default #[cargho(option, default = "String::from(\"only up\")")] direction: String, } fn main() { let up: GoUp = cargho::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:
#[derive(FromArgs)] /// Goofy thing. struct FiveStruct { /// always five #[cargho(option, from_str_fn(always_five))] five: usize, } fn always_five(_value: &str) -> Result<usize, String> { Ok(5) }
Positional arguments can be declared using #[cargho(positional)]
.
These arguments will be parsed in order of their declaration in
the structure:
use cargho::FromArgs; #[derive(FromArgs, PartialEq, Debug)] /// A command with positional arguments. struct WithPositional { #[cargho(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:
#[derive(FromArgs, PartialEq, Debug)] /// Top-level command. struct TopLevel { #[cargho(subcommand)] nested: MySubCommandEnum, } #[derive(FromArgs, PartialEq, Debug)] #[cargho(subcommand)] enum MySubCommandEnum { One(SubCommandOne), Two(SubCommandTwo), } #[derive(FromArgs, PartialEq, Debug)] /// First subcommand. #[cargho(subcommand, name = "one")] struct SubCommandOne { #[cargho(option)] /// how many x x: usize, } #[derive(FromArgs, PartialEq, Debug)] /// Second subcommand. #[cargho(subcommand, name = "two")] struct SubCommandTwo { #[cargho(switch)] /// whether to fooey fooey: bool, }
Structs
Information to display to the user about why a FromArgs
construction exited early.
Traits
A type which can be the receiver of a Flag
.
Types which can be constructed from a single commandline value.
Types which can be constructed from a set of commandline arguments.
A FromArgs
implementation that represents a single subcommand.
A FromArgs
implementation that can parse into one or more subcommands.
A top-level FromArgs
implementation that is not a subcommand.
Functions
Create a FromArgs
type from the current process’s env::args
.
Create a FromArgs
type from the current process’s env::args
.
Type Definitions
Information about a particular command used for output.
Derive Macros
Entrypoint for #[derive(FromArgs)]
.