A CLI tool that converts complex regular expressions into human-readable plain English descriptions with bidirectional conversion, example generation, and multi-flavor support.

Overview

Regex Humanizer helps developers understand and work with regular expressions by:

Explaining complex regex patterns in plain English
Generating concrete example strings that match patterns
Converting natural language descriptions to regex patterns
Supporting multiple regex flavors (PCRE, JavaScript, Python, Go)
Building patterns interactively through a guided wizard

Installation

From Source

git clone <repository-url>
cd regex-humanizer
pip install -e .

Using pip

pip install regex-humanizer

Development Installation

pip install -e ".[dev]"

Quick Start

Explain a regex pattern

# Simple pattern
regex-humanizer explain "^\w+@\w+\.\w+$"

# With specific flavor
regex-humanizer explain "hello" --flavor python

# Verbose output
regex-humanizer explain "\d{3}-\d{4}" --verbose

# JSON output
regex-humanizer explain "[a-z]+" --json

Generate matching examples

# Generate example matches
regex-humanizer generate "\d{3}-\d{4}"

# Specify number of examples
regex-humanizer generate "[abc]+" --count 10

# JSON output
regex-humanizer generate "\w+" --json

Convert English to regex

# Basic conversion
regex-humanizer from-english "a digit followed by a letter"

# With flavor
regex-humanizer from-english "one or more letters" --flavor javascript

# JSON output
regex-humanizer from-english "start of string followed by digits" --json

Interactive pattern builder

# Start the wizard
regex-humanizer build

Commands

explain

Explain a regex pattern in plain English.

regex-humanizer explain PATTERN [OPTIONS]

Options:

--flavor TEXT: Regex flavor (pcre, javascript, python, go) [default: pcre]
--verbose/--simple: Show detailed breakdown
--json: Output in JSON format

generate

Generate example strings that match the pattern.

regex-humanizer generate PATTERN [OPTIONS]

Options:

--flavor TEXT: Regex flavor [default: pcre]
-n, --count INTEGER: Number of examples [default: 5]
--json: Output in JSON format

from-english

Convert an English description to a regex pattern.

regex-humanizer from-english DESCRIPTION [OPTIONS]

Options:

--flavor TEXT: Target regex flavor [default: pcre]
--json: Output in JSON format

build

Launch the interactive pattern builder wizard.

regex-humanizer build

flavors

List all supported regex flavors.

regex-humanizer flavors

detect

Detect the flavor of a regex pattern based on syntax.

regex-humanizer detect PATTERN

Examples

Email pattern

$ regex-humanizer explain "^\w+@[a-z]+\.[a-z]+$"
Pattern: ^\w+@[a-z]+\.[a-z]+$
Flavor: pcre

Description:
the start of the string, one or more word characters, the literal character '@', one or more lowercase letters, the literal character '.', one or more lowercase letters, and the end of the string

Phone number pattern

$ regex-humanizer generate "\d{3}-\d{3}-\d{4}"
Pattern: \d{3}-\d{3}-\d{4}

Matching examples:
  1. 123-456-7890
  2. 555-123-4567
  3. 987-654-3210
  4. 111-222-3333
  5. 444-555-6666

Complex pattern with groups

$ regex-humanizer explain "(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})"
Pattern: (?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})
Flavor: pcre

Description:
a named 'year' group containing: exactly 4 digits, the literal character '-', a named 'month' group containing: exactly 2 digits, the literal character '-', and a named 'day' group containing: exactly 2 digits

Features

Regex to English Conversion

Parse any regex pattern and generate a human-readable explanation:

Literals and escaped characters
Character classes and ranges
Quantifiers (greedy, lazy, possessive)
Anchors (^, $, \b, \B)
Groups (capturing, non-capturing, named)
Alternations (|)
Special sequences (\d, \w, \s, etc.)

Example Match Generation

Generate concrete strings that match a pattern:

Support for all pattern types
Multiple examples per pattern
Random generation for variety
Fallback to test string matching

Bidirectional Conversion

Convert natural language to regex and back:

Parse English descriptions
Generate valid regex patterns
Round-trip validation

Multi-Flavor Support

Support for PCRE, JavaScript, Python, and Go:

Feature detection per flavor
Compatibility warnings
Flavor-aware parsing

Interactive Wizard

Build patterns step by step:

Guided interface
Real-time preview
Instant explanations
Edit and navigation support

Configuration

Environment Variables

Variable	Description
`PYTHONPATH`	Python path for imports (set to `src`)

Configuration Files

.pre-commit-config.yaml: Pre-commit hooks for code quality
pyproject.toml: Project configuration and dependencies

Development

Setup

git clone <repository-url>
cd regex-humanizer
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src

# Run specific test file
pytest tests/test_parser.py -v

Linting

# flake8
flake8 src/ tests/

# mypy type checking
mypy src/

Code Formatting

# Black formatting
black src/ tests/

# isort imports
isort src/ tests/

Pre-commit Hooks

# Install pre-commit hooks
pre-commit install

# Run all hooks manually
pre-commit run --all-files

Testing Strategy

The project includes comprehensive tests:

Unit tests: Parser, converter, examples, flavors modules
Integration tests: CLI commands end-to-end
Test files:
- tests/test_parser.py: Tokenization and AST tests
- tests/test_converter.py: English description tests
- tests/test_examples.py: Example generation tests
- tests/test_flavors.py: Flavor support tests
- tests/test_cli.py: CLI command tests

Error Handling

The tool handles common errors gracefully:

Invalid regex syntax: Clear error messages with position info
Unsupported features: Warnings for flavor incompatibilities
No matches found: Alternative example generation
Conversion loss: Round-trip validation warnings

License

MIT License