A CLI tool that converts complex regex patterns to human-readable English descriptions and automatically generates comprehensive test cases. Developers often struggle with cryptic regex patterns - this tool parses the regex and outputs a clear explanation of what each component does, plus generates sample inputs that match and don't match the pattern.

Features

Regex to English Translation: Convert any regex pattern to plain English
Auto-Generate Test Cases: Generate matching and non-matching test strings
Multi-Flavor Support: PCRE, JavaScript, and Python regex flavors
Interactive Mode: REPL-style interface for exploring regex patterns
Pattern Validation: Check if patterns are valid for a specific flavor
Flavor Conversion: Convert patterns between different regex flavors

Installation

pip install regex-humanizer-cli

Or from source:

pip install -e .

Quick Start

Explain a regex pattern:

regex-humanizer explain "\d{3}-\d{4}"

Generate test cases:

regex-humanizer test "\d{3}-\d{4}" --count 5

Start interactive mode:

regex-humanizer interactive

Commands

explain

Explain a regex pattern in human-readable English:

regex-humanizer explain "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"

Options:

--output, -o: Output format (text, json)
--verbose, -v: Show detailed breakdown
--flavor, -f: Regex flavor (pcre, javascript, python)

test

Generate test cases for a regex pattern:

regex-humanizer test "\d+" --count 10

Options:

--output, -o: Output format (text, json)
--count, -n: Number of test cases to generate (default: 5)

interactive

Start an interactive REPL for exploring regex patterns:

regex-humanizer interactive --flavor python

validate

Validate a regex pattern:

regex-humanizer validate "\A\z" --flavor python

convert

Convert a regex pattern between flavors:

regex-humanizer convert "\d{3}" --from-flavor pcre --to-flavor javascript

flavors

List available regex flavors:

regex-humanizer flavors

Interactive Mode

The interactive mode provides a REPL for exploring regex patterns:

$ regex-humanizer interactive
Regex Humanizer Interactive Mode
Type a regex pattern to explain, or 'help' for commands.

>>> \w+
Pattern: \w+
English Explanation:
  - ONE OR MORE of: word characters (letters, digits, or underscores)

Commands in interactive mode:

explain <pattern> - Explain a pattern
test <pattern> - Generate test cases
flavor <name> - Change regex flavor
help - Show help message
quit or exit - Exit interactive mode

Flavor Support

Flavor	Lookbehind	Possessive Quantifiers	Named Groups
PCRE	Yes	Yes	Yes
JavaScript	No	No	Yes
Python	Yes	No	Yes

Examples

Email Pattern

$ regex-humanizer explain "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"

Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Flavor: pcre

English Explanation:
  - START of string
  - ONE OR MORE of: characters from the set (letters, digits, dots, underscores, percent, plus, or hyphen)
  - LITERAL: @
  - ONE OR MORE of: characters from the set (letters, digits, dots, or hyphen)
  - LITERAL: .
  - ONE OR MORE of: letters
  - END of string

Phone Number Pattern

$ regex-humanizer test "\(\d{3}\) \d{3}-\d{4}" --count 3

Pattern: \(\d{3}\) \d{3}-\d{4}
Flavor: pcre

Matching strings (should match the pattern):
  1. (555) 123-4567
  2. (999) 000-9999
  3. (123) 456-7890

Non-matching strings (should NOT match the pattern):
  1. 555-123-4567
  2. (555)123-4567
  3. (555) 123 4567

Python API

from regex_humanizer import translate_regex, generate_test_cases

# Translate regex to English
explanation = translate_regex(r"\d{3}-\d{4}", flavor="pcre")
print(explanation)

# Generate test cases
tests = generate_test_cases(r"[a-z]+", flavor="python", matching_count=5)
print(tests)

Development

Setup

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/regex-humanizer-cli.git
cd regex-humanizer-cli
pip install -e ".[dev]"

Testing

pytest tests/ -v --cov=regex_humanizer --cov-report=term-missing

Linting

ruff check .

License

MIT License - see LICENSE file for details.