Add new link:… format key to FormatCodes

Author: xulbux

CHANGELOG.md

@@ -27,6 +27,7 @@
 * Fixed a small bug in `ProgressBar`, where it would only overwrite and not actually clear the previous line.
 * Added a new constant `ANSI.COLOR_VARIANTS_MAP`, which contains all possible color variants that can be used in formatting.
 * Made it possible to also pass console default colors to `title_bg_color` in `Console.log()`, instead of only custom RGBA or HEXA colors.
+* Added a new format key `link:…` to `FormatCodes`, which allows you to create hyperlinks in the console output with the syntax `[link:URL](display text)`.
 
 **BREAKING CHANGES:**
 * All `Console` methods that allow console default colors as input for their color params, now actually validate the given color, raising an error if it's not valid.

src/xulbux/base/consts.py

@@ -97,6 +97,11 @@ def seq(cls, placeholders: int = 1, /) -> FormattableString:
     SEQ_BG_COLOR: Final[FormattableString] = CHAR + START + "48" + SEP + "2" + SEP + "{}" + SEP + "{}" + SEP + "{}" + END
     """ANSI escape sequence with three placeholders for setting the RGB background color."""
 
+    SEQ_LINK_OPEN: Final[FormattableString] = CHAR + "]8;;{}" + CHAR + "\\"
+    """OSC 8 hyperlink opening sequence with a placeholder for the URL."""
+    SEQ_LINK_CLOSE: Final[str] = CHAR + "]8;;" + CHAR + "\\"
+    """OSC 8 hyperlink closing sequence."""
+
     COLOR_MAP: Final[set[str]] = {
         "black",
         "red",

src/xulbux/format_codes.py

@@ -129,6 +129,12 @@
 - Total reset:
   This will reset all previously applied formatting codes.
   - `[_]`
+- Hyperlinks:
+  Create a clickable hyperlink using the `link:` prefix followed by any URL.
+  Auto-reset braces are required to define the visible, clickable text.
+  Examples:
+  - `[link:file:///C:/path/to/file.txt](open file)`
+  - `[link:https://example.com|br:blue](click here)`
 
 ------------------------------------------------------------------------------------------------------------------------------------
 #### Additional Formatting Codes when a `default_color` is set
@@ -192,7 +198,8 @@
 _PATTERNS = LazyRegex(
     star_reset=r"\[\s*([^]_]*?)\s*\*\s*([^]_]*?)\]",
     star_reset_inside=r"([^|]*?)\s*\*\s*([^|]*)",
-    ansi_seq=ANSI.CHAR + r"(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])",
+    ansi_seq=ANSI.CHAR + r"(?:\].*?(?:\x1b\\|\x07)|\[[0-?]*[ -/]*[@-~]|[@-Z\\-_])",
+    link=r"(?i)^\s*link\s*:\s*(.+?)\s*$",
     formatting=(
         Regex.brackets("[", "]", is_group=True, ignore_in_strings=False) + r"(?:([/\\]?)"
         + Regex.brackets("(", ")", is_group=True, strip_spaces=False, ignore_in_strings=False) + r")?"
@@ -633,8 +640,15 @@ def __call__(self, match: _rx.Match[str], /) -> str:
         else:
             _formats = _PATTERNS.star_reset_inside.sub(r"\1_\2", formats)
 
-        if all(self.cls._get_replacement(format_key, self.default_color) != format_key
-               for format_key in self.cls._formats_to_keys(_formats)):
+        has_link = False
+        has_invalid_key = False
+        for format_key in self.cls._formats_to_keys(_formats):
+            if _PATTERNS.link.match(format_key):
+                has_link = True
+            elif self.cls._get_replacement(format_key, self.default_color) == format_key:
+                has_invalid_key = True
+
+        if has_link or not has_invalid_key:
             # ESCAPE THE FORMATTING CODE
             escaped = f"[{self.escape_char}{formats}]"
             if auto_reset_txt:
@@ -702,14 +716,48 @@ def __call__(self, match: _rx.Match[str], /) -> str:
         if self.formats_escaped:
             self.original_formats = self.formats = _PATTERNS.escape_char.sub(r"\1", self.formats)
 
+        # HANDLE HYPERLINK FORMAT
+        all_keys = self.cls._formats_to_keys(self.formats)
+        if (result := self.handle_link(match, all_keys)) is not None:
+            return result
+
         self.process_formats_and_auto_reset()
 
+        # IF THERE ARE NO FORMATS OR ALL FORMATS ARE INVALID, RETURN THE ORIGINAL STRING
         if not self.formats:
             return match.group(0)
 
         self.convert_to_ansi()
         return self.build_output(match)
 
+    def handle_link(self, match: _rx.Match[str], all_keys: list[str], /) -> Optional[str]:
+        """Handle a hyperlink format code, returning the OSC 8 sequence or None if not a link."""
+        link_key = next((k for k in all_keys if _PATTERNS.link.match(k)), None)
+
+        if link_key is None:
+            return None
+        if self.auto_reset_txt is None:
+            return match.group(0)  # LINK WITHOUT DISPLAY BRACES IS INVALID
+        if self.formats_escaped:
+            return f"[{self.original_formats}]({self.auto_reset_txt})"
+
+        link_url = _PATTERNS.link.match(link_key).group(1)  # type: ignore[union-attr]
+        display = self.auto_reset_txt
+
+        if other_keys := [k for k in all_keys if k != link_key]:
+            # APPLY REMAINING FORMAT CODES TO DISPLAY TEXT WITH AUTO-RESET
+            display = "[{}]({})".format("|".join(other_keys), display)
+        if other_keys or ("[" in display and "]" in display):
+            display = self.cls.to_ansi(
+                display,
+                self.default_color,
+                self.brightness_steps,
+                _default_start=False,
+                _validate_default=False,
+            )
+
+        return ANSI.SEQ_LINK_OPEN.format(link_url) + display + ANSI.SEQ_LINK_CLOSE
+
     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

tests/test_format_codes.py

@@ -80,6 +80,40 @@ def test_escape():
     assert FormatCodes.escape("[--]Hello", default_color="#FFF") == "[/--]Hello"
 
 
+def test_hyperlinks():
+    url = "https://example.com"
+    file_url = "file:///C:/path/to/file.txt"
+    link_open = ANSI.SEQ_LINK_OPEN.format(url)
+    link_open_file = ANSI.SEQ_LINK_OPEN.format(file_url)
+    link_close = ANSI.SEQ_LINK_CLOSE
+
+    # BASIC LINK
+    assert FormatCodes.to_ansi(f"[link:{url}](click here)") == f"{link_open}click here{link_close}"
+
+    # FILE URL
+    assert FormatCodes.to_ansi(f"[link:{file_url}](open file)") == f"{link_open_file}open file{link_close}"
+
+    # LINK WITH NESTED FORMATTING IN DISPLAY TEXT
+    assert FormatCodes.to_ansi(f"[link:{url}]([b](bold link))") == f"{link_open}{bold}bold link{reset_bold}{link_close}"
+
+    # LINK COMBINED WITH OTHER FORMAT KEYS
+    assert FormatCodes.to_ansi(f"[link:{url}|b](click here)") == f"{link_open}{bold}click here{reset_bold}{link_close}"
+    bright_blue = f"{ANSI.CHAR}{ANSI.START}{ANSI.CODES_MAP['br:blue']}{ANSI.END}"
+    assert FormatCodes.to_ansi(f"[link:{url}|br:blue](click here)"
+                               ) == (f"{link_open}{bright_blue}click here{reset_color}{link_close}")
+
+    # LINK WITHOUT DISPLAY BRACES IS INVALID (LEFT AS-IS)
+    assert FormatCodes.to_ansi(f"[link:{url}]") == f"[link:{url}]"
+
+    # ESCAPE: LINK SHOULD BE ESCAPED
+    assert FormatCodes.escape(f"[link:{url}](click here)") == f"[/link:{url}](click here)"
+    assert FormatCodes.escape(f"[link:{url}|b](click here)") == f"[/link:{url}|b](click here)"
+
+    # REMOVE: OSC SEQUENCES FROM LINK SHOULD BE STRIPPED, LEAVING ONLY DISPLAY TEXT
+    assert FormatCodes.remove(f"[link:{url}](click here)") == "click here"
+    assert FormatCodes.remove_ansi(f"{link_open}click here{link_close}") == "click here"
+
+
 def test_remove_ansi():
     ansi_string = f"{bold}Hello {orange}World!{reset}"
     clean_string = "Hello World!"