cornerlibstone 0.1.0

Lib Cornerstone — a zero-dependency foundation for building command-line tools in Rust: argument parsing, nested subcommands, themeable help in multiple presets, structured errors and exit codes, config loading, interactive prompts, shell-completion and man/markdown generation, logging, JSON output, and root/destructive-operation guards.
Documentation
//! Zero-dependency argument parser.
//!
//! Given a [`Command`] spec and the raw arguments, produces [`Matches`]: the
//! resolved positional values and flag values. Supports:
//!
//! * `--long value` and `--long=value`
//! * `-s value` and `-svalue`
//! * bundled boolean shorts: `-abc` == `-a -b -c`
//! * `--` to stop flag parsing; everything after is positional
//! * variadic trailing positionals
//!
//! Parse errors are [`crate::error::Error`] with the `USAGE` exit code.

use crate::error::{Error, Result};
use crate::spec::{Command, FlagKind};
use std::collections::HashMap;

/// The result of parsing: flag values and positional arguments by name.
#[derive(Debug, Default, Clone)]
pub struct Matches {
    bools: HashMap<String, bool>,
    values: HashMap<String, String>,
    positionals: HashMap<String, Vec<String>>,
}

impl Matches {
    /// Whether a boolean switch was present.
    pub fn flag(&self, long: &str) -> bool {
        self.bools.get(long).copied().unwrap_or(false)
    }

    /// The value of a value-flag, if present (or its default).
    pub fn value(&self, long: &str) -> Option<&str> {
        self.values.get(long).map(|s| s.as_str())
    }

    /// A required positional; errors if missing.
    pub fn arg(&self, name: &str) -> Result<&str> {
        self.positionals
            .get(name)
            .and_then(|v| v.first())
            .map(|s| s.as_str())
            .ok_or_else(|| Error::usage(format!("missing required argument <{}>", name)))
    }

    /// An optional positional.
    pub fn arg_opt(&self, name: &str) -> Option<&str> {
        self.positionals.get(name).and_then(|v| v.first()).map(|s| s.as_str())
    }

    /// All values of a variadic positional.
    pub fn args(&self, name: &str) -> Vec<String> {
        self.positionals.get(name).cloned().unwrap_or_default()
    }
}

/// Parse `raw` against `cmd`. `raw` should exclude the program name and the
/// subcommand token (i.e. just the arguments to this command).
pub fn parse(cmd: &Command, raw: &[String]) -> Result<Matches> {
    let mut m = Matches::default();

    // Seed defaults for value-flags.
    for f in &cmd.flags {
        if let Some(d) = &f.default {
            m.values.insert(f.long.clone(), d.clone());
        }
        if f.kind == FlagKind::Bool {
            m.bools.insert(f.long.clone(), false);
        }
    }

    let mut positional_values: Vec<String> = Vec::new();
    let mut i = 0;
    let mut no_more_flags = false;

    while i < raw.len() {
        let tok = &raw[i];

        if no_more_flags {
            positional_values.push(tok.clone());
            i += 1;
            continue;
        }

        if tok == "--" {
            no_more_flags = true;
            i += 1;
            continue;
        }

        if let Some(rest) = tok.strip_prefix("--") {
            // Long flag, possibly --key=value.
            let (name, inline_val) = match rest.split_once('=') {
                Some((k, v)) => (k, Some(v.to_string())),
                None => (rest, None),
            };
            let flag = cmd
                .flags
                .iter()
                .find(|f| f.long == name)
                .ok_or_else(|| Error::usage(format!("unknown flag --{}", name)))?;
            match flag.kind {
                FlagKind::Bool => {
                    if inline_val.is_some() {
                        return Err(Error::usage(format!("flag --{} takes no value", name)));
                    }
                    m.bools.insert(flag.long.clone(), true);
                }
                FlagKind::Value => {
                    let val = if let Some(v) = inline_val {
                        v
                    } else {
                        i += 1;
                        raw.get(i)
                            .cloned()
                            .ok_or_else(|| Error::usage(format!("flag --{} needs a value", name)))?
                    };
                    m.values.insert(flag.long.clone(), val);
                }
            }
            i += 1;
            continue;
        }

        if tok.len() > 1 && tok.starts_with('-') && tok != "-" {
            // Short flag(s). Could be bundled bools, or -s value, or -svalue.
            let chars: Vec<char> = tok[1..].chars().collect();
            let mut consumed_value = false;
            for (ci, c) in chars.iter().enumerate() {
                let flag = cmd
                    .flags
                    .iter()
                    .find(|f| f.short == Some(*c))
                    .ok_or_else(|| Error::usage(format!("unknown flag -{}", c)))?;
                match flag.kind {
                    FlagKind::Bool => {
                        m.bools.insert(flag.long.clone(), true);
                    }
                    FlagKind::Value => {
                        // The rest of this token is the value, if any; otherwise
                        // the next token.
                        let remainder: String = chars[ci + 1..].iter().collect();
                        let val = if !remainder.is_empty() {
                            remainder
                        } else {
                            i += 1;
                            raw.get(i).cloned().ok_or_else(|| {
                                Error::usage(format!("flag -{} needs a value", c))
                            })?
                        };
                        m.values.insert(flag.long.clone(), val);
                        consumed_value = true;
                        break;
                    }
                }
            }
            let _ = consumed_value;
            i += 1;
            continue;
        }

        // Bare positional.
        positional_values.push(tok.clone());
        i += 1;
    }

    // Bind positionals to their declared names.
    let mut pv = positional_values.into_iter();
    for (idx, arg) in cmd.args.iter().enumerate() {
        if arg.variadic {
            let rest: Vec<String> = pv.by_ref().collect();
            if arg.required && rest.is_empty() {
                return Err(Error::usage(format!(
                    "missing required argument <{}>",
                    arg.name
                )));
            }
            m.positionals.insert(arg.name.clone(), rest);
            break;
        }
        match pv.next() {
            Some(v) => {
                m.positionals.insert(arg.name.clone(), vec![v]);
            }
            None => {
                if arg.required {
                    return Err(Error::usage(format!(
                        "missing required argument <{}>",
                        arg.name
                    )));
                }
            }
        }
        let _ = idx;
    }

    // Any leftover positionals are an error (unless the last arg was variadic,
    // in which case we already consumed them).
    let leftover: Vec<String> = pv.collect();
    if !leftover.is_empty() {
        return Err(Error::usage(format!(
            "unexpected argument(s): {}",
            leftover.join(" ")
        )));
    }

    Ok(m)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::spec::{Arg, Command, Flag};

    fn cmd() -> Command {
        let mut c = Command::new("t");
        c.args.push(Arg::new("name"));
        c.args.push(Arg::new("extra").optional());
        c.flags.push(Flag::switch("verbose").short('v'));
        c.flags.push(Flag::value("output").short('o'));
        c
    }

    fn parse_ok(raw: &[&str]) -> Matches {
        let owned: Vec<String> = raw.iter().map(|s| s.to_string()).collect();
        parse(&cmd(), &owned).expect("should parse")
    }

    #[test]
    fn positional_required_and_optional() {
        let m = parse_ok(&["alice"]);
        assert_eq!(m.arg("name").unwrap(), "alice");
        assert!(m.arg_opt("extra").is_none());
        let m = parse_ok(&["alice", "bob"]);
        assert_eq!(m.arg_opt("extra"), Some("bob"));
    }

    #[test]
    fn missing_required_is_usage_error() {
        let e = parse(&cmd(), &[]).unwrap_err();
        assert_eq!(e.code, crate::error::codes::USAGE);
    }

    #[test]
    fn long_flag_space_and_equals() {
        assert_eq!(parse_ok(&["x", "--output", "f"]).value("output"), Some("f"));
        assert_eq!(parse_ok(&["x", "--output=f"]).value("output"), Some("f"));
    }

    #[test]
    fn short_flag_space_and_attached() {
        assert_eq!(parse_ok(&["x", "-o", "f"]).value("output"), Some("f"));
        assert_eq!(parse_ok(&["x", "-of"]).value("output"), Some("f"));
    }

    #[test]
    fn bool_switch() {
        assert!(parse_ok(&["x", "-v"]).flag("verbose"));
        assert!(parse_ok(&["x", "--verbose"]).flag("verbose"));
        assert!(!parse_ok(&["x"]).flag("verbose"));
    }

    #[test]
    fn double_dash_stops_flags() {
        let m = parse_ok(&["x", "--", "-v"]);
        // -v after -- is positional, so it fills `extra`
        assert_eq!(m.arg_opt("extra"), Some("-v"));
        assert!(!m.flag("verbose"));
    }

    #[test]
    fn unknown_flag_errors() {
        let owned = vec!["x".to_string(), "--nope".to_string()];
        assert_eq!(parse(&cmd(), &owned).unwrap_err().code, crate::error::codes::USAGE);
    }

    #[test]
    fn value_flag_missing_value_errors() {
        let owned = vec!["x".to_string(), "--output".to_string()];
        assert!(parse(&cmd(), &owned).is_err());
    }

    #[test]
    fn variadic_collects_rest() {
        let mut c = Command::new("t");
        c.args.push(Arg::new("items").variadic());
        let owned: Vec<String> = ["a", "b", "c"].iter().map(|s| s.to_string()).collect();
        let m = parse(&c, &owned).unwrap();
        assert_eq!(m.args("items"), vec!["a", "b", "c"]);
    }

    #[test]
    fn too_many_positionals_errors() {
        let owned: Vec<String> = ["a", "b", "c"].iter().map(|s| s.to_string()).collect();
        assert!(parse(&cmd(), &owned).is_err());
    }

    #[test]
    fn default_value_applied() {
        let mut c = Command::new("t");
        c.flags.push(Flag::value("mode").default("fast"));
        let m = parse(&c, &[]).unwrap();
        assert_eq!(m.value("mode"), Some("fast"));
    }
}