yaml_edit/nodes/

mod.rs

//! AST node types for YAML.
//!
//! # CST invariants
//!
//! yaml-edit is a lossless editor: every mutation produces text that
//! re-parses into the same tree shape (see [`crate::debug::roundtrip_ok`]
//! and [`crate::debug::validate_tree`]). To keep that property, all
//! mutation helpers in this module must uphold the following invariants
//! on the concrete syntax tree.
//!
//! ## Where whitespace lives
//!
//! For a block-style mapping entry `key:\n  - a`, the NEWLINE after
//! `key:` and the INDENT before the SEQUENCE both live inside the parent
//! VALUE, *not* inside the child SEQUENCE. The SEQUENCE_ENTRYs
//! themselves carry only the DASH, WHITESPACE, and content:
//!
//! ```text
//! MAPPING_ENTRY
//!   KEY ...
//!   COLON ":"
//!   VALUE
//!     NEWLINE "\n"
//!     INDENT "  "
//!     SEQUENCE
//!       SEQUENCE_ENTRY
//!         DASH "-"
//!         WHITESPACE " "
//!         SCALAR ...
//! ```
//!
//! Consequence: when constructing a fresh block SEQUENCE or MAPPING to
//! splice under a key, do **not** prepend its own leading INDENT for the
//! first entry - the parent VALUE already carries one. Duplicating it
//! renders as doubled indentation and violates the no-stacked-INDENT
//! check in [`crate::debug::validate_tree`].
//!
//! Comment and blank lines before a block collection's first entry live
//! in the parent as well, so removing the first entry moves the lines
//! after it out of the collection.
//!
//! For flow-style values (`{a: 1}`, `[1, 2]`) all separators live
//! *inside* the flow SEQUENCE / MAPPING: the parent VALUE has no direct
//! NEWLINE child. `value_is_block` in `mapping.rs` distinguishes the two
//! by looking for a NEWLINE token as a direct child of VALUE.
//!
//! The space after the colon belongs to MAPPING_ENTRY, before VALUE,
//! including for block values that start on the key line with an anchor,
//! tag or block scalar indicator (`key: &a\n  - a`, `key: |\n  text`).
//!
//! ## Entry termination
//!
//! Block-style MAPPING_ENTRY and SEQUENCE_ENTRY nodes are terminated by
//! a NEWLINE, the entry's own last token, after the comment ending its
//! line if there is one. A mapping entry keeps that comment in its VALUE,
//! a sequence entry after its item:
//!
//! ```text
//! SEQUENCE
//!   SEQUENCE_ENTRY
//!     DASH "-"
//!     WHITESPACE " "
//!     SCALAR ("a")
//!     WHITESPACE "  "
//!     COMMENT "# note"
//!     NEWLINE "\n"
//!   SEQUENCE_ENTRY ...
//! ```
//!
//! An explicit-key entry (`? key\n: value  # c\n`) is no different: its
//! VALUE holds the comment and the entry the NEWLINE ending the value's
//! line. One without a `:` line (`? key  # c\n`) has the comment after
//! its KEY, then its empty VALUE and the NEWLINE. An entry that ends in a
//! block node, a nested block collection or a block scalar, has its line
//! ended by that node. See [`trivia`].
//!
//! Two carve-outs:
//! - The **last** entry of a block collection may lack a terminator
//!   (unterminated sources like `a: 1\nb: 2` are legitimate YAML and
//!   must roundtrip).
//! - An explicit-key entry without a value whose key is a block node
//!   (`? - a\n`) ends in the zero-width `SCALAR { NULL "" }` of its value
//!   (see below), after the NEWLINE ending the key.
//!
//! An empty value never holds the lines after it. Where the parser looks
//! past the end of the line for a value and finds none, the line break
//! and whatever follows it are left to the entry and the collection, as
//! after any other value: `key:\n` is `VALUE { SCALAR { NULL "" } }`
//! followed by the entry's NEWLINE, and the INDENT, blank lines and
//! comment lines after it belong to the collection.
//!
//! The lines after a nested block collection's last entry, blank lines
//! and comment lines with their INDENT, belong to the collection that
//! holds the next entry, as the lines between its own entries do, or to
//! the root collection at the end of the document. A nested block
//! collection always ends in an entry:
//!
//! ```text
//! # m:\n  a: 1\n    # c\n\nz: 1\n
//! MAPPING
//!   MAPPING_ENTRY ("m")
//!     VALUE
//!       ...
//!       MAPPING
//!         MAPPING_ENTRY ("a: 1\n")
//!   INDENT "    "
//!   COMMENT "# c"
//!   NEWLINE "\n"
//!   NEWLINE "\n"
//!   MAPPING_ENTRY ("z") ...
//! ```
//!
//! When inserting a new sibling entry after an existing one, mutation
//! helpers must first ensure the predecessor is terminated
//! ([`trivia::terminate`]).
//!
//! ## Document-level trivia
//!
//! Trivia outside the root node lives in DOCUMENT: a leading BOM, blank
//! lines and comment lines before the root, and the NEWLINE and blank
//! lines after a scalar or flow-collection root. The file root holds
//! only what is outside every document: the lines before a `---` that
//! follows a comment, or before a directive, the lines after a `...`
//! and a stream of nothing but comments. A BOM must stay first in the
//! stream, so `---` and directives are inserted after it.
//!
//! ## Implicit-null values
//!
//! Every `MAPPING_ENTRY` and `SEQUENCE_ENTRY` holds a value node, even
//! when the source omits it. The parser emits a zero-width
//! `SCALAR { NULL "" }` at every "missing value" position:
//!
//! ```text
//! Source form                     CST shape
//! ------------------------------- ----------------------------------------
//! key:\n     (block mapping)      VALUE { SCALAR { NULL "" } }, NEWLINE
//! key:       (block mapping, EOF) VALUE { SCALAR { NULL "" } }
//! {key}      (flow mapping)       MAPPING_ENTRY { KEY { SCALAR "key" },
//!                                                 VALUE { SCALAR { NULL "" } } }
//! {key:}     (flow mapping)       MAPPING_ENTRY { KEY { SCALAR "key" },
//!                                                 COLON,
//!                                                 VALUE { SCALAR { NULL "" } } }
//! {,}        (flow mapping)       MAPPING_ENTRY { KEY   { SCALAR { NULL "" } },
//!                                                 VALUE { SCALAR { NULL "" } },
//!                                                 COMMA }
//! {: v}      (flow mapping)       KEY { SCALAR { NULL "" } }, COLON, VALUE ...
//! ? key\n    (explicit key)       MAPPING_ENTRY { QUESTION, KEY ...,
//!                                                 VALUE { SCALAR { NULL "" } },
//!                                                 NEWLINE }
//! {? : v}    (flow explicit key)  KEY { QUESTION, WHITESPACE,
//!                                       SCALAR { NULL "" } }, COLON, ...
//! [{]:\n     (missing `:`, error) KEY ..., COLON "",
//!                                 VALUE { SCALAR { NULL "" } }, NEWLINE
//! - \n       (block sequence)     SEQUENCE_ENTRY { DASH, WHITESPACE,
//!                                                  SCALAR { NULL "" }, NEWLINE }
//! [a, , c]   (flow sequence)      SEQUENCE_ENTRY { SCALAR { NULL "" }, COMMA, ... }
//! - !e\n     (tag, no content)    TAGGED_NODE { TAG, SCALAR { NULL "" } }
//! ```
//!
//! The invariant: **every KEY, every VALUE, every SEQUENCE_ENTRY holds
//! exactly one scalar or collection node.** Mappings wrap the value in a
//! `VALUE` node; sequences hold the scalar directly as a
//! `SEQUENCE_ENTRY` child (matching how each shape wraps its non-null
//! values -- sequences never had a wrapper, mappings always did).
//!
//! Error recovery keeps to the same shapes. A node with nothing to read
//! (`[}`, `{?`) is the zero-width null, and a token no entry can start,
//! like the `]` of `[]:\n]:`, goes in an ERROR node beside the entries,
//! as content after the end of a document does. What is left of a block
//! entry's line after its node (`a: :`, `- [a] ]`) stays in the entry's
//! slot, as more nodes, rather than opening another entry on that line.
//!
//! The zero-width `NULL ""` token renders as nothing, so round-trips are
//! lossless. This is distinct from a programmatically-written null,
//! which uses `SCALAR { NULL "null" }` (textual, four characters) so
//! the value is visible in the output.
//!
//! Consequences for mutation helpers:
//!
//! - Iterating `SEQUENCE_ENTRY` children with `matches!(kind, SCALAR |
//!   MAPPING | SEQUENCE | ALIAS | TAGGED_NODE)` finds the value in
//!   every entry, including implicit-null ones. `len` / `get` /
//!   `set` / `remove` therefore share the same set of indexes.
//! - `Scalar::is_null()` returns `true` for the zero-width form.
//! - `set(i, real_value)` on an implicit-null entry may need to insert
//!   a separating WHITESPACE that the original didn't have (the value
//!   was zero-width so no separator was needed). See `Sequence::set`
//!   for the `after_dash` pattern used in block sequences.
//!
//! ## No stacked INDENTs, no double trailing NEWLINEs
//!
//! Two adjacent INDENT tokens as direct children of the same node
//! concatenate at render time and produce visibly-wrong indentation
//! (this was the shape of issue #38). Two adjacent NEWLINE tokens at the
//! tail of a MAPPING_ENTRY or SEQUENCE_ENTRY render as a stray blank
//! line (issue #18).
//!
//! Both are checked by [`crate::debug::validate_tree`]; mutation helpers
//! must not produce either. Note the check for double NEWLINE is scoped
//! to *entries*, not their parent MAPPING / SEQUENCE containers: bare
//! NEWLINEs between entries (blank-line separators) are valid formatting
//! and appear at the container level.
//!
//! ## Flow separators live on the previous entry
//!
//! Inside a flow mapping or sequence, the COMMA between two entries is
//! stored after the *previous* entry's KEY / VALUE / SCALAR, not inside
//! the entry it precedes, along with anything before it and the rest of
//! its line: white space, a comment and the NEWLINE. An entry without a
//! comma owns the rest of its line the same way. Comment and blank lines
//! after that, and the INDENT of the next line, belong to the collection,
//! as between block entries:
//!
//! ```text
//! # {a: 1, # c\n # d\n b: 2\n}
//! MAPPING
//!   LEFT_BRACE "{"
//!   MAPPING_ENTRY ("a: 1, # c\n")
//!   INDENT " "
//!   COMMENT "# d"
//!   NEWLINE "\n"
//!   INDENT " "
//!   MAPPING_ENTRY ("b: 2\n")
//!   RIGHT_BRACE "}"
//! ```
//!
//! Inserters that append a new entry must add a `, ` suffix to the entry
//! they follow, not a `,` prefix on themselves. See
//! [`trivia::FlowSeparator`].
//!
//! ## Prefer targeted splices over whole-node rebuilds
//!
//! Reconstructing an entire MAPPING or SEQUENCE from a builder discards
//! anchors, tags, comments, quoting styles, and any tokens the fix
//! didn't know about. Mutation helpers should locate the specific
//! `NodeOrToken` range they need to change and use `splice_children`,
//! preserving the surrounding tokens.

use crate::lex::SyntaxKind;

/// YAML language type for rowan.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Lang {}

impl rowan::Language for Lang {
    type Kind = SyntaxKind;

    fn kind_from_raw(raw: rowan::SyntaxKind) -> Self::Kind {
        // SAFETY: SyntaxKind is #[repr(u16)] with contiguous discriminants
        // from ROOT = 0 through EOF, so every value in that range is a valid
        // variant. The bound is checked in every build, not just debug: a
        // stray value here would otherwise be undefined behaviour rather
        // than a panic.
        assert!(
            raw.0 <= SyntaxKind::EOF as u16,
            "raw SyntaxKind value {} is out of range (max {})",
            raw.0,
            SyntaxKind::EOF as u16,
        );
        unsafe { std::mem::transmute::<u16, SyntaxKind>(raw.0) }
    }

    fn kind_to_raw(kind: Self::Kind) -> rowan::SyntaxKind {
        kind.into()
    }
}

pub type SyntaxNode = rowan::SyntaxNode<Lang>;
pub type SyntaxToken = rowan::SyntaxToken<Lang>;

/// Detach `anchor` with the whitespace separating it from what follows it
/// on the same line, or else the space before it, so `k: &a 1` becomes
/// `k: 1` and `k: &a` followed by a block becomes `k:`.
pub(crate) fn detach_anchor(anchor: &SyntaxToken) {
    let separator = anchor
        .next_token()
        .filter(|t| t.kind() == SyntaxKind::WHITESPACE)
        .or_else(|| {
            anchor
                .prev_token()
                .filter(|t| t.kind() == SyntaxKind::WHITESPACE)
        });
    if let Some(separator) = separator {
        separator.detach();
    }
    anchor.detach();
}

/// Build a standalone `SyntaxToken` of `kind` with `text`, ready to
/// splice into a parent's child list via `splice_children`.
pub(crate) fn fresh_token(kind: SyntaxKind, text: &str) -> SyntaxToken {
    let mut builder = rowan::GreenNodeBuilder::new();
    builder.start_node(SyntaxKind::ROOT.into());
    builder.token(kind.into(), text);
    builder.finish_node();
    SyntaxNode::new_root_mut(builder.finish())
        .first_token()
        .expect("just built a token")
}

/// Put `ws` and `comment` at the end of the first line of `value`, a
/// mutable node holding a block scalar: on its header line, where the
/// parser keeps a comment following the indicator.
pub(crate) fn insert_header_comment(value: &SyntaxNode, ws: &str, comment: &str) {
    let header_end = value
        .descendants_with_tokens()
        .find(|c| c.kind() == SyntaxKind::NEWLINE)
        .expect("a block scalar's header ends with a line break");
    let parent = header_end.parent().expect("a token has a parent");
    let idx = header_end.index();
    insert_children(
        &parent,
        idx,
        vec![
            fresh_token(SyntaxKind::WHITESPACE, ws).into(),
            fresh_token(SyntaxKind::COMMENT, comment).into(),
        ],
    );
}

/// Whether `key` ends in an anchor or alias name, which would take in a
/// `:` written right after it: `*a:` is an alias to `a:`.
pub(crate) fn ends_in_property_name(key: &SyntaxNode) -> bool {
    key.last_token()
        .is_some_and(|t| matches!(t.kind(), SyntaxKind::ANCHOR | SyntaxKind::REFERENCE))
}

/// Put a space between the key of `entry` and the `:` right after it if
/// the key [ends in a property name](ends_in_property_name).
pub(crate) fn separate_key_from_colon(entry: &SyntaxNode) {
    let Some(key) = entry_key(entry).filter(ends_in_property_name) else {
        return;
    };
    if key
        .next_sibling_or_token()
        .is_some_and(|n| n.kind() == SyntaxKind::COLON)
    {
        let i = key.index() + 1;
        insert_children(
            entry,
            i,
            vec![fresh_token(SyntaxKind::WHITESPACE, " ").into()],
        );
    }
}

/// The node at the place of `node` in an immutable copy of its tree.
///
/// A mutable rowan tree works out each node's offset by walking up to the
/// root, so every step of a traversal costs the depth it is at. A pass that
/// only reads a whole tree runs on a copy to stay linear in its size.
pub(crate) fn immutable_copy(node: &SyntaxNode) -> SyntaxNode {
    let path: Vec<(usize, rowan::TextRange)> = node
        .ancestors()
        .take_while(|n| n.parent().is_some())
        .map(|n| (n.index(), n.text_range()))
        .collect();
    let root = node.ancestors().last().unwrap_or_else(|| node.clone());
    let missing = "the copy has the same shape as the tree";
    path.iter().rev().fold(
        SyntaxNode::new_root(root.green().into_owned()),
        |parent, &(index, range)| {
            // Find the child by its range rather than counting through the
            // ones before it, then step past any empty siblings beside it.
            let mut child = parent.child_or_token_at_range(range).expect(missing);
            while child.index() < index {
                child = child.next_sibling_or_token().expect(missing);
            }
            while child.index() > index {
                child = child.prev_sibling_or_token().expect(missing);
            }
            child.into_node().expect(missing)
        },
    )
}

/// The first direct child node of `parent` with the given `kind`, if any.
fn child_of_kind(parent: &SyntaxNode, kind: SyntaxKind) -> Option<SyntaxNode> {
    parent.children().find(|n| n.kind() == kind)
}

/// Does `parent` have a direct child token whose kind satisfies `pred`?
///
/// Flow/block style and several syntactic properties are decided by the
/// presence of a marker token (`{`, `[`, `|`, `:`) directly under a node,
/// never a nested one, so the search deliberately stays one level deep.
pub(crate) fn has_child_token(parent: &SyntaxNode, pred: impl Fn(SyntaxKind) -> bool) -> bool {
    parent
        .children_with_tokens()
        .any(|el| el.as_token().is_some_and(|t| pred(t.kind())))
}

/// The first direct child token of `parent` with the given `kind`, if any.
pub(crate) fn child_token(parent: &SyntaxNode, kind: SyntaxKind) -> Option<SyntaxToken> {
    parent
        .children_with_tokens()
        .filter_map(|el| el.into_token())
        .find(|t| t.kind() == kind)
}

/// Replace the children of `parent` in `range` with `children`.
///
/// rowan 0.16's `SyntaxNode::splice_children` detaches the range while
/// iterating over it, so it stops after the first element and leaves the
/// rest in place. Use this whenever the range can hold more than one child.
pub(crate) fn replace_children(
    parent: &SyntaxNode,
    range: std::ops::Range<usize>,
    mut children: Vec<rowan::NodeOrToken<SyntaxNode, SyntaxToken>>,
) {
    match_line_breaks(parent, &mut children);
    for i in range.clone().rev() {
        match parent
            .children_with_tokens()
            .nth(i)
            .expect("range within the parent's children")
        {
            rowan::NodeOrToken::Node(n) => n.detach(),
            rowan::NodeOrToken::Token(t) => t.detach(),
        }
    }
    parent.splice_children(range.start..range.start, children);
}

/// Insert `children` into `parent`'s child list at `at`.
pub(crate) fn insert_children(
    parent: &SyntaxNode,
    at: usize,
    children: Vec<rowan::NodeOrToken<SyntaxNode, SyntaxToken>>,
) {
    replace_children(parent, at..at, children);
}

/// Append `children` at the end of `parent`'s child list.
pub(crate) fn append_children(
    parent: &SyntaxNode,
    children: Vec<rowan::NodeOrToken<SyntaxNode, SyntaxToken>>,
) {
    insert_children(parent, parent.children_with_tokens().count(), children);
}

/// Rewrite the `\n` line breaks in `elements`, about to go into the tree
/// `node` is in, to the document's own line break.
///
/// Builders and fresh tokens always write `\n`; in a document using `\r\n`
/// or `\r` they would mix line endings. The document's line break is its
/// first one, as for the lexer's mixed line ending check. A document
/// without one keeps `\n`.
fn match_line_breaks(
    node: &SyntaxNode,
    elements: &mut [rowan::NodeOrToken<SyntaxNode, SyntaxToken>],
) {
    let tokens = |e: &rowan::NodeOrToken<SyntaxNode, SyntaxToken>| {
        let tokens: Vec<_> = match e {
            rowan::NodeOrToken::Node(n) => n
                .descendants_with_tokens()
                .filter_map(|c| c.into_token())
                .collect(),
            rowan::NodeOrToken::Token(t) => vec![t.clone()],
        };
        tokens
            .into_iter()
            .filter(|t| t.text().contains('\n') && !t.text().contains('\r'))
            .collect::<Vec<_>>()
    };
    let to_rewrite: Vec<_> = elements.iter().map(tokens).collect();
    if to_rewrite.iter().all(Vec::is_empty) {
        return;
    }
    let root = node.ancestors().last().expect("a node is its own ancestor");
    let Some(line_break) = root
        .descendants_with_tokens()
        .filter_map(|c| c.into_token())
        .find(|t| t.kind() == SyntaxKind::NEWLINE)
        .map(|t| t.text().to_string())
        .filter(|b| b != "\n")
    else {
        return;
    };
    for (element, tokens) in elements.iter_mut().zip(to_rewrite) {
        for token in tokens {
            let fresh = fresh_token(token.kind(), &token.text().replace('\n', &line_break));
            match element {
                rowan::NodeOrToken::Token(_) => *element = fresh.into(),
                rowan::NodeOrToken::Node(_) => {
                    let parent = token.parent().expect("a token in a node has a parent");
                    let i = token.index();
                    parent.splice_children(i..i + 1, vec![fresh.into()]);
                }
            }
        }
    }
}

/// Lay out the lines after `entry`, a block collection entry just
/// inserted, so that a block scalar its value ends in does not take them
/// in.
pub(crate) fn settle_lines_after_inserted_entry(entry: &SyntaxNode) {
    move_blank_lines_ahead_of_kept_scalar(entry);
    replaced_value::settle_lines_after_block_scalar(entry);
}

/// Move the blank lines straight after `entry`, a block collection entry
/// just inserted, to in front of its line, if its value ends in a kept
/// (`|+`, `>+`) block scalar.
///
/// Such a scalar takes every blank line after it into its value, so the
/// new entry goes after the blank lines rather than before them, leaving
/// the text around it as it was.
fn move_blank_lines_ahead_of_kept_scalar(entry: &SyntaxNode) {
    if !ends_with_kept_block_scalar(entry) {
        return;
    }
    let Some(line_end) = entry
        .last_token()
        .filter(|t| t.kind() == SyntaxKind::NEWLINE)
    else {
        return;
    };
    let mut lines = Vec::new();
    let mut next = line_end.next_token();
    loop {
        let space = next
            .clone()
            .filter(|t| matches!(t.kind(), SyntaxKind::INDENT | SyntaxKind::WHITESPACE));
        let Some(line_break) = space
            .as_ref()
            .map_or(next.clone(), |t| t.next_token())
            .filter(|t| t.kind() == SyntaxKind::NEWLINE)
        else {
            break;
        };
        next = line_break.next_token();
        lines.extend(space);
        lines.push(line_break);
    }
    if lines.is_empty() {
        return;
    }
    let moved: Vec<_> = lines
        .into_iter()
        .map(|t| {
            t.detach();
            fresh_token(t.kind(), t.text()).into()
        })
        .collect();

    // The lines go in front of the outermost element that starts the
    // entry's line, within the document.
    let first = entry.first_token().expect("an inserted entry has tokens");
    let line_start = std::iter::successors(Some(first), |t| {
        t.prev_token()
            .filter(|p| !matches!(p.kind(), SyntaxKind::NEWLINE | SyntaxKind::BOM))
    })
    .last()
    .expect("successors yields its first item");
    let mut at = rowan::NodeOrToken::Token(line_start.clone());
    while let Some(parent) = at
        .parent()
        .filter(|p| p.kind() != SyntaxKind::DOCUMENT && p.first_token() == Some(line_start.clone()))
    {
        at = rowan::NodeOrToken::Node(parent);
    }
    let parent = at.parent().expect("an inserted entry is in a document");
    let index = at.index();
    insert_children(&parent, index, moved);
}

/// Whether the last node `entry` holds is a kept (`|+`, `>+`) block scalar.
fn ends_with_kept_block_scalar(entry: &SyntaxNode) -> bool {
    ending_block_scalar(entry).is_some_and(|scalar| {
        scalar_node::block_scalar_indicators(&scalar).0 == scalar_node::Chomping::Keep
    })
}

/// The block scalar that is the last node `entry` holds, if any.
pub(crate) fn ending_block_scalar(entry: &SyntaxNode) -> Option<SyntaxNode> {
    let tokens: Vec<_> = entry
        .descendants_with_tokens()
        .filter_map(|c| c.into_token())
        .collect();
    tokens
        .iter()
        .rev()
        .filter(|t| !t.text().is_empty())
        .find_map(|t| {
            let parent = t.parent()?;
            let layout = matches!(
                t.kind(),
                SyntaxKind::NEWLINE | SyntaxKind::WHITESPACE | SyntaxKind::INDENT
            );
            match parent.kind() {
                SyntaxKind::SCALAR => Some(Some(parent)),
                _ if layout => None,
                _ => Some(None),
            }
        })
        .flatten()
        .filter(is_block_scalar)
}

/// The `children_with_tokens()` index of `parent`'s `index`-th child node of
/// the given kind.
pub(crate) fn nth_entry_index(
    parent: &SyntaxNode,
    kind: SyntaxKind,
    index: usize,
) -> Option<usize> {
    parent
        .children_with_tokens()
        .enumerate()
        .filter(|(_, c)| c.as_node().is_some_and(|n| n.kind() == kind))
        .map(|(i, _)| i)
        .nth(index)
}

/// How strings written into the flow collection `collection` are quoted.
///
/// If the string scalars among its keys and items are all double-quoted,
/// as in JSON, new strings are too; if any is plain or single-quoted, they
/// are quoted only where needed. A collection without string scalars of its
/// own goes by the nearest enclosing flow collection that has some, and
/// failing that quotes only where needed.
pub(crate) fn flow_quoting(collection: &SyntaxNode) -> crate::as_yaml::FlowQuoting {
    use crate::as_yaml::FlowQuoting;
    let is_flow = |n: &SyntaxNode| starts_a_flow_collection(n) || mapping::is_flow_pair(n);
    let own_quoting = |n: SyntaxNode| {
        let mut strings = n
            .children()
            .flat_map(|entry| entry.children())
            .flat_map(|c| match c.kind() {
                SyntaxKind::KEY | SyntaxKind::VALUE => c.children().collect(),
                _ => vec![c],
            })
            .filter(|c| c.kind() == SyntaxKind::SCALAR)
            .filter_map(|c| c.first_token())
            .filter(|t| t.kind() == SyntaxKind::STRING)
            .peekable();
        strings.peek()?;
        Some(if strings.all(|t| t.text().starts_with('"')) {
            FlowQuoting::Double
        } else {
            FlowQuoting::Minimal
        })
    };
    collection
        .ancestors()
        .filter(|n| matches!(n.kind(), SyntaxKind::MAPPING | SyntaxKind::SEQUENCE))
        .take_while(is_flow)
        .find_map(own_quoting)
        .unwrap_or(FlowQuoting::Minimal)
}

/// Emit `key`'s content for use inside a `KEY` node, of a flow mapping
/// quoting strings as `flow` says if it is set.
///
/// A block scalar or block collection, tagged or not, is written in flow
/// form instead: a block collection cannot be an implicit key, and a block
/// scalar does not read back as the same key, as the entry's `:` lands
/// inside the block. `indent` is the column of the entry, which a
/// multi-line key's continuation lines are shifted to clear.
pub(crate) fn build_key_content(
    builder: &mut rowan::GreenNodeBuilder,
    key: &impl crate::AsYaml,
    indent: usize,
    flow: Option<crate::as_yaml::FlowQuoting>,
) {
    if let Some(quoting) = flow {
        // Flow context already rules out block scalars.
        key.build_flow_content(builder, indent, quoting);
        return;
    }
    if let Some(key) = mapping::flow_form(key, 2, crate::as_yaml::FlowQuoting::Minimal) {
        return build_key_content(builder, &key, indent, None);
    }
    // flow_form leaves raw values that claim to be inline alone, but a
    // string with line breaks still renders as a block scalar, and a set as
    // a block mapping below its tag. In flow context both fit on one line.
    let spans_lines = key.value_node().is_none() && {
        let mut probe = rowan::GreenNodeBuilder::new();
        probe.start_node(SyntaxKind::ROOT.into());
        key.build_content(&mut probe, 0, false);
        probe.finish_node();
        SyntaxNode::new_root(probe.finish())
            .text()
            .contains_char('\n')
    };
    key.build_content(builder, indent, spans_lines);
}

/// Whether `key`, as [`build_key_content`] writes it, spans several lines,
/// which in a block mapping only an explicit key may do.
pub(crate) fn key_spans_lines(key: &impl crate::AsYaml) -> bool {
    let mut builder = rowan::GreenNodeBuilder::new();
    builder.start_node(SyntaxKind::ROOT.into());
    build_key_content(&mut builder, key, 0, None);
    builder.finish_node();
    SyntaxNode::new_root(builder.finish())
        .text()
        .contains_char('\n')
}

/// The `KEY` child of a `MAPPING_ENTRY`.
pub(crate) fn entry_key(entry: &SyntaxNode) -> Option<SyntaxNode> {
    child_of_kind(entry, SyntaxKind::KEY)
}

/// The `VALUE` child of a `MAPPING_ENTRY` or `SEQUENCE_ENTRY`.
pub(crate) fn entry_value(entry: &SyntaxNode) -> Option<SyntaxNode> {
    child_of_kind(entry, SyntaxKind::VALUE)
}

/// The node a KEY, VALUE or other holder wraps, as a
/// [`YamlNode`](crate::as_yaml::YamlNode).
pub(crate) fn held_node(holder: &SyntaxNode) -> Option<crate::as_yaml::YamlNode> {
    holder
        .children()
        .next()
        .and_then(crate::as_yaml::YamlNode::from_syntax)
}

/// A macro to create AST node wrappers.
macro_rules! ast_node {
    ($ast:ident, $kind:ident, $doc:expr) => {
        #[doc = $doc]
        #[doc = ""]
        #[doc = "**Note:** This type uses interior mutability through the rowan library."]
        #[doc = "Mutation methods work even when called through `&self`. See the crate-level"]
        #[doc = "documentation for details on the mutability model."]
        #[derive(Clone, PartialEq, Eq, Hash)]
        pub struct $ast(pub(crate) SyntaxNode);

        impl std::fmt::Debug for $ast {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.debug_struct(stringify!($ast))
                    .field("syntax", &self.0)
                    .finish()
            }
        }

        impl AstNode for $ast {
            type Language = Lang;

            fn can_cast(kind: SyntaxKind) -> bool {
                kind == SyntaxKind::$kind
            }

            fn cast(syntax: SyntaxNode) -> Option<Self> {
                if Self::can_cast(syntax.kind()) {
                    Some(Self(syntax))
                } else {
                    None
                }
            }

            fn syntax(&self) -> &SyntaxNode {
                &self.0
            }
        }

        impl std::fmt::Display for $ast {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                write!(f, "{}", self.0.text())
            }
        }
    };
}

pub(crate) use ast_node;
/// Emit the `byte_range` / `start_position` / `end_position` trio for a
/// wrapper whose `self.0` exposes `text_range()`. `$what` names the node
/// in the generated docs ("sequence", "comment", ...).
macro_rules! ast_node_spans {
    ($what:expr) => {
        #[doc = concat!("Get the byte offset range of this ", $what, " in the source text.")]
        #[doc = ""]
        #[doc = "Returns the start and end byte offsets as a `TextPosition`."]
        pub fn byte_range(&self) -> crate::TextPosition {
            self.0.text_range().into()
        }

        #[doc = concat!("Get the line and column where this ", $what, " starts.")]
        #[doc = ""]
        #[doc = "Requires the original source text to calculate line/column from byte"]
        #[doc = "offsets. Line and column numbers are 1-indexed."]
        #[doc = ""]
        #[doc = "# Arguments"]
        #[doc = ""]
        #[doc = "* `source_text` - The original YAML source text"]
        pub fn start_position(&self, source_text: &str) -> crate::LineColumn {
            crate::byte_offset_to_line_column(source_text, self.byte_range().start as usize)
        }

        #[doc = concat!("Get the line and column where this ", $what, " ends.")]
        #[doc = ""]
        #[doc = "Requires the original source text to calculate line/column from byte"]
        #[doc = "offsets. Line and column numbers are 1-indexed."]
        #[doc = ""]
        #[doc = "# Arguments"]
        #[doc = ""]
        #[doc = "* `source_text` - The original YAML source text"]
        pub fn end_position(&self, source_text: &str) -> crate::LineColumn {
            crate::byte_offset_to_line_column(source_text, self.byte_range().end as usize)
        }
    };
}

pub(crate) use ast_node_spans;

// Node modules
pub mod alias_node;
pub mod comment;
pub mod directive;
pub mod document;
mod empty_collection;
pub mod entry;
mod kept_aliases;
pub mod mapping;
mod predicates;
mod replaced_value;
pub mod scalar_node;
pub mod sequence;
pub mod tagged_node;
pub(crate) mod trivia;

pub(crate) use predicates::{
    in_flow_collection, is_block_scalar, is_quoted_scalar, starts_a_flow_collection,
};

// Re-exports
pub use alias_node::Alias;
pub use comment::Comment;
pub use directive::Directive;
pub use document::Document;
pub use entry::{Entry, OccupiedEntry, VacantEntry};
pub use mapping::{Mapping, MappingEntry};
pub use scalar_node::{Scalar, ScalarConversionError};
pub use sequence::Sequence;
pub use tagged_node::TaggedNode;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_replace_children_removes_whole_range() {
        let mut builder = rowan::GreenNodeBuilder::new();
        builder.start_node(SyntaxKind::ROOT.into());
        for text in ["a", "b", "c", "d", "e"] {
            builder.token(SyntaxKind::STRING.into(), text);
        }
        builder.finish_node();
        let root = SyntaxNode::new_root_mut(builder.finish());

        replace_children(
            &root,
            1..4,
            vec![fresh_token(SyntaxKind::STRING, "X").into()],
        );
        assert_eq!(root.to_string(), "aXe");
    }
}