feat: add support for printing explicit hyperlinks

Author: eugenesvk

README.md

@@ -38,7 +38,23 @@ from xontrib_term_integrations.utils import set_user_var
 set_user_var('my_term_user_var','value_of_my_term_user_var')
 ```
 
-You can disable registering the alias with a `$XONTRIB_TERM_INTEGRATIONS_SKIP_ALIAS = True`
+Print Explicit Hyperlinks[^2] via the helper `print_link` function:
+```xsh
+# via a xonsh alias
+print_link 'https://example.com' 'Example Domain'
+
+# or an explicit Python import
+from xontrib_term_integrations.utils import print_link
+print_link('https://example.com', 'Example Domain')
+```
+
+You can disable registering the aliases with a `$XONTRIB_TERM_INTEGRATIONS_SKIP_ALIAS = True`
+
+(WezTerm) You can disable other features with the following environment variables:
+  - `$WEZTERM_SHELL_SKIP_ALL = False` to disable all integrations
+  - `$WEZTERM_SHELL_SKIP_SEMANTIC_ZONES = False` to disable zones
+  - `$WEZTERM_SHELL_SKIP_CWD = False` to disable OSC 7 cwd setting
+  - `$WEZTERM_SHELL_SKIP_USER_VARS = False` to disable user vars that capture information about running programs
 
 ## Contributing
 
@@ -70,3 +86,4 @@ pre-commit install-hooks
 - WezTerm is _not_ recognized in root shells due to [this issue](https://github.com/wez/wezterm/issues/3114)
 
 [^1]: Variables associated with a given pane rather than a process. [WezTerm](https://wezfurlong.org/wezterm/shell-integration.html#user-vars), [iTerm2](https://iterm2.com/documentation-escape-codes.html)
+[^2]: Display a cleaner text instead of a URL that can be clicked to resolve to that URL. [WezTerm](https://wezfurlong.org/wezterm/hyperlinks.html#explicit-hyperlinks), [iTerm2](https://iterm2.com/documentation-escape-codes.html)

xontrib_term_integrations/iterm2.py

@@ -3,6 +3,10 @@
 from . import utils
 from .semantic_prompt import ShellIntegrationPrompt
 
+env = XSH.env or {}
+
+_skip_alias = env.get("XONTRIB_TERM_INTEGRATIONS_SKIP_ALIAS", False)
+
 
 @XSH.builtins.events.on_precommand
 def iterm_precmd(**_):
@@ -29,3 +33,5 @@ def onpostinit(**__):
 
 
 XSH.env["PROMPT"] = ShellIntegrationPrompt(XSH.env)
+if not _skip_alias:
+    XSH.aliases["print_link"] = utils.write_osc_hyperlink_alias

xontrib_term_integrations/kitty.py

@@ -4,6 +4,10 @@
 from . import kitty_completions, utils
 from .semantic_prompt import ShellIntegrationPrompt
 
+env = XSH.env or {}
+
+_skip_alias = env.get("XONTRIB_TERM_INTEGRATIONS_SKIP_ALIAS", False)
+
 
 @XSH.builtins.events.on_precommand
 def iterm_precmd(**_):
@@ -38,4 +42,7 @@ def ps2_multiline_prompt():
 XSH.env["PROMPT"] = ShellIntegrationPrompt(XSH.env)
 XSH.env["MULTILINE_PROMPT"] = ps2_multiline_prompt
 
+if not _skip_alias:
+    XSH.aliases["print_link"] = utils.write_osc_hyperlink_alias
+
 add_one_completer("kitty", kitty_completions.xonsh_complete, loc="<import")

xontrib_term_integrations/utils.py

@@ -47,6 +47,10 @@ def term_osc7_cmd(code):
     return f"{Codes.OSC}7;{code}{Codes.ST}"
 
 
+def term_osc8_cmd(code):
+    return f"{Codes.OSC}8;{code}{Codes.ST}"
+
+
 def term_dcs_cmd(code):
     return f"{Codes.DCS}{code}{Codes.ST}"
 
@@ -86,6 +90,10 @@ def write_osc7_cmd(code):
     return write_to_out(term_osc7_cmd(code))
 
 
+def write_osc8_cmd(code):
+    return write_to_out(term_osc8_cmd(code))
+
+
 def write_dcs_cmd(code):
     return write_to_out(term_dcs_cmd(code))
 
@@ -131,6 +139,40 @@ def write_osc_user_host(env):
         write_osc_cmd(f"RemoteHost={user}@{host}")
 
 
+def write_osc_hyperlink(uri, text, params=""):
+    # wezfurlong.org/wezterm/hyperlinks.html#explicit-hyperlinks
+    # open : OSC 8 ; params ; [URI] ST
+    # text : no escape sequences
+    # close: OSC 8 ;        ;       ST
+    write_to_out(term_osc8_cmd(f"{params};{uri}") + f"{text}" + term_osc8_cmd(";"))
+
+
+def write_osc_hyperlink_fn(
+    uri: str, text: str, params: Annotated[Optional[str], Arg(nargs="?")] = ""  # noqa
+):
+    """Prints an Explicit Hyperlink `Text` resolving to the given `URL`
+    (see ``wezfurlong.org/wezterm/hyperlinks.html#explicit-hyperlinks`` for details)
+
+    Parameters
+    ----------
+    uri
+        Target of the hyperlink, including the scheme, e.g.
+        `https://` for web addresses
+        `file://` for local files (followed by a mandatory `hostname`)
+        `mailto:` for email, etc.
+    text
+        Hyperlink text that resolves to the URI on click
+    params
+        Additional colon:separated parameters, e.g., `id:1`
+    """
+
+    write_osc_hyperlink(uri, text, params)
+
+
+def print_link(uri, text, params=""):
+    write_osc_hyperlink(uri, text, params)
+
+
 def set_user_var(
     var, val
 ):  # emit an OSC 1337 sequence to set a user var associated with the current
@@ -167,6 +209,9 @@ def set_user_var_fn(
     set_user_var(var, val)
 
 
+write_osc_hyperlink_alias = ArgParserAlias(
+    func=write_osc_hyperlink_fn, has_args=True, prog="print_link"
+)
 set_user_var_alias = ArgParserAlias(
     func=set_user_var_fn, has_args=True, prog="set_user_var"
 )

xontrib_term_integrations/wezterm.py

@@ -127,6 +127,7 @@ def wezterm_prompt_pre():
 
     if not _skip_alias:
         XSH.aliases["set_user_var"] = utils.set_user_var_alias
+        XSH.aliases["print_link"] = utils.write_osc_hyperlink_alias
 
     prompt_name = ["PROMPT", "RIGHT_PROMPT", "BOTTOM_TOOLBAR", "MULTILINE_PROMPT"]
     extend = False if _skip_zone else True