Update README.md

display type for fallback commands
display type and range for arguments/options

.gitea/workflows/main.yaml

@@ -1,36 +0,0 @@
-on:
-  push:
-    branches:
-      - main
-
-env:
-  INFENDRO__TOKEN: ${{ secrets.TOKEN }}
-
-jobs:
-  publish:
-    runs-on: linux
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/cache/restore@v4
-        with:
-          key: gradle
-          path: |
-            ~/.gradle/caches/
-            ~/.gradle/wrapper/
-            ~/.konan/
-
-      - uses: actions/setup-java@v4
-        with:
-          java-version: '24'
-          distribution: 'temurin'
-
-      - run: ./gradlew publish
-
-      - uses: actions/cache/save@v4
-        with:
-          key: gradle
-          path: |
-            ~/.gradle/caches/
-            ~/.gradle/wrapper/
-            ~/.konan/

.gitea/workflows/publish.yaml

@@ -0,0 +1,47 @@
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  publish:
+    runs-on: linux
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '24'
+          distribution: 'temurin'
+
+      - name: Cache Gradle
+        uses: actions/cache@v4
+        with:
+          key: gradle-${{ hashFiles('**/libs.versions.toml') }}
+          restore-keys: gradle
+          path: |
+            ~/.gradle/caches/
+            ~/.gradle/wrapper/
+
+      - name: Cache Konan
+        uses: actions/cache@v4
+        with:
+          key: konan-${{ hashFiles('**/libs.versions.toml') }}
+          restore-keys: konan
+          path: |
+            ~/.konan/
+
+      - name: Cache Node
+        uses: actions/cache@v4
+        with:
+          key: node-${{ hashFiles('**/libs.versions.toml') }}
+          restore-keys: node
+          path: |
+            ~/.gradle/nodejs
+            ~/.gradle/yarn
+
+      - name: Publish
+        run: ./gradlew publish
+        env:
+          INFENDRO__TOKEN: ${{ secrets.TOKEN }}

README.md

@@ -1,15 +1,6 @@
-# cli-kt
+# cli.kt
 
-`cli-kt` is a Kotlin Multiplatform framework for implementing terminal applications.
-
-## Targets
-
-| Target           | Status        |
-|------------------|---------------|
-| JVM              | Supported     |
-| JavaScript       | Supported     |
-| Native (Linux)   | Supported     |
-| Native (Windows) | Not Supported |
+`cli.kt` is a Kotlin Multiplatform framework for implementing terminal applications.
 
 ## Installation
 
@@ -21,46 +12,48 @@ repositories {
 }
 
 dependencies {
-    implementation("com.infendro:cli:1.3.1")
+    implementation("com.infendro:cli:1.4.1")
 }
 ```
 
 ## Usage
 
 ```kotlin
-fun main(args: Array<String>) {
-    // declare root command
-    cli {
+fun main(args: Array<String>) = command("application", description = "example application") {
+    execute {
+        // define execution of command (e.g., display help)
+        help()
+    }
+
+    // register command "greet"
+    +command("greet", description = "greet someone") {
+        // declare and register arguments
+        val speakersArg = +argument.string("speakers", description = "the greeters").variable(min = 1)
+
+        // declare and register options
+        val greetingOpt = +option.string("greeting", "greet", "g", description = "the greeting").orElse("Hello")
+        val nameOpt = +option.string("name", "n", description = "the greetee").orNull()
+
         execute {
-            // execution of root command (e.g., display help)
+            // retrieve the arguments and options
+            val speakers by speakersArg
+            val greeting by greetingOpt
+            val name by nameOpt
+
+            println("${speakers.joinToString()}: $greeting ${name ?: "World"}!")
         }
 
-        // declare command "test"
-        command("test") {
-            // declare arguments
-            val greetingArg = stringOrElse("greeting", "greet", "g", other = "Hello")
-            val nameArg = stringOrNull("name", "n")
+        // register more commands...
+    }
 
-            execute {
-                // retrieve the arguments
-                val greeting by greetingArg
-                val name by nameArg
+    // register fallback command "value"
+    +command.fallback.string("value", description = "execute an arbitrary command") { valueArg ->
+        execute {
+            // retrieve the value used for the fallback command
+            val value by valueArg
 
-                println("$greeting ${name ?: "World"}!")
-            }
-
-            // declare more commands...
+            println("""command "$value" executed!""")
         }
-
-        // declare wildcard command
-        command { wildcard ->
-            execute {
-                // retrieve the value used for the wildcard command
-                val value by wildcard
-
-                println("command $value executed!")
-            }
-        }
-    }.run(args)
-}
+    }
+}.run(*args)
 ```

build.gradle.kts

@@ -1,8 +1,11 @@
+@file:OptIn(ExperimentalWasmDsl::class)
+
 import com.infendro.plugin.infendro
 import com.infendro.plugin.token
+import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
 
 group = "com.infendro"
-version = "1.3.1"
+version = "1.4.1"
 
 plugins {
     alias(libs.plugins.infendro)
@@ -12,10 +15,14 @@ plugins {
 
 kotlin {
     jvm()
-    js {
-        nodejs()
-    }
     linuxX64()
+    linuxArm64()
+    mingwX64()
+    macosX64()
+    macosArm64()
+    js { nodejs() }
+    wasmJs { nodejs() }
+    wasmWasi { nodejs() }
 
     repositories {
         mavenCentral()

gradle/libs.versions.toml

@@ -1,6 +1,6 @@
 [versions]
-infendro = "1.0.0"
-kotlin = "2.2.21"
+infendro = "1.1.0"
+kotlin = "2.3.0"
 
 [plugins]
 infendro = { id = "com.infendro.plugin", version.ref = "infendro" }

src/commonMain/kotlin/com/infendro/cli/Dsl.kt

@@ -0,0 +1,4 @@
+package com.infendro.cli
+
+@DslMarker
+internal annotation class Dsl

src/commonMain/kotlin/com/infendro/cli/argument/Argument.kt

@@ -1,44 +1,70 @@
 package com.infendro.cli.argument
 
-import com.infendro.cli.exception.build.NoArgumentNameException
+import com.infendro.cli.exception.InvalidArgumentName
+import com.infendro.cli.exception.InvalidRange
+import com.infendro.cli.parser.Parser
+import com.infendro.cli.util.Regex.ARGUMENT
 
-sealed class Argument<T>(
-    val names: List<String>,
+sealed class Argument<T : Any>(
     val parser: Parser<T>,
+    val name: String,
+    val description: String?,
+    val min: Int,
+    val max: Int?,
 ) {
-    abstract val required: Boolean
-
-    val name: String
-        get() = names[0]
-
     init {
-        if (names.isEmpty())
-            throw NoArgumentNameException()
+        when {
+            !name.matches(ARGUMENT) -> throw InvalidArgumentName(name)
+            min !in 0..count || max == 0 -> throw InvalidRange()
+        }
     }
 
-    interface Parser<T> {
-        fun parse(text: String?): T
-    }
+    val required: Boolean
+        get() = min > 0
+    val optional: Boolean
+        get() = !required
 
-    class Single<T>(
-        names: List<String>,
+    val bounded: Boolean
+        get() = max != null
+    val unbounded: Boolean
+        get() = !bounded
+
+    val count: Int
+        get() = max ?: Int.MAX_VALUE
+
+    class Required<T : Any>(
         parser: Parser<T>,
-    ) : Argument<T>(names, parser) {
-        override val required: Boolean = true
+        name: String,
+        description: String?,
+    ) : Argument<T>(parser, name, description, min = 1, max = 1) {
+        fun orElse(other: T) =
+            OrElse(parser, name, description, other)
+
+        fun orNull() =
+            OrNull(parser, name, description)
+
+        fun variable(min: Int = 0, max: Int? = null) =
+            Variable(parser, name, description, min, max)
     }
 
-    class SingleOrElse<T>(
-        names: List<String>,
+    class OrElse<T : Any>(
         parser: Parser<T>,
+        name: String,
+        description: String?,
         val other: T,
-    ) : Argument<T>(names, parser) {
-        override val required: Boolean = false
-    }
+    ) : Argument<T>(parser, name, description, min = 0, max = 1)
 
-    class SingleOrNull<T>(
-        names: List<String>,
+    class OrNull<T : Any>(
         parser: Parser<T>,
-    ) : Argument<T>(names, parser) {
-        override val required: Boolean = false
-    }
+        name: String,
+        description: String?,
+    ) : Argument<T>(parser, name, description, min = 0, max = 1)
+
+    class Variable<T : Any>(
+        parser: Parser<T>,
+        name: String,
+        description: String?,
+        min: Int,
+        max: Int?,
+    ) : Argument<T>(parser, name, description, min, max)
 }

src/commonMain/kotlin/com/infendro/cli/argument/ArgumentFactory.kt

@@ -0,0 +1,31 @@
+package com.infendro.cli.argument
+
+import com.infendro.cli.parser.*
+
+object ArgumentFactory {
+    fun string(name: String, description: String? = null) =
+        argument(StringParser, name, description)
+
+    fun int(name: String, description: String? = null) =
+        argument(IntParser, name, description)
+
+    fun long(name: String, description: String? = null) =
+        argument(LongParser, name, description)
+
+    fun float(name: String, description: String? = null) =
+        argument(FloatParser, name, description)
+
+    fun double(name: String, description: String? = null) =
+        argument(DoubleParser, name, description)
+
+    fun boolean(name: String, description: String? = null) =
+        argument(BooleanParser, name, description)
+
+    inline fun <reified T : Enum<T>> enum(name: String, description: String? = null) =
+        argument(enumParser<T>(), name, description)
+}
+
+val argument = ArgumentFactory
+
+fun <T : Any> argument(parser: Parser<T>, name: String, description: String? = null) =
+    Argument.Required(parser, name, description)

src/commonMain/kotlin/com/infendro/cli/argument/Boolean.kt

@@ -1,30 +0,0 @@
-package com.infendro.cli.argument
-
-import com.infendro.cli.command.Command
-import com.infendro.cli.exception.run.ParseException
-
-object BooleanParser : Argument.Parser<Boolean> {
-    override fun parse(text: String?): Boolean = try {
-        text?.toBooleanStrict() ?: true
-    } catch (_: IllegalArgumentException) {
-        throw ParseException(text, "Boolean")
-    }
-}
-
-fun boolean(vararg names: String) =
-    Argument.Single(names.asList(), BooleanParser)
-
-fun booleanOrElse(vararg names: String, other: Boolean) =
-    Argument.SingleOrElse(names.asList(), BooleanParser, other)
-
-fun booleanOrNull(vararg names: String) =
-    Argument.SingleOrNull(names.asList(), BooleanParser)
-
-fun Command.Builder.boolean(vararg names: String) =
-    Argument.Single(names.asList(), BooleanParser).also { argument(it) }
-
-fun Command.Builder.booleanOrElse(vararg names: String, other: Boolean) =
-    Argument.SingleOrElse(names.asList(), BooleanParser, other).also { argument(it) }
-
-fun Command.Builder.booleanOrNull(vararg names: String) =
-    Argument.SingleOrNull(names.asList(), BooleanParser).also { argument(it) }

src/commonMain/kotlin/com/infendro/cli/argument/Int.kt

@@ -1,33 +0,0 @@
-package com.infendro.cli.argument
-
-import com.infendro.cli.command.Command
-import com.infendro.cli.exception.run.ParseException
-
-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
-        }
-    }
-}
-
-fun int(vararg names: String) =
-    Argument.Single(names.asList(), IntParser)
-
-fun intOrElse(vararg names: String, other: Int) =
-    Argument.SingleOrElse(names.asList(), IntParser, other)
-
-fun intOrNull(vararg names: String) =
-    Argument.SingleOrNull(names.asList(), IntParser)
-
-fun Command.Builder.int(vararg names: String) =
-    Argument.Single(names.asList(), IntParser).also { argument(it) }
-
-fun Command.Builder.intOrElse(vararg names: String, other: Int) =
-    Argument.SingleOrElse(names.asList(), IntParser, other).also { argument(it) }
-
-fun Command.Builder.intOrNull(vararg names: String) =
-    Argument.SingleOrNull(names.asList(), IntParser).also { argument(it) }

src/commonMain/kotlin/com/infendro/cli/argument/String.kt

@@ -1,27 +0,0 @@
-package com.infendro.cli.argument
-
-import com.infendro.cli.command.Command
-import com.infendro.cli.exception.run.ParseException
-
-object StringParser : Argument.Parser<String> {
-    override fun parse(text: String?): String =
-        text ?: throw ParseException(text, "String")
-}
-
-fun string(vararg names: String) =
-    Argument.Single(names.asList(), StringParser)
-
-fun stringOrElse(vararg names: String, other: String) =
-    Argument.SingleOrElse(names.asList(), StringParser, other)
-
-fun stringOrNull(vararg names: String) =
-    Argument.SingleOrNull(names.asList(), StringParser)
-
-fun Command.Builder.string(vararg names: String) =
-    Argument.Single(names.asList(), StringParser).also { argument(it) }
-
-fun Command.Builder.stringOrElse(vararg names: String, other: String) =
-    Argument.SingleOrElse(names.asList(), StringParser, other).also { argument(it) }
-
-fun Command.Builder.stringOrNull(vararg names: String) =
-    Argument.SingleOrNull(names.asList(), StringParser).also { argument(it) }

src/commonMain/kotlin/com/infendro/cli/command/Command.kt

@@ -1,102 +1,184 @@
 package com.infendro.cli.command
 
+import com.infendro.cli.Dsl
 import com.infendro.cli.argument.Argument
-import com.infendro.cli.exception.CliException
-import com.infendro.cli.exception.build.*
-import com.infendro.cli.exception.run.UnknownCommandException
-import com.infendro.cli.util.Regex.ARGUMENT_NAME
-import com.infendro.cli.util.Regex.COMMAND_NAME
+import com.infendro.cli.command.context.Context
+import com.infendro.cli.command.context.ContextParser
+import com.infendro.cli.command.help.DefaultHelpRenderer
+import com.infendro.cli.command.help.HelpRenderer
+import com.infendro.cli.exception.*
+import com.infendro.cli.option.Option
+import com.infendro.cli.parser.Parser
+import com.infendro.cli.util.Regex
 
-class Command private constructor(
-    val name: String?,
+sealed class Command private constructor(
+    val name: String,
+    val description: String?,
     val commands: List<Command>,
     val arguments: List<Argument<*>>,
-    private val block: Execution.() -> Unit,
+    val options: List<Option<*>>,
+    internal val execute: Context.() -> Unit,
+    internal val renderer: HelpRenderer,
 ) {
-    fun run(args: Array<String>) = try {
-        val index = args.withIndex()
-            .firstOrNull { (_, value) -> value.startsWith("-") }
-            ?.index ?: args.size
-
-        val cmd = args.slice(0..<index)
-        val arg = args.slice(index..<args.size)
-
-        var command = this
-        for (c in cmd) {
-            command = command.commands.firstOrNull { it.name == c || it.name == null }
-                ?: throw UnknownCommandException(c)
-        }
-
-        val execution = Execution.from(command, cmd, arg)
-        val execute = command.block
-        execution.execute()
-    } catch (e: CliException) {
-        println(e.message)
+    init {
+        if (!name.matches(Regex.COMMAND)) throw InvalidCommandName(name)
     }
 
-    class Builder internal constructor(
-        private val index: Int,
-        private val name: String?,
-    ) {
-        private val commands = mutableListOf<Command>()
-        private val arguments = mutableListOf<Argument<*>>()
-        private lateinit var block: Execution.() -> Unit
-
-        private val nextIndex: Int
-            get() = index + 1
-
-        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)
-            val key = Key(nextIndex)
-            builder.block(key)
-            val command = builder.build()
-
-            commands.add(command)
-        }
-
-        fun argument(argument: Argument<*>) {
-            for (name in argument.names) {
-                if (!name.matches(ARGUMENT_NAME))
-                    throw IllegalArgumentNameException(name)
-
-                if (arguments.any { name in it.names })
-                    throw DuplicateArgumentException(name)
+    fun run(vararg args: String) {
+        when (val result = ContextParser(this, arrayOf(*args)).parse()) {
+            is ContextParser.Result.Success -> result.context.execute()
+            is ContextParser.Result.Help -> {
+                val command = result.path.last()
+                val help = command.renderer.render(result.path)
+                if (help != null) print(help)
+            }
+            is ContextParser.Result.Failure -> {
+                println("error: ${result.error.message}")
+                val command = result.path.last()
+                val help = command.renderer.render(result.path)
+                if (help != null) print("\n$help")
             }
-
-            arguments.add(argument)
-        }
-
-        fun arguments(vararg arguments: Argument<*>) =
-            arguments.forEach(::argument)
-
-        fun execute(block: Execution.() -> Unit) {
-            if (this::block.isInitialized)
-                throw DuplicateExecuteException()
-
-            this.block = block
-        }
-
-        fun build(): Command {
-            if (!this::block.isInitialized)
-                throw NoExecuteException()
-
-            return Command(name, commands, arguments, block)
         }
     }
 
-    class Key internal constructor(
-        internal val index: Int,
-    )
-}
+    class Named(
+        name: String,
+        description: String?,
+        commands: List<Command>,
+        arguments: List<Argument<*>>,
+        options: List<Option<*>>,
+        execute: Context.() -> Unit,
+        renderer: HelpRenderer,
+    ) : Command(name, description, commands, arguments, options, execute, renderer) {
+        class Builder(
+            name: String,
+            description: String?,
+        ) : Command.Builder<Named>(name, description) {
+            override fun create() =
+                Named(name, description, commands, arguments, options, execute, renderer)
+        }
+    }
 
-fun cli(block: Command.Builder.() -> Unit): Command {
-    val builder = Command.Builder(-1, null)
-    builder.block()
-    return builder.build()
+    class Fallback<T : Any>(
+        val key: Key<T>,
+        val parser: Parser<T>,
+        name: String,
+        description: String?,
+        commands: List<Command>,
+        arguments: List<Argument<*>>,
+        options: List<Option<*>>,
+        execute: Context.() -> Unit,
+        renderer: HelpRenderer,
+    ) : Command(name, description, commands, arguments, options, execute, renderer) {
+        class Builder<T : Any>(
+            val parser: Parser<T>,
+            name: String,
+            description: String?,
+        ) : Command.Builder<Fallback<T>>(name, description) {
+            internal val key = Key<T>()
+
+            override fun create() =
+                Fallback(key, parser, name, description, commands, arguments, options, execute, renderer)
+        }
+
+        class Key<T>
+    }
+
+    @Dsl
+    sealed class Builder<COMMAND : Command>(
+        protected val name: String,
+        protected val description: String?,
+    ) {
+        protected val commands = mutableListOf<Command>()
+        protected val arguments = mutableListOf<Argument<*>>()
+        protected val options = mutableListOf<Option<*>>()
+        private var _execute: (Context.() -> Unit)? = null
+        private var _renderer: HelpRenderer? = null
+
+        protected val execute: Context.() -> Unit
+            get() = _execute!!
+        protected val renderer: HelpRenderer
+            get() = _renderer!!
+
+        fun register(command: Command) {
+            validateCommand(command)
+            commands += command
+        }
+
+        fun register(vararg commands: Command) = commands.forEach(::register)
+        operator fun <T : Command> T.unaryPlus() = also(::register)
+
+        fun register(argument: Argument<*>) {
+            validateArgument(argument)
+            arguments += argument
+        }
+
+        fun register(vararg arguments: Argument<*>) = arguments.forEach(::register)
+        operator fun <T : Argument<*>> T.unaryPlus() = also(::register)
+
+        fun register(option: Option<*>) {
+            validateOption(option)
+            options += option
+        }
+
+        fun register(vararg options: Option<*>) = options.forEach(::register)
+        operator fun <T : Option<*>> T.unaryPlus() = also(::register)
+
+        fun execute(block: Context.() -> Unit) {
+            validateExecute()
+            _execute = block
+        }
+
+        fun renderer(renderer: HelpRenderer) {
+            validateRenderer()
+            _renderer = renderer
+        }
+
+        internal abstract fun create(): COMMAND
+
+        internal fun build(): Command {
+            if (_execute == null) _execute = {}
+            if (_renderer == null) _renderer = DefaultHelpRenderer
+
+            validate()
+            return create()
+        }
+
+        private fun validateCommand(command: Command) {
+            if (commands.isNotEmpty()) {
+                val last = commands.last()
+                if (last is Fallback<*>) throw InvalidCommandOrder()
+            }
+            if (commands.any { it.name == command.name }) throw DuplicateCommand(command)
+        }
+
+        private fun validateArgument(argument: Argument<*>) {
+            if (arguments.isNotEmpty()) {
+                val last = arguments.last()
+                when {
+                    last.unbounded -> throw InvalidArgumentOrder()
+                    argument.required && last.optional -> throw InvalidArgumentOrder()
+                }
+            }
+            if (arguments.any { it.name == argument.name }) throw DuplicateArgument(argument)
+        }
+
+        private fun validateOption(option: Option<*>) {
+            for (name in option.names) {
+                if (options.any { name in it.names }) throw DuplicateOption(option)
+            }
+        }
+
+        private fun validateExecute() {
+            if (_execute != null) throw DuplicateExecute()
+        }
+
+        private fun validateRenderer() {
+            if (_renderer != null) throw DuplicateRenderer()
+        }
+
+        private fun validate() {
+            if (commands.any { it is Fallback<*> } && arguments.isNotEmpty()) throw InvalidFallback()
+        }
+    }
 }

src/commonMain/kotlin/com/infendro/cli/command/CommandFactory.kt

@@ -0,0 +1,50 @@
+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, description: String? = null, block: Builder<*>.(Fallback.Key<String>) -> Unit) =
+            fallback(StringParser, name, description, block)
+
+        fun int(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<Int>) -> Unit) =
+            fallback(IntParser, name, description, block)
+
+        fun long(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<Long>) -> Unit) =
+            fallback(LongParser, name, description, block)
+
+        fun float(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<Float>) -> Unit) =
+            fallback(FloatParser, name, description, block)
+
+        fun double(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<Double>) -> Unit) =
+            fallback(DoubleParser, name, description, block)
+
+        fun boolean(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<Boolean>) -> Unit) =
+            fallback(BooleanParser, name, description, block)
+
+        inline fun <reified T : Enum<T>> enum(
+            name: String,
+            description: String,
+            noinline block: Builder<*>.(Fallback.Key<T>) -> Unit,
+        ) =
+            fallback(enumParser<T>(), name, description, block)
+    }
+
+    fun <T : Any> fallback(
+        parser: Parser<T>,
+        name: String,
+        description: String? = null,
+        block: Fallback.Builder<T>.(Fallback.Key<T>) -> Unit,
+    ) = Fallback.Builder(parser, name, description).apply { block(key) }.build()
+
+    val fallback = FallbackFactory()
+}
+
+fun command(
+    name: String,
+    description: String? = null,
+    block: Builder<*>.() -> Unit,
+) = Named.Builder(name, description).apply(block).build()
+
+val command = CommandFactory()

src/commonMain/kotlin/com/infendro/cli/command/Execution.kt

@@ -1,94 +0,0 @@
-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 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: 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)
-
-                    if (dashes !in 1..2 || trimmed.isEmpty())
-                        throw MalformedArgumentException(arg[i])
-
-                    val (name, value) = when {
-                        trimmed.contains('=') -> {
-                            val (name, value) = trimmed.split('=', limit = 2)
-                            name to value
-                        }
-
-                        else -> {
-                            val next = arg.getOrNull(i + 1)
-                            if (next != null && !next.startsWith('-')) {
-                                i++
-                                trimmed to next
-                            } else {
-                                trimmed to null
-                            }
-                        }
-                    }
-
-                    val names = when {
-                        dashes == 1 -> name.map { "$it" }
-                        else -> listOf(name)
-                    }
-
-                    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()
-}

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

@@ -0,0 +1,63 @@
+package com.infendro.cli.command.context
+
+import com.infendro.cli.Dsl
+import com.infendro.cli.command.Command
+import com.infendro.cli.argument.Argument
+import com.infendro.cli.option.Option
+import kotlin.reflect.KProperty
+
+@Dsl
+class Context internal constructor(
+    private val path: List<Command>,
+    private val commands: Map<Command.Fallback.Key<*>, Any>,
+    private val arguments: Map<Argument<*>, List<Any>>,
+    private val options: Map<Option<*>, List<Any>>,
+) {
+    val command: Command
+        get() = path.last()
+
+    internal fun execute() = (command.execute)()
+
+    fun help() {
+        command.renderer.render(path)?.let { print(it) }
+    }
+
+    @Suppress("UNCHECKED_CAST")
+    private val <T : Any> Command.Fallback.Key<T>.value: T
+        get() = commands[this] as T
+
+    operator fun <T : Any> Command.Fallback.Key<T>.getValue(thisRef: Any?, property: KProperty<*>): T =
+        value
+
+    @Suppress("UNCHECKED_CAST")
+    private val <T : Any> Argument<T>.values: List<T>
+        get() = arguments[this] as List<T>
+
+    operator fun <T : Any> Argument.Required<T>.getValue(thisRef: Any?, property: KProperty<*>): T =
+        values.first()
+
+    operator fun <T : Any> Argument.OrElse<T>.getValue(thisRef: Any?, property: KProperty<*>): T =
+        values.firstOrNull() ?: other
+
+    operator fun <T : Any> Argument.OrNull<T>.getValue(thisRef: Any?, property: KProperty<*>): T? =
+        values.firstOrNull()
+
+    operator fun <T : Any> Argument.Variable<T>.getValue(thisRef: Any?, property: KProperty<*>): List<T> =
+        values
+
+    @Suppress("UNCHECKED_CAST")
+    private val <T : Any> Option<T>.values: List<T>
+        get() = options[this] as List<T>
+
+    operator fun <T : Any> Option.Required<T>.getValue(thisRef: Any?, property: KProperty<*>): T =
+        values.first()
+
+    operator fun <T : Any> Option.OrElse<T>.getValue(thisRef: Any?, property: KProperty<*>): T =
+        values.firstOrNull() ?: other
+
+    operator fun <T : Any> Option.OrNull<T>.getValue(thisRef: Any?, property: KProperty<*>): T? =
+        values.firstOrNull()
+
+    operator fun <T : Any> Option.Variable<T>.getValue(thisRef: Any?, property: KProperty<*>): List<T> =
+        values
+}

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

@@ -0,0 +1,183 @@
+package com.infendro.cli.command.context
+
+import com.infendro.cli.command.Command
+import com.infendro.cli.error.*
+import com.infendro.cli.parser.Parser
+
+internal class ContextParser(
+    private val root: Command,
+    private val args: Array<String>,
+) {
+    sealed class Result {
+        data class Success(
+            val context: Context,
+        ) : Result()
+
+        data class Help(
+            val path: List<Command>,
+        ) : Result()
+
+        data class Failure(
+            val path: List<Command>,
+            val error: Error,
+        ) : Result()
+    }
+
+    private fun success(context: Context) = Result.Success(context)
+    private fun help(path: List<Command>) = Result.Help(path)
+    private fun failure(path: List<Command>, error: Error) = Result.Failure(path, error)
+
+    private var index = 0
+    private val current: String
+        get() = args[index]
+    private val next: String?
+        get() = args.getOrNull(index + 1)
+
+    private fun hasNext() = index < args.size
+    private fun consume() {
+        index++
+    }
+
+    fun parse(): Result {
+        // command
+        var command = root
+        val path = mutableListOf(root)
+        val commands = mutableMapOf<Command.Fallback.Key<*>, Any>()
+
+        while (hasNext()) {
+            if (current.startsWith("-"))
+                break
+
+            val cmd = command.commands.firstOrNull {
+                (it is Command.Named && it.name == current) || it is Command.Fallback<*>
+            }
+            if (cmd == null) {
+                when {
+                    command.arguments.isEmpty() -> return failure(path, UnknownCommand(command, current))
+                    else -> break
+                }
+            }
+
+            command = cmd
+            path += cmd
+            if (cmd is Command.Fallback<*>) {
+                val value = when (val result = cmd.parser.parse(current)) {
+                    is Parser.Result.Success<*> -> result.value
+                    is Parser.Result.Failure<*> -> return failure(path, result.error)
+                }
+                commands[cmd.key] = value
+            }
+
+            consume()
+        }
+
+        // arguments and options
+        val arguments = command.arguments.associateWith { mutableListOf<Any>() }
+        val options = command.options.associateWith { mutableListOf<Any>() }
+
+        var endOfOptions = false
+        var argumentIndex = 0
+        var argumentCount = 0
+
+        while (hasNext()) {
+            val dashes = current.takeWhile { it == '-' }.count()
+            val trimmed = current.drop(dashes)
+
+            when {
+                // argument
+                endOfOptions || dashes == 0 -> {
+                    val argument = command.arguments.getOrNull(argumentIndex)
+                        ?: return failure(path, UnexpectedArgument(current))
+
+                    val value = when (val result = argument.parser.parse(current)) {
+                        is Parser.Result.Success<*> -> result.value
+                        is Parser.Result.Failure<*> -> return failure(path, result.error)
+                    }
+                    arguments[argument]!! += value
+                    argumentCount++
+
+                    if (argumentCount == argument.count) {
+                        argumentCount = 0
+                        argumentIndex++
+                    }
+                }
+
+                // option
+                dashes in 1..2 -> {
+                    if (dashes == 2 && trimmed.isEmpty()) {
+                        endOfOptions = true
+                        consume()
+                        continue
+                    }
+
+                    if (dashes == 2 && trimmed == "help")
+                        return help(path)
+
+                    val (name, text) = when {
+                        trimmed.contains('=') -> {
+                            val (name, value) = trimmed.split('=', limit = 2)
+                            name to value
+                        }
+                        else -> {
+                            if (next?.startsWith('-') == false) {
+                                consume()
+                                trimmed to current
+                            } else {
+                                trimmed to null
+                            }
+                        }
+                    }
+
+                    val names = when {
+                        dashes == 1 -> name.map { "$it" }
+                        else -> listOf(name)
+                    }
+
+                    for (name in names) {
+                        val option = command.options.firstOrNull { name in it.names }
+                            ?: return failure(path, UnknownOption(command, name))
+
+                        val value = when {
+                            text != null ->
+                                when (val result = option.parser.parse(text)) {
+                                    is Parser.Result.Success<*> -> result.value
+                                    is Parser.Result.Failure<*> -> return failure(path, result.error)
+                                }
+                            option.flag -> option.fallback!!
+                            else -> return failure(path, MissingOptionValue(option))
+                        }
+                        options[option]!! += value
+                    }
+                }
+
+                // malformed option
+                else -> {
+                    when {
+                        current.contains('=') -> {
+                            val (option) = current.split('=', limit = 2)
+                            return failure(path, MalformedOption(option))
+                        }
+                        else -> return failure(path, MalformedOption(current))
+                    }
+                }
+            }
+
+            consume()
+        }
+
+        // validate arguments
+        for (argument in command.arguments) {
+            val count = arguments[argument]!!.count()
+            if (count !in argument.min..argument.count) return failure(path, InvalidArgumentCount(argument, count))
+        }
+
+        // validate options
+        for (option in command.options) {
+            val count = options[option]!!.count()
+            if (count !in option.min..option.count) return failure(path, InvalidOptionCount(option, count))
+        }
+
+        val context = Context(path, commands, arguments, options)
+        return success(context)
+    }
+}

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

@@ -0,0 +1,189 @@
+package com.infendro.cli.command.help
+
+import com.infendro.cli.command.Command
+import com.infendro.cli.argument.Argument
+import com.infendro.cli.option.Option
+import kotlin.reflect.KClass
+
+object DefaultHelpRenderer : HelpRenderer {
+    override fun render(path: List<Command>) = buildString {
+        val command = path.last()
+
+        usage(path)
+        if (command.description != null) {
+            appendLine()
+            appendLine(command.description)
+        }
+        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(path: List<Command>) {
+        val command = path.last()
+
+        append("Usage:")
+        for (command in path) {
+            append(" ")
+            when {
+                command is 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 = renderRange(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 = renderRange(option.min, option.max)
+                    append("($text)$range")
+                }
+            }
+        }
+        appendLine()
+    }
+
+    private fun StringBuilder.commands(commands: List<Command>) {
+        val rows = commands.map { command ->
+            val name = when {
+                command is Command.Fallback<*> -> "<${command.name}>"
+                else -> command.name
+            }
+            val type = when {
+                command is Command.Fallback<*> -> command.parser.type.name
+                else -> null
+            }
+            val description = command.description
+            CommandRow(name, type, description)
+        }
+        val nameWidth = rows.maxOf { it.name.length }
+
+        appendLine("Commands:")
+        when {
+            rows.any { it.type != null } -> {
+                val typeWidth = rows.maxOf { it.type?.length ?: 0 }
+
+                rows.forEach { row ->
+                    appendLine("  ${row.name.padEnd(nameWidth)}    ${(row.type ?: "").padEnd(typeWidth)}    ${row.description ?: ""}")
+                }
+            }
+            else -> rows.forEach { row ->
+                appendLine("  ${row.name.padEnd(nameWidth)}    ${row.description ?: ""}")
+            }
+        }
+    }
+
+    private fun StringBuilder.arguments(arguments: List<Argument<*>>) {
+        val rows = arguments.map { argument ->
+            val name = argument.name
+            val type = argument.parser.type.name
+            val range = renderRange(argument.min, argument.max)
+            val description = argument.description
+            ArgumentRow(name, type, range, description)
+        }
+        val nameWidth = rows.maxOf { it.name.length }
+        val constraintsWidth = rows.maxOf { it.constraints.length }
+
+        appendLine("Arguments:")
+        for (row in rows) {
+            appendLine("  ${row.name.padEnd(nameWidth)}    ${row.constraints.padEnd(constraintsWidth)}    ${row.description ?: ""}")
+        }
+    }
+
+    private fun StringBuilder.options(options: List<Option<*>>) {
+        val rows = options.map { option ->
+            val name = option.names.joinToString(" | ") { it.withPrefix() }
+            val type = option.parser.type.name
+            val range = renderRange(option.min, option.max)
+            val description = option.description
+            OptionRow(name, type, range, description)
+        }
+        val nameWidth = rows.maxOf { it.name.length }
+        val constraintsWidth = rows.maxOf { it.constraints.length }
+
+        appendLine("Options:")
+        for (row in rows) {
+            appendLine("  ${row.name.padEnd(nameWidth)}    ${row.constraints.padEnd(constraintsWidth)}    ${row.description ?: ""}")
+        }
+    }
+
+    private fun String.withPrefix() = when {
+        length == 1 -> "-$this"
+        else -> "--$this"
+    }
+
+    private val KClass<*>.name: String
+        get() = simpleName ?: "Unknown"
+
+    private fun renderRange(min: Int, max: Int?) = when {
+        max == null -> "{$min,}"
+        min == max -> "{$min}"
+        else -> "{$min,$max}"
+    }
+
+    private fun renderRangeFull(min: Int, max: Int?) = when {
+        min == 1 && max == 1 -> "required"
+        min == 0 && max == 1 -> "optional"
+        else -> when {
+            max == null -> "at least $min"
+            min == max -> "exactly $min"
+            else -> "between $min and $max"
+        }
+    }
+
+    data class CommandRow(
+        val name: String,
+        val type: String?,
+        val description: String?,
+    )
+
+    data class ArgumentRow(
+        val name: String,
+        val type: String,
+        val range: String,
+        val description: String?,
+    ) {
+        val constraints: String
+            get() = "$type$range"
+    }
+
+    data class OptionRow(
+        val name: String,
+        val type: String,
+        val range: String,
+        val description: String?,
+    ) {
+        val constraints: String
+            get() = "$type$range"
+    }
+}

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

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

src/commonMain/kotlin/com/infendro/cli/command/help/NoOpHelpRenderer.kt

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

src/commonMain/kotlin/com/infendro/cli/error/Error.kt

@@ -0,0 +1,5 @@
+package com.infendro.cli.error
+
+abstract class Error {
+    abstract val message: String
+}

src/commonMain/kotlin/com/infendro/cli/error/InvalidArgumentCount.kt

@@ -0,0 +1,18 @@
+package com.infendro.cli.error
+
+import com.infendro.cli.argument.Argument
+
+class InvalidArgumentCount(
+    val argument: Argument<*>,
+    val count: Int,
+) : Error() {
+    override val message: String
+        get() {
+            val expected = when {
+                argument.min == argument.max -> "${argument.min}"
+                argument.unbounded -> "at least ${argument.min}"
+                else -> "${argument.min} to ${argument.max}"
+            }
+            return """Invalid number of values for argument "${argument.name}". Expected $expected but found $count."""
+        }
+}

src/commonMain/kotlin/com/infendro/cli/error/InvalidOptionCount.kt

@@ -0,0 +1,18 @@
+package com.infendro.cli.error
+
+import com.infendro.cli.option.Option
+
+class InvalidOptionCount(
+    val option: Option<*>,
+    val count: Int,
+) : Error() {
+    override val message: String
+        get() {
+            val expected = when {
+                option.min == option.max -> "${option.min}"
+                option.unbounded -> "at least ${option.min}"
+                else -> "${option.min} to ${option.max}"
+            }
+            return """Invalid number of values passed for option "${option.name}". Expected $expected but found $count."""
+        }
+}

src/commonMain/kotlin/com/infendro/cli/error/InvalidValue.kt

@@ -0,0 +1,11 @@
+package com.infendro.cli.error
+
+import kotlin.reflect.KClass
+
+class InvalidValue(
+    val value: String,
+    val type: KClass<*>,
+) : Error() {
+    override val message: String
+        get() = """"$value" cannot be converted to ${type.simpleName ?: "Unknown"}."""
+}

src/commonMain/kotlin/com/infendro/cli/error/MalformedOption.kt

@@ -0,0 +1,8 @@
+package com.infendro.cli.error
+
+class MalformedOption(
+    val option: String,
+) : Error() {
+    override val message: String
+        get() = """Malformed option "$option"."""
+}

src/commonMain/kotlin/com/infendro/cli/error/MissingOptionValue.kt

@@ -0,0 +1,10 @@
+package com.infendro.cli.error
+
+import com.infendro.cli.option.Option
+
+class MissingOptionValue(
+    val option: Option<*>,
+) : Error() {
+    override val message: String
+        get() = """No value provided for option "${option.name}"."""
+}

src/commonMain/kotlin/com/infendro/cli/error/UnexpectedArgument.kt

@@ -0,0 +1,8 @@
+package com.infendro.cli.error
+
+class UnexpectedArgument(
+    val argument: String,
+) : Error() {
+    override val message: String
+        get() = """Unexpected argument "$argument"."""
+}

src/commonMain/kotlin/com/infendro/cli/error/UnknownCommand.kt

@@ -0,0 +1,24 @@
+package com.infendro.cli.error
+
+import com.infendro.cli.command.Command
+import com.infendro.cli.util.distance
+import com.infendro.cli.util.threshold
+import kotlin.math.min
+
+class UnknownCommand(
+    val command: Command,
+    val name: String,
+) : Error() {
+    override val message: String
+        get() = buildString {
+            val suggestion = command.commands
+                .map { it.name }
+                .associateWith { distance(name, it) }
+                .filter { it.value <= min(it.key.length - 1, threshold) }
+                .minByOrNull { it.value }
+                ?.key
+
+            append("""Unknown command "$name".""")
+            if (suggestion != null) append(""" Did you mean "$suggestion"?""")
+        }
+}

src/commonMain/kotlin/com/infendro/cli/error/UnknownOption.kt

@@ -0,0 +1,24 @@
+package com.infendro.cli.error
+
+import com.infendro.cli.command.Command
+import com.infendro.cli.util.distance
+import com.infendro.cli.util.threshold
+import kotlin.math.min
+
+class UnknownOption(
+    val command: Command,
+    val name: String,
+) : Error() {
+    override val message: String
+        get() = buildString {
+            val suggestion = command.options
+                .flatMap { it.names }
+                .associateWith { distance(name, it) }
+                .filter { it.value <= min(it.key.length - 1, threshold) }
+                .minByOrNull { it.value }
+                ?.key
+
+            append("""Unknown option "$name".""")
+            if (suggestion != null) append(""" Did you mean "$suggestion"?""")
+        }
+}

src/commonMain/kotlin/com/infendro/cli/exception/BuildException.kt

@@ -0,0 +1,5 @@
+package com.infendro.cli.exception
+
+abstract class BuildException : Exception() {
+    abstract override val message: String
+}

src/commonMain/kotlin/com/infendro/cli/exception/CliException.kt

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

src/commonMain/kotlin/com/infendro/cli/exception/DuplicateArgument.kt

@@ -0,0 +1,10 @@
+package com.infendro.cli.exception
+
+import com.infendro.cli.argument.Argument
+
+class DuplicateArgument(
+    val argument: Argument<*>,
+) : BuildException() {
+    override val message: String
+        get() = """duplicate argument "${argument.name}""""
+}

src/commonMain/kotlin/com/infendro/cli/exception/DuplicateCommand.kt

@@ -0,0 +1,10 @@
+package com.infendro.cli.exception
+
+import com.infendro.cli.command.Command
+
+class DuplicateCommand(
+    val command: Command,
+) : BuildException() {
+    override val message: String
+        get() = """duplicate command "${command.name}""""
+}

src/commonMain/kotlin/com/infendro/cli/exception/DuplicateExecute.kt

@@ -0,0 +1,6 @@
+package com.infendro.cli.exception
+
+class DuplicateExecute : BuildException() {
+    override val message: String
+        get() = """duplicate execute block"""
+}

src/commonMain/kotlin/com/infendro/cli/exception/DuplicateOption.kt

@@ -0,0 +1,10 @@
+package com.infendro.cli.exception
+
+import com.infendro.cli.option.Option
+
+class DuplicateOption(
+    val option: Option<*>,
+) : BuildException() {
+    override val message: String
+        get() = """duplicate option "${option.name}""""
+}

src/commonMain/kotlin/com/infendro/cli/exception/DuplicateRenderer.kt

@@ -0,0 +1,6 @@
+package com.infendro.cli.exception
+
+class DuplicateRenderer : BuildException() {
+    override val message: String
+        get() = """duplicate renderer"""
+}

src/commonMain/kotlin/com/infendro/cli/exception/InvalidArgumentName.kt

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

src/commonMain/kotlin/com/infendro/cli/exception/InvalidArgumentOrder.kt

@@ -0,0 +1,6 @@
+package com.infendro.cli.exception
+
+class InvalidArgumentOrder : BuildException() {
+    override val message: String
+        get() = """invalid argument order"""
+}

src/commonMain/kotlin/com/infendro/cli/exception/InvalidCommandName.kt

@@ -0,0 +1,8 @@
+package com.infendro.cli.exception
+
+class InvalidCommandName(
+    val name: String,
+) : BuildException() {
+    override val message: String
+        get() = """invalid command name "$name""""
+}

src/commonMain/kotlin/com/infendro/cli/exception/InvalidCommandOrder.kt

@@ -0,0 +1,6 @@
+package com.infendro.cli.exception
+
+class InvalidCommandOrder : BuildException() {
+    override val message: String
+        get() = """invalid command order"""
+}

src/commonMain/kotlin/com/infendro/cli/exception/InvalidFallback.kt

@@ -0,0 +1,6 @@
+package com.infendro.cli.exception
+
+class InvalidFallback : BuildException() {
+    override val message: String
+        get() = """invalid fallback"""
+}

src/commonMain/kotlin/com/infendro/cli/exception/InvalidOptionName.kt

@@ -0,0 +1,8 @@
+package com.infendro.cli.exception
+
+class InvalidOptionName(
+    val name: String,
+) : BuildException() {
+    override val message: String
+        get() = """invalid option name "$name""""
+}

src/commonMain/kotlin/com/infendro/cli/exception/InvalidRange.kt

@@ -0,0 +1,6 @@
+package com.infendro.cli.exception
+
+class InvalidRange : BuildException() {
+    override val message: String
+        get() = """invalid range"""
+}

src/commonMain/kotlin/com/infendro/cli/exception/MissingOptionName.kt

@@ -0,0 +1,6 @@
+package com.infendro.cli.exception
+
+class MissingOptionName : BuildException() {
+    override val message: String
+        get() = """missing option name"""
+}

src/commonMain/kotlin/com/infendro/cli/exception/build/DuplicateArgumentException.kt

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

src/commonMain/kotlin/com/infendro/cli/exception/build/DuplicateCommandException.kt

@@ -1,5 +0,0 @@
-package com.infendro.cli.exception.build
-
-class DuplicateCommandException(
-    val command: String?,
-) : Exception()

src/commonMain/kotlin/com/infendro/cli/exception/build/DuplicateExecuteException.kt

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

src/commonMain/kotlin/com/infendro/cli/exception/build/IllegalArgumentNameException.kt

@@ -1,5 +0,0 @@
-package com.infendro.cli.exception.build
-
-class IllegalArgumentNameException(
-    val name: String,
-) : Exception()

src/commonMain/kotlin/com/infendro/cli/exception/build/IllegalCommandNameException.kt

@@ -1,5 +0,0 @@
-package com.infendro.cli.exception.build
-
-class IllegalCommandNameException(
-    val name: String,
-) : Exception()

src/commonMain/kotlin/com/infendro/cli/exception/build/NoArgumentNameException.kt

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

src/commonMain/kotlin/com/infendro/cli/exception/build/NoExecuteException.kt

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

src/commonMain/kotlin/com/infendro/cli/exception/run/DuplicateArgumentException.kt

@@ -1,10 +0,0 @@
-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""""
-}

src/commonMain/kotlin/com/infendro/cli/exception/run/MalformedArgumentException.kt

@@ -1,10 +0,0 @@
-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""""
-}

src/commonMain/kotlin/com/infendro/cli/exception/run/MissingArgumentException.kt

@@ -1,10 +0,0 @@
-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""""
-}

src/commonMain/kotlin/com/infendro/cli/exception/run/ParseException.kt

@@ -1,11 +0,0 @@
-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"""
-}

src/commonMain/kotlin/com/infendro/cli/exception/run/UnknownArgumentException.kt

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

src/commonMain/kotlin/com/infendro/cli/exception/run/UnknownCommandException.kt

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

src/commonMain/kotlin/com/infendro/cli/option/Option.kt

@@ -0,0 +1,83 @@
+package com.infendro.cli.option
+
+import com.infendro.cli.exception.InvalidOptionName
+import com.infendro.cli.exception.InvalidRange
+import com.infendro.cli.exception.MissingOptionName
+import com.infendro.cli.parser.Parser
+import com.infendro.cli.util.Regex.OPTION
+
+sealed class Option<T : Any>(
+    val parser: Parser<T>,
+    val fallback: T?,
+    val names: List<String>,
+    val description: String?,
+    val min: Int,
+    val max: Int?,
+) {
+    val name: String
+        get() = names.maxBy { it.length }
+
+    val flag: Boolean
+        get() = fallback != null
+
+    val required: Boolean
+        get() = min > 0
+    val optional: Boolean
+        get() = !required
+
+    val bounded: Boolean
+        get() = max != null
+    val unbounded: Boolean
+        get() = !bounded
+
+    val count: Int
+        get() = max ?: Int.MAX_VALUE
+
+    init {
+        when {
+            names.isEmpty() -> throw MissingOptionName()
+            names.any { !it.matches(OPTION) } -> throw InvalidOptionName(name)
+            min !in 0..count || max == 0 -> throw InvalidRange()
+        }
+    }
+
+    class Required<T : Any>(
+        parser: Parser<T>,
+        fallback: T?,
+        names: List<String>,
+        description: String?,
+    ) : Option<T>(parser, fallback, names, description, min = 1, max = 1) {
+        fun orElse(other: T) =
+            OrElse(parser, fallback, names, description, other)
+
+        fun orNull() =
+            OrNull(parser, fallback, names, description)
+
+        fun variable(min: Int = 0, max: Int? = null) =
+            Variable(parser, fallback, names, description, min, max)
+    }
+
+    class OrElse<T : Any>(
+        parser: Parser<T>,
+        fallback: T?,
+        names: List<String>,
+        description: String?,
+        val other: T,
+    ) : Option<T>(parser, fallback, names, description, min = 0, max = 1)
+
+    class OrNull<T : Any>(
+        parser: Parser<T>,
+        fallback: T?,
+        names: List<String>,
+        description: String?,
+    ) : Option<T>(parser, fallback, names, description, min = 0, max = 1)
+
+    class Variable<T : Any>(
+        parser: Parser<T>,
+        fallback: T?,
+        names: List<String>,
+        description: String?,
+        min: Int,
+        max: Int?,
+    ) : Option<T>(parser, fallback, names, description, min, max)
+}

src/commonMain/kotlin/com/infendro/cli/option/OptionFactory.kt

@@ -0,0 +1,34 @@
+package com.infendro.cli.option
+
+import com.infendro.cli.parser.*
+
+object OptionFactory {
+    fun string(vararg names: String, description: String? = null) =
+        option(StringParser, *names, description = description)
+
+    fun int(vararg names: String, description: String? = null) =
+        option(IntParser, *names, description = description)
+
+    fun long(vararg names: String, description: String? = null) =
+        option(LongParser, *names, description = description)
+
+    fun float(vararg names: String, description: String? = null) =
+        option(FloatParser, *names, description = description)
+
+    fun double(vararg names: String, description: String? = null) =
+        option(DoubleParser, *names, description = description)
+
+    fun boolean(vararg names: String, description: String? = null) =
+        option(BooleanParser, fallback = true, *names, description = description)
+
+    inline fun <reified T : Enum<T>> enum(vararg names: String, description: String? = null) =
+        option(enumParser<T>(), *names, description = description)
+}
+
+val option = OptionFactory
+
+fun <T : Any> option(parser: Parser<T>, vararg names: String, description: String? = null) =
+    Option.Required(parser, fallback = null, names.asList(), description)
+
+fun <T : Any> option(parser: Parser<T>, fallback: T, vararg names: String, description: String? = null) =
+    Option.Required(parser, fallback, names.asList(), description)

src/commonMain/kotlin/com/infendro/cli/parser/BooleanParser.kt

@@ -0,0 +1,10 @@
+package com.infendro.cli.parser
+
+object BooleanParser : Parser<Boolean>(Boolean::class) {
+    override fun parse(text: String) =
+        when (text) {
+            "true", "t" -> success(true)
+            "false", "f" -> success(false)
+            else -> failure(text)
+        }
+}

src/commonMain/kotlin/com/infendro/cli/parser/DoubleParser.kt

@@ -0,0 +1,8 @@
+package com.infendro.cli.parser
+
+object DoubleParser : Parser<Double>(Double::class) {
+    override fun parse(text: String) =
+        text.toDoubleOrNull()
+            ?.let { success(it) }
+            ?: failure(text)
+}

src/commonMain/kotlin/com/infendro/cli/parser/EnumParser.kt

@@ -0,0 +1,16 @@
+package com.infendro.cli.parser
+
+import kotlin.enums.enumEntries
+import kotlin.reflect.KClass
+
+class EnumParser<T : Enum<T>>(
+    type: KClass<T>,
+    private val values: List<T>,
+) : Parser<T>(type) {
+    override fun parse(text: String) =
+        values.firstOrNull { it.name == text }
+            ?.let { success(it) }
+            ?: failure(text)
+}
+
+inline fun <reified T : Enum<T>> enumParser() = EnumParser(T::class, enumEntries<T>())

src/commonMain/kotlin/com/infendro/cli/parser/FloatParser.kt

@@ -0,0 +1,8 @@
+package com.infendro.cli.parser
+
+object FloatParser : Parser<Float>(Float::class) {
+    override fun parse(text: String) =
+        text.toFloatOrNull()
+            ?.let { success(it) }
+            ?: failure(text)
+}

src/commonMain/kotlin/com/infendro/cli/parser/IntParser.kt

@@ -0,0 +1,8 @@
+package com.infendro.cli.parser
+
+object IntParser : Parser<Int>(Int::class) {
+    override fun parse(text: String) =
+        text.toIntOrNull()
+            ?.let { success(it) }
+            ?: failure(text)
+}

src/commonMain/kotlin/com/infendro/cli/parser/LongParser.kt

@@ -0,0 +1,8 @@
+package com.infendro.cli.parser
+
+object LongParser : Parser<Long>(Long::class) {
+    override fun parse(text: String) =
+        text.toLongOrNull()
+            ?.let { success(it) }
+            ?: failure(text)
+}

src/commonMain/kotlin/com/infendro/cli/parser/Parser.kt

@@ -0,0 +1,24 @@
+package com.infendro.cli.parser
+
+import com.infendro.cli.error.Error
+import com.infendro.cli.error.InvalidValue
+import kotlin.reflect.KClass
+
+abstract class Parser<T : Any>(
+    val type: KClass<T>,
+) {
+    sealed class Result<T : Any> {
+        data class Success<T : Any>(
+            val value: T,
+        ) : Result<T>()
+
+        data class Failure<T : Any>(
+            val error: Error,
+        ) : Result<T>()
+    }
+
+    protected fun success(value: T) = Result.Success(value)
+    protected fun failure(text: String) = Result.Failure<T>(InvalidValue(text, type))
+
+    abstract fun parse(text: String): Result<T>
+}

src/commonMain/kotlin/com/infendro/cli/parser/StringParser.kt

@@ -0,0 +1,6 @@
+package com.infendro.cli.parser
+
+object StringParser : Parser<String>(String::class) {
+    override fun parse(text: String) =
+        success(text)
+}

src/commonMain/kotlin/com/infendro/cli/util/Distance.kt

@@ -0,0 +1,54 @@
+package com.infendro.cli.util
+
+internal const val threshold = 2
+
+/**
+ * Calculates the Damerau-Levenshtein distance between two strings.
+ *
+ * The distance is the minimum number of operations (insertion, deletion, substitution, and transposition) required to transform one string into another.
+ *
+ * @param a The source string.
+ * @param b The target string.
+ * @return The minimum number of operations to transform [a] into [b].
+ */
+internal fun distance(a: String, b: String): Int {
+    if (a == b) return 0
+
+    val n = a.length
+    val m = b.length
+
+    if (n == 0) return m
+    if (m == 0) return n
+
+    var prev2 = IntArray(m + 1)
+    var prev1 = IntArray(m + 1) { it }
+    var curr = IntArray(m + 1)
+
+    for (i in 1..n) {
+        curr[0] = i
+        for (j in 1..m) {
+            val cost = if (a[i - 1] == b[j - 1]) 0 else 1
+
+            curr[j] = minOf(
+                prev1[j] + 1,        // deletion
+                curr[j - 1] + 1,     // insertion
+                prev1[j - 1] + cost, // substitution
+            )
+
+            // transposition
+            if (i > 1 && j > 1 && a[i - 1] == b[j - 2] && a[i - 2] == b[j - 1]) {
+                curr[j] = minOf(
+                    curr[j],
+                    prev2[j - 2] + 1,
+                )
+            }
+        }
+
+        val tmp = prev2
+        prev2 = prev1
+        prev1 = curr
+        curr = tmp
+    }
+
+    return prev1[m]
+}

src/commonMain/kotlin/com/infendro/cli/util/Regex.kt

@@ -1,6 +1,7 @@
 package com.infendro.cli.util
 
 internal object Regex {
-    val COMMAND_NAME = Regex("""[a-z]+(?:-[a-z]+)*""")
-    val ARGUMENT_NAME = Regex("""[a-z]+(?:[\-.][a-z]+)*""")
+    val COMMAND = Regex("""[a-zA-Z][a-zA-Z0-9]*(?:-[a-zA-Z0-9]+)*""")
+    val ARGUMENT = Regex("""[a-zA-Z][a-zA-Z0-9]*(?:[\-.][a-zA-Z0-9]+)*""")
+    val OPTION = Regex("""[a-zA-Z][a-zA-Z0-9]*(?:[\-.][a-zA-Z0-9]+)*""")
 }