Struct dia_args::Args

pub struct Args { /* private fields */ }

Arguments

Notes

• sub_args() are not verified. They are the ones after -- phrase, which (often) are meant for being passed to sub processes.

Implementations

impl Args

pub fn cmd(&self) -> Option<&str>

Gets the command

This is simply the first one of args().

pub fn args(&self) -> Option<Vec<&str>>

Gets arguments

If it’s some vector, the vector is not empty.

The first one can be used as a command, via cmd().

pub fn options(&self) -> &HashMap<String, Vec<String>>

Gets raw options

Normally you don’t need this. Instead, you can use get(), get_vec()…

pub fn sub_args(&self) -> Option<Vec<&str>>

Sub arguments

If it’s some vector, the vector is not empty.

pub fn is_empty(&self) -> bool

Checks if there are no arguments/options/sub arguments

pub fn use_stdin(&self) -> bool

Gets flag for using stdin

pub fn into_sub_cmd(self) -> (Option<String>, Self)

Transforms into sub command

For example:

• Command line:

  ~> program help version 1

• Parsed as:

  help version 1

• After calling this function:

  version 1

use dia_args;

const CMD_VERSION: &str = "version";

let (cmd, args) = dia_args::parse()?.into_sub_cmd();
match cmd.as_ref().map(|s| s.as_str()) {
    Some(CMD_VERSION) => if args.is_empty() {
        println!("Version: ...");
    } else {
        eprintln!("{:?} command doesn't take arguments", CMD_VERSION);
    },
    Some(other) => eprintln!("Command {:?} not supported", other),
    None => eprintln!("Missing command"),
};

pub fn get<T>(&self, keys: &[&str]) -> Result<Option<T>> where
    T: FromStr,
    <T as FromStr>::Err: Debug, 

Gets a value

You can provide multiple keys as you want. But the user can only provide one single key of them. This function can be used for short version and long version of your keys.

Examples

use dia_args;

let args = dia_args::parse_strings(["--type", "ogg"].iter())?;
assert_eq!(args.get::<String>(&["-t", "--type"])?.unwrap(), "ogg");

let args = dia_args::parse_strings(["--type", "ogg"].iter())?;
assert!(args.get::<String>(&["-t"])?.is_none());

let args = dia_args::parse_strings(["--type", "ogg", "-t", "some"].iter())?;
args.get::<String>(&["-t", "--type"]).unwrap_err();

pub fn take<T>(&mut self, keys: &[&str]) -> Result<Option<T>> where
    T: FromStr,
    <T as FromStr>::Err: Debug, 

Calls get() and removes the keys if the result is Ok(Some)

Examples

use dia_args;

let mut args = dia_args::parse_strings(["--type", "rs"].iter())?;
assert_eq!(args.take::<String>(&["--type"])?.unwrap(), "rs");
assert!(args.get::<String>(&["--type"])?.is_none());

pub fn get_vec<T>(&self, keys: &[&str]) -> Result<Option<Vec<T>>> where
    T: FromStr,
    <T as FromStr>::Err: Debug, 

Gets a vector of values

Examples

use dia_args;

let args = dia_args::parse_strings(
    ["--type", "ogg", "-t", "m4v", "--type", "md", "-t", "rs"].iter()
)?;
let mut types = args.get_vec::<String>(&["-t", "--type"])?.unwrap();
types.sort();
assert_eq!(types, &["m4v", "md", "ogg", "rs"]);

pub fn take_vec<T>(&mut self, keys: &[&str]) -> Result<Option<Vec<T>>> where
    T: FromStr,
    <T as FromStr>::Err: Debug, 

Calls get_vec() and removes the keys if the result is Ok(Some)

Examples

use dia_args;

let mut args = dia_args::parse_strings(["-l", "c", "-l", "c++"].iter())?;
let mut languages = args.take_vec::<String>(&["-l"])?.unwrap();
languages.sort();
assert_eq!(languages, &["c", "c++"]);
assert!(args.is_empty());

pub fn take_args(&mut self) -> Option<Vec<String>>

Takes arguments out

Examples

use dia_args;

let mut args = dia_args::parse_strings(["do", "this", "--faster=true"].iter())?;
assert_eq!(args.take_args().unwrap(), &["do", "this"]);

pub fn take_sub_args(&mut self) -> Option<Vec<String>>

Takes sub arguments out

Examples

use dia_args;

let mut args = dia_args::parse_strings(
    ["eat", "chicken", "--", "with", "ronnie-coleman"].iter()
)?;
assert_eq!(args.take_sub_args().unwrap(), &["with", "ronnie-coleman"]);

pub fn merge_options(
    &mut self,
    other: &mut Self,
    filter: &[&[&str]],
    merge_option: MergeOption
) -> Result<usize>

Merges options with other

• This function works on options, not commands/stdin flag/sub arguments…
• Other’s options will be taken out, if conditions are met.
• Result is number of items merged.

Parameters

• filter:

  • If you provide some sets of keys, only those (from other) are accepted.
  • If you provide an empty slice, or any of its items is empty, an error is returned.

Examples

Your program allows the user to set options from file. Later you want to give the user new ability to set options via command line, overwriting the ones from file. Then this function can help.

use dia_args::MergeOption;

const OPTION_DEBUG: &[&str] = &["-d", "--debug"];
const OPTION_PORT: &[&str] = &["--port"];

// Here in test, we're parsing from strings.
// In real code, you might want to use dia_args::parse_file()
let mut args_from_file = dia_args::parse_strings(
    ["--debug=false", "--port=6789"].iter()
)?;

// Command line arguments
let mut cmd_line_args = dia_args::parse_strings(
    ["-d=true", "--address", "localhost"].iter()
)?;

// Merge
let count = cmd_line_args.merge_options(
    &mut args_from_file, &[OPTION_DEBUG, OPTION_PORT], MergeOption::IgnoreExisting,
)?;
assert_eq!(count, 1);

// Verify
assert_eq!(cmd_line_args.get(OPTION_DEBUG)?, Some(true));
assert_eq!(cmd_line_args.get::<String>(&["--address"])?.unwrap(), "localhost");
assert_eq!(cmd_line_args.get::<u16>(OPTION_PORT)?, Some(6789));

Trait Implementations

impl AsRef<Args> for Args

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Args

fn clone(&self) -> Args

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Args

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Args

fn default() -> Args

Returns the “default value” for a type.