class Athena::Console::Application

• Athena::Console::Application
• Reference
• Object

Overview

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.

Defined in:

Constructors

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

Instance Method Summary

• #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.

• #auto_exit? : Bool

  Returns if application should exit automatically after executing a command.

• #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.

• #catch_exceptions? : Bool

  Returns if the application should handle exceptions raised within the execution of a command.

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

  Allows setting the ACON::Loader::Interface that should be used by self.

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

  Returns all commands within self, optionally only including the ones within the provided namespace.

• #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.

• #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.

• #definition : ACON::Input::Definition

  Returns the ACON::Input::Definition associated with self.

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

  Sets the definition that should be used by self.

• #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.

• #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.

• #get(name : String) : ACON::Command

  Returns the ACON::Command with the provided name.

• #has?(name : String) : Bool

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

• #help : String

  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 : ACON::Helper::HelperSet

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

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

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

• #long_version : String

  Returns the #name and #version of the application.

• #name : String

  Returns the name of this CLI application.

• #namespaces : Array(String)

  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.

• #single_command? : Bool

  Returns true if self only supports a single command.

• #version : String

  Returns the version of this CLI application.

Constructor Detail

Instance Method Detail

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

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::Exceptions::ValidationFailed)

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!

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