qframe/widgets/code_view/

mod.rs

//! Highlighted code.

use std::ops::{Bound, RangeBounds};

use unicode_segmentation::UnicodeSegmentation;

use super::cells;
use super::highlight::{Language, Token, highlight};
use crate::event::Event;
use crate::geometry::{Rect, Size, clamp_u16};
use crate::keymap::Key;
use crate::style::CellStyle;
use crate::text;
use crate::theme::State;
use crate::widget::{EventCx, MeasureCx, PaintCx, Widget};

/// One visual row of code: a line number on the first row of a source line, and coloured pieces.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct CodeRow {
    /// The source line the row shows part of, counted from 1.
    pub(crate) line: usize,
    pub(crate) number: Option<usize>,
    pub(crate) pieces: Vec<(String, Token)>,
}

/// Lays `code` out in rows no wider than `width` cells, wrapping long lines. Continuation
/// rows are indented by two cells.
pub(crate) fn code_rows(code: &str, language: Language, width: u16) -> Vec<CodeRow> {
    let tokens = highlight(code, language);
    let mut rows = Vec::new();
    let mut line_start = 0;
    for (index, line) in code.split('\n').enumerate() {
        let line_end = line_start + line.len();
        let mut row = CodeRow { line: index + 1, number: Some(index + 1), pieces: Vec::new() };
        let mut used = 0u16;
        for (range, token) in &tokens {
            let start = range.start.max(line_start);
            let end = range.end.min(line_end);
            if start >= end {
                continue;
            }
            for grapheme in code[start..end].graphemes(true) {
                let cell = if grapheme == "\t" { "    " } else { grapheme };
                let w = text::width(cell);
                if used.saturating_add(w) > width && used > 0 {
                    rows.push(std::mem::replace(
                        &mut row,
                        CodeRow { line: index + 1, number: None, pieces: vec![("  ".to_owned(), Token::Plain)] },
                    ));
                    used = 2;
                }
                match row.pieces.last_mut() {
                    Some((piece, last)) if last == token => piece.push_str(cell),
                    _ => row.pieces.push((cell.to_owned(), *token)),
                }
                used = used.saturating_add(w);
            }
        }
        rows.push(row);
        line_start = line_end + 1;
    }
    if code.ends_with('\n') {
        rows.pop();
    }
    rows
}

/// Paints `rows` in `area` using the `code-token.<kind>` and `code-line-number` styles.
pub(crate) fn paint_rows(cx: &mut PaintCx<'_>, area: Rect, rows: &[CodeRow], gutter: u16) {
    for (y, row) in rows.iter().enumerate() {
        let Ok(y) = u16::try_from(y) else { break };
        if y >= area.height {
            break;
        }
        let row_y = area.y + i32::from(y);
        // Line numbers help reading, not copying: clean copies leave the gutter out.
        if gutter > 0 {
            cx.decoration(Rect::new(area.x, row_y, gutter, 1));
        }
        if gutter > 0
            && let Some(number) = row.number
        {
            let style = cx.style("code-line-number", None, &[]).text();
            let label = format!("{number:>width$}", width = usize::from(gutter - 2));
            cx.text(area.x, row_y, &label, style, gutter);
        }
        let mut x = area.x + i32::from(gutter);
        for (piece, token) in &row.pieces {
            let style = cx.style("code-token", Some(token.variant()), &[]).text();
            x += i32::from(cx.text(x, row_y, piece, style, area.right().saturating_sub(x).try_into().unwrap_or(0)));
        }
    }
}

/// Marks the padding of a code block at `rect` around `inner` as decoration, so clean copies of
/// a selection across the block keep only the code.
pub(crate) fn padding_decoration(cx: &mut PaintCx<'_>, rect: Rect, inner: Rect) {
    cx.decoration(Rect::new(rect.x, rect.y, rect.width, clamp_u16(inner.y - rect.y)));
    cx.decoration(Rect::new(rect.x, inner.bottom(), rect.width, clamp_u16(rect.bottom() - inner.bottom())));
    cx.decoration(Rect::new(rect.x, inner.y, clamp_u16(inner.x - rect.x), inner.height));
    cx.decoration(Rect::new(inner.right(), inner.y, clamp_u16(rect.right() - inner.right()), inner.height));
}

/// Width of the line number column for `code`, including two cells of spacing.
pub(crate) fn gutter_width(code: &str) -> u16 {
    let lines = code.split('\n').count();
    text::width(&lines.to_string()).saturating_add(2)
}

/// How a line of a diff changed; see [`CodeView::line_marks`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum LineMark {
    /// The line is in both versions; drawn as any other line.
    #[default]
    Unchanged,
    /// The line is new: a success tint and a `+` sign.
    Added,
    /// The line is gone: a danger tint and a `−` sign.
    Removed,
}

/// The tone of highlighted lines; see [`CodeView::highlight_lines`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum LineTone {
    /// A line to look at, such as the one a "go to line" reached: an accent tint and the pillar.
    #[default]
    Accent,
    /// A line worth a careful look, such as a finding of a review: a warning tint and the
    /// warning icon.
    Warning,
}

impl LineTone {
    fn variant(self) -> &'static str {
        match self {
            Self::Accent => "accent",
            Self::Warning => "warning",
        }
    }
}

/// The sign of a marked or highlighted line.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Sign {
    /// An icon on the first row of the line.
    Icon(&'static str),
    /// The theme's pillar on every row of the line.
    Pillar,
}

/// Rows of context kept around a revealed line, so it does not land on the very edge of the
/// scroll view.
const REVEAL_CONTEXT: u16 = 2;

/// What a code view remembers between frames.
#[derive(Debug, Default)]
struct CodeMemory {
    /// The line last revealed, so the view scrolls to a line once and then lets the user move.
    revealed: Option<usize>,
}

/// Code with syntax colours, line numbers and wrapping of long lines.
///
/// While focused, `c` copies the code to the clipboard and flashes. The code is a text selection
/// region: a mouse drag selects inside it (turn it off with
/// [`NodeMut::selectable`](crate::widget::NodeMut::selectable)), and clean copies leave out the
/// line numbers and the signs of marked lines.
///
/// For reviews, [`line_marks`](Self::line_marks) shows a diff and
/// [`highlight_lines`](Self::highlight_lines) tints lines to look at; either adds a sign column
/// at the left edge. [`reveal`](Self::reveal) scrolls the enclosing
/// [`ScrollView`](crate::widgets::ScrollView) to a line.
///
/// Style keys: `code` (`bg`, `padding`) with `focus` and `pressed`; `code-line-number`;
/// `code-token.<kind>` where kind is `keyword`, `type`, `function`, `macro`, `string`,
/// `number`, `comment`, `attribute`, `lifetime`, `punctuation`, `table`, `key`, `variable` or
/// `plain`; `code-line.<look>` (`bg` for the line, `fg` for its sign) where look is `added`,
/// `removed`, `accent` or `warning`. Icons: `line-added`, `line-removed`, `warning` and the
/// pillar.
pub struct CodeView<Msg> {
    code: String,
    language: Language,
    line_numbers: bool,
    marks: Vec<LineMark>,
    /// The number each source line carries, when the caller gave them outright.
    numbers: Option<Vec<Option<usize>>>,
    highlights: Vec<(usize, usize, LineTone)>,
    reveal: Option<usize>,
    reveal_number: Option<usize>,
    on_copy: Option<Msg>,
}

impl<Msg: 'static> CodeView<Msg> {
    /// Shows `code` in `language`.
    #[must_use]
    pub fn new(code: impl Into<String>, language: Language) -> Self {
        Self {
            code: code.into(),
            language,
            line_numbers: true,
            marks: Vec::new(),
            numbers: None,
            highlights: Vec::new(),
            reveal: None,
            reveal_number: None,
            on_copy: None,
        }
    }

    /// Marks lines as a diff: the first mark belongs to line 1, the next to line 2, and lines
    /// past the last mark are unchanged. Added lines are tinted with the success colour and
    /// signed `+`, removed ones with the danger colour and `−`, in the sign column at the left
    /// edge.
    ///
    /// The line numbers then follow the files rather than the text: a diff puts the lines of two
    /// versions one after another, so counting from the top would number neither file. A removed
    /// line carries the old file's number, an added line the new file's, and a line in both
    /// carries the new file's, which is the one a finding such as `PKGBUILD:22` means. Give
    /// [`line_numbers_from`](Self::line_numbers_from) instead when the diff starts part way into
    /// the file, and reach a line by its number with [`reveal_number`](Self::reveal_number).
    #[must_use]
    pub fn line_marks(mut self, marks: impl IntoIterator<Item = LineMark>) -> Self {
        self.marks = marks.into_iter().collect();
        self
    }

    /// Tints `lines` (counted from 1, like the line numbers) in `tone`, over any diff mark, and
    /// puts the tone's sign in the sign column. Call it again for more lines; where ranges meet,
    /// the later call wins. The tint is separate from a text selection, which draws over it.
    #[must_use]
    pub fn highlight_lines(mut self, lines: impl RangeBounds<usize>, tone: LineTone) -> Self {
        let first = match lines.start_bound() {
            Bound::Included(&n) => n,
            Bound::Excluded(&n) => n.saturating_add(1),
            Bound::Unbounded => 1,
        };
        let last = match lines.end_bound() {
            Bound::Included(&n) => n,
            Bound::Excluded(&n) => n.saturating_sub(1),
            Bound::Unbounded => usize::MAX,
        };
        self.highlights.push((first.max(1), last, tone));
        self
    }

    /// Scrolls the enclosing [`ScrollView`](crate::widgets::ScrollView) just enough to show
    /// `line` (counted from 1; past the end, the last line) with two rows of context, gliding
    /// there unless motion is reduced. It happens when the revealed line changes, so the user
    /// can scroll away afterwards; outside a scroll view it does nothing.
    #[must_use]
    pub fn reveal(mut self, line: usize) -> Self {
        self.reveal = Some(line);
        self
    }

    /// Shows or hides line numbers; shown by default.
    #[must_use]
    pub fn line_numbers(mut self, show: bool) -> Self {
        self.line_numbers = show;
        self
    }

    /// Gives each line its own number outright: the first number belongs to the first line of the
    /// code, and `None` leaves that line's column blank, as a hunk header has no number of its
    /// own. Lines past the last number are blank too.
    ///
    /// This is for a diff that starts part way into a file, where nothing in the text says the
    /// hunk began at line 120. A whole-file diff needs only [`line_marks`](Self::line_marks),
    /// which numbers the lines from the marks. Numbers given here win over that.
    #[must_use]
    pub fn line_numbers_from(mut self, numbers: impl IntoIterator<Item = Option<usize>>) -> Self {
        self.numbers = Some(numbers.into_iter().collect());
        self
    }

    /// Scrolls to the line whose number is `number`, the way [`reveal`](Self::reveal) scrolls to
    /// a line of the text. In a diff the two are not the same line, so this is what a finding
    /// that names a file and a line asks for.
    ///
    /// Two lines can carry one number — the line a version lost and the line that took its place.
    /// The line the new file numbers that way is the one reached, because that is the file a
    /// finding is about; a number only a removed line carries reaches that line. A number no line
    /// carries scrolls nowhere. Given as well as [`reveal`](Self::reveal), this wins.
    #[must_use]
    pub fn reveal_number(mut self, number: usize) -> Self {
        self.reveal_number = Some(number);
        self
    }

    /// The number each source line is drawn with: the ones given outright, else the numbers the
    /// diff marks imply, else the line's own place in the text.
    fn numbers(&self) -> Vec<Option<usize>> {
        let lines = self.code.split('\n').count();
        if let Some(given) = &self.numbers {
            return (0..lines).map(|index| given.get(index).copied().flatten()).collect();
        }
        if self.marks.is_empty() {
            return (1..=lines).map(Some).collect();
        }
        let (mut old, mut new) = (0, 0);
        (0..lines)
            .map(|index| match self.marks.get(index) {
                Some(LineMark::Removed) => {
                    old += 1;
                    Some(old)
                }
                Some(LineMark::Added) => {
                    new += 1;
                    Some(new)
                }
                Some(LineMark::Unchanged) | None => {
                    old += 1;
                    new += 1;
                    Some(new)
                }
            })
            .collect()
    }

    /// The source line `number` names, preferring the line the new file numbers that way over one
    /// the old file lost.
    fn line_of_number(&self, number: usize) -> Option<usize> {
        let numbers = self.numbers();
        let carries = |index: &usize| numbers.get(*index).copied().flatten() == Some(number);
        let kept = |index: &usize| !matches!(self.marks.get(*index), Some(LineMark::Removed));
        let index = (0..numbers.len())
            .find(|index| carries(index) && kept(index))
            .or_else(|| (0..numbers.len()).find(carries))?;
        Some(index + 1)
    }

    /// Message sent after the code was copied with `c`.
    #[must_use]
    pub fn on_copy(mut self, message: Msg) -> Self {
        self.on_copy = Some(message);
        self
    }

    fn gutter(&self) -> u16 {
        if !self.line_numbers {
            return 0;
        }
        if self.numbers.is_none() && self.marks.is_empty() {
            return gutter_width(&self.code);
        }
        // A diff's numbers are the files' own, which can be wider than the count of lines shown.
        let widest = self.numbers().into_iter().flatten().max().unwrap_or(1);
        text::width(&widest.to_string()).saturating_add(2)
    }

    /// Width of the sign column: a sign and a space when lines are marked or highlighted.
    fn signs(&self) -> u16 {
        if self.marks.is_empty() && self.highlights.is_empty() { 0 } else { 2 }
    }

    /// How `line` is drawn: the `code-line` variant of its tint and its sign, if any.
    fn look(&self, line: usize) -> Option<(&'static str, Sign)> {
        if let Some((_, _, tone)) =
            self.highlights.iter().rev().find(|(first, last, _)| (*first..=*last).contains(&line))
        {
            let sign = match tone {
                LineTone::Accent => Sign::Pillar,
                LineTone::Warning => Sign::Icon("warning"),
            };
            return Some((tone.variant(), sign));
        }
        match self.marks.get(line.checked_sub(1)?) {
            Some(LineMark::Added) => Some(("added", Sign::Icon("line-added"))),
            Some(LineMark::Removed) => Some(("removed", Sign::Icon("line-removed"))),
            Some(LineMark::Unchanged) | None => None,
        }
    }

    /// The rows of the code, each first row of a source line carrying the number that line is
    /// drawn with.
    fn numbered_rows(&self, width: u16) -> Vec<CodeRow> {
        let mut rows = code_rows(&self.code, self.language, width);
        if self.numbers.is_none() && self.marks.is_empty() {
            return rows;
        }
        let numbers = self.numbers();
        for row in &mut rows {
            if row.number.is_some() {
                row.number = row.line.checked_sub(1).and_then(|index| numbers.get(index).copied().flatten());
            }
        }
        rows
    }

    /// Tints marked and highlighted rows across `area` and draws their signs at `x`.
    fn paint_looks(&self, cx: &mut PaintCx<'_>, area: Rect, x: i32, top: i32, rows: &[CodeRow]) {
        for (index, row) in rows.iter().enumerate() {
            let Some((variant, sign)) = self.look(row.line) else { continue };
            // A wrapped line signs only its first row, and a line without a number of its own —
            // a hunk header — still signs.
            let first_row = index == 0 || rows[index - 1].line != row.line;
            let y = top + i32::try_from(index).unwrap_or(i32::MAX);
            let style = cx.style("code-line", Some(variant), &[]);
            if let Some(bg) = style.color("bg") {
                cx.fill(Rect::new(area.x, y, area.width, 1), bg);
            }
            let color = style.color("fg").unwrap_or_else(|| cx.color("text"));
            match sign {
                Sign::Pillar => cx.pillar(x, y, color),
                Sign::Icon(icon) if first_row => {
                    let glyph = cx.env().icons().glyph(icon).into_owned();
                    cx.text(x, y, &glyph, CellStyle::fg(color), 1);
                }
                Sign::Icon(_) => {}
            }
        }
    }

    /// Asks the enclosing scroll view to show the revealed line, once per line.
    fn request_reveal(&self, cx: &mut PaintCx<'_>, area: Rect, top: i32, rows: &[CodeRow]) {
        let asked = match self.reveal_number {
            Some(number) => self.line_of_number(number),
            None => self.reveal,
        };
        let wanted = asked.map(|line| line.clamp(1, rows.last().map_or(1, |row| row.line)));
        let memory = cx.memory::<CodeMemory>();
        if memory.revealed == wanted {
            return;
        }
        memory.revealed = wanted;
        let Some(line) = wanted else { return };
        let Some(first) = rows.iter().position(|row| row.line == line) else { return };
        let count = rows[first..].iter().take_while(|row| row.line == line).count();
        let context = i32::from(REVEAL_CONTEXT);
        let y = (top + i32::try_from(first).unwrap_or(i32::MAX) - context).max(area.y);
        let bottom = (top + i32::try_from(first + count).unwrap_or(i32::MAX) + context).min(area.bottom());
        cx.reveal(Rect::new(area.x, y, area.width, clamp_u16(bottom - y)));
    }
}

impl<Msg: Clone + 'static> Widget<Msg> for CodeView<Msg> {
    fn measure(&self, cx: &mut MeasureCx<'_>, available: Size) -> Size {
        let padding = cx.env().theme().style("code", None, &[]).pair("padding").unwrap_or((1, 2));
        let content_width =
            available.width.saturating_sub(cells::sum([padding.1.saturating_mul(2), self.signs(), self.gutter()]));
        let rows = code_rows(&self.code, self.language, content_width.max(1));
        let widest = rows
            .iter()
            .map(|row| cells::sum(row.pieces.iter().map(|(piece, _)| text::width(piece))))
            .max()
            .unwrap_or(0);
        Size::new(
            cells::sum([widest, self.signs(), self.gutter(), padding.1.saturating_mul(2)]),
            clamp_u16(i32::try_from(rows.len()).unwrap_or(i32::MAX)).saturating_add(padding.0.saturating_mul(2)),
        )
        .min(available)
    }

    fn paint(&self, cx: &mut PaintCx<'_>, area: Rect) {
        let mut states = cx.states();
        states.retain(|state| *state != State::Hover);
        let style = cx.style("code", None, &states);
        if let Some(bg) = style.text().bg {
            cx.clear(area, bg);
        }
        cx.register_hit(area);
        let inner = area.inset(style.padding());
        // The padding is surface, not code: a selection starts and stays inside it.
        cx.selectable(inner);
        let (signs, gutter) = (self.signs(), self.gutter());
        let width = inner.width.saturating_sub(signs).saturating_sub(gutter).max(1);
        let rows = self.numbered_rows(width);
        if signs > 0 {
            // Signs say how a line changed; copies of the code leave them out like line numbers.
            cx.decoration(Rect::new(inner.x, inner.y, signs, inner.height));
            self.paint_looks(cx, area, inner.x, inner.y, &rows);
        }
        paint_rows(
            cx,
            Rect::new(inner.x + i32::from(signs), inner.y, inner.width.saturating_sub(signs), inner.height),
            &rows,
            gutter,
        );
        self.request_reveal(cx, area, inner.y, &rows);
    }

    fn event(&self, cx: &mut EventCx<'_, Msg>, event: &Event) -> bool {
        let Event::Key(key) = event else {
            return false;
        };
        if !key.is_plain(Key::Char('c')) {
            return false;
        }
        cx.copy(self.code.clone());
        cx.flash();
        if let Some(message) = &self.on_copy {
            cx.emit(message.clone());
        }
        true
    }

    fn focusable(&self) -> bool {
        true
    }
}

#[cfg(test)]
mod tests;