add syntax highlighting support with syntect crate

Author: erratic-pattern

.github/workflows/ci.yml

@@ -26,6 +26,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
+        features: [fancy, syntect]
         rust: [1.56.0, stable]
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
@@ -43,10 +44,10 @@ jobs:
         run: cargo clippy --all -- -D warnings
       - name: Run tests
         if: matrix.rust == 'stable'
-        run: cargo test --all --verbose --features fancy
+        run: cargo test --all --verbose --features ${{matrix.features}}
       - name: Run tests
         if: matrix.rust == '1.56.0'
-        run: cargo test --all --verbose --features fancy no-format-args-capture
+        run: cargo test --all --verbose --features ${{matrix.features}} no-format-args-capture
 
   miri:
     name: Miri

Cargo.toml

@@ -28,6 +28,7 @@ backtrace = { version = "0.3.61", optional = true }
 terminal_size = { version = "0.1.17", optional = true }
 backtrace-ext = { version = "0.2.1", optional = true }
 serde = { version = "1.0.162", features = ["derive"], optional = true }
+syntect = { version = "5.1.0", optional = true }
 
 [dev-dependencies]
 semver = "1.0.4"
@@ -56,6 +57,7 @@ fancy-no-backtrace = [
     "supports-unicode",
 ]
 fancy = ["fancy-no-backtrace", "backtrace", "backtrace-ext"]
+syntect = ["fancy", "dep:syntect"]
 
 [workspace]
 members = ["miette-derive"]

src/handlers/graphical.rs

@@ -1,10 +1,11 @@
 use std::fmt::{self, Write};
 
-use owo_colors::{OwoColorize, Style};
+use owo_colors::{OwoColorize, Style, Styled};
 use unicode_width::UnicodeWidthChar;
 
 use crate::diagnostic_chain::{DiagnosticChain, ErrorKind};
 use crate::handlers::theme::*;
+use crate::highlighters::get_highlighter;
 use crate::protocol::{Diagnostic, Severity};
 use crate::{LabeledSpan, MietteError, ReportHandler, SourceCode, SourceSpan, SpanContents};
 
@@ -403,6 +404,9 @@ impl GraphicalReportHandler {
             .map(|(label, st)| FancySpan::new(label.label().map(String::from), *label.inner(), st))
             .collect::<Vec<_>>();
 
+        let mut highlighter_state =
+            get_highlighter().and_then(|h| h.start_highlighter_state(source));
+
         // The max number of gutter-lines that will be active at any given
         // point. We need this to figure out indentation, so we do one loop
         // over the lines to see what the damage is gonna be.
@@ -476,7 +480,12 @@ impl GraphicalReportHandler {
             self.render_line_gutter(f, max_gutter, line, &labels)?;
 
             // And _now_ we can print out the line text itself!
-            self.render_line_text(f, &line.text)?;
+            if let Some(ref mut highlighter_state) = highlighter_state {
+                let styled_text = highlighter_state.highlight_line(&line.text);
+                self.render_highlighted_line_text(f, &styled_text)?;
+            } else {
+                self.render_line_text(f, &line.text)?;
+            }
 
             // Next, we write all the highlights that apply to this particular line.
             let (single_line, multi_line): (Vec<_>, Vec<_>) = labels
@@ -688,6 +697,30 @@ impl GraphicalReportHandler {
         Ok(())
     }
 
+    fn render_highlighted_line_text(
+        &self,
+        f: &mut impl fmt::Write,
+        styled_text: &[Styled<&str>],
+    ) -> fmt::Result {
+        for styled in styled_text {
+            let styled_text = styled.to_string();
+            for (c, width) in styled_text
+                .chars()
+                .zip(self.line_visual_char_width(&styled_text))
+            {
+                if c == '\t' {
+                    for _ in 0..width {
+                        f.write_char(' ')?;
+                    }
+                } else {
+                    f.write_char(c)?;
+                }
+            }
+        }
+        f.write_char('\n')?;
+        Ok(())
+    }
+
     fn render_single_line_highlights(
         &self,
         f: &mut impl fmt::Write,

src/highlighters/mod.rs

@@ -0,0 +1,91 @@
+//! This module exposes traits for creating syntax highlighters to highlight source code with
+//! ANSI terminal codes when rendering with the [crate::GraphicalReportHandler].
+//!
+//! By default, there are no syntax highlighters exported by miette. To enable support for
+//! specific highlighters, you should enable their associated feature flag.
+//!
+//! Currently supported syntax highlighters and their feature flags:
+//! * `syntect` - Enables [syntect] syntax highlighting support via the [crate::highlighters::SyntectHighlighter]
+//!
+//! Docs for these highlighters can be found in the [crate::highlighters] module.
+//!
+
+use std::error::Error as StdError;
+
+use crate::{Diagnostic, SourceCode};
+use once_cell::sync::OnceCell;
+use owo_colors::Styled;
+
+#[cfg(feature = "syntect")]
+pub use syntect::*;
+
+#[cfg(feature = "syntect")]
+mod syntect;
+
+/// A syntax highlighter for highlighting miette [SourceCode] snippets.
+pub trait Highlighter {
+    /// Creates a new [HighlighterState] to begin parsing and highlighting a [SourceCode] snippets.
+    ///
+    /// The [crate::GraphicalReportHandler] will call this function at the start of rendering
+    /// to highlight lines of source code.
+    fn start_highlighter_state<'h>(
+        &'h self,
+        source: &dyn SourceCode,
+    ) -> Option<Box<dyn HighlighterState + 'h>>;
+}
+
+/// A stateful highlighting iterator over lines of source code.
+///
+/// Use [Highlighter::start_highlighter_state] to create a HighlighterState, which
+/// can then be used to iteratively produce highlighted regions of text with
+/// the [HighlighterState::highlight_line] method.
+pub trait HighlighterState {
+    /// Highlight an individual line from the source code by returning a vector of [Styled]
+    /// regions.
+    fn highlight_line<'s>(&mut self, line: &'s str) -> Vec<Styled<&'s str>>;
+}
+
+static HIGHLIGHTER: OnceCell<Option<Box<dyn Highlighter + Send + Sync>>> = OnceCell::new();
+
+/// Error indicating that [`set_highlighter()`] was unable to install the provided
+/// [`Highlighter`]
+#[derive(Debug)]
+pub struct HighlighterInstallError;
+
+impl core::fmt::Display for HighlighterInstallError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        f.write_str("cannot install provided Highlighter, a hook has already been installed")
+    }
+}
+
+impl StdError for HighlighterInstallError {}
+impl Diagnostic for HighlighterInstallError {}
+
+/// Set the [`Highlighter`] to use with [`crate::GraphicalReportHandler`]
+///
+/// If compiling with the `syntect` feature, it will automatically use the default
+/// [`SyntectHighlighter`] and you will only want to call this if you're overriding
+/// the default highlighting theme and settings.
+pub fn set_highlighter(
+    highlighter: impl Highlighter + Send + Sync + 'static,
+) -> Result<(), HighlighterInstallError> {
+    HIGHLIGHTER
+        .set(Some(Box::new(highlighter)))
+        .map_err(|_| HighlighterInstallError)
+}
+
+/// Retrieves the current global [`Highlighter`]
+pub(crate) fn get_highlighter() -> Option<&'static (dyn Highlighter + Send + Sync)> {
+    HIGHLIGHTER.get_or_init(|| default_highlighter()).as_deref()
+}
+
+/// Default [`Highlighter`]. Uses feature flags to determine
+///
+/// NOTE: if/when multiple highlighters are supported, this should panic with
+/// a helpful message if multiple are enabled.
+fn default_highlighter() -> Option<Box<dyn Highlighter + Send + Sync>> {
+    #[cfg(feature = "syntect")]
+    return Some(Box::new(SyntectHighlighter::default()));
+    #[cfg(not(feature = "syntect"))]
+    return None;
+}

src/highlighters/syntect.rs

@@ -0,0 +1,137 @@
+use std::path::Path;
+
+// all syntect imports are explicitly qualified, but their paths are shortened for convenience
+mod syntect {
+    pub(super) use syntect::{
+        highlighting::{
+            Color, HighlightIterator, HighlightState, Highlighter, Style, Theme, ThemeSet,
+        },
+        parsing::{ParseState, ScopeStack, SyntaxReference, SyntaxSet},
+    };
+}
+
+use owo_colors::{Rgb, Style, Styled};
+
+use crate::{
+    highlighters::{Highlighter, HighlighterState},
+    SourceCode,
+};
+
+/// Highlights miette [SourceCode] with the [syntect] highlighting crate.
+#[derive(Debug, Clone)]
+pub struct SyntectHighlighter {
+    theme: syntect::Theme,
+    syntax_set: syntect::SyntaxSet,
+}
+
+impl Default for SyntectHighlighter {
+    fn default() -> Self {
+        let syntax_set = syntect::SyntaxSet::load_defaults_nonewlines();
+        let theme_set = syntect::ThemeSet::load_defaults();
+        let theme = theme_set.themes.get("base16-ocean.dark").unwrap().clone();
+        Self::new(theme, syntax_set)
+    }
+}
+
+impl Highlighter for SyntectHighlighter {
+    fn start_highlighter_state<'h>(
+        &'h self,
+        source: &dyn SourceCode,
+    ) -> Option<Box<dyn HighlighterState + 'h>> {
+        let syntax = self.get_syntax_from_source(source)?;
+        let highlighter = syntect::Highlighter::new(&self.theme);
+        let parse_state = syntect::ParseState::new(syntax);
+        let highlight_state =
+            syntect::HighlightState::new(&highlighter, syntect::ScopeStack::new());
+        Some(Box::new(SyntectHighlighterState {
+            syntax_set: &self.syntax_set,
+            highlighter,
+            parse_state,
+            highlight_state,
+        }))
+    }
+}
+
+impl SyntectHighlighter {
+    /// Create a SyntectHighlighter
+    pub fn new(theme: syntect::Theme, syntax_set: syntect::SyntaxSet) -> Self {
+        Self { theme, syntax_set }
+    }
+
+    /// Determine syntect SyntaxReference to use for given SourceCode
+    fn get_syntax_from_source(&self, source: &dyn SourceCode) -> Option<&syntect::SyntaxReference> {
+        if let Some(language) = source.language() {
+            self.syntax_set.find_syntax_by_name(language)
+        } else if let Some(name) = source.name() {
+            if let Some(ext) = Path::new(name).extension() {
+                self.syntax_set
+                    .find_syntax_by_extension(ext.to_string_lossy().as_ref())
+            } else {
+                None
+            }
+        } else {
+            None
+        }
+    }
+}
+
+/// Stateful highlighting iterator for [SyntectHighlighter]
+#[derive(Debug)]
+pub struct SyntectHighlighterState<'h> {
+    syntax_set: &'h syntect::SyntaxSet,
+    highlighter: syntect::Highlighter<'h>,
+    parse_state: syntect::ParseState,
+    highlight_state: syntect::HighlightState,
+}
+
+impl<'h> HighlighterState for SyntectHighlighterState<'h> {
+    fn highlight_line<'s>(&mut self, line: &'s str) -> Vec<Styled<&'s str>> {
+        let use_bg_color = false;
+        let ops = self.parse_state.parse_line(line, &self.syntax_set).unwrap();
+        syntect::HighlightIterator::new(
+            &mut self.highlight_state,
+            &ops,
+            line,
+            &mut self.highlighter,
+        )
+        .map(|(style, str)| (convert_style(style, use_bg_color).style(str)))
+        .collect()
+    }
+}
+
+/* Convert syntect Style into owo_colors Style */
+#[inline]
+fn convert_style(syntect_style: syntect::Style, use_bg_color: bool) -> Style {
+    if use_bg_color {
+        let fg = blend_fg_color(syntect_style);
+        let bg = convert_color(syntect_style.background);
+        Style::new().color(fg).on_color(bg)
+    } else {
+        let fg = convert_color(syntect_style.foreground);
+        Style::new().color(fg)
+    }
+}
+
+/* Blend foreground RGB into background RGB according to alpha channel */
+#[inline]
+fn blend_fg_color(syntect_style: syntect::Style) -> Rgb {
+    let fg = syntect_style.foreground;
+    if fg.a == 0xff {
+        return convert_color(fg);
+    }
+    let bg = syntect_style.background;
+    let ratio = fg.a as u32;
+    let r = (fg.r as u32 * ratio + bg.r as u32 * (255 - ratio)) / 255;
+    let g = (fg.g as u32 * ratio + bg.g as u32 * (255 - ratio)) / 255;
+    let b = (fg.b as u32 * ratio + bg.b as u32 * (255 - ratio)) / 255;
+    Rgb(r as u8, g as u8, b as u8)
+}
+
+/** Convert syntect color into owo color.
+ *
+ * Note: ignores alpha channel. use blend_fg_color if you need that
+ */
+#[inline]
+fn convert_color(color: syntect::Color) -> Rgb {
+    Rgb(color.r, color.g, color.b)
+}

src/lib.rs

@@ -672,6 +672,8 @@ mod eyreish;
 #[cfg(feature = "fancy-no-backtrace")]
 mod handler;
 mod handlers;
+#[cfg(feature = "fancy-no-backtrace")]
+pub mod highlighters;
 #[doc(hidden)]
 pub mod macro_helpers;
 mod miette_diagnostic;

src/named_source.rs

@@ -58,4 +58,12 @@ impl SourceCode for NamedSource {
             contents.line_count(),
         )))
     }
+
+    fn name(&self) -> Option<&str> {
+        Some(&self.name)
+    }
+
+    fn language(&self) -> Option<&str> {
+        self.source.language()
+    }
 }

src/protocol.rs

@@ -240,6 +240,20 @@ pub trait SourceCode: Send + Sync {
         context_lines_before: usize,
         context_lines_after: usize,
     ) -> Result<Box<dyn SpanContents<'a> + 'a>, MietteError>;
+
+    /// Optional method. The name of this source, if any
+    fn name(&self) -> Option<&str> {
+        None
+    }
+
+    /// Optional method. The language name for this source code, if any.
+    /// This is used to drive syntax highlighting.
+    ///
+    /// Examples: Rust, TOML, C
+    ///
+    fn language(&self) -> Option<&str> {
+        None
+    }
 }
 
 /// A labeled [`SourceSpan`].