#!/usr/bin/env @PYCMD@
# -*- coding: utf-8 -*-
########################################################################
# Utility functions for variable substitution / expansion.
#    expand_path: expand $src/, $build/, etc. using dirs.py
#    expand_message: expand $var in free-form strings, with optional extras
#
# Copyright © 2025 by Bill Cattey and Warren Young
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
# OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above
# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

import re
from typing import Match, Optional, Dict
from . import dirs


def _lookup_expansion(
    key: str, extra: Optional[Dict[str, str]] = None
) -> Optional[str]:
    """Return expansion from dirs or from extra, or None if unknown."""
    val = getattr(dirs, key, None)
    if isinstance(val, str):
        return val
    if extra and key in extra:
        return extra[key]
    return None


def expand_message(template: str, extra: Optional[Dict[str, str]] = None) -> str:
    """
    Expand $vars in a message string using dirs + optional extra dict.
    Unknown variables remain unchanged.
    """

    def replacer(match: Match[str]) -> str:
        key = match.group(1)
        val = _lookup_expansion(key, extra)
        return val if val is not None else match.group(0)

    return re.sub(r"\$(\w+)", replacer, template)
