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
and Abort
exceptions. If it catches one, it will then print
out the appropriate information and exit the process. If the caught exception is a
PrintMessage
or PrintHelpMessage
, the process exit status
will be 0 and the message will be printed to stdout. Otherwise it will exit with status 1 and print
the message 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 don’t want exceptions to be caught,
you can call parse
wherever you would normally call main
.
fun main(args: Array<String>) = Cli().parse(args)
Which Exceptions Exist?¶
Clikt will throw Abort
if it needs to halt execution immediately without a specific
message. All other exceptions are subclasses of UsageError
.
The following subclasses exist:
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 other exceptions subclass from this. These exceptions are automatically augmented with extra information about the current parameter, if possible.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.