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.
+`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
 
@@ -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>) {
+fun main(args: Array<String>) = command("application", description = "example application") {
-    // declare root command
-    cli {
     execute {
-            // execution of root command (e.g., display help)
+        // define execution of command (e.g., display help)
+        help()
     }
 
-        // declare command "test"
+    // register command "greet"
-        command("test") {
+    +command("greet", description = "greet someone") {
-            // declare arguments
+        // declare and register arguments
-            val greetingArg = stringOrElse("greeting", "greet", "g", other = "Hello")
+        val speakersArg = +argument.string("speakers", description = "the greeters").variable(min = 1)
-            val nameArg = stringOrNull("name", "n")
+
+        // 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
+            // retrieve the arguments and options
-                val greeting by greetingArg
+            val speakers by speakersArg
-                val name by nameArg
+            val greeting by greetingOpt
+            val name by nameOpt
 
-                println("$greeting ${name ?: "World"}!")
+            println("${speakers.joinToString()}: $greeting ${name ?: "World"}!")
         }
 
-            // declare more commands...
+        // register more commands...
     }
 
-        // declare wildcard command
+    // register fallback command "value"
-        command { wildcard ->
+    +command.fallback.string("value", description = "execute an arbitrary command") { valueArg ->
         execute {
-                // retrieve the value used for the wildcard command
+            // retrieve the value used for the fallback command
-                val value by wildcard
+            val value by valueArg
 
-                println("command $value executed!")
+            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"
+infendro = "1.1.0"
-kotlin = "2.2.21"
+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

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

@@ -1,88 +0,0 @@
-package com.infendro.cli.command
-
-import com.infendro.cli.parser.*
-
-sealed class Argument<T : Any>(
-    val parser: Parser<T>,
-) {
-    abstract val required: Boolean
-
-    class Required<T : Any>(
-        parser: Parser<T>,
-    ) : Argument<T>(parser) {
-        override val required: Boolean
-            get() = true
-    }
-
-    class OrElse<T : Any>(
-        val other: T,
-        parser: Parser<T>,
-    ) : Argument<T>(parser) {
-        override val required: Boolean
-            get() = false
-    }
-
-    class OrNull<T : Any>(
-        parser: Parser<T>,
-    ) : Argument<T>(parser) {
-        override val required: Boolean
-            get() = false
-    }
-
-    class Variable<T : Any>(
-        parser: Parser<T>,
-    ) : Argument<T>(parser) {
-        override val required: Boolean
-            get() = false
-    }
-
-    companion object {
-        fun string() =
-            Required(StringParser)
-
-        fun stringOrElse(other: String) =
-            OrElse(other, StringParser)
-
-        fun stringOrNull() =
-            OrNull(StringParser)
-
-        fun strings() =
-            Variable(StringParser)
-
-        fun int() =
-            Required(IntParser)
-
-        fun intOrElse(other: Int) =
-            OrElse(other, IntParser)
-
-        fun intOrNull() =
-            OrNull(IntParser)
-
-        fun ints() =
-            Variable(IntParser)
-
-        fun boolean() =
-            Required(BooleanParser)
-
-        fun booleanOrElse(other: Boolean) =
-            OrElse(other, BooleanParser)
-
-        fun booleanOrNull() =
-            OrNull(BooleanParser)
-
-        fun booleans() =
-            Variable(BooleanParser)
-
-        inline fun <reified T : Enum<T>> enum() =
-            Required(enumParser<T>())
-
-        inline fun <reified T : Enum<T>> enumOrElse(other: T) =
-            OrElse(other, enumParser<T>())
-
-        inline fun <reified T : Enum<T>> enumOrNull() =
-            OrNull(enumParser<T>())
-
-        inline fun <reified T : Enum<T>> enums() =
-            Variable(enumParser<T>())
-    }
-}

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

@@ -1,110 +1,184 @@
 package com.infendro.cli.command
 
+import com.infendro.cli.Dsl
+import com.infendro.cli.argument.Argument
 import com.infendro.cli.command.context.Context
-import com.infendro.cli.command.context.Parser
+import com.infendro.cli.command.context.ContextParser
-import com.infendro.cli.exception.build.*
+import com.infendro.cli.command.help.DefaultHelpRenderer
-import com.infendro.cli.exception.run.CliException
+import com.infendro.cli.command.help.HelpRenderer
-import com.infendro.cli.util.Regex.COMMAND
+import com.infendro.cli.exception.*
-import com.infendro.cli.util.Regex.OPTION
+import com.infendro.cli.option.Option
+import com.infendro.cli.parser.Parser
+import com.infendro.cli.util.Regex
 
-class Command private constructor(
+sealed class Command private constructor(
-    val name: String?,
+    val name: String,
+    val description: String?,
     val commands: List<Command>,
-    val options: List<Option<*>>,
     val arguments: List<Argument<*>>,
+    val options: List<Option<*>>,
     internal val execute: Context.() -> Unit,
+    internal val renderer: HelpRenderer,
 ) {
-    val fallback: Boolean
+    init {
-        get() = name == null
+        if (!name.matches(Regex.COMMAND)) throw InvalidCommandName(name)
-
-    fun run(args: Array<String>) = try {
-        Parser.parse(this, args).execute()
-    } catch (e: CliException) {
-        println(e.message)
     }
 
-    class Builder internal constructor(
+    fun run(vararg args: String) {
-        private val level: Int,
+        when (val result = ContextParser(this, arrayOf(*args)).parse()) {
-        private val name: String?,
+            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")
+            }
+        }
+    }
+
+    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)
+        }
+    }
+
+    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?,
     ) {
-        private val commands = mutableListOf<Command>()
+        protected val commands = mutableListOf<Command>()
-        private val arguments = mutableListOf<Argument<*>>()
+        protected val arguments = mutableListOf<Argument<*>>()
-        private val options = mutableListOf<Option<*>>()
+        protected val options = mutableListOf<Option<*>>()
-        private lateinit var _execute: Context.() -> Unit
+        private var _execute: (Context.() -> Unit)? = null
+        private var _renderer: HelpRenderer? = null
 
-        private val key: Key
+        protected val execute: Context.() -> Unit
-            get() = Key(level)
+            get() = _execute!!
+        protected val renderer: HelpRenderer
+            get() = _renderer!!
 
-        fun command(name: String? = null, block: Builder.(Key) -> Unit) {
+        fun register(command: Command) {
-            // validate
+            validateCommand(command)
-            val last = commands.lastOrNull()
+            commands += command
-            when {
-                last != null && last.fallback -> throw CommandOrderException()
-                name != null && !name.matches(COMMAND) -> throw IllegalCommandNameException(name)
-                commands.any { it.name == name } -> throw DuplicateCommandException(name)
         }
 
-            commands += Builder(level + 1, name).also { it.block(it.key) }.build()
+        fun register(vararg commands: Command) = commands.forEach(::register)
-        }
+        operator fun <T : Command> T.unaryPlus() = also(::register)
-
-        fun argument(argument: Argument<*>) {
-            // validate
-            val last = arguments.lastOrNull()
-            when {
-                last is Argument.Variable -> throw ArgumentOrderException()
-                argument.required && last != null && !last.required -> throw ArgumentOrderException()
-            }
 
+        fun register(argument: Argument<*>) {
+            validateArgument(argument)
             arguments += argument
         }
 
-        fun <T : Argument<*>> T.register() = also(::argument)
+        fun register(vararg arguments: Argument<*>) = arguments.forEach(::register)
-
+        operator fun <T : Argument<*>> T.unaryPlus() = also(::register)
-        fun arguments(vararg arguments: Argument<*>) = arguments.forEach(::argument)
-        fun <T : Argument<*>> Array<T>.register() = also(::arguments)
-
-        fun option(option: Option<*>) {
-            // validate
-            for (name in option.names) {
-                when {
-                    !name.matches(OPTION) -> throw IllegalOptionNameException(name)
-                    options.any { name in it.names } -> throw DuplicateOptionException(name)
-                }
-            }
 
+        fun register(option: Option<*>) {
+            validateOption(option)
             options += option
         }
 
-        fun <T : Option<*>> T.register() = also(::option)
+        fun register(vararg options: Option<*>) = options.forEach(::register)
-
+        operator fun <T : Option<*>> T.unaryPlus() = also(::register)
-        fun options(vararg options: Option<*>) = options.forEach(::option)
-        fun <T : Option<*>> Array<T>.register() = also(::options)
 
         fun execute(block: Context.() -> Unit) {
-            if (::_execute.isInitialized)
+            validateExecute()
-                throw DuplicateExecuteException()
-
             _execute = block
         }
 
-        fun build(): Command {
+        fun renderer(renderer: HelpRenderer) {
-            // validate
+            validateRenderer()
-            val last = commands.lastOrNull()
+            _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 != null && last.fallback && arguments.isNotEmpty() -> throw InvalidFallbackException()
+                    last.unbounded -> throw InvalidArgumentOrder()
+                    argument.required && last.optional -> throw InvalidArgumentOrder()
+                }
+            }
+            if (arguments.any { it.name == argument.name }) throw DuplicateArgument(argument)
         }
 
-            if (!::_execute.isInitialized)
+        private fun validateOption(option: Option<*>) {
-                _execute = {}
+            for (name in option.names) {
-
+                if (options.any { name in it.names }) throw DuplicateOption(option)
-            return Command(name, commands, options, arguments, _execute)
             }
         }
 
-    class Key internal constructor(
+        private fun validateExecute() {
-        internal val index: Int,
+            if (_execute != null) throw DuplicateExecute()
-    )
         }
 
-fun cli(block: Command.Builder.() -> Unit) =
+        private fun validateRenderer() {
-    Command.Builder(-1, null).also(block).build()
+            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/Option.kt

@@ -1,131 +0,0 @@
-package com.infendro.cli.command
-
-import com.infendro.cli.exception.build.MissingOptionNameException
-import com.infendro.cli.parser.*
-
-sealed class Option<T : Any>(
-    val parser: Parser<T>,
-    val fallback: T?,
-    val names: List<String>,
-) {
-    val flag: Boolean
-        get() = fallback != null
-
-    val name: String
-        get() = names[0]
-
-    abstract val required: Boolean
-
-    init {
-        if (names.isEmpty())
-            throw MissingOptionNameException()
-    }
-
-    class Required<T : Any>(
-        parser: Parser<T>,
-        fallback: T?,
-        names: List<String>,
-    ) : Option<T>(parser, fallback, names) {
-        constructor(
-            parser: Parser<T>,
-            names: List<String>,
-        ) : this(parser, null, names)
-
-        override val required: Boolean
-            get() = true
-    }
-
-    class OrElse<T : Any>(
-        parser: Parser<T>,
-        fallback: T?,
-        names: List<String>,
-        val other: T,
-    ) : Option<T>(parser, fallback, names) {
-        constructor(
-            parser: Parser<T>,
-            names: List<String>,
-            other: T,
-        ) : this(parser, null, names, other)
-
-        override val required: Boolean
-            get() = false
-    }
-
-    class OrNull<T : Any>(
-        parser: Parser<T>,
-        fallback: T?,
-        names: List<String>,
-    ) : Option<T>(parser, fallback, names) {
-        constructor(
-            parser: Parser<T>,
-            names: List<String>,
-        ) : this(parser, null, names)
-
-        override val required: Boolean
-            get() = false
-    }
-
-    class Variable<T : Any>(
-        parser: Parser<T>,
-        fallback: T?,
-        names: List<String>,
-    ) : Option<T>(parser, fallback, names) {
-        constructor(
-            parser: Parser<T>,
-            names: List<String>,
-        ) : this(parser, null, names)
-
-        override val required: Boolean
-            get() = false
-    }
-
-    companion object {
-        fun string(vararg names: String) =
-            Required(StringParser, names.asList())
-
-        fun stringOrElse(vararg names: String, other: String) =
-            OrElse(StringParser, names.asList(), other)
-
-        fun stringOrNull(vararg names: String) =
-            OrNull(StringParser, names.asList())
-
-        fun strings(vararg names: String) =
-            Variable(StringParser, names.asList())
-
-        fun int(vararg names: String) =
-            Required(IntParser, names.asList())
-
-        fun intOrElse(vararg names: String, other: Int) =
-            OrElse(IntParser, names.asList(), other)
-
-        fun intOrNull(vararg names: String) =
-            OrNull(IntParser, names.asList())
-
-        fun ints(vararg names: String) =
-            Variable(IntParser, names.asList())
-
-        fun boolean(vararg names: String) =
-            Required(BooleanParser, true, names.asList())
-
-        fun booleanOrElse(vararg names: String, other: Boolean) =
-            OrElse(BooleanParser, true, names.asList(), other)
-
-        fun booleanOrNull(vararg names: String) =
-            OrNull(BooleanParser, true, names.asList())
-
-        fun booleans(vararg names: String) =
-            Variable(BooleanParser, true, names.asList())
-
-        inline fun <reified T : Enum<T>> enum(vararg names: String) =
-            Required(enumParser<T>(), names.asList())
-
-        inline fun <reified T : Enum<T>> enumOrElse(vararg names: String, other: T) =
-            OrElse(enumParser<T>(), names.asList(), other)
-
-        inline fun <reified T : Enum<T>> enumOrNull(vararg names: String) =
-            OrNull(enumParser<T>(), names.asList())
-
-        inline fun <reified T : Enum<T>> enums(vararg names: String) =
-            Variable(enumParser<T>(), names.asList())
-    }
-}

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

@@ -1,59 +1,63 @@
 package com.infendro.cli.command.context
 
-import com.infendro.cli.command.Argument
+import com.infendro.cli.Dsl
 import com.infendro.cli.command.Command
-import com.infendro.cli.command.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>,
-    val commands: List<Cmd>,
+    private val commands: Map<Command.Fallback.Key<*>, Any>,
-    val options: List<Opt>,
+    private val arguments: Map<Argument<*>, List<Any>>,
-    val arguments: List<Arg>,
+    private val options: Map<Option<*>, List<Any>>,
 ) {
-    class Cmd(
+    val command: Command
-        val name: String,
+        get() = path.last()
-    )
-
-    class Arg(
-        val value: Any,
-    )
-
-    class Opt(
-        val name: String,
-        val value: Any,
-    )
 
     internal fun execute() = (command.execute)()
 
-    operator fun Command.Key.getValue(thisRef: Any?, property: KProperty<*>): String = commands[index].name
+    fun help() {
-
+        command.renderer.render(path)?.let { print(it) }
-    private val <T : Any> Argument<T>.index: Int
+    }
-        get() = command.arguments.indexOf(this)
+
-
+    @Suppress("UNCHECKED_CAST")
-    @Suppress("UNCHECKED_CAST")
+    private val <T : Any> Command.Fallback.Key<T>.value: T
-    private val <T : Any> Argument<T>.value: T?
+        get() = commands[this] as T
-        get() = arguments.getOrNull(index)?.value as? T
+
-
+    operator fun <T : Any> Command.Fallback.Key<T>.getValue(thisRef: Any?, property: KProperty<*>): T =
-    @Suppress("UNCHECKED_CAST")
+        value
-    private val <T : Any> Argument.Variable<T>.values: List<T>
+
-        get() = arguments.drop(index).map { it.value as T }
+    @Suppress("UNCHECKED_CAST")
-
+    private val <T : Any> Argument<T>.values: List<T>
-    operator fun <T : Any> Argument.Required<T>.getValue(thisRef: Any?, property: KProperty<*>): T = value!!
+        get() = arguments[this] as List<T>
-    operator fun <T : Any> Argument.OrElse<T>.getValue(thisRef: Any?, property: KProperty<*>): T = value ?: other
+
-    operator fun <T : Any> Argument.OrNull<T>.getValue(thisRef: Any?, property: KProperty<*>): T? = value
+    operator fun <T : Any> Argument.Required<T>.getValue(thisRef: Any?, property: KProperty<*>): T =
-    operator fun <T : Any> Argument.Variable<T>.getValue(thisRef: Any?, property: KProperty<*>): List<T> = values
+        values.first()
-
+
-    @Suppress("UNCHECKED_CAST")
+    operator fun <T : Any> Argument.OrElse<T>.getValue(thisRef: Any?, property: KProperty<*>): T =
-    private val <T : Any> Option<T>.value: T?
+        values.firstOrNull() ?: other
-        get() = options.firstOrNull { it.name in names }?.value as? T
+
-
+    operator fun <T : Any> Argument.OrNull<T>.getValue(thisRef: Any?, property: KProperty<*>): T? =
-    @Suppress("UNCHECKED_CAST")
+        values.firstOrNull()
-    private val <T : Any> Option.Variable<T>.values: List<T>
+
-        get() = options.filter { it.name in names }.map { it.value as T }
+    operator fun <T : Any> Argument.Variable<T>.getValue(thisRef: Any?, property: KProperty<*>): List<T> =
-
+        values
-    operator fun <T : Any> Option.Required<T>.getValue(thisRef: Any?, property: KProperty<*>): T = value!!
+
-    operator fun <T : Any> Option.OrElse<T>.getValue(thisRef: Any?, property: KProperty<*>): T = value ?: other
+    @Suppress("UNCHECKED_CAST")
-    operator fun <T : Any> Option.OrNull<T>.getValue(thisRef: Any?, property: KProperty<*>): T? = value
+    private val <T : Any> Option<T>.values: List<T>
-    operator fun <T : Any> Option.Variable<T>.getValue(thisRef: Any?, property: KProperty<*>): List<T> = values
+        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/context/Parser.kt

@@ -1,130 +0,0 @@
-package com.infendro.cli.command.context
-
-import com.infendro.cli.command.Argument
-import com.infendro.cli.command.Command
-import com.infendro.cli.command.Option
-import com.infendro.cli.command.context.Context.*
-import com.infendro.cli.exception.run.*
-
-internal object Parser {
-    fun parse(root: Command, args: Array<String>): Context {
-        var command = root
-        val cmd = mutableListOf<Cmd>()
-        val arg = mutableListOf<Arg>()
-        val opt = mutableListOf<Opt>()
-
-        var i = 0
-
-        // commands
-        while (i < args.size) {
-            val current = args[i]
-
-            if (current.startsWith("-"))
-                break
-
-            val c = command.commands.firstOrNull { it.name == current || it.fallback }
-            if (c == null) {
-                when {
-                    command.arguments.isEmpty() -> throw UnknownCommandException(current)
-                    else -> break
-                }
-            }
-
-            command = c
-            cmd += Cmd(current)
-
-            i++
-        }
-
-        // arguments and options
-        var endOfOptions = false
-        var argumentIndex = 0
-        while (i < args.size) {
-            val dashes = args[i].takeWhile { it == '-' }.count()
-            val current = args[i].drop(dashes)
-
-            when {
-                // argument
-                endOfOptions || dashes == 0 -> {
-                    val argument = command.arguments.getOrNull(argumentIndex)
-                        ?: throw TooManyArgumentsException()
-
-                    if (argument !is Argument.Variable)
-                        argumentIndex++
-
-                    val value = argument.parser.parse(current) as Any
-                    arg += Arg(value)
-                }
-
-                // option
-                dashes in 1..2 -> {
-                    if (dashes == 2 && current.isEmpty()) {
-                        endOfOptions = true
-                        i++
-                        continue
-                    }
-
-                    val (name, text) = when {
-                        current.contains('=') -> {
-                            val (name, value) = current.split('=', limit = 2)
-                            name to value
-                        }
-
-                        else -> {
-                            val next = args.getOrNull(i + 1)
-                            if (next != null && !next.startsWith('-')) {
-                                i++
-                                current to next
-                            } else {
-                                current 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 }
-                            ?: throw UnknownOptionException(name)
-
-                        val value = when {
-                            text != null -> option.parser.parse(text)
-                            option.flag -> option.fallback!!
-                            else -> throw MissingOptionValueException(name)
-                        }
-                        opt += Opt(name, value)
-                    }
-                }
-
-                // malformed option
-                else -> {
-                    when {
-                        args[i].contains('=') -> {
-                            val (option) = args[i].split('=', limit = 2)
-                            throw MalformedOptionException(option)
-                        }
-                        else -> throw MalformedOptionException(args[i])
-                    }
-                }
-            }
-
-            i++
-        }
-
-        if (arg.size < command.arguments.count { it is Argument.Required })
-            throw MissingArgumentException()
-
-        for (option in command.options) {
-            val count = opt.count { it.name in option.names }
-            when {
-                option is Option.Required && count == 0 -> throw MissingOptionException(option.name)
-                option !is Option.Variable && count > 1 -> throw DuplicateOptionException(option.name)
-            }
-        }
-
-        return Context(command, cmd, opt, arg)
-    }
-}

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/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/ArgumentOrderException.kt

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

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

@@ -1,3 +0,0 @@
-package com.infendro.cli.exception.build
-
-class CommandOrderException : 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/DuplicateOptionException.kt

@@ -1,5 +0,0 @@
-package com.infendro.cli.exception.build
-
-class DuplicateOptionException(
-    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/IllegalOptionNameException.kt

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,8 +0,0 @@
-package com.infendro.cli.exception.run
-
-class MissingOptionValueException(
-    val option: String,
-) : CliException() {
-    override val message: String
-        get() = """no value provided for option "$option""""
-}

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

@@ -1,9 +0,0 @@
-package com.infendro.cli.exception.run
-
-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/TooManyArgumentsException.kt

@@ -1,6 +0,0 @@
-package com.infendro.cli.exception.run
-
-class TooManyArgumentsException : CliException() {
-    override val message: String
-        get() = """too many arguments"""
-}

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

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

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

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

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

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

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

@@ -1,17 +1,16 @@
 package com.infendro.cli.parser
 
-import com.infendro.cli.exception.run.ParseException
 import kotlin.enums.enumEntries
+import kotlin.reflect.KClass
 
 class EnumParser<T : Enum<T>>(
-    private val name: String,
+    type: KClass<T>,
     private val values: List<T>,
-) : Parser<T> {
+) : Parser<T>(type) {
-    override fun parse(text: String): T = try {
+    override fun parse(text: String) =
-        values.first { it.name == text }
+        values.firstOrNull { it.name == text }
-    } catch (_: Exception) {
+            ?.let { success(it) }
-        throw ParseException(text, name)
+            ?: failure(text)
-    }
 }
 
-inline fun <reified T : Enum<T>> enumParser() = EnumParser(T::class.simpleName!!, enumEntries<T>())
+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

@@ -1,11 +1,8 @@
 package com.infendro.cli.parser
 
-import com.infendro.cli.exception.run.ParseException
+object IntParser : Parser<Int>(Int::class) {
-
+    override fun parse(text: String) =
-object IntParser : Parser<Int> {
+        text.toIntOrNull()
-    override fun parse(text: String): Int = try {
+            ?.let { success(it) }
-        text.toInt()
+            ?: failure(text)
-    } catch (_: Exception) {
-        throw ParseException(text, "Int")
-    }
 }

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

@@ -1,5 +1,24 @@
 package com.infendro.cli.parser
 
-interface Parser<T> {
+import com.infendro.cli.error.Error
-    fun parse(text: String): T
+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

@@ -1,5 +1,6 @@
 package com.infendro.cli.parser
 
-object StringParser : Parser<String> {
+object StringParser : Parser<String>(String::class) {
-    override fun parse(text: String): String = text
+    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

@@ -2,5 +2,6 @@ package com.infendro.cli.util
 
 internal object Regex {
     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]+)*""")
 }