Struct OptSpecs 

pub struct OptSpecs { /* private fields */ }

Specification for program’s valid command-line options.

An instance of this struct is needed before command-line options can be parsed. Instances are created with function OptSpecs::new and they are modified with option and other methods

The struct instance is used when parsing the command line given by program’s user. The parser methods is getopt.

Implementations

impl OptSpecs

pub fn new() -> Self

Create and return a new instance of OptSpecs struct.

The created instance is “empty” and does not contain any specifications for command-line options. Apply option or other methods to make it useful for parsing command-line.

Examples found in repository

examples/basic.rs (line 21)

fn main() {
    // 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()
        .option("help", "h", OptValue::None) // Arguments: (id, name, value_type)
        .option("help", "help", OptValue::None)
        .option("file", "f", OptValue::RequiredNonEmpty)
        .option("file", "file", OptValue::RequiredNonEmpty)
        .option("verbose", "v", OptValue::OptionalNonEmpty)
        .option("verbose", "verbose", OptValue::OptionalNonEmpty)
        .flag(OptFlags::OptionsEverywhere);

    // 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);

    // Create a condition variable for possible exit on error.
    let mut error_exit = false;

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

    // Report user about missing values for options that require them
    // (i.e. "file").
    for o in parsed.required_value_missing() {
        eprintln!("Value is required for option '{}'.", o.name);
        error_exit = true;
    }

    // Exit if there were bad command-line arguments.
    if error_exit {
        eprintln!("Use '-h' for help.");
        std::process::exit(1);
    }

    // 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.");
        std::process::exit(0);
    }

    // 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);
    }
}

pub fn option(self, id: &str, name: &str, value_type: OptValue) -> Self

Add an option specification for OptSpecs.

The method requires three arguments:

1. id: Programmer’s identifier string for the option. Later, after parsing the command line, the identifier is used to match if this particular option was present in the command-line.

   Several options may have the same identifier string. This makes sense when different option names in the command line represent the same meaning, like -h and --help for printing program’s help message.

2. name: Option’s name string in the command line (without prefix). If the string is a single character (like h) it defines a short option which is entered as -h in the command line. If there are more than one character in the string it defines a long option name (like help) which is entered as --help in the command line.

   All options must have a unique name string. This method will panic if the same name is added twice. The method will also panic if the name string contains illegal characters. Space characters are not accepted. A short option name can’t be - and long option names can’t have any = characters nor - as their first character.

3. value_type: The argument is a variant of enum OptValue and it defines if and how this option accepts a value. See the enum’s documentation for more information.

The return value is the same struct instance which was modified.

Examples found in repository

examples/basic.rs (line 22)

fn main() {
    // 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()
        .option("help", "h", OptValue::None) // Arguments: (id, name, value_type)
        .option("help", "help", OptValue::None)
        .option("file", "f", OptValue::RequiredNonEmpty)
        .option("file", "file", OptValue::RequiredNonEmpty)
        .option("verbose", "v", OptValue::OptionalNonEmpty)
        .option("verbose", "verbose", OptValue::OptionalNonEmpty)
        .flag(OptFlags::OptionsEverywhere);

    // 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);

    // Create a condition variable for possible exit on error.
    let mut error_exit = false;

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

    // Report user about missing values for options that require them
    // (i.e. "file").
    for o in parsed.required_value_missing() {
        eprintln!("Value is required for option '{}'.", o.name);
        error_exit = true;
    }

    // Exit if there were bad command-line arguments.
    if error_exit {
        eprintln!("Use '-h' for help.");
        std::process::exit(1);
    }

    // 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.");
        std::process::exit(0);
    }

    // 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);
    }
}

pub fn flag(self, flag: OptFlags) -> Self

Add a flag that changes parser’s behavior.

Method’s only argument flag is a variant of enum OptFlags and it is a configuration flag that changes parser’s general behavior. See the enum’s documentation for more information.

The return value is the same struct instance which was modified.

Examples found in repository

examples/basic.rs (line 28)

fn main() {
    // 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()
        .option("help", "h", OptValue::None) // Arguments: (id, name, value_type)
        .option("help", "help", OptValue::None)
        .option("file", "f", OptValue::RequiredNonEmpty)
        .option("file", "file", OptValue::RequiredNonEmpty)
        .option("verbose", "v", OptValue::OptionalNonEmpty)
        .option("verbose", "verbose", OptValue::OptionalNonEmpty)
        .flag(OptFlags::OptionsEverywhere);

    // 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);

    // Create a condition variable for possible exit on error.
    let mut error_exit = false;

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

    // Report user about missing values for options that require them
    // (i.e. "file").
    for o in parsed.required_value_missing() {
        eprintln!("Value is required for option '{}'.", o.name);
        error_exit = true;
    }

    // Exit if there were bad command-line arguments.
    if error_exit {
        eprintln!("Use '-h' for help.");
        std::process::exit(1);
    }

    // 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.");
        std::process::exit(0);
    }

    // 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);
    }
}

pub fn limit_options(self, limit: u32) -> Self

Maximum number of valid options.

Method’s argument limit sets the maximum number of valid options to collect from the command line. The rest is ignored. This doesn’t include unknown options (see limit_unknown_options).

The return value is the same struct instance which was modified.

pub fn limit_other_args(self, limit: u32) -> Self

Maximum number of other command-line arguments.

Method’s argument limit sets the maximum number of other (non-option) arguments to collect from the command line. The rest is ignored.

Note: If your program accepts n number of command-line argument (apart from options) you could set this limit to n + 1. This way you know if there were more arguments than needed and can inform program’s user about that. There is no need to collect more arguments.

The return value is the same struct instance which was modified.

pub fn limit_unknown_options(self, limit: u32) -> Self

Maximum number of unknown options.

Method’s argument limit sets the maximum number of unique unknown options to collect from the command line. Duplicates are not collected.

Note: If you want to stop your program if it notices just one unknown option you can set this limit to 1. There is probably no need to collect more of them.

The return value is the same struct instance which was modified.

pub fn getopt<I, S>(&self, args: I) -> Args

where I: IntoIterator<Item = S>, S: ToString,

Getopt-parse an iterable item as command line arguments.

This method’s argument args is of any type that implements trait IntoIterator and that has items of type that implements trait ToString. For example, argument args can be a vector or an iterator such as command-line arguments returned by std::env::args.

The return value is an Args struct which represents the command-line information in organized form.

Examples found in repository

examples/basic.rs (line 34)

fn main() {
    // 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()
        .option("help", "h", OptValue::None) // Arguments: (id, name, value_type)
        .option("help", "help", OptValue::None)
        .option("file", "f", OptValue::RequiredNonEmpty)
        .option("file", "file", OptValue::RequiredNonEmpty)
        .option("verbose", "v", OptValue::OptionalNonEmpty)
        .option("verbose", "verbose", OptValue::OptionalNonEmpty)
        .flag(OptFlags::OptionsEverywhere);

    // 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);

    // Create a condition variable for possible exit on error.
    let mut error_exit = false;

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

    // Report user about missing values for options that require them
    // (i.e. "file").
    for o in parsed.required_value_missing() {
        eprintln!("Value is required for option '{}'.", o.name);
        error_exit = true;
    }

    // Exit if there were bad command-line arguments.
    if error_exit {
        eprintln!("Use '-h' for help.");
        std::process::exit(1);
    }

    // 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.");
        std::process::exit(0);
    }

    // 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);
    }
}

Trait Implementations

impl Debug for OptSpecs

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

Formats the value using the given formatter.

impl Default for OptSpecs

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for OptSpecs

fn eq(&self, other: &OptSpecs) -> 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 OptSpecs