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

CliktCommand

abstract class CliktCommand

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.

Constructors

<init>

CliktCommand(help: String = "", epilog: String = "", name: String? = null, invokeWithoutSubcommand: Boolean = false)

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

Properties

commandHelp

val commandHelp: String

commandHelpEpilog

val commandHelpEpilog: String

commandName

val commandName: String

context

val context: Context

This command's context.

invokeWithoutSubcommand

val invokeWithoutSubcommand: Boolean

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.

Functions

aliases

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

A list of command aliases.

echo

fun echo(message: Any?, trailingNewline: Boolean = true, err: Boolean = false): Unit

Print the message to the screen.

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.

main

fun main(argv: List<String>): Unit

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

fun main(argv: Array<String>): Unit

parse

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

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

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

registerArgument

fun registerArgument(argument: Argument): Unit

Register an argument with this command.

registerOption

fun registerOption(option: Option): Unit

Register an option with this command.

registeredSubcommandNames

fun registeredSubcommandNames(): List<String>

The names of all direct children of this command

run

abstract fun run(): Unit

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

shortHelp

fun shortHelp(): String

The help displayed in the commands list when this command is used as a subcommand.

Extension Functions

argument

fun CliktCommand.argument(name: String = "", help: String = ""): RawArgument

Create a property delegate argument.

context

fun <T : CliktCommand> T.context(block: Builder.() -> Unit): T

Configure this command's Context.

findObject

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

Find the closest object of type T, or null

fun <T : Any> CliktCommand.findObject(default: () -> T): ReadOnlyProperty<CliktCommand, T>

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

option

fun CliktCommand.option(vararg names: String, help: String = "", metavar: String? = null, hidden: Boolean = false, envvar: String? = null): RawOption

Create a property delegate option.

requireObject

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

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

subcommands

fun <T : CliktCommand> T.subcommands(commands: Iterable<CliktCommand>): T
fun <T : CliktCommand> T.subcommands(vararg commands: CliktCommand): T

Add the given commands as a subcommand of this command.

versionOption

fun <T : CliktCommand> T.versionOption(version: String, help: String = "Show the version and exit.", names: Set<String> = setOf("--version"), message: (String) -> String = { "$commandName version $it" }): T

Add an eager option to this command that, when invoked, prints a version message and exits.

Inheritors

NoRunCliktCommand

open class NoRunCliktCommand : CliktCommand

A CliktCommand that has a default implementation of CliktCommand.run that is a no-op.