Skip to content

abstract class Athena::Console::Command
inherits Reference #

An ACON::Command represents a concrete command that can be invoked via the CLI. All commands should inherit from this base type, but additional abstract subclasses can be used to share common logic for related command classes.

Creating a Command#

A command is defined by extending ACON::Command and implementing the #execute method. For example:

class CreateUserCommand < ACON::Command
  @@default_name = "app:create-user"

  protected def configure : Nil
    # ...
  end

  protected def execute(input : ACON::Input::Interface, output : ACON::Output::Interface) : ACON::Command::Status
    # Implement all the business logic here.

    # Indicates the command executed successfully.
    ACON::Command::Status::SUCCESS
  end
end

Command Lifecycle#

Commands have three lifecycle methods that are invoked when running the command:

  1. setup (optional) - Executed before #interact and #execute. Can be used to setup state based on input data.
  2. interact (optional) - Executed after #setup but before #execute. Can be used to check if any arguments/options are missing and interactively ask the user for those values. After this method, missing arguments/options will result in an error.
  3. execute (required) - Contains the business logic for the command, returning the status of the invocation via ACON::Command::Status.
class CreateUserCommand < ACON::Command
  @@default_name = "app:create-user"

  protected def configure : Nil
    # ...
  end

  protected def setup(input : ACON::Input::Interface, output : ACON::Output::Interface) : Nil
    # ...
  end

  protected def interact(input : ACON::Input::Interface, output : ACON::Output::Interface) : Nil
    # ...
  end

  protected def execute(input : ACON::Input::Interface, output : ACON::Output::Interface) : ACON::Command::Status
    # Indicates the command executed successfully.
    ACON::Command::Status::SUCCESS
  end
end

Configuring the Command#

In most cases, a command is going to need to be configured to better fit its purpose. The #configure method can be used configure various aspects of the command, such as its name, description, ACON::Inputs, help message, aliases, etc.

protected def configure : Nil
  self
    .help("Creates a user...") # Shown when running the command with the `--help` option
    .aliases("new-user")       # Alternate names for the command
    .hidden                    # Hide the command from the list
  # ...
end

Info

The name and description can also be set via @@default_name and @@default_description class variables, which is the preferred way of setting them.

The #configure command is called automatically at the end of the constructor method. If your command defines its own, be sure to call super() to also run the parent constructor. super may also be called after setting the properties if they should be used to determine how to configure the command.

class CreateUserCommand < ACON::Command
  def initialize(@require_password : Bool = false)
    super()
  end

  protected def configure : Nil
    self
      .argument("password", @require_password ? ACON::Input::Argument::Mode::REQUIRED : ACON::Input::Argument::Mode::OPTIONAL)
  end
end

Output#

The #execute method has access to an ACON::Output::Interface instance that can be used to write messages to display. The output parameter should be used instead of #puts or #print to decouple the command from STDOUT.

protected def execute(input : ACON::Input::Interface, output : ACON::Output::Interface) : ACON::Command::Status
  # outputs multiple lines to the console (adding "\n" at the end of each line)
  output.puts([
    "User Creator",
    "============",
    "",
  ])

  # outputs a message followed by a "\n"
  output.puts "Whoa!"

  # outputs a message without adding a "\n" at the end of the line
  output.print "You are about to "
  output.print "create a user."

  ACON::Command::Status::SUCCESS
end

See ACON::Output::Interface for more information.

Input#

In most cases, a command is going to have some sort of input arguments/options. These inputs can be setup in the #configure method, and accessed via the input parameter within #execute.

protected def configure : Nil
  self
    .argument("username", :required, "The username of the user")
end

protected def execute(input : ACON::Input::Interface, output : ACON::Output::Interface) : ACON::Command::Status
  # Retrieve the username as a String?
  output.puts %(Hello #{input.argument "username"}!)

  ACON::Command::Status::SUCCESS
end

See ACON::Input::Interface for more information.

Testing the Command#

Athena::Console also includes a way to test your console commands without needing to build and run a binary. A single command can be tested via an ACON::Spec::CommandTester and a whole application can be tested via an ACON::Spec::ApplicationTester.

See ACON::Spec for more information.

Direct known subclasses

Athena::Console::Commands::Generic Athena::Console::Commands::Help Athena::Console::Commands::List

Constructors#

.new(name : String? = nil) #

View source

Class methods#

.default_description #

Returns the default description of self, or nil if it was not set.

View source

.default_name #

Returns the default name of self, or nil if it was not set.

View source

Methods#

#aliases(aliases : Enumerable(String)) : self #

Sets the aliases of self.

View source

#aliases #

Returns/sets the list of aliases that may also be used to execute self in addition to its #name.

View source

#aliases(*aliases : String) : self #

Sets the aliases of self.

View source

#aliases=(aliases : Array(String)) #

Returns/sets the list of aliases that may also be used to execute self in addition to its #name.

View source

#application #

Returns the ACON::Application associated with self, otherwise nil.

View source

#application=(application : ACON::Application? = nil) : Nil #

View source

#application? #

Returns the ACON::Application associated with self, otherwise nil.

View source

#argument(name : String, mode : ACON::Input::Argument::Mode = :optional, description : String = "", default = nil) : self #

Adds an ACON::Input::Argument to self with the provided name. Optionally supports setting its mode, description, and default value.

View source

#definition(definition : Array(ACON::Input::Argument | ACON::Input::Option)) : self #

Sets the ACON::Input::Definition on self.

View source

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

Sets the ACON::Input::Definition on self.

View source

#definition #

View source

#definition(*definitions : ACON::Input::Argument | ACON::Input::Option) : self #

Sets the ACON::Input::Definition on self.

View source

#description(description : String) : self #

Sets the #description of self.

View source

#description #

Returns the description ofself`.

View source

#enabled? #

Returns if self is enabled in the current environment.

Can be overridden to return false if it cannot run under the current conditions.

View source

#help(help : String) : self #

Sets the #help of self.

View source

#help #

Returns/sets the help template for self.

See #processed_help.

View source

#help=(help : String) #

Returns/sets the help template for self.

See #processed_help.

View source

#helper(helper_class : T.class) : T forall T #

Returns an ACON:Helper::Interface of the provided helper_class.

formatter = self.helper ACON::Helper::Formatter
# ...
View source

#helper_set #

Returns/sets an ACON::Helper::HelperSet on self.

View source

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

Returns/sets an ACON::Helper::HelperSet on self.

View source

#hidden(hidden : Bool = true) : self #

Hides self from the command list.

View source

#hidden? #

Returns true if self is hidden from the command list, otherwise false.

View source

#ignore_validation_errors #

Makes the command ignore any input validation errors.

View source

#name(name : String) : self #

View source

#name #

Returns the name of self.

View source

#name? #

Returns the name of self.

View source

#option(name : String, shortcut : String? = nil, value_mode : ACON::Input::Option::Value = :none, description : String = "", default = nil) : self #

Adds an ACON::Input::Option to self with the provided name. Optionally supports setting its shortcut, value_mode, description, and default value.

View source

#process_title=(process_title : String?) #

Sets the process title of self.

Todo

Implement this.

View source

#processed_help #

The #help message can include some template variables for the command:

  • %command.name% - Returns the #name of self. E.g. app:create-user

This method returns the #help message with these variables replaced.

View source

#run(input : ACON::Input::Interface, output : ACON::Output::Interface) : ACON::Command::Status #

Runs the command with the provided input and output, returning the status of the invocation as an ACON::Command::Status.

View source

#synopsis(short : Bool = false) : String #

Returns a short synopsis of self, including its #name and expected arguments/options. For example app:user-create [--dry-run] [--] <username>.

View source

#usage(usage : String) : self #

Adds a usage string that will displayed within the Usage section after the auto generated entry.

View source

#usages #

Returns the list of usages for self.

See #usage.

View source