"""Punctuation handling and text-to-speech character substitution.

This module re-exports functionality from the unspeakables module for
backward compatibility. It provides character translation maps and
substitution functions for cleaning text before speech synthesis.

The module maintains the original API while delegating to unspeakables.py
for the actual implementation. This allows existing code to continue
using 'import punctuator' while benefiting from the refactored unspeakables
module.

Re-exported items:
    zwnj: Zero-width non-joiner character
    custom: Custom term translations (e.g., 'json' -> 'JSon')
    unspeakables: Basic unspeakable character replacements
    some: Some punctuation replacements (basic set)
    most: Most punctuation replacements (larger set)
    all: All punctuation replacements (complete set)
    is_punctuation: Function to check if string is all punctuation
    substitute: Function to translate text using translation map

Example:
    >>> from winston.punctuator import substitute, most
    >>> text = "Hello, world! Price: $5.99"
    >>> substitute(text, most)
    'Hello, world EXCLAIM Price COLON  DOLLAR   5.99'

Typical usage:
    from winston.punctuator import substitute, most
    clean_text = substitute(user_input, most)
    tts.speak(clean_text)

Note:
    This is a compatibility shim. New code should import from
    unspeakables module directly.
"""

from __future__ import annotations
from typing import Callable
import re
import string
import builtins
from . import unspeakables as unspeakables_module

# Re-export for backward compatibility
zwnj: str = unspeakables_module.zwnj
"""Zero-width non-joiner character (U+200C)."""

custom: dict[str, str] = unspeakables_module.custom
"""Custom translations for specific terms (e.g., 'json' -> 'JSon')."""

unspeakables: dict[str, str] = unspeakables_module.unspeakables  # This maintains the original variable name
"""Basic unspeakable character replacements (spaces, hyphens, etc.)."""

some: dict[str, str] = unspeakables_module.some
"""Some punctuation replacements - basic set (!, ?, @, etc.)."""

most: dict[str, str] = unspeakables_module.most
"""Most punctuation replacements - larger set (includes quotes, backslash)."""

all: dict[str, str] = unspeakables_module.all_punctuation
"""All punctuation replacements - complete set (includes periods, commas)."""

# Re-export functions for backward compatibility
is_punctuation: Callable[[str], bool] = unspeakables_module.is_punctuation
"""Check if string consists entirely of punctuation characters.

Args:
    s: String to check.

Returns:
    True if all characters are punctuation, False otherwise.
"""

substitute: Callable[[str, dict[str, str]], str] = unspeakables_module.substitute
"""Translate unsupported characters in text for TTS engines.

Performs multi-pass substitution including context-sensitive dash/hyphen
handling. First pass uses translation map, second pass applies dash/hyphen
context rules.

Args:
    input_text: The original text to be processed.
    translation_map: Dictionary mapping characters to replacements.
        Defaults to 'most' set.

Returns:
    The translated text suitable for TTS engine.

Note:
    Dashes are context-sensitive:
    - Surrounded by spaces or quotes: becomes 'dash'
    - Between words (no spaces): becomes space (for hyphenated words)
"""
