1.  Introduction

rs_textfinder_opt is a recursive, regex-based file-content search tool written in Rust. Given a root directory, a set of file extensions, and a regular expression, it walks the directory tree and prints every file whose content matches. It serves as the canonical Rust implementation for design and performance comparisons against the C++, C#, and Python TextFinders.

1.1  Crates

Four independent crates make up the project, linked by relative paths. No library references another library or the application binary - all composition happens in EntryPoint.

Crate	Kind	Role
RustCmdLine	library	Parses /Key [Value] or -Key [Value] command-line arguments
RustDirNav	library	Generic, event-driven depth-first directory walker
EntryPoint	binary (text_finder)	Application - wires the libraries and drives the search
RustTfVerify	binary (tf_verify)	Integration verifier - runs text_finder as a subprocess and checks its output against requirement assertions

RustCmdLine     RustDirNav
       \             /
        \           /
       EntryPoint  ────▶  text_finder (binary)
                                    ▲
                                    │ subprocess
                              RustTfVerify

1.2  Quick Start

# 1. Build the search tool
cd EntryPoint
cargo build

# 2. Search the parent directory for Rust files containing "struct"
cargo run -- /P ".." /p "rs" /r "struct"

# bash / Unix users - the - prefix works equally well
cargo run -- -P ".." -p "rs" -r "struct"

1.3  Command-Line Options

Options accept either a / prefix (Windows / PowerShell) or a - prefix (bash / Unix); the two forms are equivalent. An option supplied without a following value receives the value "true".

Option	Argument	Default	Meaning
/P	path	.	Root directory for the search
/p	extensions	(all files)	Comma-separated extensions, e.g. rs,txt
/r	regex	. (any)	Regular expression matched against file content
/s	true/false	true	Recurse into subdirectories
/H	true/false	true	Hide directories that contain no matching files
/v	(flag)	off	Print all resolved options before searching
/h	(flag)	off	Print help and exit

1.4  Examples

# Find all Rust files containing "impl" under the current directory
cargo run -- /P "." /p "rs" /r "impl"

# Search text and markdown files for a TODO comment, show all directories
cargo run -- /P "." /p "txt,md" /r "TODO" /H false

# Verbose output - shows resolved path, patterns, and regex before searching
cargo run -- /P ".." /p "rs" /r "fn main" /v

1.5  Design at a Glance

The following pages walk through the design and full source of each component in composition order:

Page	Focus
2. RustCmdLine	CmdLineParse - argv → HashMap<char, String> + extension patterns; dual / / - prefix support.
3. RustDirNav	Generic DirNav<App: DirEvent> depth-first walker with baked-in skip list and cached file_type().
4. EntryPoint	read_file buffer reuse, TextFinder byte-regex matcher, TfAppl event glue, and main wiring.
5. Conclusion	Sample output, build & test commands, integration verifier, and references.

Two design threads run through every part. First, no library depends on another library or on the binary; EntryPoint owns all composition and supplies a DirEvent implementor that carries the regex-matching logic. Second, every performance win over the baseline rs_textfinder comes from cutting per-file work: caching DirEntry::file_type() eliminates a stat syscall per entry, a raw-byte regex skips UTF-8 conversion, and a thread-local buffer removes one heap allocation per file.