regex-humanizer/README.md

Regex Humanizer CLI

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