extension PureYAML.Parsing.LibYAML.Scanner { /// The result of one `scanStep()` call. enum ScanOutcome: Equatable { /// A token is safe to release to the caller now. case token(PureYAML.Parsing.LibYAML.Token) /// The buffered input was exhausted mid-fetch; append more input (via /// `reader.append(_:)`) and call `scanStep()` again. The scanner's state is /// unchanged from before this call, as if it had not been called. case needMoreInput /// STREAM-END has been released and no further tokens remain. case done } /// Resumable, one-token-at-a-time counterpart to `scanAll()`. Where `scanAll()` /// assumes the full input is already buffered, `scanStep()` may be driven across /// a `Reader` still receiving chunks (`isFinal == false`): a fetch that runs off /// the buffered end is rolled back in full (as if it had not been attempted) /// rather than mistaken for true end of input. /// /// A token already queued is not always safe to hand out immediately: libyaml's /// simple-key mechanism can still splice a KEY (and a BLOCK-MAPPING-START) in /// front of it once a later `:` is found (`saveSimpleKey`/`insert(_:atTokenNumber:)` /// in `LibYAML.Scanner.swift`/`LibYAML.IndentEngine.swift`). Port of libyaml's /// `yaml_parser_fetch_more_tokens` release condition: the token at the queue /// front (position `tokensParsed`) is safe to release only when no currently /// possible simple key (at any flow level) is still recorded at that exact /// position; such a key could still resolve into a splice targeting that slot. mutating func scanStep() throws -> ScanOutcome { while true { if isFrontSafeToRelease, let token = indentEngine.dequeue() { return .token(token) } if streamEndProduced { return .done } // A dry run can only ever be reported while `!reader.isFinal` (see // `Reader.peek(_:)`), so once the caller has appended every chunk and // called `markFinal()`, no fetch can ever need rolling back. Skipping // the snapshot in that case matters: it is the entire cost difference // between `scanStep()` and `scanAll()` once the whole input is already // buffered (measured in StreamingScannerPerformanceTests), since neither // reads nor mutations inside `fetchNextToken()` become any cheaper by // being wrapped in an unused checkpoint. guard !reader.isFinal else { try fetchNextToken() continue } let checkpoint = self do { try fetchNextToken() } catch { if reader.ranDry { self = checkpoint return .needMoreInput } throw error } if reader.ranDry { self = checkpoint return .needMoreInput } } } private var isFrontSafeToRelease: Bool { guard !indentEngine.tokens.isEmpty else { return false } return !simpleKeys.contains { $0.possible && $0.tokenNumber == indentEngine.tokensParsed } } }