OptionWithValues

An Option that takes one or more values.

Properties

Link copied to clipboard

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

Link copied to clipboard

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

Link copied to clipboard

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

Link copied to clipboard
open val eager: Boolean

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

Link copied to clipboard
abstract val envvar: String?

The environment variable name to use.

Link copied to clipboard

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

Link copied to clipboard
abstract override var groupName: String?

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

Link copied to clipboard

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

Link copied to clipboard
abstract val helpTags: Map<String, String>

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

Link copied to clipboard
abstract val hidden: Boolean

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

Link copied to clipboard
abstract val metavarGetter: Context.() -> String??

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

Link copied to clipboard
abstract val names: Set<String>

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

Link copied to clipboard
abstract val nvalues: IntRange

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

Link copied to clipboard

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

Link copied to clipboard
abstract val secondaryNames: Set<String>

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

Link copied to clipboard

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

Link copied to clipboard

Called in finalize to transform each invocation.

Link copied to clipboard

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

Link copied to clipboard

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

Link copied to clipboard
abstract val value: AllT

The value for this option.

Link copied to clipboard
abstract val valueSourceKey: String?

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

Link copied to clipboard
abstract val valueSplit: Regex?

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

Functions

Link copied to clipboard

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

Link copied to clipboard

Convert the option values to Boolean

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

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

Link copied to clipboard

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.

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

Link copied to clipboard

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

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

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

Convert the option values to a Double

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

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

Link copied to clipboard
abstract fun finalize(context: Context, invocations: List<Invocation>)

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

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

Turn an option into a boolean flag.

Link copied to clipboard

Convert the option values to a Float

Link copied to clipboard
open operator override fun getValue(thisRef: ParameterHolder, property: KProperty<*>): AllT
Link copied to clipboard
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.

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

Link copied to clipboard

Set the help for this option lazily.

Set the help for this option.

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

Convert the option to an InputStream.

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

Convert the option values to an Int

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

Convert the option values to an Long

Link copied to clipboard
abstract fun metavar(context: Context): String?

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

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

Link copied to clipboard

A flag that doesn't have a default value.

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

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

Link copied to clipboard
abstract fun optionHelp(context: Context): String

The description of this option, usually a single line.

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

Convert the option to an OutputStream.

Link copied to clipboard

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

Link copied to clipboard

Information about this option for the help output.

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

Link copied to clipboard
abstract fun postValidate(context: Context)

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

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

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

Implementations must call ParameterHolder.registerOption

Link copied to clipboard

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

Link copied to clipboard

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

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

Link copied to clipboard

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

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

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

Link copied to clipboard

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, 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.

Link copied to clipboard

Change the number of values that this option takes.

Link copied to clipboard

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

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

Convert the option values to a UInt

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

Convert the option values to a ULong

Link copied to clipboard

Make a multiple option return a unique set of values

Link copied to clipboard

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

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