Struct Args

pub struct Args {
    pub options: Vec<Opt>,
    pub other: Vec<String>,
    pub unknown: Vec<String>,
}

Parsed command line in organized form.

Instances of this struct are usually created with OptSpecs::getopt method and an instance represents the parsed output in organized form. See each field’s documentation for more information.

Programmers can use the parsed output (Args struct) any way they like. There are some methods for convenience.

Fields

options: Vec<Opt>

A vector of valid command-line options.

Elements of this vector are Opt structs which each represents a single command-line option. Elements are in the same order as given (by program’s user) in the command line. The vector is empty if the parser didn’t find any valid command-line options.

other: Vec<String>

A vector of other arguments (non-options).

Each element of the vector is a single non-option argument string in the same order as given (by program’s user) in the command line. The vector is empty if the parser didn’t find any non-option arguments.

unknown: Vec<String>

Unknown options.

Command-line arguments that look like options but were not part of OptSpecs specification are classified as unknown. They are listed in this vector. Possible duplicate unknown options have been filtered out.

Each element is the name string for the option (without - or -- prefix). For unknown short options the element is a single-character string. For unknown long options the string has more than one character. The whole vector is empty if there were no unknown options.

If a long option does not accept a value (that is, its value type is OptValueType::None) but user gives it a value with equal sign notation (--foo=), that option is classified as unknown and it will be in this field’s vector with name foo=.

Implementations

impl Args

pub fn required_value_missing(&self) -> Vec<&Opt>

Find options with missing required value.

This method finds all (otherwise valid) options which require a value but the value is missing. That is, OptSpecs struct specification defined that an option requires a value but program’s user didn’t give one in the command line. Such thing can happen if an option like --file is the last argument in the command line and that option requires a value. Empty string "" is not classified as missing value because it can be valid user input in many situations.

This method returns a vector (possibly empty) and each element is a reference to an Opt struct in the original Args::options field contents.

Examples found in repository

examples/basic.rs (line 43)

fn main() -> ExitCode {
    // The `OptSpecs::new()` function below creates a new option
    // specification struct `OptSpecs`. Its `option()` methods configure
    // three different options for logical meanings "help", "file" and
    // "verbose". All three options can be written in command-line with
    // a short variant (like "-h") and a long variant (like "--help").
    // Some options accept or require a value.
    //
    // Flag OptionsEverywhere changes parser's behavior. This flag means
    // that options and other arguments (non-options) can be mixed in
    // their order in the command line. Without the flag the option
    // parsing stops at the first non-option argument and the rest of
    // the command-line is parsed as non-options.
    let specs = OptSpecs::new()
        .flag(OptFlags::OptionsEverywhere) // Argument: (flag)
        .option("help", "h", OptValueType::None) // Arguments: (id, name, value_type)
        .option("help", "help", OptValueType::None)
        .option("file", "f", OptValueType::Required)
        .option("file", "file", OptValueType::Required)
        .option("verbose", "v", OptValueType::Optional)
        .option("verbose", "verbose", OptValueType::Optional);

    // Get arguments iterator from operating system and skip the first item
    let args = std::env::args().skip(1); // which is this program's file path.

    // Parse program's command-line with the given specification `specs`.
    let parsed = specs.getopt(args);

    // With this you can see the parsed output which is an `Args`
    // struct.
    eprintln!("{:#?}", parsed);

    // Report user about unknown options.
    for u in &parsed.unknown {
        eprintln!("Unknown option: {}", u);
    }

    // Report user about missing values for options that require them
    // (i.e. "file"). Exit the program with error code.
    for o in &parsed.required_value_missing() {
        eprintln!("Value is required for option '{}'.", o.name);
        return ExitCode::FAILURE;
    }

    // Print help and exit because "-h" or "--help" was given. We use
    // option's identifier string "help" here to find if the correct
    // option was present in the command line. See the `id` argument of
    // `option()` methods above.
    if parsed.option_exists("help") {
        println!("Print friendly help about program's usage.");
        return ExitCode::from(2);
    }

    // Collect all (required) values for "-f" and "--file". We use
    // option's identifier (id) string "file" to find the option.
    for f in &parsed.options_value_all("file") {
        println!("File name: {:?}", f);
    }

    // Notice if "-v" or "--verbose" was given (even without a value).
    // Then collect all its (optional) values. We use option's
    // identifier (id) string "verbose".
    if parsed.option_exists("verbose") {
        println!("Option 'verbose' was given.");

        for v in &parsed.options_value_all("verbose") {
            println!("Verbose level: {:?}", v);
        }
    }

    // Collect all other (non-option) arguments.
    for o in &parsed.other {
        println!("Other argument: {:?}", o);
    }

    // Try to run this program with various command-line options to see
    // the output.
    ExitCode::SUCCESS
}

pub fn option_exists(&self, id: &str) -> bool

Return boolean whether option with the given id exists.

This is functionally the same as options_first(id).is_some().

Examples found in repository

examples/basic.rs (line 52)

fn main() -> ExitCode {
    // The `OptSpecs::new()` function below creates a new option
    // specification struct `OptSpecs`. Its `option()` methods configure
    // three different options for logical meanings "help", "file" and
    // "verbose". All three options can be written in command-line with
    // a short variant (like "-h") and a long variant (like "--help").
    // Some options accept or require a value.
    //
    // Flag OptionsEverywhere changes parser's behavior. This flag means
    // that options and other arguments (non-options) can be mixed in
    // their order in the command line. Without the flag the option
    // parsing stops at the first non-option argument and the rest of
    // the command-line is parsed as non-options.
    let specs = OptSpecs::new()
        .flag(OptFlags::OptionsEverywhere) // Argument: (flag)
        .option("help", "h", OptValueType::None) // Arguments: (id, name, value_type)
        .option("help", "help", OptValueType::None)
        .option("file", "f", OptValueType::Required)
        .option("file", "file", OptValueType::Required)
        .option("verbose", "v", OptValueType::Optional)
        .option("verbose", "verbose", OptValueType::Optional);

    // Get arguments iterator from operating system and skip the first item
    let args = std::env::args().skip(1); // which is this program's file path.

    // Parse program's command-line with the given specification `specs`.
    let parsed = specs.getopt(args);

    // With this you can see the parsed output which is an `Args`
    // struct.
    eprintln!("{:#?}", parsed);

    // Report user about unknown options.
    for u in &parsed.unknown {
        eprintln!("Unknown option: {}", u);
    }

    // Report user about missing values for options that require them
    // (i.e. "file"). Exit the program with error code.
    for o in &parsed.required_value_missing() {
        eprintln!("Value is required for option '{}'.", o.name);
        return ExitCode::FAILURE;
    }

    // Print help and exit because "-h" or "--help" was given. We use
    // option's identifier string "help" here to find if the correct
    // option was present in the command line. See the `id` argument of
    // `option()` methods above.
    if parsed.option_exists("help") {
        println!("Print friendly help about program's usage.");
        return ExitCode::from(2);
    }

    // Collect all (required) values for "-f" and "--file". We use
    // option's identifier (id) string "file" to find the option.
    for f in &parsed.options_value_all("file") {
        println!("File name: {:?}", f);
    }

    // Notice if "-v" or "--verbose" was given (even without a value).
    // Then collect all its (optional) values. We use option's
    // identifier (id) string "verbose".
    if parsed.option_exists("verbose") {
        println!("Option 'verbose' was given.");

        for v in &parsed.options_value_all("verbose") {
            println!("Verbose level: {:?}", v);
        }
    }

    // Collect all other (non-option) arguments.
    for o in &parsed.other {
        println!("Other argument: {:?}", o);
    }

    // Try to run this program with various command-line options to see
    // the output.
    ExitCode::SUCCESS
}

pub fn options_all(&self, id: &str) -> Vec<&Opt>

Find all options with the given id.

Find all options which have the identifier id. (Option identifiers have been defined in OptSpecs struct before parsing.) The return value is a vector (possibly empty, if no matches) and each element is a reference to Opt struct in the original Args struct. Elements in the vector are in the same order as in the parsed command line.

pub fn options_first(&self, id: &str) -> Option<&Opt>

Find the first option with the given id.

Find and return the first match for option id in command-line arguments’ order. (Options’ identifiers have been defined in OptSpecs struct before parsing.)

The return value is a variant of enum Option. Their meanings:

• None: No options found with the given id.

• Some(&Opt): An option was found with the given id and a reference is provided to its Opt struct in the original Args::options field.

pub fn options_last(&self, id: &str) -> Option<&Opt>

Find the last option with the given id.

This is similar to options_first method but this returns the last match in command-line arguments’ order.

pub fn options_value_all(&self, id: &str) -> Vec<&String>

Find and return all values for options with the given id.

Find all options which match the identifier id and which also have a value assigned. (Options’ identifiers have been defined in OptSpecs struct before parsing.) Collect options’ values into a new vector in the same order as they were given in the command line. Vector’s elements are references to the value strings in the original Args struct. The returned vector is empty if there were no matches.

Examples found in repository

examples/basic.rs (line 59)

fn main() -> ExitCode {
    // The `OptSpecs::new()` function below creates a new option
    // specification struct `OptSpecs`. Its `option()` methods configure
    // three different options for logical meanings "help", "file" and
    // "verbose". All three options can be written in command-line with
    // a short variant (like "-h") and a long variant (like "--help").
    // Some options accept or require a value.
    //
    // Flag OptionsEverywhere changes parser's behavior. This flag means
    // that options and other arguments (non-options) can be mixed in
    // their order in the command line. Without the flag the option
    // parsing stops at the first non-option argument and the rest of
    // the command-line is parsed as non-options.
    let specs = OptSpecs::new()
        .flag(OptFlags::OptionsEverywhere) // Argument: (flag)
        .option("help", "h", OptValueType::None) // Arguments: (id, name, value_type)
        .option("help", "help", OptValueType::None)
        .option("file", "f", OptValueType::Required)
        .option("file", "file", OptValueType::Required)
        .option("verbose", "v", OptValueType::Optional)
        .option("verbose", "verbose", OptValueType::Optional);

    // Get arguments iterator from operating system and skip the first item
    let args = std::env::args().skip(1); // which is this program's file path.

    // Parse program's command-line with the given specification `specs`.
    let parsed = specs.getopt(args);

    // With this you can see the parsed output which is an `Args`
    // struct.
    eprintln!("{:#?}", parsed);

    // Report user about unknown options.
    for u in &parsed.unknown {
        eprintln!("Unknown option: {}", u);
    }

    // Report user about missing values for options that require them
    // (i.e. "file"). Exit the program with error code.
    for o in &parsed.required_value_missing() {
        eprintln!("Value is required for option '{}'.", o.name);
        return ExitCode::FAILURE;
    }

    // Print help and exit because "-h" or "--help" was given. We use
    // option's identifier string "help" here to find if the correct
    // option was present in the command line. See the `id` argument of
    // `option()` methods above.
    if parsed.option_exists("help") {
        println!("Print friendly help about program's usage.");
        return ExitCode::from(2);
    }

    // Collect all (required) values for "-f" and "--file". We use
    // option's identifier (id) string "file" to find the option.
    for f in &parsed.options_value_all("file") {
        println!("File name: {:?}", f);
    }

    // Notice if "-v" or "--verbose" was given (even without a value).
    // Then collect all its (optional) values. We use option's
    // identifier (id) string "verbose".
    if parsed.option_exists("verbose") {
        println!("Option 'verbose' was given.");

        for v in &parsed.options_value_all("verbose") {
            println!("Verbose level: {:?}", v);
        }
    }

    // Collect all other (non-option) arguments.
    for o in &parsed.other {
        println!("Other argument: {:?}", o);
    }

    // Try to run this program with various command-line options to see
    // the output.
    ExitCode::SUCCESS
}

pub fn options_value_first(&self, id: &str) -> Option<&String>

Find the first option with a value for given option id.

Find the first option with the identifier id and which has a value assigned. (Options’ identifiers have been defined in OptSpecs struct before parsing.) Method’s return value is a variant of enum Option which are:

• None: No options found with the given id and a value assigned. Note that there could be options for the same id but they don’t have a value.

• Some(&String): An option was found with the given id and the option has a value assigned. A reference is provided to the string value in the Opt::value field in the original Args::options field.

pub fn options_value_last(&self, id: &str) -> Option<&String>

Find the last option with a value for given option id.

This is similar to options_value_first method but this method finds and returns the last option’s value.

Note: Program’s user may give the same option several times in the command line. If the option accepts a value it may be suitable to consider only the last value relevant. (Or the first, or maybe print an error message for providing several, possibly conflicting, values.)

Trait Implementations

impl Debug for Args

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

Formats the value using the given formatter.

impl PartialEq for Args

fn eq(&self, other: &Args) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Args