class

Cling::Command

Inherits Reference < Object

Constructors

new(*, aliases : Set(String) | Nil = nil, usage : Array(String) | Nil = nil, header : String | Nil = nil, summary : String | Nil = nil, description : String | Nil = nil, footer : String | Nil = nil, parent : Command | Nil = nil, children : Array(Command) | Nil = nil, arguments : Hash(String, Argument) | Nil = nil, options : Hash(String, Option) | Nil = nil, hidden : Bool = false, inherit_borders : Bool = false, inherit_options : Bool = false, inherit_streams : Bool = false, stdin : IO = STDIN, stdout : IO = STDOUT, stderr : IO = STDERR)

Instance methods

add_alias(name : String) : Nil

Adds an alias to the command.

add_aliases(*names : String) : Nil

Adds several aliases to the command.

add_argument(name : String, *, description : String | Nil = nil, required : Bool = false, multiple : Bool = false, hidden : Bool = false) : Nil

Adds an argument to the command.

add_command(command : Command) : Nil

Adds a command as a subcommand to the parent. The command can then be referenced by specifying it as the first argument in the command line.

add_commands(*commands : Command) : Nil

Adds several commands as subcommands to the parent (see add_command).

add_option(short : Char, long : String, *, description : String | Nil = nil, required : Bool = false, hidden : Bool = false, type : Option::Type = :none, default : Value::Type = nil) : Nil

Adds a short flag option to the command.

add_option(long : String, *, description : String | Nil = nil, required : Bool = false, hidden : Bool = false, type : Option::Type = :none, default : Value::Type = nil) : Nil

Adds a long flag option to the command.

add_usage(usage : String) : Nil

Adds a usage string to the command.

aliases

A set of aliases for the command.

arguments

A hash of arguments belonging to the command. These arguments are parsed at execution time and can be accessed in the pre_run, run, and post_run methods via ArgumentsInput.

children

A hash of commands that belong and inherit from the parent command.

description

The description of the command to show for specific help with the command.

description=(description : String | Nil)

The description of the command to show for specific help with the command.

execute(input : String | Array(String), *, parser : Parser | Nil = nil, terminate : Bool = true) : Int32

Executes the command with the given input and parser (see Parser). Returns the program exit status code, by default it is 0.

exit_program(code : Int32 = 1) : NoReturn

Raises an ExitProgram exception to exit the program. By default it is 1.

header

A header message to display at the top of generated help templates.

help_template

Returns the help template for this command. By default, one is generated interally unless this method is overridden.

hidden=(hidden : Bool)

Whether the command should be hidden from generated help templates.

hidden?

Whether the command should be hidden from generated help templates.

inherit_borders=(inherit_borders : Bool)

Whether the command should inherit the header and footer strings from the parent command.

inherit_borders?

Whether the command should inherit the header and footer strings from the parent command.

inherit_options=(inherit_options : Bool)

Whether the command should inherit the options from the parent command.

inherit_options?

Whether the command should inherit the options from the parent command.

inherit_streams=(inherit_streams : Bool)

Whether the command should inherit the IO streams from the parent command.

inherit_streams?

Whether the command should inherit the IO streams from the parent command.

is?(name : String) : Bool

Returns true if the argument matches the command name or any aliases.

name

The name of the command. This is the only required field of a command and cannot be empty or blank.

name=(name : String)

The name of the command. This is the only required field of a command and cannot be empty or blank.

on_error(ex : Exception)

A hook method for when the command raises an exception during execution. By default, this raises the exception.

on_invalid_option(message : String)

A hook method for when the command receives an invalid option, for example, a value given to an option that takes no arguments. By default, this raises a CommandError.

on_missing_arguments(arguments : Array(String))

A hook method for when the command receives missing arguments during execution. By default, this raises a CommandError.

on_missing_options(options : Array(String))

A hook method for when the command receives missing options that are required during execution. By default, this raises an CommandError.

on_unknown_arguments(arguments : Array(String))

A hook method for when the command receives unknown arguments during execution. By default, this raises a CommandError.

on_unknown_options(options : Array(String))

A hook method for when the command receives unknown options during execution. By default, this raises an CommandError.

options

A hash of flag options belonging to the command. These options are parsed at execution time and can be accessed in the pre_run, run, and post_run methods via OptionsInput.

parent

The parent of the command of which the current command inherits from.

parent=(parent : Command | Nil)

The parent of the command of which the current command inherits from.

post_run(arguments : Arguments, options : Options) : Nil

A hook method to run once the pre_run and main run methods have been executed.

pre_run(arguments : Arguments, options : Options) : Bool | Nil

A hook method to run once the command/subcommands, arguments and options have been parsed. This has access to the parsed arguments and options from the command line. This is useful if you want to implement checks for specific flags outside of the main run method, such as -v/--version flags or -h/--help flags.

run(arguments : Arguments, options : Options) : Nil

The main point of execution for the command, where arguments and options can be accessed.

setup

An abstract method that should define information about the command such as the name, aliases, arguments, options, etc. The command name is required for all commands, all other values are optional including the help message.

stderr

The standard error stream for commands (defaults to STDERR). This is a helper method for custom commands and is only used by the MainCommand helper class.

stderr=(stderr : IO)

The standard error stream for commands (defaults to STDERR). This is a helper method for custom commands and is only used by the MainCommand helper class.

stdin

The standard input stream for commands (defaults to STDIN). This is a helper method for custom commands and is only used by the MainCommand helper class.

stdin=(stdin : IO)

The standard input stream for commands (defaults to STDIN). This is a helper method for custom commands and is only used by the MainCommand helper class.

stdout

The standard output stream for commands (defaults to STDOUT). This is a helper method for custom commands and is only used by the MainCommand helper class.

stdout=(stdout : IO)

The standard output stream for commands (defaults to STDOUT). This is a helper method for custom commands and is only used by the MainCommand helper class.

summary

The summary of the command to show in generated help templates.

summary=(summary : String | Nil)

The summary of the command to show in generated help templates.

usage

An array of usage strings to display in generated help templates.