clikt/com.github.ajalt.clikt.core/CliktCommand

CliktCommand

abstract class CliktCommand(help: String = "", epilog: String = "", name: String? = null, val invokeWithoutSubcommand: Boolean = false, val printHelpOnEmptyArgs: Boolean = false, val helpTags: Map<String, String> = emptyMap(), autoCompleteEnvvar: String? = "", allowMultipleSubcommands: Boolean = false, treatUnknownOptionsAsArgs: Boolean = false, hidden: Boolean = false) : ParameterHolder

The CliktCommand is the core of command line interfaces in Clikt.

Command line interfaces created by creating a subclass of CliktCommand with properties defined with option and argument. You can then parse argv by calling main, which will take care of printing errors and help to the user. If you want to handle output yourself, you can use parse instead.

Once the command line has been parsed and all of the parameters are populated, run is called.

Parameters

help

The help for this command. The first line is used in the usage string, and the entire string is used in the help output. Paragraphs are automatically re-wrapped to the terminal width.

epilog

Text to display at the end of the full help output. It is automatically re-wrapped to the terminal width.

name

The name of the program to use in the help output. If not given, it is inferred from the class name.

invokeWithoutSubcommand

Used when this command has subcommands, and this command is called without a subcommand. If true, run will be called. By default, a PrintHelpMessage is thrown instead.

printHelpOnEmptyArgs

If this command is called with no values on the command line, print a help message (by throwing PrintHelpMessage) if this is true, otherwise run normally.

helpTags

Extra information about this option to pass to the help formatter.

autoCompleteEnvvar

The envvar to use to enable shell autocomplete script generation. Set to null to disable generation.

allowMultipleSubcommands

If true, allow multiple of this command's subcommands to be called sequentially. This will disable allowInterspersedArgs on the context of this command an its descendants. This functionality is experimental, and may change in a future release.

treatUnknownOptionsAsArgs

If true, any options on the command line whose names aren't valid will be parsed as an argument rather than reporting an error. You'll need to define an argument().multiple() to collect these options, or an error will still be reported. Unknown short option flags grouped with other flags on the command line will always be reported as errors.

hidden

If true, don't display this command in help output when used as a subcommand.

Constructors

CliktCommand

fun CliktCommand(help: String = "", epilog: String = "", name: String? = null, invokeWithoutSubcommand: Boolean = false, printHelpOnEmptyArgs: Boolean = false, helpTags: Map<String, String> = emptyMap(), autoCompleteEnvvar: String? = "", allowMultipleSubcommands: Boolean = false, treatUnknownOptionsAsArgs: Boolean = false, hidden: Boolean = false)

Functions

aliases

open fun aliases(): Map<String, List<String>>

A list of command aliases.

getFormattedHelp

open fun getFormattedHelp(): String

Return the full help string for this command.

getFormattedUsage

open fun getFormattedUsage(): String

Return the usage string for this command.

issueMessage

fun issueMessage(message: String)

Add a message to be printed after parsing

main

fun main(argv: Array<out String>)

fun main(argv: List<String>)

Parse the command line and print helpful output if any errors occur.

parse

fun parse(argv: Array<String>, parentContext: Context? = null)

fun parse(argv: List<String>, parentContext: Context? = null)

Parse the command line and throw an exception if parsing fails.

registerArgument

fun registerArgument(argument: Argument)

registeredArguments

fun registeredArguments(): List<Argument>

Get a read-only list of arguments registered in this command (e.g. via registerArgument or an argument delegate)

registeredOptions

fun registeredOptions(): List<Option>

Get a read-only list of options registered in this command (e.g. via registerOption or an option delegate)

registeredParameterGroups

fun registeredParameterGroups(): List<ParameterGroup>

Get a read-only list of groups registered in this command (e.g. via registerOptionGroup or an OptionGroup delegate)

registeredSubcommandNames

fun registeredSubcommandNames(): List<String>

The names of all direct children of this command

registeredSubcommands

fun registeredSubcommands(): List<CliktCommand>

Get a read-only list of commands registered as subcommands of this command.

registerOption

open override fun registerOption(option: GroupableOption)

fun registerOption(option: Option)

registerOptionGroup

fun registerOptionGroup(group: ParameterGroup)

run

abstract fun run()

Perform actions after parsing is complete and this command is invoked.

toString

open override fun toString(): String

Properties

commandHelp

open val commandHelp: String

The help text for this command.

commandHelpEpilog

open val commandHelpEpilog: String

Help text to display at the end of the help output, after any parameters.

commandName

val commandName: String

The name of this command, used in help output.

currentContext

val currentContext: Context

This command's context.

helpTags

val helpTags: Map<String, String>

invokeWithoutSubcommand

val invokeWithoutSubcommand: Boolean = false

messages

val messages: List<String>

All messages issued during parsing.

printHelpOnEmptyArgs

val printHelpOnEmptyArgs: Boolean = false

Inheritors

CompletionCommand

NoOpCliktCommand

Extensions

argument

fun CliktCommand.argument(name: String = "", help: String = "", helpTags: Map<String, String> = emptyMap(), completionCandidates: CompletionCandidates? = null): RawArgument

Create a property delegate argument.

findObject

inline fun <T : Any> CliktCommand.findObject(): ReadOnlyProperty<CliktCommand, T?>

Find the closest object of type T, or null

findOrSetObject

inline fun <T : Any> CliktCommand.findOrSetObject(crossinline default: () -> T): ReadOnlyProperty<CliktCommand, T>

Find the closest object of type T, setting context.obj if one is not found.

mutuallyExclusiveOptions

fun <T : Any> ParameterHolder.mutuallyExclusiveOptions(option1: OptionDelegate<out T?>, option2: OptionDelegate<out T?>, vararg options: OptionDelegate<out T?>, name: String? = null, help: String? = null): MutuallyExclusiveOptions<T, T?>

Declare a set of two or more mutually exclusive options.

option

fun ParameterHolder.option(vararg names: String, help: String = "", metavar: String? = null, hidden: Boolean = false, envvar: String? = null, helpTags: Map<String, String> = emptyMap(), completionCandidates: CompletionCandidates? = null, valueSourceKey: String? = null): RawOption

Create a property delegate option.

requireObject

inline fun <T : Any> CliktCommand.requireObject(): ReadOnlyProperty<CliktCommand, T>

Find the closest object of type T, or throw a NullPointerException