sparkles:base

sparkles:base is the shared foundation for Sparkles libraries: small allocation-conscious buffers, recycled Error storage for @nogc code, text readers/writers, owned Unicode 18 codecs and text algorithms, terminal styling, styled Interpolated Expression Sequences, and the core logging interface.

Use it when a package needs low-level building blocks without depending on the higher-level sparkles:core-cli UI and argument-parsing modules.

import sparkles.base.buffer : UniqueBuffer;
import sparkles.base.text.writers : writeIntegerPadded;

UniqueBuffer!(char, 16) buf;
writeIntegerPadded(buf, 7, 3);
assert(buf[] == "007");

Owned text APIs include unlimited whole-grapheme segmentation, explicit terminal cell policy, word/sentence/line boundaries, whole-paragraph bidi, normalization, contextual casing and typed source maps. Their @nogc cores use caller-owned arenas with explicit capacity failures and borrowed-view lifetimes; unlimited Unicode context does not mean unlimited caller storage. Import specialized modules directly as described in the API index.

How this documentation is organised

These docs follow the Diátaxis framework.

Tutorial

Learning-oriented. Build one small program using the buffer, text writer, styled text, and logger primitives.

• Getting started

How-to guides

Task-oriented. Short recipes for common jobs.

• Log through CoreLogger
• Write @nogc text
• Style templates with IES
• Pretty-print values
• Parse text with readers
• Analyze Unicode text without allocation
• Own a heap value without the collector
• Test @nogc code with check helpers

Reference

Information-oriented. Lookup material for modules and symbols.

• API index
• Base codecs
• Percent-encoding
• Unicode analysis

Explanation

Understanding-oriented. Why base exists as a separate package.

• The design
• Buffers: storage as capabilities
• Base codecs: design notes