| //! A pathologically simple command line argument parser. |
| //! |
| //! Most argument parsers are declarative: you tell them what to parse, |
| //! and they do it. |
| //! |
| //! This one provides you with a stream of options and values and lets you |
| //! figure out the rest. |
| //! |
| //! ## Example |
| //! ```no_run |
| //! 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(()) |
| //! } |
| //! ``` |
| //! Let's walk through this: |
| //! - We start parsing with [`Parser::from_env`]. |
| //! - We call [`parser.next()`][Parser::next] in a loop to get all the arguments until they run out. |
| //! - We match on arguments. [`Short`][Arg::Short] and [`Long`][Arg::Long] indicate an option. |
| //! - To get the value that belongs to an option (like `10` in `-n 10`) we call [`parser.value()`][Parser::value]. |
| //! - This returns a standard [`OsString`][std::ffi::OsString]. |
| //! - For convenience, [`use lexopt::prelude::*`][prelude] adds a [`.parse()`][ValueExt::parse] method, analogous to [`str::parse`]. |
| //! - Calling `parser.value()` is how we tell `Parser` that `-n` takes a value at all. |
| //! - `Value` indicates a free-standing argument. |
| //! - `if thing.is_none()` is a useful pattern for positional arguments. If we already found `thing` we pass it on to another case. |
| //! - It also contains an `OsString`. |
| //! - The [`.string()`][ValueExt::string] method decodes it into a plain `String`. |
| //! - If we don't know what to do with an argument we use [`return Err(arg.unexpected())`][Arg::unexpected] to turn it into an error message. |
| //! - Strings can be promoted to errors for custom error messages. |
| |
| #![forbid(unsafe_code)] |
| #![warn(missing_docs, missing_debug_implementations, elided_lifetimes_in_paths)] |
| #![allow(clippy::should_implement_trait)] |
| |
| use std::{ |
| ffi::{OsStr, OsString}, |
| fmt::Display, |
| mem::replace, |
| str::FromStr, |
| }; |
| |
| #[cfg(unix)] |
| use std::os::unix::ffi::{OsStrExt, OsStringExt}; |
| #[cfg(target_os = "wasi")] |
| use std::os::wasi::ffi::{OsStrExt, OsStringExt}; |
| #[cfg(windows)] |
| use std::os::windows::ffi::{OsStrExt, OsStringExt}; |
| |
| type InnerIter = std::vec::IntoIter<OsString>; |
| |
| fn make_iter(iter: impl Iterator<Item = OsString>) -> InnerIter { |
| iter.collect::<Vec<_>>().into_iter() |
| } |
| |
| /// A parser for command line arguments. |
| #[derive(Debug, Clone)] |
| pub struct Parser { |
| source: InnerIter, |
| state: State, |
| /// The last option we emitted. |
| last_option: LastOption, |
| /// The name of the command (argv\[0\]). |
| bin_name: Option<String>, |
| } |
| |
| #[derive(Debug, Clone)] |
| enum State { |
| /// Nothing interesting is going on. |
| None, |
| /// We have a value left over from --option=value. |
| PendingValue(OsString), |
| /// We're in the middle of -abc. |
| /// |
| /// On Windows and other non-UTF8-OsString platforms this Vec should |
| /// only ever contain valid UTF-8 (and could instead be a String). |
| Shorts(Vec<u8>, usize), |
| #[cfg(windows)] |
| /// We're in the middle of -ab� on Windows (invalid UTF-16). |
| ShortsU16(Vec<u16>, usize), |
| /// We saw -- and know no more options are coming. |
| FinishedOpts, |
| } |
| |
| /// We use this to keep track of the last emitted option, for error messages when |
| /// an expected value is not found. |
| /// |
| /// We also use this as storage for long options so we can hand out &str |
| /// (because String doesn't support pattern matching). |
| #[derive(Debug, Clone)] |
| enum LastOption { |
| None, |
| Short(char), |
| Long(String), |
| } |
| |
| /// A command line argument found by [`Parser`], either an option or a positional argument. |
| #[derive(Debug, Clone, PartialEq, Eq)] |
| pub enum Arg<'a> { |
| /// A short option, e.g. `Short('q')` for `-q`. |
| Short(char), |
| /// A long option, e.g. `Long("verbose")` for `--verbose`. (The dashes are not included.) |
| Long(&'a str), |
| /// A positional argument, e.g. `/dev/null`. |
| Value(OsString), |
| } |
| |
| impl Parser { |
| /// Get the next option or positional argument. |
| /// |
| /// A return value of `Ok(None)` means the command line has been exhausted. |
| /// |
| /// Options that are not valid unicode are transformed with replacement |
| /// characters as by [`String::from_utf8_lossy`]. |
| /// |
| /// # Errors |
| /// |
| /// [`Error::UnexpectedValue`] is returned if the last option had a |
| /// value that hasn't been consumed, as in `--option=value` or `-o=value`. |
| /// |
| /// It's possible to continue parsing after an error (but this is rarely useful). |
| 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.) |
| // clap always interprets it as a short flag in this case, but |
| // that feels sloppy. |
| Ok(Some('=')) if *pos > 1 => { |
| 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(_) => { |
| // Advancing may allow recovery. |
| // This is a little iffy, there might be more bad unicode next. |
| // The standard library may turn multiple bytes into a single |
| // replacement character, but we don't imitate that. |
| *pos += 1; |
| 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 => { |
| 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 { |
| State::None => (), |
| ref state => panic!("unexpected state {:?}", state), |
| } |
| |
| let arg = match self.source.next() { |
| Some(arg) => arg, |
| None => return Ok(None), |
| }; |
| |
| if arg == "--" { |
| self.state = State::FinishedOpts; |
| return self.next(); |
| } |
| |
| #[cfg(any(unix, target_os = "wasi"))] |
| { |
| // Fast solution for platforms where OsStrings are just UTF-8-ish bytes |
| let mut arg = arg.into_vec(); |
| if arg.starts_with(b"--") { |
| // Long options have two forms: --option and --option=value. |
| if let Some(ind) = arg.iter().position(|&b| b == b'=') { |
| // The value can be an OsString... |
| self.state = State::PendingValue(OsString::from_vec(arg[ind + 1..].into())); |
| arg.truncate(ind); |
| } |
| // ...but the option has to be a string. |
| // String::from_utf8_lossy().into_owned() would work, but its |
| // return type is Cow: if the original was valid a borrowed |
| // version is returned, and then into_owned() does an |
| // unnecessary copy. |
| // By trying String::from_utf8 first we avoid that copy if arg |
| // is already UTF-8 (which is most of the time). |
| // reqwest does a similar maneuver more efficiently with unsafe: |
| // https://github.com/seanmonstar/reqwest/blob/e6a1a09f0904e06de4ff1317278798c4ed28af66/src/async_impl/response.rs#L194 |
| let option = match String::from_utf8(arg) { |
| Ok(text) => text, |
| Err(err) => String::from_utf8_lossy(err.as_bytes()).into_owned(), |
| }; |
| Ok(Some(self.set_long(option))) |
| } else if arg.len() > 1 && arg[0] == b'-' { |
| self.state = State::Shorts(arg, 1); |
| self.next() |
| } else { |
| Ok(Some(Arg::Value(OsString::from_vec(arg)))) |
| } |
| } |
| |
| #[cfg(not(any(unix, target_os = "wasi")))] |
| { |
| // Platforms where looking inside an OsString is harder |
| |
| #[cfg(windows)] |
| { |
| // Fast path for Windows |
| let mut bytes = arg.encode_wide(); |
| const DASH: u16 = b'-' as u16; |
| match (bytes.next(), bytes.next()) { |
| (Some(DASH), Some(_)) => { |
| // This is an option, we'll have to do more work. |
| // (We already checked for "--" earlier.) |
| } |
| _ => { |
| // Just a value, return early. |
| return Ok(Some(Arg::Value(arg))); |
| } |
| } |
| } |
| |
| let mut arg = match arg.into_string() { |
| Ok(arg) => arg, |
| Err(arg) => { |
| // The argument is not valid unicode. |
| // If it's an option we'll have to do something nasty, |
| // otherwise we can return it as-is. |
| |
| #[cfg(windows)] |
| { |
| // On Windows we can only get here if this is an option, otherwise |
| // we return earlier. |
| // Unlike on Unix, we can't efficiently process invalid unicode. |
| // Semantically it's UTF-16, but internally it's WTF-8 (a superset of UTF-8). |
| // So we only process the raw version here, when we know we really have to. |
| let mut arg: Vec<u16> = arg.encode_wide().collect(); |
| const DASH: u16 = b'-' as u16; |
| const EQ: u16 = b'=' as u16; |
| if arg.starts_with(&[DASH, DASH]) { |
| if let Some(ind) = arg.iter().position(|&u| u == EQ) { |
| self.state = |
| State::PendingValue(OsString::from_wide(&arg[ind + 1..])); |
| arg.truncate(ind); |
| } |
| let long = self.set_long(String::from_utf16_lossy(&arg)); |
| return Ok(Some(long)); |
| } else { |
| assert!(arg.len() > 1); |
| assert_eq!(arg[0], DASH); |
| self.state = State::ShortsU16(arg, 1); |
| return self.next(); |
| } |
| }; |
| |
| #[cfg(not(windows))] |
| { |
| // This code may be reachable on Hermit and SGX, but probably |
| // not on wasm32-unknown-unknown, which is unfortunate as that's |
| // the only one we can easily test. |
| |
| // This allocates unconditionally, sadly. |
| let text = arg.to_string_lossy(); |
| if text.starts_with('-') { |
| // Use the lossily patched version and hope for the best. |
| // This may be incorrect behavior. Our only other option |
| // is an error but I don't want to write complicated code |
| // I can't actually test. |
| // Please open an issue if this behavior affects you! |
| text.into_owned() |
| } else { |
| // It didn't look like an option, so return it as a value. |
| return Ok(Some(Arg::Value(arg))); |
| } |
| } |
| } |
| }; |
| |
| // The argument is valid unicode. This is the ideal version of the |
| // code, the previous mess was purely to deal with invalid unicode. |
| if arg.starts_with("--") { |
| if let Some(ind) = arg.find('=') { |
| self.state = State::PendingValue(arg[ind + 1..].into()); |
| arg.truncate(ind); |
| } |
| Ok(Some(self.set_long(arg))) |
| } else if arg.starts_with('-') && arg != "-" { |
| self.state = State::Shorts(arg.into(), 1); |
| self.next() |
| } else { |
| Ok(Some(Arg::Value(arg.into()))) |
| } |
| } |
| } |
| |
| /// Get a value for an option. |
| /// |
| /// This function should normally be called right after seeing an option |
| /// that expects a value, with positional arguments being collected |
| /// using [`next()`][Parser::next]. |
| /// |
| /// A value is collected even if it looks like an option |
| /// (i.e., starts with `-`). |
| /// |
| /// # Errors |
| /// |
| /// An [`Error::MissingValue`] is returned if the end of the command |
| /// line is reached. |
| pub fn value(&mut self) -> Result<OsString, Error> { |
| if let Some(value) = self.optional_value() { |
| return Ok(value); |
| } |
| |
| if let Some(value) = self.source.next() { |
| return Ok(value); |
| } |
| |
| Err(Error::MissingValue { |
| option: self.format_last_option(), |
| }) |
| } |
| |
| /// Gather multiple values for an option. |
| /// |
| /// This is used for options that take multiple arguments, such as a |
| /// `--command` flag that's invoked as `app --command echo 'Hello world'`. |
| /// |
| /// It will gather arguments until another option is found, or `--` is found, or |
| /// the end of the command line is reached. This differs from `.value()`, which |
| /// takes a value even if it looks like an option. |
| /// |
| /// An equals sign (`=`) will limit this to a single value. That means `-a=b c` and |
| /// `--opt=b c` will only yield `"b"` while `-a b c`, `-ab c` and `--opt b c` will |
| /// yield `"b"`, `"c"`. |
| /// |
| /// # Errors |
| /// If not at least one value is found then [`Error::MissingValue`] is returned. |
| /// |
| /// # Example |
| /// ``` |
| /// # fn main() -> Result<(), lexopt::Error> { |
| /// # use lexopt::prelude::*; |
| /// # use std::ffi::OsString; |
| /// # use std::path::PathBuf; |
| /// # let mut parser = lexopt::Parser::from_args(&["a", "b", "-x", "one", "two", "three", "four"]); |
| /// let arguments: Vec<OsString> = parser.values()?.collect(); |
| /// # assert_eq!(arguments, &["a", "b"]); |
| /// # let _ = parser.next(); |
| /// let at_most_three_files: Vec<PathBuf> = parser.values()?.take(3).map(Into::into).collect(); |
| /// # assert_eq!(parser.raw_args()?.as_slice(), &["four"]); |
| /// for value in parser.values()? { |
| /// // ... |
| /// } |
| /// # Ok(()) } |
| /// ``` |
| pub fn values(&mut self) -> Result<ValuesIter<'_>, Error> { |
| // This code is designed so that just calling .values() doesn't consume |
| // any arguments as long as you don't use the iterator. It used to work |
| // differently. |
| // "--" is treated like an option and not consumed. This seems to me the |
| // least unreasonable behavior, and it's the easiest to implement. |
| if self.has_pending() || self.next_is_normal() { |
| Ok(ValuesIter { |
| took_first: false, |
| parser: Some(self), |
| }) |
| } else { |
| Err(Error::MissingValue { |
| option: self.format_last_option(), |
| }) |
| } |
| } |
| |
| /// Inspect an argument and consume it if it's "normal" (not an option or --). |
| /// |
| /// Used by [`Parser::values`]. |
| /// |
| /// This method should not be called while partway through processing an |
| /// argument. |
| fn next_if_normal(&mut self) -> Option<OsString> { |
| if self.next_is_normal() { |
| self.source.next() |
| } else { |
| None |
| } |
| } |
| |
| /// Execute the check for next_if_normal(). |
| fn next_is_normal(&self) -> bool { |
| assert!(!self.has_pending()); |
| let arg = match self.source.as_slice().first() { |
| // There has to be a next argument. |
| None => return false, |
| Some(arg) => arg, |
| }; |
| if let State::FinishedOpts = self.state { |
| // If we already found a -- then we're really not supposed to be here, |
| // but we shouldn't treat the next argument as an option. |
| return true; |
| } |
| if arg == "-" { |
| // "-" is the one argument with a leading '-' that's allowed. |
| return true; |
| } |
| #[cfg(any(unix, target_os = "wasi"))] |
| let lead_dash = arg.as_bytes().first() == Some(&b'-'); |
| #[cfg(windows)] |
| let lead_dash = arg.encode_wide().next() == Some(b'-' as u16); |
| #[cfg(not(any(unix, target_os = "wasi", windows)))] |
| let lead_dash = arg.to_string_lossy().as_bytes().first() == Some(&b'-'); |
| |
| !lead_dash |
| } |
| |
| /// Take raw arguments from the original command line. |
| /// |
| /// This returns an iterator of [`OsString`]s. Any arguments that are not |
| /// consumed are kept, so you can continue parsing after you're done with |
| /// the iterator. |
| /// |
| /// To inspect an argument without consuming it, use [`RawArgs::peek`] or |
| /// [`RawArgs::as_slice`]. |
| /// |
| /// # Errors |
| /// |
| /// Returns an [`Error::UnexpectedValue`] if the last option had a left-over |
| /// argument, as in `--option=value`, `-ovalue`, or if it was midway through |
| /// an option chain, as in `-abc`. The iterator only yields whole arguments. |
| /// To avoid this, use [`try_raw_args()`][Parser::try_raw_args]. |
| /// |
| /// After this error the method is guaranteed to succeed, as it consumes the |
| /// rest of the argument. |
| /// |
| /// # Example |
| /// As soon as a free-standing argument is found, consume the other arguments |
| /// as-is, and build them into a command. |
| /// ``` |
| /// # 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(()) } |
| pub fn raw_args(&mut self) -> Result<RawArgs<'_>, Error> { |
| if let Some(value) = self.optional_value() { |
| return Err(Error::UnexpectedValue { |
| option: self.format_last_option().unwrap(), |
| value, |
| }); |
| } |
| |
| Ok(RawArgs(&mut self.source)) |
| } |
| |
| /// Take raw arguments from the original command line, *if* the current argument |
| /// has finished processing. |
| /// |
| /// Unlike [`raw_args()`][Parser::raw_args] this does not consume any value |
| /// in case of a left-over argument. This makes it safe to call at any time. |
| /// |
| /// It returns `None` exactly when [`optional_value()`][Parser::optional_value] |
| /// would return `Some`. |
| /// |
| /// Note: If no arguments are left then it returns an empty iterator (not `None`). |
| /// |
| /// # Example |
| /// Process arguments of the form `-123` as numbers. For a complete runnable version of |
| /// this example, see |
| /// [`examples/nonstandard.rs`](https://github.com/blyxxyz/lexopt/blob/e3754e6f24506afb42394602fc257b1ad9258d84/examples/nonstandard.rs). |
| /// ``` |
| /// # fn main() -> Result<(), lexopt::Error> { |
| /// # use lexopt::prelude::*; |
| /// # use std::ffi::OsString; |
| /// # use std::path::PathBuf; |
| /// # let mut parser = lexopt::Parser::from_iter(&["-13"]); |
| /// 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; |
| /// } |
| /// } |
| /// # Ok(()) } |
| /// ``` |
| pub fn try_raw_args(&mut self) -> Option<RawArgs<'_>> { |
| if self.has_pending() { |
| None |
| } else { |
| Some(RawArgs(&mut self.source)) |
| } |
| } |
| |
| /// Check whether we're halfway through an argument, or in other words, |
| /// if [`Parser::optional_value()`] would return `Some`. |
| fn has_pending(&self) -> bool { |
| match self.state { |
| State::None | State::FinishedOpts => false, |
| State::PendingValue(_) => true, |
| State::Shorts(ref arg, pos) => pos < arg.len(), |
| #[cfg(windows)] |
| State::ShortsU16(ref arg, pos) => pos < arg.len(), |
| } |
| } |
| |
| #[inline(never)] |
| fn format_last_option(&self) -> Option<String> { |
| match self.last_option { |
| LastOption::None => None, |
| LastOption::Short(ch) => Some(format!("-{}", ch)), |
| LastOption::Long(ref option) => Some(option.clone()), |
| } |
| } |
| |
| /// The name of the command, as in the zeroth argument of the process. |
| /// |
| /// This is intended for use in messages. If the name is not valid unicode |
| /// it will be sanitized with replacement characters as by |
| /// [`String::from_utf8_lossy`]. |
| /// |
| /// To get the current executable, use [`std::env::current_exe`]. |
| /// |
| /// # Example |
| /// ``` |
| /// let mut parser = lexopt::Parser::from_env(); |
| /// let bin_name = parser.bin_name().unwrap_or("myapp"); |
| /// println!("{}: Some message", bin_name); |
| /// ``` |
| pub fn bin_name(&self) -> Option<&str> { |
| Some(self.bin_name.as_ref()?) |
| } |
| |
| /// Get a value only if it's concatenated to an option, as in `-ovalue` or |
| /// `--option=value` or `-o=value`, but not `-o value` or `--option value`. |
| pub fn optional_value(&mut self) -> Option<OsString> { |
| Some(self.raw_optional_value()?.0) |
| } |
| |
| /// [`Parser::optional_value`], but indicate whether the value was joined |
| /// with an = sign. This matters for [`Parser::values`]. |
| fn raw_optional_value(&mut self) -> Option<(OsString, bool)> { |
| match replace(&mut self.state, State::None) { |
| State::PendingValue(value) => Some((value, true)), |
| State::Shorts(mut arg, mut pos) => { |
| if pos >= arg.len() { |
| return None; |
| } |
| let mut had_eq_sign = false; |
| if arg[pos] == b'=' { |
| // -o=value. |
| // clap actually strips out all leading '='s, but that seems silly. |
| // We allow `-xo=value`. Python's argparse doesn't strip the = in that case. |
| pos += 1; |
| had_eq_sign = true; |
| } |
| arg.drain(..pos); // Reuse allocation |
| #[cfg(any(unix, target_os = "wasi"))] |
| { |
| Some((OsString::from_vec(arg), had_eq_sign)) |
| } |
| #[cfg(not(any(unix, target_os = "wasi")))] |
| { |
| let arg = String::from_utf8(arg) |
| .expect("short option args on exotic platforms must be unicode"); |
| Some((arg.into(), had_eq_sign)) |
| } |
| } |
| #[cfg(windows)] |
| State::ShortsU16(arg, mut pos) => { |
| if pos >= arg.len() { |
| return None; |
| } |
| let mut had_eq_sign = false; |
| if arg[pos] == b'=' as u16 { |
| pos += 1; |
| had_eq_sign = true; |
| } |
| Some((OsString::from_wide(&arg[pos..]), had_eq_sign)) |
| } |
| State::FinishedOpts => { |
| // Not really supposed to be here, but it's benign and not our fault |
| self.state = State::FinishedOpts; |
| None |
| } |
| State::None => None, |
| } |
| } |
| |
| fn new(bin_name: Option<OsString>, source: InnerIter) -> Parser { |
| Parser { |
| source, |
| state: State::None, |
| last_option: LastOption::None, |
| bin_name: bin_name.map(|s| match s.into_string() { |
| Ok(text) => text, |
| Err(text) => text.to_string_lossy().into_owned(), |
| }), |
| } |
| } |
| |
| /// Create a parser from the environment using [`std::env::args_os`]. |
| /// |
| /// This is the usual way to create a `Parser`. |
| pub fn from_env() -> Parser { |
| let mut source = make_iter(std::env::args_os()); |
| Parser::new(source.next(), source) |
| } |
| |
| // The collision with `FromIterator::from_iter` is a bit unfortunate. |
| // This name is used because: |
| // - `from_args()` was taken, and changing its behavior without changing |
| // its signature would be evil. |
| // - structopt also had a method by that name, so there's a precedent. |
| // (clap_derive doesn't.) |
| // - I couldn't think of a better one. |
| // When this name was chosen `FromIterator` could not actually be implemented. |
| // It can be implemented now, but I'm not sure there's a reason to. |
| |
| /// Create a parser from an iterator. This is useful for testing among other things. |
| /// |
| /// The first item from the iterator **must** be the binary name, as from [`std::env::args_os`]. |
| /// |
| /// The iterator is consumed immediately. |
| /// |
| /// # Example |
| /// ``` |
| /// let mut parser = lexopt::Parser::from_iter(&["myapp", "-n", "10", "./foo.bar"]); |
| /// ``` |
| pub fn from_iter<I>(args: I) -> Parser |
| where |
| I: IntoIterator, |
| I::Item: Into<OsString>, |
| { |
| let mut args = make_iter(args.into_iter().map(Into::into)); |
| Parser::new(args.next(), args) |
| } |
| |
| /// Create a parser from an iterator that does **not** include the binary name. |
| /// |
| /// The iterator is consumed immediately. |
| /// |
| /// [`bin_name()`](`Parser::bin_name`) will return `None`. Consider using |
| /// [`Parser::from_iter`] instead. |
| pub fn from_args<I>(args: I) -> Parser |
| where |
| I: IntoIterator, |
| I::Item: Into<OsString>, |
| { |
| Parser::new(None, make_iter(args.into_iter().map(Into::into))) |
| } |
| |
| /// Store a long option so the caller can borrow it. |
| fn set_long(&mut self, option: String) -> Arg<'_> { |
| self.last_option = LastOption::Long(option); |
| match self.last_option { |
| LastOption::Long(ref option) => Arg::Long(&option[2..]), |
| _ => unreachable!(), |
| } |
| } |
| } |
| |
| impl Arg<'_> { |
| /// Convert an unexpected argument into an error. |
| pub fn unexpected(self) -> Error { |
| match self { |
| Arg::Short(short) => Error::UnexpectedOption(format!("-{}", short)), |
| Arg::Long(long) => Error::UnexpectedOption(format!("--{}", long)), |
| Arg::Value(value) => Error::UnexpectedArgument(value), |
| } |
| } |
| } |
| |
| /// An iterator for multiple option-arguments, returned by [`Parser::values`]. |
| /// |
| /// It's guaranteed to yield at least one value. |
| #[derive(Debug)] |
| pub struct ValuesIter<'a> { |
| took_first: bool, |
| parser: Option<&'a mut Parser>, |
| } |
| |
| impl Iterator for ValuesIter<'_> { |
| type Item = OsString; |
| |
| fn next(&mut self) -> Option<Self::Item> { |
| let parser = self.parser.as_mut()?; |
| if self.took_first { |
| parser.next_if_normal() |
| } else if let Some((value, had_eq_sign)) = parser.raw_optional_value() { |
| if had_eq_sign { |
| self.parser = None; |
| } |
| self.took_first = true; |
| Some(value) |
| } else { |
| let value = parser |
| .next_if_normal() |
| .expect("ValuesIter must yield at least one value"); |
| self.took_first = true; |
| Some(value) |
| } |
| } |
| } |
| |
| /// An iterator for the remaining raw arguments, returned by [`Parser::raw_args`]. |
| #[derive(Debug)] |
| pub struct RawArgs<'a>(&'a mut InnerIter); |
| |
| impl Iterator for RawArgs<'_> { |
| type Item = OsString; |
| |
| fn next(&mut self) -> Option<Self::Item> { |
| self.0.next() |
| } |
| } |
| |
| impl RawArgs<'_> { |
| /// Return a reference to the next() value without consuming it. |
| /// |
| /// An argument you peek but do not consume will still be seen by `Parser` |
| /// if you resume parsing. |
| /// |
| /// See [`Iterator::peekable`], [`std::iter::Peekable::peek`]. |
| pub fn peek(&self) -> Option<&OsStr> { |
| Some(self.0.as_slice().first()?.as_os_str()) |
| } |
| |
| /// Consume and return the next argument if a condition is true. |
| /// |
| /// See [`std::iter::Peekable::next_if`]. |
| pub fn next_if(&mut self, func: impl FnOnce(&OsStr) -> bool) -> Option<OsString> { |
| match self.peek() { |
| Some(arg) if func(arg) => self.next(), |
| _ => None, |
| } |
| } |
| |
| /// Return the remaining arguments as a slice. |
| pub fn as_slice(&self) -> &[OsString] { |
| self.0.as_slice() |
| } |
| } |
| |
| // These would make sense: |
| // - fn RawArgs::iter(&self) |
| // - impl IntoIterator for &RawArgs |
| // - impl AsRef<[OsString]> for RawArgs |
| // But they're niche and constrain future design. |
| // Let's leave them out for now. |
| // (Open question: should iter() return std::slice::Iter<OsString> and get |
| // an optimized .nth() and so on for free, or should it return a novel type |
| // that yields &OsStr?) |
| |
| /// An error during argument parsing. |
| /// |
| /// This implements `From<String>` and `From<&str>`, for easy ad-hoc error |
| /// messages. |
| // |
| // This is not #[non_exhaustive] because of the MSRV. I'm hoping no more |
| // variants will turn out to be needed: this seems reasonable, if the scope |
| // of the library doesn't change. Worst case scenario it can be stuffed inside |
| // Error::Custom. |
| pub enum Error { |
| /// An option argument was expected but was not found. |
| MissingValue { |
| /// The most recently emitted option. |
| option: Option<String>, |
| }, |
| |
| /// An unexpected option was found. |
| UnexpectedOption(String), |
| |
| /// A positional argument was found when none was expected. |
| UnexpectedArgument(OsString), |
| |
| /// An option had a value when none was expected. |
| UnexpectedValue { |
| /// The option. |
| option: String, |
| /// The value. |
| value: OsString, |
| }, |
| |
| /// Parsing a value failed. Returned by methods on [`ValueExt`]. |
| ParsingFailed { |
| /// The string that failed to parse. |
| value: String, |
| /// The error returned while parsing. |
| error: Box<dyn std::error::Error + Send + Sync + 'static>, |
| }, |
| |
| /// A value was found that was not valid unicode. |
| /// |
| /// This can be returned by the methods on [`ValueExt`]. |
| NonUnicodeValue(OsString), |
| |
| /// For custom error messages in application code. |
| Custom(Box<dyn std::error::Error + Send + Sync + 'static>), |
| } |
| |
| impl Display for Error { |
| fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { |
| use crate::Error::*; |
| match self { |
| MissingValue { option: None } => write!(f, "missing argument"), |
| MissingValue { |
| option: Some(option), |
| } => { |
| write!(f, "missing argument for option '{}'", option) |
| } |
| UnexpectedOption(option) => write!(f, "invalid option '{}'", option), |
| UnexpectedArgument(value) => write!(f, "unexpected argument {:?}", value), |
| UnexpectedValue { option, value } => { |
| write!( |
| f, |
| "unexpected argument for option '{}': {:?}", |
| option, value |
| ) |
| } |
| NonUnicodeValue(value) => write!(f, "argument is invalid unicode: {:?}", value), |
| ParsingFailed { value, error } => { |
| write!(f, "cannot parse argument {:?}: {}", value, error) |
| } |
| Custom(err) => write!(f, "{}", err), |
| } |
| } |
| } |
| |
| // This is printed when returning an error from main(), so defer to Display |
| impl std::fmt::Debug for Error { |
| fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { |
| Display::fmt(self, f) |
| } |
| } |
| |
| impl std::error::Error for Error { |
| fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { |
| match self { |
| Error::ParsingFailed { error, .. } | Error::Custom(error) => Some(error.as_ref()), |
| _ => None, |
| } |
| } |
| } |
| |
| impl From<String> for Error { |
| fn from(msg: String) -> Self { |
| Error::Custom(msg.into()) |
| } |
| } |
| |
| impl<'a> From<&'a str> for Error { |
| fn from(msg: &'a str) -> Self { |
| Error::Custom(msg.into()) |
| } |
| } |
| |
| /// For [`OsString::into_string`], so it may be used with the try (`?`) operator. |
| /// |
| /// [`ValueExt::string`] is the new preferred method because it's compatible with |
| /// catch-all error types like `anyhow::Error`. |
| impl From<OsString> for Error { |
| fn from(arg: OsString) -> Self { |
| Error::NonUnicodeValue(arg) |
| } |
| } |
| |
| mod private { |
| pub trait Sealed {} |
| impl Sealed for std::ffi::OsString {} |
| } |
| |
| /// An optional extension trait with methods for parsing [`OsString`]s. |
| /// |
| /// They may fail in two cases: |
| /// - The value cannot be decoded because it's invalid unicode |
| /// ([`Error::NonUnicodeValue`]) |
| /// - The value can be decoded, but parsing fails ([`Error::ParsingFailed`]) |
| /// |
| /// If parsing fails the error will be wrapped in lexopt's own [`Error`] type. |
| pub trait ValueExt: private::Sealed { |
| /// Decode the value and parse it using [`FromStr`]. |
| /// |
| /// This will fail if the value is not valid unicode or if the subsequent |
| /// parsing fails. |
| fn parse<T: FromStr>(&self) -> Result<T, Error> |
| where |
| T::Err: Into<Box<dyn std::error::Error + Send + Sync + 'static>>; |
| |
| /// Decode the value and parse it using a custom function. |
| fn parse_with<F, T, E>(&self, func: F) -> Result<T, Error> |
| where |
| F: FnOnce(&str) -> Result<T, E>, |
| E: Into<Box<dyn std::error::Error + Send + Sync + 'static>>; |
| |
| // There is no parse_os_with() because I can't think of any useful |
| // fallible operations on an OsString. Typically you'd either decode it, |
| // use it as is, or do an infallible conversion to a PathBuf or such. |
| // |
| // If you have a use for parse_os_with() please open an issue with an |
| // example. |
| |
| /// Convert the `OsString` into a [`String`] if it's valid Unicode. |
| /// |
| /// This is like [`OsString::into_string`] but returns an |
| /// [`Error::NonUnicodeValue`] on error instead of the original `OsString`. |
| /// This makes it easier to propagate the failure with libraries like |
| /// `anyhow`. |
| fn string(self) -> Result<String, Error>; |
| } |
| |
| impl ValueExt for OsString { |
| fn parse<T: FromStr>(&self) -> Result<T, Error> |
| where |
| T::Err: Into<Box<dyn std::error::Error + Send + Sync + 'static>>, |
| { |
| self.parse_with(FromStr::from_str) |
| } |
| |
| fn parse_with<F, T, E>(&self, func: F) -> Result<T, Error> |
| where |
| F: FnOnce(&str) -> Result<T, E>, |
| E: Into<Box<dyn std::error::Error + Send + Sync + 'static>>, |
| { |
| match self.to_str() { |
| Some(text) => match func(text) { |
| Ok(value) => Ok(value), |
| Err(err) => Err(Error::ParsingFailed { |
| value: text.to_owned(), |
| error: err.into(), |
| }), |
| }, |
| None => Err(Error::NonUnicodeValue(self.into())), |
| } |
| } |
| |
| fn string(self) -> Result<String, Error> { |
| match self.into_string() { |
| Ok(string) => Ok(string), |
| Err(raw) => Err(Error::NonUnicodeValue(raw)), |
| } |
| } |
| } |
| |
| /// A small prelude for processing arguments. |
| /// |
| /// It allows you to write `Short`/`Long`/`Value` without an [`Arg`] prefix |
| /// and adds convenience methods to [`OsString`]. |
| /// |
| /// If this is used it's best to import it inside a function, not in module |
| /// scope: |
| /// ``` |
| /// # struct Args; |
| /// fn parse_args() -> Result<Args, lexopt::Error> { |
| /// use lexopt::prelude::*; |
| /// // ... |
| /// # Ok(Args) |
| /// } |
| /// ``` |
| pub mod prelude { |
| pub use super::Arg::*; |
| pub use super::ValueExt; |
| } |
| |
| /// Take the first codepoint of a bytestring. On error, return the first |
| /// (and therefore in some way invalid) byte/code unit. |
| /// |
| /// The rest of the bytestring does not have to be valid unicode. |
| fn first_codepoint(bytes: &[u8]) -> Result<Option<char>, u8> { |
| // We only need the first 4 bytes |
| let bytes = bytes.get(..4).unwrap_or(bytes); |
| let text = match std::str::from_utf8(bytes) { |
| Ok(text) => text, |
| Err(err) if err.valid_up_to() > 0 => { |
| std::str::from_utf8(&bytes[..err.valid_up_to()]).unwrap() |
| } |
| Err(_) => return Err(bytes[0]), |
| }; |
| Ok(text.chars().next()) |
| } |
| |
| #[cfg(windows)] |
| /// As before, but for UTF-16. |
| fn first_utf16_codepoint(units: &[u16]) -> Result<Option<char>, u16> { |
| match std::char::decode_utf16(units.iter().cloned()).next() { |
| Some(Ok(ch)) => Ok(Some(ch)), |
| Some(Err(_)) => Err(units[0]), |
| None => Ok(None), |
| } |
| } |
| |
| #[cfg(test)] |
| mod tests { |
| use super::prelude::*; |
| use super::*; |
| |
| fn parse(args: &'static str) -> Parser { |
| Parser::from_args(args.split_whitespace().map(bad_string)) |
| } |
| |
| /// Specialized backport of matches!() |
| macro_rules! assert_matches { |
| ($expression: expr, $( $pattern: pat )|+) => { |
| match $expression { |
| $( $pattern )|+ => (), |
| _ => panic!( |
| "{:?} does not match {:?}", |
| stringify!($expression), |
| stringify!($( $pattern )|+) |
| ), |
| } |
| }; |
| } |
| |
| #[test] |
| fn test_basic() -> Result<(), Error> { |
| let mut p = parse("-n 10 foo - -- baz -qux"); |
| assert_eq!(p.next()?.unwrap(), Short('n')); |
| assert_eq!(p.value()?.parse::<i32>()?, 10); |
| assert_eq!(p.next()?.unwrap(), Value("foo".into())); |
| assert_eq!(p.next()?.unwrap(), Value("-".into())); |
| assert_eq!(p.next()?.unwrap(), Value("baz".into())); |
| assert_eq!(p.next()?.unwrap(), Value("-qux".into())); |
| assert_eq!(p.next()?, None); |
| assert_eq!(p.next()?, None); |
| assert_eq!(p.next()?, None); |
| Ok(()) |
| } |
| |
| #[test] |
| fn test_combined() -> Result<(), Error> { |
| let mut p = parse("-abc -fvalue -xfvalue"); |
| assert_eq!(p.next()?.unwrap(), Short('a')); |
| assert_eq!(p.next()?.unwrap(), Short('b')); |
| assert_eq!(p.next()?.unwrap(), Short('c')); |
| assert_eq!(p.next()?.unwrap(), Short('f')); |
| assert_eq!(p.value()?, "value"); |
| assert_eq!(p.next()?.unwrap(), Short('x')); |
| assert_eq!(p.next()?.unwrap(), Short('f')); |
| assert_eq!(p.value()?, "value"); |
| assert_eq!(p.next()?, None); |
| Ok(()) |
| } |
| |
| #[test] |
| fn test_long() -> Result<(), Error> { |
| let mut p = parse("--foo --bar=qux --foobar=qux=baz"); |
| assert_eq!(p.next()?.unwrap(), Long("foo")); |
| assert_eq!(p.next()?.unwrap(), Long("bar")); |
| assert_eq!(p.value()?, "qux"); |
| assert_eq!(p.next()?.unwrap(), Long("foobar")); |
| match p.next().unwrap_err() { |
| Error::UnexpectedValue { option, value } => { |
| assert_eq!(option, "--foobar"); |
| assert_eq!(value, "qux=baz"); |
| } |
| _ => panic!(), |
| } |
| assert_eq!(p.next()?, None); |
| Ok(()) |
| } |
| |
| #[test] |
| fn test_dash_args() -> Result<(), Error> { |
| // "--" should indicate the end of the options |
| let mut p = parse("-x -- -y"); |
| assert_eq!(p.next()?.unwrap(), Short('x')); |
| assert_eq!(p.next()?.unwrap(), Value("-y".into())); |
| assert_eq!(p.next()?, None); |
| |
| // ...unless it's an argument of an option |
| let mut p = parse("-x -- -y"); |
| assert_eq!(p.next()?.unwrap(), Short('x')); |
| assert_eq!(p.value()?, "--"); |
| assert_eq!(p.next()?.unwrap(), Short('y')); |
| assert_eq!(p.next()?, None); |
| |
| // "-" is a valid value that should not be treated as an option |
| let mut p = parse("-x - -y"); |
| assert_eq!(p.next()?.unwrap(), Short('x')); |
| assert_eq!(p.next()?.unwrap(), Value("-".into())); |
| assert_eq!(p.next()?.unwrap(), Short('y')); |
| assert_eq!(p.next()?, None); |
| |
| // '-' is a silly and hard to use short option, but other parsers treat |
| // it like an option in this position |
| let mut p = parse("-x-y"); |
| assert_eq!(p.next()?.unwrap(), Short('x')); |
| assert_eq!(p.next()?.unwrap(), Short('-')); |
| assert_eq!(p.next()?.unwrap(), Short('y')); |
| assert_eq!(p.next()?, None); |
| |
| Ok(()) |
| } |
| |
| #[test] |
| fn test_missing_value() -> Result<(), Error> { |
| let mut p = parse("-o"); |
| assert_eq!(p.next()?.unwrap(), Short('o')); |
| match p.value() { |
| Err(Error::MissingValue { |
| option: Some(option), |
| }) => assert_eq!(option, "-o"), |
| _ => panic!(), |
| } |
| |
| let mut q = parse("--out"); |
| assert_eq!(q.next()?.unwrap(), Long("out")); |
| match q.value() { |
| Err(Error::MissingValue { |
| option: Some(option), |
| }) => assert_eq!(option, "--out"), |
| _ => panic!(), |
| } |
| |
| let mut r = parse(""); |
| assert_matches!(r.value(), Err(Error::MissingValue { option: None })); |
| |
| Ok(()) |
| } |
| |
| #[test] |
| fn test_weird_args() -> Result<(), Error> { |
| let mut p = Parser::from_args(&[ |
| "", "--=", "--=3", "-", "-x", "--", "-", "-x", "--", "", "-", "-x", |
| ]); |
| assert_eq!(p.next()?.unwrap(), Value(OsString::from(""))); |
| |
| // These are weird and questionable, but this seems to be the standard |
| // interpretation |
| // GNU getopt_long and argparse complain that it could be an abbreviation |
| // of every single long option |
| // clap complains that "--" is not expected, which matches its treatment |
| // of unknown long options |
| assert_eq!(p.next()?.unwrap(), Long("")); |
| assert_eq!(p.value()?, OsString::from("")); |
| assert_eq!(p.next()?.unwrap(), Long("")); |
| assert_eq!(p.value()?, OsString::from("3")); |
| |
| assert_eq!(p.next()?.unwrap(), Value(OsString::from("-"))); |
| assert_eq!(p.next()?.unwrap(), Short('x')); |
| assert_eq!(p.value()?, OsString::from("--")); |
| assert_eq!(p.next()?.unwrap(), Value(OsString::from("-"))); |
| assert_eq!(p.next()?.unwrap(), Short('x')); |
| assert_eq!(p.next()?.unwrap(), Value(OsString::from(""))); |
| assert_eq!(p.next()?.unwrap(), Value(OsString::from("-"))); |
| assert_eq!(p.next()?.unwrap(), Value(OsString::from("-x"))); |
| assert_eq!(p.next()?, None); |
| |
| #[cfg(any(unix, target_os = "wasi", windows))] |
| { |
| let mut q = parse("--=@"); |
| assert_eq!(q.next()?.unwrap(), Long("")); |
| assert_eq!(q.value()?, bad_string("@")); |
| assert_eq!(q.next()?, None); |
| } |
| |
| let mut r = parse(""); |
| assert_eq!(r.next()?, None); |
| |
| Ok(()) |
| } |
| |
| #[test] |
| fn test_unicode() -> Result<(), Error> { |
| let mut p = parse("-aµ --µ=10 µ --foo=µ"); |
| assert_eq!(p.next()?.unwrap(), Short('a')); |
| assert_eq!(p.next()?.unwrap(), Short('µ')); |
| assert_eq!(p.next()?.unwrap(), Long("µ")); |
| assert_eq!(p.value()?, "10"); |
| assert_eq!(p.next()?.unwrap(), Value("µ".into())); |
| assert_eq!(p.next()?.unwrap(), Long("foo")); |
| assert_eq!(p.value()?, "µ"); |
| Ok(()) |
| } |
| |
| #[cfg(any(unix, target_os = "wasi", windows))] |
| #[test] |
| fn test_mixed_invalid() -> Result<(), Error> { |
| let mut p = parse("--foo=@@@"); |
| assert_eq!(p.next()?.unwrap(), Long("foo")); |
| assert_eq!(p.value()?, bad_string("@@@")); |
| |
| let mut q = parse("-💣@@@"); |
| assert_eq!(q.next()?.unwrap(), Short('💣')); |
| assert_eq!(q.value()?, bad_string("@@@")); |
| |
| let mut r = parse("-f@@@"); |
| assert_eq!(r.next()?.unwrap(), Short('f')); |
| assert_eq!(r.next()?.unwrap(), Short('�')); |
| assert_eq!(r.next()?.unwrap(), Short('�')); |
| assert_eq!(r.next()?.unwrap(), Short('�')); |
| assert_eq!(r.next()?, None); |
| |
| let mut s = parse("--foo=bar=@@@"); |
| assert_eq!(s.next()?.unwrap(), Long("foo")); |
| assert_eq!(s.value()?, bad_string("bar=@@@")); |
| |
| Ok(()) |
| } |
| |
| #[cfg(any(unix, target_os = "wasi", windows))] |
| #[test] |
| fn test_separate_invalid() -> Result<(), Error> { |
| let mut p = parse("--foo @@@"); |
| assert_eq!(p.next()?.unwrap(), Long("foo")); |
| assert_eq!(p.value()?, bad_string("@@@")); |
| Ok(()) |
| } |
| |
| #[cfg(any(unix, target_os = "wasi", windows))] |
| #[test] |
| fn test_invalid_long_option() -> Result<(), Error> { |
| let mut p = parse("--@=10"); |
| assert_eq!(p.next()?.unwrap(), Long("�")); |
| assert_eq!(p.value().unwrap(), OsString::from("10")); |
| assert_eq!(p.next()?, None); |
| |
| let mut q = parse("--@"); |
| assert_eq!(q.next()?.unwrap(), Long("�")); |
| assert_eq!(q.next()?, None); |
| |
| Ok(()) |
| } |
| |
| #[test] |
| fn short_opt_equals_sign() -> Result<(), Error> { |
| let mut p = parse("-a=b"); |
| assert_eq!(p.next()?.unwrap(), Short('a')); |
| assert_eq!(p.value()?, OsString::from("b")); |
| assert_eq!(p.next()?, None); |
| |
| let mut p = parse("-a=b"); |
| assert_eq!(p.next()?.unwrap(), Short('a')); |
| match p.next().unwrap_err() { |
| Error::UnexpectedValue { option, value } => { |
| assert_eq!(option, "-a"); |
| assert_eq!(value, "b"); |
| } |
| _ => panic!(), |
| } |
| assert_eq!(p.next()?, None); |
| |
| let mut p = parse("-a="); |
| assert_eq!(p.next()?.unwrap(), Short('a')); |
| assert_eq!(p.value()?, OsString::from("")); |
| assert_eq!(p.next()?, None); |
| |
| let mut p = parse("-a="); |
| assert_eq!(p.next()?.unwrap(), Short('a')); |
| match p.next().unwrap_err() { |
| Error::UnexpectedValue { option, value } => { |
| assert_eq!(option, "-a"); |
| assert_eq!(value, ""); |
| } |
| _ => panic!(), |
| } |
| assert_eq!(p.next()?, None); |
| |
| let mut p = parse("-="); |
| assert_eq!(p.next()?.unwrap(), Short('=')); |
| assert_eq!(p.next()?, None); |
| |
| let mut p = parse("-=a"); |
| assert_eq!(p.next()?.unwrap(), Short('=')); |
| assert_eq!(p.value()?, "a"); |
| |
| Ok(()) |
| } |
| |
| #[cfg(any(unix, target_os = "wasi", windows))] |
| #[test] |
| fn short_opt_equals_sign_invalid() -> Result<(), Error> { |
| let mut p = parse("-a=@"); |
| assert_eq!(p.next()?.unwrap(), Short('a')); |
| assert_eq!(p.value()?, bad_string("@")); |
| assert_eq!(p.next()?, None); |
| |
| let mut p = parse("-a=@"); |
| assert_eq!(p.next()?.unwrap(), Short('a')); |
| match p.next().unwrap_err() { |
| Error::UnexpectedValue { option, value } => { |
| assert_eq!(option, "-a"); |
| assert_eq!(value, bad_string("@")); |
| } |
| _ => panic!(), |
| } |
| assert_eq!(p.next()?, None); |
| |
| let mut p = parse("-=@"); |
| assert_eq!(p.next()?.unwrap(), Short('=')); |
| assert_eq!(p.value()?, bad_string("@")); |
| |
| Ok(()) |
| } |
| |
| #[test] |
| fn multi_values() -> Result<(), Error> { |
| for &case in &["-a b c d", "-ab c d", "-a b c d --", "--a b c d"] { |
| 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()); |
| } |
| |
| for &case in &["-a=b c", "--a=b c"] { |
| 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()); |
| } |
| |
| for &case in &["-a", "--a", "-a -b", "-a -- b", "-a --"] { |
| let mut p = parse(case); |
| p.next()?.unwrap(); |
| assert!(p.values().is_err()); |
| assert!(p.next().is_ok()); |
| assert!(p.next().unwrap().is_none()); |
| } |
| |
| for &case in &["-a=", "--a="] { |
| 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()); |
| } |
| |
| // Test that .values() does not eagerly consume the first value |
| for &case in &["-a=b", "--a=b", "-a b"] { |
| let mut p = parse(case); |
| p.next()?.unwrap(); |
| assert!(p.values().is_ok()); |
| assert_eq!(p.value()?, "b"); |
| } |
| |
| { |
| let mut p = parse("-ab"); |
| p.next()?.unwrap(); |
| assert!(p.values().is_ok()); |
| assert_eq!(p.next()?.unwrap(), Short('b')); |
| } |
| |
| Ok(()) |
| } |
| |
| #[test] |
| fn raw_args() -> Result<(), Error> { |
| 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); |
| |
| 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); |
| |
| 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()); |
| |
| 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!(p.next()?, Some(Value("a".into()))); |
| assert!(p.next()?.is_none()); |
| |
| Ok(()) |
| } |
| |
| #[test] |
| fn bin_name() { |
| assert_eq!( |
| Parser::from_iter(&["foo", "bar", "baz"]).bin_name(), |
| Some("foo") |
| ); |
| assert_eq!(Parser::from_args(&["foo", "bar", "baz"]).bin_name(), None); |
| assert_eq!(Parser::from_iter(&[] as &[&str]).bin_name(), None); |
| assert_eq!(Parser::from_iter(&[""]).bin_name(), Some("")); |
| assert!(Parser::from_env().bin_name().is_some()); |
| #[cfg(any(unix, target_os = "wasi", windows))] |
| assert_eq!( |
| Parser::from_iter(vec![bad_string("foo@bar")]).bin_name(), |
| Some("foo�bar") |
| ); |
| } |
| |
| #[test] |
| fn test_value_ext() -> Result<(), Error> { |
| let s = OsString::from("-10"); |
| assert_eq!(s.parse::<i32>()?, -10); |
| assert_eq!( |
| s.parse_with(|s| match s { |
| "-10" => Ok(0), |
| _ => Err("bad"), |
| })?, |
| 0, |
| ); |
| match s.parse::<u32>() { |
| Err(Error::ParsingFailed { value, .. }) => assert_eq!(value, "-10"), |
| _ => panic!(), |
| } |
| match s.parse_with(|s| match s { |
| "11" => Ok(0_i32), |
| _ => Err("bad"), |
| }) { |
| Err(Error::ParsingFailed { value, .. }) => assert_eq!(value, "-10"), |
| _ => panic!(), |
| } |
| assert_eq!(s.string()?, "-10"); |
| Ok(()) |
| } |
| |
| #[cfg(any(unix, target_os = "wasi", windows))] |
| #[test] |
| fn test_value_ext_invalid() -> Result<(), Error> { |
| let s = bad_string("foo@"); |
| assert_matches!(s.parse::<i32>(), Err(Error::NonUnicodeValue(_))); |
| assert_matches!( |
| s.parse_with(<f32 as FromStr>::from_str), |
| Err(Error::NonUnicodeValue(_)) |
| ); |
| assert_matches!(s.string(), Err(Error::NonUnicodeValue(_))); |
| Ok(()) |
| } |
| |
| #[test] |
| fn test_first_codepoint() { |
| 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('µ')); |
| first_codepoint(b"\xFF").unwrap_err(); |
| assert_eq!(first_codepoint(b"foo\xC2\xB5").unwrap(), Some('f')); |
| } |
| |
| /// Transform @ characters into invalid unicode. |
| fn bad_string(text: &str) -> OsString { |
| #[cfg(any(unix, target_os = "wasi"))] |
| { |
| let mut text = text.as_bytes().to_vec(); |
| for ch in &mut text { |
| if *ch == b'@' { |
| *ch = b'\xFF'; |
| } |
| } |
| OsString::from_vec(text) |
| } |
| #[cfg(windows)] |
| { |
| let mut out = Vec::new(); |
| for ch in text.chars() { |
| if ch == '@' { |
| out.push(0xD800); |
| } else { |
| let mut buf = [0; 2]; |
| out.extend(&*ch.encode_utf16(&mut buf)); |
| } |
| } |
| OsString::from_wide(&out) |
| } |
| #[cfg(not(any(unix, target_os = "wasi", windows)))] |
| { |
| if text.contains('@') { |
| unimplemented!("Don't know how to create invalid OsStrings on this platform"); |
| } |
| text.into() |
| } |
| } |
| |
| /// Basic exhaustive testing of short combinations of "interesting" |
| /// arguments. They should not panic, not hang, and pass some checks. |
| /// |
| /// The advantage compared to full fuzzing is that it runs on all platforms |
| /// and together with the other tests. cargo-fuzz doesn't work on Windows |
| /// and requires a special incantation. |
| /// |
| /// A disadvantage is that it's still limited by arguments I could think of |
| /// and only does very short sequences. Another is that it's bad at |
| /// reporting failure, though the println!() helps. |
| /// |
| /// This test takes a while to run. |
| #[test] |
| fn basic_fuzz() { |
| #[cfg(any(windows, unix, target_os = "wasi"))] |
| const VOCABULARY: &[&str] = &[ |
| "", "-", "--", "---", "a", "-a", "-aa", "@", "-@", "-a@", "-@a", "--a", "--@", "--a=a", |
| "--a=", "--a=@", "--@=a", "--=", "--=@", "--=a", "-@@", "-a=a", "-a=", "-=", "-a-", |
| ]; |
| #[cfg(not(any(windows, unix, target_os = "wasi")))] |
| const VOCABULARY: &[&str] = &[ |
| "", "-", "--", "---", "a", "-a", "-aa", "--a", "--a=a", "--a=", "--=", "--=a", "-a=a", |
| "-a=", "-=", "-a-", |
| ]; |
| exhaust(Parser::new(None, Vec::new().into_iter()), 0); |
| let vocabulary: Vec<OsString> = VOCABULARY.iter().map(|&s| bad_string(s)).collect(); |
| let mut permutations = vec![vec![]]; |
| for _ in 0..3 { |
| let mut new = Vec::new(); |
| for old in permutations { |
| for word in &vocabulary { |
| let mut extended = old.clone(); |
| extended.push(word); |
| new.push(extended); |
| } |
| } |
| permutations = new; |
| for permutation in &permutations { |
| println!("{:?}", permutation); |
| let p = Parser::from_args(permutation); |
| exhaust(p, 0); |
| } |
| } |
| } |
| |
| /// Run many sequences of methods on a Parser. |
| fn exhaust(mut parser: Parser, depth: u16) { |
| if depth > 100 { |
| panic!("Stuck in loop"); |
| } |
| |
| // has_pending() == optional_value().is_some() |
| if parser.has_pending() { |
| { |
| let mut parser = parser.clone(); |
| assert!(parser.try_raw_args().is_none()); |
| assert!(parser.try_raw_args().is_none()); |
| assert!(parser.raw_args().is_err()); |
| // Recovery possible |
| assert!(parser.raw_args().is_ok()); |
| assert!(parser.try_raw_args().is_some()); |
| } |
| |
| { |
| let mut parser = parser.clone(); |
| assert!(parser.optional_value().is_some()); |
| exhaust(parser, depth + 1); |
| } |
| } else { |
| let prev_state = parser.state.clone(); |
| let prev_remaining = parser.source.as_slice().len(); |
| assert!(parser.optional_value().is_none()); |
| assert!(parser.raw_args().is_ok()); |
| assert!(parser.try_raw_args().is_some()); |
| // Verify state transitions |
| match prev_state { |
| State::None | State::PendingValue(_) => { |
| assert_matches!(parser.state, State::None); |
| } |
| State::Shorts(arg, pos) => { |
| assert_eq!(pos, arg.len()); |
| assert_matches!(parser.state, State::None); |
| } |
| #[cfg(windows)] |
| State::ShortsU16(arg, pos) => { |
| assert_eq!(pos, arg.len()); |
| assert_matches!(parser.state, State::None); |
| } |
| State::FinishedOpts => assert_matches!(parser.state, State::FinishedOpts), |
| } |
| // No arguments were consumed |
| assert_eq!(parser.source.as_slice().len(), prev_remaining); |
| } |
| |
| { |
| let mut parser = parser.clone(); |
| match parser.next() { |
| Ok(None) => { |
| assert_matches!(parser.state, State::None | State::FinishedOpts); |
| assert_eq!(parser.source.as_slice().len(), 0); |
| } |
| _ => exhaust(parser, depth + 1), |
| } |
| } |
| |
| { |
| let mut parser = parser.clone(); |
| match parser.value() { |
| Err(_) => { |
| assert_matches!(parser.state, State::None | State::FinishedOpts); |
| assert_eq!(parser.source.as_slice().len(), 0); |
| } |
| Ok(_) => { |
| assert_matches!(parser.state, State::None | State::FinishedOpts); |
| exhaust(parser, depth + 1); |
| } |
| } |
| } |
| |
| { |
| match parser.values() { |
| Err(_) => (), |
| Ok(iter) => { |
| assert!(iter.count() > 0); |
| exhaust(parser, depth + 1); |
| } |
| } |
| } |
| } |
| } |
