Getting Started

Build a Unicode-Safe Recursive Search Tool

In this tutorial you will build elgrep, a small command-line tool that searches files with an Erbsland Core regular expression. It accepts a file or a directory, walks directories recursively when requested, and highlights every match using safe terminal output.

$ elgrep [--recursive] <path> <pattern>

The example is deliberately practical. It combines several parts of Erbsland Core in one compact application:

• Application manages the executable lifecycle, options, help, and errors.

• Path and PathWalker provide portable filesystem access.

• RegEx searches Unicode text and reports byte-safe match ranges.

• TextInputStream reads one decoded line at a time.

• Terminal renders colored interactive output and plain redirected output through the same interface.

The tutorial starts with an empty Git repository and finishes with a useful C++20 application. You only need a compiler, CMake, Git, and an editor or IDE.

Create the Project Structure →

What This Tutorial Is Not

elgrep is a compact teaching application, not a replacement for a mature grep implementation. It treats regular files as UTF-8 text, searches each line independently, and returns success when the search completes even when no matches are found.