Bidirectional Text Formatter for Code Comments

A utility that processes mixed left-to-right (LTR) and right-to-left (RTL) text in code comments, ensuring proper visual display for documentation generators and IDE preview panes.

Capabilities

Format mathematical expressions with RTL text

Process text containing mathematical operations alongside RTL text, ensuring both the mathematical operators and RTL content display correctly.

• Given input "RESULT: 23 + 4-1 = 8" with uppercase treated as RTL, return the properly reordered text "8 = 1-4 + 32 :TLUSER" @test
• Given input "CALCULATE: 1.5 + 2.5 = 4.0" with uppercase treated as RTL, return properly formatted output "4.0 = 2.5 + 1.5 :ETALUCLAC" @test

Handle nested quotations in RTL context

Process text with quoted content that may contain nested punctuation or parenthetical information in RTL context.

• Given input 'USER SAID "ITEM (A, B) IS READY"' with uppercase treated as RTL, return '"YDAER SI (B ,A) METI" DIAS RESU' with mirrored parentheses @test
• Given input 'MESSAGE: "VALUE IS 100, STATUS: OK"' with uppercase treated as RTL, return '"KO :SUTATS ,100 SI EULAV" :EGASSEM' @test

Process mixed script text with explicit direction controls

Handle text with embedded directional formatting to create explicit left-to-right or right-to-left regions within larger text blocks.

• Given input "START\u202alatin text\u202cEND" (RTL embedding markers with uppercase treated as RTL), process the embedded LTR content correctly @test
• Given input with nested embeddings "OUTER\u202binner\u202alatin\u202cmid\u202cTAIL" (uppercase treated as RTL), handle multiple embedding levels correctly @test

Implementation

@generates

API

def format_comment(text: str, *, use_uppercase_as_rtl: bool = False) -> str:
    """
    Format bidirectional text for display in documentation and IDEs.

    Args:
        text: The text to format containing mixed LTR/RTL content
        use_uppercase_as_rtl: Debug mode to treat uppercase as RTL (for testing)

    Returns:
        Formatted text with proper bidirectional ordering for visual display
    """
    pass

Dependencies { .dependencies }

python-bidi { .dependency }

Provides bidirectional text algorithm implementation for proper text reordering.

@satisfied-by