Rich Text and HTML

The erbsland::cterm::text helpers let you render a focused subset of HTML as styled terminal output. They are designed to give you predictable, document-like formatting without the complexity of a full HTML engine.

The system is structured into three layers:

HtmlRenderer parses HTML fragments or full documents and renders them either into a String or directly to a CursorWriter.
Style defines the visual appearance of headings, paragraphs, lists, blockquotes, code blocks, and inline elements such as emphasis or links. StyleSelector and StyleRole let you target those rules precisely.
TextNode represents the intermediate document tree. You can inspect or construct this tree when you need more control than direct rendering provides.

If you only need plain terminal text, see Strings and Chars. For details on paragraph wrapping and layout behavior used by block rendering, refer to Paragraph Options.

Usage

Rendering HTML Fragments to Terminal Text

Use HtmlRenderer when you want to convert HTML into terminal-friendly output.

The renderer supports a practical subset of HTML, including:

paragraphs and headings
links
unordered and ordered lists
definition lists
blockquotes
code blocks
horizontal rules
common inline formatting (<strong>, <em>, etc.)

using namespace erbsland::cterm;
namespace rich = erbsland::cterm::text;

const auto html = std::string_view{
    "<h2>Status</h2>"
    "<p>Hello <strong>world</strong>.</p>"
    "<ul><li>One</li><li>Two</li></ul>"
    "<p><a href=\"/docs\">Documentation</a></p>"};

const auto summary = rich::HtmlRenderer{html}.renderString();
terminal.print(summary);

Use renderString() when you want a self-contained result that you can store, combine, or print later.

Use renderTo() when you are writing directly to a CursorWriter and want to preserve block spacing, margins, and cursor positioning across multiple render operations.

Customizing Heading, List, and Code Styles

With Style, you define how your rendered content looks through selector-based rules. Rules can target a semantic role, an optional heading or list level, a list kind, and named style tokens parsed from TextNode::style().

namespace rich = erbsland::cterm::text;

auto style = std::make_shared<rich::Style>();
style->setBaseTextStyle(CharStyle{Color{fg::BrightWhite, bg::Inherited}});
style->edit(rich::StyleSelector::strong()).setTextStyle(CharStyle{Color{fg::BrightYellow, bg::Inherited}});
style->edit(rich::StyleSelector::code()).setTextStyle(CharStyle{Color{fg::BrightCyan, bg::Black}});
style->edit(rich::StyleSelector::heading(1))
    .setTextStyle(CharStyle{Color{fg::BrightWhite, bg::Blue}})
    .setSuffix(U"  ")
    .setLineFill(U'=');
style->edit(rich::StyleSelector::listItem(rich::StyleListKind::Bullet, 0))
    .setLiteralMarker(U"• ", CharStyle{Color{fg::BrightMagenta, bg::Inherited}});

rich::HtmlRenderer{
    "<h1>Title</h1><ul><li>Entry</li></ul>",
    style}.renderTo(buffer);

Block-level layout is controlled via ParagraphIndents. The renderer automatically collapses adjacent vertical margins where it makes sense, so headings and paragraphs behave like cohesive document blocks rather than isolated printParagraph() calls.

Styling Inline Span Tokens

Generic inline spans can be styled explicitly with StyleSelector::span() and optional style tokens parsed from HTML class attributes.

namespace rich = erbsland::cterm::text;

auto style = std::make_shared<rich::Style>();
style->edit(rich::StyleSelector::span()).setTextStyle(Color{fg::White, bg::Inherited});
style->edit(rich::StyleSelector{rich::StyleRole::Span, {"tag"}})
    .setTextStyle(Color{fg::BrightBlack, bg::BrightYellow});
style->edit(rich::StyleSelector{rich::StyleRole::Span, {"warning"}})
    .setTextStyle(Color{fg::BrightYellow, bg::Inherited}, CharAttributes::Bold);

rich::HtmlRenderer{
    "<p><span class=\"tag\">beta</span> <span class=\"warning\">Read carefully.</span></p>",
    style}.renderTo(buffer);

This works well for terminal badges, inline tags, severity labels, and other compact document cues that should stay part of the text flow.

Inspecting and Building TextNode Trees

TextNode gives you access to the parsed document structure.

This is useful when you want to:

debug or inspect parsed HTML
transform content before rendering
build structured terminal output programmatically

namespace rich = erbsland::cterm::text;

auto document = rich::TextNode::createDocument();
auto paragraph = rich::TextNode::createParagraph();
auto link = rich::TextNode::createLink("/docs");

link->addChild(rich::TextNode::createText(U"Open docs"));
paragraph->addChild(link);
document->addChild(paragraph);

for (const auto &line : document->toDiagnosticTree(2)) {
    terminal.printLine(line);
}

When the HTML parser encounters unsupported block-level elements (for example tables or SVG), it inserts TextNode::Type::Unsupported nodes instead of silently dropping content. This makes missing support explicit and easier to handle in your application logic.

Interface

class HtmlRenderer

A renderer for HTML content to strings or cursor writer targets.

Public Functions

inline explicit HtmlRenderer(const std::string_view html, StyleConstPtr style = Style::defaultStyle()): Create a new HTML renderer with the given HTML content and style.

String renderString() const

Render a given HTML fragment into a string.

Paragraphs are rendered as lines, with one line break at the end of the paragraph.
Leading/trailing linebreaks, carriage returns, and tabs are trimmed at the beginning and end of the result.
Block and document margins from the text style are ignored.
List-item indentation follows the configured BulletListItem1 … NumberedListItem8 styles, but margins stay ignored.

Note

The idea behind this method is not to render structured documents but small text fragments. Therefore, the output is not suitable for large documents or complex formatting.

Returns:: A string with the formatted text.

void renderTo(const CursorWriterPtr &cursorWriterPtr) const

Render a given HTML fragment/document to a CursorWriter.

CSS-like block and document margins are applied when rendering to a cursor writer target.

Parameters:: cursorWriterPtr – The cursor writer to render the HTML to.

Public Static Functions

static TextNodePtr parse(std::string_view html)

Parse an HTML document into a text tree.

Parameters:: html – The HTML code to parse.
Returns:: A text node representing the parsed HTML.

static std::string escapeHtml(std::string_view text)

Escape text for safe use inside an HTML fragment.

Parameters:: text – The plain text to escape.
Returns:: The escaped HTML text.

using erbsland::cterm::text::StylePtr = std::shared_ptr<Style>: Shared pointer to a mutable text style.

using erbsland::cterm::text::StyleConstPtr = std::shared_ptr<const Style>: Shared pointer to an immutable text style.

class Style

A selector-driven style configuration for rich text rendering.

Public Types

enum class Predefined : uint8_t

Shared predefined style variants.

Values:

enumerator Plain: The plain built-in rich-text style.

enumerator Simple: A compact style inspired by the HTML viewer demo.

enumerator Styled: An extended decorative style inspired by the HTML viewer demo.

using Role = StyleRole : Alias for the standalone style role type.

using ListKind = StyleListKind : Alias for the standalone list-kind type.

using MatchContext = StyleMatchContext: Alias for the standalone match-context type.

Public Functions

Style(): Create the default rich-text style.

StylePtr clone() const

Create a mutable copy of this style.

Returns:: A shared pointer to a cloned style instance.

const CharStyle &baseTextStyle() const noexcept

Access the base text style used before selector-specific overlays.

Returns:: The configured base text style.

void setBaseTextStyle(const CharStyle &style) noexcept

Replace the base text style used before selector-specific overlays.

Parameters:: style – The new base text style.

const ParagraphIndents &baseBlockLayout() const noexcept

Access the base block layout used before selector-specific overrides.

Returns:: The configured base block layout.

void setBaseBlockLayout(const ParagraphIndents &layout) noexcept

Replace the base block layout used before selector-specific overrides.

Parameters:: layout – The new base block layout.

std::optional<std::reference_wrapper<const StyleRule>> definition(const StyleSelector &selector) const noexcept

Access one exact stored rule definition.

Parameters:: selector – The selector to query.
Returns:: The stored rule, if present.

StyleRule &edit(const StyleSelector &selector)

Create or access one exact stored rule definition.

New definitions are initialized from the currently resolved rule for the same selector.

Parameters:: selector – The selector to edit.
Returns:: A mutable reference to the stored rule.

void erase(const StyleSelector &selector) noexcept

Remove one exact stored rule definition.

Parameters:: selector – The selector to erase.

StyleRule resolve(const StyleSelector &selector, const StyleMatchContext &context) const

Resolve the best matching rule for one selector and match context.

Parameters:

selector – The requested selector. Explicit selector fields override the context.
context – The current node context.

Returns:

The resolved rule.

Public Static Functions

static const StyleConstPtr &defaultStyle(Predefined predefined = Predefined::Plain) noexcept

Access one shared predefined default style instance.

Parameters:: predefined – The predefined style variant to return.
Returns:: The lazily constructed shared style instance.

static const StyleConstPtr &defaultPlain() noexcept

Access the shared plain default style instance.

Returns:: The lazily constructed shared plain style instance.

static const StyleConstPtr &defaultSimple() noexcept

Access the shared simple default style instance.

Returns:: The lazily constructed shared simple style instance.

static const StyleConstPtr &defaultStyled() noexcept

Access the shared styled default style instance.

Returns:: The lazily constructed shared styled style instance.

enum class erbsland::cterm::text::StyleRole : uint8_t

Semantic roles that can be styled.

Values:

enumerator Document: The root document container.

enumerator Section: Generic block container such as section or div.

enumerator Paragraph: Regular paragraph blocks.

enumerator Heading: Heading blocks.

enumerator ListContainer: Bullet or numbered list containers.

enumerator ListItem: List item content boxes.

enumerator DefinitionList: Definition list containers.

enumerator DefinitionTerm: Definition terms.

enumerator DefinitionDescription: Definition descriptions.

enumerator Blockquote: Blockquote containers.

enumerator CodeBlock: Code blocks.

enumerator HorizontalRule: Horizontal separators.

enumerator Emphasis: Emphasized or italic inline content.

enumerator Strong: Strong or bold inline content.

enumerator Underline: Underlined inline content.

enumerator Span: Generic inline span containers.

enumerator Link: Links or active references.

enumerator Code: Inline code.

enum class erbsland::cterm::text::StyleListKind : uint8_t

The list kind for list-specific selectors.

Values:

enumerator Any: Match any list kind or non-list roles.

enumerator Bullet: Match bullet lists and bullet list items.

enumerator Numbered: Match numbered lists and numbered list items.

class StyleSelector

A selector used to define or request one style rule.

Public Functions

constexpr StyleSelector() noexcept = default: Create a paragraph selector.

inline explicit constexpr StyleSelector(const StyleRole styleRole) noexcept

Create a selector for the given role.

Parameters:: styleRole – The semantic role to match.

inline constexpr StyleSelector(const StyleRole styleRole, const std::optional<int> level, const StyleListKind listKind = StyleListKind::Any) noexcept

Create a selector with optional level and list-kind qualifiers.

Parameters:

styleRole – The semantic role to match.
level – The optional heading or list nesting level.
listKind – The optional list kind qualifier.

inline StyleSelector(const StyleRole styleRole, const std::initializer_list<std::string> requiredStyleTokens)

Create a selector with required style tokens.

Parameters:

styleRole – The semantic role to match.
requiredStyleTokens – Required style tokens parsed from TextNode::style().

inline StyleSelector(const StyleRole styleRole, const std::optional<int> level, const StyleListKind listKind, const std::initializer_list<std::string> requiredStyleTokens)

Create a selector with optional level, list kind, and required style tokens.

Parameters:

styleRole – The semantic role to match.
level – The optional heading or list nesting level.
listKind – The optional list kind qualifier.
requiredStyleTokens – Required style tokens parsed from TextNode::style().

constexpr bool operator==(const StyleSelector &other) const noexcept = default: Compare two selectors for exact identity.

inline constexpr StyleRole styleRole() const noexcept: Get the semantic role to match.

inline constexpr const std::optional<int> &level() const noexcept: Get the optional heading or list nesting level.

inline constexpr StyleListKind listKind() const noexcept: Get the optional list kind qualifier.

inline std::vector<std::string> &requiredStyleTokens() noexcept: Get the required style tokens parsed from TextNode::style().

inline const std::vector<std::string> &requiredStyleTokens() const noexcept: Get the required style tokens parsed from TextNode::style().

Public Static Functions

static inline constexpr StyleSelector role(const StyleRole role) noexcept

Create a selector for the given semantic role.

Parameters:: role – The role to select.
Returns:: The selector for that role.

static inline constexpr StyleSelector document() noexcept

Create a document selector.

Returns:: The document selector.

static inline constexpr StyleSelector section() noexcept

Create a section selector.

Returns:: The section selector.

static inline constexpr StyleSelector paragraph() noexcept

Create a paragraph selector.

Returns:: The selector for regular paragraphs.

static inline constexpr StyleSelector heading(const int level) noexcept

Create a heading selector for the given level.

Parameters:: level – The one-based heading level.
Returns:: The selector for that heading level.

static inline constexpr StyleSelector listContainer(const StyleListKind listKind, const int level) noexcept

Create a list-container selector.

Parameters:

listKind – The list kind.
level – The zero-based list nesting level.

Returns:

The selector for that list container.

static inline constexpr StyleSelector listItem(const StyleListKind listKind, const int level) noexcept

Create a list-item selector.

Parameters:

listKind – The list kind.
level – The zero-based list nesting level.

Returns:

The selector for that list item.

static inline constexpr StyleSelector definitionList() noexcept

Create a definition-list selector.

Returns:: The definition-list selector.

static inline constexpr StyleSelector definitionTerm() noexcept

Create a definition-term selector.

Returns:: The definition-term selector.

static inline constexpr StyleSelector definitionDescription() noexcept

Create a definition-description selector.

Returns:: The definition-description selector.

static inline constexpr StyleSelector blockquote() noexcept

Create a blockquote selector.

Returns:: The blockquote selector.

static inline constexpr StyleSelector codeBlock() noexcept

Create a code-block selector.

Returns:: The code-block selector.

static inline constexpr StyleSelector horizontalRule() noexcept

Create a horizontal-rule selector.

Returns:: The horizontal-rule selector.

static inline constexpr StyleSelector emphasis() noexcept

Create an emphasis selector.

Returns:: The emphasis selector.

static inline constexpr StyleSelector strong() noexcept

Create a strong-text selector.

Returns:: The strong-text selector.

static inline constexpr StyleSelector underline() noexcept

Create an underline selector.

Returns:: The underline selector.

static inline StyleSelector span(const std::initializer_list<std::string> requiredStyleTokens)

Create a span selector with required style tokens.

Parameters:: requiredStyleTokens – Required style tokens typically coming from the class attribute.
Returns:: The span selector for these required style tokens.

static inline constexpr StyleSelector link() noexcept

Create a link selector.

Returns:: The link selector.

static inline constexpr StyleSelector code() noexcept

Create an inline-code selector.

Returns:: The inline-code selector.

class StyleMarker

A visible marker used for bullet and numbered list items.

Public Types

enum class Kind : uint8_t

Marker rendering mode.

Values:

enumerator None: No visible marker.

enumerator Literal: Use literal as-is.

enumerator Ordered: Render the item number followed by suffix.

Public Functions

StyleMarker() = default: Create an empty marker.

inline Kind kind() const noexcept: Get the marker rendering mode.

inline const CharStyle &style() const noexcept: Get the overlay style applied to the rendered marker.

inline const String &literal() const noexcept: Get the literal marker text.

inline const String &suffix() const noexcept: Get the ordered-list suffix text.

StyleMarker &clear() noexcept

Clear the marker so no visible prefix is rendered.

Returns:: Reference to this marker.

StyleMarker &setStyle(const CharStyle &style) noexcept

Set the overlay style for the marker.

Parameters:: style – The new marker style.
Returns:: Reference to this marker.

StyleMarker &setStyle(Color color, CharAttributes attributes = {}) noexcept

Set the overlay style for the marker.

Parameters:

color – The marker color.
attributes – The marker attributes.

Returns:

Reference to this marker.

StyleMarker &setLiteral(String literal, const CharStyle &style = {})

Use a literal marker string.

Parameters:

literal – The literal marker text.
style – Optional marker overlay style.

Returns:

Reference to this marker.

StyleMarker &setLiteral(std::u32string_view literal, const CharStyle &style = {})

Use a literal marker string.

Parameters:

literal – The literal marker text.
style – Optional marker overlay style.

Returns:

Reference to this marker.

StyleMarker &setOrdered(String suffix = String{".\t"}, const CharStyle &style = {})

Use an ordered marker with the given suffix.

Parameters:

suffix – The text appended after the number.
style – Optional marker overlay style.

Returns:

Reference to this marker.

StyleMarker &setOrdered(std::u32string_view suffix, const CharStyle &style = {})

Use an ordered marker with the given suffix.

Parameters:

suffix – The text appended after the number.
style – Optional marker overlay style.

Returns:

Reference to this marker.

Rendered render(std::size_t number, const CharStyle &baseStyle, int targetColumn) const

Render this marker for one list item number.

Tabs advance to targetColumn, or become one space if that column is already passed.

Parameters:

number – The one-based item number for ordered lists.
baseStyle – The base style used for the marker text.
targetColumn – The wrapped content column.

Returns:

The rendered marker text plus visible width information.

struct Rendered

One rendered marker instance.

Public Members

String text: The normalized plain-text representation.

String terminalText: The terminal representation preserving tab characters.

int width = {0}: The visible width in terminal cells.

class StyleRule

One configurable rich-text style rule with convenient fluent setters.

Public Functions

StyleRule() = default: Create an empty style rule.

inline const CharStyle &textStyle() const noexcept: Get the text overlay applied to inline or block content.

StyleRule &setTextStyle(const CharStyle &style) noexcept

Replace the text overlay applied to inline or block content.

Parameters:: style – The new text style.
Returns:: Reference to this rule.

StyleRule &setTextStyle(Color color, CharAttributes attributes = {}) noexcept

Replace the text overlay applied to inline or block content.

Parameters:

color – The new text color.
attributes – The new text attributes.

Returns:

Reference to this rule.

inline const ParagraphIndents &indents() const noexcept: Get the full paragraph indentation settings.

StyleRule &setIndents(const ParagraphIndents &indents) noexcept

Replace the full paragraph indentation settings.

Parameters:: indents – The new indentation settings.
Returns:: Reference to this rule.

inline const Margins &margins() const noexcept: Get the margins around the block.

StyleRule &setMargins(Margins margins) noexcept

Replace the margins around the block.

Parameters:: margins – The new margins.
Returns:: Reference to this rule.

StyleRule &setMargins(int allSides) noexcept

Replace the margins around the block.

Parameters:: allSides – Uniform margin for all sides.
Returns:: Reference to this rule.

StyleRule &setMargins(int horizontal, int vertical) noexcept

Replace the margins around the block.

Parameters:

horizontal – Margin for left and right.
vertical – Margin for top and bottom.

Returns:

Reference to this rule.

StyleRule &setMargins(int top, int right, int bottom, int left) noexcept

Replace the margins around the block.

Parameters:

top – Top margin.
right – Right margin.
bottom – Bottom margin.
left – Left margin.

Returns:

Reference to this rule.

StyleRule &setLineIndent(int indent) noexcept

Set the shared line indent.

Parameters:: indent – The new line indent.
Returns:: Reference to this rule.

StyleRule &setFirstLineIndent(int indent) noexcept

Set the first-line indent.

Parameters:: indent – The new first-line indent, or ParagraphIndents::cUseLineIndent.
Returns:: Reference to this rule.

StyleRule &setWrappedLineIndent(int indent) noexcept

Set the wrapped-line indent.

Parameters:: indent – The new wrapped-line indent, or ParagraphIndents::cUseLineIndent.
Returns:: Reference to this rule.

inline const std::optional<String> &prefix() const noexcept: Get the optional prefix inserted before the rendered content.

StyleRule &setPrefix(String prefix)

Set the optional prefix inserted before the rendered content.

Parameters:: prefix – The prefix string.
Returns:: Reference to this rule.

StyleRule &setPrefix(std::u32string_view prefix, const CharStyle &style = {})

Set the optional prefix inserted before the rendered content.

Parameters:

prefix – The prefix text.
style – Optional style for the prefix text.

Returns:

Reference to this rule.

StyleRule &clearPrefix() noexcept

Remove any configured prefix.

Returns:: Reference to this rule.

inline const std::optional<String> &suffix() const noexcept: Get the optional suffix appended after the rendered content.

StyleRule &setSuffix(String suffix)

Set the optional suffix appended after the rendered content.

Parameters:: suffix – The suffix string.
Returns:: Reference to this rule.

StyleRule &setSuffix(std::u32string_view suffix, const CharStyle &style = {})

Set the optional suffix appended after the rendered content.

Parameters:

suffix – The suffix text.
style – Optional style for the suffix text.

Returns:

Reference to this rule.

StyleRule &clearSuffix() noexcept

Remove any configured suffix.

Returns:: Reference to this rule.

inline const std::optional<Char> &lineFill() const noexcept: Get the optional fill character for filled headings or custom separators.

StyleRule &setLineFill(const Char &lineFill) noexcept

Set the fill character for filled headings or custom separators.

Parameters:: lineFill – The fill character.
Returns:: Reference to this rule.

StyleRule &setLineFill(char32_t codePoint, const CharStyle &style = {}) noexcept

Set the fill character for filled headings or custom separators.

Parameters:

codePoint – The fill character code point.
style – Optional style for the fill character.

Returns:

Reference to this rule.

StyleRule &clearLineFill() noexcept

Remove any configured fill character.

Returns:: Reference to this rule.

inline StyleMarker &marker() noexcept: Get the marker configuration.

inline const StyleMarker &marker() const noexcept: Get the marker configuration.

StyleRule &setMarker(const StyleMarker &marker)

Replace the full marker configuration.

Parameters:: marker – The new marker.
Returns:: Reference to this rule.

StyleRule &setLiteralMarker(String literal, const CharStyle &style = {})

Configure a literal marker.

Parameters:

literal – The marker text.
style – Optional marker overlay style.

Returns:

Reference to this rule.

StyleRule &setLiteralMarker(std::u32string_view literal, const CharStyle &style = {})

Configure a literal marker.

Parameters:

literal – The marker text.
style – Optional marker overlay style.

Returns:

Reference to this rule.

StyleRule &setOrderedMarker(String suffix = String{".\t"}, const CharStyle &style = {})

Configure an ordered marker.

Parameters:

suffix – The text appended after the item number.
style – Optional marker overlay style.

Returns:

Reference to this rule.

StyleRule &setOrderedMarker(std::u32string_view suffix, const CharStyle &style = {})

Configure an ordered marker.

Parameters:

suffix – The text appended after the item number.
style – Optional marker overlay style.

Returns:

Reference to this rule.

StyleRule &clearMarker() noexcept

Remove any configured list marker.

Returns:: Reference to this rule.

using erbsland::cterm::text::TextNodePtr = std::shared_ptr<TextNode>

using erbsland::cterm::text::TextNodeConstPtr = std::shared_ptr<const TextNode>

using erbsland::cterm::text::TextNodeWeakPtr = std::weak_ptr<TextNode>

class TextNode : public std::enable_shared_from_this<TextNode>

A node in the text tree.

Public Types

enum class WalkResult : uint8_t

The result for the walk function call.

Values:

enumerator Continue: Continue.

enumerator Stop: Stop and return.

using Type = TextNodeType: The node type.

using Level = int: The nesting or heading level used by structural nodes.

Public Functions

TextNode(Type type, std::optional<std::u32string> text, std::optional<std::string> identifier, std::optional<std::string> style, std::optional<std::string> data, Level level) noexcept

Create a node with explicit metadata.

Parameters:

type – The node type.
text – Optional UTF-32 text content.
identifier – Optional identifier or anchor.
style – Optional style or class information.
data – Optional node-specific payload such as a link target or language.
level – The heading or nesting level.

inline explicit TextNode(const Type type) noexcept

Create a node with a type and otherwise empty metadata.

Parameters:: type – The node type.

inline TextNode(const Type type, std::u32string text, const Level level = 0) noexcept

Create a node with inline text content.

Parameters:

type – The node type.
text – The UTF-32 text content.
level – The heading or nesting level.

inline TextNode(const Type type, const Level level) noexcept

Create a node with a type and explicit level.

Parameters:

type – The node type.
level – The heading or nesting level.

std::vector<std::string> toDiagnosticTree(std::size_t indent = 4) const noexcept

Render this node tree into a human-readable diagnostic tree.

Each entry contains one node with metadata, indented by the given number of spaces per depth level.

Parameters:: indent – The number of spaces for each nesting level.
Returns:: The rendered diagnostic lines.

inline Type type() const noexcept

Get the node type.

Returns:: The node type.

bool hasChildren() const noexcept

Test if this node currently owns child nodes.

Returns:: true if child nodes are present.

const std::vector<TextNodePtr> &children() const noexcept

Access the child nodes.

Returns:: The child node list.

bool hasParent() const noexcept

Test if this node has a parent.

Returns:: true if a parent node is set.

TextNodePtr parent() const noexcept

Access the parent node.

Returns:: The parent node, or nullptr if there is none.

void setParent(const TextNodePtr &parent) noexcept

Set the parent node reference.

Parameters:: parent – The new parent node.

void addChild(TextNodePtr child) noexcept

Append one child node and update its parent reference.

Parameters:: child – The child node to add.

const std::u32string &text() const noexcept

Access the stored text payload.

Returns:: The UTF-32 text content, or an empty string if none is stored.

const std::optional<std::string> &identifier() const noexcept

Access the optional identifier.

Returns:: The identifier, if set.

void setIdentifier(std::string identifier) noexcept

Replace the identifier.

Parameters:: identifier – The new identifier.

const std::optional<std::string> &style() const noexcept

Access the optional style information.

Returns:: The style or class value, if set.

void setStyle(std::string style) noexcept

Replace the optional style information.

Parameters:: style – The new style or class value.

const std::optional<std::string> &data() const noexcept

Access the optional node-specific data payload.

Returns:: The data payload, if set.

void setData(std::string data) noexcept

Replace the optional node-specific data payload.

Parameters:: data – The new data payload.

Level level() const noexcept

Get the heading or nesting level.

Returns:: The current level.

void setLevel(Level level) noexcept

Set the heading or nesting level.

Parameters:: level – The new level.

template<typename Fn> inline WalkResult walk(Fn nodeFn) const

Recursively walk the node tree.

If the called function returns WalkResult::Stop, the walk will stop and return immediately.

Returns:: Continue if the walk completed, Stop if the walk was stopped by the function.

template<typename Fn> inline bool anyOf(Fn nodeFn) const

Recursively walk the node tree and return true if one fn(node) call returns true.

Parameters:: nodeFn – A function with the signature fn(const TextNode &node) -> bool.
Returns:: True if any node matches the predicate, false otherwise.

Public Static Functions

static TextNodePtr create(Type type) noexcept

Create a node with the given type using default metadata, empty text, and level 0.

Parameters:: type – The node type to create.
Returns:: The created node.

static TextNodePtr createDocument() noexcept

Create a document root node.

Returns:: The created node.

static TextNodePtr createParagraph() noexcept

Create a paragraph node.

Returns:: The created node.

static TextNodePtr createSection() noexcept

Create a section node.

Returns:: The created node.

static TextNodePtr createBlockquote() noexcept

Create a blockquote node.

Returns:: The created node.

static TextNodePtr createLineBreak() noexcept

Create an explicit line-break node.

Returns:: The created node.

static TextNodePtr createHeading(Level level) noexcept

Create a heading node.

Parameters:: level – The heading level.
Returns:: The created node.

static TextNodePtr createBulletList(Level level) noexcept

Create a bullet list node.

Parameters:: level – The nesting level.
Returns:: The created node.

static TextNodePtr createNumberedList(Level level) noexcept

Create a numbered list node.

Parameters:: level – The nesting level.
Returns:: The created node.

static TextNodePtr createListItem() noexcept

Create a list item node.

Returns:: The created node.

static TextNodePtr createDefinitionList() noexcept

Create a definition list node.

Returns:: The created node.

static TextNodePtr createDefinitionTerm() noexcept

Create a definition term node.

Returns:: The created node.

static TextNodePtr createDefinitionDescription() noexcept

Create a definition description node.

Returns:: The created node.

static TextNodePtr createCodeBlock(std::string language) noexcept

Create a code block node.

Parameters:: language – The optional language identifier.
Returns:: The created node.

static TextNodePtr createHorizontalLine() noexcept

Create a horizontal rule node.

Returns:: The created node.

static TextNodePtr createText(std::u32string text) noexcept

Create a plain text node.

Parameters:: text – The UTF-32 text content.
Returns:: The created node.

static TextNodePtr createEmphasis() noexcept

Create an emphasis node.

Returns:: The created node.

static TextNodePtr createStrong() noexcept

Create a strong-emphasis node.

Returns:: The created node.

static TextNodePtr createUnderline() noexcept

Create an underline node.

Returns:: The created node.

static TextNodePtr createSpan() noexcept

Create a generic span node.

Returns:: The created node.

static TextNodePtr createLink(std::string url) noexcept

Create a link node.

Parameters:: url – The link target.
Returns:: The created node.

static TextNodePtr createCode() noexcept

Create an inline code node.

Returns:: The created node.

static TextNodePtr createUnsupported(std::u32string text) noexcept

Create a placeholder node for unsupported content.

Parameters:: text – The placeholder text to render.
Returns:: The created unsupported node.

static bool isInlineNodeType(Type type) noexcept

Test if the given node type is an inline container node.

Parameters:: type – The node type.
Returns:: true for inline container nodes, otherwise false.

static bool isTextContainerType(Type type) noexcept

Test if the given node type can directly contain parsed text.

Parameters:: type – The node type.
Returns:: true if parsed text can be appended directly, otherwise false.

static bool isListNodeType(Type type) noexcept

Test if the given node type is a list container.

Parameters:: type – The node type.
Returns:: true for bullet or numbered lists, otherwise false.