Merge pull request '1.4.1 release' (#10) from develop into main

Reviewed-on: Infendro/cli-kt#10

.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

@@ -2,15 +2,6 @@
 
 `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 |
-
 ## Installation
 
 Add the following to your `build.gradle.kts`.
@@ -21,27 +12,27 @@ repositories {
 }
 
 dependencies {
-    implementation("com.infendro:cli:1.4.0")
+    implementation("com.infendro:cli:1.4.1")
 }
 ```
 
 ## Usage
 
 ```kotlin
-fun main(args: Array<String>) = cli("application") {
+fun main(args: Array<String>) = command("application", description = "example application") {
     execute {
         // define execution of command (e.g., display help)
         help()
     }
 
-    // declare command "greet"
-    command("greet") {
-        // declare arguments
-        val speakersArg by argument.string("speakers").variable(min = 1)
+    // register command "greet"
+    +command("greet", description = "greet someone") {
+        // declare and register arguments
+        val speakersArg = +argument.string("speakers", description = "the greeters").variable(min = 1)
 
-        // declare options
-        val greetingOpt by option.string("greeting", "greet", "g").orElse("Hello")
-        val nameOpt by option.string("name", "n").orNull()
+        // 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 {
             // retrieve the arguments and options
@@ -52,11 +43,11 @@ fun main(args: Array<String>) = cli("application") {
             println("${speakers.joinToString()}: $greeting ${name ?: "World"}!")
         }
 
-        // declare more commands...
+        // register more commands...
     }
 
-    // declare fallback command
-    fallback.string("value") { valueArg ->
+    // 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
@@ -64,5 +55,5 @@ fun main(args: Array<String>) = cli("application") {
             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.4.0"
+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"
+kotlin = "2.3.0"
 
 [plugins]
 infendro = { id = "com.infendro.plugin", version.ref = "infendro" }

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

@@ -0,0 +1,70 @@
+package com.infendro.cli.argument
+
+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 : Any>(
+    val parser: Parser<T>,
+    val name: String,
+    val description: String?,
+    val min: Int,
+    val max: Int?,
+) {
+    init {
+        when {
+            !name.matches(ARGUMENT) -> throw InvalidArgumentName(name)
+            min !in 0..count || max == 0 -> throw InvalidRange()
+        }
+    }
+
+    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
+
+    class Required<T : Any>(
+        parser: Parser<T>,
+        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 OrElse<T : Any>(
+        parser: Parser<T>,
+        name: String,
+        description: String?,
+        val other: T,
+    ) : Argument<T>(parser, name, description, min = 0, max = 1)
+
+    class OrNull<T : Any>(
+        parser: Parser<T>,
+        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/command/Command.kt

@@ -1,87 +1,84 @@
 package com.infendro.cli.command
 
 import com.infendro.cli.Dsl
-import com.infendro.cli.command.argument.Argument
+import com.infendro.cli.argument.Argument
 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.command.option.Option
-import com.infendro.cli.exception.build.*
-import com.infendro.cli.parser.*
+import com.infendro.cli.exception.*
+import com.infendro.cli.option.Option
+import com.infendro.cli.parser.Parser
 import com.infendro.cli.util.Regex
-import com.infendro.cli.util.Regex.ARGUMENT
-import com.infendro.cli.util.Regex.OPTION
-import kotlin.reflect.KProperty
 
 sealed class Command private constructor(
-    val parent: Command?,
     val name: String,
+    val description: String?,
     val commands: List<Command>,
     val arguments: List<Argument<*>>,
     val options: List<Option<*>>,
     internal val execute: Context.() -> Unit,
     internal val renderer: HelpRenderer,
 ) {
-    val path: List<Command>
-        get() = when {
-            parent == null -> listOf(this)
-            else -> parent.path + this
-        }
+    init {
+        if (!name.matches(Regex.COMMAND)) throw InvalidCommandName(name)
+    }
 
-    val help: String?
-        get() = renderer.render(this)
-
-    fun run(args: Array<String>) {
-        when (val result = ContextParser(this, args).parse()) {
+    fun run(vararg args: String) {
+        when (val result = ContextParser(this, arrayOf(*args)).parse()) {
             is ContextParser.Result.Success -> result.context.execute()
-            is ContextParser.Result.Help -> result.command.help?.let { print(it) }
+            is ContextParser.Result.Help -> {
+                val command = result.path.last()
+                val help = command.renderer.render(result.path)
+                if (help != null) print(help)
+            }
             is ContextParser.Result.Failure -> {
                 println("error: ${result.error.message}")
-                result.command.help?.let {
-                    println()
-                    print(it)
-                }
+                val command = result.path.last()
+                val help = command.renderer.render(result.path)
+                if (help != null) print("\n$help")
             }
         }
     }
 
     class Named(
-        parent: Command?,
         name: String,
+        description: String?,
         commands: List<Command>,
         arguments: List<Argument<*>>,
         options: List<Option<*>>,
         execute: Context.() -> Unit,
         renderer: HelpRenderer,
-    ) : Command(parent, name, commands, arguments, options, execute, renderer) {
+    ) : Command(name, description, commands, arguments, options, execute, renderer) {
         class Builder(
             name: String,
-        ) : Command.Builder<Named>(name) {
+            description: String?,
+        ) : Command.Builder<Named>(name, description) {
             override fun create() =
-                Named(parent, name, commands, arguments, options, execute, renderer)
+                Named(name, description, commands, arguments, options, execute, renderer)
         }
     }
 
     class Fallback<T : Any>(
-        parent: Command?,
         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(parent, name, commands, arguments, options, execute, renderer) {
+    ) : Command(name, description, commands, arguments, options, execute, renderer) {
         class Builder<T : Any>(
             val parser: Parser<T>,
             name: String,
-        ) : Command.Builder<Fallback<T>>(name) {
+            description: String?,
+        ) : Command.Builder<Fallback<T>>(name, description) {
             internal val key = Key<T>()
 
             override fun create() =
-                Fallback(parent, key, parser, name, commands, arguments, options, execute, renderer)
+                Fallback(key, parser, name, description, commands, arguments, options, execute, renderer)
         }
 
         class Key<T>
@@ -90,9 +87,8 @@ sealed class Command private constructor(
     @Dsl
     sealed class Builder<COMMAND : Command>(
         protected val name: String,
+        protected val description: String?,
     ) {
-        protected var parent: Command? = null
-        private val builders = mutableListOf<Builder<*>>()
         protected val commands = mutableListOf<Command>()
         protected val arguments = mutableListOf<Argument<*>>()
         protected val options = mutableListOf<Option<*>>()
@@ -104,40 +100,13 @@ sealed class Command private constructor(
         protected val renderer: HelpRenderer
             get() = _renderer!!
 
-        fun command(name: String, block: Builder<*>.() -> Unit) {
-            validateCommand(name)
-            builders += Named.Builder(name).apply(block)
+        fun register(command: Command) {
+            validateCommand(command)
+            commands += command
         }
 
-        inner class FallbackFactory {
-            fun string(name: String, block: Builder<*>.(Fallback.Key<String>) -> Unit) =
-                fallback(StringParser, name, block)
-
-            fun int(name: String, block: Builder<*>.(Fallback.Key<Int>) -> Unit) =
-                fallback(IntParser, name, block)
-
-            fun long(name: String, block: Builder<*>.(Fallback.Key<Long>) -> Unit) =
-                fallback(LongParser, name, block)
-
-            fun float(name: String, block: Builder<*>.(Fallback.Key<Float>) -> Unit) =
-                fallback(FloatParser, name, block)
-
-            fun double(name: String, block: Builder<*>.(Fallback.Key<Double>) -> Unit) =
-                fallback(DoubleParser, name, block)
-
-            fun boolean(name: String, block: Builder<*>.(Fallback.Key<Boolean>) -> Unit) =
-                fallback(BooleanParser, name, block)
-
-            inline fun <reified T : Enum<T>> enum(name: String, noinline block: Builder<*>.(Fallback.Key<T>) -> Unit) =
-                fallback(enumParser<T>(), name, block)
-        }
-
-        val fallback = FallbackFactory()
-
-        fun <T : Any> fallback(parser: Parser<T>, name: String, block: Fallback.Builder<T>.(Fallback.Key<T>) -> Unit) {
-            validateCommand(name)
-            builders += Fallback.Builder(parser, name).apply { block(key) }
-        }
+        fun register(vararg commands: Command) = commands.forEach(::register)
+        operator fun <T : Command> T.unaryPlus() = also(::register)
 
         fun register(argument: Argument<*>) {
             validateArgument(argument)
@@ -145,9 +114,7 @@ sealed class Command private constructor(
         }
 
         fun register(vararg arguments: Argument<*>) = arguments.forEach(::register)
-
-        operator fun <T : Argument<*>> T.provideDelegate(thisRef: Nothing?, property: KProperty<*>) = also(::register)
-        operator fun <T : Argument<*>> T.getValue(thisRef: Nothing?, property: KProperty<*>) = this
+        operator fun <T : Argument<*>> T.unaryPlus() = also(::register)
 
         fun register(option: Option<*>) {
             validateOption(option)
@@ -155,9 +122,7 @@ sealed class Command private constructor(
         }
 
         fun register(vararg options: Option<*>) = options.forEach(::register)
-
-        operator fun <T : Option<*>> T.provideDelegate(thisRef: Nothing?, property: KProperty<*>) = also(::register)
-        operator fun <T : Option<*>> T.getValue(thisRef: Nothing?, property: KProperty<*>) = this
+        operator fun <T : Option<*>> T.unaryPlus() = also(::register)
 
         fun execute(block: Context.() -> Unit) {
             validateExecute()
@@ -169,32 +134,22 @@ sealed class Command private constructor(
             _renderer = renderer
         }
 
+        internal abstract fun create(): COMMAND
+
         internal fun build(): Command {
             if (_execute == null) _execute = {}
             if (_renderer == null) _renderer = DefaultHelpRenderer
 
             validate()
-            val command = create()
-
-            for (builder in builders) {
-                builder.parent = command
-                commands += builder.build()
-            }
-
-            return command
+            return create()
         }
 
-        internal abstract fun create(): COMMAND
-
-        private fun validateCommand(name: String) {
-            if (builders.isNotEmpty()) {
-                val last = builders.last()
-                if (last is Fallback.Builder<*>) throw InvalidCommandOrder()
-            }
-            when {
-                !name.matches(Regex.COMMAND) -> throw InvalidCommand(name)
-                builders.any { it.name == name } -> throw DuplicateCommand(name)
+        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<*>) {
@@ -205,15 +160,12 @@ sealed class Command private constructor(
                     argument.required && last.optional -> throw InvalidArgumentOrder()
                 }
             }
-            if (!argument.name.matches(ARGUMENT)) throw InvalidArgument(argument.name)
+            if (arguments.any { it.name == argument.name }) throw DuplicateArgument(argument)
         }
 
         private fun validateOption(option: Option<*>) {
             for (name in option.names) {
-                when {
-                    !name.matches(OPTION) -> throw InvalidOption(name)
-                    options.any { name in it.names } -> throw DuplicateOption(name)
-                }
+                if (options.any { name in it.names }) throw DuplicateOption(option)
             }
         }
 
@@ -222,14 +174,11 @@ sealed class Command private constructor(
         }
 
         private fun validateRenderer() {
-            if (_renderer != null) throw Exception() //TODO
+            if (_renderer != null) throw DuplicateRenderer()
         }
 
         private fun validate() {
-            if (builders.any { it is Fallback.Builder<*> } && arguments.isNotEmpty()) throw InvalidFallback()
+            if (commands.any { it is Fallback<*> } && arguments.isNotEmpty()) throw InvalidFallback()
         }
     }
 }
-
-fun cli(name: String, block: Command.Builder<*>.() -> Unit) =
-    Command.Named.Builder(name).apply(block).build()

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/argument/Argument.kt

@@ -1,55 +0,0 @@
-package com.infendro.cli.command.argument
-
-import com.infendro.cli.exception.build.InvalidRange
-import com.infendro.cli.parser.Parser
-
-sealed class Argument<T : Any>(
-    val parser: Parser<T>,
-    val name: String,
-    val min: Int,
-    val max: Int?,
-) {
-    init {
-        if (min !in 0..count || max == 0) throw InvalidRange()
-    }
-
-    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
-
-    class Required<T : Any>(
-        parser: Parser<T>,
-        name: String,
-    ) : Argument<T>(parser, name, min = 1, max = 1) {
-        fun orElse(other: T) = OrElse(parser, name, other)
-        fun orNull() = OrNull(parser, name)
-        fun variable(min: Int = 0, max: Int? = null) = Variable(parser, name, min, max)
-    }
-
-    class OrElse<T : Any>(
-        parser: Parser<T>,
-        name: String,
-        val other: T,
-    ) : Argument<T>(parser, name, min = 0, max = 1)
-
-    class OrNull<T : Any>(
-        parser: Parser<T>,
-        name: String,
-    ) : Argument<T>(parser, name, min = 0, max = 1)
-
-    class Variable<T : Any>(
-        parser: Parser<T>,
-        name: String,
-        min: Int,
-        max: Int?,
-    ) : Argument<T>(parser, name, min, max)
-}

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

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

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

@@ -2,21 +2,24 @@ package com.infendro.cli.command.context
 
 import com.infendro.cli.Dsl
 import com.infendro.cli.command.Command
-import com.infendro.cli.command.argument.Argument
-import com.infendro.cli.command.option.Option
+import com.infendro.cli.argument.Argument
+import com.infendro.cli.option.Option
 import kotlin.reflect.KProperty
 
 @Dsl
 class Context internal constructor(
-    val command: Command,
+    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.help?.let { print(it) }
+        command.renderer.render(path)?.let { print(it) }
     }
 
     @Suppress("UNCHECKED_CAST")

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

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

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

@@ -1,12 +1,19 @@
 package com.infendro.cli.command.help
 
 import com.infendro.cli.command.Command
-import com.infendro.cli.command.argument.Argument
-import com.infendro.cli.command.option.Option
+import com.infendro.cli.argument.Argument
+import com.infendro.cli.option.Option
+import kotlin.reflect.KClass
 
 object DefaultHelpRenderer : HelpRenderer {
-    override fun render(command: Command) = buildString {
-        usage(command)
+    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)
@@ -21,9 +28,11 @@ object DefaultHelpRenderer : HelpRenderer {
         }
     }
 
-    private fun StringBuilder.usage(command: Command) {
+    private fun StringBuilder.usage(path: List<Command>) {
+        val command = path.last()
+
         append("Usage:")
-        for (command in command.path) {
+        for (command in path) {
             append(" ")
             when {
                 command is Command.Fallback<*> -> append("<${command.name}>")
@@ -36,11 +45,7 @@ object DefaultHelpRenderer : HelpRenderer {
                 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}}"
-                    }
+                    val range = renderRange(argument.min, argument.max)
                     append("<${argument.name}>$range")
                 }
             }
@@ -60,11 +65,7 @@ object DefaultHelpRenderer : HelpRenderer {
                 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}}"
-                    }
+                    val range = renderRange(option.min, option.max)
                     append("($text)$range")
                 }
             }
@@ -73,24 +74,66 @@ object DefaultHelpRenderer : HelpRenderer {
     }
 
     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:")
-        for (command in commands) {
-            appendLine("  * ${command.name}")
+        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 (argument in arguments) {
-            appendLine("  * ${argument.name}")
+        for (row in rows) {
+            appendLine("  ${row.name.padEnd(nameWidth)}    ${row.constraints.padEnd(constraintsWidth)}    ${row.description ?: ""}")
         }
     }
 
     private fun StringBuilder.options(options: List<Option<*>>) {
-        appendLine("Options:")
-        for (option in options) {
+        val rows = options.map { option ->
             val name = option.names.joinToString(" | ") { it.withPrefix() }
-            appendLine("  * $name")
+            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 ?: ""}")
         }
     }
 
@@ -98,4 +141,49 @@ object DefaultHelpRenderer : HelpRenderer {
         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

@@ -3,5 +3,5 @@ package com.infendro.cli.command.help
 import com.infendro.cli.command.Command
 
 interface HelpRenderer {
-    fun render(command: Command): String?
+    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/command/help/NoopHelpRenderer.kt

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

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

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

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

@@ -1,11 +1,11 @@
-package com.infendro.cli.exception.run
+package com.infendro.cli.error
 
-import com.infendro.cli.command.argument.Argument
+import com.infendro.cli.argument.Argument
 
 class InvalidArgumentCount(
     val argument: Argument<*>,
     val count: Int,
-) : RuntimeError() {
+) : Error() {
     override val message: String
         get() {
             val expected = when {
@@ -13,6 +13,6 @@ class InvalidArgumentCount(
                 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"""
+            return """Invalid number of values for argument "${argument.name}". Expected $expected but found $count."""
         }
 }

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

@@ -1,11 +1,11 @@
-package com.infendro.cli.exception.run
+package com.infendro.cli.error
 
-import com.infendro.cli.command.option.Option
+import com.infendro.cli.option.Option
 
 class InvalidOptionCount(
     val option: Option<*>,
     val count: Int,
-) : RuntimeError() {
+) : Error() {
     override val message: String
         get() {
             val expected = when {
@@ -13,6 +13,6 @@ class InvalidOptionCount(
                 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"""
+            return """Invalid number of values passed for option "${option.name}". Expected $expected but found $count."""
         }
 }

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

@@ -1,11 +1,11 @@
-package com.infendro.cli.exception.run
+package com.infendro.cli.error
 
 import kotlin.reflect.KClass
 
 class InvalidValue(
     val value: String,
     val type: KClass<*>,
-) : RuntimeError() {
+) : Error() {
     override val message: String
-        get() = """"$value" cannot be converted to ${type.simpleName ?: "Unknown"}"""
+        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/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/CliException.kt

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,6 +0,0 @@
-package com.infendro.cli.exception.run
-
-class UnexpectedArgument : RuntimeError() {
-    override val message: String
-        get() = """unexpected argument"""
-}

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

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

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

@@ -1,8 +0,0 @@
-package com.infendro.cli.exception.run
-
-class UnknownOption(
-    val option: String,
-) : RuntimeError() {
-    override val message: String
-        get() = """unknown option "$option""""
-}

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

@@ -1,13 +1,16 @@
-package com.infendro.cli.command.option
+package com.infendro.cli.option
 
-import com.infendro.cli.exception.build.InvalidRange
-import com.infendro.cli.exception.build.MissingOptionName
+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?,
 ) {
@@ -33,6 +36,7 @@ sealed class Option<T : Any>(
     init {
         when {
             names.isEmpty() -> throw MissingOptionName()
+            names.any { !it.matches(OPTION) } -> throw InvalidOptionName(name)
             min !in 0..count || max == 0 -> throw InvalidRange()
         }
     }
@@ -41,53 +45,39 @@ sealed class Option<T : Any>(
         parser: Parser<T>,
         fallback: T?,
         names: List<String>,
-    ) : Option<T>(parser, fallback, names, min = 1, max = 1) {
-        constructor(
-            parser: Parser<T>,
-            names: List<String>,
-        ) : this(parser, null, names)
+        description: String?,
+    ) : Option<T>(parser, fallback, names, description, min = 1, max = 1) {
+        fun orElse(other: T) =
+            OrElse(parser, fallback, names, description, other)
 
-        fun orElse(other: T) = OrElse(parser, fallback, names, other)
-        fun orNull() = OrNull(parser, fallback, names)
-        fun variable(min: Int = 0, max: Int? = null) = Variable(parser, fallback, names, min, max)
+        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, min = 0, max = 1) {
-        constructor(
-            parser: Parser<T>,
-            names: List<String>,
-            other: T,
-        ) : this(parser, null, names, other)
-    }
+    ) : Option<T>(parser, fallback, names, description, min = 0, max = 1)
 
     class OrNull<T : Any>(
         parser: Parser<T>,
         fallback: T?,
         names: List<String>,
-    ) : Option<T>(parser, fallback, names, min = 0, max = 1) {
-        constructor(
-            parser: Parser<T>,
-            names: List<String>,
-        ) : this(parser, null, names)
-    }
+        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, min, max) {
-        constructor(
-            parser: Parser<T>,
-            names: List<String>,
-            min: Int,
-            max: Int?,
-        ) : this(parser, null, names, min, max)
-    }
+    ) : 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/Parser.kt

@@ -1,7 +1,7 @@
 package com.infendro.cli.parser
 
-import com.infendro.cli.exception.run.InvalidValue
-import com.infendro.cli.exception.run.RuntimeError
+import com.infendro.cli.error.Error
+import com.infendro.cli.error.InvalidValue
 import kotlin.reflect.KClass
 
 abstract class Parser<T : Any>(
@@ -13,7 +13,7 @@ abstract class Parser<T : Any>(
         ) : Result<T>()
 
         data class Failure<T : Any>(
-            val error: RuntimeError,
+            val error: Error,
         ) : Result<T>()
     }
 

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]
+}