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

Package-level declarations

Types

Link copied to clipboard
typealias ArgsTransformer<ValueT, EachT> = OptionCallTransformContext.(List<ValueT>) -> EachT

A callback that transforms all the values for a call to the call type.

The input list will always have a size equal to nvalues

Link copied to clipboard
typealias CallsTransformer<EachT, AllT> = OptionTransformContext.(List<EachT>) -> AllT

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

The input list will have a size equal to the number of times the option appears on the command line.

Link copied to clipboard
class EagerOption(val names: Set<String>, val nvalues: Int, val optionHelp: String, val hidden: Boolean, val helpTags: Map<String, String>, val groupName: String?, callback: OptionTransformContext.() -> Unit) : StaticallyGroupedOption

An Option with no values that is finalized before other types of options.

Link copied to clipboard
typealias FlagConverter<InT, OutT> = OptionTransformContext.(InT) -> OutT

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

Link copied to clipboard
class FlagOption<T> : OptionDelegate<T>

An Option that has no values.

Link copied to clipboard
Link copied to clipboard
interface Option

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

Link copied to clipboard
class OptionCallTransformContext(val name: String, val option: Option, val context: Context) : Option

A receiver for options transformers.

Link copied to clipboard
interface OptionDelegate<T> : GroupableOption, ReadOnlyProperty<ParameterHolder, T>

An option that functions as a property delegate

Link copied to clipboard
class OptionTransformContext(val option: Option, val context: Context) : Option

A receiver for options transformers.

Link copied to clipboard
typealias OptionValidator<AllT> = OptionTransformContext.(AllT) -> Unit

A callback validates the final option type

Link copied to clipboard
class OptionWithValues<AllT, EachT, ValueT> : OptionDelegate<AllT> , GroupableOption

An Option that takes one or more values.

Link copied to clipboard
Link copied to clipboard
typealias ValueConverter<InT, ValueT> = OptionCallTransformContext.(InT) -> ValueT

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

Link copied to clipboard
typealias ValueTransformer<ValueT> = ValueConverter<String, ValueT>

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

Link copied to clipboard
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

Link copied to clipboard
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.

Link copied to clipboard
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.

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.

Link copied to clipboard
inline fun <InT, OutT> FlagOption<InT>.convert(crossinline conversion: FlagConverter<InT, OutT>): FlagOption<OutT>
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>
inline fun <InT : Any, ValueT : Any> NullableOption<InT, InT>.convert(metavar: String, completionCandidates: CompletionCandidates = completionCandidatesWithDefault.default, crossinline conversion: ValueConverter<InT, ValueT>): NullableOption<ValueT, ValueT>

Convert the option's value type.

Link copied to clipboard
fun RawOption.counted(): FlagOption<Int>

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

Link copied to clipboard
fun <T : Any> FlagOption<T?>.default(value: T, defaultForHelp: String = value.toString()): FlagOption<T>

Set a default value for an option.

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.

Link copied to clipboard
inline fun <T : Any> FlagOption<T?>.defaultLazy(defaultForHelp: String = "", crossinline value: () -> T): FlagOption<T>

Set a default value for an option from a lazy builder which is only called if the default value is used.

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.

Link copied to clipboard
fun <T> FlagOption<T>.deprecated(message: String? = "", tagName: String? = "deprecated", tagValue: String = "", error: Boolean = false): OptionDelegate<T>
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.

Link copied to clipboard
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
fun <T : CliktCommand> T.eagerOption(name: String, vararg additionalNames: 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.

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

Turn an option into a boolean flag.

Link copied to clipboard
fun <T> FlagOption<T>.help(help: String): FlagOption<T>
fun <AllT, EachT, ValueT> OptionWithValues<AllT, EachT, ValueT>.help(help: String): OptionWithValues<AllT, EachT, ValueT>

Set the help for this option.

Link copied to clipboard
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.

Link copied to clipboard
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): RawOption

Create a property delegate option.

Link copied to clipboard
fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.pair(): NullableOption<Pair<ValueT, ValueT>, ValueT>

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

Link copied to clipboard
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.

Link copied to clipboard
fun <T : Any> FlagOption<T?>.required(): FlagOption<T>
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 MissingOption.

Link copied to clipboard
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.

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

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

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

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

Link copied to clipboard
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.

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

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

Link copied to clipboard
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.

Link copied to clipboard
fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.triple(): NullableOption<Triple<ValueT, ValueT, ValueT>, ValueT>

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

Link copied to clipboard
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

Link copied to clipboard
fun <T : Any> FlagOption<T>.validate(validator: OptionValidator<T>): OptionDelegate<T>
fun <AllT : Any, EachT, ValueT> OptionWithValues<AllT, EachT, ValueT>.validate(validator: OptionValidator<AllT>): OptionDelegate<AllT>
@JvmName(name = "nullableValidate")
inline fun <AllT : Any, EachT, ValueT> OptionWithValues<AllT?, EachT, ValueT>.validate(crossinline validator: OptionValidator<AllT>): OptionDelegate<AllT?>

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

Link copied to clipboard
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.

Link copied to clipboard
fun <T> ValueWithDefault<T>.withDefault(default: T): ValueWithDefault<T>

Create a copy with a new default value

Link copied to clipboard
fun <T> ValueWithDefault<T>.withExplicit(explicit: T): ValueWithDefault<T>

Create a copy with a new explicit value