Class: Commander::Command
Defined Under Namespace
Classes: Options
Instance Attribute Summary collapse
-
#description ⇒ Object
Returns the value of attribute description.
-
#examples ⇒ Object
Returns the value of attribute examples.
-
#name ⇒ Object
Returns the value of attribute name.
-
#options ⇒ Object
Returns the value of attribute options.
-
#proxy_options ⇒ Object
Returns the value of attribute proxy_options.
-
#summary ⇒ Object
Returns the value of attribute summary.
-
#syntax ⇒ Object
Returns the value of attribute syntax.
Instance Method Summary collapse
- #arguments(proc) ⇒ Object
-
#call(args = []) ⇒ Object
Call the commands when_called block with args.
-
#example(description, command) ⇒ Object
Add a usage example for this command.
-
#initialize(name) ⇒ Command
constructor
Initialize new command with specified name.
- #inspect ⇒ Object
-
#option(*args, &block) ⇒ Object
Add an option.
-
#option_proc(switches) ⇒ Object
Option proxy proc used when a block is not explicitly passed via the #option method.
-
#parse_options_and_call_procs(*args) ⇒ Object
Parses options and calls associated procs, returning the arguments remaining.
-
#proxy_option_struct ⇒ Object
Creates an Options instance populated with the option values collected by the #option_proc.
-
#run(*args) ⇒ Object
Run the command with args.
-
#when_called(*args, &block) ⇒ Object
(also: #action)
Handle execution of command.
Constructor Details
#initialize(name) ⇒ Command
Initialize new command with specified name.
40 41 42 43 44 |
# File 'lib/taco/commander/command.rb', line 40 def initialize name @name, @examples, @when_called = name.to_s, [], [] @options, @proxy_options = [], [] @argument_validator = nil end |
Instance Attribute Details
#description ⇒ Object
Returns the value of attribute description.
7 8 9 |
# File 'lib/taco/commander/command.rb', line 7 def description @description end |
#examples ⇒ Object
Returns the value of attribute examples.
7 8 9 |
# File 'lib/taco/commander/command.rb', line 7 def examples @examples end |
#name ⇒ Object
Returns the value of attribute name.
7 8 9 |
# File 'lib/taco/commander/command.rb', line 7 def name @name end |
#options ⇒ Object
Returns the value of attribute options.
8 9 10 |
# File 'lib/taco/commander/command.rb', line 8 def @options end |
#proxy_options ⇒ Object
Returns the value of attribute proxy_options.
8 9 10 |
# File 'lib/taco/commander/command.rb', line 8 def @proxy_options end |
#summary ⇒ Object
Returns the value of attribute summary.
8 9 10 |
# File 'lib/taco/commander/command.rb', line 8 def summary @summary end |
#syntax ⇒ Object
Returns the value of attribute syntax.
7 8 9 |
# File 'lib/taco/commander/command.rb', line 7 def syntax @syntax end |
Instance Method Details
#arguments(proc) ⇒ Object
64 65 66 |
# File 'lib/taco/commander/command.rb', line 64 def arguments proc @argument_validator = proc end |
#call(args = []) ⇒ Object
Call the commands when_called block with args.
181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 |
# File 'lib/taco/commander/command.rb', line 181 def call args = [] object = @when_called.shift meth = @when_called.shift || :call = proxy_option_struct if @argument_validator raise ArgumentError.new("Unexpected arguments: #{args.join(' ')}") unless @argument_validator.call(args) elsif args.size > 0 raise ArgumentError.new("Unexpected arguments: #{args.join(' ')}") end case object when Proc ; object.call(args, ) when Class ; meth != :call ? object.new.send(meth, args, ) : object.new(args, ) else object.send(meth, args, ) 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
59 60 61 |
# File 'lib/taco/commander/command.rb', line 59 def example description, command @examples << [description, command] end |
#inspect ⇒ Object
221 222 223 |
# File 'lib/taco/commander/command.rb', line 221 def inspect "<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, |
do_something_recursively if .recursive
do_something_with_file .file if .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
115 116 117 118 119 120 121 122 123 124 |
# File 'lib/taco/commander/command.rb', line 115 def option *args, &block switches, description = Runner.separate_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.
217 218 219 |
# File 'lib/taco/commander/command.rb', line 217 def option_proc switches lambda { |value| << [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.
170 171 172 173 174 175 176 |
# File 'lib/taco/commander/command.rb', line 170 def *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.
203 204 205 206 207 208 209 210 |
# File 'lib/taco/commander/command.rb', line 203 def proxy_option_struct .inject Options.new do |, (option, value)| # options that are present will evaluate to true value = true if value.nil? .__send__ :"#{option}=", value end end |
#run(*args) ⇒ Object
Run the command with args.
-
parses options, call option blocks
-
invokes when_called proc
160 161 162 |
# File 'lib/taco/commander/command.rb', line 160 def run *args call (*args) end |
#when_called(*args, &block) ⇒ Object Also known as: action
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, |
# 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
147 148 149 150 |
# File 'lib/taco/commander/command.rb', line 147 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 |