Utilities

Helper classes used across the library for fonts, logging, keywords, and encoding.

DocraftFontApplier

Applies fonts to text nodes and manages font registration with the backend.

class DocraftFontApplier

Applies fonts to text nodes and manages font registration.

Uses the document context backend to register fonts and select appropriate encodings for text rendering.

Public Functions

void apply_font(const std::shared_ptr<model::DocraftText> &node) const

Applies font selection and encoding to a text node.

Parameters:

node – Text node.

~DocraftFontApplier()

Destructor.

explicit DocraftFontApplier(const std::shared_ptr<DocraftDocumentContext> &context)

Creates a font applier for a document context.

Parameters:

context – Document context.

bool is_font_utf8_encoding(const std::string &font_name) const

Returns whether a font uses UTF-8 encoding.

Parameters:

font_name – Font name.

Returns:

true if UTF-8 encoding is enabled.

Public Static Functions

static std::list<std::string> default_fonts()

Returns the list of built-in font names.

Returns:

List of font names.

static const char *get_font_registred_name(const std::string &name)

Returns the backend-registered name for a font.

Parameters:

name – Font family name.

Returns:

Backend-registered font name, or nullptr if missing.

static void set_font_encoding(const std::string &font_name, bool utf8)

Sets whether a font uses UTF-8 encoding.

Parameters:

  • font_name – Font name.

  • utf8 – true if UTF-8 encoding should be used.

DocraftFontRegistry

Singleton registry for in-memory and file-based fonts.

class DocraftFontRegistry

Singleton registry for in-memory and file-based fonts.

Stores raw font data so backends can register fonts without re-reading files.

Public Functions

bool register_font(const std::string &name, const unsigned char *data, size_t size)

Registers a font from memory.

Parameters:

  • name – Font family or variant name.

  • data – Raw font data.

  • size – Size of the data in bytes.

Returns:

true if the font was registered.

bool register_font(const std::string &name, const std::string &file_path)

Registers a font by loading it from a file path.

Parameters:

  • name – Font family or variant name.

  • file_path – Path to the font file.

Returns:

true on success, false on failure.

const DocraftFontData *get_font(const std::string &name) const

Returns font data for a registered name, or nullptr if missing.

Parameters:

name – Font family or variant name.

Returns:

Pointer to font data, or nullptr if not found.

std::vector<std::string> registered_font_names() const

Returns the list of registered font names.

Returns:

Vector of font names.

Public Static Functions

static DocraftFontRegistry &instance()

Returns the singleton instance.

Returns:

Reference to the registry singleton.

DocraftFontResolver

Resolves a font family + style request into the best available font name.

class DocraftFontResolver

Resolves a font family + style into an available font name.

The resolver builds a per-family index of available variants (regular/bold/italic/bold-italic) based on a list of built-in fonts and fonts registered in DocraftFontRegistry. It returns the closest available variant when an exact match is missing.

Public Functions

DocraftFontResolver() = default

Creates a font resolver with an empty index.

void rebuild_index(const std::vector<std::string> &builtin_fonts, const std::vector<std::string> &registered_fonts)

Rebuilds the internal index from the provided font name lists.

Parameters:

  • builtin_fonts – Built-in font names.

  • registered_fonts – Fonts registered at runtime.

std::string resolve(const std::string &requested, docraft::model::TextStyle style) const

Resolves the best matching font for a given request.

Parameters:

  • requested – Requested font family name.

  • style – Requested text style.

Returns:

Resolved font name (may be empty).

DocraftKeywordExtractor

Extracts document keywords using term-frequency statistics and stop-word filtering.

class DocraftKeywordExtractor

Extracts document keywords using term-frequency statistics.

Words are tokenized from text nodes, normalized to lowercase, filtered by min length and stopwords, then ranked by descending frequency.

Public Functions

DocraftKeywordExtractor()
explicit DocraftKeywordExtractor(Config config)
std::vector<std::string> extract(const DocraftDocument &document) const

Extract top keywords sorted by statistical frequency.

Parameters:

document – Source document.

Returns:

Top keyword list.

std::vector<std::pair<std::string, std::size_t>> extract_with_frequency(const DocraftDocument &document) const

Extract keywords with their occurrence counts.

Parameters:

document – Source document.

Returns:

Sorted pairs <keyword, frequency>.

struct Config

Public Members

std::size_t max_keywords = 10
std::size_t min_length = 4
std::vector<std::string> stop_word_languages = {"it", "en", "fr", "de", "es"}
std::unordered_set<std::string> stop_words

DocraftLogger

Simple console logging utility with configurable levels.

class DocraftLogger

Simple logging utility for console output.

Public Types

enum class LogLevel

Values:

enumerator kDebug
enumerator kInfo
enumerator kWarning
enumerator kError

Public Static Functions

static void debug(const std::string &message)

Logs a debug-level message.

Parameters:

message – Message to log.

static void info(const std::string &message)

Logs an info-level message.

Parameters:

message – Message to log.

static void warning(const std::string &message)

Logs a warning-level message.

Parameters:

message – Message to log.

static void error(const std::string &message)

Logs an error-level message.

Parameters:

message – Message to log.

static void set_level_enabled(LogLevel level, bool enabled = true)

Enables/disables a specific log level.

Parameters:

  • level – Log level to update.

  • enabled – Whether the level should be active.

static bool is_level_enabled(LogLevel level)

Returns current activation state of a log level.

Parameters:

level – Level to query.

Returns:

true if active.

static void reset_levels()

Resets levels to defaults: warning/error enabled, info/debug disabled.

static void enable_debug(bool enabled = true)
static void enable_info(bool enabled = true)
static void enable_warning(bool enabled = true)
static void enable_error(bool enabled = true)

DocraftParserUtilis

Static helpers for template expression detection and JSON data extraction.

class DocraftParserUtilis

Public Static Functions

static std::string extract_data_attribute(const std::string &data_request, const nlohmann::json &item)

Extracts a value from a JSON object based on a data request string.

The data request can be a simple key or a dot-separated path for nested values.

Parameters:

  • data_request – The data request string (e.g., “${data(name)” or “${data(“age”)”).

  • item – The JSON object to extract data from.

Returns:

The extracted value as a string, or an empty string if not found.

static std::string extract_data_attribute(const std::vector<unsigned char> &data_request, const nlohmann::json &item)
static bool is_data_request(const std::string &data_request)
static bool is_template_variable(const std::string &variable)
static bool is_data_request(const std::vector<unsigned char> &data)

Base64 Decoding

std::vector<unsigned char> docraft::utils::decode_base64(std::string_view input)

Decodes a base64 string into raw bytes.

Parameters:

input – Base64 string (no data URI prefix).

Throws:

std::invalid_argument – if the input is not valid base64.

Returns:

Decoded bytes.

Chain of Responsibility

Generic handler interface used by the layout engine.

template<class T, class K>
class DocraftChainOfResponsibilityHandler

Generic chain-of-responsibility handler interface.

Template Parameters:

  • T – Request type.

  • K – Result type.

Public Functions

virtual ~DocraftChainOfResponsibilityHandler() = default

Virtual destructor.

virtual bool handle(const std::shared_ptr<T> &request, K *result, docraft::DocraftCursor &cursor) = 0

Attempts to handle the request and write the result.

Parameters:

  • request – Input request.

  • result – Output result pointer.

  • cursor – Layout cursor used by handlers.

Returns:

true if handled, false otherwise.