"""
sn_basis/functions/text_wrapper.py – Bezeichner-Hilfsfunktionen.

Zentrale Stelle, um Freitext (z. B. ein Thema oder ein Schriftfeldinhalt) in einen
technischen Bezeichner (Layername, Dateiname) umzuwandeln. Nicht pro Aufrufstelle
ein eigenes Regex schreiben – Umlaute, Unterstrich und Bindestrich werden hier an
einer Stelle gepflegt (siehe docs/wissen/fallstricke.md, Issue Plugin_SN_Basis #42).
"""

import re

# Buchstaben, Ziffern, deutsche Umlaute/ß, Unterstrich und Bindestrich gelten immer
# als zulässig. Wurde in der Vergangenheit wiederholt vergessen, wenn ein neues
# Regex direkt im Aufrufer entstand statt diese Funktion zu nutzen.
_BEZEICHNER_ERLAUBT = r"A-Za-z0-9_\-ÄäÖöÜüß"


def sanitize_bezeichner(text: str, ersatz: str = "_") -> str:
    """Wandelt `text` in einen technischen Bezeichner um.

    Alle Zeichen außerhalb von Buchstaben/Ziffern/Umlauten/ß/Unterstrich/Bindestrich
    werden durch `ersatz` ersetzt, anschließend werden führende und folgende
    Vorkommen von `ersatz` entfernt. Gedacht für Layer- und Dateinamen – nicht für
    Freitext in Schriftfeldern oder der Legende, wo auch andere Zeichen sichtbar
    bleiben sollen.
    """
    bereinigt = re.sub(rf"[^{_BEZEICHNER_ERLAUBT}]+", ersatz, text)
    return bereinigt.strip(ersatz)