implement descriptions, improve default help

README.md

@@ -28,20 +28,20 @@ dependencies {
 ## Usage
 
 ```kotlin
-fun main(args: Array<String>) = command("application") {
+fun main(args: Array<String>) = command("application", description = "example application") {
     execute {
         // define execution of command (e.g., display help)
         help()
     }
 
     // register command "greet"
-    +command("greet") {
+    +command("greet", description = "greet someone") {
         // declare and register arguments
-        val speakersArg = +argument.string("speakers").variable(min = 1)
+        val speakersArg = +argument.string("speakers", description = "the greeters").variable(min = 1)
 
         // declare and register options
-        val greetingOpt = +option.string("greeting", "greet", "g").orElse("Hello")
+        val greetingOpt = +option.string("greeting", "greet", "g", description = "the greeting").orElse("Hello")
-        val nameOpt = +option.string("name", "n").orNull()
+        val nameOpt = +option.string("name", "n", description = "the greetee").orNull()
 
         execute {
             // retrieve the arguments and options
@@ -56,7 +56,7 @@ fun main(args: Array<String>) = command("application") {
     }
 
     // register fallback command "value"
-    +command.fallback.string("value") { valueArg ->
+    +command.fallback.string("value", description = "execute an arbitrary command") { valueArg ->
         execute {
             // retrieve the value used for the fallback command
             val value by valueArg

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

@@ -13,6 +13,7 @@ import com.infendro.cli.util.Regex
 
 sealed class Command private constructor(
     val name: String,
+    val description: String?,
     val commands: List<Command>,
     val arguments: List<Argument<*>>,
     val options: List<Option<*>>,
@@ -28,32 +29,33 @@ sealed class Command private constructor(
             is ContextParser.Result.Success -> result.context.execute()
             is ContextParser.Result.Help -> {
                 val command = result.path.last()
-                command.renderer.render(result.path)?.let { print(it) }
+                val help = command.renderer.render(result.path)
+                if (help != null) print(help)
             }
             is ContextParser.Result.Failure -> {
                 println("error: ${result.failure.message}")
                 val command = result.path.last()
-                command.renderer.render(result.path)?.let {
+                val help = command.renderer.render(result.path)
-                    println()
+                if (help != null) print("\n$help")
-                    print(it)
-                }
             }
         }
     }
 
     class Named(
         name: String,
+        description: String?,
         commands: List<Command>,
         arguments: List<Argument<*>>,
         options: List<Option<*>>,
         execute: Context.() -> Unit,
         renderer: HelpRenderer,
-    ) : Command(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(name, commands, arguments, options, execute, renderer)
+                Named(name, description, commands, arguments, options, execute, renderer)
         }
     }
 
@@ -61,20 +63,22 @@ sealed class Command private constructor(
         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, 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(key, parser, name, commands, arguments, options, execute, renderer)
+                Fallback(key, parser, name, description, commands, arguments, options, execute, renderer)
         }
 
         class Key<T>
@@ -83,6 +87,7 @@ sealed class Command private constructor(
     @Dsl
     sealed class Builder<COMMAND : Command>(
         protected val name: String,
+        protected val description: String?,
     ) {
         protected val commands = mutableListOf<Command>()
         protected val arguments = mutableListOf<Argument<*>>()

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

@@ -5,35 +5,46 @@ import com.infendro.cli.parser.*
 
 class CommandFactory internal constructor() {
     inner class FallbackFactory internal constructor() {
-        fun string(name: String, block: Builder<*>.(Fallback.Key<String>) -> Unit) =
+        fun string(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<String>) -> Unit) =
-            fallback(StringParser, name, block)
+            fallback(StringParser, name, description, block)
 
-        fun int(name: String, block: Builder<*>.(Fallback.Key<Int>) -> Unit) =
+        fun int(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<Int>) -> Unit) =
-            fallback(IntParser, name, block)
+            fallback(IntParser, name, description, block)
 
-        fun long(name: String, block: Builder<*>.(Fallback.Key<Long>) -> Unit) =
+        fun long(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<Long>) -> Unit) =
-            fallback(LongParser, name, block)
+            fallback(LongParser, name, description, block)
 
-        fun float(name: String, block: Builder<*>.(Fallback.Key<Float>) -> Unit) =
+        fun float(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<Float>) -> Unit) =
-            fallback(FloatParser, name, block)
+            fallback(FloatParser, name, description, block)
 
-        fun double(name: String, block: Builder<*>.(Fallback.Key<Double>) -> Unit) =
+        fun double(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<Double>) -> Unit) =
-            fallback(DoubleParser, name, block)
+            fallback(DoubleParser, name, description, block)
 
-        fun boolean(name: String, block: Builder<*>.(Fallback.Key<Boolean>) -> Unit) =
+        fun boolean(name: String, description: String? = null, block: Builder<*>.(Fallback.Key<Boolean>) -> Unit) =
-            fallback(BooleanParser, name, block)
+            fallback(BooleanParser, name, description, block)
 
-        inline fun <reified T : Enum<T>> enum(name: String, noinline block: Builder<*>.(Fallback.Key<T>) -> Unit) =
+        inline fun <reified T : Enum<T>> enum(
-            fallback(enumParser<T>(), name, block)
+            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, block: Fallback.Builder<T>.(Fallback.Key<T>) -> Unit) =
+    fun <T : Any> fallback(
-        Fallback.Builder(parser, name).apply { block(key) }.build()
+        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, block: Builder<*>.() -> Unit) =
+fun command(
-    Named.Builder(name).apply(block).build()
+    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

@@ -8,6 +8,7 @@ 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?,
 ) {
@@ -34,27 +35,36 @@ sealed class Argument<T : Any>(
     class Required<T : Any>(
         parser: Parser<T>,
         name: String,
-    ) : Argument<T>(parser, name, min = 1, max = 1) {
+        description: String?,
-        fun orElse(other: T) = OrElse(parser, name, other)
+    ) : Argument<T>(parser, name, description, min = 1, max = 1) {
-        fun orNull() = OrNull(parser, name)
+        fun orElse(other: T) =
-        fun variable(min: Int = 0, max: Int? = null) = Variable(parser, name, min, max)
+            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, min = 0, max = 1)
+    ) : Argument<T>(parser, name, description, min = 0, max = 1)
 
     class OrNull<T : Any>(
         parser: Parser<T>,
         name: String,
-    ) : Argument<T>(parser, name, min = 0, max = 1)
+        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, min, max)
+    ) : Argument<T>(parser, name, description, min, max)
 }

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

@@ -3,17 +3,29 @@ package com.infendro.cli.command.argument
 import com.infendro.cli.parser.*
 
 object ArgumentFactory {
-    fun string(name: String) = argument(StringParser, name)
+    fun string(name: String, description: String? = null) =
-    fun int(name: String) = argument(IntParser, name)
+        argument(StringParser, name, description)
-    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)
+    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) =
+fun <T : Any> argument(parser: Parser<T>, name: String, description: String? = null) =
-    Argument.Required(parser, name)
+    Argument.Required(parser, name, description)

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

@@ -10,6 +10,10 @@ object DefaultHelpRenderer : HelpRenderer {
         val command = path.last()
 
         usage(path)
+        if (command.description != null) {
+            appendLine()
+            appendLine(command.description)
+        }
         if (command.commands.isNotEmpty()) {
             appendLine()
             commands(command.commands)
@@ -70,37 +74,66 @@ object DefaultHelpRenderer : HelpRenderer {
     }
 
     private fun StringBuilder.commands(commands: List<Command>) {
-        appendLine("Commands:")
+        val rows = commands.map { command ->
-        for (command in commands) {
             val name = when {
-                command is Command.Fallback<*> -> {
+                command is Command.Fallback<*> -> "<${command.name}>"
-                    val name = command.name
-                    val type = command.parser.type.name
-                    "<$name> ($type)"
-                }
                 else -> command.name
             }
-            appendLine("  * $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<*>>) {
-        appendLine("Arguments:")
+        val rows = arguments.map { argument ->
-        for (argument in arguments) {
             val name = argument.name
             val type = argument.parser.type.name
-            val range = renderRangeFull(argument.min, argument.max)
+            val range = renderRange(argument.min, argument.max)
-            appendLine("  * $name ($type, $range)")
+            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<*>>) {
-        appendLine("Options:")
+        val rows = options.map { option ->
-        for (option in options) {
             val name = option.names.joinToString(" | ") { it.withPrefix() }
             val type = option.parser.type.name
-            val range = renderRangeFull(option.min, option.max)
+            val range = renderRange(option.min, option.max)
-            appendLine("  * $name ($type, $range)")
+            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 ?: ""}")
         }
     }
 
@@ -127,4 +160,30 @@ object DefaultHelpRenderer : HelpRenderer {
             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/NoOpHelpRenderer.kt

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

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

@@ -10,6 +10,7 @@ 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?,
 ) {
@@ -44,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) {
+        description: String?,
-        constructor(
+    ) : Option<T>(parser, fallback, names, description, min = 1, max = 1) {
-            parser: Parser<T>,
+        fun orElse(other: T) =
-            names: List<String>,
+            OrElse(parser, fallback, names, description, other)
-        ) : this(parser, null, names)
 
-        fun orElse(other: T) = OrElse(parser, fallback, names, other)
+        fun orNull() =
-        fun orNull() = OrNull(parser, fallback, names)
+            OrNull(parser, fallback, names, description)
-        fun variable(min: Int = 0, max: Int? = null) = Variable(parser, fallback, names, min, max)
+
+        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) {
+    ) : Option<T>(parser, fallback, names, description, min = 0, max = 1)
-        constructor(
-            parser: Parser<T>,
-            names: List<String>,
-            other: T,
-        ) : this(parser, null, names, other)
-    }
 
     class OrNull<T : Any>(
         parser: Parser<T>,
         fallback: T?,
         names: List<String>,
-    ) : Option<T>(parser, fallback, names, min = 0, max = 1) {
+        description: String?,
-        constructor(
+    ) : Option<T>(parser, fallback, names, description, min = 0, max = 1)
-            parser: Parser<T>,
-            names: List<String>,
-        ) : this(parser, null, names)
-    }
 
     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) {
+    ) : Option<T>(parser, fallback, names, description, min, max)
-        constructor(
-            parser: Parser<T>,
-            names: List<String>,
-            min: Int,
-            max: Int?,
-        ) : this(parser, null, names, min, max)
-    }
 }

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

@@ -3,20 +3,32 @@ package com.infendro.cli.command.option
 import com.infendro.cli.parser.*
 
 object OptionFactory {
-    fun string(vararg names: String) = option(StringParser, *names)
+    fun string(vararg names: String, description: String? = null) =
-    fun int(vararg names: String) = option(IntParser, *names)
+        option(StringParser, *names, description = description)
-    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, fallback = true, *names)
 
-    inline fun <reified T : Enum<T>> enum(vararg names: String) = option(enumParser<T>(), *names)
+    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) =
+fun <T : Any> option(parser: Parser<T>, vararg names: String, description: String? = null) =
-    Option.Required(parser, names.asList())
+    Option.Required(parser, fallback = null, names.asList(), description)
 
-fun <T : Any> option(parser: Parser<T>, fallback: T, vararg names: String) =
+fun <T : Any> option(parser: Parser<T>, fallback: T, vararg names: String, description: String? = null) =
-    Option.Required(parser, fallback, names.asList())
+    Option.Required(parser, fallback, names.asList(), description)