WIP: first draft of locale-invariant parsing and formatting

Author: dkhalanskyjb

core/common/src/format/FormatBuilder.kt

@@ -0,0 +1,133 @@
+/*
+ * Copyright 2019-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.format
+
+import kotlinx.datetime.internal.format.*
+import kotlinx.datetime.internal.format.AlternativesFormatStructure
+
+@DslMarker
+public annotation class DateTimeBuilder
+
+/**
+ * Common functions for all the date-time format builders.
+ */
+public interface FormatBuilder<out Self> {
+    /**
+     * Appends a set of alternative blocks to the format.
+     *
+     * When parsing, the blocks are tried in order until one of them succeeds.
+     *
+     * When formatting, there is a requirement that the later blocks contain all the fields that are present in the
+     * earlier blocks. Moreover, the additional fields must have a *default value* defined for them.
+     * Then, during formatting, the block that has the most information is chosen.
+     *
+     * Example:
+     * ```
+     * appendAlternatives({
+     *   appendLiteral("Z")
+     * }, {
+     *   appendOffsetHours()
+     *   appendOptional {
+     *     appendLiteral(":")
+     *     appendOffsetMinutes()
+     *     appendOptional {
+     *       appendLiteral(":")
+     *       appendOffsetSeconds()
+     *     }
+     *   }
+     * })
+     * ```
+     * Here, all values have the default value of zero, so the first block is chosen when formatting `UtcOffset.ZERO`.
+     */
+    public fun appendAlternatives(vararg blocks: Self.() -> Unit)
+
+    /**
+     * Appends a literal string to the format.
+     * When formatting, the string is appended to the result as is,
+     * and when parsing, the string is expected to be present in the input.
+     */
+    public fun appendLiteral(string: String)
+
+    /**
+     * Appends a format string to the format.
+     *
+     * TODO. For now, see docs for [kotlinx.datetime.internal.format.appendFormatString].
+     *
+     * @throws IllegalArgumentException if the format string is invalid.
+     */
+    public fun appendFormatString(formatString: String)
+}
+
+/**
+ * Appends an optional section to the format.
+ *
+ * When parsing, the section is parsed if it is present in the input.
+ *
+ * When formatting, the section is formatted if the value of any field in the block is not equal to the default value.
+ * Only [appendOptional] calls where all the fields have default values are permitted when formatting.
+ *
+ * Example:
+ * ```
+ * appendHours()
+ * appendLiteral(":")
+ * appendMinutes()
+ * appendOptional {
+ *   appendLiteral(":")
+ *   appendSeconds()
+ * }
+ * ```
+ *
+ * Here, because seconds have the default value of zero, they are formatted only if they are not equal to zero.
+ *
+ * This is a shorthand for `appendAlternatives({}, block)`.
+ */
+public fun <Self> FormatBuilder<Self>.appendOptional(block: Self.() -> Unit): Unit =
+    appendAlternatives({}, block)
+
+/**
+ * Appends a literal character to the format.
+ *
+ * This is a shorthand for `appendLiteral(char.toString())`.
+ */
+public fun <Self> FormatBuilder<Self>.appendLiteral(char: Char): Unit = appendLiteral(char.toString())
+
+internal interface AbstractFormatBuilder<Target, out UserSelf, ActualSelf> :
+    FormatBuilder<UserSelf> where ActualSelf : AbstractFormatBuilder<Target, UserSelf, ActualSelf> {
+
+    val actualBuilder: Builder<Target>
+    fun createEmpty(): ActualSelf
+    fun castToGeneric(actualSelf: ActualSelf): UserSelf
+
+    override fun appendAlternatives(vararg blocks: UserSelf.() -> Unit) {
+        actualBuilder.add(AlternativesFormatStructure(blocks.map { block ->
+            createEmpty().also { block(castToGeneric(it)) }.actualBuilder.build()
+        }))
+    }
+
+    override fun appendLiteral(string: String) = actualBuilder.add(ConstantFormatStructure(string))
+
+    override fun appendFormatString(formatString: String) {
+        val end = actualBuilder.appendFormatString(formatString)
+        require(end == formatString.length) {
+            "Unexpected char '${formatString[end]}' in $formatString at position $end"
+        }
+    }
+
+    fun withSharedSign(outputPlus: Boolean, block: UserSelf.() -> Unit) {
+        actualBuilder.add(
+            SignedFormatStructure(
+                createEmpty().also { block(castToGeneric(it)) }.actualBuilder.build(),
+                outputPlus
+            )
+        )
+    }
+
+    fun build(): Format<Target> = Format(actualBuilder.build())
+}
+
+internal interface Copyable<Self> {
+    fun copy(): Self
+}

core/common/src/format/LocalDateFormat.kt

@@ -0,0 +1,184 @@
+/*
+ * Copyright 2019-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.format
+
+import kotlinx.datetime.*
+import kotlinx.datetime.internal.*
+import kotlinx.datetime.internal.LruCache
+import kotlinx.datetime.internal.format.*
+import kotlinx.datetime.internal.format.parser.*
+
+public interface DateFormatBuilderFields {
+    public fun appendYear(minDigits: Int = 1, outputPlusOnExceededPadding: Boolean = false)
+    public fun appendMonthNumber(minLength: Int = 1)
+    public fun appendMonthName(names: List<String>)
+    public fun appendDayOfMonth(minLength: Int = 1)
+}
+
+@DateTimeBuilder
+public interface DateFormatBuilder : DateFormatBuilderFields, FormatBuilder<DateFormatBuilder>
+
+public class LocalDateFormat private constructor(private val actualFormat: Format<DateFieldContainer>) {
+    public companion object {
+        public fun build(block: DateFormatBuilder.() -> Unit): LocalDateFormat {
+            val builder = Builder(DateFieldContainerFormatBuilder())
+            builder.block()
+            return LocalDateFormat(builder.build())
+        }
+
+        public fun fromFormatString(formatString: String): LocalDateFormat = build { appendFormatString(formatString) }
+
+        public val ISO: LocalDateFormat = build {
+            appendYear(4, outputPlusOnExceededPadding = true)
+            appendFormatString("'-'mm'-'dd")
+        }
+
+        internal val Cache = LruCache<String, LocalDateFormat>(16) { fromFormatString(it) }
+    }
+
+    public fun format(date: LocalDate): String =
+        StringBuilder().also {
+            actualFormat.formatter.format(date.toIncompleteLocalDate(), it)
+        }.toString()
+
+    public fun parse(input: String): LocalDate {
+        val parser = Parser(::IncompleteLocalDate, IncompleteLocalDate::copy, actualFormat.parser)
+        try {
+            return parser.match(input).toLocalDate()
+        } catch (e: ParseException) {
+            throw DateTimeFormatException("Failed to parse date from '$input'", e)
+        } catch (e: IllegalArgumentException) {
+            throw DateTimeFormatException("Invalid date '$input'", e)
+        }
+    }
+
+    private class Builder(override val actualBuilder: DateFieldContainerFormatBuilder) :
+        AbstractFormatBuilder<DateFieldContainer, DateFormatBuilder, Builder>, DateFormatBuilder {
+        override fun appendYear(minDigits: Int, outputPlusOnExceededPadding: Boolean) =
+            actualBuilder.add(BasicFormatStructure(YearDirective(minDigits, outputPlusOnExceededPadding)))
+
+        override fun appendMonthNumber(minLength: Int) =
+            actualBuilder.add(BasicFormatStructure(MonthDirective(minLength)))
+
+        override fun appendMonthName(names: List<String>) =
+            actualBuilder.add(BasicFormatStructure(MonthNameDirective(names)))
+
+        override fun appendDayOfMonth(minLength: Int) = actualBuilder.add(BasicFormatStructure(DayDirective(minLength)))
+
+        override fun createEmpty(): Builder = Builder(DateFieldContainerFormatBuilder())
+        override fun castToGeneric(actualSelf: Builder): DateFormatBuilder = this
+    }
+
+}
+
+public fun LocalDate.format(formatString: String): String =
+    LocalDateFormat.Cache.get(formatString).format(this)
+
+public fun LocalDate.format(format: LocalDateFormat): String = format.format(this)
+
+public fun LocalDate.Companion.parse(input: String, formatString: String): LocalDate =
+    LocalDateFormat.Cache.get(formatString).parse(input)
+
+public fun LocalDate.Companion.parse(input: String, format: LocalDateFormat): LocalDate = format.parse(input)
+
+internal fun LocalDate.toIncompleteLocalDate(): IncompleteLocalDate =
+    IncompleteLocalDate(year, monthNumber, dayOfMonth, dayOfWeek.isoDayNumber)
+
+internal fun <T> getParsedField(field: T?, name: String): T {
+    if (field == null) {
+        throw DateTimeFormatException("Can not create a $name from the given input: the field $name is missing")
+    }
+    return field
+}
+
+internal interface DateFieldContainer {
+    var year: Int?
+    var monthNumber: Int?
+    var dayOfMonth: Int?
+    var isoDayOfWeek: Int?
+}
+
+internal object DateFields {
+    val year = SignedFieldSpec(DateFieldContainer::year, maxAbsoluteValue = null)
+    val month = UnsignedFieldSpec(DateFieldContainer::monthNumber, minValue = 1, maxValue = 12)
+    val dayOfMonth = UnsignedFieldSpec(DateFieldContainer::dayOfMonth, minValue = 1, maxValue = 31)
+    val isoDayOfWeek = UnsignedFieldSpec(DateFieldContainer::isoDayOfWeek, minValue = 1, maxValue = 7)
+}
+
+/**
+ * A [kotlinx.datetime.LocalDate], but potentially incomplete and inconsistent.
+ */
+internal class IncompleteLocalDate(
+    override var year: Int? = null,
+    override var monthNumber: Int? = null,
+    override var dayOfMonth: Int? = null,
+    override var isoDayOfWeek: Int? = null
+) : DateFieldContainer, Copyable<IncompleteLocalDate> {
+    fun toLocalDate(): LocalDate {
+        val date = LocalDate(
+            getParsedField(year, "year"),
+            getParsedField(monthNumber, "monthNumber"),
+            getParsedField(dayOfMonth, "dayOfMonth")
+        )
+        isoDayOfWeek?.let {
+            if (it != date.dayOfWeek.isoDayNumber) {
+                throw DateTimeFormatException(
+                    "Can not create a LocalDate from the given input: " +
+                        "the day of week is ${DayOfWeek(it)} but the date is $date, which is a ${date.dayOfWeek}"
+                )
+            }
+        }
+        return date
+    }
+
+    override fun copy(): IncompleteLocalDate = IncompleteLocalDate(year, monthNumber, dayOfMonth, isoDayOfWeek)
+
+    override fun toString(): String =
+        "${year ?: "??"}-${monthNumber ?: "??"}-${dayOfMonth ?: "??"} (day of week is ${isoDayOfWeek ?: "??"})"
+}
+
+internal class YearDirective(digits: Int, outputPlusOnExceededPadding: Boolean) :
+    SignedIntFieldFormatDirective<DateFieldContainer>(
+        DateFields.year,
+        minDigits = digits,
+        maxDigits = null,
+        outputPlusOnExceededPadding = outputPlusOnExceededPadding,
+    )
+
+internal class MonthDirective(minDigits: Int) :
+    UnsignedIntFieldFormatDirective<DateFieldContainer>(DateFields.month, minDigits)
+
+internal class MonthNameDirective(names: List<String>) :
+    NamedUnsignedIntFieldFormatDirective<DateFieldContainer>(DateFields.month, names)
+
+internal class DayDirective(minDigits: Int) :
+    UnsignedIntFieldFormatDirective<DateFieldContainer>(DateFields.dayOfMonth, minDigits)
+
+internal class DateFieldContainerFormatBuilder : AbstractBuilder<DateFieldContainer>() {
+
+    companion object {
+        const val name = "ld"
+    }
+
+    override fun formatFromSubBuilder(
+        name: String,
+        block: Builder<*>.() -> Unit
+    ): FormatStructure<DateFieldContainer>? =
+        if (name == DateFieldContainerFormatBuilder.name)
+            DateFieldContainerFormatBuilder().apply(block).build()
+        else null
+
+    override fun formatFromDirective(letter: Char, length: Int): FormatStructure<DateFieldContainer>? {
+        return when (letter) {
+            'y' -> BasicFormatStructure(YearDirective(length, outputPlusOnExceededPadding = false))
+            'm' -> BasicFormatStructure(MonthDirective(length))
+            'd' -> BasicFormatStructure(DayDirective(length))
+            else -> null
+        }
+    }
+
+    override fun createSibling(): Builder<DateFieldContainer> = DateFieldContainerFormatBuilder()
+}