Erbsland Core Documentation

Erbsland Core is a cross-platform C++20 foundation library for building secure, portable applications with little boilerplate. It provides a consistent API for Linux, macOS, and Windows and depends only on the C++ standard library.

Warning

Erbsland Core is in alpha. The available status is already useful for experiments and new applications, but the public API can change without a compatibility period. See Development Stages and Versioning for details.

Build elgrep — Start the Tutorial →

Choose Your Starting Point

Getting Started

Build a practical recursive search tool using the application framework, paths, streams, regular expressions, and safe terminal output.

Getting Started

Usage

Integrate Core as a Git submodule, configure its build, or consume an installed static library.

Usage

Feature Topics

Learn the concepts and patterns behind individual library areas.

Topics

API Reference

Look up public types, functions, and detailed behavior by API area.

Reference

Requirements

Check compiler, CMake, Git, platform, and contributor-tool requirements.

Requirements

Features Available Today

Text, data, and utilities

• Unicode-aware strings, text, and formatting for UTF-8, UTF-16, and UTF-32

• A safe, reliable regular-expression engine

• Byte and text streams, text encodings, and buffers

• Filesystem paths, file and directory operations, and file streams

• Date and time types, durations, and system-independent time-zone calculation

• Safe numeric utilities, including saturating arithmetic and checked conversions

• Fast and secure random-number generators with safe APIs

• Copy-on-write containers, coroutine primitives, enum flags, compression, and more

• Template render framework with a Jinja like syntax.

Applications and system integration

• Command-line option parsing with formatted help and version output

• An application framework and application-part management to minimize boilerplate

• A resource system for automatically compiled-in resources

• Terminal output with colors, styles, cursor movement, and terminal-size detection

• Error classes, diagnostics, and formatted diagnostic output

• The Erbsland Configuration Language, including validation rules

• Bounded asynchronous logging with hierarchical streams, runtime reconfiguration, and statistics

Events and networking

• Event loops, schedulers, timers, function invocation, and event threads

• Event-based TCP and UDP connections, host-name resolution, and more

• A TLS 1.3 network layer over TCP

• An event-based HTTP server and client framework for plain TCP and TLS

Cryptography

• An extensive cryptography layer with no dependency on other libraries

All Documentation

• Getting Started
• Usage
• Topics
  • Core
    • Core Application Framework
    • Choosing an Application Design
    • Writing Small Applications with Functions
    • Building Event-Driven Applications
    • Building Procedural Applications
    • Building Command-Style Applications
    • Building an Application from Parts
    • Designing Application Parts
    • Running Application Parts Independently
    • Creating Services and Foreground Daemons
    • Adding Git Version Information to Your App
  • Memory
    • Working with Bits and Bytes
    • Reading a Stream of Bits
    • Working with Predefined Byte-Spans
    • Working with Fixed Byte Arrays
    • Working with Byte Blocks
    • Byte Integer Formats Explained
    • Using Byte Buffers
    • Using Byte Ring Buffers
    • Reading and Parsing Byte Streams
    • Writing Byte Streams
    • Encoding Text in Binary Byte Streams
    • Compressing Data
    • Designing Custom Copy-on-Write Containers
    • Marking Unsafe Memory Access in Code
  • Compiled Resources
    • Compiling Resources into an Application or Library
  • Security Topics
    • About Sensitive Strings and Byte Blocks
    • Erasing Memory in a Secure Way
  • Cryptology
    • Cryptology Overview
    • Configuring TLS Profiles
    • Creating TLS Certificates and Requests
    • Storing and Verifying Passwords
    • Supported Password Hashing Algorithms
    • Using Hash Algorithms
    • Supported Hash Algorithms
  • Text
    • Text in Erbsland Core
    • Using Strings
    • String Attributes
    • Transforming Strings
    • Editing Strings in Place
    • Managing StringEditor Storage
    • Finding Text Positions
    • Slicing and Splitting Strings
    • Character Access and Parsing of Strings
    • Converting Text and Scalar Values
    • Comparing Whole and Partial Strings
    • Normalizing Unicode Strings
    • Working with Character Sets
    • Building Strings
    • Formatting Text Patterns
    • Format Specifications
    • Compatibility Format Specifications
    • Recognizing Text Patterns
    • Converting Strings
    • Encoding Internationalized Names
  • Command Line Options System
    • Options System Overview
    • Option Definitions
    • Option Sets
    • Option Modules
    • Option Values
    • Customizing Help Output
  • Exceptions, Errors and Diagnostics
    • Error Handling Overview
    • Reporting Errors with Result
    • Throwing and Handling Exceptions
    • Working with Diagnostic Data
    • Writing Custom Exceptions
  • Filesystem Access and Manipulation
    • Path API Overview
    • Working with Paths
  • Random and Secrets
    • Random API Overview
    • Working with Random Values
    • Shuffling and Selecting Elements
    • Secure Randomness
  • Regular Expressions
    • Pattern Syntax
    • Assembler, Usage and Syntax
  • Event System
    • Event System API Overview
  • Logging
    • Logging Overview
    • Choosing a Logging Setup
    • Writing Log Messages
    • Configuring Logging in Code
    • Formatting Log Lines
    • Configuring Log Manager Limits
    • Using Trace Sections
    • Using Log Writers
    • Writing Logs to the Console
    • Writing Logs to Files
    • Sending Logs to Syslog
    • Loading Logging Configuration
    • Writing an ELCL Logging Configuration
  • Streams
    • Working with Streams
    • Creating Streams and Managing Ownership
    • Byte Input and Output
    • Text Input, Output, and Encoding
    • Standard Streams
    • Readiness and Timeouts
    • Buffering and Back Pressure
    • Stream Lifecycle
    • Temporary Streams
    • Positioning Streams
    • Stream Errors and Diagnostics
    • Coroutine Streams
    • Writing Custom Streams
  • Network
    • Network API Overview
    • Working with IP Addresses and Hostnames
    • Resolving Hosts Asynchronously
    • Using TCP Connections
    • Using TLS Client Connections
    • Using TLS Server Connections
    • Using HTTP Servers
    • Using HTTP Clients
    • Sending and Receiving UDP Packets
  • Color Terminal
    • Color Terminal Demos
    • Terminal
    • Backend
    • Input
    • Cursor Output
    • Buffer
    • Buffer Views
    • Frames, Borders, Tiles
    • BlockText Rendering
    • Paragraph Options
    • Bitmap
    • Font
    • Strings and Chars
    • Color
    • Geometry
• Reference
  • Block Reference
    • Block Geometry
  • Configuration Language Reference
    • Configuration Language
    • Configuration Validation Rules
  • Core Functionality
    • Application Error Context
    • Application Framework
    • Definitions
    • Make One Namespace
    • Namespaces
  • Cryptology
    • Cryptographic Operations
    • Key Agreement and Signing
    • Password Hashing
    • Protected Data
    • TLS Support
    • X.509 Certificates
  • Cterm Reference
    • Interactive Line Editor
    • Terminal Interface
    • Terminal Document Renderer
  • Debug Reference
    • Debugging Utilities
  • Error Handling Reference
    • Errors and Diagnostics
  • Event Reference
    • Event System
  • Geometry Reference
    • Geometry Types
  • Internationalization Reference
    • Internationalization
  • Log Reference
    • Logging
  • Mathematical Types and Functions
    • Mathematical Types and Operations
  • Memory Related Types and Functions
    • Memory and Byte Data
  • Network Reference
    • Network Addressing and URLs
    • Network Connections
    • HTTP Client
    • HTTP Protocol Types
    • HTTP Server
  • Options Reference
    • Command-Line Options
  • Path Reference
    • File-System Paths
  • Random Generator
    • Random Numbers
  • Regular Expression Reference
  • Compiled Resources
    • Compiled Resources
  • Stream Reference
    • Streams
  • System Support
    • System Services
  • Text Processing
    • Characters and Unicode
    • Text Documents and Rendering
    • Text Encoding and Conversion
    • Text Formatting and Parsing
    • Text Matching and Splitting
    • Strings and Collections
  • Time Reference
    • Date and Time
  • Unit Types and Functions
    • Units and Versions
  • Utility Types and Functions
    • General Utilities
• The Story Behind Erbsland Core
  • A Simple Rule: Avoid Duplicated Code
  • Growing Alongside Qt
  • When Reuse Becomes Fragmentation
  • Separate First, Then Port and Combine
• Development Stages and Versioning
  • Alpha Stage
  • Transition from Alpha to Beta
  • Beta Stage
  • First Stable Release
• Requirements
  • Using Erbsland Core
  • Developing Erbsland Core
• Changelog
  • Version 0.1 - 2026-05-20
• Guidelines
  • Erbsland C++ Code Style
    • Formatting
    • Naming
    • Files and Includes
    • CMake
    • Comments and API Documentation
    • Class Organization
    • Modern C++
    • Erbsland Core Integration
  • CMake Build Files Structure
  • Guidelines for File Structures
    • Relation File vs. Type
    • Splitting Implementation over Multiple Files
    • Forward Declarations
    • Out-of-Line Implementations
    • Include Ownership
    • Optional Standard-Library Formatters
    • Directories and Namespaces
    • Separating Implementation Details from the Public API
  • Platform Integration Guidelines
    • General Rules
    • Strings and Buffers
    • Platform Notes
    • Tests
  • ReStructuredText Style
    • Header Style
    • Linking Symbols
  • Topic Page Guidelines
    • What are Good Topic Pages?
    • File Structure
    • Page Structure
    • Recommended Workflow to Create the Content
    • Recommended Writing Style
    • Anti-Patterns
    • Related Guidelines
  • Reference Page Guidelines
    • File Structure
    • Page Structure
    • Related Guidelines
  • Writing Style
    • General Guidelines
  • Guidelines for Writing Demos
    • Purpose of Demos
    • Demo Executable Behavior
    • Demo Code in Documentation Pages
    • Language and Themes in Demos
    • Code Style, API Usage and Theming
  • Guidelines for Writing Examples and Demos
    • Code Style
    • API Usage
    • Language and Themes in Example Code
    • Unicode and Emojis
  • Themes and Languages for Examples and Demos
    • Theme Selection
    • Demo Content Inspirations
    • Natural Language in Examples
  • Bad Code and Anti-Patterns
    • Severity
    • Automated Scanner
    • Accepted Locations
    • Anti-Pattern Catalog
  • Cryptographic Algorithm Documentation
    • Specification Mapping
    • Security-Relevant Decisions
    • Secret Lifetime
  • How to Write API Guidelines
    • Why API Guidelines
    • Common Principles
    • Main Page Structure
    • Structural Validation
    • Anti-Patterns
    • Related Guidelines
  • Common API Guidelines
    • Pattern Placeholder Definitions
    • Common Patterns
    • Additional Name Principles
    • Exception and Error Handling
    • Test Status Markers
    • Domain-Specific Page Guidelines
    • Related Guidelines
  • Block Geometry Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Pattern Definitions
    • Value Object Patterns
    • State and Membership Patterns
    • Geometry Arithmetic Patterns
    • Direction and Ring Patterns
    • Layout Patterns
    • Iteration and Division Patterns
  • Geometry API Guidelines
    • Primary Types
    • Secondary Types
    • Value Object Patterns
  • Configuration Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Value and Document Types
    • Source and Trust Types
    • Validation Rules Types
    • Error Types
    • Pattern Definitions
    • Value Access Patterns
    • Document Construction Patterns
    • Parsing Patterns
    • Validation Rule Construction Patterns
    • Source and Trust Patterns
  • Core Application API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Lifecycle Patterns
    • Customization Patterns
    • Application-Part Patterns
    • Application Service Patterns
    • Application Instance Patterns
    • Metadata and Error Patterns
  • Cryptology Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • X.509 Identity Patterns
    • Hash Selection Patterns
    • Hashing Patterns
    • Message Authentication Patterns
    • Key Derivation Patterns
    • Symmetric Encryption Patterns
    • Cryptology Configuration Patterns
    • TLS Configuration Parser Patterns
    • Protected Data Patterns
    • Key Agreement Patterns
    • Password Hashing Patterns
    • X.509 Certificate Patterns
    • Signature Verification Patterns
    • TLS 1.3 Record Protection Patterns
  • Color Terminal Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Buffer Types
    • Drawing Types
    • Input Types
    • Terminal Integration Types
    • Document Types
    • Pattern Definitions
    • Block and Style Patterns
    • Buffer Read Patterns
    • Buffer Write Patterns
    • Cursor Write Patterns
    • Terminal Patterns
    • Input Patterns
    • Interactive Read Patterns
    • Document Rendering Patterns
  • Error Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Pattern Definitions
    • Exception Patterns
    • Error Context Patterns
    • Throw Helper Patterns
  • Event Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Event Value Types
    • Scheduling and Thread Types
    • Backend Types
    • Pattern Definitions
    • Event Value Patterns
    • Dispatch Patterns
    • Subscription Patterns
    • Event Loop Patterns
    • Timer and Thread Patterns
    • Backend Patterns
  • Internationalization API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Map Patterns
    • Translator Patterns
  • Log Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Manager Patterns
    • Producer Patterns
    • Writer Patterns
  • Math Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Pattern Definitions
    • Saturating Arithmetic Patterns
    • Integer Utility Patterns
    • Big Integer Patterns
    • Saturating Value Patterns
    • Range and Bounded Value Patterns
  • Memory Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Compression Types
    • Pattern Definitions
    • Internal Byte Tool Patterns
    • Byte Value Patterns
    • Byte Sequence Read Patterns
    • Mutable Byte Sequence Patterns
    • Shared Block Patterns
    • Integer Access Patterns
    • Sequential Read and Write Patterns
    • Ring Buffer Patterns
    • Byte Compression Patterns
    • Sensitive Byte Storage Patterns
    • Shared Storage Patterns
  • Compiled Resource API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Lookup Patterns
    • Metadata Patterns
  • Network Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Address Value Patterns
    • URL Value Patterns
    • HTTP Value Patterns
    • Source Creation Patterns
    • Static Content Patterns
    • Source Lifecycle Patterns
    • TCP Patterns
    • UDP Patterns
    • TLS Client Patterns
    • TLS Server Patterns
    • HTTP Server Patterns
    • HTTP Client Patterns
  • Options Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Definition Types
    • Result Types
    • Callback and Error Types
    • Pattern Definitions
    • Definition Construction Patterns
    • Definition Name Patterns
    • Definition Property Patterns
    • Parsing Patterns
    • Display Patterns
    • Result Patterns
    • Typed Value Access Patterns
  • Path API Guidelines
    • Primary Types
    • Operation Types
    • Option Types
    • Value Types
    • Pattern Definitions
    • Path Value Patterns
    • Operation Accessor Patterns
    • Read and Write Patterns
    • Mutation and Temporary Resource Patterns
    • Information Patterns
    • Traversal Patterns
  • Random Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Source Patterns
    • Selection Patterns
    • Build Patterns
    • Mutation Patterns
    • Construction Patterns
    • Application Patterns
  • Regular Expression API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Pattern Definitions
    • Compilation and Matching Patterns
    • Match Result Patterns
    • Settings Patterns
    • Custom Input Patterns
  • Stream API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Pattern Definitions
    • Lifecycle Patterns
    • Positioning Patterns
    • Read Patterns
    • Write Patterns
    • Coroutine Patterns
    • Standard Stream Patterns
  • System Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Secondary Types
    • Lookup Patterns
    • Environment Variable Patterns
    • Process Information Patterns
    • System Information Patterns
    • Subprocess Patterns
    • Application Patterns
    • Platform Error Patterns
  • Text Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Processing Types
    • Formatting and Parsing Types
    • Collection and Pattern Types
    • Document Types
    • Layout Renderer Types
    • Codec Types
    • Pattern Definitions
    • String Value Patterns
    • String Editing Patterns
    • Reader and Split Patterns
    • Conversion and Encoding Patterns
    • Formatting and Parsing Patterns
    • Sensitive UTF-8 Patterns
    • Document Patterns
    • JSON Value Patterns
    • Layout Renderer Patterns
    • Base-N Codec Patterns
    • Punycode and IDNA Patterns
  • Time Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Amount and Part Types
    • Supporting Types
    • Policy Types
    • Part Value Patterns
    • Calendar Inspection Patterns
    • Civil Value Patterns
    • Time-of-Day Patterns
    • Duration and Delta Patterns
    • Date-Time Patterns
    • Time-Zone Patterns
    • Formatting and Parsing Patterns
    • Monotonic Time Patterns
  • Unit and Value Domain API Guidelines
    • Core Semantics
    • Primary Types
    • Concrete Unit Types
    • Value Types
    • Supporting Types
    • Pattern Definitions
    • Common Value Patterns
    • Index Patterns
    • Length and Offset Patterns
    • Range Patterns
    • Ratio Amount Patterns
    • Version Patterns
  • Utilities API Guidelines
    • Primary Types
    • Secondary Types
    • Pattern Definitions
    • Hash Patterns
    • Common Container Patterns
    • List Patterns
    • Set Patterns
    • Map Patterns
    • Flag Patterns
    • Result Patterns
    • Coroutine Patterns

The Guidelines section is contributor material for developing Core itself.

Documentation Indices

• Index

• Search Page