Struct commandlines::Command
source · pub struct Command {
pub argv: Vec<String>,
pub argc: usize,
pub executable: String,
pub options: Vec<String>,
pub definitions: HashMap<String, String>,
pub first_arg: Option<String>,
pub last_arg: Option<String>,
pub double_dash_argv: Option<Vec<String>>,
}
Expand description
A command line argument object
The Command
struct defines fields that hold parsed command line argument data and provides methods that can be used to define the logic of a command line interface application.
Examples
Instantiation
extern crate commandlines;
use commandlines::Command;
def main() {
let c = Command::new();
}
Debugging
The Command
struct supports pretty-printed display of all parsed data fields to the standard output stream with the {:#?}
formatting idiom:
use commandlines::Command;
println!("{:#?}", Command::new());
Remarks
The Vector of command line arguments presented to the executable in std::env::args().collect()
is used to define the Command
struct fields.
See the documentation for the Command
struct methods and fields to learn how to use the parsed data in your command line interface application logic.
Fields§
§argv: Vec<String>
Vector of ordered command line arguments
argc: usize
number of strings in Command.argv
executable: String
The executable path at index position 0
of Command.argv
options: Vec<String>
Vector of command line options in Command.argv
definitions: HashMap<String, String>
HashMap of command line option definitions mapped as key=option:value=definition
first_arg: Option<String>
Option<String>
of first positional argument to the executable. None
if there are no arguments to the executable.
last_arg: Option<String>
Option<String>
of last positional argument to the executable. None
if there are no arguments to the executable.
double_dash_argv: Option<Vec<String>>
Option<Vec<String>>
of ordered arguments that follow a double dash command line idiom. None
if a double dash argument is not present or there are no arguments after the double dash argument.
Implementations§
source§impl Command
impl Command
sourcepub fn new() -> Self
pub fn new() -> Self
Instantiates and returns a new Command
struct with the command line argument data in std::env::args().collect()
Remarks
Instantiate a Command
struct in the main()
method of the main.rs
file of your Rust executable project.
Examples
extern crate commandlines;
use commandlines::Command;
def main() {
let c = Command::new();
}
sourcepub fn has_args(&self) -> bool
pub fn has_args(&self) -> bool
Returns a boolean for the question “Does the command include any arguments to the executable?”
Remarks
This method defines an argument as a command line string that occurs after the executable path string located at index position 0
of Command.argv
. Please note that the executable path at index position 0
in the Vec<String>
returned by std::env::args().collect()
will always be present and is intentionally not part of this definition.
Examples
let c = commandlines::Command::new();
if !c.has_args() {
eprintln!("Missing arguments");
}
sourcepub fn has_definitions(&self) -> bool
pub fn has_definitions(&self) -> bool
Returns a boolean for the question “Does the command include any definition options?”
Remarks
A definition option is defined as a command line string that takes a short or long option format with an equal symbol character that is used to indicate that an option definition string follows. This library supports the following formats:
--option=def
-o=def
The long format with two hyphens is specified in the GNU command line argument conventions. The short format with a single hyphen is not specified in the POSIX or GNU guidelines.
Examples
let c = commandlines::Command::new();
if c.has_definitions() {
// definitions were parsed in the command
}
sourcepub fn has_options(&self) -> bool
pub fn has_options(&self) -> bool
Returns a boolean for the question “Does the command include any options?”
Remarks
An option is defined as a command line argument that starts with one or two hyphen characters. This definition includes standard long (e.g., --longoption
) and short (e.g., -s
) command line options.
Examples
let c = commandlines::Command::new();
if c.has_options() {
// start application-specific option parsing logic
}
sourcepub fn contains_arg(&self, needle: &str) -> bool
pub fn contains_arg(&self, needle: &str) -> bool
Returns a boolean for the question “Does the command include the argument string needle
?” at any index
Examples
let c = commandlines::Command::new();
if c.contains_arg("spam") {
// a `spam` argument was in the command
}
sourcepub fn contains_definition(&self, needle: &str) -> bool
pub fn contains_definition(&self, needle: &str) -> bool
Returns a boolean for the question “Does the command include the definition option needle
?”
Examples
let c = commandlines::Command::new();
if c.contains_definition("--spam") {
// command included a `--spam=[definition]` option
}
sourcepub fn contains_option(&self, needle: &str) -> bool
pub fn contains_option(&self, needle: &str) -> bool
Returns a boolean for the question “Does the command include the option string needle
?” at any index
Examples
let c = commandlines::Command::new();
if c.contains_option("--help") {
// you have a standard request for help documentation
}
sourcepub fn contains_all_options(&self, needle_vec: Vec<&str>) -> bool
pub fn contains_all_options(&self, needle_vec: Vec<&str>) -> bool
Returns a boolean for the question “Does the command include all of the option strings in needle_vec
Vector?”
Examples
let c = commandlines::Command::new();
if c.contains_all_options(vec!["--some", "--things"]) {
// implement whatever requires `some` && `things` condition
}
sourcepub fn contains_any_option(&self, needle_vec: Vec<&str>) -> bool
pub fn contains_any_option(&self, needle_vec: Vec<&str>) -> bool
Returns a boolean for the question “Does the command include any of the option strings in the needle_vec
Vector?”
Examples
let c = commandlines::Command::new();
if c.contains_any_option(vec!["-h", "--help"]) {
// received a help request with `-h` || `--help` condition
}
sourcepub fn get_definition_for(&self, needle: &str) -> Option<&String>
pub fn get_definition_for(&self, needle: &str) -> Option<&String>
Returns Option<&String> definition for a key defined by needle
Returns None
if the option was not used in the command
Examples
The following example demonstrates how to get the definition string for a command line option with the format --name=[definition]
:
let c = commandlines::Command::new();
match c.get_definition_for("--name") {
Some(x) => println!("The definition for --name is {}", *x),
None => eprintln!("Missing")
};
sourcepub fn get_argument_after(&self, needle: &str) -> Option<&String>
pub fn get_argument_after(&self, needle: &str) -> Option<&String>
Returns Option<&String>
for argument at index position i+1
for needle
at index position i
Returns None
if needle
is the last positional argument in the command
Remarks
This method can be used to obtain space-delimited definition arguments that follow an option (e.g., -o [filepath]
).
Examples
For a command with the syntax test -o [filepath]
the following can be used to get the filepath definition after the -o
option:
let c = commandlines::Command::new();
match c.get_argument_after("-o") {
Some(x) => println!("The filepath definition after -o is {}", *x),
None => eprintln!("-o is the last positional argument in the command")
}
sourcepub fn get_argument_at(&self, needle: usize) -> Option<&String>
pub fn get_argument_at(&self, needle: usize) -> Option<&String>
Returns Option<&String>
for the argument at index position needle
Returns None
if needle
is outside of the bounds of valid index values
Examples
// example command = "test subcmd --option"
let c = commandlines::Command::new();
match c.get_argument_at(0) {
Some(x) => println!("The executable is {}", *x),
None => eprintln!("Error")
}
match c.get_argument_at(1) {
Some(x) => println!("The first positional argument is {}", *x),
None => eprintln!("There is no first positional argument")
}
sourcepub fn get_index_of(&self, needle: &str) -> Option<usize>
pub fn get_index_of(&self, needle: &str) -> Option<usize>
Returns Option<usize>
for index position of the argument needle
in the Command.argv
Vector
Returns None
if needle
does not match a string in the Vector
Examples
In the following example, the command is test -o [filepath]
:
let c = commandlines::Command::new();
match c.get_index_of("-o") {
Some(x) => println!("The index position of -o is {}", x), // prints 1
None => eprintln!("The requested argument was not found")
}