# rexgen
[](https://crates.io/crates/rexgen)
[](https://docs.rs/rexgen)
[](https://github.com/SecretDeveloper/rexgen/actions/workflows/ci.yml)
[](https://github.com/SecretDeveloper/rexgen/actions/workflows/ci.yml)
A fast CLI to generate text that matches regex-like patterns. Inspired by the original TDG tool, rexgen focuses on a cleaner pattern syntax, intuitive CLI flags, and a high-performance Rust core.
## What it does
- Generates random strings that match regex-like expressions (for example `\d{5}`, `[A-Z]{2,4}`, groups, ranges, repetition).
- Processes templates with placeholders like `{{ ... }}`, replacing each with generated content.
- Supports deterministic output via `--seed` and bulk generation via `--count`.
- Allows reusable named patterns loaded from external library files.
## Why a new version
- Keep the expressive, regex-like feel of TDG while making templates simpler and the CLI more intuitive.
- Rust for speed, portability, and a single static binary.
## CLI
- Modes (exactly one required)
- `pattern <expr>` Generate strings from a single pattern expression (no free text). Default behavior: `pattern` is assumed if the mode is omitted.
- `template <file>` Processes the provided template file containing `{{ ... }}` placeholders.
- `list` List available pattern names (with namespace) from loaded libraries; marks entries that contain placeholders.
- Output
- `--count, -c <n>` Number of items to produce (default `1`). Each item is one full pattern expansion or a full template render.
- `--output, -o <path>` Write results to a file instead of stdout.
- `--separator <sep>` Separator to join multiple outputs when `--count > 1` (default: newline). Note: this controls output joining and is unrelated to `[lib].delims` in `.rxlib` files.
- Randomness
- `--seed, -s <n>` Seed for deterministic generation (same inputs => same outputs).
- Libraries (named patterns)
- `--lib, -l <file>` Load a pattern library file. Repeatable.
- `--lib-dir, -I <dir>` Add a directory to the library search path. Repeatable.
- Behavior & diagnostics
- `--strict` Treat unknown named-patterns as fatal (default: unknown treated as literal where safe).
- `--verbose, -v` Increase verbosity; `-vv` for more. `--quiet, -q` to suppress non-errors.
- `--help, -h` Show help. `--version, -V` Show version.
- `--jobs <n>` Set the parallel worker count while keeping deterministic ordering with `--seed`.
- `--no-newline` Suppress the final trailing newline normally written after command output.
### CLI examples
- `rexgen "My SSN is '{{@us:ssn}}'." --lib us-data.rxlib --count 100 --seed 42` Generate 100 SSN-like values from a named entry, deterministically.
- `rexgen '[1-9]\d\d-\d\d-\d\d\d\d' --count 5` Generate 5 SSN-like values from a raw expression.
- `rexgen template template.txt --lib names.rxlib --count 10 --output out.txt` Render `template.txt` ten times using names from `names.rxlib`.
- `rexgen pattern '[A-Z]{3}' --count 5 --separator ', '` Inline pattern rendered five times, joined by a comma+space.
- `rexgen list --lib us-data.rxlib` List all named patterns in the provided lib.
- `rexgen list --lib-dir ./patterns` List all named patterns in the provided directory.
## Design
- Pattern engine: familiar regex-like tokens with generation semantics, not full PCRE.
- Templating: minimal—plain text plus `{{ pattern }}` placeholders.
- Libraries: rxlib (TOML) files with `[lib]` metadata and a single `[patterns]` table. `--lib` loads files; `--lib-dir` adds search paths; `--list` enumerates loaded names.
- Output: stdout by default; use `--output` to write to a file.
### Language Reference
- Full pattern and template syntax, escaping rules, named references, and library metadata are documented in `docs/rexgen-language.md`.
### Template and escaping rules
- See Language Reference for placeholder delimiters and escaping details.
### Determinism and parallelism
- `--seed` guarantees identical outputs for identical inputs.
- Parallel generation (`--jobs`) remains deterministic: worker RNGs derive from the master seed so ordering and content are stable across runs and platforms.
### Output joining
- When `--count > 1`, outputs are joined with `--separator` (default newline) and no trailing separator is written.
- A final newline is written after command output by default. Use `--no-newline` for raw output.
## Testing
- Run the normal suite with `cargo test`.
- Stress coverage lives in [`tests/stress_opt_in.rs`](/Users/gary/dev/github/rexgen/tests/stress_opt_in.rs) and is opt-in so local and CI runs stay fast.
- Enable stress tests with `REXGEN_RUN_STRESS=1 cargo test --test stress_opt_in -- --nocapture`.
### Namespaces
- `namespace` and pattern keys are case-sensitive. Use `{{@ns:name}}` inside placeholders to reference across namespaces.
### Imports and search order
- Import resolution: relative to the importing file first, then each `--lib-dir` in order, then the current working directory.
- Default search dirs: current working directory and `./rexgen-patterns`.
- Import cycles are detected and reported with the chain of files forming the cycle.
### Validation on load
- Validate duplicate names per namespace, invalid names, missing imports, and malformed files with clear errors (include file and line when possible).
### rxlib format (TOML)
- See Language Reference for library file structure (`[lib]`, `[patterns]`), placeholder delimiters (`[lib].delims`), and inline placeholders in values.