class Athena::Console::Application
inherits Reference
#
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,
override the array of default commands, or customize the default input options, etc.
Constructors#
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? : Bool#
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::Exceptions::ValidationFailed)
#catch_exceptions? : Bool#
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 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 : ACON::Input::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::Exceptions::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::Exceptions::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::Exceptions::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 : 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.
The default helper set includes:
#helper_set=(helper_set : ACON::Helper::HelperSet)#
Returns/sets the ACON::Helper::HelperSet associated with self.
The default helper set includes:
#long_version : String#
View source
#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.
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? : Bool#
Returns true if self only supports a single command.
See Single Command Applications for more information.