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]