HTML

A growing implementation of HTML 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_entity (const std::string_view name) noexcept -> std::string_view
SOURCEMETA_CORE_HTML_EXPORT auto	sourcemeta::core::html_escape (std::string &text) -> void
template<typename Output>
auto	sourcemeta::core::html_escape_append (Output &output, const std::string_view input) -> void

Detailed Description

A growing implementation of HTML 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
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	reserve_additional (const std::size_t bytes) -> void
SOURCEMETA_FORCEINLINE auto	append_unchecked (const std::string_view data) noexcept -> void
SOURCEMETA_FORCEINLINE auto	size () const noexcept -> std::size_t
	Get the number of bytes accumulated so far.
SOURCEMETA_FORCEINLINE auto	back () const noexcept -> char
	Get the last character of the buffer, which must not be empty.
SOURCEMETA_FORCEINLINE auto	remove_suffix (const std::size_t count) noexcept -> void
SOURCEMETA_FORCEINLINE auto	view () const noexcept -> std::string_view
SOURCEMETA_FORCEINLINE auto	clear () noexcept -> void
	Discard the accumulated contents, keeping the capacity for reuse.
SOURCEMETA_FORCEINLINE auto	str () -> const std::string &
	Get the accumulated contents of the buffer.
SOURCEMETA_FORCEINLINE auto	take () -> std::string
auto	write (std::ostream &stream) -> void
	Write the accumulated contents to an output stream.

Member Function Documentation

append_unchecked()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLBuffer::append_unchecked ( const std::string_view data ) -> void

inlinenoexcept

Append a sequence of characters whose capacity was already reserved through reserve_additional

remove_suffix()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLBuffer::remove_suffix ( const std::size_t count ) -> void

inlinenoexcept

Remove a number of bytes from the end of the buffer, which must hold at least that many bytes

reserve()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLBuffer::reserve ( const std::size_t bytes ) -> void

inline

Reserve capacity for at least a number of bytes in total up front, keeping the accumulated contents

reserve_additional()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLBuffer::reserve_additional ( const std::size_t bytes ) -> void

inline

Reserve capacity for at least a number of bytes on top of the accumulated contents, so that appending up to that many bytes through append_unchecked needs no further capacity checks

take()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLBuffer::take ( ) -> std::string

inlinenodiscard

Move the accumulated contents out of the buffer, leaving it empty and ready to accumulate new contents

view()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLBuffer::view ( ) const -> std::string_view

inlinenodiscardnoexcept

Get a view of the accumulated contents, which stays valid until the buffer is modified

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	attribute (std::string_view name) -> HTMLWriter &
SOURCEMETA_FORCEINLINE auto	ensure_line_feed () -> HTMLWriter &
SOURCEMETA_FORCEINLINE auto	take () -> std::string
SOURCEMETA_FORCEINLINE auto	clear () -> void
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() [1/2]

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

inline

Add an attribute without a value, such as a boolean attribute, to the currently open tag. Must be called immediately after an element method and before any content. For example:

#include <sourcemeta/core/html.h>
#include <cassert>
 
sourcemeta::core::HTMLWriter document;
document.input().attribute("type", "checkbox").attribute("checked");
assert(document.str() == "<input type=\"checkbox\" checked />");

attribute() [2/2]

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.

clear()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLWriter::clear ( ) -> void

inline

Discard the output and every open element. For example:

#include <sourcemeta/core/html.h>
#include <cassert>
 
sourcemeta::core::HTMLWriter document;
document.div().p("Hello");
document.clear();
assert(document.str().empty());

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.

ensure_line_feed()

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

inline

Write a line feed unless nothing was written yet or the output already ends with one, so that the markup that follows starts on a line of its own. For example:

#include <sourcemeta/core/html.h>
#include <cassert>
 
sourcemeta::core::HTMLWriter document;
document.p("Hello");
document.ensure_line_feed();
document.ensure_line_feed();
document.p("World");
assert(document.str() == "<p>Hello</p>\n<p>World</p>");

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.

take()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::HTMLWriter::take ( ) -> std::string

inlinenodiscard

Move the rendered HTML string out of the writer, leaving the writer empty and ready to render another document. For example:

#include <sourcemeta/core/html.h>
#include <cassert>
 
sourcemeta::core::HTMLWriter document;
document.p("Hello");
const auto result{document.take()};
assert(result == "<p>Hello</p>");
assert(document.str().empty());

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

SOURCEMETA_CORE_HTML_EXPORT auto sourcemeta::core::html_entity ( const std::string_view name ) -> std::string_view

noexcept

Look up the characters of a named character reference per the HTML Living Standard, which lists every one of them at https://html.spec.whatwg.org/entities.json. The name excludes the leading ampersand and includes the trailing semicolon, which the standard lets a few legacy names omit. The result is the UTF-8 encoding of the characters, or an empty view if the name is not a named character reference. For example:

#include <sourcemeta/core/html.h>
#include <cassert>
 
assert(sourcemeta::core::html_entity("copy;") == "\xC2\xA9");
assert(sourcemeta::core::html_entity("copy") == "\xC2\xA9");
assert(sourcemeta::core::html_entity("ne").empty());

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

template<typename Output>

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

inline

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

#include <sourcemeta/core/html.h>
#include <cassert>
 
std::string output{"<p>"};
sourcemeta::core::html_escape_append(output, "1 < 2");
assert(output == "<p>1 &lt; 2");