Improve error descriptiveness in the parsing API (#360)

Fixes #359
Fixes #361

Additionally, remove delayed initialization of parsing to ensure that creating ambigous formats fails and document the thrown exception.

Author: dkhalanskyjb

core/common/src/LocalDate.kt

@@ -65,6 +65,8 @@ public expect class LocalDate : Comparable<LocalDate> {
          * (for example, [dayOfMonth] is 31 for February), consider using [DateTimeComponents.Format] instead.
          *
          * There is a collection of predefined formats in [LocalDate.Formats].
+         *
+         * @throws IllegalArgumentException if parsing using this format is ambiguous.
          */
         @Suppress("FunctionName")
         public fun Format(block: DateTimeFormatBuilder.WithDate.() -> Unit): DateTimeFormat<LocalDate>

core/common/src/LocalDateTime.kt

@@ -62,6 +62,8 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
          * (for example, [dayOfMonth] is 31 for February), consider using [DateTimeComponents.Format] instead.
          *
          * There is a collection of predefined formats in [LocalDateTime.Formats].
+         *
+         * @throws IllegalArgumentException if parsing using this format is ambiguous.
          */
         @Suppress("FunctionName")
         public fun Format(builder: DateTimeFormatBuilder.WithDateTime.() -> Unit): DateTimeFormat<LocalDateTime>

core/common/src/LocalTime.kt

@@ -97,6 +97,8 @@ public expect class LocalTime : Comparable<LocalTime> {
          * (for example, [second] is 60), consider using [DateTimeComponents.Format] instead.
          *
          * There is a collection of predefined formats in [LocalTime.Formats].
+         *
+         * @throws IllegalArgumentException if parsing using this format is ambiguous.
          */
         @Suppress("FunctionName")
         public fun Format(builder: DateTimeFormatBuilder.WithTime.() -> Unit): DateTimeFormat<LocalTime>

core/common/src/UtcOffset.kt

@@ -67,6 +67,8 @@ public expect class UtcOffset {
          * [DateTimeFormatBuilder.WithUtcOffset.offset] in a format builder for a larger data structure.
          *
          * There is a collection of predefined formats in [UtcOffset.Formats].
+         *
+         * @throws IllegalArgumentException if parsing using this format is ambiguous.
          */
         @Suppress("FunctionName")
         public fun Format(block: DateTimeFormatBuilder.WithUtcOffset.() -> Unit): DateTimeFormat<UtcOffset>

core/common/src/format/DateTimeComponents.kt

@@ -69,6 +69,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
          * Creates a [DateTimeFormat] for [DateTimeComponents] values using [DateTimeFormatBuilder.WithDateTimeComponents].
          *
          * There is a collection of predefined formats in [DateTimeComponents.Formats].
+         *
+         * @throws IllegalArgumentException if parsing using this format is ambiguous.
          */
         @Suppress("FunctionName")
         public fun Format(block: DateTimeFormatBuilder.WithDateTimeComponents.() -> Unit): DateTimeFormat<DateTimeComponents> {

core/common/src/format/DateTimeFormat.kt

@@ -115,7 +115,10 @@ internal sealed class AbstractDateTimeFormat<T, U : Copyable<U>> : DateTimeForma
         try {
             return valueFromIntermediate(matched)
         } catch (e: IllegalArgumentException) {
-            throw DateTimeFormatException(e.message!!)
+            throw DateTimeFormatException(when (val message = e.message) {
+                null -> "The value parsed from '$input' is invalid"
+                else -> "$message (when parsing '$input')"
+            }, e)
         }
     }
 

core/common/src/internal/format/FieldFormatDirective.kt

@@ -108,7 +108,7 @@ internal abstract class NamedUnsignedIntFieldFormatDirective<in Target>(
     override fun parser(): ParserStructure<Target> =
         ParserStructure(
             listOf(
-                StringSetParserOperation(values, AssignableString(), "One of $values for $name")
+                StringSetParserOperation(values, AssignableString(), "one of $values for $name")
             ), emptyList()
         )
 }
@@ -142,7 +142,7 @@ internal abstract class NamedEnumIntFieldFormatDirective<in Target, Type>(
     override fun parser(): ParserStructure<Target> =
         ParserStructure(
             listOf(
-                StringSetParserOperation(mapping.values, AssignableString(), "One of ${mapping.values} for $name")
+                StringSetParserOperation(mapping.values, AssignableString(), "one of ${mapping.values} for $name")
             ), emptyList()
         )
 }

core/common/src/internal/format/FormatStructure.kt

@@ -231,8 +231,8 @@ internal open class ConcatenatedFormatStructure<in T>(
 
 internal class CachedFormatStructure<in T>(formats: List<NonConcatenatedFormatStructure<T>>) :
     ConcatenatedFormatStructure<T>(formats) {
-    private val cachedFormatter: FormatterStructure<T> by lazy { super.formatter() }
-    private val cachedParser: ParserStructure<T> by lazy { super.parser() }
+    private val cachedFormatter: FormatterStructure<T> = super.formatter()
+    private val cachedParser: ParserStructure<T> = super.parser()
 
     override fun formatter(): FormatterStructure<T> = cachedFormatter
 

core/common/src/internal/format/parser/ParserOperation.kt

@@ -50,7 +50,12 @@ internal class NumberSpanParserOperation<Output>(
 
     init {
         require(consumers.all { (it.length ?: Int.MAX_VALUE) > 0 })
-        require(consumers.count { it.length == null } <= 1)
+        require(consumers.count { it.length == null } <= 1) {
+            val fieldNames = consumers.filter { it.length == null }.map { it.whatThisExpects }
+            "At most one variable-length numeric field in a row is allowed, but got several: $fieldNames. " +
+                "Parsing is undefined: for example, with variable-length month number " +
+                "and variable-length day of month, '111' can be parsed as Jan 11th or Nov 1st."
+        }
     }
 
     private val whatThisExpects: String

core/common/test/format/DateTimeComponentsFormatTest.kt

@@ -32,13 +32,13 @@ class DateTimeComponentsFormatTest {
                 setOffset(UtcOffset.ZERO)
             },
             format.parse("Tue, 40 Jun 2008 11:05:30 GMT"))
-        assertFailsWith<DateTimeFormatException> { format.parse("Bue, 3 Jun 2008 11:05:30 GMT") }
+        format.assertCanNotParse("Bue, 3 Jun 2008 11:05:30 GMT")
     }
 
     @Test
     fun testInconsistentLocalTime() {
         val formatTime = LocalTime.Format {
-            hour(); char(':'); minute();
+            hour(); char(':'); minute()
             chars(" ("); amPmHour(); char(':'); minute(); char(' '); amPmMarker("AM", "PM"); char(')')
         }
         val format = DateTimeComponents.Format { time(formatTime) }
@@ -53,16 +53,16 @@ class DateTimeComponentsFormatTest {
             DateTimeComponents().apply { hour = 23; hourOfAmPm = 11; minute = 15; amPm = AmPmMarker.AM },
             format.parse(time2)
         )
-        assertFailsWith<IllegalArgumentException> { formatTime.parse(time2) }
+        formatTime.assertCanNotParse(time2)
         val time3 = "23:15 (10:15 PM)" // a time with an inconsistent number of hours
         assertDateTimeComponentsEqual(
             DateTimeComponents().apply { hour = 23; hourOfAmPm = 10; minute = 15; amPm = AmPmMarker.PM },
             format.parse(time3)
         )
-        assertFailsWith<IllegalArgumentException> { formatTime.parse(time3) }
+        formatTime.assertCanNotParse(time3)
         val time4 = "23:15 (11:16 PM)" // a time with an inconsistently duplicated field
-        assertFailsWith<IllegalArgumentException> { format.parse(time4) }
-        assertFailsWith<IllegalArgumentException> { formatTime.parse(time4) }
+        format.assertCanNotParse(time4)
+        formatTime.assertCanNotParse(time4)
     }
 
     @Test
@@ -95,7 +95,7 @@ class DateTimeComponentsFormatTest {
         assertEquals(dateTime, bag.toLocalDateTime())
         assertEquals(offset, bag.toUtcOffset())
         assertEquals(berlin, bag.timeZoneId)
-        assertFailsWith<DateTimeFormatException> { format.parse("2008-06-03T11:05:30.123456789+01:00[Mars/New_York]") }
+        format.assertCanNotParse("2008-06-03T11:05:30.123456789+01:00[Mars/New_York]")
         for (zone in TimeZone.availableZoneIds) {
             assertEquals(zone, format.parse("2008-06-03T11:05:30.123456789+01:00[$zone]").timeZoneId)
         }