Athena::Console::Command

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:

@[ACONA::AsCommand("app:create-user")]
class CreateUserCommand < ACON::Command
  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.

@[ACONA::AsCommand("app:create-user")]
class CreateUserCommand < ACON::Command
  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

TIP: The suggested way of setting the name and description of the command is via the ACONA::AsCommand annotation. This enables lazy command instantiation when used within the Athena framework.

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.