Donner
C++20 SVG rendering library
Loading...
Searching...
No Matches
donner::xml::XMLNode Class Reference

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

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

Public Types

enum class  Type {
  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.
 
XMLNodeoperator= (const XMLNode &other)
 Create another reference to the same XMLNode.
 
XMLNodeoperator= (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< RcStringvalue () 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< RcStringgetAttribute (const XMLQualifiedNameRef &name) const
 Get the value of an attribute, if it exists.
 
std::optional< base::parser::FileOffsetgetAttributeLocation (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< RcStringgetNamespaceUri (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< XMLNodeparentElement () const
 Get this element's parent, if it exists.
 
std::optional< XMLNodefirstChild () const
 Get the first child of this element, if it exists.
 
std::optional< XMLNodelastChild () const
 Get the last child of this element, if it exists.
 
std::optional< XMLNodepreviousSibling () const
 Get the previous sibling of this element, if it exists.
 
std::optional< XMLNodenextSibling () 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< base::parser::FileOffsetsourceStartOffset () const
 Get the source offset of where this node starts in the XML document source (if this node was instantiated by XMLParser).
 
void setSourceStartOffset (base::parser::FileOffset offset)
 Set the source offset of where this node starts in the XML document source.
 
std::optional< base::parser::FileOffsetsourceEndOffset () const
 Get the source offset of where this node ends in the XML document source (if this node was instantiated by XMLParser).
 
void setSourceEndOffset (base::parser::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< XMLNodeTryCast (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.
 
Registryregistry () 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

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
handleEntityHandle 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
childNode 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
documentContaining document.
valueNode 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
documentContaining document.
valueNode 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
documentContaining document.
valueNode 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
documentContaining document.
valueNode 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
documentContaining document.
tagNameNode 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
registryRegistry to create the node on.
typeType of node to create.
tagNameTag 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
documentContaining document.
targetProcessing instruction target, such as "php".
valueProcessing 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
documentContaining 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
nameName of the attribute to get.
Returns
The value of the attribute, or std::nullopt if the attribute does not exist.

◆ getAttributeLocation()

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

Get the location of an attribute in the input string.

Parameters
xmlInputInput string to get the attribute location in.
nameName 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
prefixPrefix of the attribute to get the namespace URI for.
Returns
The URI of the prefix, or std::nullopt if the prefix does not exist.

◆ hasAttribute()

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

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

Parameters
nameName 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
newNodeNew node to insert.
referenceNodeA 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
nameName of the attribute to remove.

◆ removeChild()

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

Remove child from this node.

Parameters
childChild 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
newChildNew child to insert.
oldChildOld 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
nameName of the attribute to set.
valueNew value to set.

◆ setSourceEndOffset()

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

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

Parameters
offsetOffset in the source document, in characters from the start.

◆ setSourceStartOffset()

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

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

Parameters
offsetOffset 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
entityEntity 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
entityEntity 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: