Skip to main content

smooth_reading/
html.rs

1//! HTML and Markdown rendering (SPEC §4).
2
3use std::collections::HashSet;
4
5use crate::options::Options;
6use crate::tokenize::{Token, TokenizeState, tokenize, tokenize_with_state};
7
8/// Elements whose text content [`to_html`] never touches (SPEC §4).
9pub const DEFAULT_SKIP_TAGS: [&str; 7] =
10    ["code", "pre", "script", "style", "kbd", "samp", "textarea"];
11
12/// Markup options for [`to_html`].
13///
14/// ```
15/// use smooth_reading::{HtmlOptions, Options, to_html};
16///
17/// let html = HtmlOptions::new()
18///     .tag("span")
19///     .class_name("sr-fixation")
20///     .rest_tag("span")
21///     .rest_class_name("sr-rest");
22/// assert_eq!(
23///     to_html("Smooth", &Options::new(), &html),
24///     r#"<span class="sr-fixation">Smo</span><span class="sr-rest">oth</span>"#
25/// );
26/// ```
27#[derive(Debug, Clone, PartialEq, Eq)]
28pub struct HtmlOptions {
29    tag: String,
30    class_name: Option<String>,
31    rest_tag: Option<String>,
32    rest_class_name: Option<String>,
33    ignore_html_tags: bool,
34    skip_tags: Vec<String>,
35}
36
37impl Default for HtmlOptions {
38    fn default() -> Self {
39        Self::new()
40    }
41}
42
43impl HtmlOptions {
44    /// The defaults: `<b>` around the fixation, no class, no rest element,
45    /// existing markup preserved, [`DEFAULT_SKIP_TAGS`] skipped.
46    #[must_use]
47    pub fn new() -> Self {
48        Self {
49            tag: "b".to_owned(),
50            class_name: None,
51            rest_tag: None,
52            rest_class_name: None,
53            ignore_html_tags: true,
54            skip_tags: DEFAULT_SKIP_TAGS
55                .iter()
56                .map(|&tag| tag.to_owned())
57                .collect(),
58        }
59    }
60
61    /// The element wrapped around each fixation. Default `b`.
62    #[must_use]
63    pub fn tag(mut self, tag: impl Into<String>) -> Self {
64        self.tag = tag.into();
65        self
66    }
67
68    /// A `class` attribute for the fixation element. Default none.
69    #[must_use]
70    pub fn class_name(mut self, class_name: impl Into<String>) -> Self {
71        self.class_name = Some(class_name.into());
72        self
73    }
74
75    /// An element wrapped around the rest of each emphasised word. Default
76    /// none (the rest is plain text).
77    #[must_use]
78    pub fn rest_tag(mut self, rest_tag: impl Into<String>) -> Self {
79        self.rest_tag = Some(rest_tag.into());
80        self
81    }
82
83    /// A `class` attribute for the rest element. Default none.
84    #[must_use]
85    pub fn rest_class_name(mut self, rest_class_name: impl Into<String>) -> Self {
86        self.rest_class_name = Some(rest_class_name.into());
87        self
88    }
89
90    /// Whether the input is HTML whose markup must pass through untouched
91    /// (`true`, the default) or plain text whose `<`, `>` and `&` are escaped
92    /// (`false`).
93    #[must_use]
94    pub const fn ignore_html_tags(mut self, ignore_html_tags: bool) -> Self {
95        self.ignore_html_tags = ignore_html_tags;
96        self
97    }
98
99    /// Elements whose content is left untouched (compared case-insensitively).
100    /// Replaces [`DEFAULT_SKIP_TAGS`].
101    #[must_use]
102    pub fn skip_tags<I, S>(mut self, skip_tags: I) -> Self
103    where
104        I: IntoIterator<Item = S>,
105        S: Into<String>,
106    {
107        self.skip_tags = skip_tags.into_iter().map(Into::into).collect();
108        self
109    }
110
111    /// The fixation element name.
112    #[must_use]
113    pub fn get_tag(&self) -> &str {
114        &self.tag
115    }
116
117    /// The fixation element's class, if any.
118    #[must_use]
119    pub fn get_class_name(&self) -> Option<&str> {
120        self.class_name.as_deref()
121    }
122
123    /// The rest element name, if any.
124    #[must_use]
125    pub fn get_rest_tag(&self) -> Option<&str> {
126        self.rest_tag.as_deref()
127    }
128
129    /// The rest element's class, if any.
130    #[must_use]
131    pub fn get_rest_class_name(&self) -> Option<&str> {
132        self.rest_class_name.as_deref()
133    }
134
135    /// Whether existing markup passes through untouched.
136    #[must_use]
137    pub const fn get_ignore_html_tags(&self) -> bool {
138        self.ignore_html_tags
139    }
140
141    /// The elements whose content is left untouched.
142    #[must_use]
143    pub fn get_skip_tags(&self) -> &[String] {
144        &self.skip_tags
145    }
146}
147
148/// Escapes exactly `& < > "` (SPEC §4); `'` stays so `don't` reads naturally.
149///
150/// ```
151/// use smooth_reading::escape_html;
152///
153/// assert_eq!(escape_html(r#"a < b & c > "d" 'e'"#), "a &lt; b &amp; c &gt; &quot;d&quot; 'e'");
154/// ```
155#[must_use]
156pub fn escape_html(text: &str) -> String {
157    let mut out = String::with_capacity(text.len());
158    push_escaped(&mut out, text);
159    out
160}
161
162fn push_escaped(out: &mut String, text: &str) {
163    for c in text.chars() {
164        match c {
165            '&' => out.push_str("&amp;"),
166            '<' => out.push_str("&lt;"),
167            '>' => out.push_str("&gt;"),
168            '"' => out.push_str("&quot;"),
169            _ => out.push(c),
170        }
171    }
172}
173
174/// The end offset of the markup starting at byte `pos` of `text` (which holds
175/// `<` or `&`), or `None` when it is ordinary text.
176///
177/// Mirrors the regular expression every other port uses:
178///
179/// ```text
180/// <!--.*?-->
181/// |<!\[CDATA\[.*?\]\]>
182/// |<[/!?][^>]*>
183/// |<[A-Za-z][^>]*>
184/// |&(?:#[0-9]+|#[xX][0-9a-fA-F]+|[A-Za-z][A-Za-z0-9]*);
185/// ```
186///
187/// An unterminated comment or CDATA block degrades to a declaration ending at
188/// the first `>`; an unterminated `<` or a bare `&` is text.
189fn markup_end(text: &str, pos: usize) -> Option<usize> {
190    let bytes = text.as_bytes();
191    let rest = &text[pos..];
192    match bytes[pos] {
193        b'<' => {
194            if let Some(body) = rest.strip_prefix("<!--") {
195                if let Some(end) = body.find("-->") {
196                    return Some(pos + 4 + end + 3);
197                }
198            }
199            if let Some(body) = rest.strip_prefix("<![CDATA[") {
200                if let Some(end) = body.find("]]>") {
201                    return Some(pos + 9 + end + 3);
202                }
203            }
204            match bytes.get(pos + 1) {
205                Some(&next) if matches!(next, b'/' | b'!' | b'?') || next.is_ascii_alphabetic() => {
206                    rest.find('>').map(|end| pos + end + 1)
207                }
208                _ => None,
209            }
210        }
211        b'&' => {
212            let body = &bytes[pos + 1..];
213            let mut i;
214            if body.first() == Some(&b'#') {
215                let hex = matches!(body.get(1), Some(b'x' | b'X'));
216                i = if hex { 2 } else { 1 };
217                let digits_start = i;
218                while body.get(i).is_some_and(|b| {
219                    if hex {
220                        b.is_ascii_hexdigit()
221                    } else {
222                        b.is_ascii_digit()
223                    }
224                }) {
225                    i += 1;
226                }
227                if i == digits_start {
228                    return None;
229                }
230            } else {
231                if !body.first().is_some_and(u8::is_ascii_alphabetic) {
232                    return None;
233                }
234                i = 1;
235                while body.get(i).is_some_and(u8::is_ascii_alphanumeric) {
236                    i += 1;
237                }
238            }
239            (body.get(i) == Some(&b';')).then_some(pos + 1 + i + 1)
240        }
241        _ => None,
242    }
243}
244
245/// The `(closing, lower-case name)` of a tag, or `None` for comments,
246/// declarations, processing instructions and character references.
247///
248/// Mirrors `<\s*(/?)\s*([A-Za-z][^\s/>]*)`: the name starts at the first ASCII
249/// letter (after an optional `/`, which may be surrounded by whitespace, so
250/// `</ code>` closes `code`) and runs until whitespace, `/` or `>`, so
251/// `<code.x>` is named `code.x`, not the skip tag `code`.
252fn tag_name(raw: &str) -> Option<(bool, String)> {
253    let body = raw.strip_prefix('<')?.trim_start();
254    let (closing, body) = match body.strip_prefix('/') {
255        Some(body) => (true, body.trim_start()),
256        None => (false, body),
257    };
258    if !body.starts_with(|c: char| c.is_ascii_alphabetic()) {
259        return None;
260    }
261    let end = body
262        .find(|c: char| c.is_whitespace() || c == '/' || c == '>')
263        .unwrap_or(body.len());
264    // Full Unicode lower-casing, like the Python and TypeScript ports (and the
265    // skip list above), so `<CODÉ>` matches a `codé` skip tag.
266    Some((closing, body[..end].to_lowercase()))
267}
268
269/// `<br/>` and `<code / >` are self-closing (`/\s*>$`); the trailing `/` may
270/// be spaced.
271fn is_self_closing(raw: &str) -> bool {
272    raw.strip_suffix('>')
273        .is_some_and(|body| body.trim_end().ends_with('/'))
274}
275
276/// A chunk of the input: raw markup to copy through, or prose to tokenize.
277#[derive(Debug, Clone, Copy, PartialEq, Eq)]
278enum Chunk<'a> {
279    Raw(&'a str),
280    Prose(&'a str),
281}
282
283/// Splits `text` into raw chunks (markup, character references and the
284/// content of `skipped` elements, emitted verbatim) and prose chunks.
285/// Character references therefore act as word boundaries.
286fn split_markup<'a>(text: &'a str, skipped: &HashSet<String>) -> Vec<Chunk<'a>> {
287    let mut chunks = Vec::new();
288    let mut skip_name: Option<String> = None; // the skip element we are inside, if any
289    let mut skip_depth = 0_usize; // nesting of that same element: <pre><pre>..</pre></pre>
290    let mut cursor = 0;
291    let mut pos = 0;
292    let bytes = text.as_bytes();
293    while pos < bytes.len() {
294        if bytes[pos] != b'<' && bytes[pos] != b'&' {
295            pos += 1;
296            continue;
297        }
298        let Some(end) = markup_end(text, pos) else {
299            pos += 1;
300            continue;
301        };
302        if pos > cursor {
303            let prose = &text[cursor..pos];
304            chunks.push(if skip_name.is_some() {
305                Chunk::Raw(prose)
306            } else {
307                Chunk::Prose(prose)
308            });
309        }
310        let raw = &text[pos..end];
311        chunks.push(Chunk::Raw(raw));
312        cursor = end;
313        pos = end;
314
315        let Some((closing, name)) = tag_name(raw) else {
316            continue;
317        };
318        if is_self_closing(raw) {
319            continue;
320        }
321        match &skip_name {
322            None => {
323                if !closing && skipped.contains(&name) {
324                    skip_name = Some(name);
325                    skip_depth = 1;
326                }
327            }
328            Some(current) if *current == name => {
329                if closing {
330                    skip_depth -= 1;
331                    if skip_depth == 0 {
332                        skip_name = None;
333                    }
334                } else {
335                    skip_depth += 1;
336                }
337            }
338            Some(_) => {}
339        }
340    }
341    if cursor < text.len() {
342        let prose = &text[cursor..];
343        chunks.push(if skip_name.is_some() {
344            Chunk::Raw(prose)
345        } else {
346            Chunk::Prose(prose)
347        });
348    }
349    chunks
350}
351
352fn push_wrapped(out: &mut String, tag: Option<&str>, class_name: Option<&str>, body: &str) {
353    let Some(tag) = tag else {
354        push_escaped(out, body);
355        return;
356    };
357    out.push('<');
358    out.push_str(tag);
359    if let Some(class_name) = class_name {
360        out.push_str(" class=\"");
361        push_escaped(out, class_name);
362        out.push('"');
363    }
364    out.push('>');
365    push_escaped(out, body);
366    out.push_str("</");
367    out.push_str(tag);
368    out.push('>');
369}
370
371fn render(out: &mut String, tokens: &[Token<'_>], html: &HtmlOptions) {
372    for token in tokens {
373        match *token {
374            Token::Word {
375                fixation,
376                fixation_text,
377                rest_text,
378                ..
379            } if fixation > 0 => {
380                push_wrapped(
381                    out,
382                    Some(html.get_tag()),
383                    html.get_class_name(),
384                    fixation_text,
385                );
386                // A fully emphasised word gets no (empty) rest element.
387                if !rest_text.is_empty() {
388                    push_wrapped(
389                        out,
390                        html.get_rest_tag(),
391                        html.get_rest_class_name(),
392                        rest_text,
393                    );
394                }
395            }
396            _ => push_escaped(out, token.text()),
397        }
398    }
399}
400
401/// Renders `text` as HTML with the leading part of each word emphasised
402/// (SPEC §4).
403///
404/// Each fixation is wrapped in the [`HtmlOptions`] `tag` (with `class_name`);
405/// the rest of the word is plain text unless `rest_tag` is given. Everything
406/// emitted as text has `& < > "` escaped.
407///
408/// With `ignore_html_tags` (the default) existing tags, comments and character
409/// references pass through verbatim, the content of `skip_tags` elements, plus
410/// `tag` and `rest_tag` themselves so already-emphasised markup is not
411/// wrapped twice, is left untouched, and the saccade count continues across
412/// markup. With `ignore_html_tags(false)` the input is plain text and every
413/// `<`, `>` and `&` is escaped.
414///
415/// ```
416/// use smooth_reading::{HtmlOptions, Options, to_html};
417///
418/// let (options, html) = (Options::new(), HtmlOptions::new());
419/// assert_eq!(to_html("Smooth reading works.", &options, &html), "<b>Smo</b>oth <b>read</b>ing <b>wor</b>ks.");
420/// assert_eq!(
421///     to_html("<p>Smooth</p> <code>x = 1</code> & <b>done</b>", &options, &html),
422///     "<p><b>Smo</b>oth</p> <code>x = 1</code> &amp; <b>done</b>"
423/// );
424/// assert_eq!(
425///     to_html("Tom & Jerry <3", &options, &html.clone().ignore_html_tags(false)),
426///     "<b>To</b>m &amp; <b>Jer</b>ry &lt;3"
427/// );
428/// ```
429#[must_use]
430pub fn to_html(text: &str, options: &Options, html: &HtmlOptions) -> String {
431    let mut out = String::with_capacity(text.len() * 2);
432    if !html.ignore_html_tags {
433        render(&mut out, &tokenize(text, options), html);
434        return out;
435    }
436    let skipped: HashSet<String> = html
437        .skip_tags
438        .iter()
439        .map(String::as_str)
440        .chain(Some(html.tag.as_str()))
441        .chain(html.rest_tag.as_deref())
442        .map(str::to_lowercase)
443        .collect();
444    let mut state = TokenizeState::default();
445    for chunk in split_markup(text, &skipped) {
446        match chunk {
447            Chunk::Raw(raw) => out.push_str(raw),
448            Chunk::Prose(prose) => {
449                let tokens = tokenize_with_state(prose, options, &mut state);
450                render(&mut out, &tokens, html);
451            }
452        }
453    }
454    out
455}
456
457/// Renders `text` as Markdown, wrapping each fixation in `marker`.
458///
459/// Nothing is escaped; the input is assumed to be Markdown already.
460///
461/// ```
462/// use smooth_reading::{Options, to_markdown};
463///
464/// assert_eq!(to_markdown("Smooth reading works.", &Options::new(), "**"), "**Smo**oth **read**ing **wor**ks.");
465/// ```
466#[must_use]
467pub fn to_markdown(text: &str, options: &Options, marker: &str) -> String {
468    let mut out = String::with_capacity(text.len() * 2);
469    for token in tokenize(text, options) {
470        match token {
471            Token::Word {
472                fixation,
473                fixation_text,
474                rest_text,
475                ..
476            } if fixation > 0 => {
477                out.push_str(marker);
478                out.push_str(fixation_text);
479                out.push_str(marker);
480                out.push_str(rest_text);
481            }
482            _ => out.push_str(token.text()),
483        }
484    }
485    out
486}