import string


def fill_template_filename(template_string, substitution_dict):
    """
    Replace variables in the template with the respective substitution dict entries.

    Checks the `template_string` for variables (i.e., something like '${VAR_NAME}') that are listed as keys in `substitution_dict`. If such entries are found, they are replaced with the respective values in the `substitution_dict`. This function only calls `ting.Template().substitute()` in the background.

    Parameters
    ----------
    template_string: string
        A template string, see the `string.Template` constructor in the standard Python `string` module. Variable names must be enclosed in `${}`. Example: `${SUBJECT_ID}_hardcoded_text`.

    substitution_dict: dictionary string, string
        The keys are variable names, values are the replacements. See `string.Template.substitute` in the standard Python `string` module. Example: `{ 'SUBJECT_ID' : 'subject3' }`.

    Returns
    -------
    string
        The result of the replacement.

    Examples
    --------
    Fill in a template string:

    >>> import brainload.nitools as nit
    >>> template_str = '${HEMI}.white'
    >>> substitution_dict = {'HEMI' : 'lh'}
    >>> print nit.fill_template_filename(template_str, substitution_dict)
    lh.white
    """
    return string.Template(template_string).substitute(substitution_dict)