Lexopt

https://docs.rs/lexopt/0.3.2
Admin
Lexopt is a pathologically simple command line argument parser that provides a stream of options and...
Tokens:35,733
Snippets:209
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Handling subcommands and global settings

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Example of a main loop handling subcommands and a specific install command implementation.

```rust
                std::process::exit(0);
            }
            Value(value) => {
                let value = value.string()?;
                match value.as_str() {
                    value if value.starts_with('+') => {
                        settings.toolchain = value[1..].to_owned();
                    }
                    "install" => {
                        return install(settings, parser);
                    }
                    value => {
                        return Err(format!("unknown subcommand '{}'", value).into());
                    }
                }
            }
            _ => return Err(arg.unexpected()),
        }
    }

    println!("{}", HELP);
    Ok(())
}

#[derive(Debug)]
struct GlobalSettings {
    toolchain: String,
    color: Color,
    offline: bool,
    quiet: bool,
    verbose: bool,
}

fn install(settings: GlobalSettings, mut parser: lexopt::Parser) -> Result<(), lexopt::Error> {
    use lexopt::prelude::*;

    let mut package: Option<String> = None;
    let mut root: Option<PathBuf> = None;
    let mut jobs: u16 = get_no_of_cpus();

    while let Some(arg) = parser.next()? {
        match arg {
            Value(value) if package.is_none() => {
                package = Some(value.string()?);
            }
            Long("root") => {
                root = Some(parser.value()?.into());
            }
            Short('j') | Long("jobs") => {
                jobs = parser.value()?.parse()?;
            }
            Long("help") => {
                println!("cargo install [OPTIONS] CRATE");
                std::process::exit(0);
            }
            _ => return Err(arg.unexpected()),
        }
    }

    println!("Settings: {:#?}", settings);
    println!(
        "Installing {} into {:?} with {} jobs",
        package.ok_or("missing CRATE argument")?,
        root,
        jobs
    );

    Ok(())
```

--------------------------------

### Install Package with Options

Source: https://docs.rs/lexopt/0.3.2/lexopt/enum.Arg.html

Parses arguments for the 'install' subcommand, including package name, root directory, and number of jobs. Requires lexopt::Parser and GlobalSettings.

```rust
let mut package: Option<String> = None;
    let mut root: Option<PathBuf> = None;
    let mut jobs: u16 = get_no_of_cpus();

    while let Some(arg) = parser.next()? {
        match arg {
            Value(value) if package.is_none() => {
                package = Some(value.string()?);
            }
            Long("root") => {
                root = Some(parser.value()?.into());
            }
            Short('j') | Long("jobs") => {
                jobs = parser.value()?.parse()?;
            }
            Long("help") => {
                println!("cargo install [OPTIONS] CRATE");
                std::process::exit(0);
            }
            _ => return Err(arg.unexpected()),
        }
    }

    println!("Settings: {:#?}", settings);
    println!(
        "Installing {} into {:?} with {} jobs",
        package.ok_or("missing CRATE argument")?,
        root,
        jobs
    );

    Ok(())
}
```

--------------------------------

### Install Subcommand Logic with lexopt

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Implements the 'install' subcommand, parsing specific options like '--root' and '--jobs', and collecting the package name. This is useful for commands that require additional parameters beyond the subcommand itself.

```rust
fn install(settings: GlobalSettings, mut parser: lexopt::Parser) -> Result<(), lexopt::Error> {
    use lexopt::prelude::*;

    let mut package: Option<String> = None;
    let mut root: Option<PathBuf> = None;
    let mut jobs: u16 = get_no_of_cpus();

    while let Some(arg) = parser.next()? {
        match arg {
            Value(value) if package.is_none() => {
                package = Some(value.string()?);
            }
            Long("root") => {
                root = Some(parser.value()?.into());
            }
            Short('j') | Long("jobs") => {
                jobs = parser.value()?.parse()?;
            }
            Long("help") => {
                println!("cargo install [OPTIONS] CRATE");
                std::process::exit(0);
            }
            _ => return Err(arg.unexpected()),
        }
    }

    println!("Settings: {:#?}", settings);
    println!(
        "Installing {} into {:?} with {} jobs",
        package.ok_or("missing CRATE argument")?,
        root,
        jobs
    );

    Ok(())
}
```

--------------------------------

### Implement Cargo-like CLI with lexopt

Source: https://docs.rs/lexopt/0.3.2/src/cargo/cargo.rs.html

This example demonstrates how to handle global settings, subcommands, and custom argument parsing using lexopt.

```rust
1//! A very partial unfaithful implementation of cargo's command line.
2//!
3//! This showcases some hairier patterns, like subcommands and custom value parsing.
4
5use std::{path::PathBuf, str::FromStr};
6
7const HELP: &str = "cargo [+toolchain] [OPTIONS] [SUBCOMMAND]";
8
9fn main() -> Result<(), lexopt::Error> {
10    use lexopt::prelude::*;
11
12    let mut settings = GlobalSettings {
13        toolchain: "stable".to_owned(),
14        color: Color::Auto,
15        offline: false,
16        quiet: false,
17        verbose: false,
18    };
19
20    let mut parser = lexopt::Parser::from_env();
21    while let Some(arg) = parser.next()? {
22        match arg {
23            Long("color") => {
24                settings.color = parser.value()?.parse()?;
25            }
26            Long("offline") => {
27                settings.offline = true;
28            }
29            Long("quiet") => {
30                settings.quiet = true;
31                settings.verbose = false;
32            }
33            Long("verbose") => {
34                settings.verbose = true;
35                settings.quiet = false;
36            }
37            Long("help") => {
38                println!("{}", HELP);
39                std::process::exit(0);
40            }
41            Value(value) => {
42                let value = value.string()?;
43                match value.as_str() {
44                    value if value.starts_with('+') => {
45                        settings.toolchain = value[1..].to_owned();
46                    }
47                    "install" => {
48                        return install(settings, parser);
49                    }
50                    value => {
51                        return Err(format!("unknown subcommand '{}'", value).into());
52                    }
53                }
54            }
55            _ => return Err(arg.unexpected()),
56        }
57    }
58
59    println!("{}", HELP);
60    Ok(())
61}
62
63#[derive(Debug)]
64struct GlobalSettings {
65    toolchain: String,
66    color: Color,
67    offline: bool,
68    quiet: bool,
69    verbose: bool,
70}
71
72fn install(settings: GlobalSettings, mut parser: lexopt::Parser) -> Result<(), lexopt::Error> {
73    use lexopt::prelude::*;
74
75    let mut package: Option<String> = None;
76    let mut root: Option<PathBuf> = None;
77    let mut jobs: u16 = get_no_of_cpus();
78
79    while let Some(arg) = parser.next()? {
80        match arg {
81            Value(value) if package.is_none() => {
82                package = Some(value.string()?);
83            }
84            Long("root") => {
85                root = Some(parser.value()?.into());
86            }
87            Short('j') | Long("jobs") => {
88                jobs = parser.value()?.parse()?;
89            }
90            Long("help") => {
91                println!("cargo install [OPTIONS] CRATE");
92                std::process::exit(0);
93            }
94            _ => return Err(arg.unexpected()),
95        }
96    }
97
98    println!("Settings: {:#?}", settings);
99    println!(
100        "Installing {} into {:?} with {} jobs",
101        package.ok_or("missing CRATE argument")?,
102        root,
103        jobs
104    );
105
106    Ok(())
107}
108
109#[derive(Debug)]
110enum Color {
111    Auto,
112    Always,
113    Never,
114}
115
116// clap has a macro for this: https://docs.rs/clap/2.33.3/clap/macro.arg_enum.html
117// We have to do it manually.
118impl FromStr for Color {
119    type Err = String;
120
121    fn from_str(s: &str) -> Result<Self, Self::Err> {
122        match s.to_lowercase().as_str() {
123            "auto" => Ok(Color::Auto),
124            "always" => Ok(Color::Always),
125            "never" => Ok(Color::Never),
126            _ => Err(format!(
127                "Invalid style '{}' [pick from: auto, always, never]",
128                s
129            )),
130        }
131    }
132}
133
134fn get_no_of_cpus() -> u16 {
135    4
136}
```

--------------------------------

### Handle Subcommands and Toolchain Settings

Source: https://docs.rs/lexopt/0.3.2/lexopt/enum.Arg.html

Parses command-line arguments to handle subcommands like 'install' and set the toolchain. Requires lexopt::Parser.

```rust
std::process::exit(0);
            }
            Value(value) => {
                let value = value.string()?;
                match value.as_str() {
                    value if value.starts_with('+') => {
                        settings.toolchain = value[1..].to_owned();
                    }
                    "install" => {
                        return install(settings, parser);
                    }
                    value => {
                        return Err(format!("unknown subcommand '{}'", value).into());
                    }
                }
            }
            _ => return Err(arg.unexpected()),
        }
    }

    println!("{}", HELP);
    Ok(())
}
```

--------------------------------

### Lexopt Argument Parsing Example

Source: https://docs.rs/lexopt/0.3.2/lexopt

This example demonstrates how to use the lexopt crate to parse command-line arguments. It defines a struct for expected arguments, initializes a parser from the environment, and iterates through arguments to populate the struct. It also shows how to handle different argument types (options with values, flags, positional arguments) and custom error handling.

```APIDOC
## Rust - Lexopt Argument Parsing Example

### Description
This example showcases a practical implementation of the `lexopt` crate for parsing command-line arguments in a Rust application. It defines a `Args` struct to hold parsed arguments, uses `lexopt::Parser::from_env()` to initialize the parser, and iterates through arguments using `parser.next()?`.

It demonstrates matching on `Short` and `Long` options, retrieving option values with `parser.value()`, handling positional arguments with `Value`, and managing unexpected arguments with `arg.unexpected()`.

### Method
N/A (This is a code example, not an API endpoint)

### Endpoint
N/A (This is a code example, not an API endpoint)

### Parameters
N/A (This is a code example, not an API endpoint)

### Request Example
```rust
struct Args {
    thing: String,
    number: u32,
    shout: bool,
}

fn parse_args() -> Result<Args, lexopt::Error> {
    use lexopt::prelude::*;

    let mut thing = None;
    let mut number = 1;
    let mut shout = false;
    let mut parser = lexopt::Parser::from_env();

    while let Some(arg) = parser.next()? {
        match arg {
            Short('n') | Long("number") => {
                number = parser.value()?.parse()?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.string()?);
            }
            Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            _ => return Err(arg.unexpected()),
        }
    }

    Ok(Args {
        thing: thing.ok_or("missing argument THING")?,
        number,
        shout,
    })
}

fn main() -> Result<(), lexopt::Error> {
    let args = parse_args()?;
    let mut message = format!("Hello {}", args.thing);
    if args.shout {
        message = message.to_uppercase();
    }
    for _ in 0..args.number {
        println!("{}", message);
    }
    Ok(())
}
```

### Response
N/A (This is a code example, not an API endpoint)

### Response Example
N/A (This is a code example, not an API endpoint)
```

--------------------------------

### Call a library function

Source: https://docs.rs/lexopt/0.3.2/scrape-examples-help.html

Example of calling a library function within an external example file.

```rust
// examples/ex.rs
fn main() {
  a_crate::a_func();
}
```

--------------------------------

### Handle Subcommands with lexopt

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Parses arguments to determine subcommands like 'install' or to set global settings such as the toolchain. Use this when your application has distinct operational modes triggered by specific keywords.

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut settings = GlobalSettings {
        toolchain: "stable".to_owned(),
        color: Color::Auto,
        offline: false,
        quiet: false,
        verbose: false,
    };
    let mut parser = lexopt::Parser::from_env().unwrap();

    while let Some(arg) = parser.next()? {
        match arg {
            Ok(arg) => match arg {
                Long("help") => {
                    println!("{}", HELP);
                    std::process::exit(0);
                }
                Value(value) => {
                    let value = value.string()?;
                    match value.as_str() {
                        value if value.starts_with('+') => {
                            settings.toolchain = value[1..].to_owned();
                        }
                        "install" => {
                            return install(settings, parser);
                        }
                        value => {
                            return Err(format!("unknown subcommand '{}'", value).into());
                        }
                    }
                }
                _ => return Err(arg.unexpected()),
            },
            Err(err) => return Err(err.into()),
        }
    }

    println!("{}", HELP);
    Ok(())
}
```

--------------------------------

### Define a public function

Source: https://docs.rs/lexopt/0.3.2/scrape-examples-help.html

Example of a public function definition in a library source file.

```rust
// src/lib.rs
pub fn a_func() {}
```

--------------------------------

### Get Next Argument with lexopt Parser

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Retrieves the next command line argument. Returns `Ok(None)` when parsing is complete. Handles invalid UTF-8 by replacing characters.

```rust
pub fn next(&mut self) -> Result<Option<Arg<'_>>, Error>
```

--------------------------------

### Get Next Command Line Argument

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

Implement the `next` method for the `Parser` to retrieve the subsequent command-line argument. It returns `Ok(None)` when parsing is complete. Handles errors like `UnexpectedValue` for options with unconsumed values.

```rust
pub fn next(&mut self) -> Result<Option<Arg<'_>>, Error> {
        match self.state {
            State::PendingValue(ref mut value) => {
                // Last time we got `--long=value`, and `value` hasn't been used.
                let value = replace(value, OsString::new());
                self.state = State::None;
                return Err(Error::UnexpectedValue {
                    option: self
                        .format_last_option()
                        .expect("Should only have pending value after long option"),
                    value,
                });
            }
            State::Shorts(ref arg, ref mut pos) => {
                // We're somewhere inside a -abc chain. Because we're in .next(),
                // not .value(), we can assume that the next character is another option.
                match first_codepoint(&arg[*pos..]) {
                    Ok(None) => {
                        self.state = State::None;
                    }
                    // If we find "-=[...]" we interpret it as an option.
                    // If we find "-o=..." then there's an unexpected value.
                    // ('-=' as an option exists, see https://linux.die.net/man/1/a2ps.
                    // Though if you have one you should maybe disable short_equals.)
                    // clap always interprets it as a short flag in this case, but
                    // that feels sloppy.
                    Ok(Some('=')) if *pos > 1 && self.short_equals => {
                        return Err(Error::UnexpectedValue {
                            option: self.format_last_option().unwrap(),
                            value: self.optional_value().unwrap(),
                        });
                    }
                    Ok(Some(ch)) => {
                        *pos += ch.len_utf8();
                        self.last_option = LastOption::Short(ch);
                        return Ok(Some(Arg::Short(ch)));
                    }
                    Err(err) => {
                        // Advancing may allow recovery.
                        // This is a little iffy, there might be more bad unicode next.
                        match err.error_len() {
                            Some(len) => *pos += len,
                            None => *pos = arg.len(),
                        }
                        self.last_option = LastOption::Short('');
                        return Ok(Some(Arg::Short('')));
                    }
                }
            }
            #[cfg(windows)]
            State::ShortsU16(ref arg, ref mut pos) => match first_utf16_codepoint(&arg[*pos..]) {
                Ok(None) => {
                    self.state = State::None;
                }
                Ok(Some('=')) if *pos > 1 && self.short_equals => {
                    return Err(Error::UnexpectedValue {
                        option: self.format_last_option().unwrap(),
                        value: self.optional_value().unwrap(),
                    });
                }
                Ok(Some(ch)) => {
                    *pos += ch.len_utf16();
                    self.last_option = LastOption::Short(ch);
                    return Ok(Some(Arg::Short(ch)));
                }
                Err(_) => {
                    *pos += 1;
                    self.last_option = LastOption::Short('');
                    return Ok(Some(Arg::Short('')));
                }
            },
            State::FinishedOpts => {
                return Ok(self.source.next().map(Arg::Value));
            }
            State::None => (),
        }

        match self.state {

```

--------------------------------

### lexopt::prelude Usage

Source: https://docs.rs/lexopt/0.3.2/lexopt/prelude/index.html

Demonstrates how to import and use the lexopt prelude within a function to simplify argument parsing syntax.

```APIDOC
## lexopt::prelude

### Description
The prelude provides convenient access to `Short`, `Long`, and `Value` types without requiring the `Arg` prefix, and adds helper methods to `OsString`.

### Usage
It is recommended to import the prelude inside the function scope rather than the module scope.

### Example
```rust
fn parse_args() -> Result<Args, lexopt::Error> {
    use lexopt::prelude::*;
    // ...
}
```

### Re-exports
- **ValueExt**: Re-exported from `super::ValueExt`
- **Arg variants**: All variants of `super::Arg` are re-exported for direct use.
```

--------------------------------

### from_env

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Initializes a new Parser instance by reading arguments from the environment using std::env::args_os. This is the standard method for creating a parser.

```APIDOC
## POST /from_env

### Description
Create a parser from the environment using `std::env::args_os`. This is the usual way to create a `Parser`.

### Method
POST

### Endpoint
/from_env

### Parameters
None

### Request Example
```json
{
  "message": "No request body needed for from_env"
}
```

### Response
#### Success Response (200)
- **Parser** (Parser) - A new parser instance initialized from environment arguments.

#### Response Example
```json
{
  "parser": {
    "type": "Parser"
  }
}
```
```

--------------------------------

### Parser Initialization Methods

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

Methods for creating a new Parser instance from different input sources.

```APIDOC
## Parser::from_env

### Description
Creates a parser from the environment using std::env::args_os.

### Method
Static Method

### Parameters
None

## Parser::from_iter

### Description
Creates a parser from an iterator. The first item from the iterator must be the binary name.

### Method
Static Method

### Parameters
- **args** (IntoIterator) - Required - An iterator of items that can be converted to OsString.

## Parser::from_args

### Description
Creates a parser from an iterator that does not include the binary name.

### Method
Static Method

### Parameters
- **args** (IntoIterator) - Required - An iterator of items that can be converted to OsString.
```

--------------------------------

### Configure Short Option Equals Parsing

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Controls whether equals signs are parsed for short options. Disabling this is useful when option values may start with an equals sign.

```rust
let mut parser = lexopt::Parser::from_env();
parser.set_short_equals(false);
```

```rust
Short('d') | Long("delimiter") => {
    parser.set_short_equals(false);
    delimiter = Some(parser.value()?.string()?);
    parser.set_short_equals(true);
}
```

--------------------------------

### Manage global application settings

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Shows how to update a configuration struct based on parsed flags.

```rust
9fn main() -> Result<(), lexopt::Error> {
10    use lexopt::prelude::*;
11
12    let mut settings = GlobalSettings {
13        toolchain: "stable".to_owned(),
14        color: Color::Auto,
15        offline: false,
16        quiet: false,
17        verbose: false,
18    };
19
20    let mut parser = lexopt::Parser::from_env();
21    while let Some(arg) = parser.next()? {
22        match arg {
23            Long("color") => {
24                settings.color = parser.value()?.parse()?;
25            }
26            Long("offline") => {
27                settings.offline = true;
28            }
29            Long("quiet") => {
30                settings.quiet = true;
31                settings.verbose = false;
32            }
33            Long("verbose") => {
34                settings.verbose = true;
35                settings.quiet = false;
36            }
37            Long("help") => {
38                println!("{}", HELP);
```

--------------------------------

### Custom Parsing with `parse_with` in Rust

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

Demonstrates using `parse_with` for custom argument parsing logic. This is useful when the default parsing behavior is insufficient. The example shows how to handle specific string inputs and return custom errors.

```rust
s.parse_with(|s| match s {
                "-10" => Ok(0),
                _ => Err("bad"),
            })?,
            0,
        );
        assert_eq!(
            s.parse::<u32>().unwrap_err().to_string(),
            r#"cannot parse argument "-10": invalid digit found in string"#,
        );
        assert_eq!(
            s.parse_with(|s| match s {
                "11" => Ok(0_i32),
                _ => Err("bad"),
            })
            .unwrap_err()
            .to_string(),
            r#"cannot parse argument "-10": bad"#,
        );
        assert_eq!(s.string()?, "-10");
```

--------------------------------

### Importing the lexopt prelude

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

The prelude should be imported inside a function scope to provide access to Short, Long, and Value types without prefixes.

```rust
fn parse_args() -> Result<Args, lexopt::Error> {
    use lexopt::prelude::*;
    // ...
    Ok(Args)
}
```

--------------------------------

### Create Parser from Environment Arguments

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

Use this method to create a Parser instance from the command-line arguments provided in the environment. It automatically handles the binary name and subsequent arguments.

```rust
let mut source = make_iter(std::env::args_os());
Parser::new(source.next(), source)
```

--------------------------------

### Parse Command-Line Arguments with lexopt

Source: https://docs.rs/lexopt/0.3.2/src/hello/hello.rs.html

Defines a struct for arguments and parses them from the environment using lexopt. Handles short and long options, values, and help commands. Requires the lexopt crate.

```rust
struct Args {
    thing: String,
    number: u32,
    shout: bool,
}

fn parse_args() -> Result<Args, lexopt::Error> {
    use lexopt::prelude::*;

    let mut thing = None;
    let mut number = 1;
    let mut shout = false;
    let mut parser = lexopt::Parser::from_env();
    while let Some(arg) = parser.next()? {
        match arg {
            Short('n') | Long("number") => {
                number = parser.value()?.parse()?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.string()?);
            }
            Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            _ => return Err(arg.unexpected()),
        }
    }

    Ok(Args {
        thing: thing.ok_or("missing argument THING")?,
        number,
        shout,
    })
}

fn main() -> Result<(), lexopt::Error> {
    let args = parse_args()?;
    let mut message = format!("Hello {}", args.thing);
    if args.shout {
        message = message.to_uppercase();
    }
    for _ in 0..args.number {
        println!("{}", message);
    }
    Ok(())
}
```

--------------------------------

### Implement POSIX-compliant argument parsing

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Demonstrates disabling short-equals parsing and handling raw arguments for a POSIX-style CLI.

```rust
17fn main() -> Result<(), lexopt::Error> {
18    use lexopt::prelude::*;
19
20    let mut parser = lexopt::Parser::from_env();
21    parser.set_short_equals(false);
22    let mut free = Vec::new();
23    while let Some(arg) = parser.next()? {
24        match arg {
25            Short('n') | Long("number") => {
26                let num: u16 = parser.value()?.parse()?;
27                println!("Got number {}", num);
28            }
29            Long("shout") => {
30                println!("Got --shout");
31            }
32            Value(val) => {
33                free.push(val);
34                free.extend(parser.raw_args()?);
35            }
36            _ => return Err(arg.unexpected()),
37        }
38    }
39    println!("Got free args {:?}", free);
40    Ok(())
41}
```

--------------------------------

### Consuming raw arguments with raw_args()

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Shows how to consume remaining command-line arguments as-is after encountering a free-standing argument.

```rust
Value(prog) => {
    let args: Vec<_> = parser.raw_args()?.collect();
    let command = std::process::Command::new(prog).args(args);
}
```

--------------------------------

### Parse arguments with values

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

Demonstrates parsing arguments that expect values, including cases with and without spaces between the option and its value.

```Rust
let mut p = parse(case);
            p.next()?.unwrap();
            let mut iter = p.values()?;
            let values: Vec<_> = iter.by_ref().collect();
            assert_eq!(values, &["b", "c", "d"]);
            assert!(iter.next().is_none());
            assert!(p.next()?.is_none());
```

```Rust
let mut p = parse(case);
            p.next()?.unwrap();
            let mut iter = p.values()?;
            let values: Vec<_> = iter.by_ref().collect();
            assert_eq!(values, &["b"]);
            assert!(iter.next().is_none());
            assert_eq!(p.next()?.unwrap(), Value("c".into()));
            assert!(p.next()?.is_none());
```

```Rust
let mut p = parse(case);
            p.next()?.unwrap();
            assert!(p.values().is_err());
            assert!(p.next().is_ok());
            assert!(p.next().unwrap().is_none());
```

```Rust
let mut p = parse(case);
            p.next()?.unwrap();
            let mut iter = p.values()?;
            let values: Vec<_> = iter.by_ref().collect();
            assert_eq!(values, &[""]);
            assert!(iter.next().is_none());
            assert!(p.next()?.is_none());
```

```Rust
let mut p = parse(case);
            p.next()?.unwrap();
            assert!(p.values().is_ok());
            assert_eq!(p.value()?, "b");
```

```Rust
let mut p = parse("-ab");
            p.next()?.unwrap();
            assert!(p.values().is_ok());
            assert_eq!(p.next()?.unwrap(), Short('b'));
```

--------------------------------

### Manage global application settings

Source: https://docs.rs/lexopt/0.3.2/lexopt/enum.Arg.html

Updates a configuration struct based on parsed flags and handles mutually exclusive options.

```rust
fn main() -> Result<(), lexopt::Error> {
    use lexopt::prelude::*;

    let mut settings = GlobalSettings {
        toolchain: "stable".to_owned(),
        color: Color::Auto,
        offline: false,
        quiet: false,
        verbose: false,
    };

    let mut parser = lexopt::Parser::from_env();
    while let Some(arg) = parser.next()? {
        match arg {
            Long("color") => {
                settings.color = parser.value()?.parse()?;
            }
            Long("offline") => {
                settings.offline = true;
            }
            Long("quiet") => {
                settings.quiet = true;
                settings.verbose = false;
            }
            Long("verbose") => {
                settings.verbose = true;
                settings.quiet = false;
            }
            Long("help") => {
                println!("{}", HELP);
```

--------------------------------

### Handle non-standard argument patterns

Source: https://docs.rs/lexopt/0.3.2/lexopt/enum.Arg.html

Demonstrates integrating custom parsing logic alongside standard lexopt argument iteration.

```rust
fn main() -> Result<(), lexopt::Error> {
    use lexopt::prelude::*;

    let mut parser = lexopt::Parser::from_env();
    loop {
        if let Some(num) = parse_dashnum(&mut parser) {
            println!("Got number {}", num);
        } else if let Some(arg) = parser.next()? {
            match arg {
                Short('f') | Long("follow") => {
                    println!("Got --follow");
                }
                Short('n') | Long("number") => {
                    let num: u64 = parser.value()?.parse()?;
                    println!("Got number {}", num);
                }
                Value(path) => {
                    let path = PathBuf::from(path);
                    println!("Got file {}", path.display());
                }
                _ => return Err(arg.unexpected()),
            }
        } else {
            break;
        }
    }

    Ok(())
}
```

--------------------------------

### Parser - next() Method

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Retrieves the next command-line argument (option or positional). Handles argument parsing and potential errors.

```APIDOC
## GET /parser/next

### Description
Get the next option or positional argument from the command line.

### Method
GET

### Endpoint
/parser/next

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **Result** (Result<Option<Arg<'_>>, Error>) - An enum indicating success or failure. `Ok(Some(Arg))` contains the next argument, `Ok(None)` indicates no more arguments, and `Err(Error)` indicates a parsing error.

#### Response Example
```json
{
  "result": {
    "Ok": {
      "Some": {
        "kind": "Option",
        "name": "--verbose",
        "value": null
      }
    }
  }
}
```

### Errors
- **Error::UnexpectedValue**: Returned if the last option had a value that hasn’t been consumed, as in `--option=value` or `-o=value`.
```

--------------------------------

### Implement Argument Parsing with lexopt

Source: https://docs.rs/lexopt/0.3.2/src/pico_test_app/pico_test_app.rs.html

Uses a loop with lexopt::Parser to process command-line arguments and map them to a struct. Requires the lexopt crate and handles both short and long flag variants.

```rust
1#![allow(dead_code)]
2//! pico-args implements this program for a number of argument parsers:
3//! https://github.com/RazrFalcon/pico-args/tree/master/test-apps
4//!
5//! It's a nice reference point.
6//!
7//! I release this implementation into the public domain. Feel free to copy.
8
9const HELP: &str = "\
10USAGE: app [OPTIONS] --number NUMBER INPUT
11
12OPTIONS:
13  --number NUMBER       Set a number (required)
14  --opt-number NUMBER   Set an optional number
15  --width WIDTH         Set a width (non-zero, default 10)
16
17ARGS:
18  <INPUT>               Input file
19";
20
21#[derive(Debug)]
22struct AppArgs {
23    number: u32,
24    opt_number: Option<u32>,
25    width: u32,
26    input: std::path::PathBuf,
27}
28
29fn parse_width(s: &str) -> Result<u32, String> {
30    let w = s.parse().map_err(|_| "not a number")?;
31    if w != 0 {
32        Ok(w)
33    } else {
34        Err("width must be positive".to_string())
35    }
36}
37
38fn main() {
39    let args = match parse_args() {
40        Ok(args) => args,
41        Err(err) => {
42            eprintln!("Error: {}.", err);
43            std::process::exit(1);
44        }
45    };
46    println!("{:#?}", args);
47}
48
49fn parse_args() -> Result<AppArgs, lexopt::Error> {
50    use lexopt::prelude::*;
51
52    let mut number = None;
53    let mut opt_number = None;
54    let mut width = 10;
55    let mut input = None;
56
57    let mut parser = lexopt::Parser::from_env();
58    while let Some(arg) = parser.next()? {
59        match arg {
60            Short('h') | Long("help") => {
61                print!("{}", HELP);
62                std::process::exit(0);
63            }
64            Long("number") => number = Some(parser.value()?.parse()?),
65            Long("opt-number") => opt_number = Some(parser.value()?.parse()?),
66            Long("width") => width = parser.value()?.parse_with(parse_width)?,
67            Value(path) if input.is_none() => input = Some(path.into()),
68            _ => return Err(arg.unexpected()),
69        }
70    }
71    Ok(AppArgs {
72        number: number.ok_or("missing required option --number")?,
73        opt_number,
74        width,
75        input: input.ok_or("missing required argument INPUT")?,
76    })
77}
```

--------------------------------

### Analyzing First Codepoint in Byte Slices (Rust)

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

Demonstrates the `first_codepoint` function for analyzing the first Unicode codepoint in a byte slice. It handles valid UTF-8 sequences, invalid sequences, and returns `None` for empty slices.

```rust
assert_eq!(first_codepoint(b"foo").unwrap(), Some('f'));
        assert_eq!(first_codepoint(b""
).unwrap(), None);
        assert_eq!(first_codepoint(b"f\xFF\xFF").unwrap(), Some('f'));
        assert_eq!(first_codepoint(b"\xC2\xB5bar").unwrap(), Some('µ'));
        assert_eq!(first_codepoint(b"foo\xC2\xB5").unwrap(), Some('f'));
        assert_eq!(
            first_codepoint(b"\xFF\xFF").unwrap_err().error_len(),
            Some(1)
        );
        assert_eq!(first_codepoint(b"\xC2").unwrap_err().error_len(), None);
        assert_eq!(first_codepoint(b"\xC2a").unwrap_err().error_len(), Some(1));
        assert_eq!(first_codepoint(b"\xF0").unwrap_err().error_len(), None);
        assert_eq!(
            first_codepoint(b"\xF0\x9D\x84").unwrap_err().error_len(),
            None
        );
        assert_eq!(
            first_codepoint(b"\xF0\x9Da").unwrap_err().error_len(),
            Some(2)
        );
        assert_eq!(
            first_codepoint(b"\xF0\x9D\x84a").unwrap_err().error_len(),
            Some(3)
        );
        assert_eq!(first_codepoint(b"\xF0\x9D\x84\x9E").unwrap(), Some('𝄞'));
```

--------------------------------

### Handle non-standard argument patterns

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Illustrates how to integrate custom parsing functions within the main argument loop.

```rust
20fn main() -> Result<(), lexopt::Error> {
21    use lexopt::prelude::*;
22
23    let mut parser = lexopt::Parser::from_env();
24    loop {
25        if let Some(num) = parse_dashnum(&mut parser) {
26            println!("Got number {}", num);
27        } else if let Some(arg) = parser.next()? {
28            match arg {
29                Short('f') | Long("follow") => {
30                    println!("Got --follow");
31                }
32                Short('n') | Long("number") => {
33                    let num: u64 = parser.value()?.parse()?;
34                    println!("Got number {}", num);
35                }
36                Value(path) => {
37                    let path = PathBuf::from(path);
38                    println!("Got file {}", path.display());
39                }
40                _ => return Err(arg.unexpected()),
41            }
42        } else {
43            break;
44        }
45    }
46
47    Ok(())
48}
```

--------------------------------

### Parse raw arguments

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

Demonstrates how to access and iterate over raw arguments, including taking a specific number of arguments and peeking at the next argument.

```Rust
let mut p = parse("-a b c d");
            assert!(p.try_raw_args().is_some());
            assert_eq!(p.raw_args()?.collect::<Vec<_>>(), &["-a", "b", "c", "d"]);
            assert!(p.try_raw_args().is_some());
            assert!(p.next()?.is_none());
            assert!(p.try_raw_args().is_some());
            assert_eq!(p.raw_args()?.as_slice().len(), 0);
```

```Rust
let mut p = parse("-ab c d");
            p.next()?;
            assert!(p.try_raw_args().is_none());
            assert!(p.raw_args().is_err());
            assert_eq!(p.try_raw_args().unwrap().collect::<Vec<_>>(), &["c", "d"]);
            assert!(p.next()?.is_none());
            assert_eq!(p.try_raw_args().unwrap().as_slice().len(), 0);
```

```Rust
let mut p = parse("-a b c d");
            assert_eq!(p.raw_args()?.take(3).collect::<Vec<_>>(), &["-a", "b", "c"]);
            assert_eq!(p.next()?, Some(Value("d".into())));
            assert!(p.next()?.is_none());
```

```Rust
let mut p = parse("a");
            let mut it = p.raw_args()?;
            assert_eq!(it.peek(), Some("a".as_ref()));
            assert_eq!(it.next_if(|_| false), None);
            assert_eq!(
                it.next_if(|arg| {
                    assert_eq!(arg, "a");
                    true
                }),
                Some("a".into())
            );
            assert!(p.next()?.is_none());
```

--------------------------------

### Parsing Non-Standard Dash-Prefixed Arguments

Source: https://docs.rs/lexopt/0.3.2/src/nonstandard/nonstandard.rs.html

Uses try_raw_args to manually inspect and consume arguments before standard lexopt parsing logic. Requires the lexopt crate and standard library path handling.

```rust
//! Some programs accept options with an unusual syntax. For example, tail
//! accepts `-13` as an alias for `-n 13`.
//!
//! This program shows how to use `Parser::try_raw_args()` to handle them
//! manually.
//!
//! (Note: actual tail implementations handle it slightly differently! This
//! is just an example.)

use std::path::PathBuf;

fn parse_dashnum(parser: &mut lexopt::Parser) -> Option<u64> {
    let mut raw = parser.try_raw_args()?;
    let arg = raw.peek()?.to_str()?;
    let num = arg.strip_prefix('-')?.parse::<u64>().ok()?;
    raw.next(); // Consume the argument we just parsed
    Some(num)
}

fn main() -> Result<(), lexopt::Error> {
    use lexopt::prelude::*;

    let mut parser = lexopt::Parser::from_env();
    loop {
        if let Some(num) = parse_dashnum(&mut parser) {
            println!("Got number {}", num);
        } else if let Some(arg) = parser.next()? {
            match arg {
                Short('f') | Long("follow") => {
                    println!("Got --follow");
                }
                Short('n') | Long("number") => {
                    let num: u64 = parser.value()?.parse()?;
                    println!("Got number {}", num);
                }
                Value(path) => {
                    let path = PathBuf::from(path);
                    println!("Got file {}", path.display());
                }
                _ => return Err(arg.unexpected()),
            }
        } else {
            break;
        }
    }

    Ok(())
}
```

--------------------------------

### Consume raw arguments

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

Shows how to consume remaining command-line arguments as-is after encountering a free-standing argument.

```rust
/// # fn main() -> Result<(), lexopt::Error> {
/// # use lexopt::prelude::*;
/// # use std::ffi::OsString;
/// # use std::path::PathBuf;
/// # let mut parser = lexopt::Parser::from_args(&["-x", "echo", "-n", "'Hello, world'"]);
/// # while let Some(arg) = parser.next()? {
/// # match arg {
/// Value(prog) => {
///     let args: Vec<_> = parser.raw_args()?.collect();
///     let command = std::process::Command::new(prog).args(args);
/// }
/// # _ => (), }} Ok(()) }
```

--------------------------------

### Import lexopt prelude inside a function

Source: https://docs.rs/lexopt/0.3.2/lexopt/prelude/index.html

It is best practice to import the lexopt prelude inside a function, not in module scope, to avoid potential naming conflicts and keep the scope contained.

```rust
fn parse_args() -> Result<Args, lexopt::Error> {
    use lexopt::prelude::*;
    // ...
}
```

--------------------------------

### Parse complex application arguments

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Demonstrates using custom parsing functions with `parse_with` and handling required arguments.

```rust
49fn parse_args() -> Result<AppArgs, lexopt::Error> {
50    use lexopt::prelude::*;
51
52    let mut number = None;
53    let mut opt_number = None;
54    let mut width = 10;
55    let mut input = None;
56
57    let mut parser = lexopt::Parser::from_env();
58    while let Some(arg) = parser.next()? {
59        match arg {
60            Short('h') | Long("help") => {
61                print!("{}", HELP);
62                std::process::exit(0);
63            }
64            Long("number") => number = Some(parser.value()?.parse()?),
65            Long("opt-number") => opt_number = Some(parser.value()?.parse()?),
66            Long("width") => width = parser.value()?.parse_with(parse_width)?,
67            Value(path) if input.is_none() => input = Some(path.into()),
68            _ => return Err(arg.unexpected()),
69        }
70    }
71    Ok(AppArgs {
72        number: number.ok_or("missing required option --number")?,
73        opt_number,
74        width,
75        input: input.ok_or("missing required argument INPUT")?,
76    })
77}
```

--------------------------------

### Parse dash-prefixed numbers with try_raw_args

Source: https://docs.rs/lexopt/0.3.2/lexopt/struct.Parser.html

Demonstrates using try_raw_args to inspect and consume arguments without interfering with the main parser loop.

```rust
fn parse_dashnum(parser: &mut lexopt::Parser) -> Option<u64> {
    let mut raw = parser.try_raw_args()?;
    let arg = raw.peek()?.to_str()?;
    let num = arg.strip_prefix('-')?.parse::<u64>().ok()?;
    raw.next(); // Consume the argument we just parsed
    Some(num)
}

loop {
    if let Some(num) = parse_dashnum(&mut parser) {
        println!("Got number {}", num);
    } else if let Some(arg) = parser.next()? {
        match arg {
            // ...
        }
    } else {
        break;
    }
}
```

```rust
12fn parse_dashnum(parser: &mut lexopt::Parser) -> Option<u64> {
13    let mut raw = parser.try_raw_args()?;
14    let arg = raw.peek()?.to_str()?;
15    let num = arg.strip_prefix('-')?.parse::<u64>().ok()?;
16    raw.next(); // Consume the argument we just parsed
17    Some(num)
18}
```

--------------------------------

### Lexopt Error Formatting and Source in Rust

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

Shows how different argument types and errors are formatted and how to check for the underlying error source. This is useful for debugging and understanding the origin of errors.

```rust
assert_eq!(
            Arg::Short('o').unexpected().to_string(),
            "invalid option '-o'",
        );
        assert_eq!(
            Arg::Long("opt").unexpected().to_string(),
            "invalid option '--opt'",
        );
        assert_eq!(
            Arg::Value("foo".into()).unexpected().to_string(),
            r#"unexpected argument "foo""#,
        );
        assert_eq!(
            Error::from("this is an error message").to_string(),
            "this is an error message",
        );
        assert_eq!(
            Error::from("this is an error message".to_owned()).to_string(),
            "this is an error message",
        );
        assert!(Error::from("this is an error message").source().is_some());
        assert!(OsString::from("foo")
            .parse::<i32>()
            .unwrap_err()
            .source()
            .is_some());
        assert!(Arg::Short('o').unexpected().source().is_none());
        assert_eq!(
            format!("{:?}", Arg::Short('o').unexpected()),
            "invalid option '-o'",
        );
```

--------------------------------

### Implement Debug for lexopt Error

Source: https://docs.rs/lexopt/0.3.2/src/lexopt/lib.rs.html

Defers to the Display implementation for debugging output, ensuring consistent error messages.

```rust
impl std::fmt::Debug for Error {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        Display::fmt(self, f)
    }
}
```
Tokens:
Raw