Maps the parsed value using the specified transformation function. For non-nullable builders (from .default() or .required()), preserves non-nullable type when transformation returns non-null. For nullable builders, always returns nullable type.

negatable

fun OptionBuilder<Boolean?>.negatable(prefix: String? = null): OptionBuilder<Boolean?>

Makes this nullable boolean option negatable with a custom prefix. Creates an automatic negation option (e.g., --disable-colors for --colors with prefix "disable-").

@JvmName(name = "negatableNonNull")

fun OptionBuilder<Boolean>.negatable(prefix: String? = null): OptionBuilder<Boolean>

Makes this non-nullable boolean option negatable with a custom prefix. Creates an automatic negation option (e.g., --disable-colors for --colors with prefix "disable-").

oneOf

fun OptionBuilder<String?>.oneOf(vararg allowed: String, ignoreCase: Boolean = true): OptionBuilder<String?>

Restricts string option to one of the specified allowed values.

onlyInDomains

fun onlyInDomains(vararg refs: KProperty<*>): OptionBuilder<T>

Restricts this option to be available only in the specified domains.

onValue

fun onValue(callback: (T) -> Unit): OptionBuilder<T>

Registers a callback to be executed when this option's value is found during parsing. The callback receives the converted value and is executed after all parsing and validation completes. Callbacks are executed in the order their values appear on the command line.

password

fun OptionBuilder<String?>.password(prompt: String = "Password: ", confirmPrompt: String = "Confirm password: ", requireConfirmation: Boolean = false, mismatchPrompt: String = "Passwords do not match. Please try again.", maxRetries: Int = 3): OptionBuilder<CharArray?>

Converts string option to password option with prompting capabilities.

provideDelegate

open operator override fun provideDelegate(thisRef: Arguments, property: KProperty<*>): ReadOnlyProperty<Arguments, T>

Provides the property delegate implementation for command-line options. This method is called automatically by Kotlin's property delegation system. It registers the option with the Arguments instance and returns a delegate that provides access to the parsed value.

required

fun <T> OptionBuilder<T>.required(): OptionBuilder<T>

Marks this option as required.

@JvmName(name = "requiredGeneric")

fun <T : Any> OptionBuilder<T?>.required(): NonNullableOptionBuilder<T>

Marks this nullable option as required, converting it to a non-nullable type.

requireIfAllPresent

fun requireIfAllPresent(vararg refs: KProperty<*>): OptionBuilder<T>

Requires that this option be present when all of the specified properties are present.

requireIfAnyPresent

fun requireIfAnyPresent(vararg refs: KProperty<*>): OptionBuilder<T>

Requires that this option be present along with any of the specified properties.

requireIfValue

fun <U> requireIfValue(ref: KProperty<U>, predicate: (U?) -> Boolean): OptionBuilder<T>

Requires that this option be present when the specified property matches the given predicate.

requiresValue

fun <T> OptionBuilder<T>.requiresValue(requires: Boolean): OptionBuilder<T>

Controls whether this option requires a value.

set

fun <T : Any> OptionBuilder<T?>.set(): OptionSetBuilder<T>

Converts option to set collector.

validate

fun validate(vararg validations: Pair<String, (T) -> Boolean>): OptionBuilder<T>

Adds multiple validators at once.

fun validate(message: String = "Invalid value for @name: @value", predicate: (T) -> Boolean): OptionBuilder<T>

Adds a validator that checks the parsed value against the given predicate. The validator only runs if the value is not null.