bare_config/

key.rs

//! Key type for configuration path representation.
//!
//! This module provides the `Key` and `KeySegment` types for
//! representing paths to configuration values across all
//! supported configuration formats.

use core::fmt::Write;

use crate::error::{ConfigError, ConfigResult};
use nom::IResult;
use nom::Parser;
use nom::bytes::complete::take_while1;
use nom::character::complete::{char, digit1};
use nom::combinator::map_res;

fn parse_index_inner(input: &str) -> IResult<&str, usize> {
    map_res(digit1, |s: &str| s.parse::<usize>()).parse(input)
}

fn parse_key(input: &str) -> IResult<&str, String> {
    let (input, key) =
        take_while1(|c: char| c.is_ascii_alphanumeric() || c == '_' || c == '-')(input)?;
    Ok((input, key.to_string()))
}

fn parse_segment(input: &str) -> IResult<&str, KeySegment> {
    if let Ok((input, _)) = char::<&str, nom::error::Error<&str>>('[').parse(input) {
        let (input, idx) = parse_index_inner(input)?;
        let (input, _) = char::<&str, nom::error::Error<&str>>(']').parse(input)?;
        return Ok((input, KeySegment::Index(idx)));
    }

    if let Ok((input, _)) = char::<&str, nom::error::Error<&str>>('@').parse(input) {
        let (input, name) = parse_key(input)?;
        return Ok((input, KeySegment::Attribute(name)));
    }

    let (input, key) = parse_key(input)?;
    Ok((input, KeySegment::Key(key)))
}

fn parse_key_segments(input: &str) -> IResult<&str, Vec<KeySegment>> {
    // Pre-allocate: estimate capacity based on input length
    // Average segment length is ~5 chars, so divide by 5 as a rough estimate
    let estimated = std::cmp::max(1, input.len() / 5);
    let (input, first) = parse_segment(input)?;
    let mut segments = Vec::with_capacity(estimated);
    segments.push(first);
    let mut rest = input;

    while !rest.is_empty() {
        if let Ok((new_rest, _)) = char::<&str, nom::error::Error<&str>>('.').parse(rest) {
            let (new_rest, seg) = parse_segment(new_rest)?;
            segments.push(seg);
            rest = new_rest;
        } else if let Ok((new_rest, _)) = char::<&str, nom::error::Error<&str>>('[').parse(rest) {
            let (new_rest, idx) = parse_index_inner(new_rest)?;
            let (new_rest, _) = char::<&str, nom::error::Error<&str>>(']').parse(new_rest)?;
            segments.push(KeySegment::Index(idx));
            rest = new_rest;
        } else if let Ok((new_rest, _)) = char::<&str, nom::error::Error<&str>>('@').parse(rest) {
            let (new_rest, name) = parse_key(new_rest)?;
            segments.push(KeySegment::Attribute(name));
            rest = new_rest;
        } else {
            break;
        }
    }

    Ok((rest, segments))
}

fn parse_key_path(input: &str) -> IResult<&str, Vec<KeySegment>> {
    let input = if let Some(rest) = input.strip_prefix('.') {
        if rest.is_empty() {
            return Err(nom::Err::Error(nom::error::Error::new(
                input,
                nom::error::ErrorKind::Char,
            )));
        }
        rest
    } else {
        return Err(nom::Err::Error(nom::error::Error::new(
            input,
            nom::error::ErrorKind::Char,
        )));
    };
    parse_key_segments(input)
}

/// A segment of a configuration key path.
///
/// Key segments represent individual components of a key path:
/// - `Key`: A named field (e.g., `.database.url`)
/// - `Index`: An array index (e.g., `.items[0]`)
/// - `Attribute`: An attribute name (e.g., `@type`)
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum KeySegment {
    /// A named key segment.
    Key(String),
    /// An array index segment.
    Index(usize),
    /// An attribute name segment.
    Attribute(String),
}

impl KeySegment {
    /// Returns the key value if this is a key segment.
    #[must_use]
    pub fn as_key(&self) -> Option<&str> {
        match self {
            Self::Key(s) => Some(s),
            _ => None,
        }
    }

    /// Returns the index value if this is an index segment.
    #[must_use]
    pub const fn as_index(&self) -> Option<usize> {
        match self {
            Self::Index(i) => Some(*i),
            _ => None,
        }
    }

    /// Returns the attribute name if this is an attribute segment.
    #[must_use]
    pub fn as_attribute(&self) -> Option<&str> {
        match self {
            Self::Attribute(s) => Some(s),
            _ => None,
        }
    }

    /// Consumes this segment and returns the key value if it was a key segment.
    #[must_use]
    pub fn into_key(self) -> Option<String> {
        match self {
            Self::Key(s) => Some(s),
            _ => None,
        }
    }

    /// Consumes this segment and returns the index value if it was an index segment.
    #[must_use]
    pub fn into_index(self) -> Option<usize> {
        match self {
            Self::Index(i) => Some(i),
            _ => None,
        }
    }

    /// Consumes this segment and returns the attribute name if it was an attribute segment.
    #[must_use]
    pub fn into_attribute(self) -> Option<String> {
        match self {
            Self::Attribute(s) => Some(s),
            _ => None,
        }
    }
}

impl From<String> for KeySegment {
    fn from(s: String) -> Self {
        Self::Key(s)
    }
}

impl From<&str> for KeySegment {
    fn from(s: &str) -> Self {
        Self::Key(s.to_string())
    }
}

impl From<usize> for KeySegment {
    fn from(i: usize) -> Self {
        Self::Index(i)
    }
}

/// A configuration key path.
///
/// Keys represent paths to values in configuration files using
/// a dot-separated notation with support for array indices and attributes.
///
/// # Examples
///
/// ```
/// use bare_config::key::Key;
/// use std::str::FromStr;
///
/// let key = Key::from_str(".database.host").unwrap();
/// assert_eq!(key.segments().len(), 2);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
pub struct Key {
    segments: Vec<KeySegment>,
}

impl Key {
    #[allow(clippy::should_implement_trait)]
    /// Parse a key from a string path.
    ///
    /// # Errors
    ///
    /// Returns [`ConfigError::InvalidKey`] if the key format is invalid.
    pub fn from_str(s: &str) -> ConfigResult<Self> {
        let (_, segments) = parse_key_path(s)
            .map_err(|e| ConfigError::InvalidKey(format!("Parse error: {e:?}")))?;

        if segments.is_empty() {
            return Err(ConfigError::InvalidKey(
                "Key must have at least one segment".to_string(),
            ));
        }

        Ok(Self { segments })
    }

    /// Creates a key from a vector of segments.
    #[must_use]
    pub const fn from_segments(segments: Vec<KeySegment>) -> Self {
        Self { segments }
    }

    /// Returns the segments that make up this key.
    #[must_use]
    pub fn segments(&self) -> &[KeySegment] {
        &self.segments
    }

    /// Returns the number of segments in this key.
    #[must_use]
    #[allow(clippy::incompatible_msrv)]
    pub const fn len(&self) -> usize {
        self.segments.len()
    }

    /// Returns `true` if this key has no segments.
    #[must_use]
    #[allow(clippy::incompatible_msrv)]
    pub const fn is_empty(&self) -> bool {
        self.segments.is_empty()
    }

    /// Returns the parent key (all segments except the last).
    ///
    /// Returns `None` if this key has only one segment.
    #[must_use]
    pub fn parent(&self) -> Option<Self> {
        if self.segments.len() > 1 {
            Some(Self {
                segments: self.segments[..self.segments.len() - 1].to_vec(),
            })
        } else {
            None
        }
    }

    /// Returns the last segment of this key.
    #[must_use]
    pub fn last_segment(&self) -> Option<&KeySegment> {
        self.segments.last()
    }

    /// Returns the first segment of this key.
    #[must_use]
    pub fn first_segment(&self) -> Option<&KeySegment> {
        self.segments.first()
    }

    /// Appends a segment to the end of this key.
    #[must_use]
    pub fn append(mut self, segment: KeySegment) -> Self {
        self.segments.push(segment);
        self
    }

    /// Converts this key back to a string representation.
    #[must_use]
    pub fn to_key_string(&self) -> String {
        let mut result = String::new();

        for (i, segment) in self.segments.iter().enumerate() {
            if i > 0 {
                match segment {
                    KeySegment::Attribute(_) | KeySegment::Index(_) => {}
                    _ => result.push('.'),
                }
            }

            match segment {
                KeySegment::Key(s) => {
                    result.push_str(s);
                }
                KeySegment::Index(i) => {
                    result.push('[');
                    let _ = write!(&mut result, "{i}");
                    result.push(']');
                }
                KeySegment::Attribute(s) => {
                    result.push('@');
                    result.push_str(s);
                }
            }
        }

        result
    }

    /// Traverse the key segments with a function.
    ///
    /// # Errors
    ///
    /// Returns [`ConfigError::InvalidKey`] if the key is empty.
    pub fn traverse<F, T>(&self, mut f: F) -> ConfigResult<T>
    where
        F: FnMut(&KeySegment) -> ConfigResult<T>,
    {
        let mut last = None;
        for segment in &self.segments {
            last = Some(f(segment)?);
        }
        last.ok_or_else(|| ConfigError::InvalidKey("Cannot traverse empty key".to_string()))
    }

    /// Walk through all segments with a function.
    ///
    /// # Errors
    ///
    /// Returns [`ConfigError::InvalidKey`] if any segment traversal fails.
    pub fn walk<F>(&self, mut f: F) -> ConfigResult<()>
    where
        F: FnMut(usize, &KeySegment) -> ConfigResult<()>,
    {
        for (i, segment) in self.segments.iter().enumerate() {
            f(i, segment)?;
        }
        Ok(())
    }

    /// Returns the first `n` segments of this key.
    ///
    /// Returns `None` if `n` is 0 or greater than the number of segments.
    #[must_use]
    pub fn head(&self, n: usize) -> Option<Self> {
        if n > 0 && n <= self.segments.len() {
            Some(Self {
                segments: self.segments[..n].to_vec(),
            })
        } else {
            None
        }
    }

    /// Returns the last `n` segments of this key.
    ///
    /// Returns `None` if `n` is 0 or greater than the number of segments.
    #[must_use]
    pub fn tail(&self, n: usize) -> Option<Self> {
        if n > 0 && n <= self.segments.len() {
            Some(Self {
                segments: self.segments[self.segments.len() - n..].to_vec(),
            })
        } else {
            None
        }
    }

    /// Returns a new key with the given segment appended.
    #[must_use]
    pub fn child(&self, segment: KeySegment) -> Self {
        let mut new_segments = Vec::with_capacity(self.segments.len() + 1);
        new_segments.extend(self.segments.iter().cloned());
        new_segments.push(segment);
        Self {
            segments: new_segments,
        }
    }
}

impl From<Vec<KeySegment>> for Key {
    fn from(segments: Vec<KeySegment>) -> Self {
        Self { segments }
    }
}

impl std::fmt::Display for Key {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, ".{}", self.to_key_string())
    }
}

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

    #[test]
    fn test_key_from_str_simple() {
        let key = Key::from_str(".database").expect("test should succeed");
        assert_eq!(key.len(), 1);
        assert_eq!(key.segments()[0].as_key(), Some("database"));
    }

    #[test]
    fn test_key_from_str_nested() {
        let key = Key::from_str(".database.url").expect("test should succeed");
        assert_eq!(key.len(), 2);
        assert_eq!(key.segments()[0].as_key(), Some("database"));
        assert_eq!(key.segments()[1].as_key(), Some("url"));
    }

    #[test]
    fn test_key_from_str_index() {
        let key = Key::from_str(".users[0]").expect("test should succeed");
        assert_eq!(key.len(), 2);
        assert_eq!(key.segments()[0].as_key(), Some("users"));
        assert_eq!(key.segments()[1].as_index(), Some(0));
    }

    #[test]
    fn test_key_from_str_attribute() {
        let key = Key::from_str(".server@port").expect("test should succeed");
        assert_eq!(key.len(), 2);
        assert_eq!(key.segments()[0].as_key(), Some("server"));
        assert_eq!(key.segments()[1].as_attribute(), Some("port"));
    }

    #[test]
    fn test_key_from_str_complex() {
        let key = Key::from_str(".users[0].name@text").expect("test should succeed");
        assert_eq!(key.len(), 4);
        assert_eq!(key.segments()[0].as_key(), Some("users"));
        assert_eq!(key.segments()[1].as_index(), Some(0));
        assert_eq!(key.segments()[2].as_key(), Some("name"));
        assert_eq!(key.segments()[3].as_attribute(), Some("text"));
    }

    #[test]
    fn test_key_from_str_invalid_empty() {
        let result = Key::from_str("");
        assert!(result.is_err());
    }

    #[test]
    fn test_key_from_str_invalid_no_dot() {
        let result = Key::from_str("database");
        assert!(result.is_err());
    }

    #[test]
    fn test_key_parent() {
        let key = Key::from_str(".a.b.c").expect("test should succeed");
        let parent = key.parent().expect("test should succeed");
        assert_eq!(parent.len(), 2);
    }

    #[test]
    fn test_key_to_string() {
        let key = Key::from_str(".database.url").expect("test should succeed");
        assert_eq!(key.to_key_string(), "database.url");
    }

    #[test]
    fn test_key_display() {
        let key = Key::from_str(".database").expect("test should succeed");
        assert_eq!(format!("{}", key), ".database");
    }

    #[test]
    fn test_key_append() {
        let key = Key::from_str(".database").expect("test should succeed");
        let key = key.append(KeySegment::Key("url".to_string()));
        assert_eq!(key.len(), 2);
    }

    #[test]
    fn test_key_traverse() {
        let key = Key::from_str(".a.b.c").expect("test should succeed");
        let values: Vec<&str> = key.segments().iter().filter_map(|s| s.as_key()).collect();
        assert_eq!(values, vec!["a", "b", "c"]);
    }

    #[test]
    fn test_key_walk() {
        let key = Key::from_str(".a[0].b").expect("test should succeed");
        let mut count = 0;
        key.walk(|i, _segment| {
            count = i;
            Ok(())
        })
        .expect("test should succeed");
        assert_eq!(count, 2);
    }

    #[test]
    fn test_key_head_tail() {
        let key = Key::from_str(".a.b.c.d").expect("test should succeed");
        let head = key.head(2).expect("test should succeed");
        let tail = key.tail(2).expect("test should succeed");
        assert_eq!(head.len(), 2);
        assert_eq!(tail.len(), 2);
    }

    #[test]
    fn test_key_child() {
        let key = Key::from_str(".a").expect("test should succeed");
        let child = key.child(KeySegment::Key("b".to_string()));
        assert_eq!(child.len(), 2);
    }
}