feat: Add support for hyperlinks in snippet origin

Author: scrabsha

src/renderer/render.rs

@@ -488,7 +488,23 @@ fn render_origin(
         _ => origin.path.to_string(),
     };
 
+    if let Some(url) = &origin.url {
+        let url = normalize_whitespace(url);
+        buffer.append(
+            buffer_msg_line_offset,
+            &format!("\x1B]8;;{url}\x1B\\"),
+            ElementStyle::LineAndColumn,
+        );
+    }
     buffer.append(buffer_msg_line_offset, &str, ElementStyle::LineAndColumn);
+    if origin.url.is_some() {
+        buffer.append(
+            buffer_msg_line_offset,
+            "\x1B]8;;\x1B\\",
+            ElementStyle::LineAndColumn,
+        );
+    }
+
     if !renderer.short_message {
         for _ in 0..max_line_num_len {
             buffer.prepend(buffer_msg_line_offset, " ", ElementStyle::NoStyle);
@@ -555,6 +571,11 @@ fn render_snippet_annotations(
                 }
             }
         }
+
+        if let Some(url) = &snippet.url {
+            origin.url = Some(Cow::Borrowed(url));
+        }
+
         let buffer_msg_line_offset = buffer.num_lines();
         render_origin(
             renderer,

src/snippet.rs

@@ -227,6 +227,7 @@ pub struct Snippet<'a, T> {
     pub(crate) line_start: usize,
     pub(crate) source: Cow<'a, str>,
     pub(crate) markers: Vec<T>,
+    pub(crate) url: Option<Cow<'a, str>>,
     pub(crate) fold: bool,
 }
 
@@ -246,6 +247,7 @@ impl<'a, T: Clone> Snippet<'a, T> {
             line_start: 1,
             source: source.into(),
             markers: vec![],
+            url: None,
             fold: true,
         }
     }
@@ -271,6 +273,20 @@ impl<'a, T: Clone> Snippet<'a, T> {
         self
     }
 
+    /// The URL to the [`source`][Self::source]. Can be a `file://` URL.
+    ///
+    /// <div class="warning">
+    ///
+    /// Text passed to this function is considered "untrusted input", as such
+    /// all text is passed through a normalization function. Pre-styled text is
+    /// not allowed to be passed to this function.
+    ///
+    /// </div>
+    pub fn url(mut self, url: impl Into<OptionCow<'a>>) -> Self {
+        self.url = url.into().0;
+        self
+    }
+
     /// Control whether lines without [`Annotation`]s are shown
     ///
     /// The default is `fold(true)`, collapsing uninteresting lines.
@@ -487,6 +503,7 @@ pub struct Origin<'a> {
     pub(crate) path: Cow<'a, str>,
     pub(crate) line: Option<usize>,
     pub(crate) char_column: Option<usize>,
+    pub(crate) url: Option<Cow<'a, str>>,
 }
 
 impl<'a> Origin<'a> {
@@ -502,6 +519,7 @@ impl<'a> Origin<'a> {
             path: path.into(),
             line: None,
             char_column: None,
+            url: None,
         }
     }
 
@@ -522,6 +540,20 @@ impl<'a> Origin<'a> {
         self.char_column = Some(char_column);
         self
     }
+
+    /// The URL to the [`source`][Self::source]. Can be a `file://` URL.
+    ///
+    /// <div class="warning">
+    ///
+    /// Text passed to this function is considered "untrusted input", as such
+    /// all text is passed through a normalization function. Pre-styled text is
+    /// not allowed to be passed to this function.
+    ///
+    /// </div>
+    pub fn url(mut self, uri: impl Into<Cow<'a, str>>) -> Self {
+        self.url = Some(uri.into());
+        self
+    }
 }
 
 impl<'a> From<Cow<'a, str>> for Origin<'a> {

tests/hyperlink.rs

@@ -0,0 +1,37 @@
+use annotate_snippets::{renderer::DecorStyle, AnnotationKind, Level, Renderer, Snippet};
+use snapbox::{assert_data_eq, file};
+
+#[test]
+fn simple() {
+    // Most basic test: check that the a hyperlink shows up in the error message displayed in the
+    // README.
+    let source = r#"                annotations: vec![SourceAnnotation {
+                label: "expected struct `annotate_snippets::snippet::Slice`, found reference"
+                    ,
+                range: <22, 25>,"#;
+    let report =
+        &[Level::ERROR
+            .primary_title("expected type, found `22`")
+            .element(
+                Snippet::source(source)
+                    .line_start(26)
+                    .path("examples/footer.rs")
+                    .url("file://localhost/home/user/rust/file.rs")
+                    .annotation(AnnotationKind::Primary.span(193..195).label(
+                        "expected struct `annotate_snippets::snippet::Slice`, found reference",
+                    ))
+                    .annotation(
+                        AnnotationKind::Context
+                            .span(34..50)
+                            .label("while parsing this struct"),
+                    ),
+            )];
+
+    let expected_ascii = file!["hyperlink_expected_type.ascii.term.svg": TermSvg];
+    let renderer = Renderer::styled().decor_style(DecorStyle::Ascii);
+    assert_data_eq!(renderer.render(report), expected_ascii);
+
+    let expected_unicode = file!["hyperlink_expected_type.unicode.term.svg": TermSvg];
+    let renderer = Renderer::styled().decor_style(DecorStyle::Unicode);
+    assert_data_eq!(renderer.render(report), expected_unicode);
+}