Skip to main content

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}