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:

@[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

Constructors#

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

Class methods#

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

Methods#

#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. Optionally supports setting its mode, description, default value, and suggested_values.

Also checkout the value completion for how argument values can be auto completed.

#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. Optionally supports setting its mode, description, default value.

Accepts a block to use to determine this argument's suggested values. Also checkout the value completion for how argument values can be auto completed.

#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 will fall back on completion of the related input argument/option, but can be overridden if needed.

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

#enabled? : Bool#

Returns if self is enabled in the current environment.

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

#help(help : String) : self#

Sets the #help of self.

#help : String#

Returns/sets the help template for self.

See #processed_help.

#help=(help : String)#

Returns/sets the help template for self.

See #processed_help.

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

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

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

#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. Optionally supports setting its shortcut, value_mode, description, and default value.

Also checkout the value completion for how option values can be auto completed.

#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. Optionally supports setting its shortcut, value_mode, description, and default value.

Accepts a block to use to determine this argument's suggested values. Also checkout the value completion for how option values can be auto completed.

#process_title(title : String) : self#

Sets the process title of self.

Todo

Implement this.

#processed_help : String#

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.

#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. For example app:user-create [--dry-run] [--] <username>.

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

See #usage.