clikt / com.github.ajalt.clikt.parameters.options / OptionWithValues

OptionWithValues

class OptionWithValues<AllT, EachT, ValueT> : OptionDelegate<AllT>

An Option that takes one or more values.

Constructors

<init>

OptionWithValues(names: Set<String>, metavarExplicit: String?, metavarDefault: String?, nvalues: Int, help: String, hidden: Boolean, envvar: String?, envvarSplit: Regex, parser: OptionWithValuesParser, transformValue: ValueTransformer<ValueT>, transformEach: ArgsTransformer<ValueT, EachT>, transformAll: CallsTransformer<EachT, AllT>)

An Option that takes one or more values.

Properties

envvar

val envvar: String?

The environment variable name to use.

envvarSplit

val envvarSplit: Regex

The pattern to split envvar values on. If the envvar splits into multiple values, each one will be treated like a separate invocation of the option.

help

val help: String

The description of this option, usually a single line.

hidden

val hidden: Boolean

If true, this option should not appear in help output.

metavar

val metavar: String?

A name representing the values for this option that can be displayed to the user.

metavarDefault

val metavarDefault: String?

The metavar to use if metavarExplicit is null. Set by transformValues.

metavarExplicit

val metavarExplicit: String?

The metavar to use. Specified at option creation; overrides metavarDefault.

names

var names: Set<String>

The names that can be used to invoke this option. They must start with a punctuation character.

nvalues

val nvalues: Int

The number of values that must be given to this option.

parser

val parser: OptionWithValuesParser

The parser for this option's values.

secondaryNames

val secondaryNames: Set<String>

Names that can be used for a secondary purpose, like disabling flag options.

transformAll

val transformAll: CallsTransformer<EachT, AllT>

Called in finalize to transform all invocations into the final value.

transformEach

val transformEach: ArgsTransformer<ValueT, EachT>

Called in finalize to transform each invocation.

transformValue

val transformValue: ValueTransformer<ValueT>

Called in finalize to transform each value provided to each invocation.

Functions

copy

fun <AllT, EachT, ValueT> copy(transformValue: ValueTransformer<ValueT>, transformEach: ArgsTransformer<ValueT, EachT>, transformAll: CallsTransformer<EachT, AllT>, names: Set<String> = this.names, metavarExplicit: String? = this.metavarExplicit, metavarDefault: String? = this.metavarDefault, nvalues: Int = this.nvalues, help: String = this.help, hidden: Boolean = this.hidden, envvar: String? = this.envvar, envvarSplit: Regex = this.envvarSplit, parser: OptionWithValuesParser = this.parser): OptionWithValues<AllT, EachT, ValueT>

Create a new option that is a copy of this one with different transforms.

finalize

fun finalize(context: Context, invocations: List<Invocation>): Unit

Called after this command's argv is parsed to transform and store the option's value.

getValue

fun getValue(thisRef: CliktCommand, property: KProperty<*>): AllT

provideDelegate

operator fun provideDelegate(thisRef: CliktCommand, prop: KProperty<*>): ReadOnlyProperty<CliktCommand, AllT>

Implementations must call CliktCommand.registerOption

Extension Functions

choice

fun <T : Any> RawOption.choice(choices: Map<String, T>, metavar: String = mvar(choices.keys)): NullableOption<T, T>
fun <T : Any> RawOption.choice(vararg choices: Pair<String, T>, metavar: String = mvar(choices.map { it.first })): NullableOption<T, T>

Convert the option based on a fixed set of values.

fun RawOption.choice(vararg choices: String, metavar: String = mvar(choices.asIterable())): NullableOption<String, String>

Restrict the option to a fixed set of values.

convert

fun <T : Any> RawOption.convert(metavar: String = "VALUE", envvarSplit: Regex = this.envvarSplit, conversion: ValueTransformer<T>): NullableOption<T, T>

Convert the option value type.

counted

fun RawOption.counted(): FlagOption<Int>

Turn an option into a flag that counts the number of times the option occurs on the command line.

default

fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.default(value: EachT): OptionWithValues<EachT, EachT, ValueT>

If the option is not called on the command line (and is not set in an envvar), use value for the option.

double

fun RawOption.double(): NullableOption<Double, Double>

Convert the option values to a Double

file

fun RawOption.file(exists: Boolean = false, fileOkay: Boolean = true, folderOkay: Boolean = true, writable: Boolean = false, readable: Boolean = false): NullableOption<File, File>

Convert the option to a File.

flag

fun RawOption.flag(vararg secondaryNames: String, default: Boolean = false): FlagOption<Boolean>

Turn an option into a boolean flag.

float

fun RawOption.float(): NullableOption<Float, Float>

Convert the option values to a Float

int

fun RawOption.int(): NullableOption<Int, Int>

Convert the option values to an Int

long

fun RawOption.long(): NullableOption<Long, Long>

Convert the option values to a Long

multiple

fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.multiple(): OptionWithValues<List<EachT>, EachT, ValueT>

Make the option return a list of calls; each item in the list is the value of one call.

pair

fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.pair(): NullableOption<Pair<ValueT, ValueT>, ValueT>

Change to option to take two values, held in a Pair

prompt

fun <T : Any> NullableOption<T, T>.prompt(text: String? = null, default: String? = null, hideInput: Boolean = false, requireConfirmation: Boolean = false, confirmationPrompt: String = "Repeat for confirmation: ", promptSuffix: String = ": ", showDefault: Boolean = true): OptionWithValues<T, T, T>

If the option isn't given on the command line, prompt the user for manual input.

required

fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.required(): OptionWithValues<EachT, EachT, ValueT>

If the option is not called on the command line (and is not set in an envvar), throw a MissingParameter.

restrictTo

fun <T> OptionWithValues<T?, T, T>.restrictTo(min: T? = null, max: T? = null, clamp: Boolean = false): OptionWithValues<T?, T, T> where T : Number, T : Comparable<T>
fun <T> OptionWithValues<T?, T, T>.restrictTo(range: ClosedRange<T>, clamp: Boolean = false): OptionWithValues<T?, T, T> where T : Number, T : Comparable<T>

Restrict the option values to fit into a range.

switch

fun <T : Any> RawOption.switch(choices: Map<String, T>): FlagOption<T?>
fun <T : Any> RawOption.switch(vararg choices: Pair<String, T>): FlagOption<T?>

Turn an option into a set of flags that each map to a value.

transformAll

fun <AllT, EachT : Any, ValueT> NullableOption<EachT, ValueT>.transformAll(transform: CallsTransformer<EachT, AllT>): OptionWithValues<AllT, EachT, ValueT>

Transform all calls to the option to the final option type.

transformValues

fun <EachInT : Any, EachOutT : Any, ValueT> NullableOption<EachInT, ValueT>.transformValues(nvalues: Int, transform: ArgsTransformer<ValueT, EachOutT>): NullableOption<EachOutT, ValueT>

Change the number of values that this option takes.

triple

fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.triple(): NullableOption<Triple<ValueT, ValueT, ValueT>, ValueT>

Change to option to take three values, held in a Triple

validate

fun <AllT : Any, EachT, ValueT> OptionWithValues<AllT, EachT, ValueT>.validate(validator: OptionValidator<AllT>): OptionDelegate<AllT>

Check the final option value and raise an error if it's not valid.