mdman/format/
text.rs

Help
1//! Text formatter.
2
3use crate::util::{header_text, unwrap};
4use crate::EventIter;
5use anyhow::{bail, Error};
6use pulldown_cmark::{Alignment, Event, HeadingLevel, LinkType, Tag, TagEnd};
7use std::fmt::Write;
8use std::mem;
9use url::Url;
10
11pub struct TextFormatter {
12    url: Option<Url>,
13}
14
15impl TextFormatter {
16    pub fn new(url: Option<Url>) -> TextFormatter {
17        TextFormatter { url }
18    }
19}
20
21impl super::Formatter for TextFormatter {
22    fn render(&self, input: &str) -> Result<String, Error> {
23        TextRenderer::render(input, self.url.clone(), 0)
24    }
25
26    fn render_options_start(&self) -> &'static str {
27        // Tell pulldown_cmark to ignore this.
28        // This will be stripped out later.
29        "<![CDATA[\n"
30    }
31
32    fn render_options_end(&self) -> &'static str {
33        "]]>\n"
34    }
35
36    fn render_option(
37        &self,
38        params: &[&str],
39        block: &str,
40        _man_name: &str,
41    ) -> Result<String, Error> {
42        let rendered_options = params
43            .iter()
44            .map(|param| TextRenderer::render(param, self.url.clone(), 0))
45            .collect::<Result<Vec<_>, Error>>()?;
46        let trimmed: Vec<_> = rendered_options.iter().map(|o| o.trim()).collect();
47        // Wrap in HTML tags, they will be stripped out during rendering.
48        Ok(format!(
49            "<dt>{}</dt>\n<dd>\n{}</dd>\n<br>\n",
50            trimmed.join(", "),
51            block
52        ))
53    }
54
55    fn linkify_man_to_md(&self, name: &str, section: u8) -> Result<String, Error> {
56        Ok(format!("`{}`({})", name, section))
57    }
58}
59
60struct TextRenderer<'e> {
61    output: String,
62    indent: usize,
63    /// The current line being written. Once a line break is encountered (such
64    /// as starting a new paragraph), this will be written to `output` via
65    /// `flush`.
66    line: String,
67    /// The current word being written. Once a break is encountered (such as a
68    /// space) this will be written to `line` via `flush_word`.
69    word: String,
70    parser: EventIter<'e>,
71    /// The base URL used for relative URLs.
72    url: Option<Url>,
73    table: Table,
74}
75
76impl<'e> TextRenderer<'e> {
77    fn render(input: &str, url: Option<Url>, indent: usize) -> Result<String, Error> {
78        let parser = crate::md_parser(input, url.clone());
79        let output = String::with_capacity(input.len() * 3 / 2);
80        let mut mr = TextRenderer {
81            output,
82            indent,
83            line: String::new(),
84            word: String::new(),
85            parser,
86            url,
87            table: Table::new(),
88        };
89        mr.push_md()?;
90        Ok(mr.output)
91    }
92
93    fn push_md(&mut self) -> Result<(), Error> {
94        // If this is true, this is inside a cdata block used for hiding
95        // content from pulldown_cmark.
96        let mut in_cdata = false;
97        // The current list stack. None if unordered, Some if ordered with the
98        // given number as the current index.
99        let mut list: Vec<Option<u64>> = Vec::new();
100        // Used in some cases where spacing isn't desired.
101        let mut suppress_paragraph = false;
102        // Whether or not word-wrapping is enabled.
103        let mut wrap_text = true;
104
105        let mut last_seen_link_data = None;
106        while let Some((event, range)) = self.parser.next() {
107            let this_suppress_paragraph = suppress_paragraph;
108            // Always reset suppression, even if the next event isn't a
109            // paragraph. This is in essence, a 1-token lookahead where the
110            // suppression is only enabled if the next event is a paragraph.
111            suppress_paragraph = false;
112            match event {
113                Event::Start(tag) => {
114                    match tag {
115                        Tag::Paragraph => {
116                            if !this_suppress_paragraph {
117                                self.flush();
118                            }
119                        }
120                        Tag::Heading { level, .. } => {
121                            self.flush();
122                            if level == HeadingLevel::H1 {
123                                let text = header_text(&mut self.parser)?;
124                                self.push_to_line(&text.to_uppercase());
125                                self.hard_break();
126                                self.hard_break();
127                            } else if level == HeadingLevel::H2 {
128                                let text = header_text(&mut self.parser)?;
129                                self.push_to_line(&text.to_uppercase());
130                                self.flush();
131                                self.indent = 7;
132                            } else {
133                                let text = header_text(&mut self.parser)?;
134                                self.push_indent((level as usize - 2) * 3);
135                                self.push_to_line(&text);
136                                self.flush();
137                                self.indent = (level as usize - 1) * 3 + 1;
138                            }
139                        }
140                        Tag::BlockQuote(_kind) => {
141                            self.indent += 3;
142                        }
143                        Tag::CodeBlock(_kind) => {
144                            self.flush();
145                            wrap_text = false;
146                            self.indent += 4;
147                        }
148                        Tag::List(start) => list.push(start),
149                        Tag::Item => {
150                            self.flush();
151                            match list.last_mut().expect("item must have list start") {
152                                // Ordered list.
153                                Some(n) => {
154                                    self.push_indent(self.indent);
155                                    write!(self.line, "{}.", n)?;
156                                    *n += 1;
157                                }
158                                // Unordered list.
159                                None => {
160                                    self.push_indent(self.indent);
161                                    self.push_to_line("o ")
162                                }
163                            }
164                            self.indent += 3;
165                            suppress_paragraph = true;
166                        }
167                        Tag::FootnoteDefinition(_label) => unimplemented!(),
168                        Tag::Table(alignment) => {
169                            assert!(self.table.alignment.is_empty());
170                            self.flush();
171                            self.table.alignment.extend(alignment);
172                            let table = self.table.process(&mut self.parser, self.indent)?;
173                            self.output.push_str(&table);
174                            self.hard_break();
175                            self.table = Table::new();
176                        }
177                        Tag::TableHead | Tag::TableRow | Tag::TableCell => {
178                            bail!("unexpected table element")
179                        }
180                        Tag::Emphasis => {}
181                        Tag::Strong => {}
182                        // Strikethrough isn't usually supported for TTY.
183                        Tag::Strikethrough => self.word.push_str("~~"),
184                        Tag::Link {
185                            link_type,
186                            dest_url,
187                            ..
188                        } => {
189                            last_seen_link_data = Some((link_type.clone(), dest_url.to_owned()));
190                            if dest_url.starts_with('#') {
191                                // In a man page, page-relative anchors don't
192                                // have much meaning.
193                                continue;
194                            }
195                            match link_type {
196                                LinkType::Autolink | LinkType::Email => {
197                                    // The text is a copy of the URL, which is not needed.
198                                    match self.parser.next() {
199                                        Some((Event::Text(_), _range)) => {}
200                                        _ => bail!("expected text after autolink"),
201                                    }
202                                }
203                                LinkType::Inline
204                                | LinkType::Reference
205                                | LinkType::Collapsed
206                                | LinkType::Shortcut => {}
207                                // This is currently unused. This is only
208                                // emitted with a broken link callback, but I
209                                // felt it is too annoying to escape `[` in
210                                // option descriptions.
211                                LinkType::ReferenceUnknown
212                                | LinkType::CollapsedUnknown
213                                | LinkType::ShortcutUnknown => {
214                                    bail!(
215                                        "link with missing reference `{}` located at offset {}",
216                                        dest_url,
217                                        range.start
218                                    );
219                                }
220                            }
221                        }
222                        Tag::Image { .. } => {
223                            bail!("images are not currently supported")
224                        }
225                        Tag::HtmlBlock { .. }
226                        | Tag::MetadataBlock { .. }
227                        | Tag::DefinitionList
228                        | Tag::DefinitionListTitle
229                        | Tag::DefinitionListDefinition => {}
230                    }
231                }
232                Event::End(tag_end) => match &tag_end {
233                    TagEnd::Paragraph => {
234                        self.flush();
235                        self.hard_break();
236                    }
237                    TagEnd::Heading(..) => {}
238                    TagEnd::BlockQuote(..) => {
239                        self.indent -= 3;
240                    }
241                    TagEnd::CodeBlock => {
242                        self.hard_break();
243                        wrap_text = true;
244                        self.indent -= 4;
245                    }
246                    TagEnd::List(..) => {
247                        list.pop();
248                    }
249                    TagEnd::Item => {
250                        self.flush();
251                        self.indent -= 3;
252                        self.hard_break();
253                    }
254                    TagEnd::FootnoteDefinition => {}
255                    TagEnd::Table => {}
256                    TagEnd::TableHead => {}
257                    TagEnd::TableRow => {}
258                    TagEnd::TableCell => {}
259                    TagEnd::Emphasis => {}
260                    TagEnd::Strong => {}
261                    TagEnd::Strikethrough => self.word.push_str("~~"),
262                    TagEnd::Link => {
263                        if let Some((link_type, ref dest_url)) = last_seen_link_data {
264                            if dest_url.starts_with('#') {
265                                continue;
266                            }
267                            match link_type {
268                                LinkType::Autolink | LinkType::Email => {}
269                                LinkType::Inline
270                                | LinkType::Reference
271                                | LinkType::Collapsed
272                                | LinkType::Shortcut => self.flush_word(),
273                                _ => {
274                                    panic!("unexpected tag {:?}", tag_end);
275                                }
276                            }
277                            self.flush_word();
278                            write!(self.word, "<{}>", dest_url)?;
279                        }
280                    }
281                    TagEnd::HtmlBlock { .. }
282                    | TagEnd::MetadataBlock { .. }
283                    | TagEnd::DefinitionList
284                    | TagEnd::DefinitionListTitle
285                    | TagEnd::Image
286                    | TagEnd::DefinitionListDefinition => {}
287                },
288                Event::Text(t) | Event::Code(t) => {
289                    if wrap_text {
290                        let chunks = split_chunks(&t);
291                        for chunk in chunks {
292                            if chunk == " " {
293                                self.flush_word();
294                            } else {
295                                self.word.push_str(chunk);
296                            }
297                        }
298                    } else {
299                        for line in t.lines() {
300                            self.push_indent(self.indent);
301                            self.push_to_line(line);
302                            self.flush();
303                        }
304                    }
305                }
306                Event::Html(t) => {
307                    if t.starts_with("<![CDATA[") {
308                        // CDATA is a special marker used for handling options.
309                        in_cdata = true;
310                        self.flush();
311                    } else if in_cdata {
312                        if t.trim().ends_with("]]>") {
313                            in_cdata = false;
314                        } else {
315                            let trimmed = t.trim();
316                            if trimmed.is_empty() {
317                                continue;
318                            }
319                            if trimmed == "<br>" {
320                                self.hard_break();
321                            } else if trimmed.starts_with("<dt>") {
322                                let opts = unwrap(trimmed, "<dt>", "</dt>");
323                                self.push_indent(self.indent);
324                                self.push_to_line(opts);
325                                self.flush();
326                            } else if trimmed.starts_with("<dd>") {
327                                let mut def = String::new();
328                                while let Some((Event::Html(t), _range)) = self.parser.next() {
329                                    if t.starts_with("</dd>") {
330                                        break;
331                                    }
332                                    def.push_str(&t);
333                                }
334                                let rendered =
335                                    TextRenderer::render(&def, self.url.clone(), self.indent + 4)?;
336                                self.push_to_line(rendered.trim_end());
337                                self.flush();
338                            } else {
339                                self.push_to_line(&t);
340                                self.flush();
341                            }
342                        }
343                    } else {
344                        self.push_to_line(&t);
345                        self.flush();
346                    }
347                }
348                Event::FootnoteReference(_t) => {}
349                Event::SoftBreak => self.flush_word(),
350                Event::HardBreak => self.flush(),
351                Event::Rule => {
352                    self.flush();
353                    self.push_indent(self.indent);
354                    self.push_to_line(&"_".repeat(79 - self.indent * 2));
355                    self.flush();
356                }
357                Event::TaskListMarker(_b) => unimplemented!(),
358                Event::InlineHtml(..) => unimplemented!(),
359                Event::InlineMath(..) => unimplemented!(),
360                Event::DisplayMath(..) => unimplemented!(),
361            }
362        }
363        Ok(())
364    }
365
366    fn flush(&mut self) {
367        self.flush_word();
368        if !self.line.is_empty() {
369            self.output.push_str(&self.line);
370            self.output.push('\n');
371            self.line.clear();
372        }
373    }
374
375    fn hard_break(&mut self) {
376        self.flush();
377        if !self.output.ends_with("\n\n") {
378            self.output.push('\n');
379        }
380    }
381
382    fn flush_word(&mut self) {
383        if self.word.is_empty() {
384            return;
385        }
386        if self.line.len() + self.word.len() >= 79 {
387            self.output.push_str(&self.line);
388            self.output.push('\n');
389            self.line.clear();
390        }
391        if self.line.is_empty() {
392            self.push_indent(self.indent);
393            self.line.push_str(&self.word);
394        } else {
395            self.line.push(' ');
396            self.line.push_str(&self.word);
397        }
398        self.word.clear();
399    }
400
401    fn push_indent(&mut self, indent: usize) {
402        for _ in 0..indent {
403            self.line.push(' ');
404        }
405    }
406
407    fn push_to_line(&mut self, text: &str) {
408        self.flush_word();
409        self.line.push_str(text);
410    }
411}
412
413/// Splits the text on whitespace.
414///
415/// Consecutive whitespace is collapsed to a single ' ', and is included as a
416/// separate element in the result.
417fn split_chunks(text: &str) -> Vec<&str> {
418    let mut result = Vec::new();
419    let mut start = 0;
420    while start < text.len() {
421        match text[start..].find(' ') {
422            Some(i) => {
423                if i != 0 {
424                    result.push(&text[start..start + i]);
425                }
426                result.push(" ");
427                // Skip past whitespace.
428                match text[start + i..].find(|c| c != ' ') {
429                    Some(n) => {
430                        start = start + i + n;
431                    }
432                    None => {
433                        break;
434                    }
435                }
436            }
437            None => {
438                result.push(&text[start..]);
439                break;
440            }
441        }
442    }
443    result
444}
445
446struct Table {
447    alignment: Vec<Alignment>,
448    rows: Vec<Vec<String>>,
449    row: Vec<String>,
450    cell: String,
451}
452
453impl Table {
454    fn new() -> Table {
455        Table {
456            alignment: Vec::new(),
457            rows: Vec::new(),
458            row: Vec::new(),
459            cell: String::new(),
460        }
461    }
462
463    /// Processes table events and generates a text table.
464    fn process(&mut self, parser: &mut EventIter<'_>, indent: usize) -> Result<String, Error> {
465        while let Some((event, _range)) = parser.next() {
466            match event {
467                Event::Start(tag) => match tag {
468                    Tag::TableHead
469                    | Tag::TableRow
470                    | Tag::TableCell
471                    | Tag::Emphasis
472                    | Tag::Strong => {}
473                    Tag::Strikethrough => self.cell.push_str("~~"),
474                    // Links not yet supported, they usually won't fit.
475                    Tag::Link { .. } => {}
476                    _ => bail!("unexpected tag in table: {:?}", tag),
477                },
478                Event::End(tag_end) => match tag_end {
479                    TagEnd::Table => return self.render(indent),
480                    TagEnd::TableCell => {
481                        let cell = mem::replace(&mut self.cell, String::new());
482                        self.row.push(cell);
483                    }
484                    TagEnd::TableHead | TagEnd::TableRow => {
485                        let row = mem::replace(&mut self.row, Vec::new());
486                        self.rows.push(row);
487                    }
488                    TagEnd::Strikethrough => self.cell.push_str("~~"),
489                    _ => {}
490                },
491                Event::Text(t) | Event::Code(t) => {
492                    self.cell.push_str(&t);
493                }
494                Event::Html(t) => bail!("html unsupported in tables: {:?}", t),
495                _ => bail!("unexpected event in table: {:?}", event),
496            }
497        }
498        bail!("table end not reached");
499    }
500
501    fn render(&self, indent: usize) -> Result<String, Error> {
502        // This is an extremely primitive layout routine.
503        // First compute the potential maximum width of each cell.
504        // 2 for 1 space margin on left and right.
505        let width_acc = vec![2; self.alignment.len()];
506        let mut col_widths = self
507            .rows
508            .iter()
509            .map(|row| row.iter().map(|cell| cell.len()))
510            .fold(width_acc, |mut acc, row| {
511                acc.iter_mut()
512                    .zip(row)
513                    // +3 for left/right margin and | symbol
514                    .for_each(|(a, b)| *a = (*a).max(b + 3));
515                acc
516            });
517        // Shrink each column until it fits the total width, proportional to
518        // the columns total percent width.
519        let max_width = 78 - indent;
520        // Include total len for | characters, and +1 for final |.
521        let total_width = col_widths.iter().sum::<usize>() + col_widths.len() + 1;
522        if total_width > max_width {
523            let to_shrink = total_width - max_width;
524            // Compute percentage widths, and shrink each column based on its
525            // total percentage.
526            for width in &mut col_widths {
527                let percent = *width as f64 / total_width as f64;
528                *width -= (to_shrink as f64 * percent).ceil() as usize;
529            }
530        }
531        // Start rendering.
532        let mut result = String::new();
533
534        // Draw the horizontal line separating each row.
535        let mut row_line = String::new();
536        row_line.push_str(&" ".repeat(indent));
537        row_line.push('+');
538        let lines = col_widths
539            .iter()
540            .map(|width| "-".repeat(*width))
541            .collect::<Vec<_>>();
542        row_line.push_str(&lines.join("+"));
543        row_line.push('+');
544        row_line.push('\n');
545
546        // Draw top of the table.
547        result.push_str(&row_line);
548        // Draw each row.
549        for row in &self.rows {
550            // Word-wrap and fill each column as needed.
551            let filled = fill_row(row, &col_widths, &self.alignment);
552            // Need to transpose the cells across rows for cells that span
553            // multiple rows.
554            let height = filled.iter().map(|c| c.len()).max().unwrap();
555            for row_i in 0..height {
556                result.push_str(&" ".repeat(indent));
557                result.push('|');
558                for filled_row in &filled {
559                    let cell = &filled_row[row_i];
560                    result.push_str(cell);
561                    result.push('|');
562                }
563                result.push('\n');
564            }
565            result.push_str(&row_line);
566        }
567        Ok(result)
568    }
569}
570
571/// Formats a row, filling cells with spaces and word-wrapping text.
572///
573/// Returns a vec of cells, where each cell is split into multiple lines.
574fn fill_row(row: &[String], col_widths: &[usize], alignment: &[Alignment]) -> Vec<Vec<String>> {
575    let mut cell_lines = row
576        .iter()
577        .zip(col_widths)
578        .zip(alignment)
579        .map(|((cell, width), alignment)| fill_cell(cell, *width - 2, *alignment))
580        .collect::<Vec<_>>();
581    // Fill each cell to match the maximum vertical height of the tallest cell.
582    let max_lines = cell_lines.iter().map(|cell| cell.len()).max().unwrap();
583    for (cell, width) in cell_lines.iter_mut().zip(col_widths) {
584        if cell.len() < max_lines {
585            cell.extend(std::iter::repeat(" ".repeat(*width)).take(max_lines - cell.len()));
586        }
587    }
588    cell_lines
589}
590
591/// Formats a cell. Word-wraps based on width, and adjusts based on alignment.
592///
593/// Returns a vec of lines for the cell.
594fn fill_cell(text: &str, width: usize, alignment: Alignment) -> Vec<String> {
595    let fill_width = |text: &str| match alignment {
596        Alignment::None | Alignment::Left => format!(" {:<width$} ", text, width = width),
597        Alignment::Center => format!(" {:^width$} ", text, width = width),
598        Alignment::Right => format!(" {:>width$} ", text, width = width),
599    };
600    if text.len() < width {
601        // No wrapping necessary, just format.
602        vec![fill_width(text)]
603    } else {
604        // Word-wrap the cell.
605        let mut result = Vec::new();
606        let mut line = String::new();
607        for word in text.split_whitespace() {
608            if line.len() + word.len() >= width {
609                // todo: word.len() > width
610                result.push(fill_width(&line));
611                line.clear();
612            }
613            if line.is_empty() {
614                line.push_str(word);
615            } else {
616                line.push(' ');
617                line.push_str(&word);
618            }
619        }
620        if !line.is_empty() {
621            result.push(fill_width(&line));
622        }
623
624        result
625    }
626}
mdman/format/text.rs

mdman/format/
text.rs
