Rename commandHelp -> help

Author: ajalt

CHANGELOG.md

@@ -12,7 +12,7 @@
 - In a subcommand with `argument().multiple()`, the behavior is now the same regardless of the value of `allowMultipleSubcommands`: if a token matches a subcommand name, it's now treated as a subcommand rather than a positional argument.
 - Due to changes to the internal parsing algorithm, the exact details of error messages when multiple usage errors occur have changed in some cases.
 - **Breaking Change:** Removed the following parameters from `CliktCommand`'s constructor; override the corresponding properties instead:
-  
+
   | removed parameter           | replacement property            |
   |-----------------------------|---------------------------------|
   | `help`                      | `fun commandHelp`               |
@@ -23,7 +23,8 @@
   | `autoCompleteEnvvar`        | `val autoCompleteEnvvar`        |
   | `allowMultipleSubcommands`  | `val allowMultipleSubcommands`  |
   | `treatUnknownOptionsAsArgs` | `val treatUnknownOptionsAsArgs` |
-  | `hidden`                    | `val hidden`                    |
+  | `hidden`                    | `val hiddenFromHelp`            |
+- The following methods on `CliktCommand` have been renamed: `commandHelp` -> `help`, `commandHelpEpilog` -> `epilog`. The old names are deprecated.
 
 ### Fixed
 - Fixed excess arguments not being reported when `allowMultipleSubcommands=true` and a subcommand has excess arguments followed by another subcommand.

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/CompletionBuiltins.kt

@@ -34,8 +34,8 @@ class CompletionCommand(
     private val epilog: String = "",
     name: String = "generate-completion",
 ) : CliktCommand(name) {
-    override fun commandHelp(context: Context): String = help
-    override fun commandHelpEpilog(context: Context): String = epilog
+    override fun help(context: Context): String = help
+    override fun helpEpilog(context: Context): String = epilog
     private val shell by argument("shell").choice(*choices)
     override fun run() {
         val cmd = currentContext.parent?.command ?: this

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/completion/FishCompletionGenerator.kt

@@ -2,7 +2,6 @@ package com.github.ajalt.clikt.completion
 
 import com.github.ajalt.clikt.completion.CompletionCandidates.Custom.ShellType
 import com.github.ajalt.clikt.core.BaseCliktCommand
-import com.github.ajalt.clikt.core.CliktCommand
 import com.github.ajalt.clikt.parameters.options.Option
 
 internal object FishCompletionGenerator {
@@ -57,7 +56,7 @@ internal object FishCompletionGenerator {
 
             append("-a $commandName ")
 
-            val help = command.commandHelp(command.currentContext).replace("'", "\\'")
+            val help = command.help(command.currentContext).replace("'", "\\'")
             if (help.isNotBlank()) {
                 append("-d '${help}'")
             }

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/BaseCliktCommand.kt

@@ -22,7 +22,6 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
      */
     name: String? = null,
 ) : ParameterHolder {
-    // TODO: rename commandName commandHelp commandHelpEpilog?
     /**
      * The name of this command, used in help output.
      *
@@ -43,15 +42,18 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
      * }
      * ```
      */
-    open fun commandHelp(context: Context): String = ""
+    open fun help(context: Context): String = ""
+
+    @Deprecated("Method renamed to `help`", ReplaceWith("help(context)"))
+    open fun commandHelp(context: Context): String = help(context)
 
     /**
      * Help text to display at the end of the help output, after any parameters.
-     *
-     * You can set this by passing `epilog` to the [CliktCommand] constructor, or by overriding this
-     * method.
      */
-    open fun commandHelpEpilog(context: Context): String = ""
+    open fun helpEpilog(context: Context): String = ""
+
+    @Deprecated("Method renamed to `helpEpilog`", ReplaceWith("helpEpilog(context)"))
+    open fun commandHelpEpilog(context: Context): String = helpEpilog(context)
 
     /**
      * Used when this command has subcommands, and this command is called without a subcommand. If
@@ -93,7 +95,7 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
     /**
      * If true, don't display this command in help output when used as a subcommand.
      */
-    open val hidden: Boolean = false
+    open val hiddenFromHelp: Boolean = false
 
     // TODO: make these all private?
     internal var _subcommands: List<T> = emptyList()
@@ -154,7 +156,7 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
                     c.commandName,
                     c.shortHelp(currentContext),
                     c.helpTags
-                ).takeUnless { c.hidden }
+                ).takeUnless { c.hiddenFromHelp }
             }
         ).flatten()
     }
@@ -185,7 +187,7 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
 
     /** The help displayed in the commands list when this command is used as a subcommand. */
     protected fun shortHelp(context: Context): String =
-        Regex("""\s*(?:```)?\s*(.+)""").find(commandHelp(context))?.groups?.get(1)?.value ?: ""
+        Regex("""\s*(?:```)?\s*(.+)""").find(help(context))?.groups?.get(1)?.value ?: ""
 
     /** The names of all direct children of this command */
     fun registeredSubcommandNames(): List<String> = _subcommands.map { it.commandName }
@@ -279,8 +281,8 @@ abstract class BaseCliktCommand<T : BaseCliktCommand<T>>(
         val programName = cmd.getCommandNameWithParents()
         return ctx.helpFormatter(ctx).formatHelp(
             error as? UsageError,
-            cmd.commandHelp(ctx),
-            cmd.commandHelpEpilog(ctx),
+            cmd.help(ctx),
+            cmd.helpEpilog(ctx),
             cmd.allHelpParams(),
             programName
         )

clikt/src/commonTest/kotlin/com/github/ajalt/clikt/output/MordantHelpFormatterTest.kt

@@ -444,7 +444,7 @@ class MordantHelpFormatterTest {
             TestCommand(name = "foo", help = "some thing to live by"),
             TestCommand(name = "bar", help = "another argument"),
             TestCommand(name = "baz"),
-            TestCommand(name = "qux", hidden = true),
+            TestCommand(name = "qux", hiddenFromHelp = true),
         )
         doTest(
             """
@@ -778,10 +778,10 @@ class MordantHelpFormatterTest {
         }
 
         class C: TestCommand(name="prog") {
-            override fun commandHelp(context: Context): String =
+            override fun help(context: Context): String =
                 context.theme.danger("command help")
 
-            override fun commandHelpEpilog(context: Context): String =
+            override fun helpEpilog(context: Context): String =
                 context.theme.danger("command epilog")
 
             val o by option("--aa", "-a")

clikt/src/commonTest/kotlin/com/github/ajalt/clikt/testing/TestCommand.kt

@@ -20,7 +20,7 @@ open class TestCommand(
     override val autoCompleteEnvvar: String? = "",
     override val allowMultipleSubcommands: Boolean = false,
     override val treatUnknownOptionsAsArgs: Boolean = false,
-    override val hidden: Boolean = false,
+    override val hiddenFromHelp: Boolean = false,
     noHelp: Boolean = false,
 ) : CliktCommand(name) {
     init {
@@ -30,9 +30,9 @@ open class TestCommand(
         }
     }
 
-    override fun commandHelp(context: Context): String = help
+    override fun help(context: Context): String = help
 
-    override fun commandHelpEpilog(context: Context): String = epilog
+    override fun helpEpilog(context: Context): String = epilog
 
     private val count = count ?: if (called) 1 else 0
     private var actualCount = 0

docs/commands.md

@@ -101,12 +101,14 @@ command names.
 
 === "Example"
     ```kotlin
-    class Tool : CliktCommand(help = "A tool that runs") {
+    class Tool : CliktCommand() {
+        override fun help(context: Context) = "A tool that runs"
         val verbose by option().flag("--no-verbose")
         override fun run() = Unit
     }
 
-    class Execute : CliktCommand(help = "Execute the command") {
+    class Execute : CliktCommand() {
+        override fun help(context: Context) = "Execute the command"
         val name by option()
         override fun run() = Unit
     }
@@ -252,7 +254,7 @@ is about to be invoked, if there is one.
             if (subcommand == null) {
                 echo("invoked without a subcommand")
             } else {
-                echo("about to run ${subcommand.commandName}")
+                echo("about to run ${subcommand.name}")
             }
         }
     }

docs/documenting.md

@@ -7,43 +7,40 @@ and set it on the [command's context][customizing-contexts].
 
 ## Help Texts
 
-[Commands][Commands] and parameters accept a `help` argument. Commands also accept an `epilog`
-argument, which is printed after the parameters and commands on the help page. All text is
-automatically trimmed of leading indentation and re-wrapped to the terminal width.
-
-As an alternative to passing your help strings as function arguments, you can also use the `help()`
-extensions for your options, and override `commandHelp` and `commandHelpEpilog` on your commands.
-These methods can access the terminal theme on the context to add color to your help text.
+You can add help text to commands and parameters. For parameters, you can pass a `help` string or 
+use the `help()` extension. For commands, you can override the `help` and `helpEpilog` methods.
 
 === "Example"
     ```kotlin
-    class Hello : CliktCommand(help = """
+    class Hello : CliktCommand() {
+        override fun help(context: Context) = """
         This script prints <name> <count> times.
-
+    
         <count> must be a positive number, and defaults to 1.
-        """
-    ) {
-        val count by option("-c", "--count", metavar="count", help = "number of greetings").int().default(1)
-        val name by argument()
-        override fun run() = repeat(count) { echo("Hello $name!") }
+        """.trimIndent()
+        val count by option("-c", "--count", metavar="count", help="number of greetings")
+            .int().default(1)
+        val name by argument(help="The name to greet")
+        override fun run() = repeat(count) { echo("Hello $commandName!") }
     }
     ```
 
 === "Alternate style"
     ```kotlin
     class Hello : CliktCommand() {
-        override fun commandHelp(context: Context): String {
+        override fun help(context: Context): String {
             val style = context.theme.info
             return """
-                This script prints ${style("<name>")} ${style("<count>")} times.
+            This script prints ${style("<name>")} ${style("<count>")} times.
 
-                ${style("<count>")} must be a positive number, and defaults to 1.
+            ${style("<count>")} must be a positive number, and defaults to 1.
             """.trimIndent()
         }
 
         val count by option("-c", "--count", metavar="count").int().default(1)
             .help { theme.success("number of greetings") }
         val name by argument()
+            .help("The name to greet")
         override fun run() = repeat(count) { echo("Hello $name!") }
     }
     ```
@@ -158,13 +155,17 @@ They have a short help string which is the first line of their help.
     ```kotlin
     class Tool : NoOpCliktCommand()
 
-    class Execute : NoOpCliktCommand(help = """
-        Execute the command.
+    class Execute : NoOpCliktCommand() {
+        override fun help(context: Context) = """
+            Execute the command.
 
-        The command will be executed.
-        """)
+            The command will be executed.
+            """.trimIndent()
+    }
 
-    class Abort : NoOpCliktCommand(help="Kill any running commands.")
+    class Abort : NoOpCliktCommand() {
+        override fun help(context: Context) = "Kill any running commands."
+    }
     ```
 
 === "Usage"
@@ -463,10 +464,9 @@ You can localize error messages by implementing [`Localization`][Localization] a
         // ... override the rest of the strings here
     }
 
-    class I18NTool : NoOpCliktCommand(help = "𝒯𝒽𝒾𝓈 𝓉𝑜𝑜𝓁 𝒾𝓈 𝒾𝓃 𝒸𝓊𝓇𝓈𝒾𝓋𝑒") {
-        init {
-            context { localization = CursiveLocalization() }
-        }
+    class I18NTool : NoOpCliktCommand() {
+        override fun help(context: Context) = "𝒯𝒽𝒾𝓈 𝓉𝑜𝑜𝓁 𝒾𝓈 𝒾𝓃 𝒸𝓊𝓇𝓈𝒾𝓋𝑒"
+        init { context { localization = CursiveLocalization() } }
     }
     ```
 

docs/options.md

@@ -868,7 +868,7 @@ You can define your own version option like this:
 class Cli : NoOpCliktCommand() {
     init {
         eagerOption("--version") {
-            throw PrintMessage("$commandName version 1.0")
+            throw PrintMessage("$name version 1.0")
         }
     }
 }

samples/aliases/src/main/kotlin/com/github/ajalt/clikt/samples/aliases/main.kt

@@ -11,7 +11,7 @@ import java.io.File
  *   have multiple tokens (e.g. `cm = commit -m`).
  */
 class AliasedCli(private val configFile: File) : NoOpCliktCommand() {
-    override fun commandHelp(context: Context) = "An example that supports aliased subcommands"
+    override fun help(context: Context) = "An example that supports aliased subcommands"
     override fun aliases(): Map<String, List<String>> {
         return configFile.readLines().map { it.split("=", limit = 2) }
             .associate { it[0].trim() to it[1].trim().split(Regex("\\s+")) }
@@ -20,22 +20,22 @@ class AliasedCli(private val configFile: File) : NoOpCliktCommand() {
 
 
 class Push : CliktCommand() {
-    override fun commandHelp(context: Context) = "push changes"
+    override fun help(context: Context) = "push changes"
     override fun run() = echo("push")
 }
 
 class Pull : CliktCommand() {
-    override fun commandHelp(context: Context) = "pull changes"
+    override fun help(context: Context) = "pull changes"
     override fun run() = echo("pull")
 }
 
 class Clone : CliktCommand() {
-    override fun commandHelp(context: Context) = "clone a repository"
+    override fun help(context: Context) = "clone a repository"
     override fun run() = echo("clone")
 }
 
 class Commit : CliktCommand() {
-    override fun commandHelp(context: Context) = "clone a repository"
+    override fun help(context: Context) = "clone a repository"
     val message by option("-m", "--message").multiple()
     override fun run() = echo("commit message=${message.joinToString("\n")}")
 }