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

Attributes included from Subcommand::Declaration

#default_subcommand

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Help

derived_usage_description, usage, usage_descriptions

Methods included from Subcommand::Declaration

find_subcommand, has_subcommands?, 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



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

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



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

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



124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/clamp/command.rb', line 124

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
  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.



71
72
73
74
75
76
77
 
# File 'lib/clamp/command.rb', line 71

def execute
  if @subcommand
    @subcommand.execute
  else
    raise "you need to define #execute"
  end
end

#help ⇒ String

Returns usage documentation for this command.

Returns:

  • (String) —

    usage documentation for this command



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

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



47
48
49
50
51
52
53
 
# File 'lib/clamp/command.rb', line 47

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



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

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



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

def run(arguments)
  parse(arguments)
  execute
end