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?, parameter, 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



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

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



35
36
37
 
# File 'lib/clamp/command.rb', line 35

def invocation_path
  @invocation_path
end

#remaining_arguments ⇒ Array<String> (readonly)

Returns unconsumed command-line arguments.

Returns:

  • (Array<String>) —

    unconsumed command-line arguments



39
40
41
 
# File 'lib/clamp/command.rb', line 39

def remaining_arguments
  @remaining_arguments
end

Class Method Details

.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



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# 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

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.



70
71
72
 
# File 'lib/clamp/command.rb', line 70

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

#help ⇒ String

Returns usage documentation for this command.

Returns:

  • (String) —

    usage documentation for this command



76
77
78
 
# File 'lib/clamp/command.rb', line 76

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



46
47
48
49
50
51
52
 
# 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(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



61
62
63
64
 
# File 'lib/clamp/command.rb', line 61

def run(arguments)
  parse(arguments)
  execute
end

#subcommand_missing(name) ⇒ Object

Abort with subcommand missing usage error

@ param [String] name subcommand_name



83
84
85
 
# File 'lib/clamp/command.rb', line 83

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