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

OptionWithValues

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

An Option that takes one or more values.

Functions

fun copy(validator: OptionValidator<AllT> = this.transformValidator, names: Set<String> = this.names, metavarWithDefault: ValueWithDefault<Context.() -> String?> = this.metavarWithDefault, nvalues: Int = this.nvalues, help: String = this.optionHelp, hidden: Boolean = this.hidden, helpTags: Map<String, String> = this.helpTags, envvar: String? = this.envvar, valueSourceKey: String? = this.valueSourceKey, valueSplit: Regex? = this.valueSplit, parser: OptionWithValuesParser = this.parser, completionCandidatesWithDefault: ValueWithDefault<CompletionCandidates> = this.completionCandidatesWithDefault): OptionWithValues<AllT, EachT, ValueT>

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

fun <AllT, EachT, ValueT> copy(transformValue: ValueTransformer<ValueT>, transformEach: ArgsTransformer<ValueT, EachT>, transformAll: CallsTransformer<EachT, AllT>, validator: OptionValidator<AllT>, names: Set<String> = this.names, metavarWithDefault: ValueWithDefault<Context.() -> String?> = this.metavarWithDefault, nvalues: Int = this.nvalues, help: String = this.optionHelp, hidden: Boolean = this.hidden, helpTags: Map<String, String> = this.helpTags, valueSourceKey: String? = this.valueSourceKey, envvar: String? = this.envvar, valueSplit: Regex? = this.valueSplit, parser: OptionWithValuesParser = this.parser, completionCandidatesWithDefault: ValueWithDefault<CompletionCandidates> = this.completionCandidatesWithDefault): OptionWithValues<AllT, EachT, ValueT>

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

finalize

open override fun finalize(context: Context, invocations: List<OptionParser.Invocation>)

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

getValue

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

metavar

open override fun metavar(context: Context): String?

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

parameterHelp

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

Information about this option for the help output.

postValidate

open override fun postValidate(context: Context)

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

provideDelegate

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

Implementations must call ParameterHolder.registerOption

Properties

completionCandidates

open override val completionCandidates: CompletionCandidates

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

completionCandidatesWithDefault

val completionCandidatesWithDefault: ValueWithDefault<CompletionCandidates>

envvar

val envvar: String?

The environment variable name to use.

groupName

open override var groupName: String? = null

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

helpTags

open override val helpTags: Map<String, String>

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

hidden

open override val hidden: Boolean

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

metavarWithDefault

val metavarWithDefault: ValueWithDefault<Context.() -> String?>

The metavar to use. Specified at option creation.

names

open override var names: Set<String>

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

nvalues

open override val nvalues: Int

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

optionHelp

open override val optionHelp: String

The description of this option, usually a single line.

parameterGroup

open override var parameterGroup: ParameterGroup? = null

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

parser

open override val parser: OptionWithValuesParser

The parser for this option's values.

secondaryNames

open override 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.

transformValidator

val transformValidator: OptionValidator<AllT>

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

transformValue

val transformValue: ValueTransformer<ValueT>

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

value

open override var value: AllT

The value for this option.

valueSourceKey

open override val valueSourceKey: String?

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

valueSplit

val valueSplit: Regex?

The pattern to split values from the command line on. By default, values are split on whitespace.

Extensions

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.

check

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

@JvmName(name = "nullableCheck")

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

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

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

@JvmName(name = "nullableLazyCheck")

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

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

choice

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

fun <T : Any> RawOption.choice(vararg choices: Pair<String, T>, metavar: String = mvar(choices.map { it.first }), 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 <InT : Any, ValueT : Any> NullableOption<InT, InT>.convert(metavar: String, completionCandidates: CompletionCandidates = completionCandidatesWithDefault.default, crossinline conversion: ValueConverter<InT, ValueT>): NullableOption<ValueT, ValueT>

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

Convert the option's 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, 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 : Any, 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.

flag

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

Turn an option into a boolean flag.

float

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

Convert the option values to a Float

groupChoice

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

fun <T : OptionGroup> RawOption.groupChoice(vararg choices: Pair<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(choices: Map<String, T>): ChoiceGroup<T, T?>

fun <T : OptionGroup> RawOption.groupSwitch(vararg choices: Pair<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: 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(): OptionWithValues<Int?, Int, Int>

Convert the option values to an Int

long

fun RawOption.long(): OptionWithValues<Long?, Long, Long>

Convert the option values to a Long

multiple

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

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 <EachT : Any, ValueT> NullableOption<EachT, ValueT>.pair(): NullableOption<Pair<ValueT, ValueT>, ValueT>

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

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.

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