regex-buddy 1.0.0
Plain English to Regex - Your friendly regex helper
License: MIT
Requires Python: >=3.7
Keywords: regex, regular expressions, pattern matching, text processing

# regex-buddy

Plain English to Regex - Your friendly regex helper.

Stop struggling with regex syntax. Just describe what you want to match in plain English.

**Key Features:**
- 24+ built-in patterns with explanations
- **Debug why your regex doesn't match** (the killer feature!)
- Plain English to regex conversion
- Quick reference cheatsheet with escape guide
- Interactive regex builder
- Auto-diagnose problems when testing fails

## Installation

```bash
pip install regex-buddy
```

## Quick Start

```bash
# Get a pattern by name
regex-buddy get email

# List all available patterns
regex-buddy list

# Test a pattern against text
regex-buddy test email -t "Contact us at hello@example.com"

# Find a pattern by description
regex-buddy find "match phone numbers"

# Interactive mode
regex-buddy interactive
```

## Built-in Patterns

regex-buddy comes with 25+ pre-built patterns:

| Pattern | Description |
|---------|-------------|
| `email` | Match email addresses |
| `phone` | Match US phone numbers |
| `url` | Match URLs (http/https) |
| `ipv4` | Match IPv4 addresses |
| `date-mdy` | Match dates (MM/DD/YYYY) |
| `date-ymd` | Match dates (YYYY-MM-DD) |
| `time` | Match time (12 or 24 hour) |
| `credit-card` | Match credit card numbers |
| `ssn` | Match Social Security Numbers |
| `zip` | Match US ZIP codes |
| `hex-color` | Match hex color codes |
| `username` | Match usernames |
| `password-strong` | Match strong passwords |
| `slug` | Match URL slugs |
| `hashtag` | Match #hashtags |
| `mention` | Match @mentions |
| `uuid` | Match UUIDs |
| `html-tag` | Match HTML tags |
| `markdown-link` | Match Markdown links |
| `number` | Match numbers |
| `word` | Match whole words |

## Usage Examples

### Get a Pattern
```bash
$ regex-buddy get email

[email]
  Pattern: [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}
  Description: Match email addresses

  Python: r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"
  JavaScript: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g
```

### Get with Explanation
```bash
$ regex-buddy get email -v

[email]
  Pattern: [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}
  Description: Match email addresses

  Breakdown:
    [a-zA-Z0-9._%+-]+ - Username (letters, numbers, dots, underscores, etc.)
    @ - The @ symbol
    [a-zA-Z0-9.-]+ - Domain name
    \. - A literal dot
    [a-zA-Z]{2,} - Top-level domain (com, org, etc.)

  Examples that match:
    user@example.com
    test.email+tag@domain.co.uk
```

### Test a Pattern
```bash
$ regex-buddy test email -t "Send to john@example.com or jane@test.org"

Matches found: 2

Matches:
  1. john@example.com
  2. jane@test.org
```

### Find by Description
```bash
$ regex-buddy find "match urls"

Found built-in pattern: url
  Pattern: https?://(?:www\.)?...
  Description: Match URLs (http and https)
```

### Debug Why It Doesn't Match (The Killer Feature!)
```bash
$ regex-buddy debug "www.google.com" "visit www.google.com today"

Debugging pattern: www.google.com
Against text: visit www.google.com today

Pattern DOES match: ['www.google.com']

Suggestions:
  - '.' in your pattern: Dot matches ANY character. Use \. for literal dot
  - Consider using \b for word boundaries to avoid partial matches
```

The debug command catches common issues:
- Unescaped special characters (dots, asterisks, etc.)
- Case sensitivity problems
- Anchor issues (^ and $)
- Greedy vs lazy matching
- Missing word boundaries
- Shows partial matches to help you find where it breaks

### Cheatsheet
```bash
# Quick reference
$ regex-buddy cheatsheet

# Escape guide (what characters need escaping)
$ regex-buddy cheatsheet -e
```

### Explain Any Pattern
```bash
$ regex-buddy 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,}

Breakdown:
  [a-zA-Z0-9._%+-] - Any character in: a-zA-Z0-9._%+-
  + - One or more of previous
  [a-zA-Z] - Any character in: a-zA-Z
  {2,} - 2 or more times

Potential issues:
  - Unescaped '.' - matches ANY character. Did you mean '\.'?
```

### Interactive Mode
```bash
$ regex-buddy interactive

regex-buddy interactive mode
Commands: list, get <name>, test <pattern>, explain <pattern>, find <description>, quit

regex> get phone
regex> test email
Enter text to test (empty line to finish):
my email is test@example.com
please reply to hello@world.org

Matches found: 2
```

## Python API

```python
from regex_buddy import (
    get_pattern, test_pattern, list_patterns,
    debug_no_match, check_common_mistakes, RegexBuilder
)

# Get a pattern
email_pattern = get_pattern("email")
print(email_pattern["pattern"])
# [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}

# Test a pattern
result = test_pattern(email_pattern["pattern"], "Contact: user@example.com")
print(result["matches"])
# ['user@example.com']

# Debug why something doesn't match
diag = debug_no_match(r"www.google.com", "visit www.google.com")
print(diag["suggestions"])
# ['Dot matches ANY character. Use \\. for literal dot', ...]

# Check for common mistakes before they cause problems
warnings = check_common_mistakes(r"(a+)+")
# [{'type': 'catastrophic_backtracking', 'message': '...'}]

# Build patterns interactively
builder = RegexBuilder()
pattern = (builder
    .start()
    .digits(exact=3)
    .literal("-")
    .digits(exact=4)
    .end()
    .build())
print(pattern)  # ^\d{3}\-\d{4}$

# List all patterns
patterns = list_patterns()
for name, description in patterns.items():
    print(f"{name}: {description}")
```

## Support

If you find this project useful, consider supporting its development:

- [Buy Me a Coffee](https://buymeacoffee.com/brody4321)
- [Ko-fi](https://ko-fi.com/brody4321)

## License

MIT License