Represents an XML element belonging to an XMLDocument. More...

#include "donner/base/xml/XMLNode.h"

Public Types
enum class	Type : uint8_t { Document , Element , Data , CData , Comment , DocType , ProcessingInstruction , XMLDeclaration }
	Node type, use type() to query the value. To create nodes of different types, use the relevant static method constructor, such as CreateElementNode and CreateCommentNode. More...

Public Member Functions
	XMLNode (const XMLNode &other)
	Create another reference to the same XMLNode.
	XMLNode (XMLNode &&other) noexcept
	Move constructor.
	~XMLNode () noexcept=default
	Destructor.
XMLNode &	operator= (const XMLNode &other)
	Create another reference to the same XMLNode.
XMLNode &	operator= (XMLNode &&other) noexcept
	Move assignment operator.
Type	type () const
	Get the type of this node.
XMLQualifiedNameRef	tagName () const
	Get the XML tag name string for this node.
EntityHandle	entityHandle () const
	Get the underlying EntityHandle, for advanced use-cases that require direct access to the ECS.
std::optional< RcString >	value () const
	Get the value of this node, which depends on the node type.
void	setValue (const RcStringOrRef &value)
	Set the value of this node.
bool	hasAttribute (const XMLQualifiedNameRef &name) const
	Returns true if the element has an attribute with the given name.
std::optional< RcString >	getAttribute (const XMLQualifiedNameRef &name) const
	Get the value of an attribute, if it exists.
std::optional< FileOffsetRange >	getNodeLocation () const
	Get the location of this node in the input string.
std::optional< FileOffsetRange >	getAttributeLocation (std::string_view xmlInput, const XMLQualifiedNameRef &name) const
	Get the location of an attribute in the input string.
SmallVector< XMLQualifiedNameRef, 10 >	attributes () const
	Get the list of attributes for this element.
std::optional< RcString >	getNamespaceUri (const RcString &prefix) const
	Get the namespace URI of an attribute prefix, if it exists.
void	setAttribute (const XMLQualifiedNameRef &name, std::string_view value)
	Set the value of a generic XML attribute, which may be either a presentation attribute or custom user-provided attribute.
void	removeAttribute (const XMLQualifiedNameRef &name)
	Remove an attribute, which may be either a presentation attribute or custom user-provided attribute.
std::optional< XMLNode >	parentElement () const
	Get this element's parent, if it exists.
std::optional< XMLNode >	firstChild () const
	Get the first child of this element, if it exists.
std::optional< XMLNode >	lastChild () const
	Get the last child of this element, if it exists.
std::optional< XMLNode >	previousSibling () const
	Get the previous sibling of this element, if it exists.
std::optional< XMLNode >	nextSibling () const
	Get the next sibling of this element, if it exists.
void	insertBefore (const XMLNode &newNode, std::optional< XMLNode > referenceNode)
	Insert `newNode` as a child, before `referenceNode`.
void	appendChild (const XMLNode &child)
	Append `child` as a child of the current node.
void	replaceChild (const XMLNode &newChild, const XMLNode &oldChild)
	Replace `oldChild` with `newChild` in the tree, removing `oldChild` and inserting `newChild` in its place.
void	removeChild (const XMLNode &child)
	Remove `child` from this node.
void	remove ()
	Remove this node from its parent, if it has one.
std::optional< FileOffset >	sourceStartOffset () const
	Get the source offset of where this node starts in the XML document source (if this node was instantiated by XMLParser).
void	setSourceStartOffset (FileOffset offset)
	Set the source offset of where this node starts in the XML document source.
std::optional< FileOffset >	sourceEndOffset () const
	Get the source offset of where this node ends in the XML document source (if this node was instantiated by XMLParser).
void	setSourceEndOffset (FileOffset offset)
	Set the source offset of where this node ends in the XML document source.
bool	operator== (const XMLNode &other) const
	Returns true if the two XMLNode handles reference the same underlying document.
bool	operator!= (const XMLNode &other) const
	Returns true if the two XMLNode handles reference the same underlying document.

Static Public Member Functions
static XMLNode	CreateElementNode (XMLDocument &document, const XMLQualifiedNameRef &tagName)
	Create a new XML node for an element bound to `document`.
static XMLNode	CreateDataNode (XMLDocument &document, const RcStringOrRef &value)
	Create a new XML node for an element bound to `document`, with a given `value`.
static XMLNode	CreateCDataNode (XMLDocument &document, const RcStringOrRef &value)
	Create a new XML node for a CDATA section bound to `document`, with a given `value`.
static XMLNode	CreateCommentNode (XMLDocument &document, const RcStringOrRef &value)
	Create a new XML node for a comment bound to `document`, with a given `value`.
static XMLNode	CreateDocTypeNode (XMLDocument &document, const RcStringOrRef &value)
	Create a new XML node for a document type declaration bound to `document`, with a given `value`.
static XMLNode	CreateProcessingInstructionNode (XMLDocument &document, const RcStringOrRef &target, const RcStringOrRef &value)
	Create a new XML node for a processing instruction bound to `document`, with a given `target` and `value`.
static XMLNode	CreateXMLDeclarationNode (XMLDocument &document)
	Create a new XML node for an XML declaration bound to `document`.
static std::optional< XMLNode >	TryCast (EntityHandle entity)
	Try to cast to an XMLNode from a raw Entity.

Protected Member Functions
	XMLNode (EntityHandle handle)
	Internal constructor to create an XMLNode from an EntityHandle.
Registry &	registry () const
	Get the underlying ECS Registry, which holds all data for the document, for advanced use.
EntityHandle	toHandle (Entity entity) const
	Convert an Entity to an EntityHandle, for advanced use.

Static Protected Member Functions
static XMLNode	CreateDocumentNode (XMLDocument &document)
	Create an XMLNode for the root node of a document.
static Entity	CreateEntity (Registry &registry, Type type, const XMLQualifiedNameRef &tagName="")
	Create an Entity for a node of `type`.

Protected Attributes
EntityHandle	handle_
	The underlying ECS Entity for this element, which holds all data.

Friends
class	XMLDocument
std::ostream &	operator<< (std::ostream &os, const Type &type)
	Ostream output operator.

Detailed Description

Represents an XML element belonging to an XMLDocument.

Each XMLNode may only belong to a single document, and each document can have only one root. XMLDocument is responsible for managing the lifetime of all elements in the document, by storing a shared pointer to the internal Registry data-store.

Data is stored using the Entity Component System (Entity Component System (ECS)) pattern, which is a data-oriented design optimized for fast data access and cache locality, particularly during rendering.

XMLDocument and XMLNode provide a facade over the ECS, and surface a familiar Document Object Model (DOM) API to traverse and manipulate the document tree, which is internally stored within Components in the ECS. This makes XMLNode a thin wrapper around an Entity, making the object lightweight and usable on the stack.

See also: XMLDocument; Entity Component System (ECS)

Member Enumeration Documentation

◆ Type

enum class donner::xml::XMLNode::Type : uint8_t

strong

Node type, use type() to query the value. To create nodes of different types, use the relevant static method constructor, such as CreateElementNode and CreateCommentNode.

Enumerator
Document	Document node, which is the root of the document tree. This is created automatically by XMLDocument. tagName() and value() are empty.
Element	Element node, representing a regular XML tag, such as <svg>. tagName() is the tag name, and value() contains the text of the first data node. See also https://www.w3.org/TR/xml/#dt-element
Data	Data node, containing verbatim text. value() contains the data, and tagName() is empty.
CData	CDATA node, such as <![CDATA[ ... ]]> . value() contains the data, and tagName() is empty. See also https://www.w3.org/TR/xml/#sec-cdata-sect
Comment	Comment node, such as <!-- ... -->. value() contains the comment text, and tagName() is empty. See also https://www.w3.org/TR/xml/#sec-comments
DocType	Document Type Declaration (DTD) node, such as <!DOCTYPE ...>. tagName() is empty, and value() contains the contents of the node. See also https://www.w3.org/TR/xml/#dtd
ProcessingInstruction	Processing Instruction (PI) node, such as <?php ... ?>. tagName() is the PI target, e.g. "php". value() contains the remaining content. See also https://www.w3.org/TR/xml/#sec-pi
XMLDeclaration	XML Declaration node, such as <?xml ... ?>, which is a special case of ProcessingInstruction when the type is "xml". Contents are parsed as attributes. tagName() is "xml" and value() is empty. See also https://www.w3.org/TR/xml/#sec-prolog-dtd

Constructor & Destructor Documentation

◆ XMLNode()

donner::xml::XMLNode::XMLNode ( EntityHandle handle )

explicitprotected

Internal constructor to create an XMLNode from an EntityHandle.

Parameters

handle EntityHandle to wrap.

Member Function Documentation

◆ appendChild()

void donner::xml::XMLNode::appendChild ( const XMLNode & child )

Append child as a child of the current node.

If child is already in the tree, it is first removed from its parent. However, if inserting the child will create a cycle, the behavior is undefined.

Parameters

child Node to append.

◆ CreateCDataNode()

XMLNode donner::xml::XMLNode::CreateCDataNode	(	XMLDocument &	document,
		const RcStringOrRef &	value )

static

Create a new XML node for a CDATA section bound to document, with a given value.

Note that this does not insert the node into the document tree, to do so call appendChild.

This is represented as <![CDATA[ ... ]]> in XML.

Parameters

document	Containing document.
value	Node value, such as "Hello, world!".

◆ CreateCommentNode()

XMLNode donner::xml::XMLNode::CreateCommentNode	(	XMLDocument &	document,
		const RcStringOrRef &	value )

static

Create a new XML node for a comment bound to document, with a given value.

Note that this does not insert the node into the document tree, to do so call appendChild.

This is represented as  in XML.

Parameters

document	Containing document.
value	Node value, such as "Hello, world!".

◆ CreateDataNode()

XMLNode donner::xml::XMLNode::CreateDataNode	(	XMLDocument &	document,
		const RcStringOrRef &	value )

static

Create a new XML node for an element bound to document, with a given value.

Note that this does not insert the node into the document tree, to do so call appendChild.

Parameters

document	Containing document.
value	Node value, such as "Hello, world!".

◆ CreateDocTypeNode()

XMLNode donner::xml::XMLNode::CreateDocTypeNode	(	XMLDocument &	document,
		const RcStringOrRef &	value )

static

Create a new XML node for a document type declaration bound to document, with a given value.

Note that this does not insert the node into the document tree, to do so call appendChild.

This is represented as <!DOCTYPE ...> in XML.

Parameters

document	Containing document.
value	Node value, such as svg.

◆ CreateDocumentNode()

XMLNode donner::xml::XMLNode::CreateDocumentNode ( XMLDocument & document )

staticprotected

Create an XMLNode for the root node of a document.

This is called internally by XMLDocument.

◆ CreateElementNode()

XMLNode donner::xml::XMLNode::CreateElementNode	(	XMLDocument &	document,
		const XMLQualifiedNameRef &	tagName )

static

Create a new XML node for an element bound to document.

Note that this does not insert the node into the document tree, to do so call appendChild.

Parameters

document	Containing document.
tagName	Node tag name, such as "xml" or "svg".

◆ CreateEntity()

Entity donner::xml::XMLNode::CreateEntity	(	Registry &	registry,
		Type	type,
		const XMLQualifiedNameRef &	tagName = "" )

staticprotected

Create an Entity for a node of type.

Parameters

registry	Registry to create the node on.
type	Type of node to create.
tagName	Tag name of the node to create. This is only used for some types, for other nodes pass an empty string.

◆ CreateProcessingInstructionNode()

XMLNode donner::xml::XMLNode::CreateProcessingInstructionNode	(	XMLDocument &	document,
		const RcStringOrRef &	target,
		const RcStringOrRef &	value )

static

Create a new XML node for a processing instruction bound to document, with a given target and value.

Note that this does not insert the node into the document tree, to do so call appendChild.

This is represented as <?php ... ?> in XML.

Parameters

document	Containing document.
target	Processing instruction target, such as "php".
value	Processing instruction value, such as "echo 'Hello, world!';".

◆ CreateXMLDeclarationNode()

XMLNode donner::xml::XMLNode::CreateXMLDeclarationNode ( XMLDocument & document )

static

Create a new XML node for an XML declaration bound to document.

Note that this does not insert the node into the document tree, to do so call appendChild.

This is represented as <?xml ... ?> in XML.

Contents of the declaration are accessible through the attribute getters/setters.

Parameters

document Containing document.

◆ firstChild()

std::optional< XMLNode > donner::xml::XMLNode::firstChild ( ) const

Get the first child of this element, if it exists.

Returns: The first child element, or std::nullopt if the element has no children.

◆ getAttribute()

std::optional< RcString > donner::xml::XMLNode::getAttribute ( const XMLQualifiedNameRef & name ) const

Get the value of an attribute, if it exists.

Parameters

name	Name of the attribute to get.

Returns: The value of the attribute, or std::nullopt if the attribute does not exist.

◆ getAttributeLocation()

std::optional< FileOffsetRange > donner::xml::XMLNode::getAttributeLocation	(	std::string_view	xmlInput,
		const XMLQualifiedNameRef &	name ) const

Get the location of an attribute in the input string.

For example, for the following XML:

<root>
  <child attr="Hello, world!">
</root>

The FileOffsetRange for the attr attribute should contain the substring attr="Hello, world!"

Parameters

xmlInput	Input string to get the attribute location in.
name	Name of the attribute to get the location for.

Returns: Offset of the attribute in the input string, or std::nullopt if the attribute does not exist.

◆ getNamespaceUri()

std::optional< RcString > donner::xml::XMLNode::getNamespaceUri ( const RcString & prefix ) const

Get the namespace URI of an attribute prefix, if it exists.

Parameters

prefix Prefix of the attribute to get the namespace URI for.

Returns: The URI of the prefix, or std::nullopt if the prefix does not exist.

◆ getNodeLocation()

std::optional< FileOffsetRange > donner::xml::XMLNode::getNodeLocation ( ) const

Get the location of this node in the input string.

For example, for the following XML:

<root>
  <child>Hello, world!</child>
</root>

The FileOffsetRange for the child element should contain the substring <child>Hello, world!</child>

Returns: Start and end offsets of the node in the input string, or std::nullptr if source locations are not available.

◆ hasAttribute()

bool donner::xml::XMLNode::hasAttribute ( const XMLQualifiedNameRef & name ) const

Returns true if the element has an attribute with the given name.

Parameters

name	Name of the attribute to check.

Returns: true if the attribute exists, false otherwise.

◆ insertBefore()

void donner::xml::XMLNode::insertBefore	(	const XMLNode &	newNode,
		std::optional< XMLNode >	referenceNode )

Insert newNode as a child, before referenceNode.

If referenceNode is std::nullopt, append the child.

If newNode is already in the tree, it is first removed from its parent. However, if inserting the child will create a cycle, the behavior is undefined.

Parameters

newNode	New node to insert.
referenceNode	A child of this node to insert `newNode` before, or `std::nullopt`. Must be a child of the current node.

◆ lastChild()

std::optional< XMLNode > donner::xml::XMLNode::lastChild ( ) const

Get the last child of this element, if it exists.

Returns: The last child element, or std::nullopt if the element has no children.

◆ nextSibling()

std::optional< XMLNode > donner::xml::XMLNode::nextSibling ( ) const

Get the next sibling of this element, if it exists.

Returns: The next sibling element, or std::nullopt if the element has no next sibling.

◆ parentElement()

std::optional< XMLNode > donner::xml::XMLNode::parentElement ( ) const

Get this element's parent, if it exists.

If the parent is not set, this document is either the root element or has not been inserted into the document tree.

Returns: The parent element, or std::nullopt if the parent is not set.

◆ previousSibling()

std::optional< XMLNode > donner::xml::XMLNode::previousSibling ( ) const

Get the previous sibling of this element, if it exists.

Returns: The previous sibling element, or std::nullopt if the element has no previous sibling.

◆ remove()

void donner::xml::XMLNode::remove ( )

Remove this node from its parent, if it has one.

Has no effect if this has no parent.

◆ removeAttribute()

void donner::xml::XMLNode::removeAttribute ( const XMLQualifiedNameRef & name )

Remove an attribute, which may be either a presentation attribute or custom user-provided attribute.

If this is a presentation attribute, the presentation attributes value will be removed (internally by setting the value to 'inherit').

Parameters

name	Name of the attribute to remove.

◆ removeChild()

void donner::xml::XMLNode::removeChild ( const XMLNode & child )

Remove child from this node.

Parameters

child Child to remove, must be a child of the current node.

◆ replaceChild()

void donner::xml::XMLNode::replaceChild	(	const XMLNode &	newChild,
		const XMLNode &	oldChild )

Replace oldChild with newChild in the tree, removing oldChild and inserting newChild in its place.

If newChild is already in the tree, it is first removed from its parent. However, if inserting the child will create a cycle, the behavior is undefined.

Parameters

newChild	New child to insert.
oldChild	Old child to remove, must be a child of the current node.

◆ setAttribute()

void donner::xml::XMLNode::setAttribute	(	const XMLQualifiedNameRef &	name,
		std::string_view	value )

Set the value of a generic XML attribute, which may be either a presentation attribute or custom user-provided attribute.

This API supports a superset of trySetPresentationAttribute, however its parse errors are ignored. If the attribute is not a presentation attribute, or there are parse errors the attribute will be stored as a custom attribute instead.

Parameters

name	Name of the attribute to set.
value	New value to set.

◆ setSourceEndOffset()

void donner::xml::XMLNode::setSourceEndOffset ( FileOffset offset )

Set the source offset of where this node ends in the XML document source.

Parameters

offset Offset in the source document, in characters from the start.

◆ setSourceStartOffset()

void donner::xml::XMLNode::setSourceStartOffset ( FileOffset offset )

Set the source offset of where this node starts in the XML document source.

Parameters

offset Offset in the source document, in characters from the start.

◆ toHandle()

EntityHandle donner::xml::XMLNode::toHandle ( Entity entity ) const

inlineprotected

Convert an Entity to an EntityHandle, for advanced use.

Parameters

entity Entity to convert.

◆ TryCast()

std::optional< XMLNode > donner::xml::XMLNode::TryCast ( EntityHandle entity )

static

Try to cast to an XMLNode from a raw Entity.

This is a checked cast, and will return std::nullopt if the entity is not an XML node.

Parameters

entity Entity to cast.

◆ value()

std::optional< RcString > donner::xml::XMLNode::value ( ) const

Get the value of this node, which depends on the node type.

For nodes without a value, this will return std::nullopt.

The documentation for this class was generated from the following files:

donner/base/xml/XMLNode.h
donner/base/xml/XMLNode.cc

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ XMLNode()

Member Function Documentation

◆ appendChild()

◆ CreateCDataNode()

◆ CreateCommentNode()

◆ CreateDataNode()

◆ CreateDocTypeNode()

◆ CreateDocumentNode()

◆ CreateElementNode()

◆ CreateEntity()

◆ CreateProcessingInstructionNode()

◆ CreateXMLDeclarationNode()

◆ firstChild()

◆ getAttribute()

◆ getAttributeLocation()

◆ getNamespaceUri()

◆ getNodeLocation()

◆ hasAttribute()

◆ insertBefore()

◆ lastChild()

◆ nextSibling()

◆ parentElement()

◆ previousSibling()

◆ remove()

◆ removeAttribute()

◆ removeChild()

◆ replaceChild()

◆ setAttribute()

◆ setSourceEndOffset()

◆ setSourceStartOffset()

◆ toHandle()

◆ TryCast()

◆ value()