rakata_formats/gff/

mod.rs

//! GFF V3.2 binary reader and writer.
//!
//! GFF is a typed, table-backed binary graph format used for most KotOR game
//! data objects (`UTC`, `UTI`, `ARE`, `DLG`, and others).
//!
//! ## Shape of the container
//!
//! A 56-byte header carrying an offset-and-count pair for each of six sections:
//! structs, fields, labels, the field data blob, and two index arrays. Every
//! section is located by its own header entry.
//!
//! One trap worth knowing before reading the header: the last three counts are
//! byte lengths while the first three are element counts.
//!
//! ## The overloaded word
//!
//! Both struct and field records carry a `data_or_offset` that means different
//! things by context, with no discriminator stored beside it. On a field it is
//! the value itself when the type fits in four bytes and an offset into the data
//! blob or an index array otherwise. On a struct it is a field index directly
//! when `field_count` is exactly one, and a byte offset into the field indices
//! array for any other count.
//!
//! Getting that wrong does not fail loudly, it reads a plausible number out of
//! the wrong region, which is why this module validates every range before
//! decoding rather than trusting the arithmetic.
//!
//! ## Logical Data Model
//! ```text
//! Gff
//!  `-- root GffStruct
//!       `-- [GffField(label, GffValue)]
//!            `-- nested structs/lists recursively reference tables
//! ```
//!
//! Offsets in struct and field records reference table locations or blob
//! offsets depending on field type. This module keeps those rules explicit and
//! validates all ranges before decoding.

mod coerce;
mod document;
mod label;
mod path;
mod reader;
mod walk;
mod writer;

pub use coerce::*;
pub use document::{Change, GffDocument, GffDocumentError};
pub use label::*;
pub use path::{GffPath, GffPathError, GffPathParseError, GffPathSegment};
pub use reader::{read_gff, read_gff_from_bytes};
pub use walk::GffWalk;
pub use writer::{write_gff, write_gff_to_vec};

use num_enum::{IntoPrimitive, TryFromPrimitive};
use thiserror::Error;

use rakata_core::{DecodeTextError, EncodeTextError, ResRef, StrRef, TextEncoding};

use crate::binary::{self, DecodeBinary, EncodeBinary};

/// GFF V3.2 header size.
const GFF_HEADER_SIZE: usize = 56;
/// Size of one struct-table entry.
const STRUCT_ENTRY_SIZE: usize = 12;
/// Size of one field-table entry.
const FIELD_ENTRY_SIZE: usize = 12;
/// Fixed width for field labels in the label table.
const LABEL_SIZE: usize = 16;
/// Binary GFF version supported by KotOR.
const GFF_VERSION_V32: [u8; 4] = *b"V3.2";
/// Default encoding used for non-localized GFF text values.
const DEFAULT_TEXT_ENCODING: TextEncoding = TextEncoding::Windows1252;

/// The magic a GFF carries when it claims no format of its own.
///
/// Every typed reader in the workspace accepts this alongside the magic it is
/// looking for, which makes it the one four-byte value that appears in all of
/// them and means the same thing each time. Named so those guards cite it
/// rather than spelling it out, and so the meaning sits somewhere a reader can
/// find: a container carrying this says only that it is a GFF, and which view
/// it should be read as has to come from somewhere other than the bytes.
///
/// A `.res` save sidecar and a `.bic` both present as this, which is the same
/// point [`ResourceType::Gff`](rakata_core::ResourceType::Gff) makes about
/// resource types.
pub const GENERIC_FILE_TYPE: [u8; 4] = *b"GFF ";

/// In-memory representation of a binary GFF file.
#[derive(Debug, Clone, PartialEq)]
pub struct Gff {
    /// Four-byte file type (`GFF `, `UTC `, `UTI `, ...).
    pub file_type: [u8; 4],
    /// Root structure.
    pub root: GffStruct,
}

impl Gff {
    /// Creates a GFF value with the provided file type and root structure.
    pub fn new(file_type: [u8; 4], root: GffStruct) -> Self {
        Self { file_type, root }
    }

    /// Creates a generic `GFF ` container.
    pub fn generic(root: GffStruct) -> Self {
        Self {
            file_type: GENERIC_FILE_TYPE,
            root,
        }
    }
}

impl DecodeBinary for Gff {
    type Error = GffBinaryError;

    fn decode_binary(bytes: &[u8]) -> Result<Self, Self::Error> {
        read_gff_from_bytes(bytes)
    }
}

impl EncodeBinary for Gff {
    type Error = GffBinaryError;

    fn encode_binary(&self) -> Result<Vec<u8>, Self::Error> {
        write_gff_to_vec(self)
    }
}

/// One GFF struct node.
#[derive(Debug, Clone, PartialEq)]
pub struct GffStruct {
    /// Struct ID from the binary table.
    pub struct_id: i32,
    /// Ordered fields for this struct.
    pub fields: Vec<GffField>,
}

impl GffStruct {
    /// Creates an empty struct with the given `struct_id`.
    pub fn new(struct_id: i32) -> Self {
        Self {
            struct_id,
            fields: Vec::new(),
        }
    }

    /// Creates a struct with pre-populated fields.
    pub fn with_fields(struct_id: i32, fields: Vec<GffField>) -> Self {
        Self { struct_id, fields }
    }

    /// Appends a new field.
    ///
    /// Takes a built [`GffLabel`] rather than converting one, so the decision
    /// about an unrepresentable label belongs to whoever supplied it. A source
    /// literal goes through [`gff_label!`](crate::gff_label) and fails the
    /// build; a label read out of a file or a user's input goes through
    /// [`GffLabel::new`] and carries a `Result` the caller has to answer.
    pub fn push_field(&mut self, label: GffLabel, value: GffValue) {
        self.fields.push(GffField { label, value });
    }

    /// Returns the first field value that matches `label`, or `None` when the
    /// struct carries no field under that label.
    ///
    /// A struct can hold one label more than once, and vanilla content does:
    /// every `EntryList` and `ReplyList` node in a `.dlg` carries `SoundExists`
    /// six times over. Across every GFF file in the install the copies agree in
    /// value, so taking the first is not a choice between different answers.
    /// It is still a choice, and a caller that wants to see the rest has to
    /// walk [`Self::fields`] itself.
    pub fn field(&self, label: &str) -> Option<&GffValue> {
        self.fields
            .iter()
            .find(|field| field.label == label)
            .map(|field| &field.value)
    }
}

/// One labeled GFF field.
#[derive(Debug, Clone, PartialEq)]
pub struct GffField {
    /// Field label.
    pub label: GffLabel,
    /// Field payload.
    pub value: GffValue,
}

/// The GFF V3.2 field type set, declared once for every enum that mirrors it.
///
/// Four types describe this one closed set: the wire codes the reader decodes,
/// the runtime value, the serde DTO, and the schema's expected type. They were
/// maintained by hand and had already drifted, and the drift was silent because
/// nothing matches a schema type against a wire code. Passing the set through
/// this macro is what makes a variant present in one and absent from another
/// unrepresentable.
///
/// Each row is a variant name, its wire code, the name the format gives it, a
/// description, the runtime payload, and the DTO payload. The set is fixed by
/// the format, so this list does not grow.
///
/// Code `18` is deliberately absent. `docs/src/formats/gff/index.md` records it
/// as defined by the format with no established storage rule, and a reader that
/// meets one is supposed to surface it rather than guess which branch to take.
/// Leaving it out of the wire enum is what makes the reader do that: it reports
/// the code it could not decode instead of reading four bytes out of a region
/// nothing attests.
macro_rules! gff_field_types {
    ($emit:ident) => {
        $emit! {
            UInt8 = 0, "BYTE", "unsigned 8-bit integer", u8, u8;
            Int8 = 1, "CHAR", "signed 8-bit integer", i8, i8;
            UInt16 = 2, "WORD", "unsigned 16-bit integer", u16, u16;
            Int16 = 3, "SHORT", "signed 16-bit integer", i16, i16;
            UInt32 = 4, "DWORD", "unsigned 32-bit integer", u32, u32;
            Int32 = 5, "INT", "signed 32-bit integer", i32, i32;
            UInt64 = 6, "DWORD64", "unsigned 64-bit integer", u64, u64;
            Int64 = 7, "INT64", "signed 64-bit integer", i64, i64;
            Single = 8, "FLOAT", "32-bit floating point", f32, f32;
            Double = 9, "DOUBLE", "64-bit floating point", f64, f64;
            String = 10, "CExoString", "variable-length string", String, String;
            ResRef = 11, "CResRef", "resource reference, at most 16 bytes", ResRef, String;
            LocalizedString = 12, "CExoLocString",
                "localized string with an optional TLK reference",
                GffLocalizedString, GffLocalizedStringDto;
            Binary = 13, "VOID", "raw binary blob", Vec<u8>,
                #[serde(with = "hex_bytes")] Vec<u8>;
            Struct = 14, "Struct", "nested struct", Box<GffStruct>, Box<GffStructDto>;
            List = 15, "List", "struct list", Vec<GffStruct>, Vec<GffStructDto>;
            Vector4 = 16, "Quaternion", "four packed `f32`, scalar first", [f32; 4], [f32; 4];
            Vector3 = 17, "Vector", "three packed `f32`", [f32; 3], [f32; 3];
        }
    };
}

pub(crate) use gff_field_types;

macro_rules! emit_gff_value {
    ($($variant:ident = $id:literal, $wire:literal, $description:literal, $value:ty,
        $(#[$dto_attr:meta])* $dto:ty;)*) => {
        /// Runtime value for one GFF field.
        #[derive(Debug, Clone, PartialEq)]
        pub enum GffValue {
            $(
                #[doc = concat!("`", $wire, "`: ", $description, ".")]
                $variant($value),
            )*
        }
    };
}

gff_field_types!(emit_gff_value);

impl GffValue {
    /// Test/fixture helper: constructs a [`GffValue::ResRef`] from a string
    /// literal, panicking on invalid input.
    ///
    /// Production code should construct `GffValue::ResRef(resref)` directly
    /// with a validated [`ResRef`]. This helper exists so fixture generators
    /// and unit tests can avoid boilerplate when the input is a known-valid
    /// literal.
    #[doc(hidden)]
    pub fn resref_lit(value: &str) -> Self {
        GffValue::ResRef(ResRef::new(value).expect("valid resref literal"))
    }
}

/// CExoLocString payload.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GffLocalizedString {
    /// TLK string reference (`StrRef::invalid()` means use substrings).
    pub string_ref: StrRef,
    /// Embedded localized substrings.
    pub substrings: Vec<GffLocalizedSubstring>,
}

impl Default for GffLocalizedString {
    /// An empty localized string: no TLK reference and no substrings.
    ///
    /// `StrRef::invalid()` is the engine's own "no TLK entry" marker rather
    /// than a stand-in, so this is the genuine empty value for the type.
    fn default() -> Self {
        Self::new(StrRef::invalid())
    }
}

impl GffLocalizedString {
    /// Creates an empty localized string.
    pub fn new(string_ref: impl Into<StrRef>) -> Self {
        Self {
            string_ref: string_ref.into(),
            substrings: Vec::new(),
        }
    }
}

/// One localized substring entry.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GffLocalizedSubstring {
    /// Packed string ID (`language_id * 2 + gender`).
    pub string_id: u32,
    /// Decoded text payload.
    pub text: String,
}

impl GffLocalizedSubstring {
    /// Returns the language ID portion (`string_id / 2`).
    pub fn language_id(&self) -> u32 {
        self.string_id / 2
    }

    /// Returns `true` for feminine entries (`string_id % 2 == 1`).
    pub fn is_feminine(&self) -> bool {
        self.string_id % 2 == 1
    }
}

/// Errors produced while parsing or writing binary GFF data.
#[derive(Debug, Error)]
pub enum GffBinaryError {
    /// I/O read/write failure.
    #[error(transparent)]
    Io(#[from] std::io::Error),
    /// Header/body layout is invalid or truncated.
    #[error("invalid GFF header: {0}")]
    InvalidHeader(String),
    /// GFF version is unsupported.
    #[error("invalid GFF version: {0:?}")]
    InvalidVersion([u8; 4]),
    /// Encountered an unknown field type ID.
    #[error("invalid GFF field type id: {0}")]
    InvalidFieldType(u32),
    /// In-memory data is not valid for binary serialization.
    #[error("invalid GFF data: {0}")]
    InvalidData(String),
    /// Value cannot fit the target on-disk width.
    #[error("value overflow while writing `{0}`")]
    ValueOverflow(&'static str),
    /// Label exceeds 16 bytes after encoding.
    #[error("label `{label}` encoded length {len} exceeds maximum {max}")]
    LabelTooLong {
        /// Label text.
        label: String,
        /// Encoded byte length.
        len: usize,
        /// Maximum allowed byte length.
        max: usize,
    },
    /// Text cannot be represented in the target encoding.
    #[error("GFF text encoding failed for {context}: {source}")]
    TextEncoding {
        /// Context path for error reporting.
        context: String,
        /// Source encoding error.
        #[source]
        source: EncodeTextError,
    },
    /// Text bytes cannot be decoded losslessly.
    #[error("GFF text decoding failed for {context}: {source}")]
    TextDecoding {
        /// Context path for error reporting.
        context: String,
        /// Source decoding error.
        #[source]
        source: DecodeTextError,
    },
    /// Language ID maps to an unsupported encoding.
    #[error("unsupported language id {0} for localized string encoding")]
    UnsupportedLanguageEncoding(u32),
}

impl From<binary::BinaryLayoutError> for GffBinaryError {
    fn from(error: binary::BinaryLayoutError) -> Self {
        Self::InvalidHeader(error.to_string())
    }
}

macro_rules! emit_field_type {
    ($($variant:ident = $id:literal, $wire:literal, $description:literal, $value:ty,
        $(#[$dto_attr:meta])* $dto:ty;)*) => {
        #[derive(Debug, Clone, Copy, PartialEq, Eq, IntoPrimitive, TryFromPrimitive)]
        #[repr(u32)]
        pub(super) enum FieldType {
            $($variant = $id,)*
        }
    };
}

gff_field_types!(emit_field_type);

pub(super) fn to_u32(value: usize, name: &'static str) -> Result<u32, GffBinaryError> {
    u32::try_from(value).map_err(|_| GffBinaryError::ValueOverflow(name))
}

pub(super) fn to_usize(value: u32, name: &'static str) -> Result<usize, GffBinaryError> {
    binary::checked_to_usize(value, name).map_err(|_| {
        GffBinaryError::InvalidData(format!("{name} does not fit target platform usize"))
    })
}

//
// Serde Support (JSON)
//

#[cfg(feature = "serde")]
/// JSON serialization support for GFF.
pub mod serde_json_fmt {
    use super::*;
    use serde::{Deserialize, Serialize};
    use serde_json::{from_slice, from_str, to_string_pretty, to_vec};

    /// Serializes a GFF to JSON.
    ///
    /// # Errors
    ///
    /// [`GffBinaryError::InvalidData`] carrying the `serde_json` message. The
    /// DTO is built from the tree first and holds nothing that resists
    /// serialization, so this arm is not reachable in practice.
    pub fn write_gff_to_json(gff: &Gff) -> Result<String, GffBinaryError> {
        let dto = GffDto::from(gff);
        to_string_pretty(&dto).map_err(|e| GffBinaryError::InvalidData(e.to_string()))
    }

    /// Serializes a GFF to JSON bytes.
    ///
    /// # Errors
    ///
    /// The same as [`write_gff_to_json`].
    pub fn write_gff_to_json_vec(gff: &Gff) -> Result<Vec<u8>, GffBinaryError> {
        let dto = GffDto::from(gff);
        to_vec(&dto).map_err(|e| GffBinaryError::InvalidData(e.to_string()))
    }

    /// Deserializes a GFF from JSON.
    ///
    /// # Errors
    ///
    /// [`GffBinaryError::InvalidData`] carrying the `serde_json` message, for
    /// JSON that is malformed or does not have the DTO's shape, and
    /// [`GffBinaryError::InvalidHeader`] when the DTO reads and does not
    /// convert to a tree.
    ///
    /// The JSON form keys fields by label, so a struct carrying one label
    /// several times does not survive the round trip. A vanilla `.dlg` node
    /// carries `SoundExists` six times over.
    pub fn read_gff_from_json(json: &str) -> Result<Gff, GffBinaryError> {
        let dto: GffDto = from_str(json).map_err(|e| GffBinaryError::InvalidData(e.to_string()))?;
        Gff::try_from(dto)
    }

    /// Deserializes a GFF from JSON bytes.
    ///
    /// # Errors
    ///
    /// The same as [`read_gff_from_json`].
    pub fn read_gff_from_json_bytes(bytes: &[u8]) -> Result<Gff, GffBinaryError> {
        let dto: GffDto =
            from_slice(bytes).map_err(|e| GffBinaryError::InvalidData(e.to_string()))?;
        Gff::try_from(dto)
    }

    /// Serializable DTO for the root GFF file.
    #[derive(Serialize, Deserialize)]
    pub struct GffDto {
        /// File type signature (e.g. "UTC ").
        pub file_type: String,
        /// Root struct data.
        pub root: GffStructDto,
    }

    /// Serializable DTO for a GFF struct.
    #[derive(Serialize, Deserialize)]
    pub struct GffStructDto {
        /// Struct ID (usually -1 for root, or specific ID for list items).
        pub struct_id: i32,
        /// Fields in the order the file carries them.
        ///
        /// A sequence rather than a map keyed by label, because a struct can
        /// carry one label more than once. Keying by label dropped five of
        /// every `.dlg` node's six `SoundExists` copies, which is 565 of one
        /// vanilla file's 4,473 fields, and the JSON looked complete.
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        pub fields: Vec<GffFieldDto>,
    }

    /// Serializable DTO for one labelled field.
    #[derive(Serialize, Deserialize)]
    pub struct GffFieldDto {
        /// Field label.
        pub label: String,
        /// Field payload, inlined beside the label rather than nested under
        /// a second `value` key.
        #[serde(flatten)]
        pub value: GffValueDto,
    }

    macro_rules! emit_value_dto {
        ($($variant:ident = $id:literal, $wire:literal, $description:literal, $value:ty,
            $(#[$dto_attr:meta])* $dto:ty;)*) => {
            /// Serializable DTO for a GFF field value.
            ///
            /// A `Binary` payload is a hex string in JSON rather than an array
            /// of numbers, which is the one place the DTO does not mirror the
            /// runtime value's shape.
            #[derive(Serialize, Deserialize)]
            #[serde(tag = "type", content = "value")]
            pub enum GffValueDto {
                $(
                    #[doc = concat!("`", $wire, "`: ", $description, ".")]
                    $(#[$dto_attr])*
                    $variant($dto),
                )*
            }
        };
    }

    gff_field_types!(emit_value_dto);

    /// Serializable DTO for a localized string.
    #[derive(Serialize, Deserialize)]
    pub struct GffLocalizedStringDto {
        /// Reference into `dialog.tlk`.
        pub str_ref: i32,
        /// Substrings in the order the file carries them.
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        pub substrings: Vec<GffSubstringDto>,
    }

    /// Serializable DTO for one localized substring.
    ///
    /// A sequence entry rather than a map keyed by the id. No install file was
    /// seen carrying an id twice, so unlike [`GffStructDto::fields`] this is
    /// not fixing observed loss; the map had to go because a numeric key does
    /// not survive `serde`'s flattening, which left the field DTO readable in
    /// one direction only.
    #[derive(Serialize, Deserialize)]
    pub struct GffSubstringDto {
        /// Packed language-and-gender id.
        pub string_id: u32,
        /// Decoded text payload.
        pub text: String,
    }

    impl From<&Gff> for GffDto {
        fn from(gff: &Gff) -> Self {
            let file_type = rakata_core::text::decode_text(
                &gff.file_type,
                rakata_core::text::TextEncoding::Windows1252,
            );
            Self {
                file_type,
                root: GffStructDto::from(&gff.root),
            }
        }
    }

    impl TryFrom<GffDto> for Gff {
        type Error = GffBinaryError;

        fn try_from(dto: GffDto) -> Result<Self, Self::Error> {
            let mut file_type = [0u8; 4];
            let bytes = dto.file_type.as_bytes();
            if bytes.len() > 4 {
                return Err(GffBinaryError::InvalidHeader("file_type too long".into()));
            }
            file_type[..bytes.len()].copy_from_slice(bytes);

            Ok(Self {
                file_type,
                root: GffStruct::try_from(dto.root)?,
            })
        }
    }

    impl From<&GffStruct> for GffStructDto {
        fn from(s: &GffStruct) -> Self {
            Self {
                struct_id: s.struct_id,
                fields: s
                    .fields
                    .iter()
                    .map(|field| GffFieldDto {
                        label: field.label.to_string(),
                        value: GffValueDto::from(&field.value),
                    })
                    .collect(),
            }
        }
    }

    impl TryFrom<GffStructDto> for GffStruct {
        type Error = GffBinaryError;

        fn try_from(dto: GffStructDto) -> Result<Self, Self::Error> {
            let mut fields = Vec::with_capacity(dto.fields.len());
            for field in dto.fields {
                fields.push(GffField {
                    label: field.label.try_into().map_err(|_| {
                        GffBinaryError::InvalidData("Invalid GFF label in JSON".into())
                    })?,
                    value: GffValue::try_from(field.value)?,
                });
            }
            Ok(Self {
                struct_id: dto.struct_id,
                fields,
            })
        }
    }

    impl From<&GffValue> for GffValueDto {
        fn from(v: &GffValue) -> Self {
            match v {
                GffValue::UInt8(x) => Self::UInt8(*x),
                GffValue::Int8(x) => Self::Int8(*x),
                GffValue::UInt16(x) => Self::UInt16(*x),
                GffValue::Int16(x) => Self::Int16(*x),
                GffValue::UInt32(x) => Self::UInt32(*x),
                GffValue::Int32(x) => Self::Int32(*x),
                GffValue::UInt64(x) => Self::UInt64(*x),
                GffValue::Int64(x) => Self::Int64(*x),
                GffValue::Single(x) => Self::Single(*x),
                GffValue::Double(x) => Self::Double(*x),
                GffValue::String(x) => Self::String(x.clone()),
                GffValue::ResRef(x) => Self::ResRef(x.to_string()),
                GffValue::LocalizedString(x) => {
                    Self::LocalizedString(GffLocalizedStringDto::from(x))
                }
                GffValue::Binary(x) => Self::Binary(x.clone()),
                GffValue::Struct(x) => Self::Struct(Box::new(GffStructDto::from(x.as_ref()))),
                GffValue::List(x) => Self::List(x.iter().map(GffStructDto::from).collect()),
                GffValue::Vector4(x) => Self::Vector4(*x),
                GffValue::Vector3(x) => Self::Vector3(*x),
            }
        }
    }

    impl TryFrom<GffValueDto> for GffValue {
        type Error = GffBinaryError;

        fn try_from(dto: GffValueDto) -> Result<Self, Self::Error> {
            Ok(match dto {
                GffValueDto::UInt8(x) => Self::UInt8(x),
                GffValueDto::Int8(x) => Self::Int8(x),
                GffValueDto::UInt16(x) => Self::UInt16(x),
                GffValueDto::Int16(x) => Self::Int16(x),
                GffValueDto::UInt32(x) => Self::UInt32(x),
                GffValueDto::Int32(x) => Self::Int32(x),
                GffValueDto::UInt64(x) => Self::UInt64(x),
                GffValueDto::Int64(x) => Self::Int64(x),
                GffValueDto::Single(x) => Self::Single(x),
                GffValueDto::Double(x) => Self::Double(x),
                GffValueDto::String(x) => Self::String(x),
                GffValueDto::ResRef(x) => Self::ResRef(
                    ResRef::new(&x)
                        .map_err(|e| GffBinaryError::InvalidData(format!("resref `{x}`: {e}")))?,
                ),
                GffValueDto::LocalizedString(x) => {
                    Self::LocalizedString(GffLocalizedString::from(x))
                }
                GffValueDto::Binary(x) => Self::Binary(x),
                GffValueDto::Struct(x) => Self::Struct(Box::new(GffStruct::try_from(*x)?)),
                GffValueDto::List(x) => {
                    let mut list = Vec::with_capacity(x.len());
                    for item in x {
                        list.push(GffStruct::try_from(item)?);
                    }
                    Self::List(list)
                }
                GffValueDto::Vector4(x) => Self::Vector4(x),
                GffValueDto::Vector3(x) => Self::Vector3(x),
            })
        }
    }

    impl From<&GffLocalizedString> for GffLocalizedStringDto {
        fn from(s: &GffLocalizedString) -> Self {
            Self {
                str_ref: s.string_ref.raw(),
                substrings: s
                    .substrings
                    .iter()
                    .map(|sub| GffSubstringDto {
                        string_id: sub.string_id,
                        text: sub.text.clone(),
                    })
                    .collect(),
            }
        }
    }

    impl From<GffLocalizedStringDto> for GffLocalizedString {
        fn from(dto: GffLocalizedStringDto) -> Self {
            let substrings = dto
                .substrings
                .into_iter()
                .map(|sub| GffLocalizedSubstring {
                    string_id: sub.string_id,
                    text: sub.text,
                })
                .collect();
            Self {
                string_ref: StrRef::from_raw(dto.str_ref),
                substrings,
            }
        }
    }

    mod hex_bytes {
        use serde::{Deserialize, Deserializer, Serializer};

        pub fn serialize<S>(bytes: &[u8], serializer: S) -> Result<S::Ok, S::Error>
        where
            S: Serializer,
        {
            let hex = hex_encode(bytes);
            serializer.serialize_str(&hex)
        }

        pub fn deserialize<'de, D>(deserializer: D) -> Result<Vec<u8>, D::Error>
        where
            D: Deserializer<'de>,
        {
            let s = String::deserialize(deserializer)?;
            hex_decode(&s).map_err(serde::de::Error::custom)
        }

        fn hex_encode(bytes: &[u8]) -> String {
            use std::fmt::Write;
            let mut s = String::with_capacity(bytes.len() * 2);
            for b in bytes {
                write!(&mut s, "{b:02X}").expect("writing to a String cannot fail");
            }
            s
        }

        fn hex_decode(s: &str) -> Result<Vec<u8>, String> {
            if !s.len().is_multiple_of(2) {
                return Err("odd length hex string".into());
            }
            let mut bytes = Vec::with_capacity(s.len() / 2);
            for i in (0..s.len()).step_by(2) {
                let byte_str = &s[i..i + 2];
                let byte = u8::from_str_radix(byte_str, 16)
                    .map_err(|e| format!("invalid hex byte {}: {}", byte_str, e))?;
                bytes.push(byte);
            }
            Ok(bytes)
        }
    }
}

#[cfg(feature = "serde")]
pub use serde_json_fmt::{
    read_gff_from_json, read_gff_from_json_bytes, write_gff_to_json, write_gff_to_json_vec,
};

#[cfg(test)]
mod tests {
    use super::GffLocalizedString;
    use rakata_core::StrRef;

    #[test]
    fn a_default_localized_string_is_empty_and_unreferenced() {
        let value = GffLocalizedString::default();

        assert_eq!(value.string_ref, StrRef::invalid());
        assert!(value.substrings.is_empty());
        assert_eq!(value, GffLocalizedString::new(StrRef::invalid()));
    }
}