class Mercenary::Command

Attributes

actions[RW]
aliases[R]
commands[RW]
description[R]
map[R]
name[R]
options[RW]
parent[RW]
syntax[R]
trace[R]

Public Class Methods

new(name, parent = nil) click to toggle source

Public: Creates a new Command

name - the name of the command parent - (optional) the instancce of Mercenary::Command which you wish to

be the parent of this command

Returns nothing

# File lib/mercenary/command.rb, line 23
def initialize(name, parent = nil)
  @name     = name
  @options  = []
  @commands = {}
  @actions  = []
  @map      = {}
  @parent   = parent
  @trace    = false
  @aliases  = []
end

Public Instance Methods

action(&block) click to toggle source

Public: Add an action Proc to be executed at runtime

block - the Proc to be executed at runtime

Returns nothing

# File lib/mercenary/command.rb, line 127
def action(&block)
  @actions << block
end
add_default_options(opts) click to toggle source

Public: Add version and help options to the command

opts - instance of OptionParser

Returns nothing

# File lib/mercenary/command.rb, line 192
def add_default_options(opts)
  option "show_help", "-h", "--help", "Show this message"
  option "show_version", "-v", "--version", "Print the name and version"
  option "show_backtrace", "-t", "--trace", "Show the full backtrace when an error occurs"
  opts.on("-v", "--version", "Print the version") do
    puts "#{name} #{version}"
    exit(0)
  end

  opts.on("-t", "--trace", "Show full backtrace if an error occurs") do
    @trace = true
  end

  opts.on_tail("-h", "--help", "Show this message") do
    puts self
    exit
  end
end
alias(cmd_name) click to toggle source

Public: Add an alias for this command’s name to be attached to the parent

cmd_name - the name of the alias

Returns nothing

# File lib/mercenary/command.rb, line 116
def alias(cmd_name)
  logger.debug "adding alias to parent for self: '#{cmd_name}'"
  aliases << cmd_name
  @parent.commands[cmd_name] = self
end
command(cmd_name) { |cmd| ... } click to toggle source

Public: Adds a subcommand

cmd_name - the name of the command block - a block accepting the new instance of Mercenary::Command to be

modified (optional)

Returns nothing

# File lib/mercenary/command.rb, line 105
def command(cmd_name)
  cmd = Command.new(cmd_name, self)
  yield cmd
  @commands[cmd_name] = cmd
end
default_command(command_name = nil) click to toggle source

Public: Sets the default command

command_name - the command name to be executed in the event no args are

present

Returns the default command if there is one, ‘nil` otherwise

# File lib/mercenary/command.rb, line 73
def default_command(command_name = nil)
  if command_name
    if commands.key?(command_name)
      @default_command = commands[command_name] if command_name
      @default_command
    else
      raise ArgumentError, "'#{command_name}' couldn't be found in this command's list of commands."
    end
  else
    @default_command
  end
end
execute(argv = [], config = {}) click to toggle source

Public: Execute all actions given the inputted args and options

argv - (optional) command-line args (sans opts) config - (optional) the Hash configuration of string key to value

Returns nothing

# File lib/mercenary/command.rb, line 217
def execute(argv = [], config = {})
  if actions.empty? && !default_command.nil?
    default_command.execute
  else
    actions.each { |a| a.call(argv, config) }
  end
end
full_name() click to toggle source

Public: Get the name of the current command plus that of

its parent commands

Returns the full name of the command

# File lib/mercenary/command.rb, line 253
def full_name
  the_name = []
  the_name << parent.full_name if parent&.full_name
  the_name << name
  the_name.join(" ")
end
go(argv, opts, config) click to toggle source

Public: Run the command

argv - an array of string args opts - the instance of OptionParser config - the output config hash

Returns the command to be executed

# File lib/mercenary/command.rb, line 157
def go(argv, opts, config)
  opts.banner = "Usage: #{syntax}"
  process_options(opts, config)
  add_default_options(opts)

  if argv[0] && cmd = commands[argv[0].to_sym]
    logger.debug "Found subcommand '#{cmd.name}'"
    argv.shift
    cmd.go(argv, opts, config)
  else
    logger.debug "No additional command found, time to exec"
    self
  end
end
has_command?(sub_command) click to toggle source

Public: Check if this command has a subcommand

sub_command - the name of the subcommand

Returns true if this command is the parent of a command of name ‘sub_command’ and false otherwise

# File lib/mercenary/command.rb, line 231
def has_command?(sub_command)
  commands.key?(sub_command)
end
ident() click to toggle source

Public: Identify this command

Returns a string which identifies this command

# File lib/mercenary/command.rb, line 238
def ident
  "<Command name=#{identity}>"
end
identity() click to toggle source

Public: Get the full identity (name & version) of this command

Returns a string containing the name and version if it exists

# File lib/mercenary/command.rb, line 245
def identity
  "#{full_name} #{version}".strip
end
logger(level = nil) click to toggle source

Public: Fetch a Logger (stdlib)

level - the logger level (a Logger constant, see docs for more info)

Returns the instance of Logger

# File lib/mercenary/command.rb, line 137
def logger(level = nil)
  unless @logger
    @logger = Logger.new(STDOUT)
    @logger.level = level || Logger::INFO
    @logger.formatter = proc do |severity, _datetime, _progname, msg|
      "#{identity} | " << "#{severity.downcase.capitalize}:".ljust(7) << " #{msg}\n"
    end
  end

  @logger.level = level unless level.nil?
  @logger
end
names_and_aliases() click to toggle source

Public: Return all the names and aliases for this command.

Returns a comma-separated String list of the name followed by its aliases

# File lib/mercenary/command.rb, line 263
def names_and_aliases
  ([name.to_s] + aliases).compact.join(", ")
end
option(sym, *options) click to toggle source

Public: Adds an option switch

sym - the variable key which is used to identify the value of the switch

at runtime in the options hash

Returns nothing

# File lib/mercenary/command.rb, line 92
def option(sym, *options)
  new_option = Option.new(sym, options)
  @options << new_option
  @map[new_option] = sym
end
process_options(opts, config) click to toggle source

Public: Add this command’s options to OptionParser and set a default

action of setting the value of the option to the inputted hash

opts - instance of OptionParser config - the Hash in which the option values should be placed

Returns nothing

# File lib/mercenary/command.rb, line 179
def process_options(opts, config)
  options.each do |option|
    opts.on(*option.for_option_parser) do |x|
      config[map[option]] = x
    end
  end
end
summarize() click to toggle source

Public: Build a string containing a summary of the command

Returns a one-line summary of the command.

# File lib/mercenary/command.rb, line 270
def summarize
  "  #{names_and_aliases.ljust(20)}  #{description}"
end
to_s() click to toggle source

Public: Build a string containing the command name, options and any subcommands

Returns the string identifying this command, its options and its subcommands

# File lib/mercenary/command.rb, line 277
def to_s
  Presenter.new(self).print_command
end
version(version = nil) click to toggle source

Public: Sets or gets the command version

version - the command version (optional)

Returns the version and sets it if an argument is non-nil

# File lib/mercenary/command.rb, line 39
def version(version = nil)
  @version = version if version
  @version
end