Class: MCollective::Application
- Inherits:
-
Object
- Object
- MCollective::Application
- Includes:
- RPC
- Defined in:
- lib/mcollective/application.rb
Class Method Summary collapse
-
.[](option) ⇒ Object
retrieves a specific option.
-
.[]=(option, value) ⇒ Object
set an option in the options hash.
-
.application_options ⇒ Object
Intialize a blank set of options if its the first time used else returns active options.
-
.description(descr) ⇒ Object
Sets the application description, there can be only one description per application so multiple calls will just change the description.
- .exclude_argument_sections(*sections) ⇒ Object
-
.intialize_application_options ⇒ Object
Creates an empty set of options.
-
.option(name, arguments) ⇒ Object
Wrapper to create command line options.
-
.usage(usage) ⇒ Object
Supplies usage information, calling multiple times will create multiple usage lines in –help output.
Instance Method Summary collapse
-
#application_cli_arguments ⇒ Object
Returns an array of all the arguments built using calls to optin.
-
#application_description ⇒ Object
Retrieve the current application description.
-
#application_failure(e, err_dest = STDERR) ⇒ Object
Handles failure, if we’re far enough in the initialization phase it will log backtraces if its in verbose mode only.
-
#application_options ⇒ Object
Retrieves the full hash of application options.
-
#application_parse_options(help = false) ⇒ Object
Builds an ObjectParser config, parse the CLI options and validates based on the option config.
-
#application_usage ⇒ Object
Return the current usage text false if nothing is set.
-
#clioptions(help) ⇒ Object
Creates a standard options hash, pass in a block to add extra headings etc see Optionparser.
-
#configuration ⇒ Object
The application configuration built from CLI arguments.
- #disconnect ⇒ Object
-
#halt(stats) ⇒ Object
A helper that creates a consistent exit code for applications by looking at an instance of MCollective::RPC::Stats.
- #help ⇒ Object
-
#main ⇒ Object
Fake abstract class that logs if the user tries to use an application without supplying a main override method.
-
#options ⇒ Object
The active options hash used for MC::Client and other configuration.
-
#rpcclient(agent, flags = {}) ⇒ Object
Wrapper around MC::RPC#rpcclient that forcably supplies our options hash if someone forgets to pass in options in an application the filters and other cli options wouldnt take effect which could have a disasterous outcome.
-
#run ⇒ Object
The main logic loop, builds up the options, validate configuration and calls the main as supplied by the user.
- #validate_cli_options ⇒ Object
-
#validate_option(blk, name, value) ⇒ Object
Calls the supplied block in an option for validation, an error raised will log to STDERR and exit the application.
Methods included from RPC
discovered, #empty_filter?, #printrpc, #printrpcstats, reply, request, #rpcoptions, stats
Class Method Details
.[](option) ⇒ Object
retrieves a specific option
20 21 22 23 |
# File 'lib/mcollective/application.rb', line 20 def [](option) unless @application_options @application_options[option] end |
.[]=(option, value) ⇒ Object
set an option in the options hash
14 15 16 17 |
# File 'lib/mcollective/application.rb', line 14 def []=(option, value) unless @application_options @application_options[option] = value end |
.application_options ⇒ Object
Intialize a blank set of options if its the first time used else returns active options
8 9 10 11 |
# File 'lib/mcollective/application.rb', line 8 def unless @application_options @application_options end |
.description(descr) ⇒ Object
Sets the application description, there can be only one description per application so multiple calls will just change the description
28 29 30 |
# File 'lib/mcollective/application.rb', line 28 def description(descr) self[:description] = descr end |
.exclude_argument_sections(*sections) ⇒ Object
38 39 40 41 42 43 44 45 46 47 |
# File 'lib/mcollective/application.rb', line 38 def exclude_argument_sections(*sections) sections = [sections].flatten sections.each do |s| raise "Unknown CLI argument section #{s}" unless ["rpc", "common", "filter"].include?(s) end unless @application_options self[:exclude_arg_sections] = sections end |
.intialize_application_options ⇒ Object
Creates an empty set of options
79 80 81 82 83 84 |
# File 'lib/mcollective/application.rb', line 79 def @application_options = {:description => nil, :usage => [], :cli_arguments => [], :exclude_arg_sections => []} end |
.option(name, arguments) ⇒ Object
Wrapper to create command line options
- name: varaible name that will be used to access the option value
- description: textual info shown in --help
- arguments: a list of possible arguments that can be used
to activate this option
- type: a data type that ObjectParser understand of :bool or :array
- required: true or false if this option has to be supplied
- validate: a proc that will be called with the value used to validate
the supplied value
option :foo,
:description => "The foo option"
:arguments => ["--foo ARG"]
after this the value supplied will be in configuration
65 66 67 68 69 70 71 72 73 74 75 76 |
# File 'lib/mcollective/application.rb', line 65 def option(name, arguments) opt = {:name => name, :description => nil, :arguments => [], :type => String, :required => false, :validate => Proc.new { true }} arguments.each_pair{|k,v| opt[k] = v} self[:cli_arguments] << opt end |
.usage(usage) ⇒ Object
Supplies usage information, calling multiple times will create multiple usage lines in –help output
34 35 36 |
# File 'lib/mcollective/application.rb', line 34 def usage(usage) self[:usage] << usage end |
Instance Method Details
#application_cli_arguments ⇒ Object
Returns an array of all the arguments built using calls to optin
245 246 247 |
# File 'lib/mcollective/application.rb', line 245 def application_cli_arguments [:cli_arguments] end |
#application_description ⇒ Object
Retrieve the current application description
232 233 234 |
# File 'lib/mcollective/application.rb', line 232 def application_description [:description] end |
#application_failure(e, err_dest = STDERR) ⇒ Object
Handles failure, if we’re far enough in the initialization phase it will log backtraces if its in verbose mode only
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 |
# File 'lib/mcollective/application.rb', line 251 def application_failure(e, err_dest=STDERR) # peole can use exit() anywhere and not get nasty backtraces as a result if e.is_a?(SystemExit) disconnect raise(e) end err_dest.puts "#{$0} failed to run: #{e} (#{e.class})" if .nil? || [:verbose] e.backtrace.each{|l| err_dest.puts "\tfrom #{l}"} end disconnect exit 1 end |
#application_options ⇒ Object
Retrieves the full hash of application options
227 228 229 |
# File 'lib/mcollective/application.rb', line 227 def self.class. end |
#application_parse_options(help = false) ⇒ Object
Builds an ObjectParser config, parse the CLI options and validates based on the option config
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 |
# File 'lib/mcollective/application.rb', line 135 def (help=false) @options ||= {:verbose => false} @options = (help) do |parser, | parser.define_head application_description if application_description parser. = "" if application_usage parser.separator "" application_usage.each do |u| parser.separator "Usage: #{u}" end parser.separator "" end parser.define_tail "" parser.define_tail "The Marionette Collective #{MCollective.version}" application_cli_arguments.each do |carg| opts_array = [] opts_array << :on # if a default is set from the application set it up front if carg.include?(:default) configuration[carg[:name]] = carg[:default] end # :arguments are multiple possible ones if carg[:arguments].is_a?(Array) carg[:arguments].each {|a| opts_array << a} else opts_array << carg[:arguments] end # type was given and its not one of our special types, just pass it onto optparse opts_array << carg[:type] if carg[:type] and ! [:bool, :array].include?(carg[:type]) opts_array << carg[:description] # Handle our special types else just rely on the optparser to handle the types if carg[:type] == :bool parser.send(*opts_array) do |v| validate_option(carg[:validate], carg[:name], v) configuration[carg[:name]] = true end elsif carg[:type] == :array parser.send(*opts_array) do |v| validate_option(carg[:validate], carg[:name], v) configuration[carg[:name]] = [] unless configuration.include?(carg[:name]) configuration[carg[:name]] << v end else parser.send(*opts_array) do |v| validate_option(carg[:validate], carg[:name], v) configuration[carg[:name]] = v end end end end end |
#application_usage ⇒ Object
Return the current usage text false if nothing is set
237 238 239 240 241 |
# File 'lib/mcollective/application.rb', line 237 def application_usage usage = [:usage] usage.empty? ? false : usage end |
#clioptions(help) ⇒ Object
Creates a standard options hash, pass in a block to add extra headings etc see Optionparser
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 |
# File 'lib/mcollective/application.rb', line 111 def (help) oparser = Optionparser.new({:verbose => false, :progress_bar => true}, "filter", [:exclude_arg_sections]) = oparser.parse do |parser, | if block_given? yield(parser, ) end RPC::Helpers.(parser, ) unless [:exclude_arg_sections].include?("rpc") end return oparser.parser.help if help post_option_parser(configuration) if respond_to?(:post_option_parser) return rescue Exception => e application_failure(e) end |
#configuration ⇒ Object
The application configuration built from CLI arguments
88 89 90 91 |
# File 'lib/mcollective/application.rb', line 88 def configuration @application_configuration ||= {} @application_configuration end |
#disconnect ⇒ Object
291 292 293 294 |
# File 'lib/mcollective/application.rb', line 291 def disconnect MCollective::PluginManager["connector_plugin"].disconnect rescue end |
#halt(stats) ⇒ Object
A helper that creates a consistent exit code for applications by looking at an instance of MCollective::RPC::Stats
Exit with 0 if nodes were discovered and all passed Exit with 0 if no discovery were done and > 0 responses were received Exit with 1 if no nodes were discovered Exit with 2 if nodes were discovered but some RPC requests failed Exit with 3 if nodes were discovered, but not responses receivedif Exit with 4 if no discovery were done and no responses were received
312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 |
# File 'lib/mcollective/application.rb', line 312 def halt(stats) request_stats = {:discoverytime => 0, :discovered => 0, :failcount => 0}.merge(stats.to_hash) # was discovery done? if request_stats[:discoverytime] != 0 # was any nodes discovered if request_stats[:discovered] == 0 exit 1 # nodes were discovered, did we get responses elsif request_stats[:responses] == 0 exit 3 else # we got responses and discovery was done, no failures if request_stats[:failcount] == 0 exit 0 else exit 2 end end else # discovery wasnt done and we got no responses if request_stats[:responses] == 0 exit 4 else exit 0 end end end |
#help ⇒ Object
269 270 271 |
# File 'lib/mcollective/application.rb', line 269 def help (true) end |
#main ⇒ Object
Fake abstract class that logs if the user tries to use an application without supplying a main override method.
298 299 300 301 |
# File 'lib/mcollective/application.rb', line 298 def main STDERR.puts "Applications need to supply a 'main' method" exit 1 end |
#options ⇒ Object
The active options hash used for MC::Client and other configuration
94 95 96 |
# File 'lib/mcollective/application.rb', line 94 def @options end |
#rpcclient(agent, flags = {}) ⇒ Object
Wrapper around MC::RPC#rpcclient that forcably supplies our options hash if someone forgets to pass in options in an application the filters and other cli options wouldnt take effect which could have a disasterous outcome
348 349 350 351 352 |
# File 'lib/mcollective/application.rb', line 348 def rpcclient(agent, flags = {}) flags[:options] = unless flags.include?(:options) super end |
#run ⇒ Object
The main logic loop, builds up the options, validate configuration and calls the main as supplied by the user. Disconnects when done and pass any exception onto the application_failure helper
276 277 278 279 280 281 282 283 284 285 286 287 288 289 |
# File 'lib/mcollective/application.rb', line 276 def run validate_configuration(configuration) if respond_to?(:validate_configuration) Util.setup_windows_sleeper if Util.windows? main disconnect rescue Exception => e application_failure(e) end |
#validate_cli_options ⇒ Object
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 |
# File 'lib/mcollective/application.rb', line 205 def # Check all required parameters were set validation_passed = true application_cli_arguments.each do |carg| # Check for required arguments if carg[:required] unless configuration[ carg[:name] ] validation_passed = false STDERR.puts "The #{carg[:name]} option is mandatory" end end end unless validation_passed STDERR.puts "\nPlease run with --help for detailed help" exit 1 end end |
#validate_option(blk, name, value) ⇒ Object
Calls the supplied block in an option for validation, an error raised will log to STDERR and exit the application
100 101 102 103 104 105 106 107 |
# File 'lib/mcollective/application.rb', line 100 def validate_option(blk, name, value) validation_result = blk.call(value) unless validation_result == true STDERR.puts "Validation of #{name} failed: #{validation_result}" exit 1 end end |