class Commander::Command

Attributes

description[RW]
examples[RW]
name[RW]
options[RW]
priority[RW]
summary[RW]
syntax[RW]

Public Class Methods

new(name) click to toggle source

Initialize new command with specified name.

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

Public Instance Methods

<=>(other) click to toggle source

Allows the commands to be sorted via priority

# File lib/commander/command.rb, line 19
def <=>(other)
  # Different classes can not be compared and thus are considered
  # equal in priority
  return 0 unless self.class == other.class

  # Sort firstly based on the commands priority
  comp = (self.priority || 0) <=> (other.priority || 0)

  # Fall back on name comparison if priority is equal
  comp == 0 ? self.name <=> other.name : comp
end
action(*args, &block)
Alias for: when_called
assert_correct_number_of_args!(args) click to toggle source
# File lib/commander/command.rb, line 118
def assert_correct_number_of_args!(args)
  return if primary_command_word == 'help'
  too_many = too_many_args?(args)
  if too_many
    raise CommandUsageError, "excess arguments for command '#{primary_command_word}'"
  elsif too_few_args?(args)
    raise CommandUsageError, "insufficient arguments for command '#{primary_command_word}'"
  end
end
example(description, command) click to toggle source

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/commander/command.rb, line 50
def example(description, command)
  @examples << [description, command]
end
hidden(set = true) click to toggle source

Flags the command not to appear in general help text

# File lib/commander/command.rb, line 110
def hidden(set = true)
  @hidden ||= set
end
inspect() click to toggle source
# File lib/commander/command.rb, line 114
def inspect
  "<Commander::Command:#{name}>"
end
option(*args, default: nil, &block) click to toggle source

Add an option.

This is the legacy `option` method which now wraps `slop`

# File lib/commander/command.rb, line 60
def option(*args, default: nil, &block)
  # Split the description from the switchers
  switches, description = Runner.separate_switches_from_description(*args)

  # Other switches are normally short tags and something like below
  # In this case the VALUE needs to be ignored
  # -k VALUE
  other_switches = switches.dup.tap(&:pop).map do |string|
    string.split(' ').first
  end

  long_switch, meta = switches.last.split(' ', 2)

  # The meta flag is the VALUE from denotes if its a boolean or
  # string method
  method = meta.nil? ? :bool : :string

  # Adds the option to Slop
  slop.send(method, *other_switches, long_switch, description, default: default)
end
optional_argument_count() click to toggle source
# File lib/commander/command.rb, line 144
def optional_argument_count
  syntax_parts.select do |part|
    part[0] == '[' && part[-1] == ']'
  end.length
end
primary_command_word() click to toggle source
# File lib/commander/command.rb, line 136
def primary_command_word
  name.split.last
end
required_argument_count() click to toggle source
# File lib/commander/command.rb, line 154
def required_argument_count
  total_argument_count - optional_argument_count
end
run!(args, opts, config) click to toggle source
# File lib/commander/command.rb, line 31
def run!(args, opts, config)
  assert_correct_number_of_args!(args)
  callee = @when_called.dup
  callee.shift&.send(callee.shift || :call, args, opts, config)
end
slop() click to toggle source
# File lib/commander/command.rb, line 81
def slop
  @slop ||= Slop::Options.new
end
syntax_parts() click to toggle source
# File lib/commander/command.rb, line 128
def syntax_parts
  @syntax_parts ||= syntax.split.tap do |parts|
    while part = parts.shift do
      break if part == primary_command_word || parts.length == 0
    end
  end
end
too_few_args?(args) click to toggle source
# File lib/commander/command.rb, line 162
def too_few_args?(args)
  args.length < required_argument_count
end
too_many_args?(args) click to toggle source
# File lib/commander/command.rb, line 158
def too_many_args?(args)
  !variable_arg? && args.length > total_argument_count
end
total_argument_count() click to toggle source
# File lib/commander/command.rb, line 140
def total_argument_count
  syntax_parts.length
end
variable_arg?() click to toggle source
# File lib/commander/command.rb, line 150
def variable_arg?
  syntax_parts.any? {|part| part[-4..-1] == '...]' || part[-3..-1] == '...'}
end
when_called(*args, &block) click to toggle source

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, config|
   # do something
end

# Pass an object to handle callback (requires method symbol)
c.when_called SomeObject, :some_method
# File lib/commander/command.rb, line 100
def when_called(*args, &block)
  fail ArgumentError, 'must pass an object, class, or block.' if args.empty? && !block
  @when_called = block ? [block] : args
end
Also aliased as: action