Representation of a "running" XML document which is displayed on the fly. More...

#include <tsxmlRunningDocument.h>

Inheritance diagram for ts::xml::RunningDocument:

[legend]

Collaboration diagram for ts::xml::RunningDocument:

[legend]

Public Member Functions
	RunningDocument (Report &report=(ts::NullReport::Instance()))
	Constructor.

virtual	~RunningDocument () override
	Destructor.

size_t	childrenCount () const
	Get the number of children.

virtual void	clear ()
	Clear the content of the node.

virtual Node *	clone () const override
	Clone the content of the node in a dynamically allocated object.

void	close ()
	Close the running document.

UString	debug () const
	Build a debug string for the node.

size_t	depth () const
	Get the depth of an XML element.

Document *	document ()
	Get the document into which the node is located.

const Document *	document () const
	Get the document into which the node is located.

Node *	firstChild ()
	Get the first child of a node.

const Node *	firstChild () const
	Get the first child of a node.

Element *	firstChildElement ()
	Get the first child Element of a node.

const Element *	firstChildElement () const
	Get the first child Element of a node.

void	flush ()
	Flush the running document.

bool	hasChildren () const
	Check if the node has children.

Element *	initialize (const UString &rootName, const UString &declaration=UString())
	Initialize the document.

Node *	lastChild ()
	Get the last child.

const Node *	lastChild () const
	Get the last child.

size_t	lineNumber () const
	Get the line number in input document.

bool	load (const UString &fileName, bool search=true)
	Load and parse an XML file.

bool	load (std::istream &strm)
	Load and parse an XML file.

void	move (Node *newSibling, bool before)
	Move the node before or after another node, potentially to a new parent.

void	moveAfter (Node *newSibling)
	Move the node after another node, potentially to a new parent.

void	moveBefore (Node *newSibling)
	Move the node before another node, potentially to a new parent.

Node *	nextSibling ()
	Get the next sibling node.

const Node *	nextSibling () const
	Get the next sibling node.

Element *	nextSiblingElement ()
	Find the next sibling element.

const Element *	nextSiblingElement () const
	Find the next sibling element.

virtual UString	oneLiner () const
	Format the value as a one-liner XML text.

Element *	open (const UString &rootName, const UString &declaration=UString(), const fs::path &fileName=fs::path(), std::ostream &strm=std::cout)
	Initialize the running document.

Node *	parent ()
	Get the parent's node.

const Node *	parent () const
	Get the parent's node.

bool	parse (const UString &text)
	Parse an XML document.

bool	parse (const UStringList &lines)
	Parse an XML document.

bool	preserveSpace () const
	Check if the node or one of its ancestors has attribute xml:space="preserve".

Node *	previousSibling ()
	Get the previous sibling node.

const Node *	previousSibling () const
	Get the previous sibling node.

Element *	previousSiblingElement ()
	Find the previous sibling element.

const Element *	previousSiblingElement () const
	Find the previous sibling element.

virtual void	print (TextFormatter &output, bool keepNodeOpen=false) const override
	Format the node for an output XML document.

virtual void	printClose (TextFormatter &output, size_t levels=std::numeric_limits< size_t >::max()) const override
	Print the closing tags for the node.

void	removeComments (bool recurse)
	Remove all comments in the XML node.

void	reparent (Node *newParent, bool last=true)
	Attach the node to a new parent.

Report &	report () const
	Get a reference to the report object for the XML node.

bool	ringAlone () const
	Check if the node is alone in its own ring.

void	ringInsertAfter (RingNode *o)
	Insert this object in a ring after the specified node.

void	ringInsertBefore (RingNode *o)
	Insert this object in a ring before the specified node.

template<typename T >
T *	ringNext ()
	Get the next node in the ring.

template<typename T >
const T *	ringNext () const
	Get the next node in the ring.

template<typename T >
T *	ringPrevious ()
	Get the previous node in the ring.

template<typename T >
const T *	ringPrevious () const
	Get the previous node in the ring.

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.

void	ringSwap (RingNode *o)
	Swap this object and another one in their rings.

Element *	rootElement ()
	Get the root element of the document.

const Element *	rootElement () const
	Get the root element of the document.

bool	save (const fs::path &fileName, size_t indent=2)
	Save an XML file.

void	setTweaks (const Tweaks &tw)
	Set the global XML parsing and formatting tweaks for the document.

void	setValue (const UString &value)
	Set the value of the node.

virtual bool	stickyOutput () const
	Check if the text shall be stuck to other elements in XML output.

virtual UString	toString () const override
	Convert to a string object.

virtual const Tweaks &	tweaks () const override
	Get a constant reference to the global XML parsing and formatting tweaks for the document.

virtual UString	typeName () const override
	Return a node type name, mainly for debug purpose.

const UString &	value () const
	Get the value of the node.

Static Public Member Functions
static UString	DisplayFileName (const UString &name, bool stdInputIfEmpty=false)
	Get a suitable display name for an XML file name or inline content.

static bool	IsInlineXML (const UString &name)
	Check if a "file name" is in fact inline XML content instead of a file name.

Protected Member Functions
Node *	identifyNextNode (TextParser &parser)
	Identify the next token in the document.

virtual bool	parseChildren (TextParser &parser)
	Parse children nodes and add them to the node.

virtual bool	parseNode (TextParser &parser, const Node *parent) override
	Parse the node.

void	setPreserveSpace (bool on)
	Called by the subclass when its spaces shall be preserved.

Detailed Description

Representation of a "running" XML document which is displayed on the fly.

The idea is to display or save an XML document which is built element by element without waiting for the end of the document. Moreover, considering that the document can be arbitrary long, can take an arbitrary long time to be built and is not used for anything else than display or save, elements are destroyed after being displayed or saved to avoid wasting memory.

Constructor & Destructor Documentation

◆ RunningDocument()

ts::xml::RunningDocument::RunningDocument ( Report & report = (ts::NullReport::Instance()) )

explicit

Constructor.

Parameters

[in,out] report Where to report errors.

Member Function Documentation

◆ open()

Element * ts::xml::RunningDocument::open	(	const UString &	rootName,
		const UString &	declaration = `UString()`,
		const fs::path &	fileName = `fs::path()`,
		std::ostream &	strm = `std::cout`
	)

Initialize the running document.

The initial declaration and root are created. The output XML file is initialized but nothing is printed yet.

Parameters

[in]	rootName	Name of the root element to create.
[in]	declaration	Optional XML declaration. When omitted or empty, the standard declaration is used, specifying UTF-8 as format.
[in]	fileName	Output file name to create. When empty or "-", strm is used for output.
[in,out]	strm	The default output text stream when fileName is empty or "-". The referenced stream object must remain valid as long as this object.

Returns: New root element of the document or null on error.

◆ flush()

void ts::xml::RunningDocument::flush ( )

Flush the running document.

All elements under the document root are displayed or saved and then deleted. The XML document header is issued with the first element. The XML structure is left open for more elements, in the next call to flush().

◆ close()

void ts::xml::RunningDocument::close ( )

Close the running document.

If the XML structure is still open, it is closed. The output file, if any, is closed.

◆ parse() [1/2]

bool ts::xml::Document::parse ( const UStringList & lines )

inherited

Parse an XML document.

Parameters

[in] lines List of text lines forming the XML document.

Returns: True on success, false on error.

◆ parse() [2/2]

bool ts::xml::Document::parse ( const UString & text )

inherited

Parse an XML document.

Parameters

[in] text The XML document.

Returns: True on success, false on error.

◆ load() [1/2]

bool ts::xml::Document::load	(	const UString &	fileName,
		bool	search = `true`
	)

inherited

Load and parse an XML file.

Parameters

[in]	fileName	Name of the XML file to load. If fileName is empty or "-", read the standard input. If fileName starts with "<?xml", this is considered as "inline XML content". The document is loaded from this string instead of reading a file.
[in]	search	If true, search the XML file in the TSDuck configuration directories if fileName is not found and does not contain any directory part.

Returns: True on success, false on error.

See also: SearchConfigurationFile()

◆ load() [2/2]

bool ts::xml::Document::load ( std::istream & strm )

inherited

Load and parse an XML file.

Parameters

[in,out] strm A standard text stream in input mode.

Returns: True on success, false on error.

◆ save()

bool ts::xml::Document::save	(	const fs::path &	fileName,
		size_t	indent = `2`
	)

inherited

Save an XML file.

Parameters

[in]	fileName	Name of the XML file to save. If fileName is empty or "-", writes to the standard output.
[in]	indent	Indentation width of each level.

Returns: True on success, false on error.

◆ IsInlineXML()

static bool ts::xml::Document::IsInlineXML ( const UString & name )

staticinherited

Check if a "file name" is in fact inline XML content instead of a file name.

Parameters

[in] name A file name string.

Returns: True if name contains inline XML content, false otherwise.

◆ DisplayFileName()

static UString ts::xml::Document::DisplayFileName	(	const UString &	name,
		bool	stdInputIfEmpty = `false`
	)

staticinherited

Get a suitable display name for an XML file name or inline content.

Parameters

[in]	name	A file name string.
[in]	stdInputIfEmpty	If true and if fileName is empty, reads the standard input.

Returns: A suitable string to display.

◆ rootElement() [1/2]

const Element * ts::xml::Document::rootElement ( ) const

inlineinherited

Get the root element of the document.

Returns: The root element of the document or a null pointer if there is none.

◆ rootElement() [2/2]

Element * ts::xml::Document::rootElement ( )

inlineinherited

Get the root element of the document.

Returns: The root element of the document or or a null pointer if there is none.

◆ initialize()

Element * ts::xml::Document::initialize	(	const UString &	rootName,
		const UString &	declaration = `UString()`
	)

inherited

Initialize the document.

The initial declaration and root are created.

Parameters

[in]	rootName	Name of the root element to create.
[in]	declaration	Optional XML declaration. When omitted, the standard declaration is used, specifying UTF-8 as format.

Returns: New root element of the document or null on error.

◆ tweaks()

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

overridevirtualinherited

Get a constant reference to the global XML parsing and formatting tweaks for the document.

Returns: A constant reference to the global XML tweaks.

Reimplemented from ts::xml::Node.

◆ setTweaks()

void ts::xml::Document::setTweaks ( const Tweaks & tw )

inlineinherited

Set the global XML parsing and formatting tweaks for the document.

Parameters

[in] tw The new global XML tweaks.

◆ toString()

virtual UString ts::xml::Document::toString ( ) const

overridevirtualinherited

Convert to a string object.

Returns: This object, converted as a string.

Implements ts::StringifyInterface.

◆ clone()

virtual Node * ts::xml::Document::clone ( ) const

overridevirtualinherited

Clone the content of the node in a dynamically allocated object.

This virtual method must be implemented by subclasses to allocate a object of the right class.

Returns: The address of a new XML node of the same class as this object, same content, same structure.

Implements ts::xml::Node.

◆ typeName()

virtual UString ts::xml::Document::typeName ( ) const

overridevirtualinherited

Return a node type name, mainly for debug purpose.

Returns: Node type name.

Implements ts::xml::Node.

◆ print()

virtual void ts::xml::Document::print	(	TextFormatter &	output,
		bool	keepNodeOpen = `false`
	)		const

overridevirtualinherited

Format the node for an output XML document.

Parameters

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

Implements ts::xml::Node.

◆ printClose()

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

overridevirtualinherited

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]	output	The output object to format the XML document.
[in]	levels	Number of levels to close. By default, close the complete document. If zero, no output is produced.

Reimplemented from ts::xml::Node.

◆ parseNode()

virtual bool ts::xml::Document::parseNode	(	TextParser &	parser,
		const Node *	parent
	)

overrideprotectedvirtualinherited

Parse the node.

Parameters

[in,out]	parser	The 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]	parent	Candidate parent node, for information only, do not modify. Can be null.

Returns: True on success, false on error.

Implements ts::xml::Node.

◆ lineNumber()

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

inlineinherited

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 ( )

virtualinherited

Clear the content of the node.

The node becomes empty but remains attached to its parent.

Reimplemented in ts::xml::Element.

◆ reparent()

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

inherited

Attach the node to a new parent.

The node is first detached from its previous parent.

Parameters

[in,out]	newParent	New 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]	last	If true, the child is added at the end of the list of children. If false, it is added at the beginning.

◆ moveBefore()

void ts::xml::Node::moveBefore ( Node * newSibling )

inlineinherited

Move the node before another node, potentially to a new parent.

Parameters

[in,out] newSibling A new sibling. The node will be moved before this one.

◆ moveAfter()

void ts::xml::Node::moveAfter ( Node * newSibling )

inlineinherited

Move the node after another node, potentially to a new parent.

Parameters

[in,out] newSibling A new sibling. The node will be moved after this one.

◆ move()

void ts::xml::Node::move	(	Node *	newSibling,
		bool	before
	)

inherited

Move the node before or after another node, potentially to a new parent.

Parameters

[in,out]	newSibling	A new sibling. The node will be moved before or after this one.
[in]	before	If true, move the node before newSibling, after it otherwise.

◆ parent() [1/2]

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

inlineinherited

Get the parent's node.

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

◆ parent() [2/2]

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

inlineinherited

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

inlineinherited

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 ( )

inherited

Get the document into which the node is located.

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

◆ depth()

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

inherited

Get the depth of an XML element.

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

◆ preserveSpace()

bool ts::xml::Node::preserveSpace ( ) const

inherited

Check if the node or one of its ancestors has attribute xml:space="preserve".

Returns: True if spaces shall be preserved.

◆ hasChildren()

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

inlineinherited

Check if the node has children.

Returns: True if the node has children.

◆ childrenCount()

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

inlineinherited

Get the number of children.

Returns: The number of children.

◆ firstChild() [1/2]

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

inlineinherited

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 ( )

inlineinherited

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

inlineinherited

Get the last child.

Returns: The last child or zero if there is none.

◆ lastChild() [2/2]

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

inlineinherited

Get the last child.

Returns: The last child or nullptr if there is none.

◆ nextSibling() [1/2]

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

inlineinherited

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 ( )

inherited

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

inlineinherited

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 ( )

inherited

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

inlineinherited

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 ( )

inherited

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

inlineinherited

Find the next sibling element.

Returns: Element address or zero if not found.

◆ nextSiblingElement() [2/2]

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

inherited

Find the next sibling element.

Returns: Element address or zero if not found.

◆ previousSiblingElement() [1/2]

const Element * ts::xml::Node::previousSiblingElement ( ) const

inlineinherited

Find the previous sibling element.

Returns: Element address or zero if not found.

◆ previousSiblingElement() [2/2]

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

inherited

Find the previous sibling element.

Returns: Element address or zero if not found.

◆ value()

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

inlineinherited

Get the value of the node.

The semantic of the value depends on the node subclass:

Comment: Content of the comment, without "".
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 )

inlineinherited

Set the value of the node.

Parameters

[in] value New value to set.

See also: value()

◆ removeComments()

void ts::xml::Node::removeComments ( bool recurse )

inherited

Remove all comments in the XML node.

Parameters

[in] recurse If true, apply recursively to all children nodes.

◆ oneLiner()

virtual UString ts::xml::Node::oneLiner ( ) const

virtualinherited

Format the value as a one-liner XML text.

Returns: The formatted one-line XML text.

◆ stickyOutput()

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

virtualinherited

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

inherited

Build a debug string for the node.

Returns: A debug string for the node.

◆ report()

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

inlineinherited

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 )

protectedinherited

Identify the next token in the document.

Parameters

[in,out] parser The 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.)

◆ parseChildren()

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

protectedvirtualinherited

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] parser The document parser.

Returns: True on success, false on error.

◆ setPreserveSpace()

void ts::xml::Node::setPreserveSpace ( bool on )

inlineprotectedinherited

Called by the subclass when its spaces shall be preserved.

Typically called when xml:space="preserve" is encountered.

Parameters

[in] on True is spaces shall be preserved.

◆ 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] o A 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] o A 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] o The node to swap with.

◆ ringNext() [1/2]

template<typename T >

T * ts::RingNode::ringNext ( )

inlineinherited

Get the next node in the ring.

Template Parameters

T	A 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

T	A 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

T	A 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

T	A 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:

tsxmlRunningDocument.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ RunningDocument()

Member Function Documentation

◆ open()

◆ flush()

◆ close()

◆ parse() [1/2]

◆ parse() [2/2]

◆ load() [1/2]

◆ load() [2/2]

◆ save()

◆ IsInlineXML()

◆ DisplayFileName()

◆ rootElement() [1/2]

◆ rootElement() [2/2]

◆ initialize()

◆ tweaks()

◆ setTweaks()

◆ toString()

◆ clone()

◆ typeName()

◆ print()

◆ printClose()

◆ parseNode()

◆ lineNumber()

◆ clear()

◆ reparent()

◆ moveBefore()

◆ moveAfter()

◆ move()

◆ parent() [1/2]

◆ parent() [2/2]

◆ document() [1/2]

◆ document() [2/2]

◆ depth()

◆ preserveSpace()

◆ hasChildren()

◆ childrenCount()

◆ firstChild() [1/2]

◆ firstChild() [2/2]

◆ lastChild() [1/2]

◆ lastChild() [2/2]

◆ nextSibling() [1/2]

◆ nextSibling() [2/2]

◆ previousSibling() [1/2]

◆ previousSibling() [2/2]

◆ firstChildElement() [1/2]

◆ firstChildElement() [2/2]

◆ nextSiblingElement() [1/2]

◆ nextSiblingElement() [2/2]

◆ previousSiblingElement() [1/2]

◆ previousSiblingElement() [2/2]

◆ value()

◆ setValue()

◆ removeComments()

◆ oneLiner()

◆ stickyOutput()

◆ debug()

◆ report()

◆ identifyNextNode()

◆ parseChildren()

◆ setPreserveSpace()

◆ ringAlone()

◆ ringInsertAfter()

◆ ringInsertBefore()

◆ ringSwap()

◆ ringNext() [1/2]

◆ ringNext() [2/2]

◆ ringPrevious() [1/2]

◆ ringPrevious() [2/2]

◆ ringSize()