Skip to content
niso

niso-xml

Generated from crates/niso-xml/CONTRACT.md when the site was built at 7aa23e2.

What parse and serialize promise, and what a Builder or a Tree must guarantee for them.

Parsing

Section titled “Parsing”
  • XML 1.0 and Namespaces in XML 1.0. parse accepts exactly the well-formed, namespace-well-formed documents, and reports the first error of any other with Expat’s message (the one Firefox’s error documents show) and its line and column. Line breaks are normalized first (CR LF and CR become LF) and a leading byte order mark is dropped; a character XML’s Char production doesn’t allow is an error wherever it is.
  • No DTD processing beyond the internal subset’s entities. The internal subset’s general entities are expanded where they’re referenced, in content (where their text is parsed as markup) and in attribute values; the five predefined entities and character references always work. External entities aren’t read (a reference to one expands to nothing in content and is an error in an attribute value), a reference to an unparsed (NDATA) entity is an error, and other declarations are skipped, so no default attributes come from a DTD. As in Expat, declarations after a parameter entity reference are skipped too (it isn’t read), and when the doctype has an external subset or the internal subset a parameter entity reference, a reference to an undeclared entity is skipped unless the document is standalone; otherwise it is an error. A doctype with one of the XHTML or MathML DTDs’ public IDs (as Firefox’s catalog has them) defines HTML’s named character references, from markup5ever’s table.
  • Limits. Entity references nest at most MAX_ENTITY_DEPTH (32) deep. Their output (the replacement texts read, and NODE_COST (128) for each node and attribute built from one) may be at most MAX_AMPLIFICATION (100) times the document’s size, or AMPLIFICATION_THRESHOLD (8 MiB) if that is more, as Expat’s amplification limit. Past either, the parse fails. Parsing doesn’t recurse per element, so a document may nest as deep as it likes, and its attribute and namespace checks take linear time in the number of attributes.
  • What the builder sees. document once, then each node is created and appended to its parent before anything after it in the source: the doctype, comments and processing instructions around the document element are the document’s children. Character data between markup is one text node (references included); a CDATA section is a node of its own. The XML declaration makes no node. Element and attribute names come resolved: namespace (None for none), prefix and local name; namespace declarations are attributes in the XMLNS namespace, xmlns with no prefix and xmlns:p with the prefix xmlns.
  • On an error the builder holds the nodes made before it, appended where they belong; the caller decides what to do with them.

Serializing

Section titled “Serializing”
  • serialize is DOM Parsing’s “produce an XML serialization”, with two changes WPT tests: an attribute named xmlns in no namespace declares the default namespace as one in the XMLNS namespace does, and a prefix for an attribute whose namespace has none in scope is always generated (ns1, ns2, …). With require_well_formed, it returns NotWellFormed where the standard throws.
  • It keeps a stack of its own, so a tree may be as deep as it likes.

What a Tree guarantees

Section titled “What a Tree guarantees”
  • Nodes are handles that stay valid, and the tree doesn’t change, during a serialization. kind is one of Kind’s for every node.
  • children are a node’s children in order; template_contents is an HTML template element’s contents (a document fragment), which the serialization uses in place of its children.
  • name and attributes give namespaces as None for no namespace, never empty, with namespace declarations among the attributes in the XMLNS namespace.
  • data is a text node’s, CDATA section’s, comment’s or processing instruction’s data; target a processing instruction’s target; doctype a doctype’s name, public ID and system ID.

Bindings

Section titled “Bindings”
  • C: none of its own; the core’s niso_dom_implementation_parse_document and niso_node_xml_serialization (idl/dom-parsing.webidl, [NisoNative]) call this crate.
  • Glue: glue/dom-parsing.js, DOMParser and XMLSerializer over those two, the optional dom-parsing section (glue-dom-parsing). XMLHttpRequest’s documents call parseDocument from its own section.