Adding a new feature of diagram generation for the regex

- In beta development

Author: devbm7

README.md

@@ -12,12 +12,14 @@ Explain, test, and generate examples for regular expressions.
 - 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`)
 
@@ -46,14 +48,25 @@ Test if a string matches a pattern:
 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
+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
@@ -82,6 +95,9 @@ 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:
@@ -90,10 +106,6 @@ Contributions are welcome! To contribute:
 - Run tests
 - Open a pull request
 
-## License
-
-MIT
-
 ## Running Tests & Coverage
 
 To run all tests with coverage (threshold: 90%):
@@ -104,3 +116,7 @@ pytest
 ```
 
 If coverage is below 90%, pytest will fail. Coverage details will be shown in the terminal.
+
+## License
+
+MIT

docs/examples.md

@@ -21,4 +21,56 @@ print(examples(r"[A-Z]{2}\d{2}", count=2))
 ```python
 from rexplain import test
 print(test(r"foo.*", "foobar"))
+```
+
+## Railroad Diagrams
+
+### Basic Diagram Generation
+
+```python
+from rexplain import diagram
+
+# Generate a simple diagram
+svg_content = diagram(r"^\w+$")
+print(svg_content[:100])  # Show first 100 characters
+
+# Save diagram to file
+diagram(r"^\w+$", "simple_diagram.svg")
+```
+
+### Detailed Diagram Generation
+
+```python
+from rexplain import diagram
+
+# Generate a detailed diagram based on parsed components
+diagram(r"^\w+@\w+\.\w+$", "email_diagram.svg", detailed=True)
+```
+
+### CLI Usage
+
+```bash
+# Generate basic diagram
+rexplain diagram "^\\w+$" --output basic.svg
+
+# Generate detailed diagram
+rexplain diagram "^\\w+@\\w+\\.\\w+$" --detailed --output email.svg
+
+# Print SVG to stdout
+rexplain diagram "^\\d{3}-\\d{2}-\\d{4}$"
+```
+
+### Complex Pattern Examples
+
+```python
+from rexplain import diagram
+
+# Email validation pattern
+diagram(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$", "email_validation.svg")
+
+# Phone number pattern
+diagram(r"^\(\d{3}\) \d{3}-\d{4}$", "phone_number.svg")
+
+# Password validation pattern
+diagram(r"^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[A-Za-z\d]{8,}$", "password_validation.svg")
 ``` 

pyproject.toml

@@ -10,6 +10,9 @@ authors = [{name = "Dev B. Makwana"}]
 license = {text = "MIT"}
 readme = "README.md"
 requires-python = ">=3.8"
+dependencies = [
+    "pyrailroad>=0.4.0"
+]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",

src/rexplain/__init__.py

@@ -1,8 +1,9 @@
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 
 from .core.explainer import RegexExplainer
 from .core.generator import ExampleGenerator
 from .core.tester import RegexTester
+from .core.diagram import generate_railroad_diagram, generate_detailed_railroad_diagram
 
 def explain(pattern: str, flags: int = 0) -> str:
     r"""
@@ -58,4 +59,29 @@ def test(pattern: str, test_string: str, flags: int = 0):
         MatchResult(matches=True, reason='Full match.', ...)
     """
     result = RegexTester().test(pattern, test_string, flags=flags)
-    return result
+    return result
+
+
+def diagram(pattern: str, output_path: str = None, detailed: bool = False) -> str:
+    r"""
+    Generate a railroad diagram for a regex pattern.
+
+    Args:
+        pattern (str): The regex pattern to visualize.
+        output_path (str, optional): Path to save the SVG file. If None, returns SVG content.
+        detailed (bool, optional): Whether to generate a detailed diagram based on parsed components. Defaults to False.
+
+    Returns:
+        str: SVG content as string if output_path is None, otherwise the file path.
+
+    Example:
+        >>> diagram(r"^\w+$", "diagram.svg")
+        'diagram.svg'
+        >>> svg_content = diagram(r"^\w+$")
+        >>> print(svg_content[:100])
+        '<svg xmlns="http://www.w3.org/2000/svg" ...'
+    """
+    if detailed:
+        return generate_detailed_railroad_diagram(pattern, output_path)
+    else:
+        return generate_railroad_diagram(pattern, output_path)

src/rexplain/cli/main.py

@@ -7,6 +7,7 @@
     from rexplain.core.explainer import RegexExplainer
     from rexplain.core.generator import ExampleGenerator
     from rexplain.core.tester import RegexTester
+    from rexplain.core.diagram import generate_railroad_diagram, generate_detailed_railroad_diagram
     from rexplain import __version__
 except ImportError as e:
     print("IMPORT ERROR:", e, file=sys.stderr)
@@ -20,6 +21,10 @@ def generate(self, pattern, count=3):
     class RegexTester:
         def test(self, pattern, string):
             return type('Result', (), {"matches": True, "reason": "[Stub] Always matches", "to_dict": lambda self: {"matches": True, "reason": "[Stub] Always matches"}})()
+    def generate_railroad_diagram(pattern, output_path=None):
+        return f"[Stub] Diagram for: {pattern}"
+    def generate_detailed_railroad_diagram(pattern, output_path=None):
+        return f"[Stub] Detailed diagram for: {pattern}"
     __version__ = "unknown"
 
 PROJECT_ABOUT = (
@@ -31,7 +36,7 @@ def test(self, pattern, string):
 def main():
     parser = argparse.ArgumentParser(
         description='rexplain: Regex explanation toolkit',
-        epilog='Examples:\n  rexplain explain "^\\d{3}-\\d{2}-\\d{4}$" --examples 2\n  rexplain test "foo.*" "foobar"\n  rexplain --version\n  rexplain --about',
+        epilog='Examples:\n  rexplain explain "^\\d{3}-\\d{2}-\\d{4}$" --examples 2\n  rexplain test "foo.*" "foobar"\n  rexplain diagram "^\\w+$" --output diagram.svg\n  rexplain --version\n  rexplain --about',
         formatter_class=argparse.RawTextHelpFormatter
     )
     parser.add_argument('--version', action='store_true', help='Show version and exit')
@@ -54,6 +59,12 @@ def main():
     test_parser.add_argument('pattern', help='Regex pattern to test')
     test_parser.add_argument('string', help='String to test against the pattern')
 
+    # rexplain diagram "pattern" --output diagram.svg
+    diagram_parser = subparsers.add_parser('diagram', help='Generate a railroad diagram for a regex pattern')
+    diagram_parser.add_argument('pattern', help='Regex pattern to visualize')
+    diagram_parser.add_argument('--output', '-o', help='Output file path for SVG (default: print to stdout)')
+    diagram_parser.add_argument('--detailed', '-d', action='store_true', help='Generate detailed diagram based on parsed components')
+
     args = parser.parse_args()
 
     # Handle global flags
@@ -90,6 +101,17 @@ def main():
             output = result.to_dict() if hasattr(result, 'to_dict') else result
             print(output)
             sys.exit(0 if getattr(result, 'matches', False) else 1)
+        elif args.command == 'diagram':
+            if args.detailed:
+                result = generate_detailed_railroad_diagram(args.pattern, args.output)
+            else:
+                result = generate_railroad_diagram(args.pattern, args.output)
+            
+            if not args.output:
+                print(result)
+            else:
+                print(f"Diagram saved to: {result}")
+            sys.exit(0)
         else:
             parser.print_help()
             sys.exit(1)