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 contains a match. It is the canonical Rust implementation used when comparing designs and performance against the C++, C#, and Python TextFinders.

1.1  Crates

The project is composed of four independent crates linked by relative paths. Library crates never reference each other 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); both are equivalent. Any option that appears on the command line 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 next three 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; all composition happens in EntryPoint, which supplies a DirEvent implementor that carries the regex-matching logic. Second, every observable performance win over the baseline rs_textfinder comes from reducing per-file work: cached DirEntry::file_type() avoids a stat syscall per entry, raw-byte regex avoids UTF-8 conversion, and a thread-local buffer avoids one heap allocation per file.