mathtex_editor_core/

doc.rs

//! The document and clipboard format is an id-free nested tree rebuilt into slotmap storage on load.

use serde::{de, Deserialize, Deserializer, Serialize};

use crate::model::{Deco, FracStyle, Kind, Mark, MatrixEnv, Node, NodeId, SeqId, Symbol, Tree, Variant};

/// The current serialized document format version.
pub const DOCUMENT_VERSION: u32 = 1;

/// A whole document on disk.
///
/// The live editor uses slotmap ids and parent links. This type deliberately contains neither,
/// making the persisted representation deterministic and independent of allocation history.
/// For example, an `x` atom is represented in JSON as:
///
/// ```text
/// {"version":1,"root":[{"type":"atom","data":{"latex":"x","class":"ord"}}]}
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Document {
    #[serde(deserialize_with = "deserialize_version")]
    version: u32,
    /// The nodes in the document's root sequence.
    pub root: Vec<NodeDoc>,
}

impl Document {
    /// Build a document containing `root` using the current format version.
    pub fn new(root: Vec<NodeDoc>) -> Self {
        Self {
            version: DOCUMENT_VERSION,
            root,
        }
    }

    /// Return the serialized format version.
    pub fn version(&self) -> u32 {
        self.version
    }

    /// Return the nodes in the root sequence.
    pub fn root(&self) -> &[NodeDoc] {
        &self.root
    }

    /// Return the number of nodes in the root sequence.
    pub fn len(&self) -> usize {
        self.root.len()
    }

    /// Return whether the root sequence contains no nodes.
    pub fn is_empty(&self) -> bool {
        self.root.is_empty()
    }

    /// Consume the document and return its root sequence.
    pub fn into_root(self) -> Vec<NodeDoc> {
        self.root
    }
}

impl Default for Document {
    fn default() -> Self {
        Self::new(Vec::new())
    }
}

fn deserialize_version<'de, D>(deserializer: D) -> Result<u32, D::Error>
where
    D: Deserializer<'de>,
{
    let version = u32::deserialize(deserializer)?;
    if version == DOCUMENT_VERSION {
        Ok(version)
    } else {
        Err(de::Error::custom(format_args!(
            "unsupported document version {version}; expected {DOCUMENT_VERSION}"
        )))
    }
}

/// A clipboard or paste fragment.
pub type DocFragment = Vec<NodeDoc>;

/// Generates parallel node declarations for the live tree and document tree.
macro_rules! node_kinds {
    (
        $(
            $variant:ident {
                $( $field:ident : $mode:ident $ty:ty ),* $(,)?
            }
        ),* $(,)?
    ) => {
        /// The serialized form of a node.
        #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
        #[serde(tag = "type", content = "data", rename_all = "snake_case")]
        pub enum NodeDoc {
            /// A serialized atom.
            Atom(Symbol),
            $(
                /// A serialized generated node variant.
                $variant {
                    $( /// A serialized generated node field.
                    $field : node_kinds!(@doc_ty $mode $ty) ),*
                },
            )*
            /// A serialized matrix.
            Matrix {
                /// The matrix environment.
                env: MatrixEnv,
                /// The serialized matrix cells by row.
                rows: Vec<Vec<Vec<NodeDoc>>>,
            },
        }

        impl Tree {
            fn node_to_doc(&self, node: NodeId) -> NodeDoc {
                match self.kind(node).expect("live node") {
                    Kind::Atom(s) => NodeDoc::Atom(s.clone()),
                    $(
                        Kind::$variant { $( $field ),* } => NodeDoc::$variant {
                            $( $field : node_kinds!(@to_doc self $mode $field) ),*
                        },
                    )*
                    Kind::Matrix { env, rows } => NodeDoc::Matrix {
                        env: *env,
                        rows: rows
                            .iter()
                            .map(|row| row.iter().map(|&c| self.seq_to_doc(c)).collect())
                            .collect(),
                    },
                }
            }

            fn doc_kind(&mut self, d: &NodeDoc) -> Kind {
                match d {
                    NodeDoc::Atom(s) => Kind::Atom(s.clone()),
                    $(
                        NodeDoc::$variant { $( $field ),* } => Kind::$variant {
                            $( $field : node_kinds!(@from_doc self $mode $field) ),*
                        },
                    )*
                    NodeDoc::Matrix { env, rows } => {
                        let mut grid = Vec::with_capacity(rows.len());
                        for row in rows {
                            let mut r = Vec::with_capacity(row.len());
                            for cell in row {
                                r.push(self.doc_seq(cell));
                            }
                            grid.push(r);
                        }
                        Kind::Matrix { env: *env, rows: grid }
                    }
                }
            }
        }
    };

    // Field type in NodeDoc.
    (@doc_ty seq     $ty:ty) => { Vec<NodeDoc> };
    (@doc_ty opt_seq $ty:ty) => { Option<Vec<NodeDoc>> };
    (@doc_ty copy    $ty:ty) => { $ty };
    (@doc_ty clone   $ty:ty) => { $ty };

    // Live Kind field to document field.
    (@to_doc $self:ident seq     $f:ident) => { $self.seq_to_doc(*$f) };
    (@to_doc $self:ident opt_seq $f:ident) => { $self.opt_seq_to_doc(*$f) };
    (@to_doc $self:ident copy    $f:ident) => { *$f };
    (@to_doc $self:ident clone   $f:ident) => { $f.clone() };

    // Document field to live Kind field.
    (@from_doc $self:ident seq     $f:ident) => { $self.doc_seq($f) };
    (@from_doc $self:ident opt_seq $f:ident) => { $self.doc_opt_seq($f) };
    (@from_doc $self:ident copy    $f:ident) => { *$f };
    (@from_doc $self:ident clone   $f:ident) => { $f.clone() };
}

node_kinds! {
    Frac {
        num: seq SeqId,
        den: seq SeqId,
        style: copy FracStyle,
    },
    Script {
        base: seq SeqId,
        sub: opt_seq SeqId,
        sup: opt_seq SeqId,
    },
    BigOp {
        op: clone Symbol,
        lower: seq SeqId,
        upper: seq SeqId,
    },
    Sqrt {
        index: seq SeqId,
        radicand: seq SeqId,
    },
    Delim {
        open: copy char,
        close: copy char,
        body: seq SeqId,
    },
    Accent {
        mark: copy Mark,
        base: seq SeqId,
    },
    UnderOver {
        base: seq SeqId,
        over: opt_seq SeqId,
        under: opt_seq SeqId,
        over_deco: copy Deco,
        under_deco: copy Deco,
    },
    Styled {
        variant: copy Variant,
        content: seq SeqId,
    },
    HostBox {
        token: copy u32,
    },
}

/// Collect every host object token reachable in `nodes` so hosts can dispose dead objects.
pub fn collect_host_tokens(nodes: &[NodeDoc], out: &mut std::collections::BTreeSet<u32>) {
    for d in nodes {
        match d {
            NodeDoc::Atom(_) => {}
            NodeDoc::HostBox { token } => {
                out.insert(*token);
            }
            NodeDoc::Frac { num, den, .. } => {
                collect_host_tokens(num, out);
                collect_host_tokens(den, out);
            }
            NodeDoc::Script { base, sub, sup } => {
                collect_host_tokens(base, out);
                for s in [sub, sup].into_iter().flatten() {
                    collect_host_tokens(s, out);
                }
            }
            NodeDoc::BigOp { lower, upper, .. } => {
                collect_host_tokens(lower, out);
                collect_host_tokens(upper, out);
            }
            NodeDoc::Sqrt { index, radicand } => {
                collect_host_tokens(index, out);
                collect_host_tokens(radicand, out);
            }
            NodeDoc::Delim { body, .. } => collect_host_tokens(body, out),
            NodeDoc::Accent { base, .. } => collect_host_tokens(base, out),
            NodeDoc::UnderOver { base, over, under, .. } => {
                collect_host_tokens(base, out);
                for s in [over, under].into_iter().flatten() {
                    collect_host_tokens(s, out);
                }
            }
            NodeDoc::Styled { content, .. } => collect_host_tokens(content, out),
            NodeDoc::Matrix { rows, .. } => {
                for cell in rows.iter().flatten() {
                    collect_host_tokens(cell, out);
                }
            }
        }
    }
}

impl Tree {
    /// Serialize the live tree to the id free document form.
    pub fn to_doc(&self) -> Document {
        Document::new(self.seq_to_doc(self.root()))
    }

    fn seq_to_doc(&self, seq: SeqId) -> Vec<NodeDoc> {
        self.items(seq).iter().map(|&n| self.node_to_doc(n)).collect()
    }

    fn opt_seq_to_doc(&self, seq: Option<SeqId>) -> Option<Vec<NodeDoc>> {
        seq.map(|s| self.seq_to_doc(s))
    }

    /// Rebuild a tree from the document form with fresh ids.
    pub fn from_doc(doc: &Document) -> Self {
        let mut t = Tree::new();
        let root = t.root();
        for d in doc.root() {
            t.push_doc_node(root, d);
        }
        t
    }

    /// Splice a clipboard fragment into `at.seq` starting at `at.index`.
    pub fn insert_fragment(&mut self, at: crate::model::Cursor, frag: &DocFragment) -> crate::model::Cursor {
        let mut idx = at.index;
        for d in frag {
            let kind = self.doc_kind(d);
            let node = self.nodes.insert(Node {
                parent: at.seq,
                kind,
            });
            for s in self.child_seqs(node) {
                if let Some(sq) = self.seqs.get_mut(s) {
                    sq.parent = Some(node);
                }
            }
            if let Some(sq) = self.seqs.get_mut(at.seq) {
                let i = idx.min(sq.items.len());
                sq.items.insert(i, node);
            }
            idx += 1;
        }
        crate::model::Cursor {
            seq: at.seq,
            index: idx,
        }
    }

    fn push_doc_node(&mut self, seq: SeqId, d: &NodeDoc) {
        let kind = self.doc_kind(d);
        let node = self.nodes.insert(Node { parent: seq, kind });
        for s in self.child_seqs(node) {
            if let Some(sq) = self.seqs.get_mut(s) {
                sq.parent = Some(node);
            }
        }
        if let Some(sq) = self.seqs.get_mut(seq) {
            sq.items.push(node);
        }
    }

    fn doc_seq(&mut self, docs: &[NodeDoc]) -> SeqId {
        let seq = self.alloc_seq(None);
        for d in docs {
            self.push_doc_node(seq, d);
        }
        seq
    }

    fn doc_opt_seq(&mut self, docs: &Option<Vec<NodeDoc>>) -> Option<SeqId> {
        match docs {
            Some(d) => Some(self.doc_seq(d)),
            None => None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::model::{Cursor, MathClass};

    fn atom(c: &str) -> Symbol {
        Symbol {
            latex: c.into(),
            class: MathClass::Ord,
        }
    }

    #[test]
    fn doc_roundtrip() {
        let mut t = Tree::new();
        let root = t.root();
        let c = t.insert_fraction(Cursor { seq: root, index: 0 }, FracStyle::Bar, None);
        let c = t.insert_atom(c, atom("a")); // Numerator is `a`.
        let _ = c;
        // Add a script in the denominator.
        let frac = t.items(root)[0];
        let den = t.child_seqs(frac)[1];
        t.insert_atom(Cursor { seq: den, index: 0 }, atom("b"));

        let d1 = t.to_doc();
        let json = serde_json::to_string(&d1).unwrap();
        let decoded = serde_json::from_str(&json).unwrap();
        let t2 = Tree::from_doc(&decoded);
        let d2 = t2.to_doc();
        assert_eq!(d1, d2);
    }

    /// Round trips one of every kind so bad `node_kinds!` mode tags fail as assertions.
    #[test]
    fn doc_roundtrip_all_kinds() {
        use crate::model::{Mark, MatrixEnv, ScriptSlot, UnderOverSpec, Variant};
        let mut t = Tree::new();
        let root = t.root();
        let end = |t: &Tree| Cursor { seq: root, index: t.len(root) };

        // Atom plus Script exercises `opt_seq` with content.
        t.insert_atom(Cursor { seq: root, index: 0 }, atom("a"));
        let c = t.attach_script(Cursor { seq: root, index: 1 }, ScriptSlot::Sup);
        t.insert_atom(c, atom("2"));
        // Fraction.
        let c = t.insert_fraction(end(&t), FracStyle::Bar, None);
        t.insert_atom(c, atom("x"));
        // Square root.
        let c = t.insert_sqrt(end(&t), None);
        t.insert_atom(c, atom("y"));
        // Big operator.
        t.insert_big_op(end(&t), Symbol { latex: "\\sum".into(), class: MathClass::Op });
        // Delimiter pair.
        let c = t.insert_delimiters(end(&t), '(', ')', None);
        t.insert_atom(c, atom("z"));
        // Accent.
        let c = t.insert_accent(end(&t), Mark::Hat, None);
        t.insert_atom(c, atom("b"));
        // Styled content.
        let c = t.insert_styled(end(&t), Variant::Bold, None);
        t.insert_atom(c, atom("c"));
        // UnderOver with an over slot exercises `opt_seq` with an empty value.
        let spec = UnderOverSpec { over: true, under: false, over_deco: Deco::Brace, under_deco: Deco::None };
        let c = t.insert_under_over(end(&t), spec, None);
        t.insert_atom(c, atom("d"));
        // Matrix exercises the handwritten arm.
        let c = t.insert_matrix(end(&t), MatrixEnv::Pmatrix, 2, 2);
        t.insert_atom(c, atom("e"));
        // Host object atom keeps its token through the round trip.
        t.insert_host_box(end(&t), 7);

        let d1 = t.to_doc();
        let json = serde_json::to_string(&d1).unwrap();
        let decoded = serde_json::from_str(&json).unwrap();
        let t2 = Tree::from_doc(&decoded);
        let d2 = t2.to_doc();
        assert_eq!(d1, d2);
    }

    /// Pins serde field order and the distinction between `Some` holding empty data and `None`.
    #[test]
    fn doc_serde_field_order_is_canonical() {
        let pos = |s: &str, key: &str| s.find(&format!("\"{key}\"")).unwrap_or_else(|| panic!("missing {key} in {s}"));

        let bigop = NodeDoc::BigOp {
            op: Symbol { latex: "\\sum".into(), class: MathClass::Op },
            lower: vec![],
            upper: vec![],
        };
        let s = serde_json::to_string(&bigop).unwrap();
        assert!(pos(&s, "op") < pos(&s, "lower") && pos(&s, "lower") < pos(&s, "upper"), "BigOp order: {s}");

        let uo = NodeDoc::UnderOver {
            base: vec![],
            over: Some(vec![]), // Distinguishes `Some(empty)` from `None`.
            under: None,
            over_deco: Deco::Brace,
            under_deco: Deco::None,
        };
        let s = serde_json::to_string(&uo).unwrap();
        assert!(
            pos(&s, "base") < pos(&s, "over")
                && pos(&s, "over") < pos(&s, "under")
                && pos(&s, "under") < pos(&s, "over_deco")
                && pos(&s, "over_deco") < pos(&s, "under_deco"),
            "UnderOver order: {s}"
        );
        // `Some` holding empty data and `None` survive serde round trip distinctly.
        let back: NodeDoc = serde_json::from_str(&s).unwrap();
        assert_eq!(back, uo);
    }

    #[test]
    fn collect_host_tokens_reaches_nested_slots() {
        let mut t = Tree::new();
        let root = t.root();
        // Top level, numerator, and a matrix cell each hold a host box.
        t.insert_host_box(Cursor { seq: root, index: 0 }, 3);
        let cnum = t.insert_fraction(Cursor { seq: root, index: 1 }, FracStyle::Bar, None);
        t.insert_host_box(cnum, 7);
        let c = t.insert_matrix(Cursor { seq: root, index: 2 }, MatrixEnv::Pmatrix, 2, 2);
        t.insert_host_box(c, 9);

        let mut tokens = std::collections::BTreeSet::new();
        collect_host_tokens(t.to_doc().root(), &mut tokens);
        assert_eq!(tokens.into_iter().collect::<Vec<_>>(), vec![3, 7, 9]);
    }

    #[test]
    fn document_json_has_a_stable_shape() {
        let doc = Document::new(vec![NodeDoc::Atom(atom("x"))]);

        let json = serde_json::to_string(&doc).unwrap();

        assert_eq!(
            json,
            r#"{"version":1,"root":[{"type":"atom","data":{"latex":"x","class":"ord"}}]}"#
        );
    }

    /// A clipboard fragment travels as a `Document`, so hosts embed this exact wire shape.
    #[test]
    fn host_box_fragment_json_has_a_stable_shape() {
        let doc = Document::new(vec![NodeDoc::HostBox { token: 17 }]);

        let json = serde_json::to_string(&doc).unwrap();

        assert_eq!(json, r#"{"version":1,"root":[{"type":"host_box","data":{"token":17}}]}"#);
        let back: Document = serde_json::from_str(&json).unwrap();
        assert_eq!(back, doc);
    }

    #[test]
    fn unknown_document_version_is_rejected() {
        let error = serde_json::from_str::<Document>(r#"{"version":2,"root":[]}"#)
            .unwrap_err()
            .to_string();

        assert!(error.contains("unsupported document version 2"), "{error}");
    }
}