oneyaml_syntax/tree/line.rs
1//! Edits at a line's end, with a
2//! byte-identical round trip.
3//!
4//! A block scalar's text ends with the line break that ends its last line
5//! (and, kept with `|+`/`>+`, the blank lines after it): that break is
6//! part of its token. Any other content ends before its line break, which
7//! is a [`SyntaxKind::LineBreak`] token of its own, placed at the
8//! outermost level that continues after it (C4). So replacing a block
9//! scalar by other content, or other content by a block scalar, moves a
10//! line break across levels, which one splice under one parent cannot do.
11//!
12//! The two primitives here take text that **ends its line** (a fragment
13//! whose text ends with a line break: a block scalar's, or a final
14//! [`SyntaxKind::LineBreak`] element) and put it in place of, or after, an
15//! element range that ends its line, placing the break where the parser
16//! does. They are one or two splices applied as one edit, each checked
17//! for well-formedness on the result and undone together when refused
18//! (see [`SyntaxTree::splice_pair`](super::SyntaxTree)).
19
20use super::edit::{Replaced, SpliceArgs, token_fragment};
21use super::{Fragment, Inserted, NodeId, SyntaxKind, SyntaxTree, TreeEditError};
22
23/// Where the line an element range ends on ends.
24#[derive(Clone, Copy)]
25enum LineEnd {
26 /// In the range's last token (a block scalar's text).
27 Inner,
28 /// A line break token right after the range, at any level.
29 Break(u32),
30 /// The end of the text (no line break).
31 Eof,
32}
33
34/// `with` holds only white space, comments, and line breaks (that is,
35/// lines of trivia, which the parser places at the outermost level that
36/// continues after the content before them, C4).
37fn trivia_lines(with: &Fragment) -> bool {
38 with.root_kinds().all(|k| {
39 matches!(
40 k,
41 SyntaxKind::Whitespace | SyntaxKind::Comment | SyntaxKind::LineBreak
42 )
43 })
44}
45
46impl SyntaxTree {
47 /// How the line that element `last` ends on ends.
48 fn line_end_after(&self, last: u32) -> Result<LineEnd, TreeEditError> {
49 // The range's text ends with a line break (a block scalar's, even
50 // an empty one whose last token has no bytes).
51 let (start, end) = self.nav_bytes(last).ok_or(TreeEditError::Internal)?;
52 if end > start {
53 let b = end.checked_sub(1).and_then(|i| self.byte_at(i));
54 if matches!(b, Some(b'\n' | b'\r')) {
55 return Ok(LineEnd::Inner);
56 }
57 }
58 match self.nav_after(last) {
59 None => Ok(LineEnd::Eof),
60 Some(c) => {
61 let at = self.nav_bytes(c).ok_or(TreeEditError::Internal)?.0;
62 if self.kind_of(c) == Some(SyntaxKind::LineBreak) && at == end {
63 Ok(LineEnd::Break(c))
64 } else {
65 Err(TreeEditError::NotWellFormed)
66 }
67 }
68 }
69 }
70
71 /// Where a line break ending content that ends right before `cut`
72 /// goes: before `cut` under its parent, or at the end of the stream.
73 fn outer_place(&self, cut: Option<u32>) -> Result<(u32, Option<u32>), TreeEditError> {
74 match cut {
75 Some(c) => Ok((
76 self.nav_parent(c).ok_or(TreeEditError::Internal)?,
77 self.nav_prev(c),
78 )),
79 None => Ok((0, self.nav_last(0))),
80 }
81 }
82
83 /// The inserted span without its last element when `dropped` (a line
84 /// break that went in with it).
85 fn body_span(
86 &self,
87 span: Option<(u32, u32)>,
88 dropped: bool,
89 ) -> Result<Inserted, TreeEditError> {
90 let (f, l) = span.ok_or(TreeEditError::Internal)?;
91 let l = if dropped && f != l {
92 self.nav_prev(l).ok_or(TreeEditError::Internal)?
93 } else {
94 l
95 };
96 Ok(Inserted {
97 first: self.id_of(f),
98 last: self.id_of(l),
99 })
100 }
101
102 /// Replaces the siblings `first..=last`, **through the end of their
103 /// line**, by `with`, whose text must end with a line break: the text
104 /// becomes the text before `first`, then `with`'s text, then the text
105 /// after the line break that ended the range's line (block scalars replaced or inserted at the end of a
106 /// collection or document).
107 ///
108 /// The range's line ends inside its last token (a block scalar's text
109 /// ends with its line break), at a [`SyntaxKind::LineBreak`] token
110 /// right after it (at whatever level the parser put it), or at the end
111 /// of the text. `with` ends its line inside its last token (a block
112 /// scalar), or with a final [`SyntaxKind::LineBreak`] element, which
113 /// goes where the parser puts it: after the collections the new
114 /// content ends, before what followed the old line. So `a: |\n x\n`
115 /// with the scalar replaced by `1\n` gives `a: 1\n`, and `a: 1\n`
116 /// with `1` replaced by `|\n x\n` gives `a: |\n x\n`.
117 ///
118 /// One or two splices, applied and checked for well-formedness as one
119 /// edit (refused, the tree is unchanged). O(depth + log R +
120 /// removed + inserted roots + windows). `inserted` names the
121 /// fragment's elements without a final line break element.
122 ///
123 /// # Errors
124 ///
125 /// Those of [`SyntaxTree::replace_range`];
126 /// [`TreeEditError::NotWellFormed`] also when the range's line goes on
127 /// after it (e.g. a comment follows) or `with`'s text does not end
128 /// with a line break; [`TreeEditError::EmptyFragment`] for a fragment
129 /// that is only a line break.
130 pub fn replace_to_line_end(
131 &mut self,
132 first: NodeId,
133 last: NodeId,
134 with: Fragment,
135 ) -> Result<Replaced, TreeEditError> {
136 let (f, l) = (self.live_slot(first)?, self.live_slot(last)?);
137 let (parent, roots) = self.sibling_range(f, l)?;
138 let pk = self.check_parent(parent)?;
139 self.check_removable(&roots)?;
140 if !with.ends_line() {
141 return Err(TreeEditError::NotWellFormed);
142 }
143 let (body, brk) = with.split_last_break()?;
144 if body.is_empty() || body.root_kinds().all(|k| k == SyntaxKind::LineBreak) {
145 return Err(TreeEditError::EmptyFragment);
146 }
147 self.check_insertable(parent, pk, &body)?;
148 let end = self.line_end_after(l)?;
149 let prev = self.nav_prev(f);
150 let cut = self.nav_after(l);
151 let had_break = brk.is_some();
152 // The old line end, when it is a token of its own, goes; the new
153 // one (a final break element) goes where content ending before
154 // `cut` puts it.
155 let (removed_break, outer_parent) = match end {
156 LineEnd::Break(b) => (Some(b), self.nav_parent(b)),
157 LineEnd::Inner | LineEnd::Eof => (None, cut.map_or(Some(0), |c| self.nav_parent(c))),
158 };
159 if outer_parent == Some(parent) || (removed_break.is_none() && brk.is_none()) {
160 // One splice: the break (if any) is a sibling of the range, or
161 // nothing moves across levels.
162 let mut removed = roots;
163 removed.extend(removed_break);
164 let fragment = match brk {
165 Some(b) => body.concat(b)?,
166 None => body,
167 };
168 let (taken, span) = self.splice(parent, prev, &removed, Some(fragment), true)?;
169 let mut taken = taken.ok_or(TreeEditError::Internal)?;
170 if removed_break.is_some() {
171 taken = taken.split_last_break()?.0;
172 }
173 return Ok(Replaced {
174 removed: taken,
175 inserted: self.body_span(span, had_break)?,
176 });
177 }
178 let first_args = SpliceArgs {
179 parent,
180 prev,
181 removed: roots,
182 fragment: Some(body),
183 };
184 let ((taken, span), _) = self.splice_pair(first_args, move |t, _| {
185 Ok(Some(match removed_break {
186 Some(b) => SpliceArgs {
187 parent: t.nav_parent(b).ok_or(TreeEditError::Internal)?,
188 prev: t.nav_prev(b),
189 removed: vec![b],
190 fragment: brk,
191 },
192 None => {
193 let (p, before) = t.outer_place(cut)?;
194 SpliceArgs {
195 parent: p,
196 prev: before,
197 removed: Vec::new(),
198 fragment: brk,
199 }
200 }
201 }))
202 })?;
203 Ok(Replaced {
204 removed: taken.ok_or(TreeEditError::Internal)?,
205 inserted: self.body_span(span, false)?,
206 })
207 }
208
209 /// Removes the siblings `first..=last`, **through the end of their
210 /// line**, and puts `trivia` (white space, comments, and line breaks
211 /// only, ending with a line break; `None`: nothing) where the parser
212 /// puts trivia after
213 /// the content before `first` (freeze gate:
214 /// removing the last entry of a block collection whose value is a
215 /// block scalar, as in a GitHub Actions `run: |` step or a ConfigMap's
216 /// `data`).
217 ///
218 /// The range's line ends inside its last token (a block scalar's text)
219 /// or at a [`SyntaxKind::LineBreak`] token right after it, which goes
220 /// too. `trivia` is typically the line end of the content before the
221 /// range (its same-line comment and line break): when the range is the
222 /// end of a collection, that trivia cannot stay inside it (the parser
223 /// never ends a node with trivia, C4) and goes after the collections
224 /// the content before `first` ends, before what followed the range's
225 /// line (or at the end of the stream). So in `a: 1\nb: |\n x\n` the
226 /// siblings from the line break after `1` through the block scalar,
227 /// removed with `trivia` = `\n`, give `a: 1\n` with the break after the
228 /// mapping; and in `o:\n a: |+\n x\n\n b: 1\nz: 2\n` the siblings
229 /// from the indentation of `b` through `1`, removed with `None`, give
230 /// `o:\n a: |+\n x\n\nz: 2\n` (the break after `1`, outside the
231 /// inner mapping, goes too: left alone, the kept scalar would read it).
232 ///
233 /// One or two splices, applied and checked for well-formedness as one
234 /// edit (refused, the tree is unchanged). Returns the removed
235 /// siblings (without the old line break token).
236 ///
237 /// # Errors
238 ///
239 /// Those of [`SyntaxTree::remove_range`];
240 /// [`TreeEditError::NotWellFormed`] also when the range's line goes on
241 /// after it or ends the text without a line break, or `trivia` holds
242 /// anything but white space, comments, and line breaks, or does not
243 /// end with a line break.
244 pub fn remove_to_line_end(
245 &mut self,
246 first: NodeId,
247 last: NodeId,
248 trivia: Option<Fragment>,
249 ) -> Result<Fragment, TreeEditError> {
250 let (f, l) = (self.live_slot(first)?, self.live_slot(last)?);
251 let (parent, roots) = self.sibling_range(f, l)?;
252 let parent_kind = self.check_parent(parent)?;
253 self.check_removable(&roots)?;
254 if trivia
255 .as_ref()
256 .is_some_and(|t| !t.ends_line() || !trivia_lines(t))
257 {
258 return Err(TreeEditError::NotWellFormed);
259 }
260 let with = trivia;
261 let prev = self.nav_prev(f);
262 // The old line end: inside the range (`None`), or a line break
263 // token right after it, which `with` replaces.
264 let (removed_break, cut) = match self.line_end_after(l)? {
265 LineEnd::Inner | LineEnd::Eof => (None, self.nav_after(l)),
266 LineEnd::Break(b) => (Some(b), Some(b)),
267 };
268 let outer = cut.map_or(Some(0), |c| self.nav_parent(c));
269 // One splice: the break (if any) and the trivia's place are under
270 // the range's parent, or there is neither.
271 if outer == Some(parent) || (removed_break.is_none() && with.is_none()) {
272 if let Some(w) = &with {
273 self.check_insertable(parent, parent_kind, w)?;
274 }
275 let mut removed = roots;
276 removed.extend(removed_break.filter(|_| outer == Some(parent)));
277 let (taken, _) = self.splice(parent, prev, &removed, with, true)?;
278 let mut taken = taken.ok_or(TreeEditError::Internal)?;
279 if removed_break.is_some() {
280 taken = taken.split_last_break()?.0;
281 }
282 return Ok(taken);
283 }
284 if let Some(w) = &with {
285 let o = outer.ok_or(TreeEditError::Internal)?;
286 let outer_kind = self.kind_of(o).ok_or(TreeEditError::Internal)?;
287 self.check_insertable(o, outer_kind, w)?;
288 }
289 let first_args = SpliceArgs {
290 parent,
291 prev,
292 removed: roots,
293 fragment: None,
294 };
295 let ((taken, _), _) = self.splice_pair(first_args, move |t, _| {
296 Ok(Some(match removed_break {
297 Some(b) => SpliceArgs {
298 parent: t.nav_parent(b).ok_or(TreeEditError::Internal)?,
299 prev: t.nav_prev(b),
300 removed: vec![b],
301 fragment: with,
302 },
303 None => {
304 let (p, before) = t.outer_place(cut)?;
305 SpliceArgs {
306 parent: p,
307 prev: before,
308 removed: Vec::new(),
309 fragment: with,
310 }
311 }
312 }))
313 })?;
314 taken.ok_or(TreeEditError::Internal)
315 }
316
317 /// Gives the block scalar that ends the text its final line break: the
318 /// scalar `sibling` ends (`a: |-\n x` at the end of the input) has a
319 /// last line that does not end, so nothing can follow it. Its text gets
320 /// `brk` (a line break: `\n`, `\r\n` or `\r`), after the white space
321 /// that ends the input behind it, if any (that white space is the text
322 /// of one more line of the scalar then: `- |+\n ` becomes
323 /// `- |+\n \n`). Lines can then go after it with
324 /// [`SyntaxTree::insert_line_after`].
325 ///
326 /// One or two splices applied and checked as one edit.
327 ///
328 /// # Errors
329 ///
330 /// [`TreeEditError::NotWellFormed`] when `sibling` does not end the text
331 /// in a block scalar without a final line break, or `brk` is not a line
332 /// break; [`TreeEditError::Stale`].
333 pub fn close_block_scalar(&mut self, sibling: NodeId, brk: &str) -> Result<(), TreeEditError> {
334 if !matches!(brk, "\n" | "\r\n" | "\r") {
335 return Err(TreeEditError::NotWellFormed);
336 }
337 let s = self.live_slot(sibling)?;
338 // White space ends the input behind the scalar, or nothing does.
339 let ws = match self.nav_after(s) {
340 None => None,
341 Some(w)
342 if self.kind_of(w) == Some(SyntaxKind::Whitespace)
343 && self.nav_after(w).is_none() =>
344 {
345 Some(w)
346 }
347 Some(_) => return Err(TreeEditError::NotWellFormed),
348 };
349 let tok = self.nav_last_leaf(s).ok_or(TreeEditError::NotWellFormed)?;
350 let kind = self.kind_of(tok).ok_or(TreeEditError::Internal)?;
351 if !matches!(kind, SyntaxKind::LiteralScalar | SyntaxKind::FoldedScalar) {
352 return Err(TreeEditError::NotWellFormed);
353 }
354 let mut text = super::Node::new(self, tok).text().into_owned();
355 if text.ends_with(['\n', '\r']) {
356 return Err(TreeEditError::NotWellFormed);
357 }
358 if let Some(w) = ws {
359 text.push_str(&super::Node::new(self, w).text());
360 }
361 // The block scalar's header, which the content token is read after.
362 let scalar = self.nav_parent(tok).ok_or(TreeEditError::Internal)?;
363 let mut header = None;
364 let mut at = self.nav_first(scalar);
365 while let Some(x) = at {
366 if self.kind_of(x) == Some(SyntaxKind::BlockScalarHeader) {
367 header = Some(super::Node::new(self, x).text().into_owned());
368 break;
369 }
370 at = self.nav_next(x);
371 }
372 let header = header.ok_or(TreeEditError::NotWellFormed)?;
373 let closed = block_token_fragment(kind, &header, &text, brk, &self.settings)?;
374 let first_args = SpliceArgs {
375 parent: scalar,
376 prev: self.nav_prev(tok),
377 removed: vec![tok],
378 fragment: Some(closed),
379 };
380 self.splice_pair(first_args, move |t, _| {
381 Ok(match ws {
382 Some(w) => Some(SpliceArgs {
383 parent: t.nav_parent(w).ok_or(TreeEditError::Internal)?,
384 prev: t.nav_prev(w),
385 removed: vec![w],
386 fragment: None,
387 }),
388 None => None,
389 })
390 })?;
391 Ok(())
392 }
393
394 /// Inserts `with`, whose text must end with a line break, as the lines
395 /// right after the line that `sibling` ends (see
396 /// [`SyntaxTree::replace_to_line_end`]): the text becomes the text
397 /// through that line's break, then `with`'s text, then the rest. The
398 /// new elements go under `sibling`'s parent, after it; the line
399 /// breaks go where the parser puts them. So in `a: |\n x\n` an entry
400 /// `b: 1\n` inserted after the scalar gives `a: |\n x\nb: 1\n`, and in
401 /// `a: 1\n` an entry `b: |\n y\n` inserted after `1` gives
402 /// `a: 1\nb: |\n y\n`.
403 ///
404 /// One or two splices, applied and checked as one edit.
405 /// `inserted` names what went in under the parent (a copy of
406 /// `sibling`'s line break first, when that break lies outside the
407 /// parent; without `with`'s final line break element).
408 ///
409 /// **Trivia**: `with` of white space, comments, and line
410 /// breaks only (comment lines) goes wholly where the parser puts trivia
411 /// after `sibling`'s line: right after `sibling`'s line break, under
412 /// that break's parent, or, when `sibling`'s line ends inside its own
413 /// text, before the element after it, under that element's parent (or
414 /// at the end of the stream). So comment lines after a root collection
415 /// that ends with a block scalar go at stream level. `inserted` names
416 /// all of `with`'s elements.
417 ///
418 /// # Errors
419 ///
420 /// Those of [`SyntaxTree::insert_after`];
421 /// [`TreeEditError::NotWellFormed`] also when `sibling`'s line goes on
422 /// after it or ends the text without a line break, or `with`'s text
423 /// does not end with one; [`TreeEditError::EmptyFragment`].
424 pub fn insert_line_after(
425 &mut self,
426 sibling: NodeId,
427 with: Fragment,
428 ) -> Result<Inserted, TreeEditError> {
429 let s = self.live_slot(sibling)?;
430 let parent = self.nav_parent(s).ok_or(TreeEditError::NoParent)?;
431 let pk = self.check_parent(parent)?;
432 if !with.ends_line() {
433 return Err(TreeEditError::NotWellFormed);
434 }
435 if trivia_lines(&with) {
436 let (p, before) = match self.line_end_after(s)? {
437 LineEnd::Eof => return Err(TreeEditError::NotWellFormed),
438 LineEnd::Break(b) => (self.nav_parent(b).ok_or(TreeEditError::Internal)?, Some(b)),
439 LineEnd::Inner => self.outer_place(self.nav_after(s))?,
440 };
441 let p_kind = self.check_parent(p)?;
442 self.check_insertable(p, p_kind, &with)?;
443 let (_, span) = self.splice(p, before, &[], Some(with), true)?;
444 return self.body_span(span, false);
445 }
446 let (body, brk) = with.split_last_break()?;
447 if body.is_empty() || body.root_kinds().all(|k| k == SyntaxKind::LineBreak) {
448 return Err(TreeEditError::EmptyFragment);
449 }
450 self.check_insertable(parent, pk, &body)?;
451 let end = self.line_end_after(s)?;
452 let had_break = brk.is_some();
453 match end {
454 LineEnd::Eof => Err(TreeEditError::NotWellFormed),
455 LineEnd::Break(b) if self.nav_parent(b) == Some(parent) => {
456 // The collection goes on after the break: the new lines go
457 // right after it, their breaks with them.
458 let fragment = match brk {
459 Some(x) => body.concat(x)?,
460 None => body,
461 };
462 let (_, span) = self.splice(parent, Some(b), &[], Some(fragment), true)?;
463 self.body_span(span, had_break)
464 }
465 LineEnd::Break(b) => {
466 // `sibling`'s break lies outside the parent: a copy of it
467 // goes in after `sibling`, then the new lines; the break
468 // itself goes, or becomes the new lines' final break.
469 let text = super::Node::new(self, b).text().into_owned();
470 let copy = token_fragment(SyntaxKind::LineBreak, &text, false, &self.settings)?;
471 let fragment = copy.concat(body)?;
472 let first_args = SpliceArgs {
473 parent,
474 prev: Some(s),
475 removed: Vec::new(),
476 fragment: Some(fragment),
477 };
478 let ((_, span), _) = self.splice_pair(first_args, move |t, _| {
479 Ok(Some(SpliceArgs {
480 parent: t.nav_parent(b).ok_or(TreeEditError::Internal)?,
481 prev: t.nav_prev(b),
482 removed: vec![b],
483 fragment: brk,
484 }))
485 })?;
486 self.body_span(span, false)
487 }
488 LineEnd::Inner => {
489 let cut = self.nav_after(s);
490 let outer = cut.map_or(Some(0), |c| self.nav_parent(c));
491 if brk.is_none() || outer == Some(parent) {
492 let fragment = match brk {
493 Some(x) => body.concat(x)?,
494 None => body,
495 };
496 let (_, span) = self.splice(parent, Some(s), &[], Some(fragment), true)?;
497 return self.body_span(span, had_break);
498 }
499 let first_args = SpliceArgs {
500 parent,
501 prev: Some(s),
502 removed: Vec::new(),
503 fragment: Some(body),
504 };
505 let ((_, span), _) = self.splice_pair(first_args, move |t, _| {
506 let (p, before) = t.outer_place(cut)?;
507 Ok(Some(SpliceArgs {
508 parent: p,
509 prev: before,
510 removed: Vec::new(),
511 fragment: brk,
512 }))
513 })?;
514 self.body_span(span, false)
515 }
516 }
517 }
518}
519
520/// The block scalar token of `kind` holding `text` and then `brk`, read
521/// through the parser after the scalar's `header` (the scalar's content
522/// token, copied out).
523fn block_token_fragment(
524 kind: SyntaxKind,
525 header: &str,
526 text: &str,
527 brk: &str,
528 settings: &oneyaml_core::Settings,
529) -> Result<Fragment, TreeEditError> {
530 let bad = TreeEditError::InvalidToken { kind };
531 let want = format!("{text}{brk}");
532 let tree = SyntaxTree::parse_with(format!("{header}{brk}{want}"), settings);
533 if tree.has_errors() {
534 return Err(bad);
535 }
536 let mut found = None;
537 for n in tree.root().descendants().filter(|n| n.is_token()) {
538 if n.kind() == kind {
539 if found.is_some() {
540 return Err(bad);
541 }
542 found = Some(n);
543 }
544 }
545 let token = found.ok_or(bad)?;
546 if token.text() != want {
547 return Err(TreeEditError::InvalidToken { kind });
548 }
549 let (arena, _) = tree.copy_forest(&[token.slot()])?;
550 Ok(Fragment {
551 arena,
552 context: String::new(),
553 has_tags: false,
554 })
555}