class Clamp::Command

{Command} models a shell command. Each command invocation is a new object. Command options and parameters are represented as attributes (see {Command::Declaration}).

The main entry-point is {#run}, which uses {#parse} to populate attributes based on an array of command-line arguments, then calls {#execute} (which you provide) to make it go.

Attributes

context[RW]

invocation_path[R]

@return [String] the path used to invoke this command

remaining_arguments[R]

@return [Array<String>] unconsumed command-line arguments

Public Class Methods

new(invocation_path, context = {}) click to toggle source

Create a command execution.

@param [String] #invocation_path the path used to invoke the command @param [Hash] context additional data the command may need

# File lib/clamp/command.rb, line 28
def initialize(invocation_path, context = {})
  @invocation_path = invocation_path
  @context = context
end

Public Instance Methods

execute() click to toggle source

Execute the command (assuming that all options/parameters have been set).

This method is designed to be overridden in sub-classes.

# File lib/clamp/command.rb, line 70
def execute
  raise "you need to define #execute"
end

help() click to toggle source

@return [String] usage documentation for this command

# File lib/clamp/command.rb, line 76
def help
  self.class.help(invocation_path)
end

parse(arguments) click to toggle source

Parse command-line arguments.

@param [Array<String>] arguments command-line arguments @return [Array<String>] unconsumed arguments

# File lib/clamp/command.rb, line 46
def parse(arguments)
  @remaining_arguments = arguments.dup
  parse_options
  parse_parameters
  parse_subcommand
  handle_remaining_arguments
end

run(arguments) click to toggle source

Run the command, with the specified arguments.

This calls {#parse} to process the command-line arguments, then delegates to {#execute}.

@param [Array<String>] arguments command-line arguments

# File lib/clamp/command.rb, line 61
def run(arguments)
  parse(arguments)
  execute
end

subcommand_missing(name) click to toggle source

Abort with subcommand missing usage error

@ param [String] name subcommand_name

# File lib/clamp/command.rb, line 83
def subcommand_missing(name)
  signal_usage_error(Clamp.message(:no_such_subcommand, :name => name))
end

Protected Instance Methods

handle_remaining_arguments() click to toggle source

# File lib/clamp/command.rb, line 95
def handle_remaining_arguments
  signal_usage_error Clamp.message(:too_many_arguments) unless remaining_arguments.empty?
end

Private Instance Methods

request_help() click to toggle source

# File lib/clamp/command.rb, line 114
def request_help
  raise HelpWanted, self
end

signal_error(message, options = {}) click to toggle source

# File lib/clamp/command.rb, line 107
def signal_error(message, options = {})
  status = options.fetch(:status, 1)
  e = ExecutionError.new(message, self, status)
  e.set_backtrace(caller)
  raise e
end

signal_usage_error(message) click to toggle source

# File lib/clamp/command.rb, line 101
def signal_usage_error(message)
  e = UsageError.new(message, self)
  e.set_backtrace(caller)
  raise e
end