From 940a803e1bfb8101876a1e37e3d7ac3e8a31d3ea Mon Sep 17 00:00:00 2001
From: 7000pctAUTO <lukems3823@gmail.com>
Date: Fri, 6 Feb 2026 01:09:42 +0000
Subject: [PATCH] Initial upload: regex-humanizer-cli with CI/CD workflow

---
 README.md | 213 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 211 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 510ef89..40949ab 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,212 @@
-# regex-humanizer-cli
+# Regex Humanizer CLI
 
-A CLI tool that converts complex regex patterns to human-readable English descriptions and generates comprehensive test cases
\ No newline at end of file
+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.