API Reference

This page provides auto-generated documentation for the rexplain package.

Package Overview

rexplain

diagram(pattern, output_path=None, detailed=False)

Generate a railroad diagram for a regex pattern.

Parameters:

Name	Type	Description	Default
pattern	str	The regex pattern to visualize.	required
output_path	str	Path to save the SVG file. If None, returns SVG content.	None
detailed	bool	Whether to generate a detailed diagram based on parsed components. Defaults to False.	False

Returns:

Name	Type	Description
str	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" ...'

Source code in src/rexplain/__init__.py

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)

examples(pattern, count=3, flags=0)

Generate example strings that match the regex pattern.

Parameters:

Name	Type	Description	Default
pattern	str	The regex pattern.	required
count	int	Number of examples to generate. Defaults to 3.	3
flags	int	Regex flags (e.g., re.IGNORECASE). Defaults to 0.	0

Returns:

Type	Description
	List[str]: Example strings matching the pattern.

Example

examples(r"[A-Z]{2}\d{2}", count=2) ['AB12', 'XY34']

Source code in src/rexplain/__init__.py

def examples(pattern: str, count: int = 3, flags: int = 0):
    r"""
    Generate example strings that match the regex pattern.

    Args:
        pattern (str): The regex pattern.
        count (int, optional): Number of examples to generate. Defaults to 3.
        flags (int, optional): Regex flags (e.g., re.IGNORECASE). Defaults to 0.

    Returns:
        List[str]: Example strings matching the pattern.

    Example:
        >>> examples(r"[A-Z]{2}\d{2}", count=2)
        ['AB12', 'XY34']
    """
    return ExampleGenerator().generate(pattern, count, flags=flags)

explain(pattern, flags=0)

Explain what a regex pattern does, line by line.

Parameters:

Name	Type	Description	Default
pattern	str	The regex pattern to explain.	required
flags	int	Regex flags (e.g., re.IGNORECASE). Defaults to 0.	0

Returns:

Name	Type	Description
str	str	A line-by-line explanation of the regex pattern.

Example

explain(r"^\w+$") '^ - asserts position at the start of a line\n\w+ - matches a word character one or more times (greedy)\n$ - asserts position at the end of a line'

Source code in src/rexplain/__init__.py

def explain(pattern: str, flags: int = 0) -> str:
    r"""
    Explain what a regex pattern does, line by line.

    Args:
        pattern (str): The regex pattern to explain.
        flags (int, optional): Regex flags (e.g., re.IGNORECASE). Defaults to 0.

    Returns:
        str: A line-by-line explanation of the regex pattern.

    Example:
        >>> explain(r"^\w+$")
        '^ - asserts position at the start of a line\n\w+ - matches a word character one or more times (greedy)\n$ - asserts position at the end of a line'
    """
    return RegexExplainer().explain(pattern, flags=flags)

test(pattern, test_string, flags=0)

Test if a string matches a regex pattern and explain why/why not.

Parameters:

Name	Type	Description	Default
pattern	str	The regex pattern.	required
test_string	str	The string to test.	required
flags	int	Regex flags (e.g., re.IGNORECASE). Defaults to 0.	0

Returns:

Name	Type	Description
MatchResult		Result object with match status and explanation.

Example

test(r"foo.*", "foobar") MatchResult(matches=True, reason='Full match.', ...)

Source code in src/rexplain/__init__.py

def test(pattern: str, test_string: str, flags: int = 0):
    r"""
    Test if a string matches a regex pattern and explain why/why not.

    Args:
        pattern (str): The regex pattern.
        test_string (str): The string to test.
        flags (int, optional): Regex flags (e.g., re.IGNORECASE). Defaults to 0.

    Returns:
        MatchResult: Result object with match status and explanation.

    Example:
        >>> test(r"foo.*", "foobar")
        MatchResult(matches=True, reason='Full match.', ...)
    """
    result = RegexTester().test(pattern, test_string, flags=flags)
    return result