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

Public Class Methods

new(invocation_path, context = {}, parent_attribute_values = {}) 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 = {}, parent_attribute_values = {})
  @invocation_path = invocation_path
  @context = context
  parent_attribute_values.each do |attribute, value|
    attribute.of(self).set(value)
  end
end

Private Class Methods

run(invocation_path = File.basename($0), arguments = ARGV, context = {}) click to toggle source

Create an instance of this command class, and run it.

@param [String] #invocation_path the path used to invoke the command @param [Array<String>] arguments command-line arguments @param [Hash] context additional data the command may need

# File lib/clamp/command.rb, line 131
def run(invocation_path = File.basename($0), arguments = ARGV, context = {})
  begin
    new(invocation_path, context).run(arguments)
  rescue Clamp::UsageError => e
    $stderr.puts "ERROR: #{e.message}"
    $stderr.puts ""
    $stderr.puts "See: '#{e.command.invocation_path} --help'"
    exit(1)
  rescue Clamp::HelpWanted => e
    puts e.command.help
  rescue Clamp::ExecutionError => e
    $stderr.puts "ERROR: #{e.message}"
    exit(e.status)
  rescue SignalException => e
    exit(128 + e.signo)
  end
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 75
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 81
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 51
def parse(arguments)
  @remaining_arguments = arguments.dup
  parse_options
  parse_parameters
  parse_subcommand
  handle_remaining_arguments
end
remaining_arguments() click to toggle source

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

# File lib/clamp/command.rb, line 42
def remaining_arguments
  @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 66
def run(arguments)
  parse(arguments)
  execute
end

Protected Instance Methods

handle_remaining_arguments() click to toggle source
# File lib/clamp/command.rb, line 93
def handle_remaining_arguments
  unless remaining_arguments.empty?
    signal_usage_error Clamp.message(:too_many_arguments)
  end
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