argot-core/org.draftcode.argot

Package-level declarations

Types

ArgotConversionException

class ArgotConversionException(message: String, cause: Throwable? = null) : Exception

Thrown by a Converter when a raw string cannot be converted to the target type.

ArgotEngine

object ArgotEngine

Parses an argument list against a CommandSpec.

ArgotParseException

sealed class ArgotParseException : Exception

Base type for all user-input parsing failures. The cli wrapper prints usage and the message to stderr and exits 2.

ArgumentBuilder

class ArgumentBuilder<T : Any> : PropertyDelegateProvider<Arguments, ReadOnlyProperty<Arguments, T>>

Builds a positional argument, named after the property it is assigned to. The call you end with decides the property's type:

ArgumentListBuilder

class ArgumentListBuilder<T : Any> : PropertyDelegateProvider<Arguments, ReadOnlyProperty<Arguments, List<T>>>

A trailing list argument, reached via ArgumentBuilder.multiple. Resolves to an empty list when no positionals remain, unless required is set.

Arguments

abstract class Arguments(val programName: String = "program", val description: String = "", val version: String? = null)

Base class for declaring a command line with by delegates.

ArgumentSpec

class ArgumentSpec(val name: String, val converter: Converter<*>, val help: String = "", val required: Boolean = true, val multiple: Boolean = false) : ParamSpec

A positional parameter, consumed left to right from the non-option arguments.

BooleanConverter

object BooleanConverter : Converter<Boolean>

Accepts, case-insensitively, true/false, 1/0, yes/no, y/n, and on/off.

CommandSpec

class CommandSpec(val programName: String, val description: String = "", val params: List<ParamSpec>, val version: String? = null)

Describes a command: its name, description, optional version, and parameters.

Converter

interface Converter<out T>

Converts a raw command-line string into a typed value. Implement this to support a type beyond the built-ins.

DoubleConverter

object DoubleConverter : Converter<Double>

EnumConverter

class EnumConverter<out E : Enum<*>>(entries: List<E>, val typeName: String) : Converter<E>

Matches a raw value against enum constant names, case-insensitively.

FlagBuilder

class FlagBuilder : PropertyDelegateProvider<Arguments, ReadOnlyProperty<Arguments, Boolean>>

Builds a boolean flag. A flag name means true, a negation name means false, and absence means default.

FlagSpec

class FlagSpec(val names: List<String>, val help: String = "", val negationNames: List<String> = emptyList(), val default: Boolean = false) : ParamSpec

A named boolean parameter whose presence means true.

HelpRequested

class HelpRequested : RuntimeException

Thrown when --help or -h is present. Not an error: cli prints rendered and exits 0.

IntConverter

object IntConverter : Converter<Int>

LongConverter

object LongConverter : Converter<Long>

OptionalArgumentBuilder

class OptionalArgumentBuilder<T : Any> : PropertyDelegateProvider<Arguments, ReadOnlyProperty<Arguments, T?>>

An optional positional argument, reached via ArgumentBuilder.optional. Resolves to null when absent.

OptionBuilder

class OptionBuilder<T : Any> : PropertyDelegateProvider<Arguments, ReadOnlyProperty<Arguments, T?>>

Builds a value-bearing option. The call you end with decides the property's type:

OptionListBuilder

class OptionListBuilder<T : Any> : PropertyDelegateProvider<Arguments, ReadOnlyProperty<Arguments, List<T>>>

A repeatable option, reached via OptionBuilder.multiple. Resolves to an empty list when the option never appears, unless required is set.

OptionSpec

class OptionSpec(val names: List<String>, val converter: Converter<*>, val help: String = "", val required: Boolean = false, val default: Any? = null, val multiple: Boolean = false) : ParamSpec

A named parameter that takes a value, for example --count 3, --count=3, or -c 3.

ParamSpec

sealed class ParamSpec

A declared command-line parameter: an OptionSpec, FlagSpec, or ArgumentSpec.

ParsedValues

class ParsedValues

The typed result of a successful parse, keyed by each parameter's canonical name.

RequiredOptionBuilder

class RequiredOptionBuilder<T : Any> : PropertyDelegateProvider<Arguments, ReadOnlyProperty<Arguments, T>>

An option that always resolves to a value, reached via OptionBuilder.required or OptionBuilder.default.

StringConverter

object StringConverter : Converter<String>

VersionRequested

class VersionRequested : RuntimeException

Thrown when --version is present and CommandSpec.version is set. cli prints rendered and exits 0.

Functions

cli

fun <T> cli(block: () -> T): T

Runs block and turns Argot's outcomes into the usual command-line behaviour:

enumConverter

inline fun <E : Enum<E>> enumConverter(): EnumConverter<E>

parse

fun <T : Arguments> T.parse(argv: Array<String>): T

Parses argv into this instance and returns it, without printing or exiting.

parsed

fun <T : Arguments> T.parsed(argv: Array<String>): T

Parses argv into this instance via cli, printing help or errors and exiting as appropriate.