Class: Commander::Command

Inherits:
Object show all
Defined in:
lib/commander/command.rb

Defined Under Namespace

Classes: Options

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name) ⇒ Command

Initialize new command with specified name.



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

def initialize name
  @name, @examples, @when_called = name.to_s, [], []
  @options, @proxy_options = [], []
end

Instance Attribute Details

#description ⇒ Object

Returns the value of attribute description.



7
8
9
 
# File 'lib/commander/command.rb', line 7

def description
  @description
end

#examples ⇒ Object

Returns the value of attribute examples.



7
8
9
 
# File 'lib/commander/command.rb', line 7

def examples
  @examples
end

#name ⇒ Object

Returns the value of attribute name.



7
8
9
 
# File 'lib/commander/command.rb', line 7

def name
  @name
end

#options ⇒ Object

Returns the value of attribute options.



8
9
10
 
# File 'lib/commander/command.rb', line 8

def options
  @options
end

#proxy_options ⇒ Object

Returns the value of attribute proxy_options.



8
9
10
 
# File 'lib/commander/command.rb', line 8

def proxy_options
  @proxy_options
end

#summary ⇒ Object

Returns the value of attribute summary.



8
9
10
 
# File 'lib/commander/command.rb', line 8

def summary
  @summary
end

#syntax ⇒ Object

Returns the value of attribute syntax.



7
8
9
 
# File 'lib/commander/command.rb', line 7

def syntax
  @syntax
end

Instance Method Details

#call(args = []) ⇒ Object

Call the commands when_called block with args.



172
173
174
175
176
177
178
179
180
181
 
# File 'lib/commander/command.rb', line 172

def call args = []
  object = @when_called.shift
  meth = @when_called.shift || :call
  options = proxy_option_struct
  case object
  when Proc  ; object.call(args, options)
  when Class ; meth != :call ? object.new.send(meth, args, options) : object.new(args, options)
  else         object.send(meth, args, options) if object
  end 
end

#example(description, command) ⇒ Object

Add a usage example for this command.

Usage examples are later displayed in help documentation created by the help formatters.

Examples:

command :something do |c|
  c.example "Should do something", "my_command something"
end



58
59
60
 
# File 'lib/commander/command.rb', line 58

def example description, command 
  @examples << [description, command]
end

#inspect ⇒ Object

:nodoc:



203
204
205
 
# File 'lib/commander/command.rb', line 203

def inspect #:nodoc:
  "<Commander::Command:#{name}>"
end

#option(*args, &block) ⇒ Object

Add an option.

Options are parsed via OptionParser so view it for additional usage documentation. A block may optionally be passed to handle the option, otherwise the options struct seen below contains the results of this option. This handles common formats such as:

-h, --help          options.help           # => bool
--[no-]feature      options.feature        # => bool
--large-switch      options.large_switch   # => bool
--file FILE         options.file           # => file passed
--list WORDS        options.list           # => array
--date [DATE]       options.date           # => date or nil when optional argument not set

Examples:

command :something do |c|
  c.option '--recursive', 'Do something recursively'
  c.option '--file FILE', 'Specify a file'
  c.option('--info', 'Display info') { puts "handle with block" }
  c.option '--[no-]feature', 'With or without feature'
  c.option '--list FILES', Array, 'List the files specified'

  c.when_called do |args, options|
    do_something_recursively if options.recursive
    do_something_with_file options.file if options.file
  end 
end

Help Formatters:

This method also parses the arguments passed in order to determine which were switches, and which were descriptions for the option which can later be used within help formatters using option and option.

Input Parsing:

Since Commander utilizes OptionParser you can pre-parse and evaluate option arguments. Simply require ‘optparse/time’, or ‘optparse/date’, as these objects must respond to #parse.

c.option '--time TIME', Time
c.option '--date [DATE]', Date



109
110
111
112
113
114
115
116
117
118
 
# File 'lib/commander/command.rb', line 109

def option *args, &block
  switches, description = Runner.seperate_switches_from_description *args
  proc = block || option_proc(switches)
  @options << {
    :args => args,
    :proc => proc,
    :switches => switches,
    :description => description,
  }
end

#option_proc(switches) ⇒ Object

Option proxy proc used when a block is not explicitly passed via the #option method. This allows commander to auto-populate and work with option values.



199
200
201
 
# File 'lib/commander/command.rb', line 199

def option_proc switches
  lambda { |value| proxy_options << [Runner.switch_to_sym(switches.last), value] } 
end

#parse_options_and_call_procs(*args) ⇒ Object

Parses options and calls associated procs, returning the arguments remaining.



161
162
163
164
165
166
167
 
# File 'lib/commander/command.rb', line 161

def parse_options_and_call_procs *args
  return args if args.empty?
  @options.inject OptionParser.new do |opts, option| 
    opts.on *option[:args], &option[:proc]
    opts
  end.parse! args
end

#proxy_option_struct ⇒ Object

Creates an Options instance populated with the option values collected by the #option_proc.



187
188
189
190
191
192
 
# File 'lib/commander/command.rb', line 187

def proxy_option_struct
  proxy_options.inject Options.new do |options, (option, value)|
    options.__send__ :"#{option}=", value
    options
  end
end

#run(*args) ⇒ Object

Run the command with args.

  • parses options, call option blocks

  • invokes when_called proc



153
154
155
 
# File 'lib/commander/command.rb', line 153

def run *args
  call parse_options_and_call_procs(*args)
end

#when_called(*args, &block) ⇒ Object

Handle execution of command. The handler may be a class, object, or block (see examples below).

Examples:

# Simple block handling
c.when_called do |args, options|
   # do something
end 

# Create inst of Something and pass args / options
c.when_called MyLib::Command::Something

# Create inst of Something and use arbitrary method
 c.when_called MyLib::Command::Something, :some_method

# Pass an object to handle callback (requires method symbol)
c.when_called SomeObject, :some_method

Raises:

  • (ArgumentError) 


141
142
143
144
 
# File 'lib/commander/command.rb', line 141

def when_called *args, &block
  raise ArgumentError, 'must pass an object, class, or block.' if args.empty? and !block
  @when_called = block ? [block] : args
end