Class: Clamp::Command

Inherits:
Object
  • Object
show all
Extended by:
Help, Option::Declaration, Parameter::Declaration, Subcommand::Declaration
Includes:
Option::Parsing, Parameter::Parsing, Subcommand::Parsing
Defined in:
lib/clamp/command.rb

Overview

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.

Instance Attribute Summary collapse

Attributes included from Help

#declared_usage_descriptions, #description

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Help

banner, derived_usage_description, usage, usage_descriptions

Methods included from Subcommand::Declaration

default_subcommand, default_subcommand=, find_subcommand, find_subcommand_class, has_subcommands?, inheritable_attributes, recognised_subcommands, subcommand

Methods included from Parameter::Declaration

has_parameters?, inheritable_parameters, parameter, parameter_buffer_limit, parameters

Methods included from Option::Declaration

declared_options, find_option, option, recognised_options

Constructor Details

#initialize(invocation_path, context = {}) ⇒ Command

Create a command execution.

Parameters:

  • invocation_path (String) —

    the path used to invoke the command

  • context (Hash) (defaults to: {}) —

    additional data the command may need



30
31
32
33
 
# File 'lib/clamp/command.rb', line 30

def initialize(invocation_path, context = {})
  @invocation_path = invocation_path
  @context = context
end

Instance Attribute Details

#invocation_path ⇒ String (readonly)

Returns the path used to invoke this command.

Returns:

  • (String) —

    the path used to invoke this command



37
38
39
 
# File 'lib/clamp/command.rb', line 37

def invocation_path
  @invocation_path
end

#remaining_arguments ⇒ Array<String> (readonly)

Returns unconsumed command-line arguments.

Returns:

  • (Array<String>) —

    unconsumed command-line arguments



41
42
43
 
# File 'lib/clamp/command.rb', line 41

def remaining_arguments
  @remaining_arguments
end

Class Method Details

.execute(&block) ⇒ Object

An alternative to “def execute”



129
130
131
 
# File 'lib/clamp/command.rb', line 129

def execute(&block)
  define_method(:execute, &block)
end

.run(invocation_path = File.basename($PROGRAM_NAME), arguments = ARGV, context = {}) ⇒ Object

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

Parameters:

  • invocation_path (String) (defaults to: File.basename($PROGRAM_NAME)) —

    the path used to invoke the command

  • arguments (Array<String>) (defaults to: ARGV) —

    command-line arguments

  • context (Hash) (defaults to: {}) —

    additional data the command may need



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# 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

Instance Method Details

#execute ⇒ Object

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

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



73
74
75
 
# File 'lib/clamp/command.rb', line 73

def execute
  raise "you need to define #execute"
end

#help ⇒ String

Returns usage documentation for this command.

Returns:

  • (String) —

    usage documentation for this command



79
80
81
 
# File 'lib/clamp/command.rb', line 79

def help
  self.class.help(invocation_path)
end

#parse(arguments) ⇒ Array<String>

Parse command-line arguments.

Parameters:

  • arguments (Array<String>) —

    command-line arguments

Returns:

  • (Array<String>) —

    unconsumed arguments



48
49
50
51
52
53
54
55
 
# 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

#run(arguments) ⇒ Object

Run the command, with the specified arguments.

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

Parameters:

  • arguments (Array<String>) —

    command-line arguments



64
65
66
67
 
# File 'lib/clamp/command.rb', line 64

def run(arguments)
  parse(arguments)
  execute
end

#subcommand_missing(name) ⇒ Object

Abort with subcommand missing usage error

@ param [String] name subcommand_name



86
87
88
 
# File 'lib/clamp/command.rb', line 86

def subcommand_missing(name)
  signal_usage_error(Clamp.message(:no_such_subcommand, name: name))
end