{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.
@return [String] the path used to invoke this command
@return [Array<String>] unconsumed command-line arguments
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
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($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
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
@return [String] usage documentation for this command
# File lib/clamp/command.rb, line 76 def help self.class.help(invocation_path) end
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 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
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
# File lib/clamp/command.rb, line 95 def handle_remaining_arguments signal_usage_error Clamp.message(:too_many_arguments) unless remaining_arguments.empty? end
# File lib/clamp/command.rb, line 114 def request_help raise HelpWanted, self end
# 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
# File lib/clamp/command.rb, line 101 def signal_usage_error(message) e = UsageError.new(message, self) e.set_backtrace(caller) raise e end