add location property to ValueSource.Invocation

allowing more useful help messages upon transform failure.

Author: RafeArnold

clikt/api/clikt.api

@@ -1457,18 +1457,23 @@ public final class com/github/ajalt/clikt/sources/ValueSource$Companion {
 
 public final class com/github/ajalt/clikt/sources/ValueSource$Invocation {
 	public static final field Companion Lcom/github/ajalt/clikt/sources/ValueSource$Invocation$Companion;
-	public fun <init> (Ljava/util/List;)V
+	public fun <init> (Ljava/util/List;Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/util/List;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()Ljava/util/List;
-	public final fun copy (Ljava/util/List;)Lcom/github/ajalt/clikt/sources/ValueSource$Invocation;
-	public static synthetic fun copy$default (Lcom/github/ajalt/clikt/sources/ValueSource$Invocation;Ljava/util/List;ILjava/lang/Object;)Lcom/github/ajalt/clikt/sources/ValueSource$Invocation;
+	public final fun component2 ()Ljava/lang/String;
+	public final fun copy (Ljava/util/List;Ljava/lang/String;)Lcom/github/ajalt/clikt/sources/ValueSource$Invocation;
+	public static synthetic fun copy$default (Lcom/github/ajalt/clikt/sources/ValueSource$Invocation;Ljava/util/List;Ljava/lang/String;ILjava/lang/Object;)Lcom/github/ajalt/clikt/sources/ValueSource$Invocation;
 	public fun equals (Ljava/lang/Object;)Z
+	public final fun getLocation ()Ljava/lang/String;
 	public final fun getValues ()Ljava/util/List;
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;
 }
 
 public final class com/github/ajalt/clikt/sources/ValueSource$Invocation$Companion {
-	public final fun just (Ljava/lang/Object;)Ljava/util/List;
-	public final fun value (Ljava/lang/Object;)Lcom/github/ajalt/clikt/sources/ValueSource$Invocation;
+	public final fun just (Ljava/lang/Object;Ljava/lang/String;)Ljava/util/List;
+	public static synthetic fun just$default (Lcom/github/ajalt/clikt/sources/ValueSource$Invocation$Companion;Ljava/lang/Object;Ljava/lang/String;ILjava/lang/Object;)Ljava/util/List;
+	public final fun value (Ljava/lang/Object;Ljava/lang/String;)Lcom/github/ajalt/clikt/sources/ValueSource$Invocation;
+	public static synthetic fun value$default (Lcom/github/ajalt/clikt/sources/ValueSource$Invocation$Companion;Ljava/lang/Object;Ljava/lang/String;ILjava/lang/Object;)Lcom/github/ajalt/clikt/sources/ValueSource$Invocation;
 }
 

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/parameters/options/Option.kt

@@ -174,7 +174,7 @@ internal fun Option.hasEnvvarOrSourcedValue(
 
 private fun Option.readValueSource(context: Context): List<OptionInvocation>? {
     return context.valueSource?.getValues(context, this)
-        ?.map { OptionInvocation("", it.values) }
+        ?.map { OptionInvocation(it.location, it.values) }
         ?.ifEmpty { null }
 }
 

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/sources/ValueSource.kt

@@ -1,16 +1,27 @@
 package com.github.ajalt.clikt.sources
 
 import com.github.ajalt.clikt.core.Context
-import com.github.ajalt.clikt.parameters.options.*
+import com.github.ajalt.clikt.parameters.options.Option
+import com.github.ajalt.clikt.parameters.options.OptionWithValues
+import com.github.ajalt.clikt.parameters.options.inferEnvvar
+import com.github.ajalt.clikt.parameters.options.longestName
+import com.github.ajalt.clikt.parameters.options.splitOptionPrefix
+import com.github.ajalt.clikt.sources.ValueSource.Companion.name
 
 interface ValueSource {
-    data class Invocation(val values: List<String>) {
+    /**
+     * @property location A pointer to where the invocation's values were retrieved from. Useful for indicating where
+     * a failure occurred in error help messages.
+     */
+    data class Invocation(val values: List<String>, val location: String = "") {
         companion object {
             /** Create a list of a single Invocation with a single value */
-            fun just(value: Any?): List<Invocation> = listOf(value(value))
+            fun just(value: Any?, location: String = ""): List<Invocation> =
+                listOf(value(value = value, location = location))
 
             /** Create an Invocation with a single value */
-            fun value(value: Any?): Invocation = Invocation(listOf(value.toString()))
+            fun value(value: Any?, location: String = ""): Invocation =
+                Invocation(values = listOf(value.toString()), location = location)
         }
     }
 

test/src/commonTest/kotlin/com/github/ajalt/clikt/sources/ValueSourceTest.kt

@@ -0,0 +1,46 @@
+package com.github.ajalt.clikt.sources
+
+import com.github.ajalt.clikt.core.BadParameterValue
+import com.github.ajalt.clikt.core.Context
+import com.github.ajalt.clikt.parameters.options.Option
+import com.github.ajalt.clikt.parameters.options.option
+import com.github.ajalt.clikt.parameters.types.int
+import com.github.ajalt.clikt.testing.TestCommand
+import com.github.ajalt.clikt.testing.formattedMessage
+import com.github.ajalt.clikt.testing.parse
+import io.kotest.assertions.throwables.shouldThrow
+import io.kotest.matchers.shouldBe
+import kotlin.test.Test
+
+class ValueSourceTest {
+    @Test
+    fun `parameter name can be provided to invocation`() {
+        class C : TestCommand() {
+            @Suppress("unused")
+            val theInteger by option("-i").int()
+        }
+
+        val sourceWithoutParameterName = object : ValueSource {
+            override fun getValues(
+                context: Context,
+                option: Option
+            ): List<ValueSource.Invocation> = ValueSource.Invocation.just(value = "foo")
+        }
+
+        val sourceWithParameterName = object : ValueSource {
+            override fun getValues(
+                context: Context,
+                option: Option
+            ): List<ValueSource.Invocation> =
+                ValueSource.Invocation.just(value = "foo", location = "value_source_option")
+        }
+
+        shouldThrow<BadParameterValue> {
+            C().apply { configureContext { valueSource = sourceWithoutParameterName } }.parse("")
+        }.formattedMessage shouldBe "invalid value: foo is not a valid integer"
+
+        shouldThrow<BadParameterValue> {
+            C().apply { configureContext { valueSource = sourceWithParameterName } }.parse("")
+        }.formattedMessage shouldBe "invalid value for value_source_option: foo is not a valid integer"
+    }
+}