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
@return [String] the path used to invoke this command
@return [Array<String>] unconsumed command-line arguments
Public Class Methods
Source
# File lib/clamp/command.rb, line 129 def execute(&block) define_method(:execute, &block) end
An alternative to “def execute”
Source
# File lib/clamp/command.rb, line 30 def initialize(invocation_path, context = {}) @invocation_path = invocation_path @context = context end
Create a command execution.
@param [String] invocation_path
the path used to invoke the command @param [Hash] context additional data the command may need
Source
# File lib/clamp/command.rb, line 139 def run(invocation_path = File.basename($PROGRAM_NAME), arguments = ARGV, context = {}) 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
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
Public Instance Methods
Source
# File lib/clamp/command.rb, line 73 def execute raise "you need to define #execute" end
Execute the command (assuming that all options/parameters have been set).
This method is designed to be overridden in sub-classes.
Source
# File lib/clamp/command.rb, line 79 def help self.class.help(invocation_path) end
@return [String] usage documentation for this command
Source
# File lib/clamp/command.rb, line 48 def parse(arguments) @remaining_arguments = arguments.dup parse_options parse_parameters parse_subcommand verify_required_options_are_set handle_remaining_arguments end
Parse command-line arguments.
@param [Array<String>] arguments command-line arguments @return [Array<String>] unconsumed arguments
Source
# File lib/clamp/command.rb, line 64 def run(arguments) parse(arguments) execute end
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
Source
# File lib/clamp/command.rb, line 86 def subcommand_missing(name) signal_usage_error(Clamp.message(:no_such_subcommand, name: name)) end
Abort with subcommand missing usage error
@ param [String] name subcommand_name
Protected Instance Methods
Source
# File lib/clamp/command.rb, line 98 def handle_remaining_arguments signal_usage_error Clamp.message(:too_many_arguments) unless remaining_arguments.empty? end
Private Instance Methods
Source
# File lib/clamp/command.rb, line 117 def request_help raise HelpWanted, self end
Source
# File lib/clamp/command.rb, line 110 def signal_error(message, options = {}) status = options.fetch(:status, 1) e = ExecutionError.new(message, self, status) e.set_backtrace(caller) raise e end
Source
# File lib/clamp/command.rb, line 104 def signal_usage_error(message) e = UsageError.new(message, self) e.set_backtrace(caller) raise e end