Add choice options with groups

ajalt · ajalt · commit fd5ed396d83d · 2019-05-12T14:09:55.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,7 +11,7 @@
   [`OptionWithValues.valueSplit`](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.parameters.options/-option-with-values/value-split.html).
 - Marking options as deprecated with [`option().deprecated()`](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.parameters.options/deprecated.html)
 - You can manually set the pattern to split envvars on by passing a pattern to the `envvarSplit` parameter of [`option()`](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.parameters.options/option.html)
-- [Option groups](https://ajalt.github.io/clikt/documenting/#grouping-options-in-help), [mutually exclusive groups](https://ajalt.github.io/clikt/options/#prompting-for-input), and [co-occurring groups](https://ajalt.github.io/clikt/options/#co-occurring-option-groups)
+- [Option groups](https://ajalt.github.io/clikt/documenting/#grouping-options-in-help), [mutually exclusive groups](https://ajalt.github.io/clikt/options/#prompting-for-input), [co-occurring groups](https://ajalt.github.io/clikt/options/#co-occurring-option-groups), and [choice options with groups](https://ajalt.github.io/clikt/options/#choice-options-with-groups)
 
 ### Changed
 - If multiple `--` tokens are present on the command line, all subsequent occurrences after the first are now
diff --git a/clikt/src/main/kotlin/com/github/ajalt/clikt/core/ParameterHolder.kt b/clikt/src/main/kotlin/com/github/ajalt/clikt/core/ParameterHolder.kt
@@ -23,4 +23,7 @@ interface ParameterHolder {
 interface GroupableOption : Option {
     /** The group that this option belongs to, or null. Set by the group. */
     var parameterGroup: ParameterGroup?
+
+    /** The name of the group, or null if this option should not be grouped in the help output. */
+    var groupName: String?
 }
diff --git a/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt b/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/groups/ChoiceGroup.kt
@@ -0,0 +1,104 @@
+package com.github.ajalt.clikt.parameters.groups
+
+import com.github.ajalt.clikt.completion.CompletionCandidates.Fixed
+import com.github.ajalt.clikt.core.BadParameterValue
+import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
+import com.github.ajalt.clikt.core.MissingParameter
+import com.github.ajalt.clikt.parameters.internal.NullableLateinit
+import com.github.ajalt.clikt.parameters.options.Option
+import com.github.ajalt.clikt.parameters.options.RawOption
+import com.github.ajalt.clikt.parameters.options.option
+import com.github.ajalt.clikt.parameters.options.required
+import com.github.ajalt.clikt.parsers.OptionParser
+import kotlin.properties.ReadOnlyProperty
+import kotlin.reflect.KProperty
+
+class ChoiceGroup<GroupT : OptionGroup, OutT>(
+        internal val option: RawOption,
+        internal val groups: Map<String, GroupT>,
+        internal val transform: (GroupT?) -> OutT
+) : ParameterGroupDelegate<OutT> {
+    override val groupName: String? = null
+    override val groupHelp: String? = null
+    private var value: OutT by NullableLateinit("Cannot read from option delegate before parsing command line")
+
+    override fun provideDelegate(thisRef: CliktCommand, prop: KProperty<*>): ReadOnlyProperty<CliktCommand, OutT> {
+        option.provideDelegate(thisRef, prop) // infer the option name and register it
+        thisRef.registerOptionGroup(this)
+        for ((_, group) in groups) {
+            for (option in group.options) {
+                option.parameterGroup = this
+                option.groupName = group.groupName
+                thisRef.registerOption(option)
+            }
+        }
+        return this
+    }
+
+    override fun getValue(thisRef: CliktCommand, property: KProperty<*>): OutT = value
+
+    override fun finalize(context: Context, invocationsByOption: Map<Option, List<OptionParser.Invocation>>) {
+        val key = option.value
+        if (key == null) {
+            value = transform(null)
+            return
+        }
+
+        val group = groups[key]
+                ?: throw BadParameterValue(
+                        "invalid choice: $key. (choose from ${groups.keys.joinToString()})",
+                        option,
+                        context
+                )
+        group.finalize(context, invocationsByOption.filterKeys { it in group.options })
+        value = transform(group)
+    }
+}
+
+/**
+ * Convert the option to an option group based on a fixed set of values.
+ *
+ * ### Example:
+ *
+ * ```kotlin
+ * option().choice(mapOf("foo" to FooOptionGroup(), "bar" to BarOptionGroup()))
+ * ```
+ *
+ * @see com.github.ajalt.clikt.parameters.types.choice
+ */
+fun <T : OptionGroup> RawOption.groupChoice(choices: Map<String, T>): ChoiceGroup<T, T?> {
+    return ChoiceGroup(
+            copy(transformValue, transformEach, transformAll, completionCandidates = Fixed(choices.keys)),
+            choices
+    ) { it }
+}
+
+/**
+ * Convert the option to an option group based on a fixed set of values.
+ *
+ * ### Example:
+ *
+ * ```kotlin
+ * option().choice("foo" to FooOptionGroup(), "bar" to BarOptionGroup())
+ * ```
+ *
+ * @see com.github.ajalt.clikt.parameters.types.choice
+ */
+fun <T : OptionGroup> RawOption.groupChoice(vararg choices: Pair<String, T>): ChoiceGroup<T, T?> {
+    return groupChoice(choices.toMap())
+}
+
+/**
+ * If a [groupChoice] option is not called on the command line, throw a [MissingParameter] exception.
+ *
+ * ### Example:
+ *
+ * ```kotlin
+ * option().choice("foo" to FooOptionGroup(), "bar" to BarOptionGroup()).required()
+ * ```
+ */
+fun <T : OptionGroup> ChoiceGroup<T, T?>.required(): ChoiceGroup<T, T> {
+    return ChoiceGroup(option, groups) { it ?: throw MissingParameter(option) }
+}
+
diff --git a/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt b/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/groups/CoOccurringOptionGroup.kt
@@ -2,7 +2,6 @@ package com.github.ajalt.clikt.parameters.groups
 
 import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.core.Context
-import com.github.ajalt.clikt.core.MissingParameter
 import com.github.ajalt.clikt.output.HelpFormatter
 import com.github.ajalt.clikt.parameters.internal.NullableLateinit
 import com.github.ajalt.clikt.parameters.options.Option
@@ -20,9 +19,10 @@ class CoOccurringOptionGroup<GroupT : OptionGroup, OutT>(
 
     override fun provideDelegate(thisRef: CliktCommand, prop: KProperty<*>): ReadOnlyProperty<CliktCommand, OutT> {
         thisRef.registerOptionGroup(this)
-        for (o in group.options) {
-            o.parameterGroup = this
-            thisRef.registerOption(o)
+        for (option in group.options) {
+            option.parameterGroup = this
+            option.groupName = groupName
+            thisRef.registerOption(option)
         }
         return this
     }
diff --git a/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOption.kt b/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/groups/MutuallyExclusiveOption.kt
@@ -37,6 +37,7 @@ class MutuallyExclusiveOptions<OptT : Any, OutT>(
         for (option in options) {
             require(option.names.isNotEmpty()) { "must specify names for all options in a group" }
             option.parameterGroup = this
+            option.groupName = groupName
             thisRef.registerOption(option)
         }
 
diff --git a/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/options/FlagOption.kt b/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/options/FlagOption.kt
@@ -27,6 +27,7 @@ class FlagOption<T>(
         val transformEnvvar: OptionTransformContext.(String) -> T,
         val transformAll: CallsTransformer<String, T>) : OptionDelegate<T> {
     override var parameterGroup: ParameterGroup? = null
+    override var groupName: String? = null
     override val metavar: String? = null
     override val nvalues: Int get() = 0
     override val parser = FlagOptionParser
@@ -49,6 +50,19 @@ class FlagOption<T>(
         thisRef.registerOption(this)
         return this
     }
+
+    fun <T> copy(
+            transformEnvvar: OptionTransformContext.(String) -> T,
+            transformAll: CallsTransformer<String, T>,
+            names: Set<String> = this.names,
+            secondaryNames: Set<String> = this.secondaryNames,
+            help: String = this.help,
+            hidden: Boolean = this.hidden,
+            helpTags: Map<String, String> = this.helpTags,
+            envvar: String? = this.envvar
+    ): FlagOption<T> {
+        return FlagOption(names, secondaryNames, help, hidden, helpTags, envvar, transformEnvvar, transformAll)
+    }
 }
 
 /**
@@ -88,17 +102,18 @@ fun <T : Any> RawOption.switch(choices: Map<String, T>): FlagOption<T?> {
             transformEnvvar = {
                 throw UsageError("environment variables not supported for switch options", this)
             },
-            transformAll = { it.map { choices[it]!! }.lastOrNull() })
+            transformAll = { it.map { choices.getValue(it) }.lastOrNull() })
 }
 
 /** Turn an option into a set of flags that each map to a value. */
 fun <T : Any> RawOption.switch(vararg choices: Pair<String, T>): FlagOption<T?> = switch(mapOf(*choices))
 
 /** Set a default value for a option. */
 fun <T : Any> FlagOption<T?>.default(value: T): FlagOption<T> {
-    return FlagOption(names, secondaryNames, help, hidden, helpTags, envvar,
+    return copy(
             transformEnvvar = { transformEnvvar(it) ?: value },
-            transformAll = { transformAll(it) ?: value })
+            transformAll = { transformAll(it) ?: value }
+    )
 }
 
 /**
@@ -108,7 +123,7 @@ fun <T : Any> FlagOption<T?>.default(value: T): FlagOption<T> {
  * if the value is not valid. It is not called if the delegate value is null.
  */
 fun <T : Any> FlagOption<T>.validate(validator: OptionValidator<T>): OptionDelegate<T> {
-    return FlagOption(names, secondaryNames, help, hidden, helpTags, envvar,
+    return copy(
             transformEnvvar = { transformEnvvar(it).also { validator(this, it) } },
             transformAll = { transformAll(it).also { validator(this, it) } }
     )
@@ -133,5 +148,5 @@ fun <T> FlagOption<T>.deprecated(
         error: Boolean = false
 ): OptionDelegate<T> {
     val helpTags = if (tagName.isNullOrBlank()) helpTags else helpTags + mapOf(tagName to tagValue)
-    return FlagOption(names, secondaryNames, help, hidden, helpTags, envvar, transformEnvvar, deprecationTransformer(message, error, transformAll))
+    return copy(transformEnvvar, deprecationTransformer(message, error, transformAll), helpTags = helpTags)
 }
diff --git a/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt b/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt
@@ -105,6 +105,7 @@ class OptionWithValues<AllT, EachT, ValueT>(
         val transformAll: CallsTransformer<EachT, AllT>
 ) : OptionDelegate<AllT>, GroupableOption {
     override var parameterGroup: ParameterGroup? = null
+    override var groupName: String? = null
     override val metavar: String? get() = metavarWithDefault.value
     override var value: AllT by NullableLateinit("Cannot read from option delegate before parsing command line")
         private set
diff --git a/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/types/choice.kt b/clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/types/choice.kt
@@ -43,7 +43,7 @@ fun <T : Any> RawArgument.choice(choices: Map<String, T>): ProcessedArgument<T,
  * ```
  */
 fun <T : Any> RawArgument.choice(vararg choices: Pair<String, T>): ProcessedArgument<T, T> {
-    return choice(mapOf(*choices))
+    return choice(choices.toMap())
 }
 
 /**
@@ -69,6 +69,8 @@ fun RawArgument.choice(vararg choices: String): ProcessedArgument<String, String
  * ```kotlin
  * option().choice(mapOf("foo" to 1, "bar" to 2))
  * ```
+ *
+ * @see com.github.ajalt.clikt.parameters.groups.groupChoice
  */
 fun <T : Any> RawOption.choice(choices: Map<String, T>,
                                metavar: String = mvar(choices.keys)): NullableOption<T, T> {
@@ -86,10 +88,12 @@ fun <T : Any> RawOption.choice(choices: Map<String, T>,
  * ```kotlin
  * option().choice("foo" to 1, "bar" to 2)
  * ```
+ *
+ * @see com.github.ajalt.clikt.parameters.groups.groupChoice
  */
 fun <T : Any> RawOption.choice(vararg choices: Pair<String, T>,
                                metavar: String = mvar(choices.map { it.first })): NullableOption<T, T> {
-    return choice(mapOf(*choices), metavar)
+    return choice(choices.toMap(), metavar)
 }
 
 /**
diff --git a/clikt/src/main/kotlin/com/github/ajalt/clikt/parsers/Parser.kt b/clikt/src/main/kotlin/com/github/ajalt/clikt/parsers/Parser.kt
@@ -96,12 +96,7 @@ internal object Parser {
             // Finalize eager options
             invocationsByOption.forEach { (o, inv) -> if (o is EagerOption) o.finalize(context, inv) }
 
-            // Finalize option groups
-            invocationsByOptionByGroup.forEach { (group, invocations) ->
-                group?.finalize(context, invocations)
-            }
-
-            // Finalize remaining un-grouped options that occurred on the command line
+            // Finalize un-grouped options that occurred on the command line
             invocationsByOptionByGroup[null]?.forEach { (o, inv) -> o.finalize(context, inv) }
 
             // Finalize un-grouped options not provided on the command line so that they can apply default values etc.
@@ -111,6 +106,11 @@ internal object Parser {
                 }
             }
 
+            // Finalize option groups after other options so that the groups can their values
+            invocationsByOptionByGroup.forEach { (group, invocations) ->
+                group?.finalize(context, invocations)
+            }
+
             // Finalize groups with no invocations
             command._groups.forEach { if (it !in invocationsByGroup) it.finalize(context, emptyMap()) }
 
diff --git a/clikt/src/test/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt b/clikt/src/test/kotlin/com/github/ajalt/clikt/parameters/groups/OptionGroupsTest.kt
@@ -2,12 +2,14 @@
 
 package com.github.ajalt.clikt.parameters.groups
 
+import com.github.ajalt.clikt.core.BadParameterValue
 import com.github.ajalt.clikt.core.MissingParameter
 import com.github.ajalt.clikt.core.MutuallyExclusiveGroupException
 import com.github.ajalt.clikt.core.UsageError
 import com.github.ajalt.clikt.parameters.options.default
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.options.required
+import com.github.ajalt.clikt.parameters.types.int
 import com.github.ajalt.clikt.testing.TestCommand
 import io.kotlintest.data.forall
 import io.kotlintest.fail
@@ -237,4 +239,50 @@ class OptionGroupsTest {
         shouldThrow<IllegalArgumentException> { C() }
                 .message shouldBe "At least one option in a co-occurring group must use `required()`"
     }
+
+    @Test
+    fun `choice group`() {
+        class Group1 : OptionGroup() {
+            val g11 by option().int().required()
+            val g12 by option().int()
+        }
+
+        class Group2 : OptionGroup() {
+            val g21 by option().int().required()
+            val g22 by option().int()
+        }
+
+        class C : TestCommand() {
+            val g by option().groupChoice("1" to Group1(), "2" to Group2())
+        }
+        forall(
+                row("", 0, null, null),
+                row("--g11=1 --g21=1", 0, null, null),
+                row("--g=1 --g11=2", 1, 2, null),
+                row("--g=1 --g11=2 --g12=3", 1, 2, 3),
+                row("--g=1 --g11=2 --g12=3", 1, 2, 3),
+                row("--g=2 --g21=2 --g22=3", 2, 2, 3),
+                row("--g=2 --g11=2 --g12=3 --g21=2 --g22=3", 2, 2, 3)
+        ) { argv, eg, eg1, eg2 ->
+            with(C()) {
+                parse(argv)
+                when (eg) {
+                    0 -> {
+                        g shouldBe null
+                    }
+                    1 -> {
+                        (g as Group1).g11 shouldBe eg1
+                        (g as Group1).g12 shouldBe eg2
+                    }
+                    2 -> {
+                        (g as Group2).g21 shouldBe eg1
+                        (g as Group2).g22 shouldBe eg2
+                    }
+                }
+            }
+        }
+
+        shouldThrow<BadParameterValue> { C().parse("--g=3") }
+                .message shouldBe "Invalid value for \"--g\": invalid choice: 3. (choose from 1, 2)"
+    }
 }
diff --git a/docs/documenting.md b/docs/documenting.md
@@ -208,7 +208,8 @@ Options:
 
 You can group options into separate help sections by using
 [OptionGroup](api/clikt/com.github.ajalt.clikt.parameters.groups/-option-group/index.html).
-The name of the group will be shown in the output. You can also add an extra help message to be shown with the group.
+The name of the group will be shown in the output. You can also add an extra help message to be
+shown with the group. Groups can't be nested.
 
 ```kotlin
 class UserOptions : OptionGroup(name = "User Options", help = "Options controlling the user") {
diff --git a/docs/options.md b/docs/options.md
diff --git a/mkdocs.yml b/mkdocs.yml

Original file line number	Diff line number	Diff line change
`@@ -23,4 +23,7 @@ interface ParameterHolder {`
`23`	`23`	`interface GroupableOption : Option {`
`24`	`24`	`/** The group that this option belongs to, or null. Set by the group. */`
`25`	`25`	`var parameterGroup: ParameterGroup?`
	`26`	`+`
	`27`	`+ /** The name of the group, or null if this option should not be grouped in the help output. */`
	`28`	`+ var groupName: String?`
`26`	`29`	`}`
Original file line number	Diff line number	Diff line change
`@@ -37,6 +37,7 @@ class MutuallyExclusiveOptions<OptT : Any, OutT>(`
`37`	`37`	`for (option in options) {`
`38`	`38`	`require(option.names.isNotEmpty()) { "must specify names for all options in a group" }`
`39`	`39`	`option.parameterGroup = this`
	`40`	`+ option.groupName = groupName`
`40`	`41`	`thisRef.registerOption(option)`
`41`	`42`	`}`
`42`	`43`