PureYAML/Sources/Parsing/LibYAML.Scanner.Streaming.swift

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
            }
            let checkpoint = self
            do {
                try fetchNextToken()
            } catch {
                if !reader.isFinal, reader.ranDry {
                    self = checkpoint
                    return .needMoreInput
                }
                throw error
            }
            if !reader.isFinal, 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 }
    }
}