Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

20.0 KB
Raw Blame
//! A small, mutable, namespace-aware XML DOM.
//!
//! Parts are parsed into an arena of nodes. Everything in the source is kept
//! (unknown elements, extension lists, comments, attribute order, the prolog),
//! so a part the editor touches is re-serialized with only the edited nodes
//! changed. Elements and attributes carry resolved [`Ns`] identifiers, so
//! lookups never depend on the prefixes a producer chose.

mod fragment;
mod ns;
mod parse;
mod write;

pub use ns::Ns;

/// Index of a node inside an [`XmlDoc`] arena.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct NodeId(u32);

/// How an element or attribute prefix is spelled on output.
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) enum Prefix {
    /// The prefix exactly as written in the source (`None` = unprefixed).
    Written(Option<Box<str>>),
    /// Created by the engine: resolved against in-scope declarations on output.
    Auto,
}

/// An attribute of an element.
#[derive(Clone, Debug)]
pub struct Attr {
    pub(crate) prefix: Prefix,
    pub(crate) local: Box<str>,
    pub(crate) ns: Ns,
    pub(crate) value: String,
}

impl Attr {
    /// Whether this attribute is a namespace declaration (`xmlns` / `xmlns:p`).
    pub fn is_ns_decl(&self) -> bool {
        match &self.prefix {
            Prefix::Written(Some(p)) => &**p == "xmlns",
            Prefix::Written(None) => &*self.local == "xmlns",
            Prefix::Auto => false,
        }
    }

    /// Local name of the attribute.
    pub fn local(&self) -> &str {
        &self.local
    }

    /// Namespace of the attribute.
    pub fn ns(&self) -> Ns {
        self.ns
    }

    /// Attribute value (entity references already decoded).
    pub fn value(&self) -> &str {
        &self.value
    }
}

/// An element node.
#[derive(Clone, Debug)]
pub struct Element {
    pub(crate) prefix: Prefix,
    pub(crate) local: Box<str>,
    pub(crate) ns: Ns,
    pub(crate) attrs: Vec<Attr>,
    pub(crate) children: Vec<NodeId>,
}

/// The payload of a node.
#[derive(Clone, Debug)]
pub enum NodeKind {
    /// An element.
    Element(Element),
    /// Character data (entity references decoded).
    Text(String),
    /// A CDATA section's raw content.
    CData(String),
    /// A comment's raw content.
    Comment(String),
    /// A processing instruction's raw content (between `<?` and `?>`).
    Pi(String),
}

#[derive(Clone, Debug)]
struct Node {
    parent: Option<NodeId>,
    kind: NodeKind,
}

/// A parsed XML document.
#[derive(Clone, Debug)]
pub struct XmlDoc {
    /// Everything before the root element, verbatim (declaration, comments).
    prolog: String,
    nodes: Vec<Node>,
    root: NodeId,
    /// URIs of namespaces outside the well-known table, by `Ns.0 - FIRST_DYNAMIC`.
    dynamic_ns: Vec<String>,
}

/// The XML declaration written for documents created from scratch.
pub const STANDARD_DECLARATION: &str =
    "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\r\n";

impl XmlDoc {
    /// Parses `bytes` (UTF-8 or UTF-16 with a byte order mark).
    /// `part` names the source in error messages.
    pub fn parse(bytes: &[u8], part: &str) -> crate::Result<Self> {
        parse::parse(bytes, part)
    }

    /// Creates a document whose root element is `(ns, local)`, declaring
    /// the namespace with its canonical prefix.
    pub fn new_root(ns: Ns, local: &str) -> Self {
        let mut doc = Self {
            prolog: STANDARD_DECLARATION.to_owned(),
            nodes: Vec::new(),
            root: NodeId(0),
            dynamic_ns: Vec::new(),
        };
        let root = doc.create_element(ns, local);
        doc.root = root;
        doc
    }

    /// Serializes the document to UTF-8 bytes.
    pub fn to_bytes(&self) -> Vec<u8> {
        write::write(self)
    }

    /// The root element.
    pub fn root(&self) -> NodeId {
        self.root
    }

    fn node(&self, id: NodeId) -> &Node {
        &self.nodes[id.0 as usize]
    }

    fn node_mut(&mut self, id: NodeId) -> &mut Node {
        &mut self.nodes[id.0 as usize]
    }

    pub(crate) fn push_node(&mut self, parent: Option<NodeId>, kind: NodeKind) -> NodeId {
        let id = NodeId(u32::try_from(self.nodes.len()).expect("xml arena overflow"));
        self.nodes.push(Node { parent, kind });
        id
    }

    /// The payload of a node.
    pub fn kind(&self, id: NodeId) -> &NodeKind {
        &self.node(id).kind
    }

    /// The element payload of a node, if it is an element.
    pub fn element(&self, id: NodeId) -> Option<&Element> {
        match &self.node(id).kind {
            NodeKind::Element(e) => Some(e),
            _ => None,
        }
    }

    fn element_mut(&mut self, id: NodeId) -> Option<&mut Element> {
        match &mut self.node_mut(id).kind {
            NodeKind::Element(e) => Some(e),
            _ => None,
        }
    }

    /// Parent of a node (`None` for the root and detached nodes).
    pub fn parent(&self, id: NodeId) -> Option<NodeId> {
        self.node(id).parent
    }

    /// Namespace of an element (`Ns::NONE` for non-elements).
    pub fn ns(&self, id: NodeId) -> Ns {
        self.element(id).map_or(Ns::NONE, |e| e.ns)
    }

    /// Local name of an element (empty for non-elements).
    pub fn local(&self, id: NodeId) -> &str {
        self.element(id).map_or("", |e| &e.local)
    }

    /// Whether `id` is the element `(ns, local)`.
    pub fn is(&self, id: NodeId, ns: Ns, local: &str) -> bool {
        self.element(id)
            .is_some_and(|e| e.ns == ns && &*e.local == local)
    }

    /// All child nodes (elements, text, comments...).
    pub fn child_nodes(&self, id: NodeId) -> &[NodeId] {
        self.element(id).map_or(&[], |e| &e.children)
    }

    /// Child elements, in document order.
    pub fn children(&self, id: NodeId) -> impl Iterator<Item = NodeId> + '_ {
        self.child_nodes(id)
            .iter()
            .copied()
            .filter(|&c| matches!(self.node(c).kind, NodeKind::Element(_)))
    }

    /// Child elements named `(ns, local)`.
    pub fn children_named<'a>(
        &'a self,
        id: NodeId,
        ns: Ns,
        local: &'a str,
    ) -> impl Iterator<Item = NodeId> + 'a {
        self.children(id).filter(move |&c| self.is(c, ns, local))
    }

    /// The first child element named `(ns, local)`.
    pub fn child(&self, id: NodeId, ns: Ns, local: &str) -> Option<NodeId> {
        self.children(id).find(|&c| self.is(c, ns, local))
    }

    /// Follows a path of child element names in one namespace.
    pub fn path(&self, id: NodeId, ns: Ns, path: &[&str]) -> Option<NodeId> {
        path.iter()
            .try_fold(id, |at, name| self.child(at, ns, name))
    }

    /// The first child element (of any name).
    pub fn first_child(&self, id: NodeId) -> Option<NodeId> {
        self.children(id).next()
    }

    /// Attributes of an element, excluding namespace declarations.
    pub fn attrs(&self, id: NodeId) -> impl Iterator<Item = &Attr> + '_ {
        self.element(id)
            .map(|e| e.attrs.as_slice())
            .unwrap_or(&[])
            .iter()
            .filter(|a| !a.is_ns_decl())
    }

    /// Value of the unprefixed attribute `name`.
    pub fn attr(&self, id: NodeId, name: &str) -> Option<&str> {
        self.attr_ns(id, Ns::NONE, name)
    }

    /// Value of the attribute `(ns, local)`.
    pub fn attr_ns(&self, id: NodeId, ns: Ns, local: &str) -> Option<&str> {
        self.attrs(id)
            .find(|a| a.ns == ns && &*a.local == local)
            .map(|a| a.value.as_str())
    }

    /// Parses an unprefixed attribute as an integer.
    pub fn attr_i64(&self, id: NodeId, name: &str) -> Option<i64> {
        self.attr(id, name).and_then(parse_i64)
    }

    /// Parses an unprefixed attribute as a float.
    pub fn attr_f64(&self, id: NodeId, name: &str) -> Option<f64> {
        self.attr(id, name)
            .and_then(|v| v.trim().parse::<f64>().ok())
    }

    /// Parses an unprefixed boolean attribute (`1`/`true`/`on` vs `0`/`false`/`off`).
    pub fn attr_bool(&self, id: NodeId, name: &str) -> Option<bool> {
        self.attr(id, name).and_then(parse_bool)
    }

    /// Concatenated text of all descendant text and CDATA nodes.
    pub fn text(&self, id: NodeId) -> String {
        let mut out = String::new();
        self.collect_text(id, &mut out);
        out
    }

    fn collect_text(&self, id: NodeId, out: &mut String) {
        match &self.node(id).kind {
            NodeKind::Text(t) | NodeKind::CData(t) => out.push_str(t),
            NodeKind::Element(e) => {
                for &c in &e.children {
                    self.collect_text(c, out);
                }
            }
            NodeKind::Comment(_) | NodeKind::Pi(_) => {}
        }
    }

    /// Descendant elements (pre-order, excluding `id` itself).
    pub fn descendants(&self, id: NodeId) -> Vec<NodeId> {
        let mut out = Vec::new();
        let mut stack: Vec<NodeId> = self.children(id).collect();
        stack.reverse();
        while let Some(n) = stack.pop() {
            out.push(n);
            let before = stack.len();
            stack.extend(self.children(n));
            stack[before..].reverse();
        }
        out
    }

    /// The URI of a namespace identifier.
    pub fn ns_uri(&self, ns: Ns) -> Option<&str> {
        if ns.0 >= Ns::FIRST_DYNAMIC {
            return self
                .dynamic_ns
                .get(usize::from(ns.0 - Ns::FIRST_DYNAMIC))
                .map(String::as_str);
        }
        ns::canonical(ns).map(|(uri, _)| uri)
    }

    pub(crate) fn intern_ns(&mut self, uri: &str) -> Ns {
        if uri.is_empty() {
            return Ns::NONE;
        }
        if let Some((_, id, _)) = ns::KNOWN.iter().find(|(u, _, _)| *u == uri) {
            return *id;
        }
        if let Some(i) = self.dynamic_ns.iter().position(|u| u == uri) {
            return Ns(Ns::FIRST_DYNAMIC + i as u16);
        }
        self.dynamic_ns.push(uri.to_owned());
        Ns(Ns::FIRST_DYNAMIC + (self.dynamic_ns.len() - 1) as u16)
    }

    /// Declares `xmlns:prefix="uri"` on element `id`, so engine-created
    /// elements in that namespace under it are written with `prefix` (as
    /// Office writes namespaces it declares locally); returns the namespace.
    pub(crate) fn declare_ns(&mut self, id: NodeId, prefix: &str, uri: &str) -> Ns {
        let ns = self.intern_ns(uri);
        if let Some(e) = self.element_mut(id) {
            e.attrs.retain(|a| !(a.is_ns_decl() && &*a.local == prefix));
            let at = e.attrs.iter().take_while(|a| a.is_ns_decl()).count();
            e.attrs.insert(
                at,
                Attr {
                    prefix: Prefix::Written(Some("xmlns".into())),
                    local: prefix.into(),
                    ns: Ns::NONE,
                    value: uri.to_owned(),
                },
            );
        }
        ns
    }

    // ---- mutation -------------------------------------------------------

    /// Creates a detached element `(ns, local)`; its prefix is chosen on output.
    pub fn create_element(&mut self, ns: Ns, local: &str) -> NodeId {
        self.push_node(
            None,
            NodeKind::Element(Element {
                prefix: Prefix::Auto,
                local: local.into(),
                ns,
                attrs: Vec::new(),
                children: Vec::new(),
            }),
        )
    }

    /// Creates a detached text node.
    pub fn create_text(&mut self, text: &str) -> NodeId {
        self.push_node(None, NodeKind::Text(text.to_owned()))
    }

    /// Sets (or adds) the unprefixed attribute `name`.
    pub fn set_attr(&mut self, id: NodeId, name: &str, value: &str) {
        self.set_attr_ns(id, Ns::NONE, name, value);
    }

    /// Sets (or adds) the attribute `(ns, local)`.
    pub fn set_attr_ns(&mut self, id: NodeId, ns: Ns, local: &str, value: &str) {
        let Some(e) = self.element_mut(id) else {
            return;
        };
        if let Some(a) = e
            .attrs
            .iter_mut()
            .find(|a| !a.is_ns_decl() && a.ns == ns && &*a.local == local)
        {
            value.clone_into(&mut a.value);
            return;
        }
        let prefix = if ns == Ns::NONE {
            Prefix::Written(None)
        } else {
            Prefix::Auto
        };
        e.attrs.push(Attr {
            prefix,
            local: local.into(),
            ns,
            value: value.to_owned(),
        });
    }

    /// Renames an element in place, keeping its namespace, attributes, and children.
    pub fn rename(&mut self, id: NodeId, local: &str) {
        if let Some(e) = self.element_mut(id) {
            e.local = local.into();
        }
    }

    /// Removes the unprefixed attribute `name`, if present.
    pub fn remove_attr(&mut self, id: NodeId, name: &str) {
        self.remove_attr_ns(id, Ns::NONE, name);
    }

    /// Removes the attribute `(ns, local)`, if present.
    pub fn remove_attr_ns(&mut self, id: NodeId, ns: Ns, local: &str) {
        if let Some(e) = self.element_mut(id) {
            e.attrs
                .retain(|a| a.is_ns_decl() || a.ns != ns || &*a.local != local);
        }
    }

    /// Detaches a node from its parent. The node stays valid and can be re-attached.
    pub fn detach(&mut self, id: NodeId) {
        if let Some(parent) = self.node(id).parent {
            if let Some(e) = self.element_mut(parent) {
                e.children.retain(|&c| c != id);
            }
            self.node_mut(id).parent = None;
        }
    }

    /// Appends `child` (detaching it first) as the last child of `parent`.
    pub fn append_child(&mut self, parent: NodeId, child: NodeId) {
        let len = self.child_nodes(parent).len();
        self.insert_child(parent, len, child);
    }

    /// Inserts `child` at `index` among all child nodes of `parent`.
    pub fn insert_child(&mut self, parent: NodeId, index: usize, child: NodeId) {
        self.detach(child);
        let Some(e) = self.element_mut(parent) else {
            return;
        };
        let index = index.min(e.children.len());
        e.children.insert(index, child);
        self.node_mut(child).parent = Some(parent);
    }

    /// Inserts `child` immediately before `reference` (a child of `parent`).
    pub fn insert_before(&mut self, reference: NodeId, child: NodeId) {
        let Some(parent) = self.parent(reference) else {
            return;
        };
        let index = self
            .child_nodes(parent)
            .iter()
            .position(|&c| c == reference)
            .unwrap_or(0);
        self.insert_child(parent, index, child);
    }

    /// Inserts `child` immediately after `reference` (a child of `parent`).
    pub fn insert_after(&mut self, reference: NodeId, child: NodeId) {
        let Some(parent) = self.parent(reference) else {
            return;
        };
        let index = self
            .child_nodes(parent)
            .iter()
            .position(|&c| c == reference)
            .map_or(usize::MAX, |i| i + 1);
        self.insert_child(parent, index, child);
    }

    /// Position of `child` among all child nodes of its parent.
    pub fn index_in_parent(&self, child: NodeId) -> Option<usize> {
        let parent = self.parent(child)?;
        self.child_nodes(parent).iter().position(|&c| c == child)
    }

    /// Replaces all children of `id` with one text node.
    pub fn set_text(&mut self, id: NodeId, text: &str) {
        for c in self.child_nodes(id).to_vec() {
            self.detach(c);
        }
        if !text.is_empty() {
            let t = self.create_text(text);
            self.append_child(id, t);
        }
    }

    /// Returns the child `(ns, local)`, creating it with `create` placement if absent.
    ///
    /// `order` lists the schema order of `parent`'s children; the new element is
    /// inserted before the first existing sibling that comes later in that order,
    /// keeping the output schema-valid.
    pub fn ensure_child(&mut self, parent: NodeId, ns: Ns, local: &str, order: &[&str]) -> NodeId {
        if let Some(c) = self.child(parent, ns, local) {
            return c;
        }
        let new = self.create_element(ns, local);
        self.insert_in_order(parent, new, order);
        new
    }

    /// Inserts the element `child` into `parent` at the position dictated by `order`.
    pub fn insert_in_order(&mut self, parent: NodeId, child: NodeId, order: &[&str]) {
        let name = self.local(child).to_owned();
        let rank = order.iter().position(|n| *n == name);
        let before = rank.and_then(|rank| {
            self.children(parent).find(|&c| {
                order
                    .iter()
                    .position(|n| *n == self.local(c))
                    .is_some_and(|r| r > rank)
            })
        });
        match before {
            Some(b) => self.insert_before(b, child),
            None => self.append_child(parent, child),
        }
    }

    /// Removes every child element named `(ns, local)`.
    pub fn remove_children_named(&mut self, parent: NodeId, ns: Ns, local: &str) {
        let doomed: Vec<_> = self.children_named(parent, ns, local).collect();
        for d in doomed {
            self.detach(d);
        }
    }

    /// Deep-copies the subtree at `id` (detached copy in the same document).
    pub fn deep_clone(&mut self, id: NodeId) -> NodeId {
        let kind = match &self.node(id).kind {
            NodeKind::Element(e) => NodeKind::Element(Element {
                children: Vec::new(),
                ..e.clone()
            }),
            other => other.clone(),
        };
        let copy = self.push_node(None, kind);
        for c in self.child_nodes(id).to_vec() {
            let cc = self.deep_clone(c);
            self.append_child(copy, cc);
        }
        copy
    }

    /// Copies the subtree at `id` of `other` into this document (detached).
    ///
    /// Prefixes are re-resolved on output, so namespaces map correctly even if
    /// the two documents bind different prefixes.
    pub fn import(&mut self, other: &XmlDoc, id: NodeId) -> NodeId {
        let kind = match &other.node(id).kind {
            NodeKind::Element(e) => {
                let ns = self.import_ns(other, e.ns);
                let attrs = e
                    .attrs
                    .iter()
                    .filter(|a| !a.is_ns_decl())
                    .map(|a| {
                        let ans = self.import_ns(other, a.ns);
                        Attr {
                            prefix: if ans == Ns::NONE {
                                Prefix::Written(None)
                            } else {
                                Prefix::Auto
                            },
                            local: a.local.clone(),
                            ns: ans,
                            value: a.value.clone(),
                        }
                    })
                    .collect();
                NodeKind::Element(Element {
                    prefix: Prefix::Auto,
                    local: e.local.clone(),
                    ns,
                    attrs,
                    children: Vec::new(),
                })
            }
            other_kind => other_kind.clone(),
        };
        let copy = self.push_node(None, kind);
        for &c in other.child_nodes(id) {
            let cc = self.import(other, c);
            self.append_child(copy, cc);
        }
        copy
    }

    fn import_ns(&mut self, other: &XmlDoc, ns: Ns) -> Ns {
        if ns.0 < Ns::FIRST_DYNAMIC {
            return ns;
        }
        match other.ns_uri(ns) {
            Some(uri) => {
                let uri = uri.to_owned();
                self.intern_ns(&uri)
            }
            None => Ns::NONE,
        }
    }
}

/// Parses an XML integer attribute (tolerating a leading `+` and whitespace).
pub fn parse_i64(v: &str) -> Option<i64> {
    let v = v.trim();
    let v = v.strip_prefix('+').unwrap_or(v);
    v.parse::<i64>()
        .ok()
        .or_else(|| v.parse::<f64>().ok().map(|f| f.round() as i64))
}

/// Parses an XML schema boolean.
pub fn parse_bool(v: &str) -> Option<bool> {
    match v.trim() {
        "1" | "true" | "on" | "t" => Some(true),
        "0" | "false" | "off" | "f" => Some(false),
        _ => None,
    }
}

#[cfg(test)]
mod test;