Compare commits

..

3 Commits

Author SHA1 Message Date
5d363e0f43 bump version to 1.3.1
All checks were successful
/ publish (push) Successful in 3m50s
update README to match changes
2025-12-28 00:33:49 +01:00
f1185886d4 improve argument parsing
fail fast by parsing arguments before command execution instead of on demand
2025-12-28 00:16:50 +01:00
79629ae68d refactor argument system
- arguments can have multiple names simultaneously
- argument values can be passed using spaces (e.g., --arg value)
- single-character arguments can be passed using a single dash (e.g., --a -> -a)
- multiple single-character arguments can be combined (e.g., -a -b -> -ab)
- simplify custom arguments using generic classes
2025-12-27 17:30:05 +01:00
19 changed files with 261 additions and 416 deletions

View File

@@ -21,17 +21,13 @@ repositories {
}
dependencies {
implementation("com.infendro:cli:1.3.0")
implementation("com.infendro:cli:1.3.1")
}
```
## Usage
```kotlin
import com.infendro.cli.argument.stringOrElse
import com.infendro.cli.argument.stringOrNull
import com.infendro.cli.command.cli
fun main(args: Array<String>) {
// declare root command
cli {
@@ -42,8 +38,8 @@ fun main(args: Array<String>) {
// declare command "test"
command("test") {
// declare arguments
val greetingArg = stringOrElse("greeting", "Hello")
val nameArg = stringOrNull("name")
val greetingArg = stringOrElse("greeting", "greet", "g", other = "Hello")
val nameArg = stringOrNull("name", "n")
execute {
// retrieve the arguments

View File

@@ -2,7 +2,7 @@ import com.infendro.plugin.infendro
import com.infendro.plugin.token
group = "com.infendro"
version = "1.3.0"
version = "1.3.1"
plugins {
alias(libs.plugins.infendro)

View File

@@ -1,51 +1,44 @@
package com.infendro.cli.argument
sealed class Argument<T> {
abstract val name: String
abstract val min: Int
abstract val max: Int
import com.infendro.cli.exception.build.NoArgumentNameException
abstract class Single<T> : Argument<T>() {
final override val min: Int
get() = 1
final override val max: Int
get() = 1
sealed class Argument<T>(
val names: List<String>,
val parser: Parser<T>,
) {
abstract val required: Boolean
abstract val parser: Parser<T>
}
val name: String
get() = names[0]
abstract class SingleOrElse<T> : Argument<T>() {
abstract val other: T
final override val min: Int
get() = 0
final override val max: Int
get() = 1
abstract val parser: Parser<T>
}
abstract class SingleOrNull<T> : Argument<T>() {
final override val min: Int
get() = 0
final override val max: Int
get() = 1
abstract val parser: Parser<T>
}
abstract class Multiple<T> : Argument<List<T>>() {
override val min: Int
get() = 0
override val max: Int
get() = Int.MAX_VALUE
abstract val parser: Parser<T>
init {
if (names.isEmpty())
throw NoArgumentNameException()
}
interface Parser<T> {
fun parse(
text: String?,
): T
fun parse(text: String?): T
}
class Single<T>(
names: List<String>,
parser: Parser<T>,
) : Argument<T>(names, parser) {
override val required: Boolean = true
}
class SingleOrElse<T>(
names: List<String>,
parser: Parser<T>,
val other: T,
) : Argument<T>(names, parser) {
override val required: Boolean = false
}
class SingleOrNull<T>(
names: List<String>,
parser: Parser<T>,
) : Argument<T>(names, parser) {
override val required: Boolean = false
}
}

View File

@@ -1,84 +1,30 @@
package com.infendro.cli.argument
import com.infendro.cli.command.Command
import com.infendro.cli.exception.run.ParseException
private object BooleanParser : Argument.Parser<Boolean> {
override fun parse(
text: String?,
): Boolean {
return text == null || text.toBooleanStrict()
object BooleanParser : Argument.Parser<Boolean> {
override fun parse(text: String?): Boolean = try {
text?.toBooleanStrict() ?: true
} catch (_: IllegalArgumentException) {
throw ParseException(text, "Boolean")
}
}
class BooleanArgument(
override val name: String,
) : Argument.Single<Boolean>() {
override val parser: Parser<Boolean>
get() = BooleanParser
}
fun boolean(vararg names: String) =
Argument.Single(names.asList(), BooleanParser)
fun boolean(
name: String,
) = BooleanArgument(name)
fun booleanOrElse(vararg names: String, other: Boolean) =
Argument.SingleOrElse(names.asList(), BooleanParser, other)
fun Command.Builder.boolean(
name: String,
) = BooleanArgument(name)
.also { argument(it) }
fun booleanOrNull(vararg names: String) =
Argument.SingleOrNull(names.asList(), BooleanParser)
class BooleanOrElseArgument(
override val name: String,
override val other: Boolean,
) : Argument.SingleOrElse<Boolean>() {
override val parser: Parser<Boolean>
get() = BooleanParser
}
fun Command.Builder.boolean(vararg names: String) =
Argument.Single(names.asList(), BooleanParser).also { argument(it) }
fun booleanOrElse(
name: String,
other: Boolean,
) = BooleanOrElseArgument(name, other)
fun Command.Builder.booleanOrElse(vararg names: String, other: Boolean) =
Argument.SingleOrElse(names.asList(), BooleanParser, other).also { argument(it) }
fun Command.Builder.booleanOrElse(
name: String,
other: Boolean,
) = BooleanOrElseArgument(name, other)
.also { argument(it) }
class BooleanOrNullArgument(
override val name: String,
) : Argument.SingleOrNull<Boolean>() {
override val parser: Parser<Boolean>
get() = BooleanParser
}
fun booleanOrNull(
name: String,
) = BooleanOrNullArgument(name)
fun Command.Builder.booleanOrNull(
name: String,
) = BooleanOrNullArgument(name)
.also { argument(it) }
class BooleansArgument(
override val name: String,
override val min: Int = 0,
override val max: Int = Int.MAX_VALUE,
) : Argument.Multiple<Boolean>() {
override val parser: Parser<Boolean>
get() = BooleanParser
}
fun booleans(
name: String,
min: Int = 0,
max: Int = Int.MAX_VALUE,
) = BooleansArgument(name, min, max)
fun Command.Builder.booleans(
name: String,
min: Int = 0,
max: Int = Int.MAX_VALUE,
) = BooleansArgument(name, min, max)
.also { argument(it) }
fun Command.Builder.booleanOrNull(vararg names: String) =
Argument.SingleOrNull(names.asList(), BooleanParser).also { argument(it) }

View File

@@ -1,84 +1,33 @@
package com.infendro.cli.argument
import com.infendro.cli.command.Command
import com.infendro.cli.exception.run.ParseException
private object IntParser : Argument.Parser<Int> {
override fun parse(
text: String?,
): Int {
return text!!.toInt()
object IntParser : Argument.Parser<Int> {
override fun parse(text: String?): Int = try {
text!!.toInt()
} catch (e: Exception) {
when (e) {
is NullPointerException, is IllegalArgumentException -> throw ParseException(text, "Int")
else -> throw e
}
}
}
class IntArgument(
override val name: String,
) : Argument.Single<Int>() {
override val parser: Parser<Int>
get() = IntParser
}
fun int(vararg names: String) =
Argument.Single(names.asList(), IntParser)
fun int(
name: String,
) = IntArgument(name)
fun intOrElse(vararg names: String, other: Int) =
Argument.SingleOrElse(names.asList(), IntParser, other)
fun Command.Builder.int(
name: String,
) = IntArgument(name)
.also { argument(it) }
fun intOrNull(vararg names: String) =
Argument.SingleOrNull(names.asList(), IntParser)
class IntOrElseArgument(
override val name: String,
override val other: Int,
) : Argument.SingleOrElse<Int>() {
override val parser: Parser<Int>
get() = IntParser
}
fun Command.Builder.int(vararg names: String) =
Argument.Single(names.asList(), IntParser).also { argument(it) }
fun intOrElse(
name: String,
other: Int,
) = IntOrElseArgument(name, other)
fun Command.Builder.intOrElse(vararg names: String, other: Int) =
Argument.SingleOrElse(names.asList(), IntParser, other).also { argument(it) }
fun Command.Builder.intOrElse(
name: String,
other: Int,
) = IntOrElseArgument(name, other)
.also { argument(it) }
class IntOrNullArgument(
override val name: String,
) : Argument.SingleOrNull<Int>() {
override val parser: Parser<Int>
get() = IntParser
}
fun intOrNull(
name: String,
) = IntOrNullArgument(name)
fun Command.Builder.intOrNull(
name: String,
) = IntOrNullArgument(name)
.also { argument(it) }
class IntsArgument(
override val name: String,
override val min: Int = 0,
override val max: Int = Int.MAX_VALUE,
) : Argument.Multiple<Int>() {
override val parser: Parser<Int>
get() = IntParser
}
fun ints(
name: String,
min: Int = 0,
max: Int = Int.MAX_VALUE,
) = IntsArgument(name, min, max)
fun Command.Builder.ints(
name: String,
min: Int = 0,
max: Int = Int.MAX_VALUE,
) = IntsArgument(name, min, max)
.also { argument(it) }
fun Command.Builder.intOrNull(vararg names: String) =
Argument.SingleOrNull(names.asList(), IntParser).also { argument(it) }

View File

@@ -1,84 +1,27 @@
package com.infendro.cli.argument
import com.infendro.cli.command.Command
import com.infendro.cli.exception.run.ParseException
private object StringParser : Argument.Parser<String> {
override fun parse(
text: String?,
): String {
return text!!
}
object StringParser : Argument.Parser<String> {
override fun parse(text: String?): String =
text ?: throw ParseException(text, "String")
}
class StringArgument(
override val name: String,
) : Argument.Single<String>() {
override val parser: Parser<String>
get() = StringParser
}
fun string(vararg names: String) =
Argument.Single(names.asList(), StringParser)
fun string(
name: String,
) = StringArgument(name)
fun stringOrElse(vararg names: String, other: String) =
Argument.SingleOrElse(names.asList(), StringParser, other)
fun Command.Builder.string(
name: String,
) = StringArgument(name)
.also { argument(it) }
fun stringOrNull(vararg names: String) =
Argument.SingleOrNull(names.asList(), StringParser)
class StringOrElseArgument(
override val name: String,
override val other: String,
) : Argument.SingleOrElse<String>() {
override val parser: Parser<String>
get() = StringParser
}
fun Command.Builder.string(vararg names: String) =
Argument.Single(names.asList(), StringParser).also { argument(it) }
fun stringOrElse(
name: String,
other: String,
) = StringOrElseArgument(name, other)
fun Command.Builder.stringOrElse(vararg names: String, other: String) =
Argument.SingleOrElse(names.asList(), StringParser, other).also { argument(it) }
fun Command.Builder.stringOrElse(
name: String,
other: String,
) = StringOrElseArgument(name, other)
.also { argument(it) }
class StringOrNullArgument(
override val name: String,
) : Argument.SingleOrNull<String>() {
override val parser: Parser<String>
get() = StringParser
}
fun stringOrNull(
name: String,
) = StringOrNullArgument(name)
fun Command.Builder.stringOrNull(
name: String,
) = StringOrNullArgument(name)
.also { argument(it) }
class StringsArgument(
override val name: String,
override val min: Int = 0,
override val max: Int = Int.MAX_VALUE,
) : Argument.Multiple<String>() {
override val parser: Parser<String>
get() = StringParser
}
fun strings(
name: String,
min: Int = 0,
max: Int = Int.MAX_VALUE,
) = StringsArgument(name, min, max)
fun Command.Builder.strings(
name: String,
min: Int = 0,
max: Int = Int.MAX_VALUE,
) = StringsArgument(name, min, max)
.also { argument(it) }
fun Command.Builder.stringOrNull(vararg names: String) =
Argument.SingleOrNull(names.asList(), StringParser).also { argument(it) }

View File

@@ -1,99 +1,37 @@
package com.infendro.cli.command
import com.infendro.cli.argument.Argument
import com.infendro.cli.exception.CliException
import com.infendro.cli.exception.build.*
import com.infendro.cli.exception.run.ArgumentCountException
import com.infendro.cli.exception.run.InvalidArgumentException
import com.infendro.cli.exception.run.UnknownArgumentException
import com.infendro.cli.exception.run.UnknownCommandException
import com.infendro.cli.util.Regex.ARGUMENT
import com.infendro.cli.util.Regex.ARGUMENT_NAME
import com.infendro.cli.util.Regex.COMMAND_NAME
class Command private constructor(
private val index: Int,
private val name: String?,
private val commands: List<Command>,
private val arguments: List<Argument<*>>,
val name: String?,
val commands: List<Command>,
val arguments: List<Argument<*>>,
private val block: Execution.() -> Unit,
) {
private val nextIndex: Int
get() = index + 1
fun run(
args: Array<String>,
) {
fun run(args: Array<String>) = try {
val index = args.withIndex()
.find { (_, value) -> value.startsWith("--") }
.firstOrNull { (_, value) -> value.startsWith("-") }
?.index ?: args.size
val cmd = args.slice(0..<index)
val arg = args.slice(index..<args.size)
try {
run(cmd, arg)
} catch (e: UnknownCommandException) {
println("""unknown command "${e.command}"""")
} catch (e: InvalidArgumentException) {
println("""invalid argument "${e.argument}"""")
} catch (e: UnknownArgumentException) {
println("""unknown argument "${e.argument}"""")
} catch (e: ArgumentCountException) {
when {
e.min == e.max -> println("""argument "${e.argument}" must appear ${e.min} times""")
e.max == Int.MAX_VALUE -> println("""argument "${e.argument}" must appear at least ${e.min} times""")
else -> println("""argument "${e.argument}" must appear between ${e.min} and ${e.max} times""")
}
}
}
private fun run(
cmd: List<String>,
arg: List<String>,
) {
if (index == cmd.lastIndex) {
Execution(
parseCmd(cmd),
parseArg(arg),
).block()
} else {
val command = commands.firstOrNull() { it.name == cmd[nextIndex] || it.name == null }
?: throw UnknownCommandException(cmd[nextIndex])
command.run(cmd, arg)
}
}
private fun parseCmd(
cmd: List<String>,
): List<Execution.Cmd> {
return cmd.map { Execution.Cmd(it) }
}
private fun parseArg(
arg: List<String>,
): List<Execution.Arg> {
val result = mutableListOf<Execution.Arg>()
for (argument in arg) {
val match = ARGUMENT.matchEntire(argument)
?: throw InvalidArgumentException(argument)
val name = match.groups["name"]!!.value
val value = match.groups["value"]?.value
if (arguments.none { it.name == name })
throw UnknownArgumentException(name)
result += Execution.Arg(name, value)
var command = this
for (c in cmd) {
command = command.commands.firstOrNull { it.name == c || it.name == null }
?: throw UnknownCommandException(c)
}
arguments.forEach { argument ->
val count = result.count { it.name == argument.name }
if (count !in argument.min..argument.max)
throw ArgumentCountException(argument.name, argument.min, argument.max)
}
return result
val execution = Execution.from(command, cmd, arg)
val execute = command.block
execution.execute()
} catch (e: CliException) {
println(e.message)
}
class Builder internal constructor(
@@ -107,46 +45,37 @@ class Command private constructor(
private val nextIndex: Int
get() = index + 1
fun command(
name: String? = null,
block: Builder.(Key) -> Unit,
) {
if (name != null && !COMMAND_NAME.matches(name))
fun command(name: String? = null, block: Builder.(Key) -> Unit) {
if (name != null && !name.matches(COMMAND_NAME))
throw IllegalCommandNameException(name)
if (commands.any { it.name == name })
throw DuplicateCommandException(name)
val builder = Builder(nextIndex, name)
builder.block(Key(nextIndex))
val key = Key(nextIndex)
builder.block(key)
val command = builder.build()
commands.add(command)
}
fun argument(
argument: Argument<*>,
) {
if (!ARGUMENT_NAME.matches(argument.name))
throw IllegalArgumentNameException(argument.name)
fun argument(argument: Argument<*>) {
for (name in argument.names) {
if (!name.matches(ARGUMENT_NAME))
throw IllegalArgumentNameException(name)
if (arguments.any { it.name == argument.name })
throw DuplicateArgumentException(argument.name)
if (arguments.any { name in it.names })
throw DuplicateArgumentException(name)
}
arguments.add(argument)
}
fun arguments(
vararg arguments: Argument<*>,
) {
for (argument in arguments) {
argument(argument)
}
}
fun arguments(vararg arguments: Argument<*>) =
arguments.forEach(::argument)
fun execute(
block: Execution.() -> Unit,
) {
fun execute(block: Execution.() -> Unit) {
if (this::block.isInitialized)
throw DuplicateExecuteException()
@@ -157,7 +86,7 @@ class Command private constructor(
if (!this::block.isInitialized)
throw NoExecuteException()
return Command(index, name, commands, arguments, block)
return Command(name, commands, arguments, block)
}
}
@@ -166,9 +95,7 @@ class Command private constructor(
)
}
fun cli(
block: Command.Builder.() -> Unit,
): Command {
fun cli(block: Command.Builder.() -> Unit): Command {
val builder = Command.Builder(-1, null)
builder.block()
return builder.build()

View File

@@ -1,47 +1,94 @@
package com.infendro.cli.command
import com.infendro.cli.argument.Argument
import com.infendro.cli.exception.run.DuplicateArgumentException
import com.infendro.cli.exception.run.MalformedArgumentException
import com.infendro.cli.exception.run.MissingArgumentException
import com.infendro.cli.exception.run.UnknownArgumentException
import kotlin.reflect.KProperty
class Execution(
class Execution private constructor(
val commands: List<Cmd>,
val arguments: List<Arg>,
) {
companion object {
fun from(command: Command, cmd: List<String>, arg: List<String>): Execution {
val commands = Cmd.from(cmd)
val arguments = Arg.from(command, arg)
return Execution(commands, arguments)
}
}
class Cmd(
val name: String,
)
) {
companion object {
fun from(cmd: List<String>): List<Cmd> = cmd.map { Cmd(it) }
}
}
class Arg(
val name: String,
val value: String?,
)
val value: Any,
) {
companion object {
fun from(command: Command, arg: List<String>): List<Arg> = buildList {
var i = 0
while (i < arg.size) {
val dashes = arg[i].takeWhile { it == '-' }.count()
val trimmed = arg[i].substring(dashes)
operator fun Command.Key.getValue(
thisRef: Any?,
property: KProperty<*>,
): String = commands[index].name
if (dashes !in 1..2 || trimmed.isEmpty())
throw MalformedArgumentException(arg[i])
operator fun <T> Argument.Single<T>.getValue(
thisRef: Any?,
property: KProperty<*>,
): T = arguments.single { it.name == name }
.let { parser.parse(it.value) }
val (name, value) = when {
trimmed.contains('=') -> {
val (name, value) = trimmed.split('=', limit = 2)
name to value
}
operator fun <T> Argument.SingleOrElse<T>.getValue(
thisRef: Any?,
property: KProperty<*>,
): T = arguments.singleOrNull { it.name == name }
?.let { parser.parse(it.value) } ?: other
else -> {
val next = arg.getOrNull(i + 1)
if (next != null && !next.startsWith('-')) {
i++
trimmed to next
} else {
trimmed to null
}
}
}
operator fun <T> Argument.SingleOrNull<T>.getValue(
thisRef: Any?,
property: KProperty<*>,
): T? = arguments.singleOrNull { it.name == name }
?.let { parser.parse(it.value) }
val names = when {
dashes == 1 -> name.map { "$it" }
else -> listOf(name)
}
operator fun <T> Argument.Multiple<T>.getValue(
thisRef: Any?,
property: KProperty<*>,
): List<T> = arguments.filter { it.name == name }
.map { parser.parse(it.value) }
for (name in names) {
val argument = command.arguments.firstOrNull { name in it.names }
?: throw UnknownArgumentException(name)
val value = argument.parser.parse(value) as Any
add(Arg(name, value))
}
i++
}
for (argument in command.arguments) {
val count = count { it.name in argument.names }
when {
argument.required && count == 0 -> throw MissingArgumentException(argument.name)
count > 1 -> throw DuplicateArgumentException(argument.name)
}
}
}
}
}
operator fun Command.Key.getValue(thisRef: Any?, property: KProperty<*>): String = commands[index].name
@Suppress("UNCHECKED_CAST")
private fun <T> Argument<T>.getValue(): T? = arguments.firstOrNull { it.name in names }?.value as? T
operator fun <T> Argument.Single<T>.getValue(thisRef: Any?, property: KProperty<*>): T = getValue()!!
operator fun <T> Argument.SingleOrElse<T>.getValue(thisRef: Any?, property: KProperty<*>): T = getValue() ?: other
operator fun <T> Argument.SingleOrNull<T>.getValue(thisRef: Any?, property: KProperty<*>): T? = getValue()
}

View File

@@ -0,0 +1,3 @@
package com.infendro.cli.exception
abstract class CliException : Exception()

View File

@@ -0,0 +1,3 @@
package com.infendro.cli.exception.build
class NoArgumentNameException : Exception()

View File

@@ -1,7 +0,0 @@
package com.infendro.cli.exception.run
class ArgumentCountException(
val argument: String,
val min: Int,
val max: Int,
) : Exception()

View File

@@ -0,0 +1,10 @@
package com.infendro.cli.exception.run
import com.infendro.cli.exception.CliException
class DuplicateArgumentException(
val argument: String,
) : CliException() {
override val message: String
get() = """duplicate argument "$argument""""
}

View File

@@ -1,5 +0,0 @@
package com.infendro.cli.exception.run
class InvalidArgumentException(
val argument: String,
) : Exception()

View File

@@ -0,0 +1,10 @@
package com.infendro.cli.exception.run
import com.infendro.cli.exception.CliException
class MalformedArgumentException(
val argument: String,
) : CliException() {
override val message: String
get() = """malformed argument "$argument""""
}

View File

@@ -0,0 +1,10 @@
package com.infendro.cli.exception.run
import com.infendro.cli.exception.CliException
class MissingArgumentException(
val argument: String,
) : CliException() {
override val message: String
get() = """missing argument "$argument""""
}

View File

@@ -0,0 +1,11 @@
package com.infendro.cli.exception.run
import com.infendro.cli.exception.CliException
class ParseException(
val text: String?,
val type: String,
) : CliException() {
override val message: String
get() = """"$text" cannot be converted to $type"""
}

View File

@@ -1,5 +1,10 @@
package com.infendro.cli.exception.run
import com.infendro.cli.exception.CliException
class UnknownArgumentException(
val argument: String,
) : Exception()
) : CliException() {
override val message: String
get() = """unknown argument "$argument""""
}

View File

@@ -1,5 +1,10 @@
package com.infendro.cli.exception.run
import com.infendro.cli.exception.CliException
class UnknownCommandException(
val command: String,
) : Exception()
) : CliException() {
override val message: String
get() = """unknown command "$command""""
}

View File

@@ -1,7 +1,6 @@
package com.infendro.cli.util
internal object Regex {
val COMMAND_NAME = """[a-z]+(?:-[a-z]+)*""".toRegex()
val ARGUMENT_NAME = """[a-z]+(?:[\-.][a-z]+)*""".toRegex()
val ARGUMENT = """--(?<name>[a-z]+(?:[\-.][a-z]+)*)(?:=(?<value>.*))?""".toRegex()
val COMMAND_NAME = Regex("""[a-z]+(?:-[a-z]+)*""")
val ARGUMENT_NAME = Regex("""[a-z]+(?:[\-.][a-z]+)*""")
}