---
name: regex-build
description: Test, explain, and sanity-check Python/PCRE regex patterns. Pass a pattern and test strings, get all matches with capture groups + a per-token explanation of the regex itself (anchors, quantifiers, character classes, groups). Pure Python stdlib. Use when the user asks "explain this regex", "test this regex", "build a regex for X", "what does this pattern match", or wants to debug a non-matching expression.
---


# regex-build

Regex sandbox + explainer. Pure Python stdlib (`re`).

## What it does

- Tests a pattern against one or more strings.
- Reports match status, all matches with `(start, end, group())`, and named groups.
- **Explains the pattern token-by-token** (anchors, quantifiers, character classes, groups, lookarounds, alternation).
- Optional `re.sub` mode for substitution previews.

## Usage

Test a pattern against inline strings:

```bash
python3 scripts/regex.py --pattern "\d+" --test "abc 123 def 456" --test "no digits here"
```

Read test strings from a file (one per line):

```bash
python3 scripts/regex.py --pattern "^\w+@\w+\.\w+$" --file emails.txt
```

Read test string from stdin:

```bash
echo "hello world" | python3 scripts/regex.py --pattern "\b\w+\b" --stdin
```

Substitution preview:

```bash
python3 scripts/regex.py --pattern "(\w+)\s(\w+)" --test "John Doe" --substitute "\2 \1"
```

Skip the explanation (just matches):

```bash
python3 scripts/regex.py --pattern "\d+" --test "abc 123" --no-explain
```

## Flags

`--flags` accepts a comma-separated list:

| flag | meaning            |
|------|--------------------|
| `i`  | IGNORECASE         |
| `m`  | MULTILINE          |
| `s`  | DOTALL             |
| `x`  | VERBOSE            |
| `a`  | ASCII              |
| `u`  | UNICODE            |

Example:

```bash
python3 scripts/regex.py --pattern "^hello" --test "Hello World" --flags "i,m"
```

## Output sections

1. **Pattern explanation** — each token annotated.
2. **Per-test results** — match status, every match span + groups (named groups labelled).
3. **Substitute output** (if `--substitute` provided).

## Why

`re.DEBUG` dumps the AST. This skill gives you a human-readable token explanation, all matches in one pass, and clean output for sanity-checking patterns before pasting into prod code.