Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_text/src/doc/djot/write.rs

15.5 KiB, 15 runs

created by r1870400018:72231, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! Writing the document tree back out as Djot.
2//!
3//! The counterpart to [`parse`](crate::doc::djot::parse), and what an editor is handed: a stored
4//! section opens as Djot, the author changes it, and it reads back to a tree. The writer is faithful to
5//! the tree, not to the bytes it was first read from, and holds one invariant: for a tree `d` in the
6//! vocabulary the [module](crate::doc::djot) maps, `parse(&render(&d)) == d`.
7//!
8//! # Escaping is light, but total where it must be
9//!
10//! A character is escaped where it would otherwise read as markup, and nowhere else that a reader
11//! would notice. The emphasis marks, brackets, braces, backticks and the backslash itself are escaped
12//! wherever they fall in text, since any of them may pair with a mark further along the line; the
13//! characters that only open a block -- `#`, `>`, `-`, `+`, `:`, `|`, and the full stop or parenthesis
14//! after a leading number -- are escaped only where they begin a line.
15//!
16//! # Delimiters are forced only where they must be
17//!
18//! Emphasis, superscript and subscript are written plain, `_so_`, unless plain would not read back:
19//! where the content begins or ends in whitespace, or where the same mark is already open around it.
20//! Then the braced form Djot keeps for the purpose is written, `{_ so _}`.
21
22use crate::doc::{
23 Align,
24 Attrs,
25 Block,
26 Cell,
27 Doc,
28 Inline,
29 Row,
30 Term,
31};
32
33use oxedyne_fe2o3_core::prelude::*;
34
35/// Renders a document as Djot.
36pub fn render(doc: &Doc) -> String {
37 let mut out = String::new();
38 blocks(&mut out, &doc.blocks);
39 while out.ends_with("\n\n") {
40 out.pop();
41 }
42 if !out.is_empty() && !out.ends_with('\n') {
43 out.push('\n');
44 }
45 out
46}
47
48/// Writes a run of blocks, a blank line between each.
49///
50/// Two lists of one kind side by side would read as one, so the second takes the other marker of its
51/// kind, which is how Djot tells two lists apart.
52fn blocks(out: &mut String, bs: &[Block]) {
53 let mut prev: Option<(bool, bool)> = None; // (ordered, alt marker) of a list just written
54 for (i, b) in bs.iter().enumerate() {
55 if i > 0 {
56 out.push('\n');
57 }
58 let alt = match (prev, b) {
59 (Some((o, a)), Block::List { ordered, .. }) if o == *ordered => !a,
60 _ => false,
61 };
62 // Two definition lists side by side would read as one, so the second is given its
63 // attributes line, empty or not.
64 let after_terms = i > 0 && matches!(bs[i - 1], Block::Terms { .. });
65 one(out, b, alt, after_terms);
66 prev = match b {
67 Block::List { ordered, .. } => Some((*ordered, alt)),
68 _ => None,
69 };
70 }
71}
72
73/// Writes one block, a list in its alternative marker where `alt` says so.
74fn one(out: &mut String, block: &Block, alt: bool, after_terms: bool) {
75 match block {
76 Block::Heading { level, content } => {
77 for _ in 0..(*level).clamp(1, 6) {
78 out.push('#');
79 }
80 if !content.is_empty() {
81 out.push(' ');
82 inlines(out, content, false, 0, false);
83 }
84 out.push('\n');
85 }
86 Block::Para(content) => {
87 inlines(out, content, true, 0, false);
88 out.push('\n');
89 }
90 Block::Code { lang, text } => {
91 // A fence longer than any run of backticks inside, so the listing cannot close it.
92 let fence = "`".repeat((longest_run(text, '`') + 1).max(3));
93 out.push_str(&fence);
94 if let Some(lang) = lang {
95 out.push_str(lang);
96 }
97 out.push('\n');
98 out.push_str(text);
99 if !text.is_empty() && !text.ends_with('\n') {
100 out.push('\n');
101 }
102 out.push_str(&fence);
103 out.push('\n');
104 }
105 Block::Quote(inner) => {
106 let mut body = String::new();
107 blocks(&mut body, inner);
108 for line in body.lines() {
109 match line.is_empty() {
110 true => out.push_str(">\n"),
111 false => {
112 out.push_str("> ");
113 out.push_str(line);
114 out.push('\n');
115 }
116 }
117 }
118 }
119 Block::List { ordered, items } => {
120 for (n, item) in items.iter().enumerate() {
121 let marker = match (ordered, alt) {
122 (true, false) => fmt!("{}.", n + 1),
123 (true, true) => fmt!("{})", n + 1),
124 (false, false) => "-".to_string(),
125 (false, true) => "+".to_string(),
126 };
127 // The item is written as though it stood alone, and indented here by the width of
128 // its marker, so nesting is the sum of the markers above it.
129 let mut body = String::new();
130 blocks(&mut body, item);
131 let pad = " ".repeat(marker.chars().count() + 1);
132 if body.is_empty() {
133 out.push_str(&marker);
134 out.push('\n');
135 }
136 // Markers nested on one line, `- - -`, would read as a break, so such an item's body
137 // starts on the line after its marker.
138 let first = body.lines().next().unwrap_or("");
139 let split = is_rule(&fmt!("{} {}", marker, first));
140 if split {
141 out.push_str(&marker);
142 out.push('\n');
143 }
144 for (k, line) in body.lines().enumerate() {
145 match (k, line.is_empty()) {
146 (_, true) => out.push('\n'),
147 (0, false) if !split => {
148 out.push_str(&marker);
149 out.push(' ');
150 out.push_str(line);
151 out.push('\n');
152 }
153 (_, false) => {
154 out.push_str(&pad);
155 out.push_str(line);
156 out.push('\n');
157 }
158 }
159 }
160 }
161 }
162 // Not `---`, which after a `-` marker reads as a break rather than an item holding one.
163 Block::Rule => out.push_str("***\n"),
164 Block::Table { head, rows, cols, caption } => {
165 table(out, head, rows, cols);
166 if !caption.is_empty() {
167 out.push_str("\n^ ");
168 inlines(out, caption, false, 0, false);
169 out.push('\n');
170 }
171 }
172 Block::Div { attrs: a, content } => {
173 let fence = ":::";
174 out.push_str(fence);
175 out.push(' ');
176 // A division classed `figure` alone takes the brace group, the bare word being a figure's.
177 match a.id.is_none() && a.pairs.is_empty() && a.classes.len() == 1 && bare(&a.classes[0])
178 && a.classes[0] != "figure"
179 {
180 true => out.push_str(&a.classes[0]),
181 false => attrs(out, a),
182 }
183 out.push('\n');
184 blocks(out, content);
185 out.push_str(fence);
186 out.push('\n');
187 }
188 Block::Figure { attrs: a, content, caption } => {
189 out.push_str("::: figure");
190 if !a.is_empty() {
191 out.push(' ');
192 attrs(out, a);
193 }
194 out.push('\n');
195 blocks(out, content);
196 if !caption.is_empty() {
197 // A table last in the figure would take the figure's caption for its own, so one
198 // with none is given its empty caption first.
199 if let Some(Block::Table { caption: c, .. }) = content.last() {
200 if c.is_empty() {
201 out.push_str("\n^\n");
202 }
203 }
204 if !content.is_empty() {
205 out.push('\n');
206 }
207 out.push_str("^ ");
208 inlines(out, caption, false, 0, false);
209 out.push('\n');
210 }
211 out.push_str(":::\n");
212 }
213 Block::Terms { attrs: a, items } => {
214 if !a.is_empty() || after_terms {
215 attrs(out, a);
216 out.push('\n');
217 }
218 for (n, t) in items.iter().enumerate() {
219 if n > 0 {
220 out.push('\n');
221 }
222 term(out, t);
223 }
224 }
225 }
226}
227
228/// Writes one item of a definition list: `: ` and the term, then each definition indented beneath
229/// it, a `::` line before every one but a first that holds something.
230fn term(out: &mut String, t: &Term) {
231 let mut body = String::new();
232 inlines(&mut body, &t.term, true, 0, false);
233 body.push('\n');
234 for (k, d) in t.defs.iter().enumerate() {
235 body.push('\n');
236 if k > 0 || d.is_empty() {
237 body.push_str("::\n");
238 if !d.is_empty() {
239 body.push('\n');
240 }
241 }
242 blocks(&mut body, d);
243 }
244 for (k, line) in body.lines().enumerate() {
245 match (k, line.is_empty()) {
246 (0, true) => out.push(':'),
247 (0, false) => {
248 out.push_str(": ");
249 out.push_str(line);
250 }
251 (_, true) => {}
252 (_, false) => {
253 out.push_str(" ");
254 out.push_str(line);
255 }
256 }
257 out.push('\n');
258 }
259}
260
261/// The `heads` value a table needs, if its header flags are not the ones a reader gives by default:
262/// every cell of the header row a header, and no cell of the body.
263fn heads(head: &Option<Row>, rows: &[Row], n: usize) -> Option<String> {
264 let flag = |r: &Row, i: usize, dflt: bool| r.0.get(i).map_or(dflt, |c| c.header);
265 let head_all = head.as_ref().map_or(true, |h| (0..n).all(|i| flag(h, i, true)));
266 if head_all && rows.iter().all(|r| (0..n).all(|i| !flag(r, i, false))) {
267 return None;
268 }
269 if head_all && !rows.is_empty() && rows.iter().all(|r| (0..n).all(|i| flag(r, i, false) == (i == 0))) {
270 return Some("rows".to_string());
271 }
272 let mut words = Vec::new();
273 if let Some(h) = head {
274 words.push((0..n).map(|i| if flag(h, i, true) { '1' } else { '0' }).collect::<String>());
275 }
276 for r in rows {
277 words.push((0..n).map(|i| if flag(r, i, false) { '1' } else { '0' }).collect::<String>());
278 }
279 Some(words.join(" "))
280}
281
282/// Does the class name stand alone after a division's colons, as `::: note` does?
283fn bare(class: &str) -> bool {
284 !class.is_empty()
285 && !class.starts_with('.')
286 && !class.starts_with('{')
287 && !class.chars().any(|c| c.is_whitespace())
288}
289
290/// Writes a brace group: the id, the classes, then the pairs, each value quoted.
291fn attrs(out: &mut String, a: &Attrs) {
292 out.push('{');
293 let mut first = true;
294 let mut sep = |out: &mut String| {
295 if !first {
296 out.push(' ');
297 }
298 first = false;
299 };
300 if let Some(id) = &a.id {
301 sep(out);
302 out.push('#');
303 out.push_str(id);
304 }
305 for c in &a.classes {
306 sep(out);
307 out.push('.');
308 out.push_str(c);
309 }
310 for (k, v) in &a.pairs {
311 sep(out);
312 out.push_str(k);
313 out.push_str("=\"");
314 out.push_str(v);
315 out.push('"');
316 }
317 out.push('}');
318}
319
320/// Writes a pipe table: the header row where there is one, the delimiter row, then the body.
321///
322/// A table with no header starts at its delimiter row, which Djot reads as aligning the columns and
323/// heading none.
324fn table(out: &mut String, head: &Option<Row>, rows: &[Row], cols: &[Align]) {
325 let n = head.iter().chain(rows).map(|r| r.0.len()).max().unwrap_or(0).max(cols.len());
326 if n == 0 {
327 return;
328 }
329 if let Some(v) = heads(head, rows, n) {
330 out.push_str("{heads=\"");
331 out.push_str(&v);
332 out.push_str("\"}\n");
333 }
334 if let Some(h) = head {
335 row(out, h, n);
336 }
337 out.push('|');
338 for i in 0..n {
339 let bar = match cols.get(i).copied().unwrap_or(Align::None) {
340 Align::None => " --- ",
341 Align::Start => " :-- ",
342 Align::Centre => " :-: ",
343 Align::End => " --: ",
344 };
345 out.push_str(bar);
346 out.push('|');
347 }
348 out.push('\n');
349 for r in rows {
350 row(out, r, n);
351 }
352}
353
354/// Writes one row of a table, padded to the width of the widest.
355fn row(out: &mut String, r: &Row, n: usize) {
356 let empty = Cell::default();
357 out.push('|');
358 for i in 0..n {
359 out.push(' ');
360 inlines(out, &r.0.get(i).unwrap_or(&empty).content, false, 0, true);
361 out.push_str(" |");
362 }
363 out.push('\n');
364}
365
366// Marks open around the inline being written.
367const EMPH: u8 = 1;
368const STRONG: u8 = 2;
369const SUP: u8 = 4;
370const SUB: u8 = 8;
371
372/// Writes a run of inline content.
373///
374/// `start` says whether what follows begins a line, which decides the block escapes; `open` holds the
375/// marks already open around the run, which decides whether a mark must be braced; and `cell` says the
376/// run is a table cell, where a pipe would end it.
377fn inlines(out: &mut String, content: &[Inline], start: bool, open: u8, cell: bool) {
378 let mut start = start;
379 let mut bare_img: Option<usize> = None; // where an image with no attrs ended
380 for item in content {
381 let after_img = bare_img.take();
382 match item {
383 Inline::Text(text) => escape(out, text, start, cell),
384 Inline::Emph { strong, content } => match strong {
385 true => mark(out, '*', STRONG, content, open, cell),
386 false => mark(out, '_', EMPH, content, open, cell),
387 },
388 Inline::Sup(content) => mark(out, '^', SUP, content, open, cell),
389 Inline::Sub(content) => mark(out, '~', SUB, content, open, cell),
390 Inline::Link { to, content } => {
391 // A bracket is read as a run of its own, so no mark is open inside it.
392 out.push('[');
393 inlines(out, content, false, 0, cell);
394 out.push_str("](");
395 dest(out, to, cell);
396 out.push(')');
397 }
398 Inline::Image { src, alt, attrs: a } => {
399 out.push_str("![");
400 escape(out, alt, false, cell);
401 out.push_str("](");
402 dest(out, src, cell);
403 out.push(')');
404 if !a.is_empty() {
405 attrs(out, a);
406 }
407 if a.is_empty() {
408 bare_img = Some(out.len());
409 }
410 }
411 Inline::Code(code) => {
412 let fence = "`".repeat(longest_run(code, '`') + 1);
413 // The reader takes one space off each end where both ends have one, so a span that
414 // would lose a space, or that begins or ends with a backtick, is padded.
415 let pad = code.starts_with('`') || code.ends_with('`')
416 || (code.starts_with(' ') && code.ends_with(' ') && !code.trim().is_empty());
417 out.push_str(&fence);
418 if pad {
419 out.push(' ');
420 }
421 out.push_str(code);
422 if pad {
423 out.push(' ');
424 }
425 out.push_str(&fence);
426 }
427 Inline::Span { attrs: a, content } => {
428 out.push('[');
429 inlines(out, content, false, 0, cell);
430 out.push(']');
431 attrs(out, a);
432 }
433 Inline::Break => out.push_str("\\\n"),
434 }
435 start = matches!(item, Inline::Break);
436 // An image takes a brace group against it as its attrs, so one that a forced mark follows is
437 // given its empty group.
438 if let Some(at) = after_img {
439 if out[at..].starts_with('{') {
440 out.insert_str(at, "{}");
441 }
442 }
443 }
444}
445
446/// Writes a pair of marks around their content, braced where plain marks would not read back.
447fn mark(out: &mut String, ch: char, bit: u8, content: &[Inline], open: u8, cell: bool) {
448 let mut inner = String::new();
449 inlines(&mut inner, content, false, open | bit, cell);
450 let braced = open & bit != 0
451 || inner.is_empty()
452 || inner.starts_with(char::is_whitespace)
453 || inner.ends_with(char::is_whitespace);
454 if braced {
455 out.push('{');
456 }
457 out.push(ch);
458 out.push_str(&inner);
459 out.push(ch);
460 if braced {
461 out.push('}');
462 }
463}
464
465/// Writes a link or image destination: plain, or in angle brackets where it holds whitespace.
466///
467/// Every character the inline pass could take for markup is escaped, including the brackets and
468/// backticks, since a destination inside a bracket is scanned by the bracket's own search for its end.
469fn dest(out: &mut String, to: &str, cell: bool) {
470 let angled = to.chars().any(char::is_whitespace);
471 if angled {
472 out.push('<');
473 }
474 for c in to.chars() {
475 let esc = match c {
476 '\\' | '(' | ')' | '<' | '>' | '[' | ']' | '`' => true,
477 '|' => cell,
478 _ => false,
479 };
480 if esc {
481 out.push('\\');
482 }
483 out.push(c);
484 }
485 if angled {
486 out.push('>');
487 }
488}
489
490/// Writes text with the characters that would read as markup escaped.
491fn escape(out: &mut String, text: &str, start: bool, cell: bool) {
492 // A number opening a line is a list marker when a full stop or parenthesis follows it.
493 let digits = text.bytes().take_while(|b| b.is_ascii_digit()).count();
494 let last = text.char_indices().last().map(|(i, _)| i);
495 for (i, c) in text.char_indices() {
496 let esc = match c {
497 '\\' | '`' | '*' | '_' | '^' | '~' | '[' | ']' | '{' | '}' | '<' => true,
498 // Before a bracket it would make an image of a link.
499 '!' => Some(i) == last,
500 '|' => cell || (start && i == 0),
501 '#' | '>' | '+' | ':' | '-' if i == 0 => start || (cell && matches!(c, '-' | ':')),
502 '.' | ')' if start && digits > 0 && i == digits => true,
503 _ => false,
504 };
505 if esc {
506 out.push('\\');
507 }
508 out.push(c);
509 }
510}
511
512/// Would the line read as a thematic break: three or more of one of `-`, `*` or `_`, and spaces?
513fn is_rule(line: &str) -> bool {
514 let t = line.trim();
515 let ch = match t.chars().next() {
516 Some(c @ ('-' | '*' | '_')) => c,
517 _ => return false,
518 };
519 t.chars().all(|c| c == ch || c == ' ' || c == '\t') && t.chars().filter(|c| *c == ch).count() >= 3
520}
521
522/// The longest unbroken run of a character in a string.
523fn longest_run(s: &str, c: char) -> usize {
524 let mut best = 0;
525 let mut run = 0;
526 for k in s.chars() {
527 match k == c {
528 true => {
529 run += 1;
530 best = best.max(run);
531 }
532 false => run = 0,
533 }
534 }
535 best
536}