abstract class Athena::Console::Command

• Athena::Console::Command
• Reference
• Object

Overview

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.

Direct Known Subclasses

• Athena::Console::Commands::DumpCompletion
• Athena::Console::Commands::Generic
• Athena::Console::Commands::Help
• Athena::Console::Commands::List

Defined in:

Constructors

• .new(name : String | Nil = nil)

Class Method Summary

• .default_description : String | Nil

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

• .default_name : String | Nil

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

Instance Method Summary

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

  Sets the aliases of self.

• #aliases : Array(String)

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

• #aliases(*aliases : String) : self

  Sets the aliases of self.

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

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

• #application : ACON::Application

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

• #application=(application : ACON::Application | Nil) : Nil
• #application? : ACON::Application | Nil

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

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

  Adds an ACON::Input::Argument to self with the provided name.

• #argument(name : String, mode : ACON::Input::Argument::Mode = :optional, description : String = "", default = nil, &suggested_values : ACON::Completion::Input -> Array(String)) : self

  Adds an ACON::Input::Argument to this command with the provided name.

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

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

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

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

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

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

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

• #description(description : String) : self

  Sets the #description of self.

• #description : String

  Returns the description of self`.

• #enabled? : Bool

  Returns if self is enabled in the current environment.

• #help(help : String) : self

  Sets the #help of self.

• #help : String

  Returns/sets the help template for self.

• #help=(help : String)

  Returns/sets the help template for self.

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

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

• #helper_set : ACON::Helper::HelperSet | Nil

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

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

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

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

  Hides self from the command list.

• #hidden? : Bool

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

• #ignore_validation_errors : Nil

  Makes the command ignore any input validation errors.

• #name(name : String) : self
• #name : String

  Returns the name of self.

• #name? : String | Nil

  Returns the name of self.

• #option(name : String, shortcut : String | Nil = nil, value_mode : ACON::Input::Option::Value = :none, description : String = "", default = nil, suggested_values : Enumerable(String) | Nil = nil) : self

  Adds an ACON::Input::Option to self with the provided name.

• #option(name : String, shortcut : String | Nil = nil, value_mode : ACON::Input::Option::Value = :none, description : String = "", default = nil, &suggested_values : ACON::Completion::Input -> Array(String)) : self

  Adds an ACON::Input::Option to self with the provided name.

• #process_title(title : String) : self

  Sets the process title of self.

• #processed_help : String

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

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

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

  Returns a short synopsis of self, including its #name and expected arguments/options.

• #usage(usage : String) : self

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

• #usages : Array(String)

  Returns the list of usages for self.

Constructor Detail

Class Method Detail

Instance Method Detail

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