TSDuck Version 3.16-1064 (TSDuck - The MPEG Transport Stream Toolkit)
ts::xml::Node Class Referenceabstract

Base class for all XML objects in a document. More...

Inheritance diagram for ts::xml::Node:
Collaboration diagram for ts::xml::Node:

Public Member Functions

virtual ~Node ()
 Virtual destructor.
 
size_t childrenCount () const
 Get the number of children. More...
 
virtual void clear ()
 Clear the content of the node. More...
 
UString debug () const
 Build a debug string for the node. More...
 
size_t depth () const
 Get the depth of an XML element. More...
 
const Documentdocument () const
 Get the document into which the node is located. More...
 
Documentdocument ()
 Get the document into which the node is located. More...
 
const NodefirstChild () const
 Get the first child of a node. More...
 
NodefirstChild ()
 Get the first child of a node. More...
 
const ElementfirstChildElement () const
 Get the first child Element of a node. More...
 
ElementfirstChildElement ()
 Get the first child Element of a node. More...
 
bool hasChildren () const
 Check if the node has children. More...
 
const NodelastChild () const
 Get the last child. More...
 
NodelastChild ()
 Get the last child. More...
 
size_t lineNumber () const
 Get the line number in input document. More...
 
const NodenextSibling () const
 Get the next sibling node. More...
 
NodenextSibling ()
 Get the next sibling node. More...
 
const ElementnextSiblingElement () const
 Find the next sibling element. More...
 
ElementnextSiblingElement ()
 Find the next sibling element. More...
 
const Nodeparent () const
 Get the parent's node. More...
 
Nodeparent ()
 Get the parent's node. More...
 
const NodepreviousSibling () const
 Get the previous sibling node. More...
 
NodepreviousSibling ()
 Get the previous sibling node. More...
 
virtual void print (TextFormatter &output, bool keepNodeOpen=false) const =0
 Format the node for an output XML document. More...
 
virtual void printClose (TextFormatter &output, size_t levels=std::numeric_limits< size_t >::max()) const
 Print the closing tags for the node. More...
 
virtual void reparent (Node *newParent, bool last=true)
 Attach the node to a new parent. More...
 
Reportreport () const
 Get a reference to the report object for the XML node. More...
 
bool ringAlone () const
 Check if the node is alone in its own ring. More...
 
void ringInsertAfter (RingNode *o)
 Insert this object in a ring after the specified node. More...
 
void ringInsertBefore (RingNode *o)
 Insert this object in a ring before the specified node. More...
 
template<typename T >
T * ringNext ()
 Get the next node in the ring. More...
 
template<typename T >
const T * ringNext () const
 Get the next node in the ring. More...
 
template<typename T >
T * ringPrevious ()
 Get the previous node in the ring. More...
 
template<typename T >
const T * ringPrevious () const
 Get the previous node in the ring. More...
 
void ringRemove ()
 Remove the node from the ring it belongs to and creates its own ring.
 
size_t ringSize () const
 Count the number of element in the ring. More...
 
void ringSwap (RingNode *o)
 Swap this object and another one in their rings. More...
 
void setReportPrefix (const UString &prefix)
 Set the prefix to display on report lines. More...
 
void setValue (const UString &value)
 Set the value of the node. More...
 
virtual bool stickyOutput () const
 Check if the text shall be stuck to other elements in XML output. More...
 
virtual const Tweakstweaks () const
 Get a constant reference to the current XML parsing and formatting tweaks for this node. More...
 
virtual UString typeName () const =0
 Return a node type name, mainly for debug purpose. More...
 
const UStringvalue () const
 Get the value of the node. More...
 

Protected Member Functions

 Node (Report &report, size_t line=0)
 Constructor. More...
 
 Node (Node *parent, const UString &value=UString(), bool last=true)
 Constructor. More...
 
NodeidentifyNextNode (TextParser &parser)
 Identify the next token in the document. More...
 
virtual bool parseChildren (TextParser &parser)
 Parse children nodes and add them to the node. More...
 
virtual bool parseNode (TextParser &parser, const Node *parent)=0
 Parse the node. More...
 

Protected Attributes

ReportWithPrefix _report
 Where to report errors.
 
UString _value
 Value of the node, depend on the node type.
 

Detailed Description

Base class for all XML objects in a document.

Implementation note on inheritance: Node is a subclass of RingNode. The "ring" is used to link all siblings. This inheritance should be private since it is an internal characteristics of Node. However, if we make this inheritance private, the dynamic_cast operations in RingNode fail. This is a very annoying C++ feature.

Constructor & Destructor Documentation

◆ Node() [1/2]

ts::xml::Node::Node ( Report report,
size_t  line = 0 
)
explicitprotected

Constructor.

Parameters
[in,out]reportWhere to report errors.
[in]lineLine number in input document.

◆ Node() [2/2]

ts::xml::Node::Node ( Node parent,
const UString value = UString(),
bool  last = true 
)
explicitprotected

Constructor.

Parameters
[in,out]parentThe parent document into which the declaration is added.
[in]valueValue of the node.
[in]lastIf true, the child is added at the end of the list of children. If false, it is added at the beginning.

Member Function Documentation

◆ lineNumber()

size_t ts::xml::Node::lineNumber ( ) const
inline

Get the line number in input document.

Returns
The line number in input document, zero if the node was built programmatically.

◆ clear()

virtual void ts::xml::Node::clear ( )
virtual

Clear the content of the node.

The node becomes empty but remains attached to its parent.

Reimplemented in ts::xml::Element.

◆ reparent()

virtual void ts::xml::Node::reparent ( Node newParent,
bool  last = true 
)
virtual

Attach the node to a new parent.

The node is first detached from its previous parent.

Parameters
[in,out]newParentNew parent. If zero, the node becomes orphan. In that case, the node will no longer be freed by its parent and must be explicitly deleted.
[in]lastIf true, the child is added at the end of the list of children. If false, it is added at the beginning.

◆ parent() [1/2]

const Node* ts::xml::Node::parent ( ) const
inline

Get the parent's node.

Returns
The parent's node or zero if this is a top-level document.

◆ parent() [2/2]

Node* ts::xml::Node::parent ( )
inline

Get the parent's node.

Returns
The parent's node or zero if this is a top-level document.

◆ document() [1/2]

const Document* ts::xml::Node::document ( ) const
inline

Get the document into which the node is located.

Returns
The node's document or zero if there is no document.

◆ document() [2/2]

Document* ts::xml::Node::document ( )

Get the document into which the node is located.

Returns
The node's document or zero if there is no document.

◆ tweaks()

virtual const Tweaks& ts::xml::Node::tweaks ( ) const
virtual

Get a constant reference to the current XML parsing and formatting tweaks for this node.

Returns
A constant reference to the XML tweaks to apply. When the node is part of a document, get the global tweaks of the document. Otherwise, get the default tweaks.

Reimplemented in ts::xml::Document.

◆ depth()

size_t ts::xml::Node::depth ( ) const

Get the depth of an XML element.

Returns
The depth of the element, ie. the number of ancestors.

◆ hasChildren()

bool ts::xml::Node::hasChildren ( ) const
inline

Check if the node has children.

Returns
True if the node has children.

◆ childrenCount()

size_t ts::xml::Node::childrenCount ( ) const
inline

Get the number of children.

Returns
The number of children.

◆ firstChild() [1/2]

const Node* ts::xml::Node::firstChild ( ) const
inline

Get the first child of a node.

Returns
The first child of the node or zero if there is no children.

◆ firstChild() [2/2]

Node* ts::xml::Node::firstChild ( )
inline

Get the first child of a node.

Returns
The first child of the node or zero if there is no children.

◆ lastChild() [1/2]

const Node* ts::xml::Node::lastChild ( ) const
inline

Get the last child.

Returns
The last child or zero if there is none.

◆ lastChild() [2/2]

Node* ts::xml::Node::lastChild ( )
inline

Get the last child.

Returns
The last child or nullptr if there is none.

◆ nextSibling() [1/2]

const Node* ts::xml::Node::nextSibling ( ) const
inline

Get the next sibling node.

Returns
The next sibling node or zero if the node is the last child.

◆ nextSibling() [2/2]

Node* ts::xml::Node::nextSibling ( )

Get the next sibling node.

Returns
The next sibling node or zero if the node is the last child.

◆ previousSibling() [1/2]

const Node* ts::xml::Node::previousSibling ( ) const
inline

Get the previous sibling node.

Returns
The previous sibling node or zero if the node is the first child.

◆ previousSibling() [2/2]

Node* ts::xml::Node::previousSibling ( )

Get the previous sibling node.

Returns
The previous sibling node or zero if the node is the first child.

◆ firstChildElement() [1/2]

const Element* ts::xml::Node::firstChildElement ( ) const
inline

Get the first child Element of a node.

Returns
The first child Element of the node or zero if there is no child Element.

◆ firstChildElement() [2/2]

Element* ts::xml::Node::firstChildElement ( )

Get the first child Element of a node.

Returns
The first child Element of the node or zero if there is no child Element.

◆ nextSiblingElement() [1/2]

const Element* ts::xml::Node::nextSiblingElement ( ) const
inline

Find the next sibling element.

Returns
Element address or zero if not found.

◆ nextSiblingElement() [2/2]

Element* ts::xml::Node::nextSiblingElement ( )

Find the next sibling element.

Returns
Element address or zero if not found.

◆ value()

const UString& ts::xml::Node::value ( ) const
inline

Get the value of the node.

The semantic of the value depends on the node subclass:

  • Comment: Content of the comment, without "<!--" and "-->".
  • Declaration: Content of the declaration, without "<?" and "?>".
  • Document: Empty.
  • Element: Name of the element.
  • Text: Text content of the element, including spaces and new-lines.
  • Unknown: Content of the tag, probably an uninterpreted DTD.
Returns
A constant reference to the node value, as a string.

◆ setValue()

void ts::xml::Node::setValue ( const UString value)
inline

Set the value of the node.

Parameters
[in]valueNew value to set.
See also
value()

◆ setReportPrefix()

void ts::xml::Node::setReportPrefix ( const UString prefix)
inline

Set the prefix to display on report lines.

Parameters
[in]prefixThe prefix to prepend to all messages.

◆ typeName()

virtual UString ts::xml::Node::typeName ( ) const
pure virtual

Return a node type name, mainly for debug purpose.

Returns
Node type name.

Implemented in ts::xml::Element, ts::xml::Document, ts::xml::Text, ts::xml::Declaration, ts::xml::Comment, and ts::xml::Unknown.

◆ print()

virtual void ts::xml::Node::print ( TextFormatter output,
bool  keepNodeOpen = false 
) const
pure virtual

Format the node for an output XML document.

Parameters
[in,out]outputThe output object to format the XML document.
[in]keepNodeOpenIf true, keep the node open so that children may be printed later.

Implemented in ts::xml::Element, ts::xml::Document, ts::xml::Text, ts::xml::Declaration, ts::xml::Comment, and ts::xml::Unknown.

◆ printClose()

virtual void ts::xml::Node::printClose ( TextFormatter output,
size_t  levels = std::numeric_limits<size_t>::max() 
) const
inlinevirtual

Print the closing tags for the node.

Typically used after print() when keepNodeOpen was true. The default implementation is to do nothing. Subclasses may replace this.

Parameters
[in,out]outputThe output object to format the XML document.
[in]levelsNumber of levels to close. By default, close the complete document. If zero, no output is produced.

Reimplemented in ts::xml::Element, and ts::xml::Document.

◆ stickyOutput()

virtual bool ts::xml::Node::stickyOutput ( ) const
inlinevirtual

Check if the text shall be stuck to other elements in XML output.

Returns
True if the text shall be stuck to other elements. False by default.

Reimplemented in ts::xml::Text.

◆ debug()

UString ts::xml::Node::debug ( ) const

Build a debug string for the node.

Returns
A debug string for the node.

◆ report()

Report& ts::xml::Node::report ( ) const
inline

Get a reference to the report object for the XML node.

Returns
A reference to the report object for the XML node.

◆ identifyNextNode()

Node* ts::xml::Node::identifyNextNode ( TextParser parser)
protected

Identify the next token in the document.

Parameters
[in,out]parserThe document parser.
Returns
A new node or zero either at end of document or before a "</" sequence. The returned node, when not zero, is not yet linked to its parent and siblings. When the returned node is not zero, the parser is located after the tag which identified the node ("<?", "<!--", etc.)

◆ parseNode()

virtual bool ts::xml::Node::parseNode ( TextParser parser,
const Node parent 
)
protectedpure virtual

Parse the node.

Parameters
[in,out]parserThe document parser. On input, the current position of the parser after the tag which identified the node ("<?", "<!--", etc.) On output, it must be after the last character of the node.
[in]parentCandidate parent node, for information only, do not modify. Can be null.
Returns
True on success, false on error.

Implemented in ts::xml::Element, ts::xml::Document, ts::xml::Text, ts::xml::Declaration, ts::xml::Comment, and ts::xml::Unknown.

◆ parseChildren()

virtual bool ts::xml::Node::parseChildren ( TextParser parser)
protectedvirtual

Parse children nodes and add them to the node.

Stop either at end of document or before a "</" sequence or on error.

Parameters
[in,out]parserThe document parser.
Returns
True on success, false on error.

◆ ringAlone()

bool ts::RingNode::ringAlone ( ) const
inlineinherited

Check if the node is alone in its own ring.

Returns
True if the node is alone in its own ring.

◆ ringInsertAfter()

void ts::RingNode::ringInsertAfter ( RingNode o)
inherited

Insert this object in a ring after the specified node.

Parameters
[in]oA node of a ring. This object is inserted after o in the ring.

◆ ringInsertBefore()

void ts::RingNode::ringInsertBefore ( RingNode o)
inherited

Insert this object in a ring before the specified node.

Parameters
[in]oA node of a ring. This object is inserted before o in the ring.

◆ ringSwap()

void ts::RingNode::ringSwap ( RingNode o)
inherited

Swap this object and another one in their rings.

If the two objects belong to the same ring, their positions are swapped. If they belong to distinct rings, they also move to each other's ring.

Parameters
[in]oThe node to swap with.

◆ ringNext() [1/2]

template<typename T >
T* ts::RingNode::ringNext ( )
inlineinherited

Get the next node in the ring.

Template Parameters
TA superclass of RingNode, the expected type of the next object in the ring.
Returns
Address of the next node in the ring or zero if the next node is not a subclass of T.

◆ ringNext() [2/2]

template<typename T >
const T* ts::RingNode::ringNext ( ) const
inlineinherited

Get the next node in the ring.

Template Parameters
TA superclass of RingNode, the expected type of the next object in the ring.
Returns
Address of the next node in the ring or zero if the next node is not a subclass of T.

◆ ringPrevious() [1/2]

template<typename T >
T* ts::RingNode::ringPrevious ( )
inlineinherited

Get the previous node in the ring.

Template Parameters
TA superclass of RingNode, the expected type of the previous object in the ring.
Returns
Address of the previous node in the ring or zero if the previous node is not a subclass of T.

◆ ringPrevious() [2/2]

template<typename T >
const T* ts::RingNode::ringPrevious ( ) const
inlineinherited

Get the previous node in the ring.

Template Parameters
TA superclass of RingNode, the expected type of the previous object in the ring.
Returns
Address of the previous node in the ring or zero if the previous node is not a subclass of T.

◆ ringSize()

size_t ts::RingNode::ringSize ( ) const
inherited

Count the number of element in the ring.

Warning: This method has a linear response time, avoid using it when possible.

Returns
The number of nodes in the ring.

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