| Class | MCollective::DDL::Base |
| In: |
lib/mcollective/ddl/base.rb
|
| Parent: | Object |
The base class for all kinds of DDL files. DDL files when run gets parsed and builds up a hash of the basic primitive types, ideally restricted so it can be converted to JSON though today there are some Ruby Symbols in them which might be fixed laster on.
The Hash being built should be stored in @entities, the format is generally not prescribed but there‘s a definite feel to how DDL files look so study the agent and discovery ones to see how the structure applies to very different use cases.
For every plugin type you should have a single word name - that corresponds to the directory in the libdir where these plugins live. If you need anything above and beyond ‘metadata’ in your plugin DDL then add a PlugintypeDDL class here and add your specific behaviors to those.
| entities | [R] | |
| meta | [R] | |
| pluginname | [R] | |
| plugintype | [R] | |
| requirements | [R] | |
| usage | [R] |
# File lib/mcollective/ddl/base.rb, line 24
24: def initialize(plugin, plugintype=:agent, loadddl=true)
25: @entities = {}
26: @meta = {}
27: @usage = ""
28: @config = Config.instance
29: @pluginname = plugin
30: @plugintype = plugintype.to_sym
31: @requirements = {}
32:
33: loadddlfile if loadddl
34: end
# File lib/mcollective/ddl/base.rb, line 89
89: def findddlfile(ddlname=nil, ddltype=nil)
90: ddlname = @pluginname unless ddlname
91: ddltype = @plugintype unless ddltype
92:
93: @config.libdir.each do |libdir|
94: ddlfile = File.join([libdir, "mcollective", ddltype.to_s, "#{ddlname}.ddl"])
95: if File.exist?(ddlfile)
96: log_code(:PLMC18, "Found %{ddlname} ddl at %{ddlfile}", :debug, :ddlname => ddlname, :ddlfile => ddlfile)
97: return ddlfile
98: end
99: end
100: return false
101: end
Generates help using the template based on the data created with metadata and input.
If no template name is provided one will be chosen based on the plugin type. If the provided template path is not absolute then the template will be loaded either from the config dir and if that does not exist, default to /etc/mcollective
# File lib/mcollective/ddl/base.rb, line 44
44: def help(template=nil)
45: template = template_for_plugintype unless template
46: template = Util.templatepath(template) unless Util.absolute_path?(template)
47:
48: template = File.read(template)
49: meta = @meta
50: entities = @entities
51:
52: unless template == "metadata-help.erb"
53: metadata_template = Util.templatepath("metadata-help.erb")
54: metadata_template = File.read(metadata_template)
55: metastring = ERB.new(metadata_template, 0, '%')
56: metastring = metastring.result(binding)
57: end
58:
59: erb = ERB.new(template, 0, '%')
60: erb.result(binding)
61: end
Registers an input argument for a given action
See the documentation for action for how to use this
# File lib/mcollective/ddl/base.rb, line 153
153: def input(argument, properties)
154: raise_code(:PLMC22, "Cannot determine what entity input '%{entity}' belongs to", :error, :entity => @current_entity) unless @current_entity
155:
156: entity = @current_entity
157:
158: [:prompt, :description, :type].each do |arg|
159: raise_code(:PLMC23, "Input needs a :%{property} property", :debug, :property => arg) unless properties.include?(arg)
160: end
161:
162: @entities[entity][:input][argument] = {:prompt => properties[:prompt],
163: :description => properties[:description],
164: :type => properties[:type],
165: :default => properties[:default],
166: :optional => properties[:optional]}
167:
168: case properties[:type]
169: when :string
170: raise "Input type :string needs a :validation argument" unless properties.include?(:validation)
171: raise "Input type :string needs a :maxlength argument" unless properties.include?(:maxlength)
172:
173: @entities[entity][:input][argument][:validation] = properties[:validation]
174: @entities[entity][:input][argument][:maxlength] = properties[:maxlength]
175:
176: when :list
177: raise "Input type :list needs a :list argument" unless properties.include?(:list)
178:
179: @entities[entity][:input][argument][:list] = properties[:list]
180: end
181: end
# File lib/mcollective/ddl/base.rb, line 81
81: def loadddlfile
82: if ddlfile = findddlfile
83: instance_eval(File.read(ddlfile), ddlfile, 1)
84: else
85: raise_code(:PLMC40, "Can't find DDL for %{type} plugin '%{name}'", :debug, :type => @plugintype, :name => @pluginname)
86: end
87: end
Registers meta data for the introspection hash
# File lib/mcollective/ddl/base.rb, line 215
215: def metadata(meta)
216: [:name, :description, :author, :license, :version, :url, :timeout].each do |arg|
217: raise "Metadata needs a :#{arg} property" unless meta.include?(arg)
218: end
219:
220: @meta = meta
221: end
Registers an output argument for a given action
See the documentation for action for how to use this
# File lib/mcollective/ddl/base.rb, line 186
186: def output(argument, properties)
187: raise "Cannot figure out what action input #{argument} belongs to" unless @current_entity
188: raise "Output #{argument} needs a description argument" unless properties.include?(:description)
189: raise "Output #{argument} needs a display_as argument" unless properties.include?(:display_as)
190:
191: action = @current_entity
192:
193: @entities[action][:output][argument] = {:description => properties[:description],
194: :display_as => properties[:display_as],
195: :default => properties[:default]}
196: end
# File lib/mcollective/ddl/base.rb, line 198
198: def requires(requirement)
199: raise "Requirement should be a hash in the form :item => 'requirement'" unless requirement.is_a?(Hash)
200:
201: valid_requirements = [:mcollective]
202:
203: requirement.keys.each do |key|
204: unless valid_requirements.include?(key)
205: raise "Requirement %s is not a valid requirement, only %s is supported" % [key, valid_requirements.join(", ")]
206: end
207:
208: @requirements[key] = requirement[key]
209: end
210:
211: validate_requirements
212: end
# File lib/mcollective/ddl/base.rb, line 67
67: def template_for_plugintype
68: case @plugintype
69: when :agent
70: return "rpc-help.erb"
71: else
72: if File.exists?(Util.templatepath("#{@plugintype}-help.erb"))
73: return "#{@plugintype}-help.erb"
74: else
75: # Default help template gets loaded if plugintype-help does not exist.
76: return "metadata-help.erb"
77: end
78: end
79: end
# File lib/mcollective/ddl/base.rb, line 63
63: def usage(usage_text)
64: @usage = usage_text
65: end
validate strings, lists and booleans, we‘ll add more types of validators when all the use cases are clear
only does validation for arguments actually given, since some might be optional. We validate the presense of the argument earlier so this is a safe assumption, just to skip them.
:string can have maxlength and regex. A maxlength of 0 will bypasss checks :list has a array of valid values
# File lib/mcollective/ddl/base.rb, line 127
127: def validate_input_argument(input, key, argument)
128: Validator.load_validators
129:
130: case input[key][:type]
131: when :string
132: Validator.validate(argument, :string)
133:
134: Validator.length(argument, input[key][:maxlength].to_i)
135:
136: Validator.validate(argument, input[key][:validation])
137:
138: when :list
139: Validator.validate(argument, input[key][:list])
140:
141: else
142: Validator.validate(argument, input[key][:type])
143: end
144:
145: return true
146: rescue => e
147: DDL.validation_fail!(:PLMC21, "Cannot validate input '%{input}': %{error}", :debug, :input => key, :error => e.to_s)
148: end
# File lib/mcollective/ddl/base.rb, line 103
103: def validate_requirements
104: if requirement = @requirements[:mcollective]
105: if Util.mcollective_version == "@DEVELOPMENT_VERSION@"
106: log_code(:PLMC19, "DDL requirements validation being skipped in development", :warn)
107: return true
108: end
109:
110: if Util.versioncmp(Util.mcollective_version, requirement) < 0
111: DDL.validation_fail!(:PLMC20, "%{type} plugin '%{name}' requires MCollective version %{requirement} or newer", :debug, :type => @plugintype.to_s.capitalize, :name => @pluginname, :requirement => requirement)
112: end
113: end
114:
115: true
116: end