cli_command/

command.rs

use crate::cli_error::{CliError, CliErrorKind};
use std::collections::HashMap;

/// Represents a parsed command with its name and arguments.
///
/// The `Command` struct holds the parsed command-line arguments in a structured format.
/// It provides convenient methods for accessing arguments with type conversion and error handling.
///
/// # Examples
///
/// ```rust
/// use cli_command::{Command, parse_command_string};
///
/// let cmd = parse_command_string("serve --port 8080 --host localhost").unwrap();
/// assert_eq!(cmd.name, "serve");
/// assert_eq!(cmd.get_argument("port"), Some("8080"));
/// assert_eq!(cmd.get_argument("host"), Some("localhost"));
/// ```
#[derive(Debug, Clone)]
pub struct Command {
    /// The command name (first non-flag argument)
    pub name: String,
    /// Parsed arguments as a map of argument names to their values
    pub arguments: HashMap<String, Box<[String]>>,
}

impl Command {
    /// Gets the nth parameter of an argument as a `usize`, if it exists and can be parsed.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    /// * `nth` - The zero-based index of the parameter
    ///
    /// # Returns
    /// * `Some(usize)` - If the parameter exists and can be parsed as a usize
    /// * `None` - If the argument doesn't exist or the parameter can't be parsed
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--numbers 1 2 3").unwrap();
    /// assert_eq!(cmd.get_argument_nth_parameter_usize("numbers", 0), Some(1));
    /// assert_eq!(cmd.get_argument_nth_parameter_usize("numbers", 1), Some(2));
    /// assert_eq!(cmd.get_argument_nth_parameter_usize("numbers", 5), None);
    /// ```
    pub fn get_argument_nth_parameter_usize(&self, argument: &str, nth: usize) -> Option<usize> {
        match self.arguments.get(argument) {
            Some(params) if params.len() > nth => usize::from_str_radix(&params[nth], 10).ok(),
            _ => None,
        }
    }

    /// Gets the nth parameter of an argument as a string slice, if it exists.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    /// * `nth` - The zero-based index of the parameter
    ///
    /// # Returns
    /// * `Some(&str)` - If the parameter exists
    /// * `None` - If the argument doesn't exist or the parameter is out of bounds
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--files a.txt b.txt c.txt").unwrap();
    /// assert_eq!(cmd.get_argument_nth_parameter("files", 0), Some("a.txt"));
    /// assert_eq!(cmd.get_argument_nth_parameter("files", 1), Some("b.txt"));
    /// assert_eq!(cmd.get_argument_nth_parameter("files", 5), None);
    /// ```
    pub fn get_argument_nth_parameter(&self, argument: &str, nth: usize) -> Option<&str> {
        match self.arguments.get(argument) {
            Some(params) if params.len() > nth => Some(&params[nth]),
            _ => None,
        }
    }

    /// Gets the nth parameter of an argument as a string slice, returning an error if missing.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    /// * `nth` - The zero-based index of the parameter
    ///
    /// # Returns
    /// * `Ok(&str)` - If the parameter exists
    /// * `Err(CliError)` - If the argument or parameter is missing
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--files a.txt b.txt").unwrap();
    /// assert_eq!(cmd.get_argument_nth_param_mandatory("files", 0).unwrap(), "a.txt");
    /// assert_eq!(cmd.get_argument_nth_param_mandatory("files", 1).unwrap(), "b.txt");
    /// ```
    pub fn get_argument_nth_param_mandatory(
        &self,
        argument: &str,
        nth: usize,
    ) -> Result<&str, CliError> {
        let params = self.get_argument_mandatory_all(argument)?;
        if params.len() > nth {
            Ok(&params[nth])
        } else if nth > 0 {
            Err(CliErrorKind::MissingParameter(argument.to_string(), nth).into())
        } else {
            Err(CliErrorKind::MissingArgument(argument.to_string()).into())
        }
    }

    /// Gets the nth parameter of an argument as a `usize`, returning an error if missing or invalid.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    /// * `nth` - The zero-based index of the parameter
    ///
    /// # Returns
    /// * `Ok(usize)` - If the parameter exists and can be parsed
    /// * `Err(CliError)` - If the argument is missing or the parameter can't be parsed
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--numbers 1 2 3").unwrap();
    /// assert_eq!(cmd.get_argument_nth_param_mandatory_usize("numbers", 0).unwrap(), 1);
    /// assert_eq!(cmd.get_argument_nth_param_mandatory_usize("numbers", 1).unwrap(), 2);
    /// ```
    pub fn get_argument_nth_param_mandatory_usize(
        &self,
        argument: &str,
        nth: usize,
    ) -> Result<usize, CliError> {
        let param = self.get_argument_nth_param_mandatory(argument, nth)?;
        Ok(usize::from_str_radix(param, 10)?)
    }

    /// Checks if an argument exists (regardless of whether it has values).
    ///
    /// # Arguments
    /// * `argument` - The name of the argument to check
    ///
    /// # Returns
    /// * `true` - If the argument exists
    /// * `false` - If the argument doesn't exist
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--verbose --port 8080").unwrap();
    /// assert!(cmd.contains_argument("verbose"));
    /// assert!(cmd.contains_argument("port"));
    /// assert!(!cmd.contains_argument("debug"));
    /// ```
    pub fn contains_argument(&self, argument: &str) -> bool {
        self.arguments.contains_key(argument)
    }

    /// Gets the first parameter of an argument as a string slice, if it exists.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    ///
    /// # Returns
    /// * `Some(&str)` - If the argument exists and has at least one parameter
    /// * `None` - If the argument doesn't exist or has no parameters
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--host localhost --port 8080").unwrap();
    /// assert_eq!(cmd.get_argument("host"), Some("localhost"));
    /// assert_eq!(cmd.get_argument("port"), Some("8080"));
    /// assert_eq!(cmd.get_argument("debug"), None);
    /// ```
    pub fn get_argument(&self, argument: &str) -> Option<&str> {
        self.get_argument_nth_parameter(argument, 0)
    }

    /// Gets the first parameter of an argument as a string slice, returning an error if missing.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    ///
    /// # Returns
    /// * `Ok(&str)` - If the argument exists and has at least one parameter
    /// * `Err(CliError)` - If the argument is missing
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--host localhost").unwrap();
    /// assert_eq!(cmd.get_argument_mandatory("host").unwrap(), "localhost");
    /// ```
    pub fn get_argument_mandatory(&self, argument: &str) -> Result<&str, CliError> {
        self.get_argument_nth_param_mandatory(argument, 0)
    }

    /// Gets the first parameter of an argument as a `usize`, returning an error if missing or invalid.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    ///
    /// # Returns
    /// * `Ok(usize)` - If the argument exists and can be parsed as a usize
    /// * `Err(CliError)` - If the argument is missing or can't be parsed
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--port 8080").unwrap();
    /// assert_eq!(cmd.get_argument_mandatory_usize("port").unwrap(), 8080);
    /// ```
    pub fn get_argument_mandatory_usize(&self, argument: &str) -> Result<usize, CliError> {
        let value = self.get_argument_mandatory(argument)?;
        Ok(usize::from_str_radix(value, 10)?)
    }

    /// Gets the first parameter of an argument as a `usize`, if it exists and can be parsed.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    ///
    /// # Returns
    /// * `Some(usize)` - If the argument exists and can be parsed as a usize
    /// * `None` - If the argument doesn't exist or can't be parsed
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--port 8080 --workers 4").unwrap();
    /// assert_eq!(cmd.get_argument_usize("port"), Some(8080));
    /// assert_eq!(cmd.get_argument_usize("workers"), Some(4));
    /// assert_eq!(cmd.get_argument_usize("debug"), None);
    /// ```
    pub fn get_argument_usize(&self, argument: &str) -> Option<usize> {
        match self.get_argument(argument) {
            Some(v) => match usize::from_str_radix(v, 10) {
                Ok(v) => Some(v),
                Err(_) => None,
            },
            None => None,
        }
    }

    /// Gets the first parameter of an argument as an `i32`, if it exists and can be parsed.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    ///
    /// # Returns
    /// * `Some(i32)` - If the argument exists and can be parsed as an i32
    /// * `None` - If the argument doesn't exist or can't be parsed
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--port 8080 --timeout 30").unwrap();
    /// assert_eq!(cmd.get_argument_i32("port"), Some(8080));
    /// assert_eq!(cmd.get_argument_i32("timeout"), Some(30));
    /// assert_eq!(cmd.get_argument_i32("debug"), None);
    /// ```
    pub fn get_argument_i32(&self, argument: &str) -> Option<i32> {
        match self.get_argument(argument) {
            Some(v) => v.parse().ok(),
            None => None,
        }
    }

    /// Gets the first parameter of an argument as a `f64`, if it exists and can be parsed.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    ///
    /// # Returns
    /// * `Some(f64)` - If the argument exists and can be parsed as an f64
    /// * `None` - If the argument doesn't exist or can't be parsed
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--ratio 0.5 --threshold 1.23").unwrap();
    /// assert_eq!(cmd.get_argument_f64("ratio"), Some(0.5));
    /// assert_eq!(cmd.get_argument_f64("threshold"), Some(1.23));
    /// assert_eq!(cmd.get_argument_f64("debug"), None);
    /// ```
    pub fn get_argument_f64(&self, argument: &str) -> Option<f64> {
        match self.get_argument(argument) {
            Some(v) => v.parse().ok(),
            None => None,
        }
    }

    /// Gets the first parameter of an argument as a `bool`, if it exists and can be parsed.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    ///
    /// # Returns
    /// * `Some(bool)` - If the argument exists and can be parsed as a bool
    /// * `None` - If the argument doesn't exist or can't be parsed
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--enabled true --disabled false").unwrap();
    /// assert_eq!(cmd.get_argument_bool("enabled"), Some(true));
    /// assert_eq!(cmd.get_argument_bool("disabled"), Some(false));
    /// assert_eq!(cmd.get_argument_bool("debug"), None);
    /// ```
    pub fn get_argument_bool(&self, argument: &str) -> Option<bool> {
        match self.get_argument(argument) {
            Some(v) => v.parse().ok(),
            None => None,
        }
    }

    /// Gets all parameters of an argument as a slice of strings, if it exists.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    ///
    /// # Returns
    /// * `Some(&Box<[String]>)` - If the argument exists
    /// * `None` - If the argument doesn't exist
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--files a.txt b.txt c.txt").unwrap();
    /// let files = cmd.get_argument_all("files").unwrap();
    /// assert_eq!(files.len(), 3);
    /// assert_eq!(&files[0], "a.txt");
    /// assert_eq!(&files[1], "b.txt");
    /// assert_eq!(&files[2], "c.txt");
    /// ```
    pub fn get_argument_all(&self, argument: &str) -> Option<&Box<[String]>> {
        self.arguments.get(argument)
    }

    /// Gets all parameters of an argument as a slice of strings, returning an error if missing.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    ///
    /// # Returns
    /// * `Ok(&Box<[String]>)` - If the argument exists
    /// * `Err(CliError)` - If the argument is missing
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--files a.txt b.txt").unwrap();
    /// let files = cmd.get_argument_mandatory_all("files").unwrap();
    /// assert_eq!(files.len(), 2);
    /// ```
    pub fn get_argument_mandatory_all(&self, argument: &str) -> Result<&Box<[String]>, CliError> {
        self.get_argument_all(argument)
            .ok_or(CliErrorKind::MissingArgument(argument.to_string()).into())
    }

    /// Gets the first parameter of an argument with type conversion, or returns a default value if missing.
    ///
    /// This method attempts to parse the argument value as the specified type `T`. If the argument
    /// is missing, it returns the provided default value instead of an error.
    ///
    /// # Arguments
    /// * `argument` - The name of the argument
    /// * `default` - The default value to return if the argument is missing
    ///
    /// # Returns
    /// * `Ok(T)` - If the argument exists and can be parsed, or if missing (returns default)
    /// * `Err(CliError)` - If the argument exists but can't be parsed as the target type
    ///
    /// # Examples
    /// ```rust
    /// use cli_command::{Command, parse_command_string};
    ///
    /// let cmd = parse_command_string("--port 8080").unwrap();
    /// let port: u16 = cmd.get_argument_or_default("port", 3000).unwrap();
    /// assert_eq!(port, 8080);
    ///
    /// let timeout: u64 = cmd.get_argument_or_default("timeout", 30).unwrap();
    /// assert_eq!(timeout, 30); // Uses default since timeout not provided
    /// ```
    pub fn get_argument_or_default<T>(&self, argument: &str, default: T) -> Result<T, CliError>
    where
        T: std::str::FromStr,
        T::Err: std::error::Error + Send + Sync + 'static,
    {
        match self.get_argument_mandatory(argument) {
            Ok(value) => T::from_str(value).map_err(|e| CliError::new_inner(Box::new(e))),
            Err(_) => Ok(default),
        }
    }
}

#[cfg(test)]
mod tests {
    use crate::cli_error::{CliError, CliErrorKind};
    use crate::parse::parse_command_string;
    use std::net::SocketAddr;
    use std::str::FromStr;

    #[test]
    fn test_get_argument_first_value_or_default() -> Result<(), CliError> {
        let cmd = parse_command_string("--socket 172.20.3.1:7618")?;
        assert_eq!(&cmd.arguments.get("socket").unwrap()[0], "172.20.3.1:7618");

        let socket =
            cmd.get_argument_or_default("socket", SocketAddr::from_str("127.0.0.1:1000")?)?;
        assert_eq!(socket, SocketAddr::from_str("172.20.3.1:7618")?);

        let cmd = parse_command_string("--streams 2")?;
        let streams = cmd.get_argument_or_default("streams", 5)?;
        assert_eq!(streams, 2);
        assert_eq!(cmd.get_argument_or_default("components", 5)?, 5);

        Ok(())
    }

    #[test]
    fn test_basic_argument_parsing() -> Result<(), CliError> {
        let cmd = parse_command_string("serve --port 8080 --host localhost --verbose")?;

        assert_eq!(cmd.name, "serve");
        assert_eq!(cmd.get_argument("port"), Some("8080"));
        assert_eq!(cmd.get_argument("host"), Some("localhost"));
        assert!(cmd.contains_argument("verbose"));
        assert!(!cmd.contains_argument("debug"));

        Ok(())
    }

    #[test]
    fn test_multiple_values() -> Result<(), CliError> {
        let cmd = parse_command_string("build --files a.txt b.txt c.txt --output dist/")?;

        assert_eq!(cmd.name, "build");
        let files = cmd.get_argument_all("files").unwrap();
        assert_eq!(files.len(), 3);
        assert_eq!(&files[0], "a.txt");
        assert_eq!(&files[1], "b.txt");
        assert_eq!(&files[2], "c.txt");
        assert_eq!(cmd.get_argument("output"), Some("dist/"));

        Ok(())
    }

    #[test]
    fn test_usize_conversion() -> Result<(), CliError> {
        let cmd = parse_command_string("--port 8080 --workers 4 --timeout 30")?;

        assert_eq!(cmd.get_argument_usize("port"), Some(8080));
        assert_eq!(cmd.get_argument_usize("workers"), Some(4));
        assert_eq!(cmd.get_argument_usize("timeout"), Some(30));
        assert_eq!(cmd.get_argument_usize("missing"), None);

        Ok(())
    }

    #[test]
    fn test_mandatory_arguments() -> Result<(), CliError> {
        let cmd = parse_command_string("--required value")?;

        assert_eq!(cmd.get_argument_mandatory("required")?, "value");

        let cmd = parse_command_string("")?;
        let result = cmd.get_argument_mandatory("missing");
        assert!(result.is_err());

        if let Err(CliError {
            kind: CliErrorKind::MissingArgument(arg),
            ..
        }) = result
        {
            assert_eq!(arg, "missing");
        } else {
            panic!("Expected MissingArgument error");
        }

        Ok(())
    }

    #[test]
    fn test_nth_parameter_access() -> Result<(), CliError> {
        let cmd = parse_command_string("--numbers 1 2 3 4 5")?;

        assert_eq!(cmd.get_argument_nth_parameter("numbers", 0), Some("1"));
        assert_eq!(cmd.get_argument_nth_parameter("numbers", 2), Some("3"));
        assert_eq!(cmd.get_argument_nth_parameter("numbers", 4), Some("5"));
        assert_eq!(cmd.get_argument_nth_parameter("numbers", 5), None);
        assert_eq!(cmd.get_argument_nth_parameter("missing", 0), None);

        Ok(())
    }

    #[test]
    fn test_nth_parameter_usize() -> Result<(), CliError> {
        let cmd = parse_command_string("--values 10 20 30")?;

        assert_eq!(cmd.get_argument_nth_parameter_usize("values", 0), Some(10));
        assert_eq!(cmd.get_argument_nth_parameter_usize("values", 1), Some(20));
        assert_eq!(cmd.get_argument_nth_parameter_usize("values", 2), Some(30));
        assert_eq!(cmd.get_argument_nth_parameter_usize("values", 3), None);
        assert_eq!(cmd.get_argument_nth_parameter_usize("missing", 0), None);

        Ok(())
    }

    #[test]
    fn test_mandatory_nth_parameter() -> Result<(), CliError> {
        let cmd = parse_command_string("--files a.txt b.txt c.txt")?;

        assert_eq!(cmd.get_argument_nth_param_mandatory("files", 0)?, "a.txt");
        assert_eq!(cmd.get_argument_nth_param_mandatory("files", 1)?, "b.txt");
        assert_eq!(cmd.get_argument_nth_param_mandatory("files", 2)?, "c.txt");

        let result = cmd.get_argument_nth_param_mandatory("files", 5);
        assert!(result.is_err());

        if let Err(CliError {
            kind: CliErrorKind::MissingParameter(arg, pos),
            ..
        }) = result
        {
            assert_eq!(arg, "files");
            assert_eq!(pos, 5);
        } else {
            panic!("Expected MissingParameter error");
        }

        Ok(())
    }

    #[test]
    fn test_mandatory_nth_parameter_usize() -> Result<(), CliError> {
        let cmd = parse_command_string("--numbers 1 2 3")?;

        assert_eq!(cmd.get_argument_nth_param_mandatory_usize("numbers", 0)?, 1);
        assert_eq!(cmd.get_argument_nth_param_mandatory_usize("numbers", 1)?, 2);
        assert_eq!(cmd.get_argument_nth_param_mandatory_usize("numbers", 2)?, 3);

        Ok(())
    }

    #[test]
    fn test_type_conversion_with_defaults() -> Result<(), CliError> {
        let cmd = parse_command_string("--port 8080")?;

        let port: u16 = cmd.get_argument_or_default("port", 3000)?;
        assert_eq!(port, 8080);

        let timeout: u64 = cmd.get_argument_or_default("timeout", 30)?;
        assert_eq!(timeout, 30); // Uses default

        let host: String = cmd.get_argument_or_default("host", "localhost".to_string())?;
        assert_eq!(host, "localhost"); // Uses default

        Ok(())
    }

    #[test]
    fn test_short_and_long_arguments() -> Result<(), CliError> {
        let cmd = parse_command_string("-v --verbose --port 8080 -h localhost")?;

        assert!(cmd.contains_argument("v"));
        assert!(cmd.contains_argument("verbose"));
        assert_eq!(cmd.get_argument("port"), Some("8080"));
        assert_eq!(cmd.get_argument("h"), Some("localhost"));

        Ok(())
    }

    #[test]
    fn test_boolean_flags() -> Result<(), CliError> {
        let cmd = parse_command_string("--enable-feature --no-cache --debug")?;

        assert!(cmd.contains_argument("enable-feature"));
        assert!(cmd.contains_argument("no-cache"));
        assert!(cmd.contains_argument("debug"));
        assert!(!cmd.contains_argument("missing"));

        Ok(())
    }

    #[test]
    fn test_empty_command() -> Result<(), CliError> {
        let cmd = parse_command_string("")?;

        assert_eq!(cmd.name, "");
        assert!(cmd.arguments.is_empty());

        Ok(())
    }

    #[test]
    fn test_command_without_arguments() -> Result<(), CliError> {
        let cmd = parse_command_string("help")?;

        assert_eq!(cmd.name, "help");
        assert!(cmd.arguments.is_empty());

        Ok(())
    }

    #[test]
    fn test_invalid_usize_parsing() -> Result<(), CliError> {
        let cmd = parse_command_string("--port abc --workers 123")?;

        assert_eq!(cmd.get_argument_usize("port"), None); // Invalid number
        assert_eq!(cmd.get_argument_usize("workers"), Some(123)); // Valid number
        assert_eq!(cmd.get_argument_usize("missing"), None); // Missing argument

        Ok(())
    }

    #[test]
    fn test_error_handling() -> Result<(), CliError> {
        let cmd = parse_command_string("--port 8080")?;

        let result = cmd.get_argument_mandatory("missing");
        assert!(result.is_err());

        let result = cmd.get_argument_nth_param_mandatory("port", 5);
        assert!(result.is_err());

        Ok(())
    }
}