Skip to content

class Athena::Console::Application
inherits Reference #

An ACON::Application is 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.

Basic Usage#

The console component best works in conjunction with a dedicated Crystal file that'll be used as the entry point. Ideally this file is compiled into a dedicated binary for use in production, but is invoked directly while developing. Otherwise, any changes made to the files it requires would not be represented. The most basic example would be:

#!/usr/bin/env crystal

# Require the component and anything extra needed based on your business logic.
require "athena-console"

# Create an ACON::Application, passing it the name of your CLI.
# Optionally accepts a second argument representing the version of the CLI.
application = ACON::Application.new "My CLI"

# Add any commands defined externally,
# or configure/customize the application as needed.

# Run the application.
# By default this uses STDIN and STDOUT for its input and output.
application.run

The shebang allows executing the file as a command without needing the crystal prefix. For example ./console list would list all commands.

External commands can be registered via #add:

application.add MyCommand.new

The #register method may also be used to define simpler/generic commands:

application.register "foo" do |input, output|
  # Do stuff here.

  # Denote that this command has finished successfully.
  ACON::Command::Status::SUCCESS
end

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#

.new(name : String, version : String = "0.1.0") : self #

View source

.new(name : String, version : SemanticVersion = SemanticVersion.new(0, 1, 0)) #

View source

Methods#

#add(command : ACON::Command) : ACON::Command? #

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

View source

#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
View source

#auto_exit? #

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

View source

#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)
View source

#catch_exceptions? #

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

View source

#command_loader=(command_loader : ACON::Loader::Interface?) #

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

View source

#commands(namespace : String? = 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.

View source

#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
View source

#definition #

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

View source

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

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

View source

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

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

View source

#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

View source

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

View source

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

View source

#has?(name : String) : Bool #

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

View source

#help #

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

View source

#helper_set #

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

The default helper set includes:

View source

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

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

The default helper set includes:

View source

#long_version #

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

View source

#name #

Returns the name of this CLI application.

View source

#namespaces #

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

View source

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

View source

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

View source

#single_command? #

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

View source

#version #

Returns the version of this CLI application.

View source