Class: Mercenary::Command

Inherits:
Object
  • Object
show all
Defined in:
lib/mercenary/command.rb

Direct Known Subclasses

Program

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, parent = nil) ⇒ Command

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



20
21
22
23
24
25
26
27
28
 
# File 'lib/mercenary/command.rb', line 20

def initialize(name, parent = nil)
  @name     = name
  @options  = []
  @commands = {}
  @actions  = []
  @map      = {}
  @parent   = parent
  @trace    = false
end

Instance Attribute Details

#actions ⇒ Object

Returns the value of attribute actions.



8
9
10
 
# File 'lib/mercenary/command.rb', line 8

def actions
  @actions
end

#commands ⇒ Object

Returns the value of attribute commands.



7
8
9
 
# File 'lib/mercenary/command.rb', line 7

def commands
  @commands
end

#description(desc = nil) ⇒ Object (readonly)

Public: Sets or gets the command description

description - the description of what the command does (optional)

Returns the description and sets it if an argument is present



60
61
62
 
# File 'lib/mercenary/command.rb', line 60

def description
  @description
end

#map ⇒ Object (readonly)

Returns the value of attribute map.



9
10
11
 
# File 'lib/mercenary/command.rb', line 9

def map
  @map
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



3
4
5
 
# File 'lib/mercenary/command.rb', line 3

def name
  @name
end

#options ⇒ Object

Returns the value of attribute options.



6
7
8
 
# File 'lib/mercenary/command.rb', line 6

def options
  @options
end

#parent ⇒ Object

Returns the value of attribute parent.



10
11
12
 
# File 'lib/mercenary/command.rb', line 10

def parent
  @parent
end

#syntax(syntax = nil) ⇒ Object (readonly)

Public: Sets or gets the syntax string

syntax - the string which describes this command’s usage syntax (optional)

Returns the syntax string and sets it if an argument is present



45
46
47
 
# File 'lib/mercenary/command.rb', line 45

def syntax
  @syntax
end

#trace ⇒ Object (readonly)

Returns the value of attribute trace.



11
12
13
 
# File 'lib/mercenary/command.rb', line 11

def trace
  @trace
end

Instance Method Details

#action(&block) ⇒ Object

Public: Add an action Proc to be executed at runtime

block - the Proc to be executed at runtime

Returns nothing



124
125
126
 
# File 'lib/mercenary/command.rb', line 124

def action(&block)
  @actions << block
end

#add_default_options(opts) ⇒ Object

Public: Add version and help options to the command

opts - instance of OptionParser

Returns nothing



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/mercenary/command.rb', line 188

def add_default_options(opts)
  option 'show_help', '-h', '--help', 'Show this message'
  option 'show_version', '-v', '--version', 'Print the name and version'
  opts.on("-v", "--version", "Print the version") do
    puts "#{name} #{version}"
    abort
  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) ⇒ Object

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

cmd_name - the name of the alias

Returns nothing



114
115
116
117
 
# File 'lib/mercenary/command.rb', line 114

def alias(cmd_name)
  logger.debug "adding alias to parent for self: '#{cmd_name}'"
  @parent.commands[cmd_name] = self
end

#command(cmd_name) {|cmd| ... } ⇒ Object

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

Yields:

  • (cmd) 


103
104
105
106
107
 
# File 'lib/mercenary/command.rb', line 103

def command(cmd_name)
  cmd = Command.new(cmd_name, self)
  yield cmd
  @commands[cmd_name] = cmd
end

#default_command(command_name = nil) ⇒ Object

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



71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/mercenary/command.rb', line 71

def default_command(command_name = nil)
  if command_name
    if commands.has_key?(command_name)
      @default_command = commands[command_name] if command_name
      @default_command
    else
      raise ArgumentError.new("'#{command_name}' couldn't be found in this command's list of commands.")
    end
  else
    @default_command
  end
end

#execute(argv = [], config = {}) ⇒ Object

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



212
213
214
215
216
217
218
 
# File 'lib/mercenary/command.rb', line 212

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 ⇒ Object

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

its parent commands

Returns the full name of the command



248
249
250
251
252
253
 
# File 'lib/mercenary/command.rb', line 248

def full_name
  the_name = []
  the_name << parent.full_name if parent && parent.full_name
  the_name << name
  the_name.join(" ")
end

#go(argv, opts, config) ⇒ Object

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



153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/mercenary/command.rb', line 153

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) ⇒ Boolean

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

Returns:

  • (Boolean) 


226
227
228
 
# File 'lib/mercenary/command.rb', line 226

def has_command?(sub_command)
  commands.keys.include?(sub_command)
end

#ident ⇒ Object

Public: Identify this command

Returns a string which identifies this command



233
234
235
 
# File 'lib/mercenary/command.rb', line 233

def ident
  "<Command name=#{identity}>"
end

#identity ⇒ Object

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

Returns a string containing the name and version if it exists



240
241
242
 
# File 'lib/mercenary/command.rb', line 240

def identity
  "#{full_name} #{version if version}".strip
end

#logger(level = nil) ⇒ Object

Public: Fetch a Logger (stdlib)

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

Returns the instance of Logger



133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/mercenary/command.rb', line 133

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

#option(sym, *options) ⇒ Object

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



90
91
92
93
94
 
# File 'lib/mercenary/command.rb', line 90

def option(sym, *options)
  new_option = Option.new(sym, options)
  @options << new_option
  @map[new_option.hash] = sym
end

#process_options(opts, config) ⇒ Object

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



175
176
177
178
179
180
181
 
# File 'lib/mercenary/command.rb', line 175

def process_options(opts, config)
  options.each do |option|
    opts.on(*option.for_option_parser) do |x|
      config[map[option.hash]] = x
    end
  end
end

#summarize ⇒ Object

Public: Build a string containing a summary of the command

Returns a one-line summary of the command.



258
259
260
 
# File 'lib/mercenary/command.rb', line 258

def summarize
  "  #{name.to_s.ljust(20)}  #{description}"
end

#to_s ⇒ Object

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

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



265
266
267
 
# File 'lib/mercenary/command.rb', line 265

def to_s
  Presenter.new(self).print_command
end

#version(version = nil) ⇒ Object

Public: Sets or gets the command version

version - the command version (optional)

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



35
36
37
38
 
# File 'lib/mercenary/command.rb', line 35

def version(version = nil)
  @version = version if version
  @version
end