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

View source

Class methods#

.default_description : String | ::Nil#

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

View source

.default_name : String | ::Nil#

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 : Array(String)#

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 : ACON::Application#

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

View source

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

View source

#application? : ACON::Application | ::Nil#

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

View source

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

View source

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

View source

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

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 : ACON::Input::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 : String#

Returns the description ofself`.

View source

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

View source

#help(help : String) : self#

Sets the #help of self.

View source

#help : String#

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 : ACON::Helper::HelperSet | ::Nil#

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

View source

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

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

View source

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

Hides self from the command list.

View source

#hidden? : Bool#

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

View source

#ignore_validation_errors : Nil#

Makes the command ignore any input validation errors.

View source

#name(name : String) : self#

View source

#name : String#

Returns the name of self.

View source

#name? : String | ::Nil#

Returns the name of self.

View source

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

View source

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

View source

#process_title(title : String) : self#

Sets the process title of self.

Todo

Implement this.

View source

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

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 : Array(String)#

Returns the list of usages for self.

See #usage.

View source