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 0.90.0 (Beta 1) is the first beta release. The public API can change without a compatibility period. Minor version updates may introduce breaking API changes. 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.
Usage
Integrate Core as a Git submodule, configure its build, or consume an installed static library.
Feature Topics
Learn the concepts and patterns behind individual library areas.
API Reference
Look up public types, functions, and detailed behavior by API area.
Requirements
Check compiler, CMake, Git, platform, and contributor-tool requirements.
Library Development
Prepare a checkout to work on Core itself, run repository maintenance commands, or extend the maintenance tool.
Features Available Today
Text, data, and utilities
Unicode-aware strings, text, and formatting for UTF-8, UTF-16, and UTF-32
JSON, BSON, CBOR, and XML value and document APIs for parsing and serialization
A safe, reliable regular-expression engine
Byte and text streams, text encodings, and buffers
Filesystem paths, file and directory operations, and file streams
UTC timestamps, calendar 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
Text layout rendering with a Jinja-like template language
Applications and system integration
Command-line option parsing with formatted help and version output
An application framework and application-part management to minimize boilerplate
Release-package tooling for Windows and macOS applications
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
Signed byte blocks and challenge-response authentication tokens
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
- Creating Release Packages
- Registering Packages in CMake
- Configuring Release Package Contents
- Signing and Notarizing Release Packages
- Memory
- Working with Bits and Bytes
- Reading and Writing Bit Streams
- 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
- Designing Custom Copy-on-Write Containers
- Marking Unsafe Memory Access in Code
- Compression
- Compiled Resources
- Security Topics
- Cryptology
- Text Strings
- Text Strings Overview
- 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
- Comparing Whole and Partial Strings
- Normalizing Unicode Strings
- Working with Character Sets
- Fuzzy Matching with Edit Distance
- Text Formatting
- Text Rendering
- Text Placeholders
- Text Parsing and Encoding
- Text Parsing and Encoding Overview
- Converting Text and Scalar Values
- Recognizing Text Patterns
- Converting Strings
- Encoding Internationalized Names
- Encoding Byte Data as Base-N Text
- Writing Bytes as Base-N Text
- Reading Base-N Text into Bytes
- Parsing HTML into Documents
- Parsing Compact Named-Key Parameters
- Configuring Named-Key Parameter Lists
- Customizing Named-Key Syntax
- Data Formats
- Configuration
- Configuration Overview
- Parsing Configuration Documents
- Working with Configuration Trees
- Accessing Configuration Values
- Validating Documents with Rule Schemas
- Using Values after Validation
- Resolving Configuration Sources
- Controlling Access to Configuration Sources
- Using Placeholders in Configuration Text
- Trusting Signed Configuration Files
- Validating Configuration Signatures
- Signing Configuration Documents
- Command Line Options System
- Exceptions, Errors and Diagnostics
- Filesystem Access and Manipulation
- Random and Secrets
- Dates and Time
- Dates and Time Overview
- Working with Dates
- Working with Times
- Working with UTC Timestamps
- Working with DateTime Values
- Customizing ISO Date and Time Output
- Working with Whole-Second Durations
- Writing Time Values with Literals
- Working with Typed Time Amounts
- Working with Precise Time Intervals
- Customizing Time Interval Output
- Understanding Calendar Changes
- Working with Calendar and Time Parts
- Measuring Elapsed Time
- Working with Monotonic Time Points
- Keeping a Wall-Clock Time with Its Zone
- Working with Time Zones
- Regular Expressions
- Event System
- Event System Overview
- Events in Erbsland Core
- Running an Application with Event Loops
- Processing Work on Event Threads
- Using Event Loops in Application Parts
- Connecting to Event Sources
- Handling Event Failures
- Keeping Callbacks and Their Owners Alive
- Scheduling Work and Timers
- Simplifying Event Code with Bindings
- Building Workflows Across Callbacks
- Communicating Between Event Loops
- Cancelling Work and Shutting Down
- Keeping Event Loops Responsive Under Load
- Driving Event Loops Directly
- Designing Objects That Produce Events
- Defining and Posting Typed Events
- Writing an Event Backend
- Integrating Native Waiting and Custom Drivers
- 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
- Color Terminal
- Color Terminal Demos
- Terminal Setup and Screen Rendering
- Implementing Terminal Backends
- Keyboard Input and Terminal Text Editing
- Cursor-Based Terminal Output
- Working with Terminal Buffers
- Viewing and Scrolling Terminal Buffers
- Drawing Terminal Frames, Borders, and Tiles
- Rendering Text in Terminal Buffers
- Configuring Terminal Paragraph Layout
- Rendering Terminal Bitmaps
- Rendering and Defining Bitmap Fonts
- Terminal Text Blocks and Block Strings
- Terminal Colors and Animated Palettes
- Terminal Layout Geometry
- Core
- Reference
- Block Reference
- Compression Related
- Configuration Language Reference
- Core Functionality
- Cryptology
- Cterm Reference
- Data Formats
- Debug Reference
- Error Handling Reference
- Event Reference
- Geometry Reference
- Internationalization Reference
- Log Reference
- Mathematical Types and Functions
- Memory Related Types and Functions
- Network Reference
- Options Reference
- Path Reference
- Random Generator
- Regular Expression Reference
- Compiled Resources
- Stream Reference
- System Support
- Text Processing
- Time Reference
- Unit Types and Functions
- Utility Types and Functions
- The Story Behind Erbsland Core
- Development Stages and Versioning
- Requirements
- Changelog
- Development
- Set Up the Repository
- Use the Maintenance Tool
- Run and Configure Commands
- Check the Repository for Commit
- Build the Documentation
- Validate API Guidelines
- Validate API Test Status
- Update Reference Documentation
- Prepare Doxygen Sources
- Create a Documentation Demo
- Process RST Documentation
- Format ELCL Files
- Clean Up the Code
- Check Anti-Patterns
- Generate Display Texts
- Generate IDNA Data
- Generate Unicode Data
- Generate Category Test Data
- Generate Time-Zone Data
- Generate Common Box-Frame Style
- Generate Frame-Border Joint Characters
- Generate Public Suffix List Data
- Customize Generated Notices
- Update Unicode Sources
- Update the Public Suffix List
- Update Public Headers
- Generate Saturating Math Data
- Generate Time Tests
- Import Cryptology Vectors
- Maintain Security Hashes
- Audit GitHub Workflow Actions
- Inspect Include Dependencies
- Develop the Maintenance Tool
- Maintenance Tool Reference
- Framework Reference
- Pre-commit Reference
- Rendering Configuration
- Documentation Build Reference
- Documentation Maintenance Reference
- Code Cleanup Reference
- Anti-Patterns Reference
- Display Text Generator Reference
- IDNA Generator Reference
- Unicode Data Generator Reference
- Category Test Generator Reference
- Time-Zone Generator Reference
- Terminal Frame Generator Reference
- Public Suffix Generator Reference
- Public Headers Reference
- Saturating Math Generator Reference
- Time Test Generator Reference
- Cryptology Vector Importer Reference
- Security Hashes Reference
- GitHub Workflows Reference
- Include Dependencies Reference
- Guidelines
- Erbsland C++ Code Style
- CMake Build Files Structure
- Guidelines for File Structures
- Platform Integration Guidelines
- ReStructuredText Style
- Topic Page Guidelines
- Reference Page Guidelines
- Maintenance Tool Documentation Guidelines
- Writing Style
- Guidelines for Writing Demos
- Integrating Demos into Pages
- Guidelines for Writing Examples and Demos
- Themes and Languages for Examples and Demos
- Bad Code and Anti-Patterns
- Archive Format Documentation
- Cryptographic Algorithm Documentation
- How to Write API Guidelines
- Common API Guidelines
- Block Geometry Domain API Guidelines
- Compression Domain API Guidelines
- Geometry API Guidelines
- Configuration Domain API Guidelines
- Core Semantics
- Primary Types
- Value and Document Types
- Source and Trust Types
- Validation Rules Types
- Error Types
- Syntax Formatting Types
- Pattern Definitions
- Value Access Patterns
- Document Construction Patterns
- Parsing Patterns
- Validation Rule Construction Patterns
- Source and Trust Patterns
- Syntax Formatting Patterns
- Core Application API Guidelines
- 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 and Parser Patterns
- Protected Data Patterns
- Key Agreement Patterns
- Password Hashing Patterns
- X.509 Certificate Patterns
- Signature Verification Patterns
- TLS 1.3 Record Protection Patterns
- TLS Identity 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
- Emulation and Rendering Patterns
- Error Domain API Guidelines
- Event Domain API Guidelines
- Internationalization API Guidelines
- Log Domain API Guidelines
- Math Domain API Guidelines
- Memory Domain API Guidelines
- Core Semantics
- Primary Types
- Secondary 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
- Sequential Bit Read and Write Patterns
- Ring Buffer Patterns
- Sensitive Byte Storage Patterns
- Shared Storage Patterns
- Compiled Resource API Guidelines
- Network Domain API Guidelines
- Options Domain API Guidelines
- Path API Guidelines
- Random Domain API Guidelines
- Regular Expression API Guidelines
- Stream API Guidelines
- System Domain API Guidelines
- 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
- Character Set Construction Patterns
- String Value Patterns
- String Joining Patterns
- String Transformation 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
- Placeholder Patterns
- Named-Key Parsing Patterns
- Base-N Codec Patterns
- Punycode and IDNA Patterns
- String Matching Patterns
- C++ Source Scanning Patterns
- Data Domain API Guidelines
- 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
- Timestamp Patterns
- Unit and Value Domain API Guidelines
- Utilities API Guidelines