sif_parser/

types.rs

// SIF Core v1 — Data types derived from the specification.
//
// Reference: SIF-SPEC.md §3 (Data Model), §7 (Type System),
//            §8 (Schema), §9 (Records), §16-22 (Semantics, Sections,
//            Directives, Blocks, References, Inline Mode, Templates),
//            Appendix A (Collected ABNF).

use std::collections::HashMap;

// ── Type System (§7) ────────────────────────────────────────────────

/// SIF type as declared in a `#schema` directive.
///
/// Types compose via suffixes: `str[]?` → `Nullable(Array(Str))`.
/// Suffixes are applied left-to-right per §7.1.
#[derive(Debug, Clone, PartialEq)]
pub enum Type {
    // Scalar types (§7.1)
    Bool,
    Int,
    Uint,
    Float,
    Str,
    Date,
    DateTime,
    Duration,
    Bytes,
    Enum(Vec<String>),
    Null,
    Any,

    // Compound types (§7.2)
    Map,
    Array(Box<Type>),
    Nullable(Box<Type>),
}

impl Type {
    /// Returns `true` if this type accepts the null literal `_`.
    pub fn is_nullable(&self) -> bool {
        matches!(self, Type::Nullable(_) | Type::Any | Type::Null)
    }
}

impl std::fmt::Display for Type {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Type::Bool => write!(f, "bool"),
            Type::Int => write!(f, "int"),
            Type::Uint => write!(f, "uint"),
            Type::Float => write!(f, "float"),
            Type::Str => write!(f, "str"),
            Type::Date => write!(f, "date"),
            Type::DateTime => write!(f, "datetime"),
            Type::Duration => write!(f, "duration"),
            Type::Bytes => write!(f, "bytes"),
            Type::Enum(variants) => {
                write!(f, "enum({})", variants.join(","))
            }
            Type::Null => write!(f, "null"),
            Type::Any => write!(f, "any"),
            Type::Map => write!(f, "map"),
            Type::Array(inner) => write!(f, "{}[]", inner),
            Type::Nullable(inner) => write!(f, "{}?", inner),
        }
    }
}

// ── Values (§9–§15) ─────────────────────────────────────────────────

/// A parsed SIF value.
#[derive(Debug, Clone, PartialEq)]
pub enum Value {
    Null,
    Bool(bool),
    Int(i64),
    Uint(u64),
    Float(f64),
    Str(String),
    Date(String),
    DateTime(String),
    Duration(String),
    Bytes(Vec<u8>),
    Enum(String),
    Array(Vec<Value>),
    Map(Vec<(String, Value)>),
}

impl Value {
    pub fn is_null(&self) -> bool {
        matches!(self, Value::Null)
    }

    pub fn as_str(&self) -> Option<&str> {
        match self {
            Value::Str(s) => Some(s),
            _ => None,
        }
    }

    pub fn as_int(&self) -> Option<i64> {
        match self {
            Value::Int(n) => Some(*n),
            _ => None,
        }
    }

    pub fn as_uint(&self) -> Option<u64> {
        match self {
            Value::Uint(n) => Some(*n),
            _ => None,
        }
    }

    pub fn as_float(&self) -> Option<f64> {
        match self {
            Value::Float(n) => Some(*n),
            _ => None,
        }
    }

    pub fn as_bool(&self) -> Option<bool> {
        match self {
            Value::Bool(b) => Some(*b),
            _ => None,
        }
    }
}

// ── Schema (§8) ─────────────────────────────────────────────────────

/// A key-value modifier on a field definition (§8.6).
///
/// Boolean flags have `value = None` (e.g., `hidden`).
/// Key-value pairs have `value = Some(...)` (e.g., `unit=usd`).
#[derive(Debug, Clone, PartialEq)]
pub struct Modifier {
    pub name: String,
    pub value: Option<String>,
}

/// A single field definition within a `#schema` directive (§8).
#[derive(Debug, Clone, PartialEq)]
pub struct FieldDef {
    pub name: String,
    pub field_type: Type,
    pub semantic: Option<String>,
    pub deprecated: bool,
    pub modifiers: Vec<Modifier>,
}

/// A parsed `#schema` directive (§8).
#[derive(Debug, Clone, PartialEq)]
pub struct Schema {
    pub fields: Vec<FieldDef>,
}

impl Schema {
    pub fn field_count(&self) -> usize {
        self.fields.len()
    }

    pub fn field_by_name(&self, name: &str) -> Option<&FieldDef> {
        self.fields.iter().find(|f| f.name == name)
    }

    pub fn field_index(&self, name: &str) -> Option<usize> {
        self.fields.iter().position(|f| f.name == name)
    }

    /// Returns the field with the `:id` semantic, if any.
    pub fn id_field(&self) -> Option<&FieldDef> {
        self.fields
            .iter()
            .find(|f| f.semantic.as_deref() == Some("id"))
    }
}

// ── CDC (SIF Streaming §17) ─────────────────────────────────────────

/// Change Data Capture operation prefix on a record.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CdcOp {
    /// No prefix — insert (default in CDC streams) or plain record.
    Insert,
    /// `Δ` (U+0394) prefix — full-replace update.
    Update,
    /// `∅` (U+2205) prefix — tombstone delete.
    Delete,
}

// ── Records (§9) ────────────────────────────────────────────────────

/// A parsed data record.
#[derive(Debug, Clone, PartialEq)]
pub struct Record {
    pub values: Vec<Value>,
    pub cdc_op: CdcOp,
}

impl Record {
    /// Access a field value by index.
    pub fn get(&self, index: usize) -> Option<&Value> {
        self.values.get(index)
    }

    /// Access a field value by name using the given schema.
    pub fn get_by_name<'a>(&'a self, name: &str, schema: &Schema) -> Option<&'a Value> {
        schema.field_index(name).and_then(|i| self.values.get(i))
    }
}

// ── Sort direction (§18.4) ──────────────────────────────────────────

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SortDirection {
    Asc,
    Desc,
}

// ── Field references (§20) ──────────────────────────────────────────

/// A reference to a field, optionally in another section.
///
/// `field` alone references the current section.
/// `§section.field` references a named section.
#[derive(Debug, Clone, PartialEq)]
pub struct FieldRef {
    pub section: Option<String>,
    pub field: String,
}

// ── Directives (§18) ────────────────────────────────────────────────

/// A parsed meta directive.
#[derive(Debug, Clone, PartialEq)]
pub enum Directive {
    Context(String),
    Source(String),
    License(String),
    Sort {
        field: String,
        direction: SortDirection,
    },
    Filter(String),
    Limit(u64),
    Truncated(Vec<(String, String)>),
    Relation {
        from: FieldRef,
        to: FieldRef,
    },
    Recall,
    Error(String),
    /// A directive not recognized by this parser (§18.8).
    Unknown {
        name: String,
        content: String,
    },
}

// ── Blocks (§19) ────────────────────────────────────────────────────

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BlockType {
    Code,
    Text,
    Diff,
    Raw,
    Template,
}

impl BlockType {
    pub fn as_str(&self) -> &'static str {
        match self {
            BlockType::Code => "code",
            BlockType::Text => "text",
            BlockType::Diff => "diff",
            BlockType::Raw => "raw",
            BlockType::Template => "template",
        }
    }
}

/// A parsed block region (§19).
#[derive(Debug, Clone, PartialEq)]
pub struct Block {
    pub block_type: BlockType,
    pub attributes: Vec<(String, String)>,
    pub content: String,
}

// ── Templates (§22) ─────────────────────────────────────────────────

/// A named template for record rendering (§22).
#[derive(Debug, Clone, PartialEq)]
pub struct Template {
    pub name: String,
    pub body: String,
}

impl Template {
    /// Render this template against a record using the given schema.
    ///
    /// Substitutes `@{field_name}` with the corresponding value.
    pub fn render(&self, record: &Record, schema: &Schema) -> String {
        let mut result = self.body.clone();
        for field in &schema.fields {
            let placeholder = format!("@{{{}}}", field.name);
            if let Some(value) = record.get_by_name(&field.name, schema) {
                let text = format_value(value);
                result = result.replace(&placeholder, &text);
            }
        }
        result
    }
}

fn format_value(value: &Value) -> String {
    match value {
        Value::Null => "_".to_string(),
        Value::Bool(b) => if *b { "T" } else { "F" }.to_string(),
        Value::Int(n) => n.to_string(),
        Value::Uint(n) => n.to_string(),
        Value::Float(n) => {
            let s = n.to_string();
            if s.contains('.') { s } else { format!("{}.0", s) }
        }
        Value::Str(s) => s.clone(),
        Value::Date(s) | Value::DateTime(s) | Value::Duration(s) => s.clone(),
        Value::Bytes(b) => base64_encode(b),
        Value::Enum(s) => s.clone(),
        Value::Array(arr) => {
            let elems: Vec<String> = arr.iter().map(format_value).collect();
            format!("[{}]", elems.join(","))
        }
        Value::Map(entries) => {
            let pairs: Vec<String> = entries
                .iter()
                .map(|(k, v)| format!("{}:{}", k, format_value(v)))
                .collect();
            format!("{{{}}}", pairs.join(","))
        }
    }
}

pub(crate) fn base64_encode(data: &[u8]) -> String {
    const CHARS: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
    let mut result = String::with_capacity((data.len() + 2) / 3 * 4);
    for chunk in data.chunks(3) {
        let b0 = chunk[0] as u32;
        let b1 = chunk.get(1).copied().unwrap_or(0) as u32;
        let b2 = chunk.get(2).copied().unwrap_or(0) as u32;
        let n = (b0 << 16) | (b1 << 8) | b2;
        result.push(CHARS[((n >> 18) & 63) as usize] as char);
        result.push(CHARS[((n >> 12) & 63) as usize] as char);
        if chunk.len() > 1 {
            result.push(CHARS[((n >> 6) & 63) as usize] as char);
        } else {
            result.push('=');
        }
        if chunk.len() > 2 {
            result.push(CHARS[(n & 63) as usize] as char);
        } else {
            result.push('=');
        }
    }
    result
}

// ── Inline Annotations (§16.3) ──────────────────────────────────────

/// A span of text that may contain inline semantic annotations.
#[derive(Debug, Clone, PartialEq)]
pub enum Span {
    /// Plain text with no annotation.
    Text(String),
    /// Annotated text: `@semantic{content}`.
    Annotated {
        semantic: String,
        children: Vec<Span>,
    },
}

// ── Sections (§17) ──────────────────────────────────────────────────

/// A section within a SIF document.
#[derive(Debug, Clone, PartialEq)]
pub struct Section {
    pub id: Option<String>,
    pub directives: Vec<Directive>,
    pub schema: Option<Schema>,
    pub records: Vec<Record>,
    pub blocks: Vec<Block>,
    pub templates: Vec<Template>,
}

// ── Header (§6) ─────────────────────────────────────────────────────

/// The parsed header line of a SIF document.
#[derive(Debug, Clone, PartialEq)]
pub struct Header {
    pub version: u32,
    pub attributes: HashMap<String, String>,
}

// ── Document (§5) ───────────────────────────────────────────────────

/// A complete parsed SIF document.
#[derive(Debug, Clone, PartialEq)]
pub struct Document {
    pub header: Header,
    pub sections: Vec<Section>,
}

impl Document {
    /// Find a section by its `§name` identifier.
    pub fn section_by_id(&self, id: &str) -> Option<&Section> {
        self.sections.iter().find(|s| s.id.as_deref() == Some(id))
    }
}

// ── Streaming Events ────────────────────────────────────────────────

/// Events emitted by the streaming `Reader`.
#[derive(Debug, Clone, PartialEq)]
pub enum Event {
    Header(Header),
    SectionId(String),
    SectionBreak,
    Schema(Schema),
    Record(Record),
    Directive(Directive),
    BlockStart {
        block_type: BlockType,
        attributes: Vec<(String, String)>,
    },
    BlockLine(String),
    BlockEnd,
    TemplateStart(String),
    TemplateLine(String),
    TemplateEnd,
}