Exception Handling¶
Clikt uses exceptions internally to signal that processing has ended early for any reason. This includes incorrect command line usage, or printing a help page.
Where are Exceptions Handled?¶
When you call CliktCommand.main
, it will parse the command line and catch any
CliktError
exceptions. If it catches one, it will then print out the error’s message
and exit the process with the error’s statusCode
. The message is printed to stderr or stdout
depending on the error’s printError
property.
For exceptions raised by Clikt, PrintMessage
and
PrintHelpMessage
have a statusCode
of 0 and print to stdout. Other
exceptions have a statusCode
of 1 and print to stderr.
Any other types of exceptions indicate a programming error, and are not caught by main
.
However, convert
and the other parameter transformations will wrap exceptions thrown
inside them in a UsageError
, so if you define a custom transformation,
you don’t have to worry about an exception escaping to the user.
Handling Exceptions Manually¶
CliktCommand.main
is just a try
/catch
block surrounding
CliktCommand.parse
, so if you don’t want exceptions to be caught,
you can call parse
wherever you would normally call main
.
Tip
You can use echoFormattedHelp to print the help or error message to any exception, or getFormattedHelp to get the help message as a string.
fun main(args: Array<String>) {
val cli = Cli()
try {
cli.parse(args)
} catch (e: CliktError) {
cli.echoFormattedHelp(e)
exitProcess(e.statusCode)
}
}
Which Exceptions Exist?¶
All exceptions thrown by Clikt are subclasses of CliktError
.
The following subclasses exist:
Abort
: The command should exit immediately with the givenstatusCode
without printing any messages.PrintMessage
: The exception’s message should be printed.PrintHelpMessage
: The help page for the exception’s command should be printed.PrintCompletionMessage
: Shell completion code for the command should be printed.UsageError
: The command line was incorrect in some way. All the following exceptions subclass from this. These exceptions are automatically augmented with extra information about the current parameter, if possible.MultiUsageError
: MultipleUsageError
s occurred. Theerrors
property contains the list of the errors.ProgramResult
: The program should exit with thestatusCode
from this exception.BadParameterValue
: A parameter was given the correct number of values, but of invalid format or type.MissingOption
andMissingArgument
: A required parameter was not provided.NoSuchOption
: An option was provided that does not exist.NoSuchSubcommand
: A subcommand was called that does not exist.IncorrectOptionValueCount
: An option was supplied but the number of values supplied to the option was incorrect.IncorrectArgumentValueCount
: An argument was supplied but the number of values supplied was incorrect.MutuallyExclusiveGroupException
: Multiple options in a mutually exclusive group were supplied when the group is restricted to a single value.FileNotFound
: A required configuration file or @-file was not found.InvalidFileFormat
: A configuration file or @-file failed to parse correctly.