syntect/
util.rs

Help
1//! Convenient helper functions for common use cases:
2//! * Printing to terminal
3//! * Iterating lines with `\n`s
4//! * Modifying ranges of highlighted output
5
6use crate::highlighting::{Color, Style, StyleModifier};
7#[cfg(feature = "parsing")]
8use crate::parsing::ScopeStackOp;
9use std::fmt::Write;
10use std::ops::Range;
11
12#[inline]
13fn blend_fg_color(fg: Color, bg: Color) -> Color {
14    if fg.a == 0xff {
15        return fg;
16    }
17    let ratio = fg.a as u32;
18    let r = (fg.r as u32 * ratio + bg.r as u32 * (255 - ratio)) / 255;
19    let g = (fg.g as u32 * ratio + bg.g as u32 * (255 - ratio)) / 255;
20    let b = (fg.b as u32 * ratio + bg.b as u32 * (255 - ratio)) / 255;
21    Color {
22        r: r as u8,
23        g: g as u8,
24        b: b as u8,
25        a: 255,
26    }
27}
28
29/// Formats the styled fragments using 24-bit color terminal escape codes.
30/// Meant for debugging and testing.
31///
32/// This function is currently fairly inefficient in its use of escape codes.
33///
34/// Note that this does not currently ever un-set the color so that the end of a line will also get
35/// highlighted with the background.  This means if you might want to use `println!("\x1b[0m");`
36/// after to clear the coloring.
37///
38/// If `bg` is true then the background is also set
39pub fn as_24_bit_terminal_escaped(v: &[(Style, &str)], bg: bool) -> String {
40    let mut s: String = String::new();
41    for &(ref style, text) in v.iter() {
42        if bg {
43            write!(s,
44                   "\x1b[48;2;{};{};{}m",
45                   style.background.r,
46                   style.background.g,
47                   style.background.b)
48                .unwrap();
49        }
50        let fg = blend_fg_color(style.foreground, style.background);
51        write!(s, "\x1b[38;2;{};{};{}m{}", fg.r, fg.g, fg.b, text).unwrap();
52    }
53    // s.push_str("\x1b[0m");
54    s
55}
56
57const LATEX_REPLACE: [(&str, &str); 3] = [
58    ("\\", "\\\\"),
59    ("{", "\\{"),
60    ("}", "\\}"),
61];
62
63/// Formats the styled fragments using LaTeX textcolor directive.
64///
65/// Usage is similar to the `as_24_bit_terminal_escaped` function:
66///
67/// ```
68/// use syntect::easy::HighlightLines;
69/// use syntect::parsing::SyntaxSet;
70/// use syntect::highlighting::{ThemeSet,Style};
71/// use syntect::util::{as_latex_escaped,LinesWithEndings};
72///
73/// // Load these once at the start of your program
74/// let ps = SyntaxSet::load_defaults_newlines();
75/// let ts = ThemeSet::load_defaults();
76///
77/// let syntax = ps.find_syntax_by_extension("rs").unwrap();
78/// let s = "pub struct Wow { hi: u64 }\nfn blah() -> u64 {}\n";
79///
80/// let mut h = HighlightLines::new(syntax, &ts.themes["InspiredGitHub"]);
81/// for line in LinesWithEndings::from(s) { // LinesWithEndings enables use of newlines mode
82///     let ranges: Vec<(Style, &str)> = h.highlight_line(line, &ps).unwrap();
83///     let escaped = as_latex_escaped(&ranges[..]);
84///     println!("{}", escaped);
85/// }
86/// ```
87///
88/// Returned content is intended to be placed inside a fancyvrb
89/// Verbatim environment:
90///
91/// ```latex
92/// \usepackage{fancyvrb}
93/// \usepackage{xcolor}
94/// % ...
95/// % enable comma-separated arguments inside \textcolor
96/// \makeatletter
97/// \def\verbatim@nolig@list{\do\`\do\<\do\>\do\'\do\-}
98/// \makeatother
99/// % ...
100/// \begin{Verbatim}[commandchars=\\\{\}]
101/// % content goes here
102/// \end{Verbatim}
103/// ```
104///
105/// Background color is ignored.
106pub fn as_latex_escaped(v: &[(Style, &str)]) -> String {
107    let mut s: String = String::new();
108    let mut prev_style: Option<Style> = None;
109    let mut content: String;
110    fn textcolor(style: &Style, first: bool) -> String {
111        format!("{}\\textcolor[RGB]{{{},{},{}}}{{",
112            if first { "" } else { "}" },
113            style.foreground.r,
114            style.foreground.b,
115            style.foreground.g)
116    }
117    for &(style, text) in v.iter() {
118        if let Some(ps) = prev_style {
119            match text {
120                " " => {
121                    s.push(' ');
122                    continue;
123                },
124                "\n" => continue,
125                _ => (),
126            }
127            if style != ps {
128                write!(s, "{}", textcolor(&style, false)).unwrap();
129            }
130        } else {
131            write!(s, "{}", textcolor(&style, true)).unwrap();
132        }
133        content = text.to_string();
134        for &(old, new) in LATEX_REPLACE.iter() {
135            content = content.replace(old, new);
136        }
137        write!(s, "{}", &content).unwrap();
138        prev_style = Some(style);
139    }
140    s.push('}');
141    s
142}
143
144/// Print out the various push and pop operations in a vector
145/// with visual alignment to the line. Obviously for debugging.
146#[cfg(feature = "parsing")]
147pub fn debug_print_ops(line: &str, ops: &[(usize, ScopeStackOp)]) {
148    for &(i, ref op) in ops.iter() {
149        println!("{}", line.trim_end());
150        print!("{: <1$}", "", i);
151        match *op {
152            ScopeStackOp::Push(s) => {
153                println!("^ +{}", s);
154            }
155            ScopeStackOp::Pop(count) => {
156                println!("^ pop {}", count);
157            }
158            ScopeStackOp::Clear(amount) => {
159                println!("^ clear {:?}", amount);
160            }
161            ScopeStackOp::Restore => println!("^ restore"),
162            ScopeStackOp::Noop => println!("noop"),
163        }
164    }
165}
166
167
168/// An iterator over the lines of a string, including the line endings.
169///
170/// This is similar to the standard library's `lines` method on `str`, except
171/// that the yielded lines include the trailing newline character(s).
172///
173/// You can use it if you're parsing/highlighting some text that you have as a
174/// string. With this, you can use the "newlines" variant of syntax definitions,
175/// which is recommended.
176///
177/// # Examples
178///
179/// ```
180/// use syntect::util::LinesWithEndings;
181///
182/// let mut lines = LinesWithEndings::from("foo\nbar\nbaz");
183///
184/// assert_eq!(Some("foo\n"), lines.next());
185/// assert_eq!(Some("bar\n"), lines.next());
186/// assert_eq!(Some("baz"), lines.next());
187///
188/// assert_eq!(None, lines.next());
189/// ```
190pub struct LinesWithEndings<'a> {
191    input: &'a str,
192}
193
194impl<'a> LinesWithEndings<'a> {
195    pub fn from(input: &'a str) -> LinesWithEndings<'a> {
196        LinesWithEndings { input }
197    }
198}
199
200impl<'a> Iterator for LinesWithEndings<'a> {
201    type Item = &'a str;
202
203    #[inline]
204    fn next(&mut self) -> Option<&'a str> {
205        if self.input.is_empty() {
206            return None;
207        }
208        let split = self.input
209            .find('\n')
210            .map(|i| i + 1)
211            .unwrap_or_else(|| self.input.len());
212        let (line, rest) = self.input.split_at(split);
213        self.input = rest;
214        Some(line)
215    }
216}
217
218/// Split a highlighted line at a byte index in the line into a before and
219/// after component.
220///
221/// This is just a helper that does the somewhat tricky logic including splitting
222/// a span if the index lies on a boundary.
223///
224/// This can be used to extract a chunk of the line out for special treatment
225/// like wrapping it in an HTML tag for extra styling.
226///
227/// Generic for testing purposes and fancier use cases, but intended for use with
228/// the `Vec<(Style, &str)>` returned by `highlight` methods. Look at the source
229/// code for `modify_range` for an example usage.
230#[allow(clippy::type_complexity)]
231pub fn split_at<'a, A: Clone>(
232    v: &[(A, &'a str)],
233    split_i: usize,
234) -> (Vec<(A, &'a str)>, Vec<(A, &'a str)>) {
235    // This function works by gradually reducing the problem into smaller sub-problems from the front
236    let mut rest = v;
237    let mut rest_split_i = split_i;
238
239    // Consume all tokens before the split
240    let mut before = Vec::new();
241    for tok in rest { // Use for instead of a while to avoid bounds checks
242        if tok.1.len() > rest_split_i {
243            break;
244        }
245        before.push(tok.clone());
246        rest_split_i -= tok.1.len();
247    }
248    rest = &rest[before.len()..];
249
250    let mut after = Vec::new();
251    // If necessary, split the token the split falls inside
252    if !rest.is_empty() && rest_split_i > 0 {
253        let mut rest_split_index = rest_split_i;
254        // Splitting in the middle of a multibyte character causes panic,
255        // so if index is in the middle of such a character,
256        // reduce the index by 1.
257        while !rest[0].1.is_char_boundary(rest_split_index) && rest_split_index > 0 {
258            rest_split_index -= 1;
259        }
260        let (sa, sb) = rest[0].1.split_at(rest_split_index);
261        before.push((rest[0].0.clone(), sa));
262        after.push((rest[0].0.clone(), sb));
263        rest = &rest[1..];
264    }
265
266    after.extend_from_slice(rest);
267
268    (before, after)
269}
270
271/// Modify part of a highlighted line using a style modifier, useful for highlighting sections of a line.
272///
273/// # Examples
274///
275/// ```
276/// use syntect::util::modify_range;
277/// use syntect::highlighting::{Style, StyleModifier, FontStyle};
278///
279/// let plain = Style::default();
280/// let boldmod = StyleModifier { foreground: None, background: None, font_style: Some(FontStyle::BOLD) };
281/// let bold = plain.apply(boldmod);
282///
283/// let l = &[(plain, "abc"), (plain, "def"), (plain, "ghi")];
284/// let l2 = modify_range(l, 1..6, boldmod);
285/// assert_eq!(l2, &[(plain, "a"), (bold, "bc"), (bold, "def"), (plain, "ghi")]);
286/// ```
287pub fn modify_range<'a>(v: &[(Style, &'a str)], r: Range<usize>, modifier: StyleModifier) -> Vec<(Style, &'a str)> {
288    let (mut result, in_and_after) = split_at(v, r.start);
289    let (inside, mut after) = split_at(&in_and_after, r.end - r.start);
290
291    result.extend(inside.iter().map(|(style, s)| { (style.apply(modifier), *s)}));
292    result.append(&mut after);
293    result
294}
295
296#[cfg(test)]
297mod tests {
298    use super::*;
299    use crate::highlighting::FontStyle;
300
301    #[test]
302    fn test_lines_with_endings() {
303        fn lines(s: &str) -> Vec<&str> {
304            LinesWithEndings::from(s).collect()
305        }
306
307        assert!(lines("").is_empty());
308        assert_eq!(lines("f"), vec!["f"]);
309        assert_eq!(lines("foo"), vec!["foo"]);
310        assert_eq!(lines("foo\n"), vec!["foo\n"]);
311        assert_eq!(lines("foo\nbar"), vec!["foo\n", "bar"]);
312        assert_eq!(lines("foo\nbar\n"), vec!["foo\n", "bar\n"]);
313        assert_eq!(lines("foo\r\nbar"), vec!["foo\r\n", "bar"]);
314        assert_eq!(lines("foo\r\nbar\r\n"), vec!["foo\r\n", "bar\r\n"]);
315        assert_eq!(lines("\nfoo"), vec!["\n", "foo"]);
316        assert_eq!(lines("\n\n\n"), vec!["\n", "\n", "\n"]);
317    }
318
319    #[test]
320    fn test_split_at() {
321        let l: &[(u8, &str)] = &[];
322        let (before, after) = split_at(l, 0); // empty
323        assert_eq!((&before[..], &after[..]), (&[][..],&[][..]));
324
325        let l = &[(0u8, "abc"), (1u8, "def"), (2u8, "ghi")];
326
327        let (before, after) = split_at(l, 0); // at start
328        assert_eq!((&before[..], &after[..]), (&[][..],&[(0u8, "abc"), (1u8, "def"), (2u8, "ghi")][..]));
329
330        let (before, after) = split_at(l, 4); // inside token
331        assert_eq!((&before[..], &after[..]), (&[(0u8, "abc"), (1u8, "d")][..],&[(1u8, "ef"), (2u8, "ghi")][..]));
332
333        let (before, after) = split_at(l, 3); // between tokens
334        assert_eq!((&before[..], &after[..]), (&[(0u8, "abc")][..],&[(1u8, "def"), (2u8, "ghi")][..]));
335
336        let (before, after) = split_at(l, 9); // just after last token
337        assert_eq!((&before[..], &after[..]), (&[(0u8, "abc"), (1u8, "def"), (2u8, "ghi")][..], &[][..]));
338
339        let (before, after) = split_at(l, 10); // out of bounds
340        assert_eq!((&before[..], &after[..]), (&[(0u8, "abc"), (1u8, "def"), (2u8, "ghi")][..], &[][..]));
341
342        let l = &[(0u8, "こんにちは"), (1u8, "世界"), (2u8, "！")];
343
344        let (before, after) = split_at(l, 3);
345
346        assert_eq!(
347            (&before[..], &after[..]),
348            (
349                &[(0u8, "こ")][..],
350                &[(0u8, "んにちは"), (1u8, "世界"), (2u8, "！")][..]
351            )
352        );
353
354        //Splitting inside a multibyte character could cause panic,
355        //so if index is inside such a character,
356        //index is decreased by 1.
357        let (before, after) = split_at(l, 4);
358
359        assert_eq!(
360            (&before[..], &after[..]),
361            (
362                &[(0u8, "こ")][..],
363                &[(0u8, "んにちは"), (1u8, "世界"), (2u8, "！")][..]
364            )
365        );
366    }
367
368    #[test]
369    fn test_as_24_bit_terminal_escaped() {
370        let style = Style {
371            foreground: Color::WHITE,
372            background: Color::BLACK,
373            font_style: FontStyle::default(),
374        };
375
376        // With background
377        let s = as_24_bit_terminal_escaped(&[(style, "hello")], true);
378        assert_eq!(s, "\x1b[48;2;0;0;0m\x1b[38;2;255;255;255mhello");
379
380        // Without background
381        let s = as_24_bit_terminal_escaped(&[(style, "hello")], false);
382        assert_eq!(s, "\x1b[38;2;255;255;255mhello");
383
384        // Blend alpha
385        let mut foreground = Color::WHITE;
386        foreground.a = 128;
387        let style = Style {
388            foreground,
389            background: Color::BLACK,
390            font_style: FontStyle::default(),
391        };
392        let s = as_24_bit_terminal_escaped(&[(style, "hello")], true);
393        assert_eq!(s, "\x1b[48;2;0;0;0m\x1b[38;2;128;128;128mhello");
394    }
395}
syntect/util.rs

syntect/
util.rs
