"""
This module provides the `FormatCodes` class, which includes methods to print and work with strings that
contain special formatting codes, which are then converted to ANSI codes for pretty console output.

------------------------------------------------------------------------------------------------------------------------------------
### The Easy Formatting

First, let's take a look at a small example of what a highly styled print string with formatting could look like using this module:
```
This here is just unformatted text. [b|u|br:blue](Next we have text that is bright blue + bold + underlined.)\\n
[#000|bg:#F67](Then there's also black text with a red background.) And finally the ([i](boring)) plain text again.
```

How all of this exactly works is explained in the sections below. 🠫

------------------------------------------------------------------------------------------------------------------------------------
#### Formatting Codes and Keys

In this module, you can apply styles and colors using simple formatting codes.
These formatting codes consist of one or multiple different formatting keys in between square brackets.

If a formatting code is placed in a print-string, the formatting of that code will be applied to everything behind it until its
formatting is reset. If applying multiple styles and colors in the same place, instead of writing the formatting keys all into
separate brackets (e.g. `[x][y][z]`), they can also be put in a single pair of brackets, separated by pipes (e.g. `[x|y|z]`).

A list of all possible formatting keys can be found under all possible formatting keys.

------------------------------------------------------------------------------------------------------------------------------------
#### Auto Resetting Formatting Codes

Certain formatting can automatically be reset, behind a certain amount of text, just like shown in the following example:
```
This is plain text, [br:blue](which is bright blue now.) Now it was automatically reset to plain again.
```

This will only reset formatting codes, that have a specific reset listed below.
That means if you use it where another formatting is already applied, that formatting is still there after the automatic reset:
```
[cyan]This is cyan text, [dim](which is dimmed now.) Now it's not dimmed any more but still cyan.
```

If you want to ignore the auto-reset functionality of `()` brackets, you can put a `\\` or `/` between them and
the formatting code:
```
[cyan]This is cyan text, [u]/(which is underlined now.) And now it is still underlined and cyan.
```

------------------------------------------------------------------------------------------------------------------------------------
#### All possible Formatting Keys

- RGB colors:
  Change the text color directly with an RGB color inside the square brackets. (With or without `rgb()` brackets doesn't matter.)
  Examples:
  - `[rgb(115, 117, 255)]`
  - `[(255, 0, 136)]`
  - `[255, 0, 136]`
- HEX colors:
  Change the text color directly with a HEX color inside the square brackets. (Whether the `RGB` or `RRGGBB` HEX format is used,
  and if there's a `#` or `0x` prefix, doesn't matter.)
  Examples:
  - `[0x7788FF]`
  - `[#7788FF]`
  - `[7788FF]`
  - `[0x78F]`
  - `[#78F]`
  - `[78F]`
- background RGB / HEX colors:
  Change the background color directly with an RGB or HEX color inside the square brackets, using the `background:` `BG:` prefix.
  (Same RGB / HEX formatting code rules as for text color.)
  Examples:
  - `[background:rgb(115, 117, 255)]`
  - `[BG:(255, 0, 136)]`
  - `[background:#7788FF]`
  - `[BG:#78F]`
- standard console colors:
  Change the text color to one of the standard console colors by just writing the color name in the square brackets.
  - `[black]`
  - `[red]`
  - `[green]`
  - `[yellow]`
  - `[blue]`
  - `[magenta]`
  - `[cyan]`
  - `[white]`
- bright console colors:
  Use the prefix `bright:` `BR:` to use the bright variant of the standard console color.
  Examples:
  - `[bright:black]` `[BR:black]`
  - `[bright:red]` `[BR:red]`
  - …
- Background console colors:
  Use the prefix `background:` `BG:` to set the background to a standard console color. (Not all consoles support bright
  standard colors.)
  Examples:
  - `[background:black]` `[BG:black]`
  - `[background:red]` `[BG:red]`
  - …
- Bright background console colors:
  Combine the prefixes `background:` / `BG:` and `bright:` / `BR:` to set the background to a bright console color.
  (The order of the prefixes doesn't matter.)
  Examples:
  - `[background:bright:black]` `[BG:BR:black]`
  - `[background:bright:red]` `[BG:BR:red]`
  - …
- Text styles:
  Use the built-in text formatting to change the style of the text. There are long and short forms for each formatting code.
  (Not all consoles support all text styles.)
  - `[bold]` `[b]`
  - `[dim]`
  - `[italic]` `[i]`
  - `[underline]` `[u]`
  - `[inverse]` `[invert]` `[in]`
  - `[hidden]` `[hide]` `[h]`
  - `[strikethrough]` `[s]`
  - `[double-underline]` `[du]`
- Specific reset:
  Use these reset codes to remove a specific style, color or background. Again, there are long and
  short forms for each reset code.
  - `[_bold]` `[_b]`
  - `[_dim]`
  - `[_italic]` `[_i]`
  - `[_underline]` `[_u]`
  - `[_inverse]` `[_invert]` `[_in]`
  - `[_hidden]` `[_hide]` `[_h]`
  - `[_strikethrough]` `[_s]`
  - `[_double-underline]` `[_du]`
  - `[_color]` `[_c]`
  - `[_background]` `[_bg]`
- Total reset:
  This will reset all previously applied formatting codes.
  - `[_]`

------------------------------------------------------------------------------------------------------------------------------------
#### Additional Formatting Codes when a `default_color` is set

1. `[*]` resets everything, just like `[_]`, but the text color will remain in `default_color`
  (if no `default_color` is set, it resets everything, exactly like `[_]`)
2. `[default]` will just color the text in `default_color`
  (if no `default_color` is set, it's treated as an invalid formatting code)
3. `[background:default]` `[BG:default]` will color the background in `default_color`
  (if no `default_color` is set, both are treated as invalid formatting codes)\n

Unlike the standard console colors, the default color can be changed by using the following modifiers:

- `[l]` will lighten the `default_color` text by `brightness_steps`%
- `[ll]` will lighten the `default_color` text by `2 × brightness_steps`%
- `[lll]` will lighten the `default_color` text by `3 × brightness_steps`%
- … etc. Same thing for darkening:
- `[d]` will darken the `default_color` text by `brightness_steps`%
- `[dd]` will darken the `default_color` text by `2 × brightness_steps`%
- `[ddd]` will darken the `default_color` text by `3 × brightness_steps`%
- … etc.
Per default, you can also use `+` and `-` to get lighter and darker `default_color` versions.
All of these lighten/darken formatting codes are treated as invalid if no `default_color` is set.
"""

from .base.types import FormattableString, Rgba, Hexa
from .base.consts import ANSI

from .string import String
from .regex import LazyRegex, Regex
from .color import Color, rgba, hexa

from typing import Optional, Literal, Final, cast
import ctypes as _ctypes
import regex as _rx
import sys as _sys
import os as _os


_CONSOLE_ANSI_CONFIGURED: bool = False
"""Whether the console was already configured to be able to interpret and render ANSI formatting."""

_ANSI_SEQ_1: Final[FormattableString] = ANSI.seq(1)
"""ANSI escape sequence with a single placeholder."""
_DEFAULT_COLOR_MODS: Final[dict[str, str]] = {
    "lighten": "+l",
    "darken": "-d",
}
"""Formatting codes for lightening and darkening the `default_color`."""
_PREFIX: Final[dict[str, set[str]]] = {
    "BG": {"background", "bg"},
    "BR": {"bright", "br"},
}
"""Formatting code prefixes for setting background- and bright-colors."""
_PREFIX_RX: Final[dict[str, str]] = {
    "BG": rf"(?:{'|'.join(_PREFIX['BG'])})\s*:",
    "BR": rf"(?:{'|'.join(_PREFIX['BR'])})\s*:",
}
"""Regex patterns for matching background- and bright-color prefixes."""

_PATTERNS = LazyRegex(
    star_reset=r"\[\s*([^]_]*?)\s*\*\s*([^]_]*?)\]",
    star_reset_inside=r"([^|]*?)\s*\*\s*([^|]*)",
    ansi_seq=ANSI.CHAR + r"(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])",
    formatting=(
        Regex.brackets("[", "]", is_group=True, ignore_in_strings=False) + r"(?:([/\\]?)"
        + Regex.brackets("(", ")", is_group=True, strip_spaces=False, ignore_in_strings=False) + r")?"
    ),
    escape_char=r"(\s*)(\/|\\)",
    escape_char_cond=r"(\s*\[\s*)(\/|\\)(?!\2+)",
    bg_opt_default=r"(?i)((?:" + _PREFIX_RX["BG"] + r")?)\s*default",
    bg_default=r"(?i)" + _PREFIX_RX["BG"] + r"\s*default",
    modifier=(
        r"(?i)^((?:BG\s*:)?)\s*("
        + "|".join([f"{_rx.escape(m)}+" for m in _DEFAULT_COLOR_MODS["lighten"] + _DEFAULT_COLOR_MODS["darken"]]) + r")$"
    ),
    rgb=r"(?i)^\s*(" + _PREFIX_RX["BG"] + r")?\s*(?:rgb|rgba)?\s*\(?\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)?\s*$",
    hex=r"(?i)^\s*(" + _PREFIX_RX["BG"] + r")?\s*(?:#|0x)?([0-9A-F]{6}|[0-9A-F]{3})\s*$",
)


class FormatCodes:
    """This class provides methods to print and work with strings that contain special formatting codes,
    which are then converted to ANSI codes for pretty console output."""

    @classmethod
    def print(
        cls,
        *values: object,
        default_color: Optional[Rgba | Hexa] = None,
        brightness_steps: int = 20,
        sep: str = " ",
        end: str = "\n",
        flush: bool = True,
    ) -> None:
        """A print function, whose print `values` can be formatted using formatting codes.\n
        --------------------------------------------------------------------------------------------------
        - `values` -⠀the values to print
        - `default_color` -⠀the default text color to use if no other text color was applied
        - `brightness_steps` -⠀the amount to increase/decrease default-color brightness per modifier code
        - `sep` -⠀the separator to use between multiple values
        - `end` -⠀the string to append at the end of the printed values
        - `flush` -⠀whether to flush the output buffer after printing\n
        --------------------------------------------------------------------------------------------------
        For exact information about how to use special formatting codes,
        see the `format_codes` module documentation."""
        cls._config_console()
        _sys.stdout.write(cls.to_ansi(sep.join(map(str, values)) + end, default_color, brightness_steps))

        if flush:
            _sys.stdout.flush()

    @classmethod
    def input(
        cls,
        prompt: object = "",
        default_color: Optional[Rgba | Hexa] = None,
        brightness_steps: int = 20,
        reset_ansi: bool = False,
    ) -> str:
        """An input, whose `prompt` can be formatted using formatting codes.\n
        --------------------------------------------------------------------------------------------------
        - `prompt` -⠀the prompt to show to the user
        - `default_color` -⠀the default text color to use if no other text color was applied
        - `brightness_steps` -⠀the amount to increase/decrease default-color brightness per modifier code
        - `reset_ansi` -⠀if true, all ANSI formatting will be reset, after the user confirmed the input
          and the program continues to run\n
        --------------------------------------------------------------------------------------------------
        For exact information about how to use special formatting codes, see the
        `format_codes` module documentation."""
        cls._config_console()
        user_input = input(cls.to_ansi(str(prompt), default_color, brightness_steps))

        if reset_ansi:
            _sys.stdout.write(f"{ANSI.CHAR}[0m")
        return user_input

    @classmethod
    def to_ansi(
        cls,
        string: str,
        default_color: Optional[Rgba | Hexa] = None,
        brightness_steps: int = 20,
        _default_start: bool = True,
        _validate_default: bool = True,
    ) -> str:
        """Convert the formatting codes inside a string to ANSI formatting.\n
        --------------------------------------------------------------------------------------------------
        - `string` -⠀the string that contains the formatting codes to convert
        - `default_color` -⠀the default text color to use if no other text color was applied
        - `brightness_steps` -⠀the amount to increase/decrease default-color brightness per modifier code
        - `_default_start` -⠀whether to start the string with the `default_color` ANSI code, if set
        - `_validate_default` -⠀whether to validate the `default_color` before use
          (expects valid RGBA color or None, if not validated)\n
        --------------------------------------------------------------------------------------------------
        For exact information about how to use special formatting codes,
        see the `format_codes` module documentation."""
        if not (0 < brightness_steps <= 100):
            raise ValueError("The 'brightness_steps' parameter must be between 1 and 100.")

        if _validate_default:
            use_default, default_color = cls._validate_default_color(default_color)
        else:
            use_default = default_color is not None
            default_color = cast(Optional[rgba], default_color)

        if use_default:
            string = _PATTERNS.star_reset.sub(r"[\1_|default\2]", string)  # REPLACE `[…|*|…]` WITH `[…|_|default|…]`
        else:
            string = _PATTERNS.star_reset.sub(r"[\1_\2]", string)  # REPLACE `[…|*|…]` WITH `[…|_|…]`

        string = "\n".join(
            _PATTERNS.formatting.sub(_ReplaceKeysHelper(cls, use_default, default_color, brightness_steps), line)
            for line in string.split("\n")
        )

        return (
            ((cls._get_default_ansi(default_color) or "") if _default_start else "") \
            + string
        ) if default_color is not None else string

    @classmethod
    def escape(
        cls,
        string: str,
        default_color: Optional[Rgba | Hexa] = None,
        _escape_char: Literal["/", "\\"] = "/",
    ) -> str:
        """Escapes all valid formatting codes in the string, so they are visible when output
        to the console using `FormatCodes.print()`. Invalid formatting codes remain unchanged.\n
        -----------------------------------------------------------------------------------------
        - `string` -⠀the string that contains the formatting codes to escape
        - `default_color` -⠀the default text color to use if no other text color was applied
        - `_escape_char` -⠀the character to use to escape formatting codes (`/` or `\\`)\n
        -----------------------------------------------------------------------------------------
        For exact information about how to use special formatting codes,
        see the `format_codes` module documentation."""
        use_default, default_color = cls._validate_default_color(default_color)

        return "\n".join(
            _PATTERNS.formatting.sub(_EscapeFormatCodeHelper(cls, use_default, default_color, _escape_char), line)
            for line in string.split("\n")
        )

    @classmethod
    def escape_ansi(cls, ansi_string: str) -> str:
        """Escapes all ANSI codes in the string, so they are visible when output to the console.\n
        -------------------------------------------------------------------------------------------
        - `ansi_string` -⠀the string that contains the ANSI codes to escape"""
        return ansi_string.replace(ANSI.CHAR, ANSI.CHAR_ESCAPED)

    @classmethod
    def remove(
        cls,
        string: str,
        default_color: Optional[Rgba | Hexa] = None,
        get_removals: bool = False,
        _ignore_linebreaks: bool = False,
    ) -> str | tuple[str, tuple[tuple[int, str], ...]]:
        """Removes all formatting codes from the string with optional tracking of removed codes.\n
        --------------------------------------------------------------------------------------------------------
        - `string` -⠀the string that contains the formatting codes to remove
        - `default_color` -⠀the default text color to use if no other text color was applied
        - `get_removals` -⠀if true, additionally to the cleaned string, a list of tuples will be returned,
          where each tuple contains the position of the removed formatting code and the removed formatting code
        - `_ignore_linebreaks` -⠀whether to ignore line breaks for the removal positions"""
        return cls.remove_ansi(
            cls.to_ansi(string, default_color=default_color),
            get_removals=get_removals,
            _ignore_linebreaks=_ignore_linebreaks,
        )

    @classmethod
    def remove_ansi(
        cls,
        ansi_string: str,
        get_removals: bool = False,
        _ignore_linebreaks: bool = False,
    ) -> str | tuple[str, tuple[tuple[int, str], ...]]:
        """Removes all ANSI codes from the string with optional tracking of removed codes.\n
        ---------------------------------------------------------------------------------------------------
        - `ansi_string` -⠀the string that contains the ANSI codes to remove
        - `get_removals` -⠀if true, additionally to the cleaned string, a list of tuples will be returned,
          where each tuple contains the position of the removed ansi code and the removed ansi code
        - `_ignore_linebreaks` -⠀whether to ignore line breaks for the removal positions"""
        if get_removals:
            removals: list[tuple[int, str]] = []

            clean_string = _PATTERNS.ansi_seq.sub(
                _RemAnsiSeqHelper(removals),
                ansi_string.replace("\n", "") if _ignore_linebreaks else ansi_string  # REMOVE LINEBREAKS FOR POSITIONS
            )
            if _ignore_linebreaks:
                clean_string = _PATTERNS.ansi_seq.sub("", ansi_string)  # BUT KEEP LINEBREAKS IN RETURNED CLEAN STRING

            return clean_string, tuple(removals)

        else:
            return _PATTERNS.ansi_seq.sub("", ansi_string)

    @classmethod
    def _config_console(cls) -> None:
        """Internal method which configure the console to be able to interpret and render ANSI formatting.\n
        -----------------------------------------------------------------------------------------------------
        This method will only do something the first time it's called. Subsequent calls will do nothing."""
        global _CONSOLE_ANSI_CONFIGURED
        if not _CONSOLE_ANSI_CONFIGURED:
            _sys.stdout.flush()
            if _os.name == "nt":
                try:
                    # ENABLE VT100 MODE ON WINDOWS TO BE ABLE TO USE ANSI CODES
                    kernel32 = getattr(_ctypes, "windll").kernel32
                    h = kernel32.GetStdHandle(-11)
                    mode = _ctypes.c_ulong()
                    kernel32.GetConsoleMode(h, _ctypes.byref(mode))
                    kernel32.SetConsoleMode(h, mode.value | 0x0004)
                except Exception:
                    pass
            _CONSOLE_ANSI_CONFIGURED = True

    @staticmethod
    def _validate_default_color(default_color: Optional[Rgba | Hexa]) -> tuple[bool, Optional[rgba]]:
        """Internal method to validate and convert `default_color` to a `rgba` color object."""
        if default_color is None:
            return False, None
        if Color.is_valid_hexa(default_color, False):
            return True, hexa(cast(str | int, default_color)).to_rgba()
        elif Color.is_valid_rgba(default_color, False):
            return True, Color._parse_rgba(default_color)
        raise TypeError("The 'default_color' parameter must be either a valid RGBA or HEXA color, or None.")

    @staticmethod
    def _formats_to_keys(formats: str) -> list[str]:
        """Internal method to convert a string of multiple format keys
        to a list of individual, stripped format keys."""
        return [k.strip() for k in formats.split("|") if k.strip()]

    @classmethod
    def _get_replacement(cls, format_key: str, default_color: Optional[rgba], brightness_steps: int = 20) -> str:
        """Internal method that gives you the corresponding ANSI code for the given format key.
        If `default_color` is not `None`, the text color will be `default_color` if all formats
        are reset or you can get lighter or darker version of `default_color` (also as BG)"""
        _format_key, format_key = format_key, cls._normalize_key(format_key)  # NORMALIZE KEY AND SAVE ORIGINAL
        if default_color and (new_default_color := cls._get_default_ansi(default_color, format_key, brightness_steps)):
            return new_default_color
        for map_key in ANSI.CODES_MAP:
            if (isinstance(map_key, tuple) and format_key in map_key) or format_key == map_key:
                return _ANSI_SEQ_1.format(
                    next((
                        v for k, v in ANSI.CODES_MAP.items() if format_key == k or (isinstance(k, tuple) and format_key in k)
                    ), None)
                )
        rgb_match = _PATTERNS.rgb.match(format_key)
        hex_match = _PATTERNS.hex.match(format_key)
        try:
            if rgb_match:
                is_bg = rgb_match.group(1)
                r, g, b = map(int, rgb_match.groups()[1:])
                if Color.is_valid_rgba((r, g, b)):
                    return ANSI.SEQ_BG_COLOR.format(r, g, b) if is_bg else ANSI.SEQ_COLOR.format(r, g, b)
            elif hex_match:
                is_bg = hex_match.group(1)
                rgb = Color.to_rgba(hex_match.group(2))
                return (
                    ANSI.SEQ_BG_COLOR.format(rgb[0], rgb[1], rgb[2])
                    if is_bg else ANSI.SEQ_COLOR.format(rgb[0], rgb[1], rgb[2])
                )
        except Exception:
            pass
        return _format_key

    @staticmethod
    def _get_default_ansi(
        default_color: rgba,
        format_key: Optional[str] = None,
        brightness_steps: Optional[int] = None,
        _modifiers: tuple[str, str] = (_DEFAULT_COLOR_MODS["lighten"], _DEFAULT_COLOR_MODS["darken"]),
    ) -> Optional[str]:
        """Internal method to get the `default_color` and lighter/darker versions of it as ANSI code."""
        if not isinstance(default_color, rgba):
            return None
        _default_color: tuple[int, int, int] = tuple(default_color)[:3]
        if brightness_steps is None or (format_key and _PATTERNS.bg_opt_default.search(format_key)):
            return (ANSI.SEQ_BG_COLOR if format_key and _PATTERNS.bg_default.search(format_key) else ANSI.SEQ_COLOR).format(
                *_default_color
            )
        if format_key is None or not (match := _PATTERNS.modifier.match(format_key)):
            return None
        is_bg, modifiers = match.groups()
        adjust = 0
        for mod in _modifiers[0] + _modifiers[1]:
            adjust = String.single_char_repeats(modifiers, mod)
            if adjust and adjust > 0:
                modifiers = mod
                break
        new_rgb = _default_color
        if adjust == 0:
            return None
        elif modifiers in _modifiers[0]:
            new_rgb = tuple(Color.adjust_lightness(default_color, (brightness_steps / 100) * adjust))
        elif modifiers in _modifiers[1]:
            new_rgb = tuple(Color.adjust_lightness(default_color, -(brightness_steps / 100) * adjust))
        return (ANSI.SEQ_BG_COLOR if is_bg else ANSI.SEQ_COLOR).format(*new_rgb[:3])

    @staticmethod
    def _normalize_key(format_key: str) -> str:
        """Internal method to normalize the given format key."""
        k_parts = format_key.replace(" ", "").lower().split(":")
        prefix_str = "".join(
            f"{prefix_key.lower()}:" for prefix_key, prefix_values in _PREFIX.items()
            if any(k_part in prefix_values for k_part in k_parts)
        )
        return prefix_str + ":".join(
            part for part in k_parts \
            if part not in {val for values in _PREFIX.values() for val in values}
        )


class _EscapeFormatCodeHelper:
    """Internal, callable helper class to escape formatting codes."""

    def __init__(
        self,
        cls: type[FormatCodes],
        use_default: bool,
        default_color: Optional[rgba],
        escape_char: Literal["/", "\\"],
    ):
        self.cls = cls
        self.use_default = use_default
        self.default_color = default_color
        self.escape_char: Literal["/", "\\"] = escape_char

    def __call__(self, match: _rx.Match[str]) -> str:
        formats, auto_reset_txt = match.group(1), match.group(3)

        # CHECK IF ALREADY ESCAPED OR CONTAINS NO FORMATTING
        if not formats or _PATTERNS.escape_char_cond.match(match.group(0)):
            return match.group(0)

        # TEMPORARILY REPLACE `*` FOR VALIDATION
        _formats = formats
        if self.use_default:
            _formats = _PATTERNS.star_reset_inside.sub(r"\1_|default\2", formats)
        else:
            _formats = _PATTERNS.star_reset_inside.sub(r"\1_\2", formats)

        if all((self.cls._get_replacement(k, self.default_color) != k) for k in self.cls._formats_to_keys(_formats)):
            # ESCAPE THE FORMATTING CODE
            escaped = f"[{self.escape_char}{formats}]"
            if auto_reset_txt:
                # RECURSIVELY ESCAPE FORMATTING IN AUTO-RESET TEXT
                escaped_auto_reset = self.cls.escape(auto_reset_txt, self.default_color, self.escape_char)
                escaped += f"({escaped_auto_reset})"
            return escaped
        else:
            # KEEP INVALID FORMATTING CODES AS-IS
            result = f"[{formats}]"
            if auto_reset_txt:
                # STILL RECURSIVELY PROCESS AUTO-RESET TEXT
                escaped_auto_reset = self.cls.escape(auto_reset_txt, self.default_color, self.escape_char)
                result += f"({escaped_auto_reset})"
            return result


class _RemAnsiSeqHelper:
    """Internal, callable helper class to remove ANSI sequences and track their removal positions."""

    def __init__(self, removals: list[tuple[int, str]]):
        self.removals = removals

    def __call__(self, match: _rx.Match[str]) -> str:
        start_pos = match.start() - sum(len(removed) for _, removed in self.removals)
        if self.removals and self.removals[-1][0] == start_pos:
            start_pos = self.removals[-1][0]
        self.removals.append((start_pos, match.group()))
        return ""


class _ReplaceKeysHelper:
    """Internal, callable helper class to replace formatting keys with their respective ANSI codes."""

    def __init__(
        self,
        cls: type[FormatCodes],
        use_default: bool,
        default_color: Optional[rgba],
        brightness_steps: int,
    ):
        self.cls = cls
        self.use_default = use_default
        self.default_color = default_color
        self.brightness_steps = brightness_steps

        # INSTANCE VARIABLES FOR CURRENT PROCESSING STATE
        self.formats: str = ""
        self.original_formats: str = ""
        self.formats_escaped: bool = False
        self.auto_reset_escaped: bool = False
        self.auto_reset_txt: Optional[str] = None
        self.format_keys: list[str] = []
        self.ansi_formats: list[str] = []
        self.ansi_resets: list[str] = []

    def __call__(self, match: _rx.Match[str]) -> str:
        self.original_formats = self.formats = match.group(1)
        self.auto_reset_escaped = bool(match.group(2))
        self.auto_reset_txt = match.group(3)

        # CHECK IF THERE'S ESCAPED FORMAT CODES
        self.formats_escaped = bool(_PATTERNS.escape_char_cond.match(match.group(0)))
        if self.formats_escaped:
            self.original_formats = self.formats = _PATTERNS.escape_char.sub(r"\1", self.formats)

        self.process_formats_and_auto_reset()

        if not self.formats:
            return match.group(0)

        self.convert_to_ansi()
        return self.build_output(match)

    def process_formats_and_auto_reset(self) -> None:
        """Process nested formatting in both formats and auto-reset text."""
        # PROCESS AUTO-RESET TEXT IF IT CONTAINS NESTED FORMATTING
        if self.auto_reset_txt and self.auto_reset_txt.count("[") > 0 and self.auto_reset_txt.count("]") > 0:
            self.auto_reset_txt = self.cls.to_ansi(
                self.auto_reset_txt,
                self.default_color,
                self.brightness_steps,
                _default_start=False,
                _validate_default=False,
            )

        # PROCESS NESTED FORMATTING IN FORMATS
        if self.formats and self.formats.count("[") > 0 and self.formats.count("]") > 0:
            self.formats = self.cls.to_ansi(
                self.formats,
                self.default_color,
                self.brightness_steps,
                _default_start=False,
                _validate_default=False,
            )

    def convert_to_ansi(self) -> None:
        """Convert format keys to ANSI codes and generate resets if needed."""
        self.format_keys = self.cls._formats_to_keys(self.formats)
        self.ansi_formats = [
            r if (r := self.cls._get_replacement(k, self.default_color, self.brightness_steps)) != k else f"[{k}]"
            for k in self.format_keys
        ]

        # GENERATE RESET CODES IF AUTO-RESET IS ACTIVE
        if self.auto_reset_txt and not self.auto_reset_escaped:
            self.gen_reset_codes()
        else:
            self.ansi_resets = []

    def gen_reset_codes(self) -> None:
        """Generate appropriate ANSI reset codes for each format key."""
        default_color_resets = ("_bg", "default") if self.use_default else ("_bg", "_c")
        reset_keys: list[str] = []

        for k in self.format_keys:
            k_lower = k.lower()
            k_set = set(k_lower.split(":"))

            # BACKGROUND COLOR FORMAT
            if _PREFIX["BG"] & k_set and len(k_set) <= 3:
                if k_set & _PREFIX["BR"]:
                    # BRIGHT BACKGROUND COLOR - RESET BOTH BG AND COLOR
                    for i in range(len(k)):
                        if self.is_valid_color(k[i:]):
                            reset_keys.extend(default_color_resets)
                            break
                else:
                    # REGULAR BACKGROUND COLOR - RESET ONLY BG
                    for i in range(len(k)):
                        if self.is_valid_color(k[i:]):
                            reset_keys.append("_bg")
                            break

            # TEXT COLOR FORMAT
            elif self.is_valid_color(k) or any(
                k_lower.startswith(pref_colon := f"{prefix}:") and self.is_valid_color(k[len(pref_colon):]) \
                for prefix in _PREFIX["BR"]
            ):
                reset_keys.append(default_color_resets[1])

            # TEXT STYLE FORMAT
            else:
                reset_keys.append(f"_{k}")

        # CONVERT RESET KEYS TO ANSI CODES
        self.ansi_resets = [
            r for k in reset_keys if ( \
                r := self.cls._get_replacement(k, self.default_color, self.brightness_steps)
            ).startswith(f"{ANSI.CHAR}{ANSI.START}")
        ]

    def build_output(self, match: _rx.Match[str]) -> str:
        """Build the final output string based on processed formats and resets."""
        # CHECK IF ALL FORMATS WERE VALID
        has_single_valid_ansi = len(self.ansi_formats) == 1 and self.ansi_formats[0].count(f"{ANSI.CHAR}{ANSI.START}") >= 1
        all_formats_valid = all(f.startswith(f"{ANSI.CHAR}{ANSI.START}") for f in self.ansi_formats)

        if not has_single_valid_ansi and not all_formats_valid:
            return match.group(0)

        # HANDLE ESCAPED FORMATTING
        if self.formats_escaped:
            return f"[{self.original_formats}]({self.auto_reset_txt})" if self.auto_reset_txt else f"[{self.original_formats}]"

        # BUILD NORMAL OUTPUT WITH FORMATS AND RESETS
        output = "".join(self.ansi_formats)

        # ADD AUTO-RESET TEXT
        if self.auto_reset_escaped and self.auto_reset_txt:
            output += f"({self.cls.to_ansi(self.auto_reset_txt, self.default_color, self.brightness_steps, _default_start=False, _validate_default=False)})"
        elif self.auto_reset_txt:
            output += self.auto_reset_txt

        # ADD RESET CODES IF NOT ESCAPED
        if not self.auto_reset_escaped:
            output += "".join(self.ansi_resets)

        return output

    def is_valid_color(self, color: str) -> bool:
        """Check whether the given color string is a valid formatting-key color."""
        return bool((color in ANSI.COLOR_MAP) or Color.is_valid_rgba(color) or Color.is_valid_hexa(color))
