Class: SimpleCommander::Command
- Defined in:
- lib/simple_commander/command.rb
Defined Under Namespace
Classes: Options
Instance Attribute Summary collapse
-
#description(val) ⇒ Object
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(val) ⇒ Object
summany.
-
#super_self ⇒ Object
Returns the value of attribute super_self.
-
#syntax(val) ⇒ Object
set syntax.
Instance Method Summary collapse
-
#call(args = []) ⇒ Object
Call the commands when_called block with args.
-
#example(description, command) ⇒ Object
Add a usage example for this command.
-
#has_no_action? ⇒ Boolean
return the block if command have a when_called block.
-
#initialize(name) ⇒ Command
constructor
Initialize new command with specified name.
- #inspect ⇒ Object
-
#method_missing(method, *args, &block) ⇒ Object
when a method is missing inside a action block command will call the method in the runner instance context.
-
#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.
67 68 69 70 |
# File 'lib/simple_commander/command.rb', line 67 def initialize(name) @name, @examples, @when_called = name.to_s, [], [] @options, @proxy_options = [], [] end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(method, *args, &block) ⇒ Object
when a method is missing inside a action block command will call the method in the runner instance context
60 61 62 |
# File 'lib/simple_commander/command.rb', line 60 def method_missing(method, *args, &block) @super_self.send method, *args, &block end |
Instance Attribute Details
#description(val) ⇒ Object
description
25 26 27 |
# File 'lib/simple_commander/command.rb', line 25 def description @description end |
#examples ⇒ Object
Returns the value of attribute examples.
5 6 7 |
# File 'lib/simple_commander/command.rb', line 5 def examples @examples end |
#name ⇒ Object
Returns the value of attribute name.
5 6 7 |
# File 'lib/simple_commander/command.rb', line 5 def name @name end |
#options ⇒ Object
Returns the value of attribute options.
6 7 8 |
# File 'lib/simple_commander/command.rb', line 6 def @options end |
#proxy_options ⇒ Object
Returns the value of attribute proxy_options.
6 7 8 |
# File 'lib/simple_commander/command.rb', line 6 def @proxy_options end |
#summary(val) ⇒ Object
summany
18 19 20 |
# File 'lib/simple_commander/command.rb', line 18 def summary @summary end |
#super_self ⇒ Object
Returns the value of attribute super_self.
5 6 7 |
# File 'lib/simple_commander/command.rb', line 5 def super_self @super_self end |
#syntax(val) ⇒ Object
set syntax
11 12 13 |
# File 'lib/simple_commander/command.rb', line 11 def syntax @syntax end |
Instance Method Details
#call(args = []) ⇒ Object
Call the commands when_called block with args.
208 209 210 211 212 213 214 215 216 217 |
# File 'lib/simple_commander/command.rb', line 208 def call(args = []) object = @when_called.shift meth = @when_called.shift || :call = proxy_option_struct case object when Proc then object.call(args, ) when Class then 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
92 93 94 |
# File 'lib/simple_commander/command.rb', line 92 def example(description, command) @examples << [description, command] end |
#has_no_action? ⇒ Boolean
return the block if command have a when_called block
75 76 77 |
# File 'lib/simple_commander/command.rb', line 75 def has_no_action? if @when_called.empty? then true else false end end |
#inspect ⇒ Object
241 242 243 |
# File 'lib/simple_commander/command.rb', line 241 def inspect "<SimpleCommander::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
143 144 145 146 147 148 149 150 151 152 |
# File 'lib/simple_commander/command.rb', line 143 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.
237 238 239 |
# File 'lib/simple_commander/command.rb', line 237 def option_proc(switches) ->(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.
197 198 199 200 201 202 203 |
# File 'lib/simple_commander/command.rb', line 197 def (*args) return args if args.empty? @options.each_with_object(OptionParser.new) do |option, opts| 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.
223 224 225 226 227 228 229 230 |
# File 'lib/simple_commander/command.rb', line 223 def proxy_option_struct .each_with_object(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
187 188 189 |
# File 'lib/simple_commander/command.rb', line 187 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
174 175 176 177 |
# File 'lib/simple_commander/command.rb', line 174 def when_called(*args, &block) fail ArgumentError, 'must pass an object, class, or block.' if args.empty? && !block @when_called = block ? [block] : args end |