Skip to main content

OptSpec

noargs

Struct OptSpec 

Source 
pub struct OptSpec {
    pub name: &'static str,
    pub short: Option<char>,
    pub ty: &'static str,
    pub doc: &'static str,
    pub env: Option<&'static str>,
    pub default: Option<&'static str>,
    pub example: Option<&'static str>,
}
Expand description

Specification for Opt.

Note that noargs does not support options with only short names.

Fields§

§name: &'static str

Option long name (usually kebab-case).

§short: Option<char>

Option short name.

§ty: &'static str

Value type.

§doc: &'static str

Documentation.

§env: Option<&'static str>

Environment variable name.

If a non-empty value is set for this environment variable, it will be used as the value of this option when the option is not specified in RawArgs.

§default: Option<&'static str>

Default value.

§example: Option<&'static str>

Example value (if this is set, the option is considered to be requried when generating the help text).

This is only used if RawArgs::metadata().help_mode is true.

Implementations§

Source§

impl OptSpec

Source

pub const DEFAULT: Self

The default specification.

Source

pub const fn new(name: &'static str) -> Self

Makes an OptSpec instance with a specified name (equivalent to noargs::opt(name)).

Source

pub const fn short(self, name: char) -> Self

Updates the value of OptSpec::short.

Examples found in repository?
examples/subcommands.rs (line 65)
55fn try_run_sum(args: &mut noargs::RawArgs) -> noargs::Result<bool> {
56    if !noargs::cmd("sum")
57        .doc("Add two integers")
58        .take(args)
59        .is_present()
60    {
61        return Ok(false);
62    }
63
64    let repeat: usize = noargs::opt("repeat")
65        .short('r')
66        .ty("N")
67        .doc("Print result multiple times")
68        .default("1")
69        .take(args)
70        .then(|o| o.value().parse())?;
71    let left: i64 = noargs::arg("<LEFT>")
72        .doc("Left operand")
73        .example("3")
74        .take(args)
75        .then(|a| a.value().parse())?;
76    let right: i64 = noargs::arg("<RIGHT>")
77        .doc("Right operand")
78        .example("4")
79        .take(args)
80        .then(|a| a.value().parse())?;
81
82    if args.metadata().help_mode {
83        return Ok(true);
84    }
85
86    let total = left + right;
87    for _ in 0..repeat {
88        println!("{total}");
89    }
90    Ok(true)
91}
More examples
Hide additional examples
examples/arrays.rs (line 14)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Same-name options can be collected by calling take() in a loop.
13    let include_opt = noargs::opt("include")
14        .short('I')
15        .ty("PATH")
16        .doc("Include path (can be specified multiple times)");
17    let mut includes = Vec::<String>::new();
18    while let Some(path) = include_opt
19        .take(&mut args)
20        .present_and_then(|o| o.value().parse())?
21    {
22        includes.push(path);
23    }
24
25    let label_opt = noargs::opt("label")
26        .short('l')
27        .ty("LABEL")
28        .doc("Label value (can be specified multiple times)");
29    let mut labels = Vec::<String>::new();
30    while let Some(label) = label_opt
31        .take(&mut args)
32        .present_and_then(|o| o.value().parse())?
33    {
34        labels.push(label);
35    }
36
37    let output: String = noargs::opt("output")
38        .short('o')
39        .ty("PATH")
40        .doc("Output path")
41        .default("summary.txt")
42        .take(&mut args)
43        .then(|o| o.value().parse())?;
44
45    // Positional arrays are handled with one required argument + optional rest.
46    // Naming convention: use `<NAME>...` for required-many and `[NAME]...` for optional-many.
47    // The `<>` / `[]` / `...` markers are cosmetic (used only in help output);
48    // required-ness is enforced below: `.then()` makes the first input required,
49    // the loop with `.present_and_then()` consumes zero or more rest inputs.
50    let first_input: String = noargs::arg("<INPUT>")
51        .doc("First input (required)")
52        .example("a.txt")
53        .take(&mut args)
54        .then(|a| a.value().parse())?;
55    let rest_input_arg = noargs::arg("[INPUT]...").doc("Additional inputs");
56    let mut inputs = vec![first_input];
57    while let Some(input) = rest_input_arg
58        .take(&mut args)
59        .present_and_then(|a| a.value().parse())?
60    {
61        inputs.push(input);
62    }
63
64    if let Some(help) = args.finish()? {
65        print!("{help}");
66        return Ok(());
67    }
68
69    println!("includes={includes:?}");
70    println!("labels={labels:?}");
71    println!("inputs={inputs:?}");
72    println!("output={output}");
73    Ok(())
74}
examples/basics.rs (line 29)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Important: call flag()/opt() before arg().
13    // Otherwise values like "-v" — or any unknown "--bogus" — can be silently
14    // consumed as positional arguments.
15    //
16    // Required option / positional: set example("...") so help mode renders
17    // a meaningful Usage / Example line. Optional fields covered by default()
18    // or present_and_then() do not need example().
19    let verbose = noargs::flag("verbose")
20        .short('v')
21        .doc("Enable verbose output")
22        .take(&mut args)
23        .is_present();
24    let dry_run = noargs::flag("dry-run")
25        .doc("Print parsed values and exit without running processing")
26        .take(&mut args)
27        .is_present();
28    let retries: usize = noargs::opt("retries")
29        .short('r')
30        .ty("N")
31        .doc("How many times to retry")
32        .default("1")
33        .take(&mut args)
34        .then(|o| o.value().parse())?;
35    let endpoint: String = noargs::opt("endpoint")
36        .ty("URL")
37        .doc("Server endpoint")
38        .env("NOARGS_ENDPOINT")
39        .default("http://localhost:8080")
40        .take(&mut args)
41        .then(|o| o.value().parse())?;
42    let format: String = noargs::opt("format")
43        .ty("FORMAT")
44        .doc("Output format")
45        .example("json")
46        .take(&mut args)
47        .then(|o| o.value().parse())?;
48    let timeout_secs: Option<u64> = noargs::opt("timeout")
49        .ty("SECONDS")
50        .doc("Optional timeout in seconds")
51        .take(&mut args)
52        .present_and_then(|o| o.value().parse())?;
53
54    let input: String = noargs::arg("<INPUT>")
55        .doc("Input file path")
56        .example("input.txt")
57        .take(&mut args)
58        .then(|a| a.value().parse())?;
59    // Optional positional with default(): the value is always a String —
60    // absent uses "out.txt", present uses the given path.
61    // For "absent vs present" distinction, use present_and_then() and bind
62    // to Option<String> — see the README's [BAZ] example.
63    let output: String = noargs::arg("[OUTPUT]")
64        .doc("Output file path")
65        .default("out.txt")
66        .take(&mut args)
67        .then(|a| a.value().parse())?;
68
69    if let Some(help) = args.finish()? {
70        // When help is requested, finish() returns the built help text.
71        // Print it here and exit without running application logic.
72        print!("{help}");
73        return Ok(());
74    }
75
76    if dry_run {
77        println!(
78            "dry-run: verbose={verbose}, retries={retries}, endpoint={endpoint}, format={format}, timeout_secs={timeout_secs:?}, input={input}, output={output}"
79        );
80        return Ok(());
81    }
82
83    println!("processing: {input} -> {output}");
84    println!("using endpoint={endpoint}, format={format}, retries={retries}");
85    if verbose {
86        println!("verbose: timeout_secs={timeout_secs:?}");
87    }
88
89    Ok(())
90}
Source

pub const fn ty(self, value_type: &'static str) -> Self

Updates the value of OptSpec::ty.

Examples found in repository?
examples/subcommands.rs (line 66)
55fn try_run_sum(args: &mut noargs::RawArgs) -> noargs::Result<bool> {
56    if !noargs::cmd("sum")
57        .doc("Add two integers")
58        .take(args)
59        .is_present()
60    {
61        return Ok(false);
62    }
63
64    let repeat: usize = noargs::opt("repeat")
65        .short('r')
66        .ty("N")
67        .doc("Print result multiple times")
68        .default("1")
69        .take(args)
70        .then(|o| o.value().parse())?;
71    let left: i64 = noargs::arg("<LEFT>")
72        .doc("Left operand")
73        .example("3")
74        .take(args)
75        .then(|a| a.value().parse())?;
76    let right: i64 = noargs::arg("<RIGHT>")
77        .doc("Right operand")
78        .example("4")
79        .take(args)
80        .then(|a| a.value().parse())?;
81
82    if args.metadata().help_mode {
83        return Ok(true);
84    }
85
86    let total = left + right;
87    for _ in 0..repeat {
88        println!("{total}");
89    }
90    Ok(true)
91}
More examples
Hide additional examples
examples/arrays.rs (line 15)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Same-name options can be collected by calling take() in a loop.
13    let include_opt = noargs::opt("include")
14        .short('I')
15        .ty("PATH")
16        .doc("Include path (can be specified multiple times)");
17    let mut includes = Vec::<String>::new();
18    while let Some(path) = include_opt
19        .take(&mut args)
20        .present_and_then(|o| o.value().parse())?
21    {
22        includes.push(path);
23    }
24
25    let label_opt = noargs::opt("label")
26        .short('l')
27        .ty("LABEL")
28        .doc("Label value (can be specified multiple times)");
29    let mut labels = Vec::<String>::new();
30    while let Some(label) = label_opt
31        .take(&mut args)
32        .present_and_then(|o| o.value().parse())?
33    {
34        labels.push(label);
35    }
36
37    let output: String = noargs::opt("output")
38        .short('o')
39        .ty("PATH")
40        .doc("Output path")
41        .default("summary.txt")
42        .take(&mut args)
43        .then(|o| o.value().parse())?;
44
45    // Positional arrays are handled with one required argument + optional rest.
46    // Naming convention: use `<NAME>...` for required-many and `[NAME]...` for optional-many.
47    // The `<>` / `[]` / `...` markers are cosmetic (used only in help output);
48    // required-ness is enforced below: `.then()` makes the first input required,
49    // the loop with `.present_and_then()` consumes zero or more rest inputs.
50    let first_input: String = noargs::arg("<INPUT>")
51        .doc("First input (required)")
52        .example("a.txt")
53        .take(&mut args)
54        .then(|a| a.value().parse())?;
55    let rest_input_arg = noargs::arg("[INPUT]...").doc("Additional inputs");
56    let mut inputs = vec![first_input];
57    while let Some(input) = rest_input_arg
58        .take(&mut args)
59        .present_and_then(|a| a.value().parse())?
60    {
61        inputs.push(input);
62    }
63
64    if let Some(help) = args.finish()? {
65        print!("{help}");
66        return Ok(());
67    }
68
69    println!("includes={includes:?}");
70    println!("labels={labels:?}");
71    println!("inputs={inputs:?}");
72    println!("output={output}");
73    Ok(())
74}
examples/basics.rs (line 30)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Important: call flag()/opt() before arg().
13    // Otherwise values like "-v" — or any unknown "--bogus" — can be silently
14    // consumed as positional arguments.
15    //
16    // Required option / positional: set example("...") so help mode renders
17    // a meaningful Usage / Example line. Optional fields covered by default()
18    // or present_and_then() do not need example().
19    let verbose = noargs::flag("verbose")
20        .short('v')
21        .doc("Enable verbose output")
22        .take(&mut args)
23        .is_present();
24    let dry_run = noargs::flag("dry-run")
25        .doc("Print parsed values and exit without running processing")
26        .take(&mut args)
27        .is_present();
28    let retries: usize = noargs::opt("retries")
29        .short('r')
30        .ty("N")
31        .doc("How many times to retry")
32        .default("1")
33        .take(&mut args)
34        .then(|o| o.value().parse())?;
35    let endpoint: String = noargs::opt("endpoint")
36        .ty("URL")
37        .doc("Server endpoint")
38        .env("NOARGS_ENDPOINT")
39        .default("http://localhost:8080")
40        .take(&mut args)
41        .then(|o| o.value().parse())?;
42    let format: String = noargs::opt("format")
43        .ty("FORMAT")
44        .doc("Output format")
45        .example("json")
46        .take(&mut args)
47        .then(|o| o.value().parse())?;
48    let timeout_secs: Option<u64> = noargs::opt("timeout")
49        .ty("SECONDS")
50        .doc("Optional timeout in seconds")
51        .take(&mut args)
52        .present_and_then(|o| o.value().parse())?;
53
54    let input: String = noargs::arg("<INPUT>")
55        .doc("Input file path")
56        .example("input.txt")
57        .take(&mut args)
58        .then(|a| a.value().parse())?;
59    // Optional positional with default(): the value is always a String —
60    // absent uses "out.txt", present uses the given path.
61    // For "absent vs present" distinction, use present_and_then() and bind
62    // to Option<String> — see the README's [BAZ] example.
63    let output: String = noargs::arg("[OUTPUT]")
64        .doc("Output file path")
65        .default("out.txt")
66        .take(&mut args)
67        .then(|a| a.value().parse())?;
68
69    if let Some(help) = args.finish()? {
70        // When help is requested, finish() returns the built help text.
71        // Print it here and exit without running application logic.
72        print!("{help}");
73        return Ok(());
74    }
75
76    if dry_run {
77        println!(
78            "dry-run: verbose={verbose}, retries={retries}, endpoint={endpoint}, format={format}, timeout_secs={timeout_secs:?}, input={input}, output={output}"
79        );
80        return Ok(());
81    }
82
83    println!("processing: {input} -> {output}");
84    println!("using endpoint={endpoint}, format={format}, retries={retries}");
85    if verbose {
86        println!("verbose: timeout_secs={timeout_secs:?}");
87    }
88
89    Ok(())
90}
Source

pub const fn doc(self, doc: &'static str) -> Self

Updates the value of OptSpec::doc.

Examples found in repository?
examples/subcommands.rs (line 67)
55fn try_run_sum(args: &mut noargs::RawArgs) -> noargs::Result<bool> {
56    if !noargs::cmd("sum")
57        .doc("Add two integers")
58        .take(args)
59        .is_present()
60    {
61        return Ok(false);
62    }
63
64    let repeat: usize = noargs::opt("repeat")
65        .short('r')
66        .ty("N")
67        .doc("Print result multiple times")
68        .default("1")
69        .take(args)
70        .then(|o| o.value().parse())?;
71    let left: i64 = noargs::arg("<LEFT>")
72        .doc("Left operand")
73        .example("3")
74        .take(args)
75        .then(|a| a.value().parse())?;
76    let right: i64 = noargs::arg("<RIGHT>")
77        .doc("Right operand")
78        .example("4")
79        .take(args)
80        .then(|a| a.value().parse())?;
81
82    if args.metadata().help_mode {
83        return Ok(true);
84    }
85
86    let total = left + right;
87    for _ in 0..repeat {
88        println!("{total}");
89    }
90    Ok(true)
91}
More examples
Hide additional examples
examples/arrays.rs (line 16)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Same-name options can be collected by calling take() in a loop.
13    let include_opt = noargs::opt("include")
14        .short('I')
15        .ty("PATH")
16        .doc("Include path (can be specified multiple times)");
17    let mut includes = Vec::<String>::new();
18    while let Some(path) = include_opt
19        .take(&mut args)
20        .present_and_then(|o| o.value().parse())?
21    {
22        includes.push(path);
23    }
24
25    let label_opt = noargs::opt("label")
26        .short('l')
27        .ty("LABEL")
28        .doc("Label value (can be specified multiple times)");
29    let mut labels = Vec::<String>::new();
30    while let Some(label) = label_opt
31        .take(&mut args)
32        .present_and_then(|o| o.value().parse())?
33    {
34        labels.push(label);
35    }
36
37    let output: String = noargs::opt("output")
38        .short('o')
39        .ty("PATH")
40        .doc("Output path")
41        .default("summary.txt")
42        .take(&mut args)
43        .then(|o| o.value().parse())?;
44
45    // Positional arrays are handled with one required argument + optional rest.
46    // Naming convention: use `<NAME>...` for required-many and `[NAME]...` for optional-many.
47    // The `<>` / `[]` / `...` markers are cosmetic (used only in help output);
48    // required-ness is enforced below: `.then()` makes the first input required,
49    // the loop with `.present_and_then()` consumes zero or more rest inputs.
50    let first_input: String = noargs::arg("<INPUT>")
51        .doc("First input (required)")
52        .example("a.txt")
53        .take(&mut args)
54        .then(|a| a.value().parse())?;
55    let rest_input_arg = noargs::arg("[INPUT]...").doc("Additional inputs");
56    let mut inputs = vec![first_input];
57    while let Some(input) = rest_input_arg
58        .take(&mut args)
59        .present_and_then(|a| a.value().parse())?
60    {
61        inputs.push(input);
62    }
63
64    if let Some(help) = args.finish()? {
65        print!("{help}");
66        return Ok(());
67    }
68
69    println!("includes={includes:?}");
70    println!("labels={labels:?}");
71    println!("inputs={inputs:?}");
72    println!("output={output}");
73    Ok(())
74}
examples/basics.rs (line 31)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Important: call flag()/opt() before arg().
13    // Otherwise values like "-v" — or any unknown "--bogus" — can be silently
14    // consumed as positional arguments.
15    //
16    // Required option / positional: set example("...") so help mode renders
17    // a meaningful Usage / Example line. Optional fields covered by default()
18    // or present_and_then() do not need example().
19    let verbose = noargs::flag("verbose")
20        .short('v')
21        .doc("Enable verbose output")
22        .take(&mut args)
23        .is_present();
24    let dry_run = noargs::flag("dry-run")
25        .doc("Print parsed values and exit without running processing")
26        .take(&mut args)
27        .is_present();
28    let retries: usize = noargs::opt("retries")
29        .short('r')
30        .ty("N")
31        .doc("How many times to retry")
32        .default("1")
33        .take(&mut args)
34        .then(|o| o.value().parse())?;
35    let endpoint: String = noargs::opt("endpoint")
36        .ty("URL")
37        .doc("Server endpoint")
38        .env("NOARGS_ENDPOINT")
39        .default("http://localhost:8080")
40        .take(&mut args)
41        .then(|o| o.value().parse())?;
42    let format: String = noargs::opt("format")
43        .ty("FORMAT")
44        .doc("Output format")
45        .example("json")
46        .take(&mut args)
47        .then(|o| o.value().parse())?;
48    let timeout_secs: Option<u64> = noargs::opt("timeout")
49        .ty("SECONDS")
50        .doc("Optional timeout in seconds")
51        .take(&mut args)
52        .present_and_then(|o| o.value().parse())?;
53
54    let input: String = noargs::arg("<INPUT>")
55        .doc("Input file path")
56        .example("input.txt")
57        .take(&mut args)
58        .then(|a| a.value().parse())?;
59    // Optional positional with default(): the value is always a String —
60    // absent uses "out.txt", present uses the given path.
61    // For "absent vs present" distinction, use present_and_then() and bind
62    // to Option<String> — see the README's [BAZ] example.
63    let output: String = noargs::arg("[OUTPUT]")
64        .doc("Output file path")
65        .default("out.txt")
66        .take(&mut args)
67        .then(|a| a.value().parse())?;
68
69    if let Some(help) = args.finish()? {
70        // When help is requested, finish() returns the built help text.
71        // Print it here and exit without running application logic.
72        print!("{help}");
73        return Ok(());
74    }
75
76    if dry_run {
77        println!(
78            "dry-run: verbose={verbose}, retries={retries}, endpoint={endpoint}, format={format}, timeout_secs={timeout_secs:?}, input={input}, output={output}"
79        );
80        return Ok(());
81    }
82
83    println!("processing: {input} -> {output}");
84    println!("using endpoint={endpoint}, format={format}, retries={retries}");
85    if verbose {
86        println!("verbose: timeout_secs={timeout_secs:?}");
87    }
88
89    Ok(())
90}
Source

pub const fn env(self, variable_name: &'static str) -> Self

Updates the value of OptSpec::env.

Examples found in repository?
examples/basics.rs (line 38)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Important: call flag()/opt() before arg().
13    // Otherwise values like "-v" — or any unknown "--bogus" — can be silently
14    // consumed as positional arguments.
15    //
16    // Required option / positional: set example("...") so help mode renders
17    // a meaningful Usage / Example line. Optional fields covered by default()
18    // or present_and_then() do not need example().
19    let verbose = noargs::flag("verbose")
20        .short('v')
21        .doc("Enable verbose output")
22        .take(&mut args)
23        .is_present();
24    let dry_run = noargs::flag("dry-run")
25        .doc("Print parsed values and exit without running processing")
26        .take(&mut args)
27        .is_present();
28    let retries: usize = noargs::opt("retries")
29        .short('r')
30        .ty("N")
31        .doc("How many times to retry")
32        .default("1")
33        .take(&mut args)
34        .then(|o| o.value().parse())?;
35    let endpoint: String = noargs::opt("endpoint")
36        .ty("URL")
37        .doc("Server endpoint")
38        .env("NOARGS_ENDPOINT")
39        .default("http://localhost:8080")
40        .take(&mut args)
41        .then(|o| o.value().parse())?;
42    let format: String = noargs::opt("format")
43        .ty("FORMAT")
44        .doc("Output format")
45        .example("json")
46        .take(&mut args)
47        .then(|o| o.value().parse())?;
48    let timeout_secs: Option<u64> = noargs::opt("timeout")
49        .ty("SECONDS")
50        .doc("Optional timeout in seconds")
51        .take(&mut args)
52        .present_and_then(|o| o.value().parse())?;
53
54    let input: String = noargs::arg("<INPUT>")
55        .doc("Input file path")
56        .example("input.txt")
57        .take(&mut args)
58        .then(|a| a.value().parse())?;
59    // Optional positional with default(): the value is always a String —
60    // absent uses "out.txt", present uses the given path.
61    // For "absent vs present" distinction, use present_and_then() and bind
62    // to Option<String> — see the README's [BAZ] example.
63    let output: String = noargs::arg("[OUTPUT]")
64        .doc("Output file path")
65        .default("out.txt")
66        .take(&mut args)
67        .then(|a| a.value().parse())?;
68
69    if let Some(help) = args.finish()? {
70        // When help is requested, finish() returns the built help text.
71        // Print it here and exit without running application logic.
72        print!("{help}");
73        return Ok(());
74    }
75
76    if dry_run {
77        println!(
78            "dry-run: verbose={verbose}, retries={retries}, endpoint={endpoint}, format={format}, timeout_secs={timeout_secs:?}, input={input}, output={output}"
79        );
80        return Ok(());
81    }
82
83    println!("processing: {input} -> {output}");
84    println!("using endpoint={endpoint}, format={format}, retries={retries}");
85    if verbose {
86        println!("verbose: timeout_secs={timeout_secs:?}");
87    }
88
89    Ok(())
90}
Source

pub const fn default(self, default: &'static str) -> Self

Updates the value of OptSpec::default.

Examples found in repository?
examples/subcommands.rs (line 68)
55fn try_run_sum(args: &mut noargs::RawArgs) -> noargs::Result<bool> {
56    if !noargs::cmd("sum")
57        .doc("Add two integers")
58        .take(args)
59        .is_present()
60    {
61        return Ok(false);
62    }
63
64    let repeat: usize = noargs::opt("repeat")
65        .short('r')
66        .ty("N")
67        .doc("Print result multiple times")
68        .default("1")
69        .take(args)
70        .then(|o| o.value().parse())?;
71    let left: i64 = noargs::arg("<LEFT>")
72        .doc("Left operand")
73        .example("3")
74        .take(args)
75        .then(|a| a.value().parse())?;
76    let right: i64 = noargs::arg("<RIGHT>")
77        .doc("Right operand")
78        .example("4")
79        .take(args)
80        .then(|a| a.value().parse())?;
81
82    if args.metadata().help_mode {
83        return Ok(true);
84    }
85
86    let total = left + right;
87    for _ in 0..repeat {
88        println!("{total}");
89    }
90    Ok(true)
91}
More examples
Hide additional examples
examples/arrays.rs (line 41)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Same-name options can be collected by calling take() in a loop.
13    let include_opt = noargs::opt("include")
14        .short('I')
15        .ty("PATH")
16        .doc("Include path (can be specified multiple times)");
17    let mut includes = Vec::<String>::new();
18    while let Some(path) = include_opt
19        .take(&mut args)
20        .present_and_then(|o| o.value().parse())?
21    {
22        includes.push(path);
23    }
24
25    let label_opt = noargs::opt("label")
26        .short('l')
27        .ty("LABEL")
28        .doc("Label value (can be specified multiple times)");
29    let mut labels = Vec::<String>::new();
30    while let Some(label) = label_opt
31        .take(&mut args)
32        .present_and_then(|o| o.value().parse())?
33    {
34        labels.push(label);
35    }
36
37    let output: String = noargs::opt("output")
38        .short('o')
39        .ty("PATH")
40        .doc("Output path")
41        .default("summary.txt")
42        .take(&mut args)
43        .then(|o| o.value().parse())?;
44
45    // Positional arrays are handled with one required argument + optional rest.
46    // Naming convention: use `<NAME>...` for required-many and `[NAME]...` for optional-many.
47    // The `<>` / `[]` / `...` markers are cosmetic (used only in help output);
48    // required-ness is enforced below: `.then()` makes the first input required,
49    // the loop with `.present_and_then()` consumes zero or more rest inputs.
50    let first_input: String = noargs::arg("<INPUT>")
51        .doc("First input (required)")
52        .example("a.txt")
53        .take(&mut args)
54        .then(|a| a.value().parse())?;
55    let rest_input_arg = noargs::arg("[INPUT]...").doc("Additional inputs");
56    let mut inputs = vec![first_input];
57    while let Some(input) = rest_input_arg
58        .take(&mut args)
59        .present_and_then(|a| a.value().parse())?
60    {
61        inputs.push(input);
62    }
63
64    if let Some(help) = args.finish()? {
65        print!("{help}");
66        return Ok(());
67    }
68
69    println!("includes={includes:?}");
70    println!("labels={labels:?}");
71    println!("inputs={inputs:?}");
72    println!("output={output}");
73    Ok(())
74}
examples/basics.rs (line 32)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Important: call flag()/opt() before arg().
13    // Otherwise values like "-v" — or any unknown "--bogus" — can be silently
14    // consumed as positional arguments.
15    //
16    // Required option / positional: set example("...") so help mode renders
17    // a meaningful Usage / Example line. Optional fields covered by default()
18    // or present_and_then() do not need example().
19    let verbose = noargs::flag("verbose")
20        .short('v')
21        .doc("Enable verbose output")
22        .take(&mut args)
23        .is_present();
24    let dry_run = noargs::flag("dry-run")
25        .doc("Print parsed values and exit without running processing")
26        .take(&mut args)
27        .is_present();
28    let retries: usize = noargs::opt("retries")
29        .short('r')
30        .ty("N")
31        .doc("How many times to retry")
32        .default("1")
33        .take(&mut args)
34        .then(|o| o.value().parse())?;
35    let endpoint: String = noargs::opt("endpoint")
36        .ty("URL")
37        .doc("Server endpoint")
38        .env("NOARGS_ENDPOINT")
39        .default("http://localhost:8080")
40        .take(&mut args)
41        .then(|o| o.value().parse())?;
42    let format: String = noargs::opt("format")
43        .ty("FORMAT")
44        .doc("Output format")
45        .example("json")
46        .take(&mut args)
47        .then(|o| o.value().parse())?;
48    let timeout_secs: Option<u64> = noargs::opt("timeout")
49        .ty("SECONDS")
50        .doc("Optional timeout in seconds")
51        .take(&mut args)
52        .present_and_then(|o| o.value().parse())?;
53
54    let input: String = noargs::arg("<INPUT>")
55        .doc("Input file path")
56        .example("input.txt")
57        .take(&mut args)
58        .then(|a| a.value().parse())?;
59    // Optional positional with default(): the value is always a String —
60    // absent uses "out.txt", present uses the given path.
61    // For "absent vs present" distinction, use present_and_then() and bind
62    // to Option<String> — see the README's [BAZ] example.
63    let output: String = noargs::arg("[OUTPUT]")
64        .doc("Output file path")
65        .default("out.txt")
66        .take(&mut args)
67        .then(|a| a.value().parse())?;
68
69    if let Some(help) = args.finish()? {
70        // When help is requested, finish() returns the built help text.
71        // Print it here and exit without running application logic.
72        print!("{help}");
73        return Ok(());
74    }
75
76    if dry_run {
77        println!(
78            "dry-run: verbose={verbose}, retries={retries}, endpoint={endpoint}, format={format}, timeout_secs={timeout_secs:?}, input={input}, output={output}"
79        );
80        return Ok(());
81    }
82
83    println!("processing: {input} -> {output}");
84    println!("using endpoint={endpoint}, format={format}, retries={retries}");
85    if verbose {
86        println!("verbose: timeout_secs={timeout_secs:?}");
87    }
88
89    Ok(())
90}
Source

pub const fn example(self, example: &'static str) -> Self

Updates the value of OptSpec::example.

Examples found in repository?
examples/basics.rs (line 45)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Important: call flag()/opt() before arg().
13    // Otherwise values like "-v" — or any unknown "--bogus" — can be silently
14    // consumed as positional arguments.
15    //
16    // Required option / positional: set example("...") so help mode renders
17    // a meaningful Usage / Example line. Optional fields covered by default()
18    // or present_and_then() do not need example().
19    let verbose = noargs::flag("verbose")
20        .short('v')
21        .doc("Enable verbose output")
22        .take(&mut args)
23        .is_present();
24    let dry_run = noargs::flag("dry-run")
25        .doc("Print parsed values and exit without running processing")
26        .take(&mut args)
27        .is_present();
28    let retries: usize = noargs::opt("retries")
29        .short('r')
30        .ty("N")
31        .doc("How many times to retry")
32        .default("1")
33        .take(&mut args)
34        .then(|o| o.value().parse())?;
35    let endpoint: String = noargs::opt("endpoint")
36        .ty("URL")
37        .doc("Server endpoint")
38        .env("NOARGS_ENDPOINT")
39        .default("http://localhost:8080")
40        .take(&mut args)
41        .then(|o| o.value().parse())?;
42    let format: String = noargs::opt("format")
43        .ty("FORMAT")
44        .doc("Output format")
45        .example("json")
46        .take(&mut args)
47        .then(|o| o.value().parse())?;
48    let timeout_secs: Option<u64> = noargs::opt("timeout")
49        .ty("SECONDS")
50        .doc("Optional timeout in seconds")
51        .take(&mut args)
52        .present_and_then(|o| o.value().parse())?;
53
54    let input: String = noargs::arg("<INPUT>")
55        .doc("Input file path")
56        .example("input.txt")
57        .take(&mut args)
58        .then(|a| a.value().parse())?;
59    // Optional positional with default(): the value is always a String —
60    // absent uses "out.txt", present uses the given path.
61    // For "absent vs present" distinction, use present_and_then() and bind
62    // to Option<String> — see the README's [BAZ] example.
63    let output: String = noargs::arg("[OUTPUT]")
64        .doc("Output file path")
65        .default("out.txt")
66        .take(&mut args)
67        .then(|a| a.value().parse())?;
68
69    if let Some(help) = args.finish()? {
70        // When help is requested, finish() returns the built help text.
71        // Print it here and exit without running application logic.
72        print!("{help}");
73        return Ok(());
74    }
75
76    if dry_run {
77        println!(
78            "dry-run: verbose={verbose}, retries={retries}, endpoint={endpoint}, format={format}, timeout_secs={timeout_secs:?}, input={input}, output={output}"
79        );
80        return Ok(());
81    }
82
83    println!("processing: {input} -> {output}");
84    println!("using endpoint={endpoint}, format={format}, retries={retries}");
85    if verbose {
86        println!("verbose: timeout_secs={timeout_secs:?}");
87    }
88
89    Ok(())
90}
Source

pub fn take(self, args: &mut RawArgs) -> Opt

Takes the first Opt instance that satisfies this specification from the raw arguments.

Examples found in repository?
examples/subcommands.rs (line 69)
55fn try_run_sum(args: &mut noargs::RawArgs) -> noargs::Result<bool> {
56    if !noargs::cmd("sum")
57        .doc("Add two integers")
58        .take(args)
59        .is_present()
60    {
61        return Ok(false);
62    }
63
64    let repeat: usize = noargs::opt("repeat")
65        .short('r')
66        .ty("N")
67        .doc("Print result multiple times")
68        .default("1")
69        .take(args)
70        .then(|o| o.value().parse())?;
71    let left: i64 = noargs::arg("<LEFT>")
72        .doc("Left operand")
73        .example("3")
74        .take(args)
75        .then(|a| a.value().parse())?;
76    let right: i64 = noargs::arg("<RIGHT>")
77        .doc("Right operand")
78        .example("4")
79        .take(args)
80        .then(|a| a.value().parse())?;
81
82    if args.metadata().help_mode {
83        return Ok(true);
84    }
85
86    let total = left + right;
87    for _ in 0..repeat {
88        println!("{total}");
89    }
90    Ok(true)
91}
More examples
Hide additional examples
examples/arrays.rs (line 19)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Same-name options can be collected by calling take() in a loop.
13    let include_opt = noargs::opt("include")
14        .short('I')
15        .ty("PATH")
16        .doc("Include path (can be specified multiple times)");
17    let mut includes = Vec::<String>::new();
18    while let Some(path) = include_opt
19        .take(&mut args)
20        .present_and_then(|o| o.value().parse())?
21    {
22        includes.push(path);
23    }
24
25    let label_opt = noargs::opt("label")
26        .short('l')
27        .ty("LABEL")
28        .doc("Label value (can be specified multiple times)");
29    let mut labels = Vec::<String>::new();
30    while let Some(label) = label_opt
31        .take(&mut args)
32        .present_and_then(|o| o.value().parse())?
33    {
34        labels.push(label);
35    }
36
37    let output: String = noargs::opt("output")
38        .short('o')
39        .ty("PATH")
40        .doc("Output path")
41        .default("summary.txt")
42        .take(&mut args)
43        .then(|o| o.value().parse())?;
44
45    // Positional arrays are handled with one required argument + optional rest.
46    // Naming convention: use `<NAME>...` for required-many and `[NAME]...` for optional-many.
47    // The `<>` / `[]` / `...` markers are cosmetic (used only in help output);
48    // required-ness is enforced below: `.then()` makes the first input required,
49    // the loop with `.present_and_then()` consumes zero or more rest inputs.
50    let first_input: String = noargs::arg("<INPUT>")
51        .doc("First input (required)")
52        .example("a.txt")
53        .take(&mut args)
54        .then(|a| a.value().parse())?;
55    let rest_input_arg = noargs::arg("[INPUT]...").doc("Additional inputs");
56    let mut inputs = vec![first_input];
57    while let Some(input) = rest_input_arg
58        .take(&mut args)
59        .present_and_then(|a| a.value().parse())?
60    {
61        inputs.push(input);
62    }
63
64    if let Some(help) = args.finish()? {
65        print!("{help}");
66        return Ok(());
67    }
68
69    println!("includes={includes:?}");
70    println!("labels={labels:?}");
71    println!("inputs={inputs:?}");
72    println!("output={output}");
73    Ok(())
74}
examples/basics.rs (line 33)
1fn main() -> noargs::Result<()> {
2    let mut args = noargs::raw_args();
3    args.metadata_mut().app_name = env!("CARGO_PKG_NAME");
4    args.metadata_mut().app_description = env!("CARGO_PKG_DESCRIPTION");
5
6    if noargs::VERSION_FLAG.take(&mut args).is_present() {
7        println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
8        return Ok(());
9    }
10    noargs::HELP_FLAG.take_help(&mut args);
11
12    // Important: call flag()/opt() before arg().
13    // Otherwise values like "-v" — or any unknown "--bogus" — can be silently
14    // consumed as positional arguments.
15    //
16    // Required option / positional: set example("...") so help mode renders
17    // a meaningful Usage / Example line. Optional fields covered by default()
18    // or present_and_then() do not need example().
19    let verbose = noargs::flag("verbose")
20        .short('v')
21        .doc("Enable verbose output")
22        .take(&mut args)
23        .is_present();
24    let dry_run = noargs::flag("dry-run")
25        .doc("Print parsed values and exit without running processing")
26        .take(&mut args)
27        .is_present();
28    let retries: usize = noargs::opt("retries")
29        .short('r')
30        .ty("N")
31        .doc("How many times to retry")
32        .default("1")
33        .take(&mut args)
34        .then(|o| o.value().parse())?;
35    let endpoint: String = noargs::opt("endpoint")
36        .ty("URL")
37        .doc("Server endpoint")
38        .env("NOARGS_ENDPOINT")
39        .default("http://localhost:8080")
40        .take(&mut args)
41        .then(|o| o.value().parse())?;
42    let format: String = noargs::opt("format")
43        .ty("FORMAT")
44        .doc("Output format")
45        .example("json")
46        .take(&mut args)
47        .then(|o| o.value().parse())?;
48    let timeout_secs: Option<u64> = noargs::opt("timeout")
49        .ty("SECONDS")
50        .doc("Optional timeout in seconds")
51        .take(&mut args)
52        .present_and_then(|o| o.value().parse())?;
53
54    let input: String = noargs::arg("<INPUT>")
55        .doc("Input file path")
56        .example("input.txt")
57        .take(&mut args)
58        .then(|a| a.value().parse())?;
59    // Optional positional with default(): the value is always a String —
60    // absent uses "out.txt", present uses the given path.
61    // For "absent vs present" distinction, use present_and_then() and bind
62    // to Option<String> — see the README's [BAZ] example.
63    let output: String = noargs::arg("[OUTPUT]")
64        .doc("Output file path")
65        .default("out.txt")
66        .take(&mut args)
67        .then(|a| a.value().parse())?;
68
69    if let Some(help) = args.finish()? {
70        // When help is requested, finish() returns the built help text.
71        // Print it here and exit without running application logic.
72        print!("{help}");
73        return Ok(());
74    }
75
76    if dry_run {
77        println!(
78            "dry-run: verbose={verbose}, retries={retries}, endpoint={endpoint}, format={format}, timeout_secs={timeout_secs:?}, input={input}, output={output}"
79        );
80        return Ok(());
81    }
82
83    println!("processing: {input} -> {output}");
84    println!("using endpoint={endpoint}, format={format}, retries={retries}");
85    if verbose {
86        println!("verbose: timeout_secs={timeout_secs:?}");
87    }
88
89    Ok(())
90}

Trait Implementations§

Source§

impl Clone for OptSpec

Source§

fn clone(&self) -> OptSpec

Returns a duplicate of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for OptSpec

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for OptSpec

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl Hash for OptSpec

Source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl PartialEq for OptSpec

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

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

impl Copy for OptSpec

Source§

impl Eq for OptSpec

Source§

impl StructuralPartialEq for OptSpec

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.