# Source code for fontTools.ufoLib.filenames

    from __future__ import annotations

    from collections.abc import Iterable

    """
    Convert user-provided internal UFO names to spec-compliant filenames.

    This module implements the algorithm for converting between a "user name" -
    something that a user can choose arbitrarily inside a font editor - and a file
    name suitable for use in a wide range of operating systems and filesystems.

    The `UFO 3 specification <http://unifiedfontobject.org/versions/ufo3/conventions/>`_
    provides an example of an algorithm for such conversion, which avoids illegal
    characters, reserved file names, ambiguity between upper- and lower-case
    characters, and clashes with existing files.

    This code was originally copied from
    `ufoLib <https://github.com/unified-font-object/ufoLib/blob/8747da7/Lib/ufoLib/filenames.py>`_
    by Tal Leming and is copyright (c) 2005-2016, The RoboFab Developers:

    -	Erik van Blokland
    -	Tal Leming
    -	Just van Rossum
    """

    # Restrictions are taken mostly from
    # https://docs.microsoft.com/en-gb/windows/win32/fileio/naming-a-file#naming-conventions.
    #
    # 1. Integer value zero, sometimes referred to as the ASCII NUL character.
    # 2. Characters whose integer representations are in the range 1 to 31,
    #    inclusive.
    # 3. Various characters that (mostly) Windows and POSIX-y filesystems don't
    #    allow, plus "(" and ")", as per the specification.
    illegalCharacters: set[str] = {
        "\x00",
        "\x01",
        "\x02",
        "\x03",
        "\x04",
        "\x05",
        "\x06",
        "\x07",
        "\x08",
        "\t",
        "\n",
        "\x0b",
        "\x0c",
        "\r",
        "\x0e",
        "\x0f",
        "\x10",
        "\x11",
        "\x12",
        "\x13",
        "\x14",
        "\x15",
        "\x16",
        "\x17",
        "\x18",
        "\x19",
        "\x1a",
        "\x1b",
        "\x1c",
        "\x1d",
        "\x1e",
        "\x1f",
        '"',
        "*",
        "+",
        "/",
        ":",
        "<",
        ">",
        "?",
        "[",
        "\\",
        "]",
        "(",
        ")",
        "|",
        "\x7f",
    }
    reservedFileNames: set[str] = {
        "aux",
        "clock$",
        "com1",
        "com2",
        "com3",
        "com4",
        "com5",
        "com6",
        "com7",
        "com8",
        "com9",
        "con",
        "lpt1",
        "lpt2",
        "lpt3",
        "lpt4",
        "lpt5",
        "lpt6",
        "lpt7",
        "lpt8",
        "lpt9",
        "nul",
        "prn",
    }
    maxFileNameLength: int = 255

    class NameTranslationError(Exception):
        pass

    def userNameToFileName(
        userName: str, existing: Iterable[str] = (), prefix: str = "", suffix: str = ""
    ) -> str:
        """Converts from a user name to a file name.

        Takes care to avoid illegal characters, reserved file names, ambiguity between
        upper- and lower-case characters, and clashes with existing files.

        Args:
                userName (str): The input file name.
                existing: A case-insensitive list of all existing file names.
                prefix: Prefix to be prepended to the file name.
                suffix: Suffix to be appended to the file name.

        Returns:
                A suitable filename.

        Raises:
                NameTranslationError: If no suitable name could be generated.

        Examples::

                >>> userNameToFileName("a") == "a"
                True
                >>> userNameToFileName("A") == "A_"
                True
                >>> userNameToFileName("AE") == "A_E_"
                True
                >>> userNameToFileName("Ae") == "A_e"
                True
                >>> userNameToFileName("ae") == "ae"
                True
                >>> userNameToFileName("aE") == "aE_"
                True
                >>> userNameToFileName("a.alt") == "a.alt"
                True
                >>> userNameToFileName("A.alt") == "A_.alt"
                True
                >>> userNameToFileName("A.Alt") == "A_.A_lt"
                True
                >>> userNameToFileName("A.aLt") == "A_.aL_t"
                True
                >>> userNameToFileName(u"A.alT") == "A_.alT_"
                True
                >>> userNameToFileName("T_H") == "T__H_"
                True
                >>> userNameToFileName("T_h") == "T__h"
                True
                >>> userNameToFileName("t_h") == "t_h"
                True
                >>> userNameToFileName("F_F_I") == "F__F__I_"
                True
                >>> userNameToFileName("f_f_i") == "f_f_i"
                True
                >>> userNameToFileName("Aacute_V.swash") == "A_acute_V_.swash"
                True
                >>> userNameToFileName(".notdef") == "_notdef"
                True
                >>> userNameToFileName("con") == "_con"
                True
                >>> userNameToFileName("CON") == "C_O_N_"
                True
                >>> userNameToFileName("con.alt") == "_con.alt"
                True
                >>> userNameToFileName("alt.con") == "alt._con"
                True
        """
        # the incoming name must be a string
        if not isinstance(userName, str):
            raise ValueError("The value for userName must be a string.")
        # establish the prefix and suffix lengths
        prefixLength = len(prefix)
        suffixLength = len(suffix)
        # replace an initial period with an _
        # if no prefix is to be added
        if not prefix and userName[0] == ".":
            userName = "_" + userName[1:]
        # filter the user name
        filteredUserName = []
        for character in userName:
            # replace illegal characters with _
            if character in illegalCharacters:
                character = "_"
            # add _ to all non-lower characters
            elif character != character.lower():
                character += "_"
            filteredUserName.append(character)
        userName = "".join(filteredUserName)
        # clip to 255
        sliceLength = maxFileNameLength - prefixLength - suffixLength
        userName = userName[:sliceLength]
        # test for illegal files names
        parts = []
        for part in userName.split("."):
            if part.lower() in reservedFileNames:
                part = "_" + part
            parts.append(part)
        userName = ".".join(parts)
        # test for clash
        fullName = prefix + userName + suffix
        if fullName.lower() in existing:
            fullName = handleClash1(userName, existing, prefix, suffix)
        # finished
        return fullName

    def handleClash1(
        userName: str, existing: Iterable[str] = [], prefix: str = "", suffix: str = ""
    ) -> str:
        """A helper function that resolves collisions with existing names when choosing a filename.

        This function attempts to append an unused integer counter to the filename.

            Args:
                    userName (str): The input file name.
                    existing: A case-insensitive list of all existing file names.
                    prefix: Prefix to be prepended to the file name.
                    suffix: Suffix to be appended to the file name.

            Returns:
                    A suitable filename.

            >>> prefix = ("0" * 5) + "."
            >>> suffix = "." + ("0" * 10)
            >>> existing = ["a" * 5]

            >>> e = list(existing)
            >>> handleClash1(userName="A" * 5, existing=e,
            ...		prefix=prefix, suffix=suffix) == (
            ... 	'00000.AAAAA000000000000001.0000000000')
            True

            >>> e = list(existing)
            >>> e.append(prefix + "aaaaa" + "1".zfill(15) + suffix)
            >>> handleClash1(userName="A" * 5, existing=e,
            ...		prefix=prefix, suffix=suffix) == (
            ... 	'00000.AAAAA000000000000002.0000000000')
            True

            >>> e = list(existing)
            >>> e.append(prefix + "AAAAA" + "2".zfill(15) + suffix)
            >>> handleClash1(userName="A" * 5, existing=e,
            ...		prefix=prefix, suffix=suffix) == (
            ... 	'00000.AAAAA000000000000001.0000000000')
            True
        """
        # if the prefix length + user name length + suffix length + 15 is at
        # or past the maximum length, silce 15 characters off of the user name
        prefixLength = len(prefix)
        suffixLength = len(suffix)
        if prefixLength + len(userName) + suffixLength + 15 > maxFileNameLength:
            l = prefixLength + len(userName) + suffixLength + 15
            sliceLength = maxFileNameLength - l
            userName = userName[:sliceLength]
        finalName = None
        # try to add numbers to create a unique name
        counter = 1
        while finalName is None:
            name = userName + str(counter).zfill(15)
            fullName = prefix + name + suffix
            if fullName.lower() not in existing:
                finalName = fullName
                break
            else:
                counter += 1
            if counter >= 999999999999999:
                break
        # if there is a clash, go to the next fallback
        if finalName is None:
            finalName = handleClash2(existing, prefix, suffix)
        # finished
        return finalName

    def handleClash2(
        existing: Iterable[str] = [], prefix: str = "", suffix: str = ""
    ) -> str:
        """A helper function that resolves collisions with existing names when choosing a filename.

        This function is a fallback to :func:`handleClash1`. It attempts to append an unused integer counter to the filename.

            Args:
                    userName (str): The input file name.
                    existing: A case-insensitive list of all existing file names.
                    prefix: Prefix to be prepended to the file name.
                    suffix: Suffix to be appended to the file name.

            Returns:
                    A suitable filename.

            Raises:
                    NameTranslationError: If no suitable name could be generated.

            Examples::

              >>> prefix = ("0" * 5) + "."
              >>> suffix = "." + ("0" * 10)
              >>> existing = [prefix + str(i) + suffix for i in range(100)]

              >>> e = list(existing)
              >>> handleClash2(existing=e, prefix=prefix, suffix=suffix) == (
              ... 	'00000.100.0000000000')
              True

              >>> e = list(existing)
              >>> e.remove(prefix + "1" + suffix)
              >>> handleClash2(existing=e, prefix=prefix, suffix=suffix) == (
              ... 	'00000.1.0000000000')
              True

              >>> e = list(existing)
              >>> e.remove(prefix + "2" + suffix)
              >>> handleClash2(existing=e, prefix=prefix, suffix=suffix) == (
              ... 	'00000.2.0000000000')
              True
        """
        # calculate the longest possible string
        maxLength = maxFileNameLength - len(prefix) - len(suffix)
        maxValue = int("9" * maxLength)
        # try to find a number
        finalName = None
        counter = 1
        while finalName is None:
            fullName = prefix + str(counter) + suffix
            if fullName.lower() not in existing:
                finalName = fullName
                break
            else:
                counter += 1
            if counter >= maxValue:
                break
        # raise an error if nothing has been found
        if finalName is None:
            raise NameTranslationError("No unique name could be found.")
        # finished
        return finalName

    if __name__ == "__main__":
        import doctest

        doctest.testmod()