# Regex Humanizer CLI

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

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

Or from source:

```bash
pip install -e .
```

## Quick Start

Explain a regex pattern:

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

Generate test cases:

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

Start interactive mode:

```bash
regex-humanizer interactive
```

## Commands

### explain

Explain a regex pattern in human-readable English:

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

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

```bash
regex-humanizer interactive --flavor python
```

### validate

Validate a regex pattern:

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

### convert

Convert a regex pattern between flavors:

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

### flavors

List available regex flavors:

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

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

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

```python
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

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

### Testing

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

### Linting

```bash
ruff check .
```

## License

MIT License - see LICENSE file for details.