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

implement automatic help

Browse Source
This commit is contained in:
Infendro
2026-01-07 18:53:35 +01:00
parent 4e9b358ef8
commit ecd255479a
18 changed files with 277 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/commonMain/kotlin/com/infendro/cli/command/Argument.kt
View File

@@ -10,9 +10,7 @@ sealed class Argument<T : Any>(
val max: Int?,
) {
init {
when {
min !in 0..count -> throw InvalidRange()
}
if (min !in 0..count || max == 0) throw InvalidRange()
}
val required: Boolean

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

@@ -3,25 +3,42 @@ package com.infendro.cli.command
import com.infendro.cli.Dsl
import com.infendro.cli.command.context.Context
import com.infendro.cli.command.context.Parser
import com.infendro.cli.command.help.DefaultHelpRenderer
import com.infendro.cli.command.help.HelpRenderer
import com.infendro.cli.exception.build.*
import com.infendro.cli.exception.run.RunException
import com.infendro.cli.util.Regex.ARGUMENT
import com.infendro.cli.util.Regex.COMMAND
import com.infendro.cli.util.Regex.OPTION
import kotlin.reflect.KProperty
class Command private constructor(
val parent: Command?,
val name: String,
val fallback: Boolean,
val commands: List<Command>,
val arguments: List<Argument<*>>,
val options: List<Option<*>>,
internal val execute: Context.() -> Unit,
internal val renderer: HelpRenderer,
) {
fun run(args: Array<String>) = try {
Parser.parse(this, args).execute()
} catch (e: RunException) {
println(e.message)
val path: List<Command>
get() = when {
parent == null -> listOf(this)
else -> parent.path + this
}
val help: String?
get() = renderer.render(this)
fun run(args: Array<String>) {
when (val result = Parser(this, args).parse()) {
is Parser.Result.Success -> result.context.execute()
is Parser.Result.Help -> result.command.help?.let { println(it) }
is Parser.Result.Failure -> {
println("error: ${result.exception.message}")
result.command.help?.let { println("\n$it") }
}
}
}
@Dsl
@@ -29,8 +46,10 @@ class Command private constructor(
private val level: Int,
private val name: String,
private val fallback: Boolean,
var renderer: HelpRenderer,
) {
private val commands = mutableListOf<Command>()
private var parent: Command? = null
private val builders = mutableListOf<Builder>()
private val arguments = mutableListOf<Argument<*>>()
private val options = mutableListOf<Option<*>>()
private lateinit var _execute: Context.() -> Unit
@@ -40,12 +59,12 @@ class Command private constructor(
fun command(name: String, block: Builder.() -> Unit) {
validateCommand(name)
commands += Builder(level + 1, name, fallback = false).apply(block).build()
builders += Builder(level + 1, name, fallback = false, renderer).apply(block)
}
fun fallback(name: String, block: Builder.(Key) -> Unit) {
validateCommand(name)
commands += Builder(level + 1, name, fallback = true).apply { block(key) }.build()
builders += Builder(level + 1, name, fallback = true, renderer).apply { block(key) }
}
fun argument(argument: Argument<*>) {
@@ -78,19 +97,24 @@ class Command private constructor(
_execute = {}
validate()
return Command(name, fallback, commands, arguments, options, _execute)
val commands = mutableListOf<Command>()
val command = Command(parent, name, fallback, commands, arguments, options, _execute, renderer)
for (builder in builders) {
builder.parent = command
commands += builder.build()
}
return command
}
private fun validateCommand(name: String) {
if (commands.isNotEmpty()) {
val last = commands.last()
when {
last.fallback -> throw InvalidCommandOrder()
}
if (builders.isNotEmpty()) {
val last = builders.last()
if (last.fallback) throw InvalidCommandOrder()
}
when {
!name.matches(COMMAND) -> throw InvalidCommand(name)
commands.any { it.name == name } -> throw DuplicateCommand(name)
builders.any { it.name == name } -> throw DuplicateCommand(name)
}
}
@@ -102,9 +126,7 @@ class Command private constructor(
argument.required && last.optional -> throw InvalidArgumentOrder()
}
}
when {
!argument.name.matches(ARGUMENT) -> throw InvalidArgument(argument.name)
}
if (!argument.name.matches(ARGUMENT)) throw InvalidArgument(argument.name)
}
private fun validateOption(option: Option<*>) {
@@ -117,14 +139,11 @@ class Command private constructor(
}
private fun validateExecute() {
if (::_execute.isInitialized)
throw DuplicateExecute()
if (::_execute.isInitialized) throw DuplicateExecute()
}
private fun validate() {
if (commands.any { it.fallback } && arguments.isNotEmpty()) {
throw InvalidFallback()
}
if (builders.any { it.fallback } && arguments.isNotEmpty()) throw InvalidFallback()
}
}
@@ -134,4 +153,4 @@ class Command private constructor(
}
fun cli(name: String, block: Command.Builder.() -> Unit) =
Command.Builder(-1, name, fallback = false).apply(block).build()
Command.Builder(-1, name, fallback = false, DefaultHelpRenderer).apply(block).build()

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

@@ -33,7 +33,7 @@ sealed class Option<T : Any>(
init {
when {
names.isEmpty() -> throw MissingOptionName()
min !in 0..count -> throw InvalidRange()
min !in 0..count || max == 0 -> throw InvalidRange()
}
}

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

@@ -10,8 +10,8 @@ import kotlin.reflect.KProperty
class Context internal constructor(
val command: Command,
val commands: List<Cmd>,
val options: List<Opt>,
val arguments: List<Arg>,
val options: List<Opt>,
) {
class Cmd(
val name: String,
@@ -28,6 +28,10 @@ class Context internal constructor(
internal fun execute() = (command.execute)()
fun help() {
command.help?.let { println(it) }
}
operator fun Command.Key.getValue(thisRef: Any?, property: KProperty<*>): String = commands[index].name
private val <T : Any> Argument<T>.index: Int

113
src/commonMain/kotlin/com/infendro/cli/command/context/Parser.kt
View File

@@ -4,26 +4,55 @@ import com.infendro.cli.command.Command
import com.infendro.cli.command.context.Context.*
import com.infendro.cli.exception.run.*
internal object Parser {
fun parse(root: Command, args: Array<String>): Context {
internal class Parser(
private val root: Command,
private val args: Array<String>,
) {
private var index = 0
private val current: String
get() = args[index]
private val next: String?
get() = args.getOrNull(index)
private fun hasNext() = index < args.size
private fun consume() {
index++
}
sealed class Result {
data class Success(
val context: Context,
) : Result()
data class Help(
val command: Command,
) : Result()
data class Failure(
val command: Command,
val exception: RunException,
) : Result()
}
fun success(context: Context) = Result.Success(context)
fun help(command: Command) = Result.Help(command)
fun failure(command: Command, exception: RunException) = Result.Failure(command, exception)
fun parse(): Result {
var command = root
val cmd = mutableListOf<Cmd>()
val arg = mutableListOf<Arg>()
val opt = mutableListOf<Opt>()
var i = 0
// commands
while (i < args.size) {
val current = args[i]
// command
while (hasNext()) {
if (current.startsWith("-"))
break
val c = command.commands.firstOrNull { it.name == current || it.fallback }
if (c == null) {
when {
command.arguments.isEmpty() -> throw UnknownCommand(current)
command.arguments.isEmpty() -> return failure(command, UnknownCommand(current))
else -> break
}
}
@@ -31,24 +60,25 @@ internal object Parser {
command = c
cmd += Cmd(current)
i++
consume()
}
// arguments and options
var endOfOptions = false
var argumentIndex = 0
var argumentCount = 0
while (i < args.size) {
val dashes = args[i].takeWhile { it == '-' }.count()
val current = args[i].drop(dashes)
while (hasNext()) {
val dashes = current.takeWhile { it == '-' }.count()
val trimmed = current.drop(dashes)
when {
// argument
endOfOptions || dashes == 0 -> {
val argument = command.arguments.getOrNull(argumentIndex)
?: throw UnexpectedArgument()
?: return failure(command, UnexpectedArgument())
val value = argument.parser.parse(current)
val value = argument.parser.parse(trimmed)
arg += Arg(value)
argumentCount++
@@ -60,25 +90,26 @@ internal object Parser {
// option
dashes in 1..2 -> {
if (dashes == 2 && current.isEmpty()) {
if (dashes == 2 && trimmed.isEmpty()) {
endOfOptions = true
i++
consume()
continue
}
if (dashes == 2 && trimmed == "help")
return help(command)
val (name, text) = when {
current.contains('=') -> {
val (name, value) = current.split('=', limit = 2)
trimmed.contains('=') -> {
val (name, value) = trimmed.split('=', limit = 2)
name to value
}
else -> {
val next = args.getOrNull(i + 1)
if (next != null && !next.startsWith('-')) {
i++
current to next
if (next?.startsWith('-') == false) {
consume()
trimmed to next
} else {
current to null
trimmed to null
}
}
}
@@ -90,12 +121,12 @@ internal object Parser {
for (name in names) {
val option = command.options.firstOrNull { name in it.names }
?: throw UnknownOption(name)
?: return failure(command, UnknownOption(name))
val value = when {
text != null -> option.parser.parse(text)
option.flag -> option.fallback!!
else -> throw MissingOptionValue(option)
else -> return failure(command, MissingOptionValue(option))
}
opt += Opt(name, value)
}
@@ -104,40 +135,36 @@ internal object Parser {
// malformed option
else -> {
when {
args[i].contains('=') -> {
val (option) = args[i].split('=', limit = 2)
throw MalformedOption(option)
current.contains('=') -> {
val (option) = current.split('=', limit = 2)
return failure(command, MalformedOption(option))
}
else -> throw MalformedOption(args[i])
else -> return failure(command, MalformedOption(current))
}
}
}
i++
consume()
}
validateArguments(command, arg)
validateOptions(command, opt)
return Context(command, cmd, opt, arg)
}
private fun validateArguments(command: Command, arg: List<Arg>) {
// validate arguments
val required = command.arguments.filter { it.required }
var consumed = 0
for (argument in required) {
val needed = if (argument === required.last()) argument.min else argument.count
val delta = arg.size - consumed
if (delta < needed) throw InvalidArgumentCount(argument, delta)
if (delta < needed) return failure(command, InvalidArgumentCount(argument, delta))
consumed += needed
}
}
private fun validateOptions(command: Command, opt: List<Opt>) {
// validate options
for (option in command.options) {
val count = opt.count { it.name in option.names }
if (count !in option.min..option.count) throw InvalidOptionCount(option, count)
if (count !in option.min..option.count) return failure(command, InvalidOptionCount(option, count))
}
val context = Context(command, cmd, arg, opt)
return success(context)
}
}

101
src/commonMain/kotlin/com/infendro/cli/command/help/DefaultHelpRenderer.kt Normal file
View File

@@ -0,0 +1,101 @@
package com.infendro.cli.command.help
import com.infendro.cli.command.Argument
import com.infendro.cli.command.Command
import com.infendro.cli.command.Option
object DefaultHelpRenderer : HelpRenderer {
override fun render(command: Command) = buildString {
usage(command)
if (command.commands.isNotEmpty()) {
appendLine()
commands(command.commands)
}
if (command.arguments.isNotEmpty()) {
appendLine()
arguments(command.arguments)
}
if (command.options.isNotEmpty()) {
appendLine()
options(command.options)
}
}
private fun StringBuilder.usage(command: Command) {
append("Usage:")
for (command in command.path) {
append(" ")
when {
command.fallback -> append("<${command.name}>")
else -> append(command.name)
}
}
for (argument in command.arguments) {
append(" ")
when {
argument.min == 1 && argument.max == 1 -> append("<${argument.name}>")
argument.min == 0 && argument.max == 1 -> append("[<${argument.name}>]")
else -> {
val range = when {
argument.unbounded -> "{${argument.min},}"
argument.min == argument.max -> "{${argument.min}}"
else -> "{${argument.min},${argument.max}}"
}
append("<${argument.name}>$range")
}
}
}
for (option in command.options) {
append(" ")
val text = buildString {
val names = option.names.joinToString("|") { it.withPrefix() }
append(names)
append(" ")
when {
option.flag -> append("[<value>]")
else -> append("<value>")
}
}
when {
option.min == 1 && option.max == 1 -> append("($text)")
option.min == 0 && option.max == 1 -> append("[$text]")
else -> {
val range = when {
option.unbounded -> "{${option.min},}"
option.min == option.max -> "{${option.min}}"
else -> "{${option.min},${option.max}}"
}
append("($text)$range")
}
}
}
appendLine()
}
private fun StringBuilder.commands(commands: List<Command>) {
appendLine("Commands:")
for (command in commands) {
appendLine(" * ${command.name}")
}
}
private fun StringBuilder.arguments(arguments: List<Argument<*>>) {
appendLine("Arguments:")
for (argument in arguments) {
appendLine(" * ${argument.name}")
}
}
private fun StringBuilder.options(options: List<Option<*>>) {
appendLine("Options:")
for (option in options) {
val name = option.names.joinToString(" | ") { it.withPrefix() }
appendLine(" * $name")
}
}
private fun String.withPrefix() = when {
length == 1 -> "-$this"
else -> "--$this"
}
}

7
src/commonMain/kotlin/com/infendro/cli/command/help/HelpRenderer.kt Normal file
View File

@@ -0,0 +1,7 @@
package com.infendro.cli.command.help
import com.infendro.cli.command.Command
interface HelpRenderer {
fun render(command: Command): String?
}

7
src/commonMain/kotlin/com/infendro/cli/command/help/NoopHelpRenderer.kt Normal file
View File

@@ -0,0 +1,7 @@
package com.infendro.cli.command.help
import com.infendro.cli.command.Command
object NoopHelpRenderer : HelpRenderer {
override fun render(command: Command) = null
}