Package com.github.ajalt.clikt.parameters.options

Types

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

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

EagerOption
Link copied to clipboard
common
class EagerOption(names: Set<String>, nvalues: Int, optionHelp: String, hidden: Boolean, helpTags: Map<String, String>, groupName: String?, callback: OptionTransformContext.() -> Unit) : StaticallyGroupedOption
An Option with no values that is finalized before other types of options.
FlagConverter
Link copied to clipboard
common
typealias FlagConverter<InT, OutT> = OptionTransformContext.(InT) -> OutT

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

FlagOption
Link copied to clipboard
common
class FlagOption<T> : OptionDelegate<T>
An Option that has no values.
NullableOption
Link copied to clipboard
common
typealias NullableOption<EachT, ValueT> = OptionWithValues<EachT?, EachT, ValueT>
Option
Link copied to clipboard
common
interface Option
An optional command line parameter that takes a fixed number of values.
OptionCallTransformContext
Link copied to clipboard
common
class OptionCallTransformContext(name: String, option: Option, context: Context) : Option
A receiver for options transformers.
OptionDelegate
Link copied to clipboard
common
interface OptionDelegate<T> : GroupableOption, ReadOnlyProperty<ParameterHolder, T>
An option that functions as a property delegate
OptionTransformContext
Link copied to clipboard
common
class OptionTransformContext(option: Option, context: Context) : Option
A receiver for options transformers.
OptionValidator
Link copied to clipboard
common
typealias OptionValidator<AllT> = OptionTransformContext.(AllT) -> Unit

A callback validates the final option type

OptionWithValues
Link copied to clipboard
common
class OptionWithValues<AllT, EachT, ValueT> : OptionDelegate<AllT> , GroupableOption
An Option that takes one or more values.
RawOption
Link copied to clipboard
common
typealias RawOption = NullableOption<String, String>
ValueConverter
Link copied to clipboard
common
typealias ValueConverter<InT, ValueT> = OptionCallTransformContext.(InT) -> ValueT

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

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

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

ValueWithDefault
Link copied to clipboard
common
data class ValueWithDefault<out T>(explicit: T?, default: T)
A container for a value that can have a default value and can be manually set

Functions

associate
Link copied to clipboard
common
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
Link copied to clipboard
common
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>
Check the final option value and raise an error if it's not valid.
@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.
@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.
convert
Link copied to clipboard
common
inline fun <InT, OutT> FlagOption<InT>.convert(crossinline conversion: FlagConverter<InT, OutT>): FlagOption<OutT>
Convert the option's value type.
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.
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.
counted
Link copied to clipboard
common
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
Link copied to clipboard
common
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.
defaultLazy
Link copied to clipboard
common
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.
deprecated
Link copied to clipboard
common
fun <T> FlagOption<T>.deprecated(message: String? = "", tagName: String? = "deprecated", tagValue: String = "", error: Boolean = false): OptionDelegate<T>
Mark this option as deprecated in the help output.
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
Link copied to clipboard
common
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.
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.
flag
Link copied to clipboard
common
fun RawOption.flag(vararg secondaryNames: String, default: Boolean = false, defaultForHelp: String = ""): FlagOption<Boolean>
Turn an option into a boolean flag.
help
Link copied to clipboard
common
fun <T> FlagOption<T>.help(help: String): FlagOption<T>
Set the help for this option.
fun <AllT, EachT, ValueT> OptionWithValues<AllT, EachT, ValueT>.help(help: String): OptionWithValues<AllT, EachT, ValueT>
Set the help for this option.
multiple
Link copied to clipboard
common
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.
option
Link copied to clipboard
common
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.
pair
Link copied to clipboard
common
fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.pair(): NullableOption<Pair<ValueT, ValueT>, ValueT>
Change this option to take two values, held in a Pair.
prompt
Link copied to clipboard
common
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
Link copied to clipboard
common
fun <T : Any> FlagOption<T?>.required(): FlagOption<T>
If the option is not called on the command line (and is not set in an envvar), throw a MissingOption.
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.
split
Link copied to clipboard
common
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
Link copied to clipboard
common
fun RawOption.splitPair(delimiter: String = "="): NullableOption<Pair<String, String>, Pair<String, String>>
Split this option's value into two with a delimiter.
switch
Link copied to clipboard
common
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.
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.
toMap
Link copied to clipboard
common
fun <A, B> OptionWithValues<List<Pair<A, B>>, Pair<A, B>, Pair<A, B>>.toMap(): OptionWithValues<Map<A, B>, Pair<A, B>, Pair<A, B>>
Convert this option's values from a list of pairs into a map with key-value pairs from the list.
transformAll
Link copied to clipboard
common
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.
transformValues
Link copied to clipboard
common
Change the number of values that this option takes.
triple
Link copied to clipboard
common
Change this option to take three values, held in a Triple.
unique
Link copied to clipboard
common
Make the multiple option return a unique set of calls

Example:

val opt: Set<Int> by option().int().multiple().unique()
validate
Link copied to clipboard
common
fun <T : Any> FlagOption<T>.validate(validator: OptionValidator<T>): OptionDelegate<T>
Check the final option value and raise an error if it's not valid.
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.
@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.
versionOption
Link copied to clipboard
common
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
Link copied to clipboard
common
fun <T> ValueWithDefault<T>.withDefault(default: T): ValueWithDefault<T>
Create a copy with a new default value
withExplicit
Link copied to clipboard
common
fun <T> ValueWithDefault<T>.withExplicit(explicit: T): ValueWithDefault<T>
Create a copy with a new explicit value