https://github.com/devbm7/rexplain
Explain, test and generate examples for regular expressions
https://github.com/devbm7/rexplain
pip python-package python3 regex regex-util
Last synced: 8 months ago
JSON representation
Explain, test and generate examples for regular expressions
- Host: GitHub
- URL: https://github.com/devbm7/rexplain
- Owner: devbm7
- License: mit
- Created: 2025-07-23T08:06:50.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-08-01T09:41:44.000Z (8 months ago)
- Last Synced: 2025-08-01T11:56:40.597Z (8 months ago)
- Topics: pip, python-package, python3, regex, regex-util
- Language: Python
- Homepage: https://devbm7.github.io/rexplain/
- Size: 656 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# rexplain
[](https://pypi.org/project/rexplain/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/devbm7/rexplain/actions/workflows/test.yml)
[](https://github.com/devbm7/rexplain/actions/workflows/test.yml)
Explain, test, and generate examples for regular expressions.
## Overview
**rexplain** is a Python toolkit for understanding, testing, and generating examples for regular expressions. It provides:
- Human-readable, line-by-line explanations of regex patterns
- Example string generation for any regex
- Detailed match testing with feedback
- Visual railroad diagrams for regex patterns
- Both a Python API and a CLI
## Features
- **Regex Explanation:** Get clear, context-aware explanations for any regex pattern
- **Test Regex:** Test if a string matches a pattern and see why/why not
- **Generate Examples:** Generate example strings that match a regex
- **Visual Diagrams:** Generate railroad diagrams to visualize regex patterns
- **CLI & API:** Use from the command line or as a Python library
- **Regex Flags:** Supports Python regex flags (e.g., `re.IGNORECASE`)
## Installation
```bash
pip install rexplain
```
## Quick Start
### CLI Usage
Explain a regex pattern:
```bash
rexplain explain "^\d{3}-\d{2}-\d{4}$"
```
Generate example strings:
```bash
rexplain examples "[A-Za-z]{5}" --count 3
```
Test if a string matches a pattern:
```bash
rexplain test "^hello.*" "hello world!"
```
Generate a railroad diagram:
```bash
rexplain diagram "^\\w+$" --output diagram.svg
rexplain diagram "^\\w+$" --detailed --output detailed.svg
```
### Python API Usage
```python
from rexplain import explain, examples, test, diagram
print(explain(r"\d+"))
print(examples(r"[A-Z]{2}\d{2}", count=2))
print(test(r"foo.*", "foobar"))
# Generate diagrams
diagram(r"^\w+$", "simple.svg")
diagram(r"^\w+$", "detailed.svg", detailed=True)
svg_content = diagram(r"^\w+$") # Returns SVG as string
```
#### Example: Detailed Explanation
```python
from rexplain import explain
print(explain(r"abc\w+\w*10$"))
# Output:
# a - matches the character 'a' (ASCII 97) literally (case sensitive)
# b - matches the character 'b' (ASCII 98) literally (case sensitive)
# c - matches the character 'c' (ASCII 99) literally (case sensitive)
# \w+ - matches a word character one or more times (greedy)
# \w* - matches a word character zero or more times (greedy)
# 1 - matches the character '1' (ASCII 49) literally (case sensitive)
# 0 - matches the character '0' (ASCII 48) literally (case sensitive)
# $ - asserts position at the end of a line
```
## API Reference
### `explain(pattern: str, flags: int = 0) -> str`
Returns a line-by-line explanation of the regex pattern.
### `examples(pattern: str, count: int = 3, flags: int = 0) -> List[str]`
Generates example strings that match the pattern.
### `test(pattern: str, test_string: str, flags: int = 0) -> dict`
Tests if a string matches the pattern and explains why/why not.
### `diagram(pattern: str, output_path: str = None, detailed: bool = False) -> str`
Generates a railroad diagram for the regex pattern. Returns SVG content or saves to file.
## Contributing
Contributions are welcome! To contribute:
- Fork the repo and create a branch
- Add or improve features/tests/docs
- Run tests
- Open a pull request
## Running Tests & Coverage
To run all tests with coverage (threshold: 70%):
```bash
pip install .[test]
pytest
```
If coverage is below 70%, pytest will fail. Coverage details will be shown in the terminal.
### Test Coverage Details
- **Required Threshold**: 70%
- **Covered Modules**: All core functionality with comprehensive test coverage
- **Missing Coverage**: Mainly CLI interface and some edge cases in diagram generation
- **Live Status**: Check the [GitHub Actions](https://github.com/devbm7/rexplain/actions/workflows/test.yml) for current coverage reports
## License
MIT