# 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

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

### Using pip

```bash
pip install regex-humanizer
```

### Development Installation

```bash
pip install -e ".[dev]"
```

## Quick Start

### Explain a regex pattern

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Start the wizard
regex-humanizer build
```

## Commands

### explain

Explain a regex pattern in plain English.

```bash
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.

```bash
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.

```bash
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.

```bash
regex-humanizer build
```

### flavors

List all supported regex flavors.

```bash
regex-humanizer flavors
```

### detect

Detect the flavor of a regex pattern based on syntax.

```bash
regex-humanizer detect PATTERN
```

## Examples

### Email pattern

```bash
$ 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

```bash
$ 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

```bash
$ 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

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

### Running Tests

```bash
# Run all tests
pytest tests/ -v

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

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

### Linting

```bash
# flake8
flake8 src/ tests/

# mypy type checking
mypy src/
```

### Code Formatting

```bash
# Black formatting
black src/ tests/

# isort imports
isort src/ tests/
```

### Pre-commit Hooks

```bash
# 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