Class MCollective::Application
In: lib/mcollective/application.rb
Parent: Object

Methods

Included Modules

RPC

Public Class methods

retrieves a specific option

[Source]

    # File lib/mcollective/application.rb, line 20
20:             def [](option)
21:                 intialize_application_options unless @application_options
22:                 @application_options[option]
23:             end

set an option in the options hash

[Source]

    # File lib/mcollective/application.rb, line 14
14:             def []=(option, value)
15:                 intialize_application_options unless @application_options
16:                 @application_options[option] = value
17:             end

Intialize a blank set of options if its the first time used else returns active options

[Source]

    # File lib/mcollective/application.rb, line 8
 8:             def application_options
 9:                 intialize_application_options unless @application_options
10:                 @application_options
11:             end

Sets the application description, there can be only one description per application so multiple calls will just change the description

[Source]

    # File lib/mcollective/application.rb, line 28
28:             def description(descr)
29:                 self[:description] = descr
30:             end

Creates an empty set of options

[Source]

    # File lib/mcollective/application.rb, line 68
68:             def intialize_application_options
69:                 @application_options = {:description   => nil,
70:                                         :usage         => [],
71:                                         :cli_arguments => []}
72:             end

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[:foo]

[Source]

    # File lib/mcollective/application.rb, line 54
54:             def option(name, arguments)
55:                 opt = {:name => name,
56:                        :description => nil,
57:                        :arguments => [],
58:                        :type => String,
59:                        :required => false,
60:                        :validate => Proc.new { true }}
61: 
62:                 arguments.each_pair{|k,v| opt[k] = v}
63: 
64:                 self[:cli_arguments] << opt
65:             end

Supplies usage information, calling multiple times will create multiple usage lines in —help output

[Source]

    # File lib/mcollective/application.rb, line 34
34:             def usage(usage)
35:                 self[:usage] << usage
36:             end

Public Instance methods

Returns an array of all the arguments built using calls to optin

[Source]

     # File lib/mcollective/application.rb, line 204
204:         def application_cli_arguments
205:             self.class.application_options[:cli_arguments]
206:         end

Retrieve the current application description

[Source]

     # File lib/mcollective/application.rb, line 191
191:         def application_description
192:             self.class.application_options[:description]
193:         end

Handles failure, if we‘re far enough in the initialization phase it will log backtraces if its in verbose mode only

[Source]

     # File lib/mcollective/application.rb, line 210
210:         def application_failure(e)
211:             STDERR.puts "#{$0} failed to run: #{e} (#{e.class})"
212: 
213:             if options
214:                 e.backtrace.each{|l| STDERR.puts "\tfrom #{l}"} if options[:verbose]
215:             else
216:                 e.backtrace.each{|l| STDERR.puts "\tfrom #{l}"}
217:             end
218: 
219:             disconnect
220: 
221:             exit 1
222:         end

Builds an ObjectParser config, parse the CLI options and validates based on the option config

[Source]

     # File lib/mcollective/application.rb, line 99
 99:         def application_parse_options
100:             @options ||= {:verbose => false}
101: 
102:             @options = rpcoptions do |parser, options|
103:                 parser.define_head application_description if application_description
104:                 parser.banner = ""
105: 
106:                 if application_usage
107:                     parser.separator ""
108: 
109:                     application_usage.each do |u|
110:                         parser.separator "Usage: #{u}"
111:                     end
112: 
113:                     parser.separator ""
114:                 end
115: 
116:                 parser.define_tail ""
117:                 parser.define_tail "The Marionette Collective #{MCollective.version}"
118: 
119: 
120:                 application_cli_arguments.each do |carg|
121:                     opts_array = []
122: 
123:                     opts_array << :on
124: 
125:                     # if a default is set from the application set it up front
126:                     if carg.include?(:default)
127:                         configuration[carg[:name]] = carg[:default]
128:                     end
129: 
130:                     # :arguments are multiple possible ones
131:                     if carg[:arguments].is_a?(Array)
132:                         carg[:arguments].each {|a| opts_array << a}
133:                     else
134:                         opts_array << carg[:arguments]
135:                     end
136: 
137:                     # type was given and its not one of our special types, just pass it onto optparse
138:                     opts_array << carg[:type] if carg[:type] and ! [:bool, :array].include?(carg[:type])
139: 
140:                     opts_array << carg[:description]
141: 
142:                     # Handle our special types else just rely on the optparser to handle the types
143:                     if carg[:type] == :bool
144:                         parser.send(*opts_array) do |v|
145:                             validate_option(carg[:validate], carg[:name], v)
146: 
147:                             configuration[carg[:name]] = true
148:                         end
149: 
150:                     elsif carg[:type] == :array
151:                         parser.send(*opts_array) do |v|
152:                             validate_option(carg[:validate], carg[:name], v)
153: 
154:                             configuration[carg[:name]] = [] unless configuration.include?(carg[:name])
155:                             configuration[carg[:name]] << v
156:                         end
157: 
158:                     else
159:                         parser.send(*opts_array) do |v|
160:                             validate_option(carg[:validate], carg[:name], v)
161: 
162:                             configuration[carg[:name]] = v
163:                         end
164:                     end
165:                 end
166:             end
167: 
168:             # Check all required parameters were set
169:             validation_passed = true
170:             application_cli_arguments.each do |carg|
171:                 # Check for required arguments
172:                 if carg[:required]
173:                     unless configuration[ carg[:name] ]
174:                         validation_passed = false
175:                         STDERR.puts "The #{carg[:name]} option is mandatory"
176:                     end
177:                 end
178:             end
179: 
180:             unless validation_passed
181:                 STDERR.puts "\nPlease run with --help for detailed help"
182:                 exit 1
183:             end
184: 
185:             post_option_parser(configuration) if respond_to?(:post_option_parser)
186:         rescue Exception => e
187:             application_failure(e)
188:         end

Return the current usage text false if nothing is set

[Source]

     # File lib/mcollective/application.rb, line 196
196:         def application_usage
197:             usage = self.class.application_options[:usage]
198: 
199:             usage.empty? ? false : usage
200:         end

The application configuration built from CLI arguments

[Source]

    # File lib/mcollective/application.rb, line 76
76:         def configuration
77:             @application_configuration ||= {}
78:             @application_configuration
79:         end

[Source]

     # File lib/mcollective/application.rb, line 243
243:         def disconnect
244:             MCollective::PluginManager["connector_plugin"].disconnect
245:         rescue
246:         end

Fake abstract class that logs if the user tries to use an application without supplying a main override method.

[Source]

     # File lib/mcollective/application.rb, line 250
250:         def main
251:             STDERR.puts "Applications need to supply a 'main' method"
252:             exit 1
253:         end

The active options hash used for MC::Client and other configuration

[Source]

    # File lib/mcollective/application.rb, line 82
82:         def options
83:             @options
84:         end

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

[Source]

     # File lib/mcollective/application.rb, line 258
258:         def rpcclient(agent, flags = {})
259:             flags[:options] = options unless flags.include?(:options)
260: 
261:             super
262:         end

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

[Source]

     # File lib/mcollective/application.rb, line 227
227:         def run
228:             application_parse_options
229: 
230:             validate_configuration(configuration) if respond_to?(:validate_configuration)
231: 
232:             main
233: 
234:             disconnect
235: 
236:         rescue SystemExit
237:             disconnect
238:             raise
239:         rescue Exception => e
240:             application_failure(e)
241:         end

Calls the supplied block in an option for validation, an error raised will log to STDERR and exit the application

[Source]

    # File lib/mcollective/application.rb, line 88
88:         def validate_option(blk, name, value)
89:             validation_result = blk.call(value)
90: 
91:             unless validation_result == true
92:                 STDERR.puts "Validation of #{name} failed: #{validation_result}"
93:                 exit 1
94:             end
95:         end

[Validate]