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, parameters_before_subcommand, recognised_subcommands, subcommand

Methods included from Parameter::Declaration

has_parameters?, parameter, parameters

Methods included from Option::Declaration

declared_options, find_option, option, recognised_options

Constructor Details

#initialize(invocation_path, context = {}, parent_attribute_values = {}) ⇒ 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



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

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

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

Class Method Details

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

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

Parameters:

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

    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



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/clamp/command.rb', line 130

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

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.



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

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

#help ⇒ String

Returns usage documentation for this command.

Returns:

  • (String) —

    usage documentation for this command



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

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



50
51
52
53
54
55
56
 
# File 'lib/clamp/command.rb', line 50

def parse(arguments)
  @remaining_arguments = arguments.dup
  parse_options
  parse_parameters
  parse_subcommand
  handle_remaining_arguments
end

#remaining_arguments ⇒ Array<String>

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

#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



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

def run(arguments)
  parse(arguments)
  execute
end