shift 0.3.0

#![deny(missing_docs)]
//! Parsing command line arguments
//!
//! Call [`parse`] to get a [`Bag`] from which options, flags and operands may be extracted.
//!
//! ## Supported syntax
//!
//! GNU-style command line invocations like the following are supported:
//!
//! ```text
//! exe commit --verbose --level=info --message message
//! exe -v -l=info -m message
//! ```
//!
//! Anything prefixed with a `-` or `--` is treated as an option or flag.
//! The following command lines are equivalent:
//! ```text
//! exe -one -two -3
//! exe --one --two --3
//! ```
//!
//! After parsing this, you'll be able to extract three flags: `one`, `two` and `3`.
//!
//! The end of options marker `--` is respected.
//! Any arguments that come after it are treated as operands (i.e. positional arguments)
//!
//! While the order the command line arguments appear in is irrelevant, the order in which you extract them is.
//! In particular, when a switch is followed by a value, it is ambiguous whether it should be treated as an option or a flag.
//! The order in which methods are called resolves this ambiguity:
//!
//! ```
//! // Treated as a flag followed by a positional argument
//! let mut bag = shift::parse(vec![
//!     String::from("program"),
//!     String::from("--option"),
//!     String::from("value")
//! ]).unwrap();
//! assert_eq!(bag.shift_flag("option"), true);
//! assert_eq!(bag.shift_operand().as_deref(), Some("value"));
//! assert!(bag.is_empty());
//!
//! // Treated as an option
//! let mut bag = shift::parse(vec![
//!     String::from("program"),
//!     String::from("--option"),
//!     String::from("value")
//! ]).unwrap();
//! assert_eq!(bag.shift_option("option").as_deref(), Some("value"));
//! assert!(bag.is_empty());
//! ```

use std::fmt::Display;

/// Parsed command line arguments
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Bag {
    program_name: String,
    entries: Vec<Entry>,
}

#[derive(Debug, Clone, PartialEq, Eq, Default)]
enum Entry {
    #[default]
    Empty,
    LongSwitch(String, Option<String>),
    ShortSwitch(String, Option<String>),
    Operand(String),
}
/// A command line parsing error
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ParseError {
    /// The list of command line arguments was not at lest 1 element long
    MissingProgramName,
    /// Encountered an option withuot a name (e.g. `--=value`)
    InvalidSwitch(String),
}

/// Parses the given command line arguments into a [bag](crate::Bag)
pub fn parse(args: Vec<String>) -> Result<Bag, ParseError> {
    let mut saw_end_of_options = false;
    let mut entries: Vec<Entry> = Vec::new();

    let mut iter = args.into_iter();

    let Some(program_name) = iter.next() else {
        return Err(ParseError::MissingProgramName);
    };

    for arg in iter {
        if saw_end_of_options || arg == "-" {
            entries.push(Entry::Operand(arg));
            continue;
        }

        if arg == "--" {
            entries.push(Entry::Operand(arg));
            saw_end_of_options = true;
            continue;
        }

        if let Some(value) = arg.strip_prefix("--") {
            if let Some((name, value)) = value.split_once('=') {
                if name.is_empty() {
                    return Err(ParseError::InvalidSwitch(arg));
                }
                entries.push(Entry::LongSwitch(
                    String::from(name),
                    Some(String::from(value)),
                ));
            } else {
                entries.push(Entry::LongSwitch(String::from(value), None));
            }
            continue;
        }

        if let Some(value) = arg.strip_prefix("-") {
            if let Some((name, value)) = value.split_once('=') {
                if name.is_empty() {
                    return Err(ParseError::InvalidSwitch(arg));
                }

                entries.push(Entry::ShortSwitch(
                    String::from(name),
                    Some(String::from(value)),
                ));
            } else {
                entries.push(Entry::ShortSwitch(String::from(value), None));
            }
            continue;
        }

        entries.push(Entry::Operand(arg));
    }

    Ok(Bag {
        program_name,
        entries,
    })
}

impl Bag {
    /// Returns `true` when there are no more flags, options or positional arguments left.
    pub fn is_empty(&self) -> bool {
        self.entries.iter().all(|e| *e == Entry::Empty)
    }

    /// Removes the first flag with the given name from the bag if it exists.
    pub fn shift_flag(&mut self, name: &str) -> bool {
        for entry in self.entries.iter_mut() {
            if let Entry::LongSwitch(n, None) | Entry::ShortSwitch(n, None) = entry {
                if n != name {
                    continue;
                }

                *entry = Entry::Empty;
                return true;
            };
        }
        false
    }

    /// Removes the next positional argument that has the given value
    ///
    /// This is useful for extracting cli commands
    pub fn shift_operand_with_value(&mut self, expected_value: &str) -> bool {
        for entry in self.entries.iter_mut() {
            if let Entry::Operand(val) = entry {
                if val != expected_value {
                    continue;
                }

                *entry = Entry::Empty;
                return true;
            }
        }

        false
    }

    /// Removes the next positional argument from the argument bag, if any.
    ///
    /// Positional arguments are removed in the order they were supplied.
    /// Anything after the end-of-options marker counts as a positional argument.
    /// Note that the end-of-options marker itself will be returned by this method.
    pub fn shift_operand(&mut self) -> Option<String> {
        for entry in self.entries.iter_mut() {
            if let Entry::Operand(val) = entry {
                let value = std::mem::take(val);
                *entry = Entry::Empty;
                return Some(value);
            }
        }
        None
    }

    /// Removes the first option with the given `name` and returns its value.
    pub fn shift_option(&mut self, name: &str) -> Option<String> {
        for i in 0..self.entries.len() {
            match &mut self.entries[i] {
                // --n=val or -n=val
                Entry::LongSwitch(n, Some(val)) | Entry::ShortSwitch(n, Some(val)) => {
                    if n != name {
                        continue;
                    }

                    let value = std::mem::take(val);
                    self.entries[i] = Entry::Empty;

                    return Some(value);
                }
                // --n val or // -n val
                Entry::LongSwitch(n, None) | Entry::ShortSwitch(n, None) => {
                    if n != name {
                        continue;
                    }

                    let Some(Entry::Operand(val)) = self.entries.get_mut(i + 1) else {
                        continue;
                    };

                    let value = std::mem::take(val);

                    self.entries[i] = Entry::Empty;
                    self.entries[i + 1] = Entry::Empty;

                    return Some(value);
                }
                _ => continue,
            }
        }

        None
    }

    /// Returns the name of the executing program
    pub fn program_name(&self) -> &str {
        self.program_name.as_str()
    }

    /// Removes any leftover flags, options and operands that have not been `shift*`-ed.
    ///
    /// Subsequent calls will return an empty slice
    pub fn shift_remaining(&mut self) -> Vec<String> {
        let mut result = Vec::new();
        for entry in self.entries.iter_mut() {
            if *entry == Entry::Empty {
                continue;
            }

            result.push(entry.to_string());
            *entry = Entry::Empty;
        }
        result
    }
}

impl Display for Entry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Entry::Empty => Ok(()),
            Entry::LongSwitch(name, Some(value)) => write!(f, "--{name}={value}"),
            Entry::ShortSwitch(name, Some(value)) => write!(f, "-{name}={value}"),
            Entry::LongSwitch(name, None) => write!(f, "--{name}"),
            Entry::ShortSwitch(name, None) => write!(f, "-{name}"),
            Entry::Operand(value) => write!(f, "{value}"),
        }
    }
}

impl Display for ParseError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::MissingProgramName => write!(
                f,
                "empty list of command line arguments; must have at least one element that corresponds to the executable name"
            ),
            Self::InvalidSwitch(invalid) => write!(f, "option without a name: `{invalid}`"),
        }
    }
}

impl std::error::Error for ParseError {}

#[cfg(test)]
mod tests {
    use super::*;

    #[track_caller]
    fn args<const N: usize>(arr: [&str; N]) -> Vec<String> {
        arr.iter().map(|s| s.to_string()).collect()
    }

    #[test]
    fn missing_exe_name() {
        let result = parse(args([]));
        assert_eq!(result, Err(ParseError::MissingProgramName));
    }

    #[test]
    fn malformed_option() {
        let result = parse(args(["program", "--=value"]));
        assert_eq!(
            result,
            Err(ParseError::InvalidSwitch(String::from("--=value")))
        );

        let result = parse(args(["program", "-=value"]));
        assert_eq!(
            result,
            Err(ParseError::InvalidSwitch(String::from("-=value")))
        );
    }

    #[test]
    fn shift_eql_separated_options() {
        let mut bag = parse(args(["program", "--opt1=val1", "-opt2=val2"])).unwrap();
        assert!(!bag.is_empty());
        assert_eq!(bag.shift_option("opt1").as_deref(), Some("val1"));
        assert_eq!(bag.shift_option("opt2").as_deref(), Some("val2"));
        assert_eq!(bag.shift_option("opt2"), None);
        assert!(bag.is_empty());
    }

    #[test]
    fn shift_space_separated_options() {
        let mut bag = parse(args(["program", "--opt1", "val1", "-opt2", "val2"])).unwrap();
        assert_eq!(bag.shift_option("opt1").as_deref(), Some("val1"));
        assert_eq!(bag.shift_option("opt2").as_deref(), Some("val2"));
        assert_eq!(bag.shift_option("opt2"), None);
        assert!(bag.is_empty());
    }

    #[test]
    fn shift_option_does_not_remove_flags() {
        let mut bag = parse(args(["program", "--switch", "--switch", "value"])).unwrap();
        assert_eq!(bag.shift_option("switch").as_deref(), Some("value"));
        assert!(bag.shift_flag("switch"));
        assert!(bag.is_empty());
    }

    #[test]
    fn shift_option_returns_multiple_values() {
        let mut bag = parse(args(["program", "--opt", "value", "--opt=value2"])).unwrap();
        assert_eq!(bag.shift_option("opt").as_deref(), Some("value"));
        assert_eq!(bag.shift_option("opt").as_deref(), Some("value2"));
        assert_eq!(bag.shift_option("opt"), None);
    }

    #[test]
    fn shifting_the_same_flag_multiple_times() {
        let mut bag = parse(args(["prgoram", "--flag", "--flag"])).unwrap();
        assert!(bag.shift_flag("flag"));
        assert!(bag.shift_flag("flag"));
        assert!(!bag.shift_flag("flag"));
        assert!(bag.is_empty());
    }

    #[test]
    fn shift_operand() {
        let mut bag = parse(args(["program", "-", "a", "b", "--", "c", "--", "-foo"])).unwrap();
        assert!(!bag.is_empty());
        assert_eq!(bag.shift_operand().as_deref(), Some("-"));
        assert_eq!(bag.shift_operand().as_deref(), Some("a"));
        assert_eq!(bag.shift_operand().as_deref(), Some("b"));
        assert_eq!(bag.shift_operand().as_deref(), Some("--"));
        assert_eq!(bag.shift_operand().as_deref(), Some("c"));
        assert_eq!(bag.shift_operand().as_deref(), Some("--"));
        assert_eq!(bag.shift_operand().as_deref(), Some("-foo"));
        assert_eq!(bag.shift_operand(), None);
        assert!(bag.is_empty());
    }

    #[test]
    fn resolving_operand_ambiguity() {
        let mut bag = parse(args(["program", "--flag", "operand"])).unwrap();
        assert_eq!(bag.shift_operand().as_deref(), Some("operand"));
        assert_eq!(bag.shift_option("flag"), None);
        assert!(bag.shift_flag("flag"));
        assert!(bag.is_empty());

        let mut bag = parse(args(["program", "--flag", "operand"])).unwrap();
        assert_eq!(bag.shift_option("flag").as_deref(), Some("operand"));
        assert_eq!(bag.shift_operand(), None);
        assert!(bag.is_empty());
    }

    #[test]
    fn shifting_remaining_arguments() {
        let mut bag = parse(args(["program", "-", "a", "b", "--", "c"])).unwrap();

        assert_eq!(bag.shift_operand().as_deref(), Some("-"));
        assert_eq!(
            bag.shift_remaining(),
            vec![
                String::from("a"),
                String::from("b"),
                String::from("--"),
                String::from("c")
            ]
        );
        assert!(bag.is_empty());
    }

    #[test]
    fn shift_operand_with_value() {
        let mut bag = parse(args(["program", "a", "b"])).unwrap();
        assert!(bag.shift_operand_with_value("b"));
        assert!(bag.shift_operand_with_value("a"));
        assert!(bag.is_empty());
    }
}

#[cfg(doctest)]
#[doc = include_str!("README.md")]
struct ReadmeDocTest;