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

Package-level declarations

Types

AllTransformer

typealias AllTransformer<EachT, AllT> = OptionTransformContext.(List<EachT>) -> AllT

A callback that transforms all the calls to the final option type.

FlagConverter

typealias FlagConverter<InT, OutT> = OptionTransformContext.(InT) -> OutT

A block that converts a flag value from one type to another

NullableOption

typealias NullableOption<EachT, ValueT> = OptionWithValues<EachT?, EachT, ValueT>

Option

interface Option

An optional command line parameter that takes a fixed number of values.

OptionCallTransformContext

class OptionCallTransformContext(val name: String, val option: Option, val context: Context) : Option, TransformContext

A receiver for options transformers.

OptionDelegate

interface OptionDelegate<T> : GroupableOption, ReadOnlyProperty<ParameterHolder, T> , PropertyDelegateProvider<ParameterHolder, ReadOnlyProperty<ParameterHolder, T>>

An option that functions as a property delegate

OptionTransformContext

class OptionTransformContext(val option: Option, val context: Context) : Option, TransformContext

A receiver for options transformers.

OptionValidator

typealias OptionValidator<AllT> = OptionTransformContext.(AllT) -> Unit

A callback validates the final option type

OptionWithValues

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

An Option that takes one or more values.

RawOption

typealias RawOption = NullableOption<String, String>

ValueConverter

typealias ValueConverter<InT, ValueT> = OptionCallTransformContext.(InT) -> ValueT

A block that converts a single value from one type to another

ValuesTransformer

typealias ValuesTransformer<ValueT, EachT> = OptionCallTransformContext.(List<ValueT>) -> EachT

A callback that transforms all values for each call after the individual values have been converted.

ValueTransformer

typealias ValueTransformer<ValueT> = ValueConverter<String, ValueT>

A callback that transforms a single value from a string to the value type

ValueWithDefault

data class ValueWithDefault<out T>(val explicit: T?, val default: T)

A container for a value that can have a default value and can be manually set

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.

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.

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.

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.

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.

eagerOption

fun <T : CliktCommand> T.eagerOption(vararg names: String, help: String = "", hidden: Boolean = false, helpTags: Map<String, String> = emptyMap(), groupName: String? = null, action: OptionTransformContext.() -> Unit): T

fun <T : CliktCommand> T.eagerOption(names: Collection<String>, help: String = "", hidden: Boolean = false, helpTags: Map<String, String> = emptyMap(), groupName: String? = null, action: OptionTransformContext.() -> Unit): T

Add an eager option to this command that, when invoked, runs action.

flag

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

Turn an option into a boolean flag.

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.

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.

option

fun ParameterHolder.option(vararg names: String, help: String = "", metavar: String? = null, hidden: Boolean = false, envvar: String? = null, helpTags: Map<String, String> = emptyMap(), completionCandidates: CompletionCandidates? = null, valueSourceKey: String? = null, eager: Boolean = false): RawOption

Create a property delegate option.

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.

pair

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

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

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.

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.

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.

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.

versionOption

inline fun <T : CliktCommand> T.versionOption(version: String, help: String = "Show the version and exit", names: Set<String> = setOf("--version"), crossinline message: (String) -> String = { "$commandName version $it" }): T

Add an eager option to this command that, when invoked, prints a version message and exits.

withDefault

fun <T> ValueWithDefault<T>.withDefault(default: T): ValueWithDefault<T>

Create a copy with a new default value

withExplicit

fun <T> ValueWithDefault<T>.withExplicit(explicit: T): ValueWithDefault<T>

Create a copy with a new explicit value