Struct CommandLineDef

pub struct CommandLineDef { /* private fields */ }

Defines the valid commandline options and arguments for this program

Implementations

impl CommandLineDef

pub fn new() -> Self

Creates a new CommandLineDef

pub fn add_flag( &mut self, aliases: Vec<&'static str>, description: &'static str, ) -> &mut Self

A convenience function for adding flag options.

Arguments

• aliases - The aliases for this option. e.g. "-n","--negative"
• description - The description of this option. e.g. A negative number.

Panics

• Panics if the alias does not start with ‘-’ or ‘–’.
• Panics if the alias starts with ‘–’ and the length is less than 4
• Panics if the alias starts with ‘-’ and the length is not equal to 2

Examples

use cl_parse::CommandLineDef;
// Simulate env::args()
let env_args=vec![
  "program".to_string(),
  "-f".to_string(),
];
let cl = CommandLineDef::new()
  .add_flag(vec!["-f","--flag"], "A flag")
  .add_option(
    vec!["-b","--bool"],
    None,
    Some("true"),
    "An ignored bool default which will be false if not specified"
  )
  .parse(env_args.into_iter());

assert_eq!(cl.program_name(), "program");

let f:bool = cl.option("-f");
assert_eq!(f, true);

let flag:bool = cl.option("--flag");
assert_eq!(flag, true);

let b:bool = cl.option("-b");
assert_eq!(b, false);

let boolean:bool = cl.option("--bool");
assert_eq!(boolean, false);

pub fn add_option( &mut self, aliases: Vec<&'static str>, value_name: Option<&'static str>, default_value: Option<&'static str>, description: &'static str, ) -> &mut Self

Adds a new option definition to this commandline definition

Arguments

• aliases - The aliases for this option. e.g. "-n","--negative"
• value_name - The Option<&'static str> name for the value associated with the option. If set to None, this option will be treated as a flag, and its value will default to “false”.
• default_value - An Option<T> containing the value to use if one is not supplied. If None, then this option will be considered required and will panic if this option is not specified on the commandline. If value_name==None, default_value will be ignored.
• description - The description of this option. e.g. A negative number.

Panics

• Panics if the alias does not start with ‘-’ or ‘–’.
• Panics if the alias starts with ‘–’ and the length is less than 4
• Panics if the alias starts with ‘-’ and the length is not equal to 2
• Panics if an alias is defined more than once

Examples

use cl_parse::CommandLineDef;
let args=vec![
  "program".to_string(),
  "-n".to_string(), "-1".to_string(),
  "-p".to_string(), "1".to_string(),
];
let cl = CommandLineDef::new()
  .add_option(vec!["-n","--negative"], Some("neg"), None, "A negative value")
  .add_option(vec!["-p","--positive"], Some("pos"), None, "A positive value")
  .parse(args.into_iter());

assert_eq!(cl.program_name(), "program");

let n:i16 = cl.option("-n");
assert_eq!(n, -1);

let neg:i16 = cl.option("--negative");
assert_eq!(neg, n);

let p:i16 = cl.option("-p");
assert_eq!(p, 1);

let pos:i16 = cl.option("--positive");
assert_eq!(pos, p);

pub fn add_option_with_values( &mut self, aliases: Vec<&'static str>, value_name: Option<&'static str>, default_value: Option<&'static str>, description: &'static str, valid_values: Vec<&'static str>, ) -> &mut Self

Adds a new option definition to this commandline definition

Arguments

• aliases - The aliases for this option. e.g. "-n","--negative"
• value_name - The Option<&'static str> name for the value associated with the option. If set to None, this option will be treated as a flag, and its value will default to “false”.
• default_value - An Option<T> containing the value to use if one is not supplied. If None, then this option will be considered required and will panic if this option is not specified on the commandline. If value_name==None, default_value will be ignored.
• description - The description of this option. e.g. A negative number.
• valid_values - a vector of valid values to validate the option against

Panics

• Panics if the alias does not start with ‘-’ or ‘–’.
• Panics if the alias starts with ‘–’ and the length is less than 4
• Panics if the alias starts with ‘-’ and the length is not equal to 2
• Panics if an alias is defined more than once

Examples

use cl_parse::CommandLineDef;
let args=vec![
  "program".to_string(),
  "--level".to_string(), "low".to_string()
];
let cl = CommandLineDef::new()
  .add_option_with_values(vec!["--level"], Some("level"), Some("med"), "Operating Speed", vec!["low", "med", "high"])
  .parse(args.into_iter());

assert_eq!(cl.program_name(), "program");

let level:String = cl.option("--level");
assert_eq!(level, "low");

pub fn add_argument(&mut self, argument_name: &'static str) -> &mut Self

Add a new argument definition to the commandline definition

Arguments

• argument_name - The name of this argument. To be used in the usage message.

Examples

use cl_parse::CommandLineDef;
let args=vec![
  "program".to_string(),
  "arg1".to_string(),
  "--bool".to_string(),
  "arg2".to_string(),
  "-n".to_string(), "-1".to_string(),
  "arg3".to_string(),
];
let cl = CommandLineDef::new()
.add_option(vec!["-b","--bool"], None, Some("false"), "A boolean value")
.add_option(vec!["-n","--num"], Some("num"), None, "A numeric value")
.add_argument("arg-0")
.add_argument("arg-1")
.add_argument("arg-2")
.parse(args.into_iter());
assert_eq!(cl.program_name(), "program");

let b:bool = cl.option("-b");
assert_eq!(b, true);

let n:i16 = cl.option("-n");
assert_eq!(n, -1);

assert_eq!(cl.arguments(), 3);

let arg0:String = cl.argument(0);
assert_eq!(arg0, "arg1");

let arg1:String = cl.argument(1);
assert_eq!(arg1, "arg2");

let arg2:String = cl.argument(2);
assert_eq!(arg2, "arg3");

pub fn parse(&self, args: impl Iterator<Item = String>) -> CommandLine

Creates a new CommandLine from this CommandLineDef and the args

Arguments

• args - A string iterator that holds the commandline arguments to be parsed

• Panics if an option is specified and its value is missing

• Panics if an undefined option is present on the commandline

• Panics if a required option is not present on the commandline

• Panics if number of arguments is incorrect

Examples

 use std::collections::VecDeque;
 use std::env;
 // Simulate env::args()
 let env_args=vec![String::from("program"), String::from("-f"), String::from("/file/path")];
 use cl_parse::{CommandLine, CommandLineDef};
 let cl = CommandLineDef::new().add_option(vec!["-f","--filename"], Some("filepath"),
     None, "The file to be parsed").parse(env_args.into_iter());

  // Test Program Name
  assert_eq!(false, cl.program_name().is_empty());

Trait Implementations

impl Default for CommandLineDef

fn default() -> CommandLineDef

Returns the “default value” for a type.