'XMLOutputStream' is a helper to write an XML file in a streaming way. More...
#include <XMLOutputStream.hh>
Public Member Functions | |
| XMLOutputStream (Operations &ops_) | |
| void | begin (std::string_view tag) |
| void | attribute (std::string_view name, std::string_view value) |
| void | data (std::string_view value) |
| void | end (std::string_view tag) |
| void | with_tag (std::string_view tag, std::invocable auto next) |
Detailed Description
class XMLOutputStream< Operations >
'XMLOutputStream' is a helper to write an XML file in a streaming way.
That is: all information must be provided in the exact same order as it appears in the output. So attributes for a tag must be provided before the data for that tag. It's not possible to go back to an earlier tag and add/change/remove attributes or data, nor is it possible to add/remove subtags to already streamed tags.
In other words: this helper class immediately write the provided data to the output stream, and it cannot make changes to already outputted data. So basically the only thing this class does is take care of the syntax details and formatting of the XML file. The main advantage of this class is that it's very cheap: it does not need to keep (much) state in memory (e.g. it does not build the whole XML tree in memory and then dump it all at the end).
One limitation of this helper is that it does not support mixed-content tags. A tag either contains data or it contains subtags, but not both (neither data nor subtags is fine).
After instantiation of the 'XMLOutputStream', you must call the begin(), attribute(), data(), end() methods. These directly correspond to elements in the XML file, so the meaning should be clear. There are also constraints on the order in which these methods are allowed to be called:
- begin() and end() calls should be properly paired. That is for each begin() there must be a corresponding end() and the 'tag' parameter for both must match. One pair must be either fully nested inside another pair or it must be fully outside that other pair.
- attribute() must be called directly after begin() or after another attribute() call, but not after data() or end()
- data() can only be called once per tag, it must be called after begin() or after attribute(), but not after data() or end().
- A call to data() must be followed by a call to end(). Not another data() call nor attribute() nor begin().
'XMLOutputStream' is templatized on an 'Operations' type. This must be a class that implements the following 3 methods: struct MyOperations { void write(const char* buf, size_t len); void write1(char c); void check(bool condition) const; };
The write() and write1() methods write data (e.g. to a file). Either a whole buffer or a single character. In some implementations it's more efficient to write a single char than to write a buffer of length 1, but in your implementation feel free to implement write1() as: write1(char c) { write(&c, 1); }
The check() method should be implemented as: assert(condition); Though in the unittests we instead make this throw an exception so that we can test the error cases.
Definition at line 75 of file XMLOutputStream.hh.
Constructor & Destructor Documentation
◆ XMLOutputStream()
|
inlineexplicit |
Definition at line 78 of file XMLOutputStream.hh.
Member Function Documentation
◆ attribute()
| void XMLOutputStream< Writer >::attribute | ( | std::string_view | name, |
| std::string_view | value | ||
| ) |
Definition at line 127 of file XMLOutputStream.hh.
Referenced by openmsx::SettingsConfig::saveSetting(), TEST_CASE(), TEST_CASE(), and TEST_CASE().
◆ begin()
| void XMLOutputStream< Writer >::begin | ( | std::string_view | tag | ) |
Definition at line 110 of file XMLOutputStream.hh.
Referenced by TEST_CASE(), TEST_CASE(), and TEST_CASE().
◆ data()
| void XMLOutputStream< Writer >::data | ( | std::string_view | value | ) |
Definition at line 139 of file XMLOutputStream.hh.
Referenced by openmsx::SettingsConfig::saveSetting(), TEST_CASE(), TEST_CASE(), and TEST_CASE().
◆ end()
| void XMLOutputStream< Writer >::end | ( | std::string_view | tag | ) |
Definition at line 152 of file XMLOutputStream.hh.
Referenced by TEST_CASE(), TEST_CASE(), and TEST_CASE().
◆ with_tag()
| void XMLOutputStream< Writer >::with_tag | ( | std::string_view | tag, |
| std::invocable auto | next | ||
| ) |
Definition at line 176 of file XMLOutputStream.hh.
References begin(), and end().
Referenced by openmsx::SettingsConfig::saveSetting().
The documentation for this class was generated from the following file:
