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 | |
| 22 | use crate::doc::{ |
| 23 | Align, |
| 24 | Attrs, |
| 25 | Block, |
| 26 | Cell, |
| 27 | Doc, |
| 28 | Inline, |
| 29 | Row, |
| 30 | Term, |
| 31 | }; |
| 32 | |
| 33 | use oxedyne_fe2o3_core::prelude::*; |
| 34 | |
| 35 | /// Renders a document as Djot. |
| 36 | pub 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. |
| 52 | fn 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. |
| 74 | fn 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. |
| 230 | fn 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. |
| 263 | fn 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? |
| 283 | fn 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. |
| 291 | fn 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. |
| 324 | fn 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. |
| 355 | fn 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. |
| 367 | const EMPH: u8 = 1; |
| 368 | const STRONG: u8 = 2; |
| 369 | const SUP: u8 = 4; |
| 370 | const 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. |
| 377 | fn 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("; |
| 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. |
| 447 | fn 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. |
| 469 | fn 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. |
| 491 | fn 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? |
| 513 | fn 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. |
| 523 | fn 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 | } |