3 # The base class for all kinds of DDL files. DDL files when
4 # run gets parsed and builds up a hash of the basic primitive
5 # types, ideally restricted so it can be converted to JSON though
6 # today there are some Ruby Symbols in them which might be fixed
9 # The Hash being built should be stored in @entities, the format
10 # is generally not prescribed but there's a definite feel to how
11 # DDL files look so study the agent and discovery ones to see how
12 # the structure applies to very different use cases.
14 # For every plugin type you should have a single word name - that
15 # corresponds to the directory in the libdir where these plugins
16 # live. If you need anything above and beyond 'metadata' in your
17 # plugin DDL then add a PlugintypeDDL class here and add your
18 # specific behaviors to those.
22 attr_reader :meta, :entities, :pluginname, :plugintype, :usage, :requirements
24 def initialize(plugin, plugintype=:agent, loadddl=true)
28 @config = Config.instance
30 @plugintype = plugintype.to_sym
33 loadddlfile if loadddl
36 # Generates help using the template based on the data
37 # created with metadata and input.
39 # If no template name is provided one will be chosen based
40 # on the plugin type. If the provided template path is
41 # not absolute then the template will be loaded relative to
42 # helptemplatedir configuration parameter
43 def help(template=nil)
44 template = template_for_plugintype unless template
45 template = File.join(@config.helptemplatedir, template) unless template.start_with?(File::SEPARATOR)
47 template = File.read(template)
51 unless template == "metadata-help.erb"
52 metadata_template = File.join(@config.helptemplatedir, "metadata-help.erb")
53 metadata_template = File.read(metadata_template)
54 metastring = ERB.new(metadata_template, 0, '%')
55 metastring = metastring.result(binding)
58 erb = ERB.new(template, 0, '%')
66 def template_for_plugintype
71 if File.exists?(File.join(@config.helptemplatedir,"#{@plugintype}-help.erb"))
72 return "#{@plugintype}-help.erb"
74 # Default help template gets loaded if plugintype-help does not exist.
75 return "metadata-help.erb"
81 if ddlfile = findddlfile
82 instance_eval(File.read(ddlfile), ddlfile, 1)
84 raise_code(:PLMC40, "Can't find DDL for %{type} plugin '%{name}'", :debug, :type => @plugintype, :name => @pluginname)
88 def findddlfile(ddlname=nil, ddltype=nil)
89 ddlname = @pluginname unless ddlname
90 ddltype = @plugintype unless ddltype
92 @config.libdir.each do |libdir|
93 ddlfile = File.join([libdir, "mcollective", ddltype.to_s, "#{ddlname}.ddl"])
94 if File.exist?(ddlfile)
95 log_code(:PLMC18, "Found %{ddlname} ddl at %{ddlfile}", :debug, :ddlname => ddlname, :ddlfile => ddlfile)
102 def validate_requirements
103 if requirement = @requirements[:mcollective]
104 if Util.mcollective_version == "@DEVELOPMENT_VERSION@"
105 log_code(:PLMC19, "DDL requirements validation being skipped in development", :warn)
109 if Util.versioncmp(Util.mcollective_version, requirement) < 0
110 DDL.validation_fail!(:PLMC20, "%{type} plugin '%{name}' requires MCollective version %{requirement} or newer", :debug, :type => @plugintype.to_s.capitalize, :name => @pluginname, :requirement => requirement)
117 # validate strings, lists and booleans, we'll add more types of validators when
118 # all the use cases are clear
120 # only does validation for arguments actually given, since some might
121 # be optional. We validate the presense of the argument earlier so
122 # this is a safe assumption, just to skip them.
124 # :string can have maxlength and regex. A maxlength of 0 will bypasss checks
125 # :list has a array of valid values
126 def validate_input_argument(input, key, argument)
127 Validator.load_validators
129 case input[key][:type]
131 Validator.validate(argument, :string)
133 Validator.length(argument, input[key][:maxlength].to_i)
135 Validator.validate(argument, input[key][:validation])
138 Validator.validate(argument, input[key][:list])
141 Validator.validate(argument, input[key][:type])
146 DDL.validation_fail!(:PLMC21, "Cannot validate input '%{input}': %{error}", :debug, :input => key, :error => e.to_s)
149 # Registers an input argument for a given action
151 # See the documentation for action for how to use this
152 def input(argument, properties)
153 raise_code(:PLMC22, "Cannot determine what entity input '%{entity}' belongs to", :error, :entity => @current_entity) unless @current_entity
155 entity = @current_entity
157 [:prompt, :description, :type].each do |arg|
158 raise_code(:PLMC23, "Input needs a :%{property} property", :debug, :property => arg) unless properties.include?(arg)
161 @entities[entity][:input][argument] = {:prompt => properties[:prompt],
162 :description => properties[:description],
163 :type => properties[:type],
164 :default => properties[:default],
165 :optional => properties[:optional]}
167 case properties[:type]
169 raise "Input type :string needs a :validation argument" unless properties.include?(:validation)
170 raise "Input type :string needs a :maxlength argument" unless properties.include?(:maxlength)
172 @entities[entity][:input][argument][:validation] = properties[:validation]
173 @entities[entity][:input][argument][:maxlength] = properties[:maxlength]
176 raise "Input type :list needs a :list argument" unless properties.include?(:list)
178 @entities[entity][:input][argument][:list] = properties[:list]
182 # Registers an output argument for a given action
184 # See the documentation for action for how to use this
185 def output(argument, properties)
186 raise "Cannot figure out what action input #{argument} belongs to" unless @current_entity
187 raise "Output #{argument} needs a description argument" unless properties.include?(:description)
188 raise "Output #{argument} needs a display_as argument" unless properties.include?(:display_as)
190 action = @current_entity
192 @entities[action][:output][argument] = {:description => properties[:description],
193 :display_as => properties[:display_as],
194 :default => properties[:default]}
197 def requires(requirement)
198 raise "Requirement should be a hash in the form :item => 'requirement'" unless requirement.is_a?(Hash)
200 valid_requirements = [:mcollective]
202 requirement.keys.each do |key|
203 unless valid_requirements.include?(key)
204 raise "Requirement %s is not a valid requirement, only %s is supported" % [key, valid_requirements.join(", ")]
207 @requirements[key] = requirement[key]
210 validate_requirements
213 # Registers meta data for the introspection hash
215 [:name, :description, :author, :license, :version, :url, :timeout].each do |arg|
216 raise "Metadata needs a :#{arg} property" unless meta.include?(arg)