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

OptionWithValues

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

An Option that takes one or more values.

Properties

acceptsNumberValueWithoutName

open val acceptsNumberValueWithoutName: Boolean

If true, this option can be specified without a name e.g. -2 instead of -o2

acceptsUnattachedValue

open val acceptsUnattachedValue: Boolean

If false, invocations must be of the form --foo=1 or -f1. If true, the forms --foo 1 and -f 1 are also accepted.

completionCandidates

open val completionCandidates: CompletionCandidates

Optional set of strings to use when the user invokes shell autocomplete on a value for this option.

eager

open val eager: Boolean

If true, the presence of this option on the command line will halt parsing immediately

envvar

abstract val envvar: String?

The environment variable name to use.

explicitCompletionCandidates

abstract val explicitCompletionCandidates: CompletionCandidates?

The completion candidates set on this option, or null if no candidates have been set

groupName

abstract override var groupName: String?

The name of the group, or null if this option should not be grouped in the help output.

helpGetter

abstract val helpGetter: HelpTransformContext.() -> String?

A block that will return the help text for this option, or null if no getter has been specified

helpTags

abstract val helpTags: Map<String, String>

Extra information about this option to pass to the help formatter.

hidden

abstract val hidden: Boolean

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

metavarGetter

abstract val metavarGetter: Context.() -> String??

A block that will return the metavar for this option, or null if no getter has been specified

names

abstract val names: Set<String>

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

nvalues

abstract val nvalues: IntRange

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

parameterGroup

abstract var parameterGroup: ParameterGroup?

The group that this option belongs to, or null. Set by the group.

secondaryNames

abstract val secondaryNames: Set<String>

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

transformAll

abstract val transformAll: AllTransformer<EachT, AllT>

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

transformEach

abstract val transformEach: ValuesTransformer<ValueT, EachT>

Called in finalize to transform each invocation.

transformValidator

abstract val transformValidator: OptionValidator<AllT>

Called after all parameters have been finalized to validate the output of transformAll

transformValue

abstract val transformValue: ValueTransformer<ValueT>

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

value

abstract val value: AllT

The value for this option.

valueSourceKey

abstract val valueSourceKey: String?

Optional explicit key to use when looking this option up from a ValueSource

valueSplit

abstract val valueSplit: Regex?

A regex to split option values on before conversion, or null to leave them unsplit

Functions

associate

fun RawOption.associate(delimiter: String = "="): OptionWithValues<Map<String, String>, Pair<String, String>, Pair<String, String>>

Change this option to take multiple values, each split on a delimiter, and converted to a map.

boolean

fun RawOption.boolean(): NullableOption<Boolean, Boolean>

Convert the option values to Boolean

check

inline fun <AllT, EachT, ValueT> OptionWithValues<AllT, EachT, ValueT>.check(crossinline lazyMessage: (AllT & Any) -> String = { it.toString() }, crossinline validator: (AllT & Any) -> Boolean): OptionDelegate<AllT>

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

inline fun <AllT, EachT, ValueT> OptionWithValues<AllT, EachT, ValueT>.check(message: String, crossinline validator: (AllT & Any) -> Boolean): OptionDelegate<AllT>

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

choice

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

fun <T : Any> RawOption.choice(choices: Map<String, T>, metavar: String = mvar(choices.keys), ignoreCase: Boolean = false): NullableOption<T, T>

Convert the option based on a fixed set of values.

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

Restrict the option to a fixed set of values.

convert

inline fun <OutT> OptionWithValues<Boolean, Boolean, Boolean>.convert(crossinline conversion: FlagConverter<Boolean, OutT>): OptionWithValues<OutT, Boolean, Boolean>

Convert this flag's value type.

inline fun <InT : Any, ValueT : Any> NullableOption<InT, InT>.convert(noinline metavar: Context.() -> String = { localization.defaultMetavar() }, completionCandidates: CompletionCandidates? = null, crossinline conversion: ValueConverter<InT, ValueT>): NullableOption<ValueT, ValueT>

inline fun <InT : Any, ValueT : Any> NullableOption<InT, InT>.convert(metavar: String, completionCandidates: CompletionCandidates? = null, crossinline conversion: ValueConverter<InT, ValueT>): NullableOption<ValueT, ValueT>

Convert the option's value type.

copy

abstract fun copy(validator: OptionValidator<AllT> = this.transformValidator, names: Set<String> = this.names, metavarGetter: Context.() -> String?? = this.metavarGetter, nvalues: IntRange = this.nvalues, helpGetter: HelpTransformContext.() -> String? = this.helpGetter, hidden: Boolean = this.hidden, helpTags: Map<String, String> = this.helpTags, envvar: String? = this.envvar, valueSourceKey: String? = this.valueSourceKey, valueSplit: Regex? = this.valueSplit, completionCandidates: CompletionCandidates? = explicitCompletionCandidates, secondaryNames: Set<String> = this.secondaryNames, acceptsNumberValueWithoutName: Boolean = this.acceptsNumberValueWithoutName, acceptsUnattachedValue: Boolean = this.acceptsUnattachedValue, eager: Boolean = this.eager): OptionWithValues<AllT, EachT, ValueT>

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

abstract fun <AllT, EachT, ValueT> copy(transformValue: ValueTransformer<ValueT>, transformEach: ValuesTransformer<ValueT, EachT>, transformAll: AllTransformer<EachT, AllT>, validator: OptionValidator<AllT>, names: Set<String> = this.names, metavarGetter: Context.() -> String?? = this.metavarGetter, nvalues: IntRange = this.nvalues, helpGetter: HelpTransformContext.() -> String? = this.helpGetter, hidden: Boolean = this.hidden, helpTags: Map<String, String> = this.helpTags, valueSourceKey: String? = this.valueSourceKey, envvar: String? = this.envvar, valueSplit: Regex? = this.valueSplit, completionCandidates: CompletionCandidates? = explicitCompletionCandidates, secondaryNames: Set<String> = this.secondaryNames, acceptsNumberValueWithoutName: Boolean = this.acceptsNumberValueWithoutName, acceptsUnattachedValue: Boolean = this.acceptsUnattachedValue, eager: Boolean = this.eager): OptionWithValues<AllT, EachT, ValueT>

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

counted

fun RawOption.counted(): OptionWithValues<Int, Int, Int>

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

default

fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.default(value: EachT, defaultForHelp: String = value.toString()): 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.

defaultLazy

inline fun <EachT, ValueT> NullableOption<EachT, ValueT>.defaultLazy(defaultForHelp: String = "", crossinline value: () -> EachT): OptionWithValues<EachT, EachT, ValueT>

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

defaultStdin

fun NullableOption<InputStream, InputStream>.defaultStdin(): OptionWithValues<InputStream, InputStream, InputStream>

Use - as the default value for an inputStream option.

defaultStdout

fun NullableOption<OutputStream, OutputStream>.defaultStdout(): OptionWithValues<OutputStream, OutputStream, OutputStream>

Use - as the default value for an outputStream option.

deprecated

fun <AllT, EachT, ValueT> OptionWithValues<AllT, EachT, ValueT>.deprecated(message: String? = "", tagName: String? = "deprecated", tagValue: String = "", error: Boolean = false): OptionDelegate<AllT>

Mark this option as deprecated in the help output.

double

fun RawOption.double(): OptionWithValues<Double?, Double, Double>

Convert the option values to a Double

enum

inline fun <T : Enum<T>> RawOption.enum(ignoreCase: Boolean = true, key: (T) -> String = { it.name }): NullableOption<T, T>

Convert the option to the values of an enum.

file

fun RawOption.file(mustExist: Boolean = false, canBeFile: Boolean = true, canBeDir: Boolean = true, mustBeWritable: Boolean = false, mustBeReadable: Boolean = false, canBeSymlink: Boolean = true): NullableOption<File, File>

Convert the option to a File.

finalize

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

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

flag

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

Turn an option into a boolean flag.

float

fun RawOption.float(): OptionWithValues<Float?, Float, Float>

Convert the option values to a Float

getValue

open operator override fun getValue(thisRef: ParameterHolder, property: KProperty<*>): AllT

groupChoice

fun <T : OptionGroup> RawOption.groupChoice(vararg choices: Pair<String, T>): ChoiceGroup<T, T?>

fun <T : OptionGroup> RawOption.groupChoice(choices: Map<String, T>): ChoiceGroup<T, T?>

Convert the option to an option group based on a fixed set of values.

groupSwitch

fun <T : OptionGroup> RawOption.groupSwitch(vararg choices: Pair<String, T>): ChoiceGroup<T, T?>

fun <T : OptionGroup> RawOption.groupSwitch(choices: Map<String, T>): ChoiceGroup<T, T?>

Convert the option into a set of flags that each map to an option group.

help

fun <AllT, EachT, ValueT> OptionWithValues<AllT, EachT, ValueT>.help(help: HelpTransformContext.() -> String): OptionWithValues<AllT, EachT, ValueT>

Set the help for this option lazily.

fun <AllT, EachT, ValueT> OptionWithValues<AllT, EachT, ValueT>.help(help: String): OptionWithValues<AllT, EachT, ValueT>

Set the help for this option.

inputStream

fun RawOption.inputStream(fileSystem: FileSystem = FileSystems.getDefault()): NullableOption<InputStream, InputStream>

Convert the option to an InputStream.

int

fun RawOption.int(acceptsValueWithoutName: Boolean = false): NullableOption<Int, Int>

Convert the option values to an Int

long

fun RawOption.long(acceptsValueWithoutName: Boolean = false): NullableOption<Long, Long>

Convert the option values to an Long

metavar

abstract fun metavar(context: Context): String?

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

multiple

fun <EachT, ValueT> NullableOption<EachT, ValueT>.multiple(default: List<EachT> = emptyList(), required: Boolean = false): OptionWithValues<List<EachT>, EachT, ValueT>

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

nullableFlag

fun RawOption.nullableFlag(vararg secondaryNames: String): NullableOption<Boolean, Boolean>

A flag that doesn't have a default value.

optionalValue

fun <ValueT : Any> NullableOption<ValueT, ValueT>.optionalValue(default: ValueT, acceptsUnattachedValue: Boolean = true): NullableOption<ValueT, ValueT>

Allow this option to be specified with or without an explicit value.

optionalValueLazy

fun <ValueT : Any> NullableOption<ValueT, ValueT>.optionalValueLazy(acceptsUnattachedValue: Boolean = true, default: () -> ValueT): NullableOption<ValueT, ValueT>

Allow this option to be specified with or without an explicit value.

optionHelp

abstract fun optionHelp(context: Context): String

The description of this option, usually a single line.

outputStream

fun RawOption.outputStream(createIfNotExist: Boolean = true, truncateExisting: Boolean = false, fileSystem: FileSystem = FileSystems.getDefault()): NullableOption<OutputStream, OutputStream>

Convert the option to an OutputStream.

pair

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

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

parameterHelp

open fun parameterHelp(context: Context): HelpFormatter.ParameterHelp.Option?

Information about this option for the help output.

path

fun RawOption.path(mustExist: Boolean = false, canBeFile: Boolean = true, canBeDir: Boolean = true, mustBeWritable: Boolean = false, mustBeReadable: Boolean = false, canBeSymlink: Boolean = true, fileSystem: FileSystem = FileSystems.getDefault()): NullableOption<Path, Path>

Convert the option to a Path.

postValidate

abstract fun postValidate(context: Context)

Called after all of a command's parameters have been finalized to perform validation of the final value.

prompt

fun OptionWithValues<Boolean, Boolean, Boolean>.prompt(text: String, default: Boolean? = null, uppercaseDefault: Boolean = true, showChoices: Boolean = true, choiceStrings: List<String> = listOf("y", "n"), promptSuffix: String = ": ", invalidChoiceMessage: String = "Invalid value, choose from "): OptionWithValues<Boolean, Boolean, Boolean>

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

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

provideDelegate

abstract operator override fun provideDelegate(thisRef: ParameterHolder, property: KProperty<*>): ReadOnlyProperty<ParameterHolder, AllT>

Implementations must call ParameterHolder.registerOption

required

fun <EachT, 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 MissingOption.

restrictTo

fun <T : Comparable<T>> OptionWithValues<T?, T, T>.restrictTo(range: ClosedRange<T>, clamp: Boolean = false): OptionWithValues<T?, T, T>

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

Restrict the option values to fit into a range.

split

fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.split(delimiter: String): OptionWithValues<List<ValueT>?, List<ValueT>, ValueT>

Change to option to take any number of values, separated by a string delimiter.

fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.split(regex: Regex): OptionWithValues<List<ValueT>?, List<ValueT>, ValueT>

Change to option to take any number of values, separated by a regex.

splitPair

fun RawOption.splitPair(delimiter: String = "="): NullableOption<Pair<String, String>, Pair<String, String>>

Split this option's value into two with a delimiter.

switch

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

fun <T : Any> RawOption.switch(choices: Map<String, T>): NullableOption<T, String>

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

toMap

fun <A, B, EachT, ValueT> OptionWithValues<List<Pair<A, B>>, EachT, ValueT>.toMap(): OptionWithValues<Map<A, B>, EachT, ValueT>

Convert this option's values from a list of pairs into a map with key-value pairs from the list.

transformAll

fun <AllT, EachT, ValueT> NullableOption<EachT, ValueT>.transformAll(defaultForHelp: String? = this.helpTags[HelpFormatter.Tags.DEFAULT], showAsRequired: Boolean = HelpFormatter.Tags.REQUIRED in this.helpTags, transform: AllTransformer<EachT, AllT>): OptionWithValues<AllT, EachT, ValueT>

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

transformValues

fun <EachT : Any, ValueT> NullableOption<ValueT, ValueT>.transformValues(nvalues: Int, transform: ValuesTransformer<ValueT, EachT>): NullableOption<EachT, ValueT>

fun <EachT, ValueT> NullableOption<ValueT, ValueT>.transformValues(nvalues: IntRange, transform: ValuesTransformer<ValueT, EachT>): NullableOption<EachT, ValueT>

Change the number of values that this option takes.

triple

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

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

uint

fun RawOption.uint(acceptsValueWithoutName: Boolean = false): NullableOption<UInt, UInt>

Convert the option values to a UInt

ulong

fun RawOption.ulong(acceptsValueWithoutName: Boolean = false): NullableOption<ULong, ULong>

Convert the option values to a ULong

unique

fun <T, EachT, ValueT> OptionWithValues<List<T>, EachT, ValueT>.unique(): OptionWithValues<Set<T>, EachT, ValueT>

Make a multiple option return a unique set of values

validate

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

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

varargValues

fun <ValueT> NullableOption<ValueT, ValueT>.varargValues(min: Int = 1, max: Int = Int.MAX_VALUE): NullableOption<List<ValueT>, ValueT>

Change this option to take a variable number of values.