Infendro/cli.kt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Wiki Activity

improve command handling, change argument/option registration

Browse Source
This commit is contained in:
Infendro
2026-01-08 18:53:54 +01:00
parent 2a9f086c9d
commit 6aa6c1b3c8
9 changed files with 123 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@@ -28,20 +28,20 @@ dependencies {
## Usage ## Usage
```kotlin ```kotlin
fun main(args: Array<String>) = cli("application") { fun main(args: Array<String>) = command("application") {
execute { execute {
// define execution of command (e.g., display help) // define execution of command (e.g., display help)
help() help()
} }
// declare command "greet" // register command "greet"
command("greet") { +command("greet") {
// declare arguments // declare and register arguments
val speakersArg by argument.string("speakers").variable(min = 1) val speakersArg = +argument.string("speakers").variable(min = 1)
// declare options // declare and register options
val greetingOpt by option.string("greeting", "greet", "g").orElse("Hello") val greetingOpt = +option.string("greeting", "greet", "g").orElse("Hello")
val nameOpt by option.string("name", "n").orNull() val nameOpt = +option.string("name", "n").orNull()
execute { execute {
// retrieve the arguments and options // retrieve the arguments and options
@@ -52,11 +52,11 @@ fun main(args: Array<String>) = cli("application") {
println("${speakers.joinToString()}: $greeting ${name ?: "World"}!") println("${speakers.joinToString()}: $greeting ${name ?: "World"}!")
} }
// declare more commands... // register more commands...
} }
// declare fallback command // register fallback command "value"
fallback.string("value") { valueArg -> +command.fallback.string("value") { valueArg ->
execute { execute {
// retrieve the value used for the fallback command // retrieve the value used for the fallback command
val value by valueArg val value by valueArg

112
src/commonMain/kotlin/com/infendro/cli/command/Command.kt
View File

@@ -8,12 +8,10 @@ import com.infendro.cli.command.help.DefaultHelpRenderer
import com.infendro.cli.command.help.HelpRenderer import com.infendro.cli.command.help.HelpRenderer
import com.infendro.cli.command.option.Option import com.infendro.cli.command.option.Option
import com.infendro.cli.error.build.* import com.infendro.cli.error.build.*
import com.infendro.cli.parser.* import com.infendro.cli.parser.Parser
import com.infendro.cli.util.Regex import com.infendro.cli.util.Regex
import kotlin.reflect.KProperty
sealed class Command private constructor( sealed class Command private constructor(
val parent: Command?,
val name: String, val name: String,
val commands: List<Command>, val commands: List<Command>,
val arguments: List<Argument<*>>, val arguments: List<Argument<*>>,
@@ -21,22 +19,21 @@ sealed class Command private constructor(
internal val execute: Context.() -> Unit, internal val execute: Context.() -> Unit,
internal val renderer: HelpRenderer, internal val renderer: HelpRenderer,
) { ) {
val path: List<Command> init {
get() = when { if (!name.matches(Regex.COMMAND)) throw InvalidCommand(name)
parent == null -> listOf(this) }
else -> parent.path + this
}
val help: String?
get() = renderer.render(this)
fun run(args: Array<String>) { fun run(args: Array<String>) {
when (val result = ContextParser(this, args).parse()) { when (val result = ContextParser(this, args).parse()) {
is ContextParser.Result.Success -> result.context.execute() is ContextParser.Result.Success -> result.context.execute()
is ContextParser.Result.Help -> result.command.help?.let { print(it) } is ContextParser.Result.Help -> {
val command = result.path.last()
command.renderer.render(result.path)?.let { print(it) }
}
is ContextParser.Result.Failure -> { is ContextParser.Result.Failure -> {
println("error: ${result.error.message}") println("error: ${result.error.message}")
result.command.help?.let { val command = result.path.last()
command.renderer.render(result.path)?.let {
println() println()
print(it) print(it)
} }
@@ -45,24 +42,22 @@ sealed class Command private constructor(
} }
class Named( class Named(
parent: Command?,
name: String, name: String,
commands: List<Command>, commands: List<Command>,
arguments: List<Argument<*>>, arguments: List<Argument<*>>,
options: List<Option<*>>, options: List<Option<*>>,
execute: Context.() -> Unit, execute: Context.() -> Unit,
renderer: HelpRenderer, renderer: HelpRenderer,
) : Command(parent, name, commands, arguments, options, execute, renderer) { ) : Command(name, commands, arguments, options, execute, renderer) {
class Builder( class Builder(
name: String, name: String,
) : Command.Builder<Named>(name) { ) : Command.Builder<Named>(name) {
override fun create() = override fun create() =
Named(parent, name, commands, arguments, options, execute, renderer) Named(name, commands, arguments, options, execute, renderer)
} }
} }
class Fallback<T : Any>( class Fallback<T : Any>(
parent: Command?,
val key: Key<T>, val key: Key<T>,
val parser: Parser<T>, val parser: Parser<T>,
name: String, name: String,
@@ -71,7 +66,7 @@ sealed class Command private constructor(
options: List<Option<*>>, options: List<Option<*>>,
execute: Context.() -> Unit, execute: Context.() -> Unit,
renderer: HelpRenderer, renderer: HelpRenderer,
) : Command(parent, name, commands, arguments, options, execute, renderer) { ) : Command(name, commands, arguments, options, execute, renderer) {
class Builder<T : Any>( class Builder<T : Any>(
val parser: Parser<T>, val parser: Parser<T>,
name: String, name: String,
@@ -79,7 +74,7 @@ sealed class Command private constructor(
internal val key = Key<T>() internal val key = Key<T>()
override fun create() = override fun create() =
Fallback(parent, key, parser, name, commands, arguments, options, execute, renderer) Fallback(key, parser, name, commands, arguments, options, execute, renderer)
} }
class Key<T> class Key<T>
@@ -89,8 +84,6 @@ sealed class Command private constructor(
sealed class Builder<COMMAND : Command>( sealed class Builder<COMMAND : Command>(
protected val name: String, protected val name: String,
) { ) {
protected var parent: Command? = null
private val builders = mutableListOf<Builder<*>>()
protected val commands = mutableListOf<Command>() protected val commands = mutableListOf<Command>()
protected val arguments = mutableListOf<Argument<*>>() protected val arguments = mutableListOf<Argument<*>>()
protected val options = mutableListOf<Option<*>>() protected val options = mutableListOf<Option<*>>()
@@ -102,40 +95,13 @@ sealed class Command private constructor(
protected val renderer: HelpRenderer protected val renderer: HelpRenderer
get() = _renderer!! get() = _renderer!!
fun command(name: String, block: Builder<*>.() -> Unit) { fun register(command: Command) {
validateCommand(name) validateCommand(command)
builders += Named.Builder(name).apply(block) commands += command
} }
inner class FallbackFactory { fun register(vararg commands: Command) = commands.forEach(::register)
fun string(name: String, block: Builder<*>.(Fallback.Key<String>) -> Unit) = operator fun <T : Command> T.unaryPlus() = also(::register)
fallback(StringParser, name, block)
fun int(name: String, block: Builder<*>.(Fallback.Key<Int>) -> Unit) =
fallback(IntParser, name, block)
fun long(name: String, block: Builder<*>.(Fallback.Key<Long>) -> Unit) =
fallback(LongParser, name, block)
fun float(name: String, block: Builder<*>.(Fallback.Key<Float>) -> Unit) =
fallback(FloatParser, name, block)
fun double(name: String, block: Builder<*>.(Fallback.Key<Double>) -> Unit) =
fallback(DoubleParser, name, block)
fun boolean(name: String, block: Builder<*>.(Fallback.Key<Boolean>) -> Unit) =
fallback(BooleanParser, name, block)
inline fun <reified T : Enum<T>> enum(name: String, noinline block: Builder<*>.(Fallback.Key<T>) -> Unit) =
fallback(enumParser<T>(), name, block)
}
val fallback = FallbackFactory()
fun <T : Any> fallback(parser: Parser<T>, name: String, block: Fallback.Builder<T>.(Fallback.Key<T>) -> Unit) {
validateCommand(name)
builders += Fallback.Builder(parser, name).apply { block(key) }
}
fun register(argument: Argument<*>) { fun register(argument: Argument<*>) {
validateArgument(argument) validateArgument(argument)
@@ -143,9 +109,7 @@ sealed class Command private constructor(
} }
fun register(vararg arguments: Argument<*>) = arguments.forEach(::register) fun register(vararg arguments: Argument<*>) = arguments.forEach(::register)
operator fun <T : Argument<*>> T.unaryPlus() = also(::register)
operator fun <T : Argument<*>> T.provideDelegate(thisRef: Nothing?, property: KProperty<*>) = also(::register)
operator fun <T : Argument<*>> T.getValue(thisRef: Nothing?, property: KProperty<*>) = this
fun register(option: Option<*>) { fun register(option: Option<*>) {
validateOption(option) validateOption(option)
@@ -153,9 +117,7 @@ sealed class Command private constructor(
} }
fun register(vararg options: Option<*>) = options.forEach(::register) fun register(vararg options: Option<*>) = options.forEach(::register)
operator fun <T : Option<*>> T.unaryPlus() = also(::register)
operator fun <T : Option<*>> T.provideDelegate(thisRef: Nothing?, property: KProperty<*>) = also(::register)
operator fun <T : Option<*>> T.getValue(thisRef: Nothing?, property: KProperty<*>) = this
fun execute(block: Context.() -> Unit) { fun execute(block: Context.() -> Unit) {
validateExecute() validateExecute()
@@ -167,32 +129,22 @@ sealed class Command private constructor(
_renderer = renderer _renderer = renderer
} }
internal abstract fun create(): COMMAND
internal fun build(): Command { internal fun build(): Command {
if (_execute == null) _execute = {} if (_execute == null) _execute = {}
if (_renderer == null) _renderer = DefaultHelpRenderer if (_renderer == null) _renderer = DefaultHelpRenderer
validate() validate()
val command = create() return create()
for (builder in builders) {
builder.parent = command
commands += builder.build()
}
return command
} }
internal abstract fun create(): COMMAND private fun validateCommand(command: Command) {
if (commands.isNotEmpty()) {
private fun validateCommand(name: String) { val last = commands.last()
if (builders.isNotEmpty()) { if (last is Fallback<*>) throw InvalidCommandOrder()
val last = builders.last()
if (last is Fallback.Builder<*>) throw InvalidCommandOrder()
}
when {
!name.matches(Regex.COMMAND) -> throw InvalidCommand(name)
builders.any { it.name == name } -> throw DuplicateCommand(name)
} }
if (commands.any { it.name == command.name }) throw DuplicateCommand(command.name)
} }
private fun validateArgument(argument: Argument<*>) { private fun validateArgument(argument: Argument<*>) {
@@ -203,6 +155,7 @@ sealed class Command private constructor(
argument.required && last.optional -> throw InvalidArgumentOrder() argument.required && last.optional -> throw InvalidArgumentOrder()
} }
} }
if (arguments.any { it.name == argument.name }) throw DuplicateArgument(argument.name)
} }
private fun validateOption(option: Option<*>) { private fun validateOption(option: Option<*>) {
@@ -220,10 +173,7 @@ sealed class Command private constructor(
} }
private fun validate() { private fun validate() {
if (builders.any { it is Fallback.Builder<*> } && arguments.isNotEmpty()) throw InvalidFallback() if (commands.any { it is Fallback<*> } && arguments.isNotEmpty()) throw InvalidFallback()
} }
} }
} }
fun cli(name: String, block: Command.Builder<*>.() -> Unit) =
Command.Named.Builder(name).apply(block).build()

39
src/commonMain/kotlin/com/infendro/cli/command/CommandFactory.kt Normal file
View File

@@ -0,0 +1,39 @@
package com.infendro.cli.command
import com.infendro.cli.command.Command.*
import com.infendro.cli.parser.*
class CommandFactory internal constructor() {
inner class FallbackFactory internal constructor() {
fun string(name: String, block: Builder<*>.(Fallback.Key<String>) -> Unit) =
fallback(StringParser, name, block)
fun int(name: String, block: Builder<*>.(Fallback.Key<Int>) -> Unit) =
fallback(IntParser, name, block)
fun long(name: String, block: Builder<*>.(Fallback.Key<Long>) -> Unit) =
fallback(LongParser, name, block)
fun float(name: String, block: Builder<*>.(Fallback.Key<Float>) -> Unit) =
fallback(FloatParser, name, block)
fun double(name: String, block: Builder<*>.(Fallback.Key<Double>) -> Unit) =
fallback(DoubleParser, name, block)
fun boolean(name: String, block: Builder<*>.(Fallback.Key<Boolean>) -> Unit) =
fallback(BooleanParser, name, block)
inline fun <reified T : Enum<T>> enum(name: String, noinline block: Builder<*>.(Fallback.Key<T>) -> Unit) =
fallback(enumParser<T>(), name, block)
}
fun <T : Any> fallback(parser: Parser<T>, name: String, block: Fallback.Builder<T>.(Fallback.Key<T>) -> Unit) =
Fallback.Builder(parser, name).apply { block(key) }.build()
val fallback = FallbackFactory()
}
fun command(name: String, block: Builder<*>.() -> Unit) =
Named.Builder(name).apply(block).build()
val command = CommandFactory()

7
src/commonMain/kotlin/com/infendro/cli/command/context/Context.kt
View File

@@ -8,15 +8,18 @@ import kotlin.reflect.KProperty
@Dsl @Dsl
class Context internal constructor( class Context internal constructor(
val command: Command, private val path: List<Command>,
private val commands: Map<Command.Fallback.Key<*>, Any>, private val commands: Map<Command.Fallback.Key<*>, Any>,
private val arguments: Map<Argument<*>, List<Any>>, private val arguments: Map<Argument<*>, List<Any>>,
private val options: Map<Option<*>, List<Any>>, private val options: Map<Option<*>, List<Any>>,
) { ) {
val command: Command
get() = path.last()
internal fun execute() = (command.execute)() internal fun execute() = (command.execute)()
fun help() { fun help() {
command.help?.let { print(it) } command.renderer.render(path)?.let { print(it) }
} }
@Suppress("UNCHECKED_CAST") @Suppress("UNCHECKED_CAST")

36
src/commonMain/kotlin/com/infendro/cli/command/context/ContextParser.kt
View File

@@ -14,18 +14,18 @@ internal class ContextParser(
) : Result() ) : Result()
data class Help( data class Help(
val command: Command, val path: List<Command>,
) : Result() ) : Result()
data class Failure( data class Failure(
val command: Command, val path: List<Command>,
val error: RunError, val error: RunError,
) : Result() ) : Result()
} }
private fun success(context: Context) = Result.Success(context) private fun success(context: Context) = Result.Success(context)
private fun help(command: Command) = Result.Help(command) private fun help(path: List<Command>) = Result.Help(path)
private fun failure(command: Command, exception: RunError) = Result.Failure(command, exception) private fun failure(path: List<Command>, exception: RunError) = Result.Failure(path, exception)
private var index = 0 private var index = 0
private val current: String private val current: String
@@ -41,6 +41,7 @@ internal class ContextParser(
fun parse(): Result { fun parse(): Result {
// command // command
var command = root var command = root
val path = mutableListOf(root)
val commands = mutableMapOf<Command.Fallback.Key<*>, Any>() val commands = mutableMapOf<Command.Fallback.Key<*>, Any>()
while (hasNext()) { while (hasNext()) {
@@ -52,16 +53,17 @@ internal class ContextParser(
} }
if (cmd == null) { if (cmd == null) {
when { when {
command.arguments.isEmpty() -> return failure(command, UnknownCommand(current)) command.arguments.isEmpty() -> return failure(path, UnknownCommand(current))
else -> break else -> break
} }
} }
command = cmd command = cmd
path += cmd
if (cmd is Command.Fallback<*>) { if (cmd is Command.Fallback<*>) {
val value = when (val result = cmd.parser.parse(current)) { val value = when (val result = cmd.parser.parse(current)) {
is Parser.Result.Success<*> -> result.value is Parser.Result.Success<*> -> result.value
is Parser.Result.Failure<*> -> return failure(command, result.error) is Parser.Result.Failure<*> -> return failure(path, result.error)
} }
commands[cmd.key] = value commands[cmd.key] = value
} }
@@ -85,11 +87,11 @@ internal class ContextParser(
// argument // argument
endOfOptions || dashes == 0 -> { endOfOptions || dashes == 0 -> {
val argument = command.arguments.getOrNull(argumentIndex) val argument = command.arguments.getOrNull(argumentIndex)
?: return failure(command, UnexpectedArgument()) ?: return failure(path, UnexpectedArgument())
val value = when (val result = argument.parser.parse(trimmed)) { val value = when (val result = argument.parser.parse(trimmed)) {
is Parser.Result.Success<*> -> result.value is Parser.Result.Success<*> -> result.value
is Parser.Result.Failure<*> -> return failure(command, result.error) is Parser.Result.Failure<*> -> return failure(path, result.error)
} }
arguments[argument]!! += value arguments[argument]!! += value
argumentCount++ argumentCount++
@@ -109,7 +111,7 @@ internal class ContextParser(
} }
if (dashes == 2 && trimmed == "help") if (dashes == 2 && trimmed == "help")
return help(command) return help(path)
val (name, text) = when { val (name, text) = when {
trimmed.contains('=') -> { trimmed.contains('=') -> {
@@ -133,16 +135,16 @@ internal class ContextParser(
for (name in names) { for (name in names) {
val option = command.options.firstOrNull { name in it.names } val option = command.options.firstOrNull { name in it.names }
?: return failure(command, UnknownOption(name)) ?: return failure(path, UnknownOption(name))
val value = when { val value = when {
text != null -> text != null ->
when (val result = option.parser.parse(current)) { when (val result = option.parser.parse(current)) {
is Parser.Result.Success<*> -> result.value is Parser.Result.Success<*> -> result.value
is Parser.Result.Failure<*> -> return failure(command, result.error) is Parser.Result.Failure<*> -> return failure(path, result.error)
} }
option.flag -> option.fallback!! option.flag -> option.fallback!!
else -> return failure(command, MissingOptionValue(option)) else -> return failure(path, MissingOptionValue(option))
} }
options[option]!! += value options[option]!! += value
} }
@@ -153,9 +155,9 @@ internal class ContextParser(
when { when {
current.contains('=') -> { current.contains('=') -> {
val (option) = current.split('=', limit = 2) val (option) = current.split('=', limit = 2)
return failure(command, MalformedOption(option)) return failure(path, MalformedOption(option))
} }
else -> return failure(command, MalformedOption(current)) else -> return failure(path, MalformedOption(current))
} }
} }
} }
@@ -166,16 +168,16 @@ internal class ContextParser(
// validate arguments // validate arguments
for (argument in command.arguments) { for (argument in command.arguments) {
val count = arguments[argument]!!.count() val count = arguments[argument]!!.count()
if (count !in argument.min..argument.count) return failure(command, InvalidArgumentCount(argument, count)) if (count !in argument.min..argument.count) return failure(path, InvalidArgumentCount(argument, count))
} }
// validate options // validate options
for (option in command.options) { for (option in command.options) {
val count = options[option]!!.count() val count = options[option]!!.count()
if (count !in option.min..option.count) return failure(command, InvalidOptionCount(option, count)) if (count !in option.min..option.count) return failure(path, InvalidOptionCount(option, count))
} }
val context = Context(command, commands, arguments, options) val context = Context(path, commands, arguments, options)
return success(context) return success(context)
} }
} }

12
src/commonMain/kotlin/com/infendro/cli/command/help/DefaultHelpRenderer.kt
View File

@@ -5,8 +5,10 @@ import com.infendro.cli.command.argument.Argument
import com.infendro.cli.command.option.Option import com.infendro.cli.command.option.Option
object DefaultHelpRenderer : HelpRenderer { object DefaultHelpRenderer : HelpRenderer {
override fun render(command: Command) = buildString { override fun render(path: List<Command>) = buildString {
usage(command) val command = path.last()
usage(path)
if (command.commands.isNotEmpty()) { if (command.commands.isNotEmpty()) {
appendLine() appendLine()
commands(command.commands) commands(command.commands)
@@ -21,9 +23,11 @@ object DefaultHelpRenderer : HelpRenderer {
} }
} }
private fun StringBuilder.usage(command: Command) { private fun StringBuilder.usage(path: List<Command>) {
val command = path.last()
append("Usage:") append("Usage:")
for (command in command.path) { for (command in path) {
append(" ") append(" ")
when { when {
command is Command.Fallback<*> -> append("<${command.name}>") command is Command.Fallback<*> -> append("<${command.name}>")

2
src/commonMain/kotlin/com/infendro/cli/command/help/HelpRenderer.kt
View File

@@ -3,5 +3,5 @@ package com.infendro.cli.command.help
import com.infendro.cli.command.Command import com.infendro.cli.command.Command
interface HelpRenderer { interface HelpRenderer {
fun render(command: Command): String? fun render(path: List<Command>): String?
} }

2
src/commonMain/kotlin/com/infendro/cli/command/help/NoopHelpRenderer.kt
View File

@@ -3,5 +3,5 @@ package com.infendro.cli.command.help
import com.infendro.cli.command.Command import com.infendro.cli.command.Command
object NoopHelpRenderer : HelpRenderer { object NoopHelpRenderer : HelpRenderer {
override fun render(command: Command) = null override fun render(path: List<Command>) = null
} }

8
src/commonMain/kotlin/com/infendro/cli/error/build/DuplicateArgument.kt Normal file
View File

@@ -0,0 +1,8 @@
package com.infendro.cli.error.build
class DuplicateArgument(
val name: String,
) : BuildException() {
override val message: String
get() = """duplicate argument "$name""""
}