class

Athena::Console::Application

Inherits Reference / Object

A container for a collection of multiple ACON::Command, and serves as the entry point of a CLI application. This class is optimized for a standard CLI environment; but it may be subclassed to provide a more specialized/customized entry point.

Default Command

The default command represents which command should be executed when no command name is provided; by default this is ACON::Commands::List. For example, running ./console would result in all the available commands being listed. The default command can be customized via #default_command.

Single Command Applications

In some cases a CLI may only have one supported command in which passing the command's name each time is tedious. In such a case an application may be declared as a single command application via the optional second argument to #default_command. Passing true makes it so that any supplied arguments or options are passed to the default command.

WARNING: Arguments and options passed to the default command are ignored when #single_command? is false.

Custom Applications

ACON::Application may also be extended in order to better fit a given application. For example, it could define some [global custom styles][Athena::Console::Formatter::OutputStyleInterface--global-custom-styles], override the array of default commands, or customize the default input options, etc.

Constructors

new(name : String, version : String = "UNKNOWN")

Instance methods

add(command : ACON::Command) : ACON::Command | Nil

Adds the provided command instance to self, allowing it be executed.

auto_exit=(auto_exit : Bool)

By default, the application will auto exit after executing a command. This method can be used to disable that functionality.

If set to false, the ACON::Command::Status of the executed command is returned from #run. Otherwise the #run method never returns.

application = ACON::Application.new "My CLI"
application.auto_exit = false
exit_status = application.run
exit_status # => ACON::Command::Status::SUCCESS

application.auto_exit = true
exit_status = application.run

# This line is never reached.
exit_status

auto_exit?

Returns if application should exit automatically after executing a command. See #auto_exit=.

catch_exceptions=(catch_exceptions : Bool)

By default, the application will gracefully handle exceptions raised as part of the execution of a command by formatting and outputting it; including varying levels of information depending on the ACON::Output::Verbosity level used.

If set to false, that logic is bypassed and the exception is bubbled up to where #run was invoked from.

application = ACON::Application.new "My CLI"

application.register "foo" do |input, output, command|
  output.puts %(Hello #{input.argument "name"}!)

  # Denote that this command has finished successfully.
  ACON::Command::Status::SUCCESS
end.argument("name", :required)

application.default_command "foo", true
application.catch_exceptions = false

application.run # => Not enough arguments (missing: 'name'). (Athena::Console::Exception::Runtime)

catch_exceptions?

Returns if the application should handle exceptions raised within the execution of a command. See #catch_exceptions=.

command_loader=(command_loader : ACON::Loader::Interface | Nil)

Allows setting the ACON::Loader::Interface that should be used by self. See the related interface for more information.

commands(namespace : String | Nil = nil) : Hash(String, ACON::Command)

Returns all commands within self, optionally only including the ones within the provided namespace. The keys of the returned hash represent the full command names, while the values are the command instances.

complete(input : ACON::Completion::Input, suggestions : ACON::Completion::Suggestions) : Nil

Determines what values should be added to the possible suggestions based on the provided input.

By default this handles completing commands and options, but can be overridden if needed.

default_command(name : String, single_command : Bool = false) : self

Sets the [default command][Athena::Console::Application--default-command] to the command with the provided name.

For example, executing the following console script via ./console would result in Hello world! being printed instead of the default list output.

application = ACON::Application.new "My CLI"

application.register "foo" do |_, output|
  output.puts "Hello world!"
  ACON::Command::Status::SUCCESS
end

application.default_command "foo"

application.run

./console # => Hello world!

For example, executing the following console script via ./console George would result in Hello George! being printed. If we tried this again without setting single_command to true, it would error saying `Command 'George' is not defined.

application = ACON::Application.new "My CLI"

application.register "foo" do |input, output, command|
  output.puts %(Hello #{input.argument "name"}!)
  ACON::Command::Status::SUCCESS
end.argument("name", :required)

application.default_command "foo", true

application.run

definition

Returns the ACON::Input::Definition associated with self. See the related type for more information.

definition=(definition : ACON::Input::Definition)

Sets the definition that should be used by self. See the related type for more information.

each_command(namespace : String | Nil = nil, & : ACON::Command -> Nil) : Nil

Yields each command within self, optionally only yields those within the provided namespace.

find(name : String) : ACON::Command

Returns the ACON::Command with the provided name, which can either be the full name, an abbreviation, or an alias. This method will attempt to find the best match given an abbreviation of a name or alias.

Raises an ACON::Exception::CommandNotFound exception when the provided name is incorrect or ambiguous.

ameba:disable Metrics/CyclomaticComplexity

find_namespace(name : String) : String

Returns the full name of a registered namespace with the provided name, which can either be the full name or an abbreviation.

Raises an ACON::Exception::NamespaceNotFound exception when the provided name is incorrect or ambiguous.

get(name : String) : ACON::Command

Returns the ACON::Command with the provided name.

Raises an ACON::Exception::CommandNotFound exception when a command with the provided name does not exist.

has?(name : String) : Bool

Returns true if a command with the provided name exists, otherwise false.

help

By default this is the same as #long_version, but can be overridden to provide more in-depth help/usage instructions for self.

helper_set

Returns/sets the ACON::Helper::HelperSet associated with self.

The default helper set includes:

ACON::Helper::Formatter
ACON::Helper::Question

helper_set=(helper_set : ACON::Helper::HelperSet)

Returns/sets the ACON::Helper::HelperSet associated with self.

The default helper set includes:

ACON::Helper::Formatter
ACON::Helper::Question

long_version

Returns the #name and #version of the application. Used when the -V or --version option is passed.

name

Returns the name of this CLI application.

namespaces

Returns all unique namespaces used by currently registered commands, excluding the global namespace.

register(name : String, &block : ACON::Input::Interface, ACON::Output::Interface, ACON::Command -> ACON::Command::Status) : ACON::Command

Creates and #adds an ACON::Command with the provided name; executing the block when the command is invoked.

run(input : ACON::Input::Interface = ACON::Input::ARGV.new, output : ACON::Output::Interface = ACON::Output::ConsoleOutput.new) : ACON::Command::Status | NoReturn

Runs the current application, optionally with the provided input and output.

Returns the ACON::Command::Status of the related command execution if #auto_exit? is false. Will gracefully handle exceptions raised within the command execution unless #catch_exceptions? is false.

single_command?

Returns true if self only supports a single command. See Single Command Applications for more information.

use_program_name_as_command=(use_program_name_as_command : Bool)

When set to true, the application will check if PROGRAM_NAME's basename matches a registered command. If it does, that command will be used and any arguments will be passed to it.

This enables symlink-based command invocation, where ./command-name (symlinked to the main binary) will automatically execute the command-name command. Any arguments are passed to the matched command rather than being interpreted as a command name.

use_program_name_as_command?

When set to true, the application will check if PROGRAM_NAME's basename matches a registered command. If it does, that command will be used and any arguments will be passed to it.

This enables symlink-based command invocation, where ./command-name (symlinked to the main binary) will automatically execute the command-name command. Any arguments are passed to the matched command rather than being interpreted as a command name.

version

Returns the version of this CLI application.