PureYAML/Sources/Parsing/LibYAML.Scanner.swift

extension PureYAML.Parsing.LibYAML {
    /// Aggregate scanner state, mirroring the fields of `yaml_parser_t` that the
    /// ported functions read and write. It is built up as the port proceeds;
    /// currently it holds the indentation engine and the simple-key mechanism.
    /// Column values follow libyaml's 0-based convention internally; conversion to
    /// the package's 1-based `Mark` happens at token emission during integration.
    struct Scanner {
        /// The indentation stack and `roll_indent` / `unroll_indent` (also the
        /// owner of `flow_level` and the token queue).
        var indentEngine = IndentEngine()
        /// `parser->simple_keys`. Always holds at least the block-context level.
        var simpleKeys: [SimpleKey] = [.empty]
        /// `parser->simple_key_allowed`. True at stream start.
        var simpleKeyAllowed = true
        /// `parser->mark`, the current position (column is 0-based here).
        var mark: PureYAML.Parsing.Mark = .start

        /// `parser->flow_level`, kept on the indent engine.
        var flowLevel: Int {
            indentEngine.flowLevel
        }

        /// Port of `yaml_parser_stale_simple_keys`. A potential simple key is
        /// invalid once it is on an earlier line or more than 1024 characters back
        /// (a simple key is single-line and bounded); a required one going stale is
        /// an error.
        mutating func staleSimpleKeys() throws {
            for index in simpleKeys.indices {
                let key = simpleKeys[index]
                guard key.possible, key.mark.line < mark.line || key.mark.index + 1024 < mark.index else {
                    continue
                }
                if key.required {
                    throw ScannerError(
                        context: "while scanning a simple key",
                        problem: "could not find expected ':'",
                        mark: key.mark,
                    )
                }
                simpleKeys[index].possible = false
            }
        }

        /// Port of `yaml_parser_save_simple_key`. Record the current position as a
        /// potential simple key for this flow level when one is allowed. A key is
        /// required (a `:` must follow) when it sits exactly at the block indent.
        mutating func saveSimpleKey() throws {
            let required = flowLevel == 0 && indentEngine.indent == mark.column
            guard simpleKeyAllowed else {
                return
            }
            let key = SimpleKey(
                possible: true,
                required: required,
                tokenNumber: indentEngine.tokensParsed + indentEngine.tokens.count,
                mark: mark,
            )
            try removeSimpleKey()
            simpleKeys[simpleKeys.count - 1] = key
        }

        /// Port of `yaml_parser_remove_simple_key`. Drop the potential key at the
        /// current flow level; removing a required key is an error.
        mutating func removeSimpleKey() throws {
            let top = simpleKeys.count - 1
            if simpleKeys[top].possible, simpleKeys[top].required {
                throw ScannerError(
                    context: "while scanning a simple key",
                    problem: "could not find expected ':'",
                    mark: simpleKeys[top].mark,
                )
            }
            simpleKeys[top].possible = false
        }

        /// Port of `yaml_parser_increase_flow_level`. Push an empty simple key for
        /// the new flow level.
        mutating func increaseFlowLevel() {
            simpleKeys.append(.empty)
            indentEngine.flowLevel += 1
        }

        /// Port of `yaml_parser_decrease_flow_level`. Pop the flow level's simple
        /// key.
        mutating func decreaseFlowLevel() {
            if indentEngine.flowLevel > 0 {
                indentEngine.flowLevel -= 1
                simpleKeys.removeLast()
            }
        }
    }
}