extension PureYAML.Parsing.LibYAML.Scanner { /// Which step of `runPlainScalarLoop`'s outer iteration a suspend happened /// at. Resuming must land back on the step that was actually interrupted, /// not on whatever step normally follows it, and in particular must never /// redo a decision (document marker, comment, or "does a blank/break run /// follow") that a *previous, already-passed* check already answered: /// `.start`'s document-marker/`#` checks and `.afterContent`'s blank/break /// guard are only meant to run once, at a genuine entry point, not at an /// arbitrary position inside an already-in-progress content or break run. /// A first version of this type resumed a dry `consumePlainContent` via /// `.start` on the (wrong) assumption that redoing its checks was harmless; /// it is not; if the resume position happens to land on a literal `#` /// that is legitimate mid-scalar content (e.g. a value containing every /// printable character), `.start`'s comment check wrongly ends the scalar /// right there. `consumePlainContent` and `consumePlainBreaks` each get /// their own dedicated "continue this same call, no pre-check" case /// (`.consumingContent`, `.consumingBreaks`) for exactly this reason. enum PlainScalarPhase: Equatable { /// Check for a document marker or comment, then consume content. case start /// Inside consuming an already-started content run (the document /// marker/comment checks that gated entry into it do not apply here). case consumingContent /// Content just finished; decide whether a blank/break run follows. case afterContent /// Inside consuming an already-confirmed blank/break run. case consumingBreaks /// A blank/break run just finished; check whether the scalar dedents. case afterBreaks } /// Thrown by `runPlainScalarLoop` when accumulating a plain scalar's content /// runs dry (`Reader.ranDry`) while `!Reader.isFinal`. Carries everything /// `resumePlainScalar(_:)` needs to continue from exactly this point once more /// input is appended, rather than rescanning the scalar's content from its /// start. `scanStep()` catches this specifically and stores it on /// `Scanner.suspendedPlainScalar`, distinct from a generic dry-run catch: no /// checkpoint restore happens for this error, since the whole point is to keep /// the reader position and accumulated content rather than discard them. struct PlainScalarSuspended: Swift.Error { var state: PlainState var indent: Int var startMark: PureYAML.Parsing.Mark var phase: PlainScalarPhase } private typealias Classify = PureYAML.Parsing.LibYAML.CharacterClass /// The folding state carried through `scan_plain_scalar`: the accumulated /// value plus the pending leading break, trailing breaks, and whitespace that /// are folded in before the next content character. Internal rather than /// private: `PlainScalarSuspended` carries one across a `scanStep()` suspend /// point, so `Scanner`'s own file needs to name the type for its stored /// `suspendedPlainScalar` property. struct PlainState { var string = "" var leadingBreak = "" var trailingBreaks = "" var whitespaces = "" var leadingBlanks = false var endMark: PureYAML.Parsing.Mark } /// Port of `yaml_parser_scan_plain_scalar`. Consumes a plain scalar, folding /// line breaks: a single break between non-empty lines becomes a space, blank /// lines become literal newlines, and leading/trailing whitespace on folded /// lines is dropped. Ends at a `: ` value indicator, a comment, a less-indented /// line (block context), a flow indicator (flow context), or a document marker. mutating func scanPlainScalar() throws -> PureYAML.Parsing.LibYAML.Token { let indent = indentEngine.indent + 1 let startMark = reader.mark var state = PlainState(endMark: reader.mark) try runPlainScalarLoop(&state, indent: indent, startMark: startMark) return finishPlainScalar(state, startMark: startMark) } /// Resumes a plain scalar suspended by a previous `PlainScalarSuspended`, /// continuing from its saved state, phase, and reader position rather than /// rescanning the content already accumulated before the suspend. /// /// Takes `state` `inout` rather than the whole `PlainScalarSuspended`, on /// purpose: the caller (`scanStep()`) must disalias `state` from the /// suspended value it came from *before* this call, since a `let /// suspended = ...; resumePlainScalar(suspended)` call would keep the /// caller's own `suspended.state` reference to the same string buffer /// alive for this whole call's duration regardless of anything done /// inside this function's own body (a value parameter is borrowed for /// the call, not owned, so a local disalias inside the callee cannot /// remove a reference the caller itself is still holding). With `state` /// passed by direct reference and no wrapping struct crossing this call /// boundary at all, there is exactly one owner of its string buffer /// throughout, so appending inside the loop below never triggers a /// spurious copy-on-write copy of the whole accumulated scalar. See /// `scanStep()`'s resume branch for where the disalias happens. mutating func resumePlainScalar( _ state: inout PlainState, indent: Int, startMark: PureYAML.Parsing.Mark, phase: PlainScalarPhase, ) throws -> PureYAML.Parsing.LibYAML.Token { try runPlainScalarLoop(&state, indent: indent, startMark: startMark, from: phase) return finishPlainScalar(state, startMark: startMark) } /// The scan loop shared by a fresh attempt and a resume, restructured as an /// explicit `PlainScalarPhase` state machine (see its own doc comment for /// why) with a `suspendIfDry` check after every step that peeked. Checking /// only once, after the whole loop exits, is not enough: a dry read /// (`reader.ranDry`, see `Reader.peek(_:)`) inside a lookahead /// (`documentMarkerAhead()`, `consumePlainContent`'s `:`-followed-by-blank /// check, `consumePlainBreaks`'s `blankLineAhead()` guard) reads as "blank or /// end" (`CharacterClass.isBlankZ`/`isBreakZ` treat a missing scalar as /// true), not as "not enough data yet", so the *next* step can reach a /// wrong-but-plausible decision (e.g. `documentMarkerAhead` wrongly says /// "not a marker", so `consumePlainContent` appends `---` as scalar content) /// before a single end-of-loop check would ever see the taint that caused /// it. Checking right after each peeking step, before its result is used for /// anything further, catches the taint before it can influence another /// decision. Batch parsing (`isFinal: true`) is unaffected: every check can /// only throw when `!reader.isFinal`, which batch callers never set, so the /// loop's own logic is otherwise identical to the original. /// /// `state` and the reader position are always resumable at a suspend point: /// nothing here calls `reader.skip()` on a dry `nil`, so accumulated content /// and position both stop exactly at the last successfully read scalar. private mutating func runPlainScalarLoop( _ state: inout PlainState, indent: Int, startMark: PureYAML.Parsing.Mark, from initialPhase: PlainScalarPhase = .start, ) throws { var phase = initialPhase while true { switch phase { case .start: let atDocumentMarker = reader.column == 0 && documentMarkerAhead() // A dry lookahead inside `documentMarkerAhead()` must resume by // redoing this whole step, not by trusting `atDocumentMarker` // (which `isBlankZ`'s nil-is-true bias could have gotten wrong) // and moving on: hence `phase: .start` here, not `.consumingContent`. try suspendIfDry(state, indent: indent, startMark: startMark, phase: .start) if atDocumentMarker { return } if reader.peek() == "#" { return } try consumePlainContent(&state, startMark: startMark) // consumePlainContent stopping is not yet known to be a real // answer (terminator found) versus a dry cutoff: check before // trusting it enough to move to `.afterContent`'s guard. On dry, // resume via `.consumingContent`, not `.start`: the document-marker // and `#` checks above only apply at a genuine entry point, and // the reader position where a content run was interrupted can // land on a literal `#` or `-` that is legitimate content, not a // fresh comment or marker. try suspendIfDry(state, indent: indent, startMark: startMark, phase: .consumingContent) phase = .afterContent case .consumingContent: try consumePlainContent(&state, startMark: startMark) try suspendIfDry(state, indent: indent, startMark: startMark, phase: .consumingContent) phase = .afterContent case .afterContent: // Reached only once consumePlainContent is known to have stopped // for a real reason, so this peek cannot itself be dry: it // re-reads the exact position consumePlainContent's own last // (already non-dry) peek confirmed, and nothing advanced between. guard Classify.isBlank(reader.peek()) || Classify.isBreak(reader.peek()) else { return } try consumePlainBreaks(&state, indent: indent, startMark: startMark) // Same reasoning as consumePlainContent above, but resuming here // must not redo `.afterContent`'s guard against new data: that // guard gates *entry* into a blank/break run, and re-asking it // after the run is already underway would wrongly treat "the run // continues" as "the run never started" (or vice versa) instead // of just continuing the same run. `.consumingBreaks` re-enters // consumePlainBreaks directly. try suspendIfDry(state, indent: indent, startMark: startMark, phase: .consumingBreaks) phase = .afterBreaks case .consumingBreaks: try consumePlainBreaks(&state, indent: indent, startMark: startMark) try suspendIfDry(state, indent: indent, startMark: startMark, phase: .consumingBreaks) phase = .afterBreaks case .afterBreaks: // `reader.column` is a plain stored field, never read via // `peek(_:)`, so this check cannot itself observe a dry read; by // construction every path reaching this case already confirmed // `!ranDry` before transitioning here. if flowLevel == 0, reader.column < indent { return } phase = .start } } } private func suspendIfDry( _ state: PlainState, indent: Int, startMark: PureYAML.Parsing.Mark, phase: PlainScalarPhase, ) throws { if !reader.isFinal, reader.ranDry { throw PlainScalarSuspended(state: state, indent: indent, startMark: startMark, phase: phase) } } private mutating func finishPlainScalar( _ state: PlainState, startMark: PureYAML.Parsing.Mark, ) -> PureYAML.Parsing.LibYAML.Token { if state.leadingBlanks { simpleKeyAllowed = true } return PureYAML.Parsing.LibYAML.Token( type: .scalar(value: state.string, style: .plain), startMark: startMark, endMark: state.endMark, ) } /// Consume the run of non-blank characters, folding any pending breaks or /// whitespace ahead of each one. private mutating func consumePlainContent(_ state: inout PlainState, startMark _: PureYAML.Parsing.Mark) throws { while let character = reader.peek(), !Classify.isBlankZ(character) { if character == ":", Classify.isBlankZ(reader.peek(1)) { break } if flowLevel > 0, character == ":", Classify.isFlowIndicator(reader.peek(1)) { // A `:` before a flow indicator ends the key; the value is empty. // libyaml rejects this as an unexpected ':', but it is a valid // value indicator in flow context. break } if flowLevel > 0, Classify.isFlowIndicator(character) { break } foldPending(&state) state.string.unicodeScalars.append(character) reader.skip() state.endMark = reader.mark } } /// Fold the pending leading break, trailing breaks, and whitespace into the /// accumulated value (the join logic from libyaml's inner loop). private func foldPending(_ state: inout PlainState) { guard state.leadingBlanks || !state.whitespaces.isEmpty else { return } guard state.leadingBlanks else { state.string += state.whitespaces state.whitespaces = "" return } if state.leadingBreak.first == "\n" { if state.trailingBreaks.isEmpty { state.string += " " } else { state.string += state.trailingBreaks state.trailingBreaks = "" } state.leadingBreak = "" } else { state.string += state.leadingBreak state.string += state.trailingBreaks state.leadingBreak = "" state.trailingBreaks = "" } state.leadingBlanks = false } /// Consume the run of blanks and line breaks between content, recording them as /// pending whitespace or folded breaks. private mutating func consumePlainBreaks(_ state: inout PlainState, indent: Int, startMark: PureYAML.Parsing.Mark) throws { while Classify.isBlank(reader.peek()) || Classify.isBreak(reader.peek()) { if Classify.isBlank(reader.peek()) { if state.leadingBlanks, reader.column < indent, Classify.isTab(reader.peek()) { // `blankLineAhead()` is its own multi-character lookahead (not // just the single already-confirmed-real `peek()` above), so it // can independently run dry: check immediately, before the // tab-violation decision below trusts its answer. Unchecked, // `isBreakZ`'s nil-is-true bias makes an incomplete lookahead // read as "blank line", suppressing a real violation until more // data arrives proves otherwise. let onBlankLine = blankLineAhead() try suspendIfDry(state, indent: indent, startMark: startMark, phase: .consumingBreaks) if !onBlankLine { // A tab below the indentation is illegal only when it indents // real content; on an otherwise-blank line it is just a blank // line the scalar folds over. libyaml rejects it either way. throw scannerError("found a tab character that violates indentation", at: startMark) } } if !state.leadingBlanks, let blank = reader.peek() { state.whitespaces.unicodeScalars.append(blank) } reader.skip() } else if !state.leadingBlanks { state.whitespaces = "" reader.skipLine() state.leadingBreak = "\n" state.leadingBlanks = true } else { reader.skipLine() state.trailingBreaks += "\n" } } } private func scannerError(_ problem: String, at mark: PureYAML.Parsing.Mark) -> PureYAML.Parsing.LibYAML.ScannerError { PureYAML.Parsing.LibYAML.ScannerError(context: "while scanning a plain scalar", problem: problem, mark: mark) } private mutating func documentMarkerAhead() -> Bool { let first = reader.peek() guard first == "-" || first == "." else { return false } return reader.peek(1) == first && reader.peek(2) == first && Classify.isBlankZ(reader.peek(3)) } }