XML Documents

Introduction

XmlDocument owns ordered top-level nodes and one root element. XmlNode represents elements, mixed content, and preserved markup; XmlParseOptions bounds incoming text. For parsing, construction, navigation, serialization, and reference behavior, see Reading and Writing XML.

textContentOrThrow() reports unresolved entity references with NotFoundError. textContent() returns no value for the same condition.

Interface

class XmlAttribute

An ordered XML attribute with preserved references from parsed input.

Public Functions

inline XmlAttribute(text::String name, text::String value)

Create a plain-text attribute.

inline const text::String &name() const noexcept

Get the qualified attribute name.

inline const text::String &value() const noexcept

Get the stored value; parsed references retain their original spelling.

inline bool hasReferences() const noexcept

Test whether the stored value contains preserved references.

class XmlDocument

A mutable XML document with ordered prolog and root nodes.

See: XML Documents

Public Functions

XmlDocument() = default

Create an empty document.

inline const util::List<XmlNodePtr> &nodes() const noexcept

Get all top-level nodes in document order.

XmlNodePtr root() const noexcept

Get the document element, or an empty pointer.

XmlNodePtr add(XmlNodePtr node)

Add a top-level node.

XmlNodePtr addRoot(text::String name, text::String text = {})

Create and add the document element with optional text.

text::String toString(XmlFormatOptions options = {}) const

Serialize this document as XML text.

Public Static Functions

static auto fromString(const text::String &text, XmlParseOptions options = {}) noexcept -> std::optional<XmlDocument>

Parse XML, returning no value on failure.

static XmlDocument fromStringOrThrow(const text::String &text, XmlParseOptions options = {})

Parse an XML document.

Throws:

err::ParseError – For malformed or unsupported input.

class XmlFormatOptions

Extension point for XML serialization settings.

class XmlNode

A mutable XML DOM node with ordered children.

See: XML Documents

Public Functions

inline XmlNodeType type() const noexcept

Get the node kind.

inline const text::String &name() const noexcept

Get an element, instruction, or entity name.

inline const text::String &text() const noexcept

Get this node’s own text or preserved markup.

inline const util::List<XmlAttribute> &attributes() const noexcept

Get ordered attributes.

inline const util::List<XmlNodePtr> &children() const noexcept

Get ordered children.

std::optional<text::String> getAttribute(const text::String &name) const

Get a decoded attribute, or no value if absent or unresolved.

std::optional<text::String> textContent() const

Get all descendant character data, or no value if an entity is unresolved.

text::String textContentOrThrow() const

Get all descendant character data.

Throws:

err::NotFoundError – If an entity reference has no resolved text value.

XmlNode &setAttribute(text::String name, text::String value)

Set or replace a plain-text attribute.

XmlNodePtr add(XmlNodePtr child)

Append a child node to an element.

XmlNodePtr addElement(text::String name, text::String text = {})

Create and append an element with optional text in one step.

XmlNodePtr addText(text::String text)

Create and append text.

Public Static Functions

static XmlNodePtr createElement(text::String name, text::String text = {})

Create an element, optionally with a text child.

static XmlNodePtr createText(text::String text)

Create a text node.

static XmlNodePtr createCData(text::String text)

Create a CDATA node.

static XmlNodePtr createComment(text::String text)

Create a comment node.

static XmlNodePtr createProcessingInstruction(text::String name, text::String text)

Create a processing instruction.

static XmlNodePtr createEntityReference(text::String name)

Create an unresolved entity reference; name omits & and ;.

static XmlNodePtr createDocType(text::String raw)

Create a preserved DOCTYPE declaration including its markup.

static XmlNodePtr createDeclaration(text::String raw)

Create a preserved XML declaration including its markup.

enum class erbsland::data::xml::XmlNodeType : uint8_t

Kinds of nodes retained in an XML document.

Values:

enumerator Element

Element with ordered attributes and children.

enumerator Text

Character data.

enumerator Comment

Comment content.

enumerator CData

CDATA content.

enumerator ProcessingInstruction

Processing instruction.

enumerator DocType

Unresolved DOCTYPE declaration.

enumerator Declaration

XML declaration.

enumerator EntityReference

Named or numeric entity reference.

class XmlParseOptions

Safety limits for parsing XML.

Public Functions

inline constexpr unit::ByteCount maximumInputLength() const noexcept

Get the input byte limit.

inline constexpr XmlParseOptions &setMaximumInputLength(unit::ByteCount value) noexcept

Set the input byte limit.

inline constexpr unit::ItemCount maximumNesting() const noexcept

Get the nesting limit.

inline constexpr XmlParseOptions &setMaximumNesting(unit::ItemCount value) noexcept

Set the nesting limit.

inline constexpr unit::ItemCount maximumNodeCount() const noexcept

Get the node count limit.

inline constexpr XmlParseOptions &setMaximumNodeCount(unit::ItemCount value) noexcept

Set the node count limit.

inline constexpr unit::ByteCount maximumStringLength() const noexcept

Get the maximum byte length of one text or attribute value.

inline constexpr XmlParseOptions &setMaximumStringLength(unit::ByteCount value) noexcept

Set the maximum byte length of one text or attribute value.

Public Static Attributes

static constexpr auto cDefaultMaximumInputLength = unit::ByteCount{16U * 1024U * 1024U}

Input limit.

static constexpr auto cDefaultMaximumNesting = unit::ItemCount{64U}

Element depth limit.

static constexpr auto cDefaultMaximumNodeCount = unit::ItemCount{1'000'000U}

Node limit.

static constexpr auto cDefaultMaximumStringLength = unit::ByteCount{8U * 1024U * 1024U}

Text byte limit.