fix(lexarg): Iterate on the design

DESIGN.md

@@ -132,5 +132,20 @@ this makes delegating to plugins in a cooperative way more challenging.
 
 In reviewing lexopt's API:
 - Error handling is included in the API in a way that might make evolution difficult
+- Escapes aren't explicitly communicated which makes communal parsing more difficult
+- lexopt builds in specific option-value semantics
 
-TODO: there were other points that felt off to me about lexopt's API wrt API stability but I do not recall what they are
+And in general we will be putting the parser in the libtest-next's API and it will be a fundamental point of extension.
+Having complete control helps ensure the full experience is cohesive.
+
+### Decision: `Short(&str)`
+
+`lexopt` and `clap` / `clap_lex` treat shorts as a `char` which gives a level of type safety to parsing.
+However, with a minimal API, providing `&str` provides span information "for free".
+
+If someone were to make an API for pluggable lexers,
+support for multi-character shorts is something people may want to opt-in to (it has been requested of clap).
+
+Performance isn't the top priority, so remoing `&str` -> `char` conversions isn't necessarily viewed as a benefit.
+This also makes `match` need to work off of `&str` instead of `char`.
+Unsure which of those would be slower and how the different characteristics match up.

crates/lexarg-error/Cargo.toml

@@ -27,9 +27,9 @@ pre-release-replacements = [
 default = []
 
 [dependencies]
+lexarg = { "version" = "0.1.0", path = "../lexarg" }
 
 [dev-dependencies]
-lexarg = { "version" = "0.1.0", path = "../lexarg" }
 
 [lints]
 workspace = true

crates/lexarg-error/examples/hello-error.rs

@@ -0,0 +1,80 @@
+use lexarg_error::ErrorContext;
+use lexarg_error::Result;
+
+struct Args {
+    thing: String,
+    number: u32,
+    shout: bool,
+}
+
+fn parse_args() -> Result<Args> {
+    #![allow(clippy::enum_glob_use)]
+    use lexarg::Arg::*;
+
+    let mut thing = None;
+    let mut number = 1;
+    let mut shout = false;
+    let raw = std::env::args_os().collect::<Vec<_>>();
+    let mut parser = lexarg::Parser::new(&raw);
+    let bin_name = parser
+        .next_raw()
+        .expect("nothing parsed yet so no attached lingering")
+        .expect("always at least one");
+    while let Some(arg) = parser.next_arg() {
+        match arg {
+            Short("n") | Long("number") => {
+                let value = parser
+                    .next_flag_value()
+                    .ok_or_else(|| ErrorContext::msg("missing required value").within(arg))?;
+                number = value
+                    .to_str()
+                    .ok_or_else(|| {
+                        ErrorContext::msg("invalid number")
+                            .unexpected(Value(value))
+                            .within(arg)
+                    })?
+                    .parse()
+                    .map_err(|e| ErrorContext::msg(e).unexpected(Value(value)).within(arg))?;
+            }
+            Long("shout") => {
+                shout = true;
+            }
+            Value(val) if thing.is_none() => {
+                thing = Some(
+                    val.to_str()
+                        .ok_or_else(|| ErrorContext::msg("invalid string").unexpected(arg))?,
+                );
+            }
+            Short("h") | Long("help") => {
+                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
+                std::process::exit(0);
+            }
+            _ => {
+                return Err(ErrorContext::msg("unexpected argument")
+                    .unexpected(arg)
+                    .within(Value(bin_name))
+                    .into());
+            }
+        }
+    }
+
+    Ok(Args {
+        thing: thing
+            .ok_or_else(|| ErrorContext::msg("missing argument THING").within(Value(bin_name)))?
+            .to_owned(),
+        number,
+        shout,
+    })
+}
+
+fn main() -> Result<()> {
+    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(())
+}

crates/lexarg-error/src/lib.rs

@@ -1,70 +1,12 @@
-//! Argument error type for use with lexarg
+//! Error type for use with lexarg
 //!
 //! Inspired by [lexopt](https://crates.io/crates/lexopt), `lexarg` simplifies the formula down
 //! further so it can be used for CLI plugin systems.
 //!
 //! ## Example
-//! ```no_run
-//! use lexarg_error::Error;
-//! use lexarg_error::Result;
-//!
-//! struct Args {
-//!     thing: String,
-//!     number: u32,
-//!     shout: bool,
-//! }
-//!
-//! fn parse_args() -> Result<Args> {
-//!     use lexarg::Arg::*;
 //!
-//!     let mut thing = None;
-//!     let mut number = 1;
-//!     let mut shout = false;
-//!     let mut raw = std::env::args_os().collect::<Vec<_>>();
-//!     let mut parser = lexarg::Parser::new(&raw);
-//!     parser.bin();
-//!     while let Some(arg) = parser.next() {
-//!         match arg {
-//!             Short('n') | Long("number") => {
-//!                 number = parser
-//!                     .flag_value().ok_or_else(|| Error::msg("`--number` requires a value"))?
-//!                     .to_str().ok_or_else(|| Error::msg("invalid number"))?
-//!                     .parse().map_err(|e| Error::msg(e))?;
-//!             }
-//!             Long("shout") => {
-//!                 shout = true;
-//!             }
-//!             Value(val) if thing.is_none() => {
-//!                 thing = Some(val.to_str().ok_or_else(|| Error::msg("invalid number"))?);
-//!             }
-//!             Long("help") => {
-//!                 println!("Usage: hello [-n|--number=NUM] [--shout] THING");
-//!                 std::process::exit(0);
-//!             }
-//!             _ => {
-//!                 return Err(Error::msg("unexpected argument"));
-//!             }
-//!         }
-//!     }
-//!
-//!     Ok(Args {
-//!         thing: thing.ok_or_else(|| Error::msg("missing argument THING"))?.to_owned(),
-//!         number,
-//!         shout,
-//!     })
-//! }
-//!
-//! fn main() -> Result<()> {
-//!     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(())
-//! }
+//! ```no_run
+#![doc = include_str!("../examples/hello-error.rs")]
 //! ```
 
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
@@ -77,55 +19,10 @@
 #[cfg(doctest)]
 pub struct ReadmeDoctests;
 
-/// `Result<T, Error>`
-///
-/// `lexarg_error::Result` may be used with one *or* two type parameters.
-///
-/// ```rust
-/// use lexarg_error::Result;
-///
-/// # const IGNORE: &str = stringify! {
-/// fn demo1() -> Result<T> {...}
-///            // ^ equivalent to std::result::Result<T, lexarg_error::Error>
-///
-/// fn demo2() -> Result<T, OtherError> {...}
-///            // ^ equivalent to std::result::Result<T, OtherError>
-/// # };
-/// ```
-///
-/// # Example
-///
-/// ```
-/// # pub trait Deserialize {}
-/// #
-/// # mod serde_json {
-/// #     use super::Deserialize;
-/// #     use std::io;
-/// #
-/// #     pub fn from_str<T: Deserialize>(json: &str) -> io::Result<T> {
-/// #         unimplemented!()
-/// #     }
-/// # }
-/// #
-/// # #[derive(Debug)]
-/// # struct ClusterMap;
-/// #
-/// # impl Deserialize for ClusterMap {}
-/// #
-/// use lexarg_error::Result;
-///
-/// fn main() -> Result<()> {
-///     # return Ok(());
-///     let config = std::fs::read_to_string("cluster.json")?;
-///     let map: ClusterMap = serde_json::from_str(&config)?;
-///     println!("cluster info: {:#?}", map);
-///     Ok(())
-/// }
-/// ```
+/// `Result` that defaults to [`Error`]
 pub type Result<T, E = Error> = std::result::Result<T, E>;
 
 /// Argument error type for use with lexarg
-#[derive(Debug)]
 pub struct Error {
     msg: String,
 }
@@ -137,24 +34,105 @@ impl Error {
     where
         M: std::fmt::Display,
     {
-        Error {
+        Self {
             msg: message.to_string(),
         }
     }
 }
 
-impl<E> From<E> for Error
+impl From<ErrorContext<'_>> for Error {
+    #[cold]
+    fn from(error: ErrorContext<'_>) -> Self {
+        Self::msg(error.to_string())
+    }
+}
+
+impl std::fmt::Debug for Error {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.msg.fmt(formatter)
+    }
+}
+
+impl std::fmt::Display for Error {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.msg.fmt(formatter)
+    }
+}
+
+/// Collect context for creating an [`Error`]
+#[derive(Debug)]
+pub struct ErrorContext<'a> {
+    msg: String,
+    within: Option<lexarg::Arg<'a>>,
+    unexpected: Option<lexarg::Arg<'a>>,
+}
+
+impl<'a> ErrorContext<'a> {
+    /// Create a new error object from a printable error message.
+    #[cold]
+    pub fn msg<M>(message: M) -> Self
+    where
+        M: std::fmt::Display,
+    {
+        Self {
+            msg: message.to_string(),
+            within: None,
+            unexpected: None,
+        }
+    }
+
+    /// [`Arg`][lexarg::Arg] the error occurred within
+    #[cold]
+    pub fn within(mut self, within: lexarg::Arg<'a>) -> Self {
+        self.within = Some(within);
+        self
+    }
+
+    /// The failing [`Arg`][lexarg::Arg]
+    #[cold]
+    pub fn unexpected(mut self, unexpected: lexarg::Arg<'a>) -> Self {
+        self.unexpected = Some(unexpected);
+        self
+    }
+}
+
+impl<E> From<E> for ErrorContext<'_>
 where
     E: std::error::Error + Send + Sync + 'static,
 {
     #[cold]
     fn from(error: E) -> Self {
-        Error::msg(error)
+        Self::msg(error)
     }
 }
 
-impl std::fmt::Display for Error {
+impl std::fmt::Display for ErrorContext<'_> {
     fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        self.msg.fmt(formatter)
+        self.msg.fmt(formatter)?;
+        if let Some(unexpected) = &self.unexpected {
+            write!(formatter, ", found `")?;
+            match unexpected {
+                lexarg::Arg::Short(short) => write!(formatter, "-{short}")?,
+                lexarg::Arg::Long(long) => write!(formatter, "--{long}")?,
+                lexarg::Arg::Escape(value) => write!(formatter, "{value}")?,
+                lexarg::Arg::Value(value) | lexarg::Arg::Unexpected(value) => {
+                    write!(formatter, "{}", value.to_string_lossy())?;
+                }
+            }
+            write!(formatter, "`")?;
+        }
+        if let Some(within) = &self.within {
+            write!(formatter, " when parsing `")?;
+            match within {
+                lexarg::Arg::Short(short) => write!(formatter, "-{short}")?,
+                lexarg::Arg::Long(long) => write!(formatter, "--{long}")?,
+                lexarg::Arg::Escape(value) => write!(formatter, "{value}")?,
+                lexarg::Arg::Value(value) | lexarg::Arg::Unexpected(value) => {
+                    write!(formatter, "{}", value.to_string_lossy())?;
+                }
+            }
+            write!(formatter, "`")?;
+        }
+        Ok(())
     }
 }