class SimpleCommander::Command

Initialize new command with specified name.

# File lib/simple_commander/command.rb, line 46
def initialize(name)
  @name, @examples, @when_called = name.to_s, [], []
  @options, @proxy_options = [], []
end

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

# File lib/simple_commander/command.rb, line 71
def example(description, command)
  @examples << [description, command]
end

return the block if command have a #when_called block

# File lib/simple_commander/command.rb, line 54
def has_no_action?
        if @when_called.empty? then true else false end
end

when a method is missing inside a action block command will call the method in the runner instance context

# File lib/simple_commander/command.rb, line 39
def method_missing(method, *args, &block)
        @super_self.send method, *args, &block 
end

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

# File lib/simple_commander/command.rb, line 122
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

Run the command with args.

• parses options, call option blocks

• invokes #when_called proc

# File lib/simple_commander/command.rb, line 166
def run(*args)
  call parse_options_and_call_procs(*args)
end

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

# File lib/simple_commander/command.rb, line 153
def when_called(*args, &block)
  fail ArgumentError, 'must pass an object, class, or block.' if args.empty? && !block
  @when_called = block ? [block] : args
end