OptionWithValues

An Option that takes one or more values.

Functions

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

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

Link copied to clipboard
open operator override fun getValue(thisRef: ParameterHolder, property: KProperty<*>): AllT
Link copied to clipboard
open override fun metavar(context: Context): String?

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

Link copied to clipboard

Information about this option for the help output.

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

Implementations must call ParameterHolder.registerOption

Properties

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

The environment variable name to use.

Link copied to clipboard
open override var groupName: String? = null

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

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

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

Link copied to clipboard
open override val hidden: Boolean

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

Link copied to clipboard

The metavar to use. Specified at option creation.

Link copied to clipboard
open override var names: Set<String>

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

Link copied to clipboard
open override val nvalues: Int

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

Link copied to clipboard
open override val optionHelp: String

The description of this option, usually a single line.

Link copied to clipboard
open override var parameterGroup: ParameterGroup? = null

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

Link copied to clipboard
open override val parser: OptionWithValuesParser

The parser for this option's values.

Link copied to clipboard
open override 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
open override var value: AllT

The value for this option.

Link copied to clipboard
open override val valueSourceKey: String?

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

Link copied to clipboard

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

Extensions

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

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

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

Link copied to clipboard

Turn an option into a flag that counts the number of times the option 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 : 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

Use - as the default value for an inputStream option.

Link copied to clipboard

Use - as the default value for an outputStream option.

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
fun RawOption.flag(vararg secondaryNames: String, default: Boolean = false, defaultForHelp: String = ""): FlagOption<Boolean>

Turn an option into a boolean flag.

Link copied to clipboard

Convert the option values to a Float

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.

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

Convert the option to an InputStream.

Link copied to clipboard

Convert the option values to an Int

Link copied to clipboard

Convert the option values to a Long

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

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(min: T? = null, max: T? = null, clamp: Boolean = false): OptionWithValues<T?, T, T>
fun <T : Comparable<T>> OptionWithValues<T?, T, T>.restrictTo(range: ClosedRange<T>, 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 regex.

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

Link copied to clipboard

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

Link copied to clipboard
fun <T : Any> RawOption.switch(choices: Map<String, T>): FlagOption<T?>
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.

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

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

Make a multiple option return a unique set of values

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