HTML

A growing implementation of HTML generation utilities per the HTML Living Standard. More...

Classes
class	sourcemeta::core::HTMLBuffer
class	sourcemeta::core::HTMLWriter

Functions
SOURCEMETA_CORE_HTML_EXPORT auto	sourcemeta::core::html_escape (std::string &text) -> void
SOURCEMETA_CORE_HTML_EXPORT auto	sourcemeta::core::html_escape_append (std::string &output, std::string_view input) -> void
SOURCEMETA_CORE_HTML_EXPORT auto	sourcemeta::core::html_escape_append (HTMLBuffer &output, std::string_view input) -> void

Detailed Description

A growing implementation of HTML generation utilities per the HTML Living Standard.

This functionality is included as follows:

#include <sourcemeta/core/html.h>

---

Class Documentation

sourcemeta::core::HTMLBuffer

class sourcemeta::core::HTMLBuffer

A fast append-only string buffer

Public Member Functions
	HTMLBuffer (const HTMLBuffer &)=delete
	HTMLBuffer (HTMLBuffer &&)=delete
SOURCEMETA_FORCEINLINE auto	reserve (const std::size_t bytes) -> void
	Reserve a number of bytes of capacity up front.
SOURCEMETA_FORCEINLINE auto	append (const char character) -> void
	Append a single character to the buffer.
SOURCEMETA_FORCEINLINE auto	append (const std::string_view data) -> void
	Append a sequence of characters to the buffer.
SOURCEMETA_FORCEINLINE auto	str () -> const std::string &
	Get the accumulated contents of the buffer.
auto	write (std::ostream &stream) -> void
	Write the accumulated contents to an output stream.

sourcemeta::core::HTMLWriter

class sourcemeta::core::HTMLWriter

A streaming HTML writer that renders directly to a string buffer. No intermediate DOM tree is built. Elements are serialized as methods are called.

#include <sourcemeta/core/html.h>
#include <cassert>
 
sourcemeta::core::HTMLWriter document;
document.div().attribute("class", "greeting");
document.h1("Hello");
document.p("World");
document.close();

Public Member Functions
SOURCEMETA_FORCEINLINE auto	reserve (std::size_t bytes) -> void
	Pre-allocate the output buffer.
SOURCEMETA_FORCEINLINE auto	close () -> HTMLWriter &
SOURCEMETA_FORCEINLINE auto	attribute (std::string_view name, std::string_view value) -> HTMLWriter &
SOURCEMETA_FORCEINLINE auto	text (std::string_view content) -> HTMLWriter &
SOURCEMETA_FORCEINLINE auto	raw (std::string_view content) -> HTMLWriter &
SOURCEMETA_FORCEINLINE auto	str () -> const std::string &
	Get the rendered HTML string.
auto	write (std::ostream &stream) -> void
	Write the rendered HTML to an output stream.

Member Function Documentation

attribute()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLWriter::attribute ( std::string_view name, std::string_view value ) -> HTMLWriter &

inline

Add an attribute to the currently open tag. Must be called immediately after an element method and before any content.

close()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLWriter::close ( ) -> HTMLWriter &

inline

Close the most recently opened element. Closing when no element is open has no effect.

raw()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLWriter::raw ( std::string_view content ) -> HTMLWriter &

inline

Write content without HTML-escaping. This is how the content of a raw-text element is emitted, since escaped text would corrupt it.

text()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLWriter::text ( std::string_view content ) -> HTMLWriter &

inline

Write HTML-escaped text content. The single-argument element shorthand routes through this and therefore also escapes. The HTML serialization emits the content of a raw-text element literally, so escaping its content would corrupt it. This writer does not special-case content by element, so the content of a raw-text element must be written unescaped rather than as escaped text, and it must not contain that element's closing-tag sequence.

Function Documentation

html_escape()

SOURCEMETA_CORE_HTML_EXPORT auto sourcemeta::core::html_escape

(

std::string &

text

)

-> void

HTML character escaping implementation per HTML Living Standard. See: https://html.spec.whatwg.org/multipage/parsing.html#escapingString

This function escapes the five HTML special characters in-place, the ampersand, less-than sign, greater-than sign, double quote, and apostrophe, along with the no-break space, each becoming its corresponding HTML entity.

For example:

#include <sourcemeta/core/html.h>
#include <cassert>
 
std::string text{"1 < 2 & 3 > 0 'x' \"y\""};
sourcemeta::core::html_escape(text);
assert(text == "1 &lt; 2 &amp; 3 &gt; 0 &#39;x&#39; &quot;y&quot;");

html_escape_append() [1/2]

SOURCEMETA_CORE_HTML_EXPORT auto sourcemeta::core::html_escape_append	(	HTMLBuffer &	output,
		std::string_view	input ) -> void

Append the HTML-escaped form of input directly to a buffer. The input must not reference the buffer, since appending to it may relocate its storage.

html_escape_append() [2/2]

SOURCEMETA_CORE_HTML_EXPORT auto sourcemeta::core::html_escape_append	(	std::string &	output,
		std::string_view	input ) -> void

Append the HTML-escaped form of input directly to output, without allocating a temporary string. The input must not reference the output, since appending to the output may relocate its storage.