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_mops(&self) -> bool
pub fn has_mops(&self) -> bool
Returns a boolean for the question “Does the command include any multi-option short syntax style option arguments?”
Remarks
POSIX defines a short option style that uses a single dash delimiter with more than one option indicated by the individual characters defined in the argument string (e.g., -hij
means that the command has the options -h -i -j
). This method provides support for determining whether a mops style option is present in the command string.
Examples
let c = commandlines::Command::new();
if c.has_mops() {
// at least one multi-option short syntax style argument was 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.
If you use POSIX multi-option short syntax style arguments (e.g., “-lmn” is used to indicate “-l -m -n”) in your application, see the Command::contains_mops()
method. This method does not test against mops style command line arguments.
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_mops(&self, needle: &str) -> bool
pub fn contains_mops(&self, needle: &str) -> bool
Returns a boolean for the question “Does the command include the option needle
when the POSIX multi-option short syntax option style is used?”
Remarks
The mops style defined by POSIX includes a single dash character followed by one or more alphanumeric characters in the Unicode Basic Latin set. Each character represents a unique option switch. For example, “-lmn” is used to indicate “-l -m -n”. This method tests against any short option formatted argument included in the command irrespective of the number of alphanumeric characters that are included. The method does not test against long options (i.e., those that begin with two dashes).
If you do not use the mops option syntax in your application, use the Command::contains_option()
method instead.
Examples
let c = commandlines::Command::new();
if c.contains_mops("-j") {
// the `j` switch was identified in a short format option on the command line
}
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_mops(&self, needle_vec: Vec<&str>) -> bool
pub fn contains_all_mops(&self, needle_vec: Vec<&str>) -> bool
Returns a boolean for the question “Does the command include the option needle
when the POSIX multi-option short syntax option style is used?”
Remarks
The mops style defined by POSIX includes a single dash character followed by one or more alphanumeric characters in the Unicode Basic Latin set. Each character represents a unique option switch. For example, “-lmn” is used to indicate “-l -m -n”. This method tests against any short option formatted argument included in the command irrespective of the number of alphanumeric characters that are included. The method does not test against long options (i.e., those that begin with two dashes).
If you do not use the mops option syntax in your application, use the Command::contains_all_options()
method instead.
Examples
let c = commandlines::Command::new();
if c.contains_all_mops(vec!["-j", "-k", "-l"]) {
// the `j`, `k` and `l` switches were identified in short format options on the command line
}
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_mops(&self, needle_vec: Vec<&str>) -> bool
pub fn contains_any_mops(&self, needle_vec: Vec<&str>) -> bool
Returns a boolean for the question “Does the command include the option needle
when the POSIX multi-option short syntax option style is used?”
Remarks
The mops style defined by POSIX includes a single dash character followed by one or more alphanumeric characters in the Unicode Basic Latin set. Each character represents a unique option switch. For example, “-lmn” is used to indicate “-l -m -n”. This method tests against any short option formatted argument included in the command irrespective of the number of alphanumeric characters that are included. The method does not test against long options (i.e., those that begin with two dashes).
If you do not use the mops option syntax in your application, use the Command::contains_any_options()
method instead.
Examples
let c = commandlines::Command::new();
if c.contains_any_mops(vec!["-j", "-k", "-l"]) {
// the `j` or `k` or `l` switch was identified in short format options on the command line
}
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 contains_sequence(&self, needle_vec: Vec<&str>) -> bool
pub fn contains_sequence(&self, needle_vec: Vec<&str>) -> bool
Returns boolean for the question “Do the command arguments to the executable match the argument strings and sequence in needle_vec
Vector?”
Examples
let c = commandlines::Command::new();
if c.contains_sequence(vec!["filter", "help"]) {
// the command sequence was identified as "[executable] filter help"
}
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")
}
sourcepub fn is_help_request(&self) -> bool
pub fn is_help_request(&self) -> bool
Returns boolean for the question “Is the command a help request with a -h
or --help
flag?”
Examples
let c = commandlines::Command::new();
if c.is_help_request() {
// handle help request
}
sourcepub fn is_version_request(&self) -> bool
pub fn is_version_request(&self) -> bool
Returns boolean for the question “Is the command a version request with a -v
or --version
flag?”
Examples
let c = commandlines::Command::new();
if c.is_version_request() {
// handle version request
}
sourcepub fn is_usage_request(&self) -> bool
pub fn is_usage_request(&self) -> bool
Returns boolean for the question “Is the command a usage request with a --usage
flag?”
Examples
let c = commandlines::Command::new();
if c.is_usage_request() {
// handle usage request
}