rakata_formats/gff/

label.rs

use std::fmt::{Display, Formatter};
use std::str::FromStr;
use thiserror::Error;

/// Maximum number of ASCII characters for a GFF field label.
pub const MAX_GFF_LABEL_LEN: usize = 16;

/// Error returned when constructing a [`GffLabel`] fails validation.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum GffLabelError {
    /// Input exceeded the maximum allowed label length.
    #[error("label length {len} exceeds maximum {max}")]
    TooLong {
        /// Actual input length.
        len: usize,
        /// Maximum allowed length.
        max: usize,
    },
    /// Input contained an invalid character.
    #[error("invalid GFF label character '{ch}'")]
    InvalidChar {
        /// The invalid character that caused validation failure.
        ch: char,
    },
}

/// Canonicalized GFF field label.
///
/// GFF labels are identifiers with a maximum length of 16 characters. This type stores
/// the exact casing of the label as an inline fixed-size buffer, making it `Copy` and
/// zero-allocation.
///
///
/// Valid characters are restricted to ASCII alphanumerics, underscores, and spaces (`[A-Za-z0-9_ ]`).
#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(try_from = "String", into = "String"))]
pub struct GffLabel {
    bytes: [u8; MAX_GFF_LABEL_LEN],
    len: u8,
}

impl GffLabel {
    /// Creates and validates a new GFF label.
    ///
    /// Accepted characters are ASCII alphanumerics, underscores, and spaces.
    ///
    /// # Errors
    ///
    /// [`GffLabelError::TooLong`] above 16 bytes, which is the fixed width the
    /// on-disk label table gives every entry, and
    /// [`GffLabelError::InvalidChar`] for anything outside the accepted set,
    /// naming the character.
    ///
    /// The length is the trap: a format's documented label can be longer than
    /// the file can hold, and the file wins. `TransitionDestination` and
    /// `PT_CONTROLLED_NPC` are both cases, and neither appears in any real
    /// file under the name the page gives it.
    pub fn new(value: impl AsRef<str>) -> Result<Self, GffLabelError> {
        let raw = value.as_ref();
        if raw.len() > MAX_GFF_LABEL_LEN {
            return Err(GffLabelError::TooLong {
                len: raw.len(),
                max: MAX_GFF_LABEL_LEN,
            });
        }
        let mut bytes = [0u8; MAX_GFF_LABEL_LEN];
        for (i, ch) in raw.chars().enumerate() {
            if !(ch.is_ascii_alphanumeric() || ch == '_' || ch == ' ') {
                return Err(GffLabelError::InvalidChar { ch });
            }
            // All valid chars are single-byte ASCII.
            bytes[i] = u8::try_from(u32::from(ch)).expect("ASCII char is guaranteed to fit in u8");
        }
        let len = u8::try_from(raw.len()).expect("len already bounded by MAX_GFF_LABEL_LEN");
        Ok(Self { bytes, len })
    }

    /// Constructs a [`GffLabel`] from a string literal at compile time.
    ///
    /// Use this for hardcoded labels in source code. Invalid input becomes
    /// a compile error when the call appears in a `const` context, and
    /// panics immediately at the call site otherwise -- validation cannot
    /// be deferred into a runtime data path.
    ///
    /// For runtime input (binary parsing, JSON, user data), use
    /// [`GffLabel::new`] which returns a [`Result`].
    ///
    /// ```
    /// # use rakata_formats::gff::GffLabel;
    /// const TAG: GffLabel = GffLabel::from_static("Tag");
    /// assert_eq!(TAG.as_str(), "Tag");
    /// ```
    ///
    /// Invalid literals are rejected at compile time when used in a
    /// `const` context:
    ///
    /// ```compile_fail
    /// # use rakata_formats::gff::GffLabel;
    /// const BAD: GffLabel = GffLabel::from_static("Tag!");
    /// ```
    #[allow(clippy::as_conversions)]
    pub const fn from_static(value: &'static str) -> Self {
        let bytes = value.as_bytes();
        let len = bytes.len();
        assert!(len <= MAX_GFF_LABEL_LEN, "GFF label exceeds 16 bytes");

        let mut storage = [0u8; MAX_GFF_LABEL_LEN];
        let mut i = 0;
        while i < len {
            let b = bytes[i];
            assert!(
                (b >= b'A' && b <= b'Z')
                    || (b >= b'a' && b <= b'z')
                    || (b >= b'0' && b <= b'9')
                    || b == b'_'
                    || b == b' ',
                "GFF label contains invalid character (allowed: [A-Za-z0-9_ ])"
            );
            storage[i] = b;
            i += 1;
        }

        // len is bounded by MAX_GFF_LABEL_LEN (16), so the cast is lossless.
        // u8::try_from is not const-stable on stable Rust, so `as` is the
        // only available option in a const context.
        Self {
            bytes: storage,
            len: len as u8,
        }
    }

    /// Returns the string representation of the label.
    pub fn as_str(&self) -> &str {
        // SAFETY-equivalent: all bytes in [0..len) are guaranteed to be ASCII
        // (validated in `new`), so the slice is valid UTF-8.
        std::str::from_utf8(&self.bytes[..usize::from(self.len)])
            .expect("all bytes are validated ASCII during construction")
    }

    /// Returns the length in bytes (equals character count since all content is ASCII).
    #[allow(clippy::as_conversions)]
    pub const fn len(&self) -> usize {
        self.len as usize
    }

    /// Returns `true` when the label is empty.
    pub const fn is_empty(&self) -> bool {
        self.len == 0
    }
}

/// Builds a [`GffLabel`] from a literal, rejecting an invalid one at compile
/// time.
///
/// [`GffLabel::from_static`] is a `const fn`, but calling it in an ordinary
/// expression evaluates it at run time, so a bad literal panics on the line
/// that runs rather than on the line that is wrong. Wrapping the call in a
/// `const` block forces the evaluation into the compile, which is the whole
/// point at a call site that only ever passes a literal.
///
/// ```
/// # use rakata_formats::gff_label;
/// let tag = gff_label!("Tag");
/// assert_eq!(tag.as_str(), "Tag");
/// ```
///
/// ```compile_fail
/// # use rakata_formats::gff_label;
/// let bad = gff_label!("Tag!");
/// ```
#[macro_export]
macro_rules! gff_label {
    ($literal:literal) => {
        const { $crate::gff::GffLabel::from_static($literal) }
    };
}

impl std::fmt::Debug for GffLabel {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "GffLabel({:?})", self.as_str())
    }
}

impl Display for GffLabel {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl FromStr for GffLabel {
    type Err = GffLabelError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::new(s)
    }
}

impl TryFrom<&str> for GffLabel {
    type Error = GffLabelError;

    fn try_from(value: &str) -> Result<Self, Self::Error> {
        Self::new(value)
    }
}

impl TryFrom<String> for GffLabel {
    type Error = GffLabelError;

    fn try_from(value: String) -> Result<Self, Self::Error> {
        Self::new(value)
    }
}

impl From<GffLabel> for String {
    fn from(val: GffLabel) -> Self {
        val.as_str().to_owned()
    }
}

impl AsRef<str> for GffLabel {
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl PartialEq<str> for GffLabel {
    fn eq(&self, other: &str) -> bool {
        self.as_str() == other
    }
}

impl PartialEq<&str> for GffLabel {
    fn eq(&self, other: &&str) -> bool {
        self.as_str() == *other
    }
}

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

    #[test]
    fn accepts_valid_label() {
        let parsed = GffLabel::new("Equip_ItemList").expect("valid label");
        assert_eq!(parsed.as_str(), "Equip_ItemList");
    }

    #[test]
    fn rejects_too_long_label() {
        let err = GffLabel::new("this_name_is_longer_than_sixteen").expect_err("must fail");
        assert!(matches!(err, GffLabelError::TooLong { .. }));
    }

    #[test]
    fn rejects_invalid_characters() {
        let err = GffLabel::new("bad!name").expect_err("must fail");
        assert_eq!(err, GffLabelError::InvalidChar { ch: '!' });
    }

    #[test]
    fn is_copy() {
        fn takes_copy<T: Copy>(_: T) {}
        takes_copy(GffLabel::new("Test").unwrap());
    }

    #[test]
    fn roundtrip_through_string() {
        let original = GffLabel::new("test_label").expect("valid");
        let s: String = original.into();
        assert_eq!(s, "test_label");
        let back: GffLabel = s.try_into().expect("valid");
        assert_eq!(back, original);
    }

    #[test]
    fn from_static_accepts_valid_label() {
        const TAG: GffLabel = GffLabel::from_static("Tag");
        assert_eq!(TAG.as_str(), "Tag");
        assert_eq!(TAG.len(), 3);
    }

    #[test]
    fn from_static_accepts_label_with_space() {
        // GIT files use labels like "Creature List", "Door List" -- the
        // space character must remain valid for K1 vanilla content.
        const LIST: GffLabel = GffLabel::from_static("Creature List");
        assert_eq!(LIST.as_str(), "Creature List");
    }

    #[test]
    fn from_static_accepts_max_length() {
        const MAX: GffLabel = GffLabel::from_static("a234567890123456");
        assert_eq!(MAX.len(), 16);
    }

    #[test]
    fn from_static_matches_new_for_valid_input() {
        let runtime = GffLabel::new("Equip_ItemList").expect("valid");
        const COMPILE_TIME: GffLabel = GffLabel::from_static("Equip_ItemList");
        assert_eq!(runtime, COMPILE_TIME);
    }

    #[test]
    #[should_panic(expected = "GFF label exceeds 16 bytes")]
    fn from_static_rejects_too_long_at_runtime() {
        // Outside a const context the assert! degrades to a runtime panic.
        // Invalid literals in a `const` binding fail to compile (covered by
        // the doctest on `from_static`).
        let _ = GffLabel::from_static("this_label_is_longer_than_sixteen");
    }

    #[test]
    #[should_panic(expected = "GFF label contains invalid character")]
    fn from_static_rejects_invalid_char_at_runtime() {
        let _ = GffLabel::from_static("bad!name");
    }
}