Support custom exit codes (#156)

CHANGELOG.md

@@ -1,6 +1,8 @@
 # Changelog
 
 ## [Unreleased]
+### Added
+- Ability to use custom program exit status codes via `ProgramResult`.
 
 ## [2.6.0] - 2020-03-15
 ### Added

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

@@ -265,6 +265,8 @@ abstract class CliktCommand(
     fun main(argv: List<String>) {
         try {
             parse(argv)
+        } catch (e: ProgramResult) {
+            exitProcessMpp(e.statusCode)
         } catch (e: PrintHelpMessage) {
             echo(e.command.getFormattedHelp())
             exitProcessMpp(0)

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

@@ -33,6 +33,11 @@ class PrintHelpMessage(val command: CliktCommand) : CliktError()
  */
 open class PrintMessage(message: String) : CliktError(message)
 
+/**
+ * Indicate that that the program finished in a controlled manner, and should complete with the given [statusCode]
+ */
+class ProgramResult(val statusCode: Int): CliktError()
+
 /**
  * An exception that indicates that shell completion code should be printed.
  *

docs/advanced.md

@@ -208,6 +208,19 @@ line. In unit tests, you should instead call [`CliktCommand.parse`][parse], whic
 with error details rather than printing the details and exiting the process. See the documentation
 on [exceptions](exceptions.md) for more information.
 
+## Custom exit status codes
+
+Clikt will normally exit your program with a status code of 0 for a normal execution, or 1 if
+there's an error. If you want to use a different value, you can `throw ProgramResult(statusCode)`.
+If you use [`CliktCommand.main`][main], that exception will be caught and `exitProcess` will be
+called with the value of `statusCode`.
+
+You could also call `exitProcess` yourself, but the [ProgramResult][ProgramResult] has a couple of
+advantages:
+
+- `ProgramResult` is easier to test. Exiting the process makes unit tests difficult to run.
+- `ProgramResult` works on all platforms. `exitProcess` is only available on the JVM.
+
 [aliases]:             api/clikt/com.github.ajalt.clikt.core/-clikt-command/aliases.md
 [tokenTransformer]:    api/clikt/com.github.ajalt.clikt.core/-context/token-transformer.md
 [customizing-context]: commands.md#customizing-contexts
@@ -218,3 +231,5 @@ on [exceptions](exceptions.md) for more information.
 [TermUI]:              api/clikt/com.github.ajalt.clikt.output/-term-ui/index.md
 [dash-dash]:           arguments.md#option-like-arguments-using-
 [expandArgumentFiles]: api/clikt/com.github.ajalt.clikt.core/-context/expand-argument-files.md
+[ProgramResult]:       api/clikt/com.github.ajalt.clikt.core/-program-result/index.md
+

docs/exceptions.md

@@ -39,6 +39,7 @@ The following subclasses exist:
 * [`PrintHelpMessage`][PrintHelpMessage] : The help page for the exception's command should be printed.
 * [`PrintCompletionMessage`][PrintCompletionMessage] : Shell completion code for the command should be printed.
 * [`UsageError`][UsageError] : The command line was incorrect in some way. All other exceptions subclass from this. These exceptions are automatically augmented with extra information about the current parameter, if possible.
+* [`ProgramResult`][ProgramResult] : The program should exit with the `statusCode` from this exception.
 * [`BadParameterValue`][BadParameterValue] : A parameter was given the correct number of values, but of invalid format or type.
 * [`MissingParameter`][MissingParameter] : A required parameter was not provided.
 * [`NoSuchOption`][NoSuchOption] : An option was provided that does not exist.
@@ -56,6 +57,7 @@ The following subclasses exist:
 [PrintMessage]:                    api/clikt/com.github.ajalt.clikt.core/-print-message/index.md
 [PrintHelpMessage]:                api/clikt/com.github.ajalt.clikt.core/-print-help-message/index.md
 [PrintCompletionMessage]:          api/clikt/com.github.ajalt.clikt.core/-print-completion-message/index.md
+[ProgramResult]:                   api/clikt/com.github.ajalt.clikt.core/-program-result/index.md
 [convert]:                         api/clikt/com.github.ajalt.clikt.parameters.options/convert.md
 [UsageError]:                      api/clikt/com.github.ajalt.clikt.core/-usage-error/index.md
 [parse]:                           api/clikt/com.github.ajalt.clikt.core/-clikt-command/parse.md