Implement the general machinery for parsing entities from code

dkhalanskyjb · dkhalanskyjb · commit 27b52ca13159 · 2024-02-27T12:05:03.000+01:00
diff --git a/core/common/src/internal/format/parser/NumberConsumer.kt b/core/common/src/internal/format/parser/NumberConsumer.kt
@@ -0,0 +1,137 @@
+/*
+ * Copyright 2023 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+package kotlinx.datetime.internal.format.parser
+
+import kotlinx.datetime.internal.POWERS_OF_TEN
+import kotlinx.datetime.internal.DecimalFraction
+
+/**
+ * A parser that expects to receive a string consisting of [length] digits, or, if [length] is `null`,
+ * a string consisting of any number of digits.
+ */
+internal sealed class NumberConsumer<in Receiver>(
+    /** The number of digits to consume. `null` means that the length is variable. */
+    open val length: Int?,
+    /** The human-readable name of the entity being parsed here. */
+    val whatThisExpects: String
+) {
+    /**
+     * Wholly consumes the given [input]. Should be called with a string consisting of [length] digits, or,
+     * if [length] is `null`, with a string consisting of any number of digits. [consume] itself does not
+     * necessarily check the length of the input string, instead expecting to be passed a valid one.
+     *
+     * Returns `null` on success and a `NumberConsumptionError` on failure.
+     */
+    abstract fun consume(storage: Receiver, input: String): NumberConsumptionError?
+}
+
+internal interface NumberConsumptionError {
+    fun errorMessage(): String
+    object ExpectedInt: NumberConsumptionError {
+        override fun errorMessage() = "expected an Int value"
+    }
+    class TooManyDigits(val maxDigits: Int): NumberConsumptionError {
+        override fun errorMessage() = "expected at most $maxDigits digits"
+    }
+    class TooFewDigits(val minDigits: Int): NumberConsumptionError {
+        override fun errorMessage() = "expected at least $minDigits digits"
+    }
+    class WrongConstant(val expected: String): NumberConsumptionError {
+        override fun errorMessage() = "expected '$expected'"
+    }
+    class Conflicting(val conflicting: Any): NumberConsumptionError {
+        override fun errorMessage() = "attempted to overwrite the existing value '$conflicting'"
+    }
+}
+
+/**
+ * A parser that accepts an [Int] value in range from `0` to [Int.MAX_VALUE].
+ */
+// TODO: should the parser reject excessive padding?
+internal class UnsignedIntConsumer<in Receiver>(
+    private val minLength: Int?,
+    private val maxLength: Int?,
+    private val setter: AssignableField<Receiver, Int>,
+    name: String,
+    private val multiplyByMinus1: Boolean = false,
+) : NumberConsumer<Receiver>(if (minLength == maxLength) minLength else null, name) {
+
+    init {
+        require(length == null || length in 1..9) { "Invalid length for field $whatThisExpects: $length" }
+    }
+
+    override fun consume(storage: Receiver, input: String): NumberConsumptionError? = when {
+        maxLength != null && input.length > maxLength -> NumberConsumptionError.TooManyDigits(maxLength)
+        minLength != null && input.length < minLength -> NumberConsumptionError.TooFewDigits(minLength)
+        else -> when (val result = input.toIntOrNull()) {
+            null -> NumberConsumptionError.ExpectedInt
+            else -> setter.setWithoutReassigning(storage, if (multiplyByMinus1) -result else result)
+        }
+    }
+}
+
+internal class ReducedIntConsumer<in Receiver>(
+    override val length: Int,
+    private val setter: AssignableField<Receiver, Int>,
+    name: String,
+    val base: Int,
+): NumberConsumer<Receiver>(length, name) {
+
+    private val modulo = POWERS_OF_TEN[length]
+    private val baseMod = base % modulo
+    private val baseFloor = base - baseMod
+
+    override fun consume(storage: Receiver, input: String): NumberConsumptionError? = when (val result = input.toIntOrNull()) {
+        null -> NumberConsumptionError.ExpectedInt
+        else -> setter.setWithoutReassigning(storage, if (result >= baseMod) {
+            baseFloor + result
+        } else {
+            baseFloor + modulo + result
+        })
+    }
+}
+
+/**
+ * A parser that consumes exactly the string [expected].
+ */
+internal class ConstantNumberConsumer<in Receiver>(
+    private val expected: String
+) : NumberConsumer<Receiver>(expected.length, "the predefined string $expected") {
+    override fun consume(storage: Receiver, input: String): NumberConsumptionError? = if (input == expected) {
+        null
+    } else {
+        NumberConsumptionError.WrongConstant(expected)
+    }
+}
+
+internal class FractionPartConsumer<in Receiver>(
+    private val minLength: Int?,
+    private val maxLength: Int?,
+    private val setter: AssignableField<Receiver, DecimalFraction>,
+    name: String,
+) : NumberConsumer<Receiver>(if (minLength == maxLength) minLength else null, name) {
+    init {
+        require(minLength == null || minLength in 1..9) { "Invalid length for field $whatThisExpects: $length" }
+        // TODO: bounds on maxLength
+    }
+
+    override fun consume(storage: Receiver, input: String): NumberConsumptionError? = when {
+        minLength != null && input.length < minLength -> NumberConsumptionError.TooFewDigits(minLength)
+        maxLength != null && input.length > maxLength -> NumberConsumptionError.TooManyDigits(maxLength)
+        else -> when (val numerator = input.toIntOrNull()) {
+            null -> NumberConsumptionError.TooManyDigits(9)
+            else -> setter.setWithoutReassigning(storage, DecimalFraction(numerator, input.length))
+        }
+    }
+}
+
+private fun <Object, Type> AssignableField<Object, Type>.setWithoutReassigning(
+    receiver: Object,
+    value: Type,
+): NumberConsumptionError? {
+    val conflictingValue = trySetWithoutReassigning(receiver, value) ?: return null
+    return NumberConsumptionError.Conflicting(conflictingValue)
+}
diff --git a/core/common/src/internal/format/parser/ParseResult.kt b/core/common/src/internal/format/parser/ParseResult.kt
@@ -0,0 +1,26 @@
+/*
+ * Copyright 2019-2022 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+package kotlinx.datetime.internal.format.parser
+
+import kotlin.jvm.JvmInline
+
+@JvmInline
+internal value class ParseResult private constructor(val value: Any) {
+    companion object {
+        fun Ok(indexOfNextUnparsed: Int) = ParseResult(indexOfNextUnparsed)
+        fun Error(position: Int, message: () -> String) =
+            ParseResult(ParseError(position, message))
+    }
+
+    inline fun<T> match(onSuccess: (Int) -> T, onFailure: (ParseError) -> T): T =
+        when (value) {
+            is Int -> onSuccess(value)
+            is ParseError -> onFailure(value)
+            else -> error("Unexpected parse result: $value")
+        }
+}
+
+internal class ParseError(val position: Int, val message: () -> String)
diff --git a/core/common/src/internal/format/parser/Parser.kt b/core/common/src/internal/format/parser/Parser.kt
@@ -0,0 +1,203 @@
+/*
+ * Copyright 2023 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+package kotlinx.datetime.internal.format.parser
+
+import kotlin.jvm.JvmInline
+
+/**
+ * Describes the commands that the parser must execute, in two portions:
+ * * [operations], which are executed in order, and
+ * * [followedBy], which are executed *in parallel* after [operations].
+ *
+ * An example of a [ParserStructure]:
+ * ```
+ * // number - dash - number - dash - number
+ * //        |
+ * //        \
+ * //         letter 'W' - number
+ * ParserStructure(
+ *   listOf(numberParser),
+ *   listOf(
+ *     ParserStructure(
+ *       listOf(stringParser("-"), numberParser, stringParser("-"), numberParser),
+ *       emptyList()
+ *     ),
+ *     ParserStructure(
+ *       listOf(stringParser("W"), numberParser),
+ *       emptyList()
+ *     ),
+ *   )
+ * )
+ * ```
+ */
+internal class ParserStructure<in Output>(
+    val operations: List<ParserOperation<Output>>,
+    val followedBy: List<ParserStructure<Output>>,
+) {
+    override fun toString(): String =
+        "${operations.joinToString(", ")}(${followedBy.joinToString(";")})"
+}
+
+// TODO: O(size of the resulting parser ^ 2), but can be O(size of the resulting parser)
+internal fun <T> List<ParserStructure<T>>.concat(): ParserStructure<T> {
+    fun <T> ParserStructure<T>.append(other: ParserStructure<T>): ParserStructure<T> = if (followedBy.isEmpty()) {
+        ParserStructure(operations + other.operations, other.followedBy)
+    } else {
+        ParserStructure(operations, followedBy.map { it.append(other) })
+    }
+    fun <T> ParserStructure<T>.simplify(): ParserStructure<T> {
+        val newOperations = mutableListOf<ParserOperation<T>>()
+        var currentNumberSpan: MutableList<NumberConsumer<T>>? = null
+        // joining together the number consumers in this parser before the first alternative
+        for (op in operations) {
+            if (op is NumberSpanParserOperation) {
+                if (currentNumberSpan != null) {
+                    currentNumberSpan.addAll(op.consumers)
+                } else {
+                    currentNumberSpan = op.consumers.toMutableList()
+                }
+            } else {
+                if (currentNumberSpan != null) {
+                    newOperations.add(NumberSpanParserOperation(currentNumberSpan))
+                    currentNumberSpan = null
+                }
+                newOperations.add(op)
+            }
+        }
+        val mergedTails = followedBy.flatMap {
+            val simplified = it.simplify()
+            // parser `ParserStructure(emptyList(), p)` is equivalent to `p`,
+            // unless `p` is empty. For example, ((a|b)|(c|d)) is equivalent to (a|b|c|d).
+            // As a special case, `ParserStructure(emptyList(), emptyList())` represents a parser that recognizes an empty
+            // string. For example, (|a|b) is not equivalent to (a|b).
+            if (simplified.operations.isEmpty())
+                simplified.followedBy.ifEmpty { listOf(simplified) }
+            else
+                listOf(simplified)
+        }
+        return if (currentNumberSpan == null) {
+            // the last operation was not a number span, or it was a number span that we are allowed to interrupt
+            ParserStructure(newOperations, mergedTails)
+        } else if (mergedTails.none {
+                it.operations.firstOrNull()?.let { it is NumberSpanParserOperation } == true
+            }) {
+            // the last operation was a number span, but there are no alternatives that start with a number span.
+            newOperations.add(NumberSpanParserOperation(currentNumberSpan))
+            ParserStructure(newOperations, mergedTails)
+        } else {
+            val newTails = mergedTails.map {
+                when (val firstOperation = it.operations.firstOrNull()) {
+                    is NumberSpanParserOperation -> {
+                        ParserStructure(
+                            listOf(NumberSpanParserOperation(currentNumberSpan + firstOperation.consumers)) + it.operations.drop(
+                                1
+                            ),
+                            it.followedBy
+                        )
+                    }
+
+                    null -> ParserStructure(
+                        listOf(NumberSpanParserOperation(currentNumberSpan)),
+                        it.followedBy
+                    )
+
+                    else -> ParserStructure(
+                        listOf(NumberSpanParserOperation(currentNumberSpan)) + it.operations,
+                        it.followedBy
+                    )
+                }
+            }
+            ParserStructure(newOperations, newTails)
+        }
+    }
+    val naiveParser = foldRight(ParserStructure<T>(emptyList(), emptyList())) { parser, acc -> parser.append(acc) }
+    return naiveParser.simplify()
+}
+
+internal interface Copyable<Self> {
+    fun copy(): Self
+}
+
+@JvmInline
+internal value class Parser<Output: Copyable<Output>>(
+    private val commands: ParserStructure<Output>
+) {
+    /**
+     * [startIndex] is the index of the first character that is not yet consumed.
+     *
+     * [allowDanglingInput] determines whether the match is only successful if the whole string after [startIndex]
+     * is consumed.
+     *
+     * [onSuccess] is invoked as soon as some parsing attempt succeeds.
+     * [onError] is invoked when some parsing attempt fails.
+     */
+    // Would be a great place to use the `Flow` from `kotlinx.coroutines` here instead of `onSuccess` and
+    // `onError`, but alas.
+    private inline fun parse(
+        input: CharSequence,
+        startIndex: Int,
+        initialContainer: Output,
+        allowDanglingInput: Boolean,
+        onError: (ParseError) -> Unit,
+        onSuccess: (Int, Output) -> Unit
+    ) {
+        val parseOptions = mutableListOf(ParserState(initialContainer, commands, startIndex))
+        iterate_over_alternatives@while (true) {
+            val state = parseOptions.removeLastOrNull() ?: break
+            val output = state.output.copy()
+            var inputPosition = state.inputPosition
+            val parserStructure = state.parserStructure
+            run parse_one_alternative@{
+                for (ix in parserStructure.operations.indices) {
+                    parserStructure.operations[ix].consume(output, input, inputPosition).match(
+                        { inputPosition = it },
+                        {
+                            onError(it)
+                            return@parse_one_alternative // continue@iterate_over_alternatives, if that were supported
+                        }
+                    )
+                }
+                if (parserStructure.followedBy.isEmpty()) {
+                    if (allowDanglingInput || inputPosition == input.length) {
+                        onSuccess(inputPosition, output)
+                    } else {
+                        onError(ParseError(inputPosition) { "There is more input to consume" })
+                    }
+                } else {
+                    for (ix in parserStructure.followedBy.indices.reversed()) {
+                        parseOptions.add(ParserState(output, parserStructure.followedBy[ix], inputPosition))
+                    }
+                }
+            }
+        }
+    }
+
+    fun match(input: CharSequence, initialContainer: Output, startIndex: Int = 0): Output {
+        val errors = mutableListOf<ParseError>()
+        parse(input, startIndex, initialContainer, allowDanglingInput = false, { errors.add(it) }, { _, out -> return@match out })
+        errors.sortByDescending { it.position }
+        // `errors` can not be empty because each parser will have (successes + failures) >= 1, and here, successes == 0
+        ParseException(errors.first()).let {
+            for (error in errors.drop(1)) {
+                it.addSuppressed(ParseException(error))
+            }
+            throw it
+        }
+    }
+
+    fun matchOrNull(input: CharSequence, initialContainer: Output, startIndex: Int = 0): Output? {
+        parse(input, startIndex, initialContainer, allowDanglingInput = false, { }, { _, out -> return@matchOrNull out })
+        return null
+    }
+
+    private class ParserState<Output>(
+        val output: Output,
+        val parserStructure: ParserStructure<Output>,
+        val inputPosition: Int,
+    )
+}
+
+internal class ParseException(error: ParseError) : Exception("Position ${error.position}: ${error.message()}")
diff --git a/core/common/src/internal/format/parser/ParserOperation.kt b/core/common/src/internal/format/parser/ParserOperation.kt
