Class: MCollective::DDL::Base
- Inherits:
-
Object
- Object
- MCollective::DDL::Base
- Defined in:
- lib/mcollective/ddl/base.rb
Overview
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.
Direct Known Subclasses
Instance Attribute Summary collapse
-
#entities ⇒ Object
readonly
Returns the value of attribute entities.
-
#meta ⇒ Object
readonly
Returns the value of attribute meta.
-
#pluginname ⇒ Object
readonly
Returns the value of attribute pluginname.
-
#plugintype ⇒ Object
readonly
Returns the value of attribute plugintype.
-
#requirements ⇒ Object
readonly
Returns the value of attribute requirements.
-
#usage(usage_text) ⇒ Object
readonly
Returns the value of attribute usage.
Instance Method Summary collapse
- #findddlfile(ddlname = nil, ddltype = nil) ⇒ Object
-
#help(template = nil) ⇒ Object
Generates help using the template based on the data created with metadata and input.
-
#initialize(plugin, plugintype = :agent, loadddl = true) ⇒ Base
constructor
A new instance of Base.
-
#input(argument, properties) ⇒ Object
See the documentation for action for how to use this.
- #loadddlfile ⇒ Object
-
#metadata(meta) ⇒ Object
Registers meta data for the introspection hash.
-
#output(argument, properties) ⇒ Object
Registers an output argument for a given action.
- #requires(requirement) ⇒ Object
- #template_for_plugintype ⇒ Object
-
#validate_input_argument(input, key, argument) ⇒ Object
validate strings, lists and booleans, we’ll add more types of validators when all the use cases are clear.
- #validate_requirements ⇒ Object
Constructor Details
#initialize(plugin, plugintype = :agent, loadddl = true) ⇒ Base
Returns a new instance of Base.
22 23 24 25 26 27 28 29 30 31 32 |
# File 'lib/mcollective/ddl/base.rb', line 22 def initialize(plugin, plugintype=:agent, loadddl=true) @entities = {} @meta = {} @usage = "" @config = Config.instance @pluginname = plugin @plugintype = plugintype.to_sym @requirements = {} loadddlfile if loadddl end |
Instance Attribute Details
#entities ⇒ Object (readonly)
Returns the value of attribute entities.
20 21 22 |
# File 'lib/mcollective/ddl/base.rb', line 20 def entities @entities end |
#meta ⇒ Object (readonly)
Returns the value of attribute meta.
20 21 22 |
# File 'lib/mcollective/ddl/base.rb', line 20 def @meta end |
#pluginname ⇒ Object (readonly)
Returns the value of attribute pluginname.
20 21 22 |
# File 'lib/mcollective/ddl/base.rb', line 20 def pluginname @pluginname end |
#plugintype ⇒ Object (readonly)
Returns the value of attribute plugintype.
20 21 22 |
# File 'lib/mcollective/ddl/base.rb', line 20 def plugintype @plugintype end |
#requirements ⇒ Object (readonly)
Returns the value of attribute requirements.
20 21 22 |
# File 'lib/mcollective/ddl/base.rb', line 20 def requirements @requirements end |
#usage(usage_text) ⇒ Object (readonly)
Returns the value of attribute usage.
20 21 22 |
# File 'lib/mcollective/ddl/base.rb', line 20 def usage @usage end |
Instance Method Details
#findddlfile(ddlname = nil, ddltype = nil) ⇒ Object
86 87 88 89 90 91 92 93 94 95 96 97 98 |
# File 'lib/mcollective/ddl/base.rb', line 86 def findddlfile(ddlname=nil, ddltype=nil) ddlname = @pluginname unless ddlname ddltype = @plugintype unless ddltype @config.libdir.each do |libdir| ddlfile = File.join([libdir, "mcollective", ddltype.to_s, "#{ddlname}.ddl"]) if File.exist?(ddlfile) Log.debug("Found #{ddlname} ddl at #{ddlfile}") return ddlfile end end return false end |
#help(template = nil) ⇒ Object
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 relative to helptemplatedir configuration parameter
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 |
# File 'lib/mcollective/ddl/base.rb', line 41 def help(template=nil) template = template_for_plugintype unless template template = File.join(@config.helptemplatedir, template) unless template.start_with?(File::SEPARATOR) template = File.read(template) = @meta entities = @entities unless template == "metadata-help.erb" = File.join(@config.helptemplatedir, "metadata-help.erb") = File.read() = ERB.new(, 0, '%') = .result(binding) end erb = ERB.new(template, 0, '%') erb.result(binding) end |
#input(argument, properties) ⇒ Object
See the documentation for action for how to use this
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 |
# File 'lib/mcollective/ddl/base.rb', line 150 def input(argument, properties) raise "Cannot figure out what entity input #{argument} belongs to" unless @current_entity entity = @current_entity [:prompt, :description, :type].each do |arg| raise "Input needs a :#{arg} property" unless properties.include?(arg) end @entities[entity][:input][argument] = {:prompt => properties[:prompt], :description => properties[:description], :type => properties[:type], :optional => properties[:optional]} case properties[:type] when :string raise "Input type :string needs a :validation argument" unless properties.include?(:validation) raise "Input type :string needs a :maxlength argument" unless properties.include?(:maxlength) @entities[entity][:input][argument][:validation] = properties[:validation] @entities[entity][:input][argument][:maxlength] = properties[:maxlength] when :list raise "Input type :list needs a :list argument" unless properties.include?(:list) @entities[entity][:input][argument][:list] = properties[:list] end end |
#loadddlfile ⇒ Object
78 79 80 81 82 83 84 |
# File 'lib/mcollective/ddl/base.rb', line 78 def loadddlfile if ddlfile = findddlfile instance_eval(File.read(ddlfile), ddlfile, 1) else raise("Can't find DDL for #{@plugintype} plugin '#{@pluginname}'") end end |
#metadata(meta) ⇒ Object
Registers meta data for the introspection hash
211 212 213 214 215 216 217 |
# File 'lib/mcollective/ddl/base.rb', line 211 def () [:name, :description, :author, :license, :version, :url, :timeout].each do |arg| raise "Metadata needs a :#{arg} property" unless .include?(arg) end @meta = end |
#output(argument, properties) ⇒ Object
Registers an output argument for a given action
See the documentation for action for how to use this
182 183 184 185 186 187 188 189 190 191 192 |
# File 'lib/mcollective/ddl/base.rb', line 182 def output(argument, properties) raise "Cannot figure out what action input #{argument} belongs to" unless @current_entity raise "Output #{argument} needs a description argument" unless properties.include?(:description) raise "Output #{argument} needs a display_as argument" unless properties.include?(:display_as) action = @current_entity @entities[action][:output][argument] = {:description => properties[:description], :display_as => properties[:display_as], :default => properties[:default]} end |
#requires(requirement) ⇒ Object
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 |
# File 'lib/mcollective/ddl/base.rb', line 194 def requires(requirement) raise "Requirement should be a hash in the form :item => 'requirement'" unless requirement.is_a?(Hash) valid_requirements = [:mcollective] requirement.keys.each do |key| unless valid_requirements.include?(key) raise "Requirement %s is not a valid requirement, only %s is supported" % [key, valid_requirements.join(", ")] end @requirements[key] = requirement[key] end validate_requirements end |
#template_for_plugintype ⇒ Object
64 65 66 67 68 69 70 71 72 73 74 75 76 |
# File 'lib/mcollective/ddl/base.rb', line 64 def template_for_plugintype case @plugintype when :agent return "rpc-help.erb" else if File.exists?(File.join(@config.helptemplatedir,"#{@plugintype}-help.erb")) return "#{@plugintype}-help.erb" else # Default help template gets loaded if plugintype-help does not exist. return "metadata-help.erb" end end end |
#validate_input_argument(input, key, argument) ⇒ Object
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
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 |
# File 'lib/mcollective/ddl/base.rb', line 124 def validate_input_argument(input, key, argument) Validator.load_validators case input[key][:type] when :string Validator.validate(argument, :string) Validator.length(argument, input[key][:maxlength].to_i) Validator.validate(argument, input[key][:validation]) when :list Validator.validate(argument, input[key][:list]) else Validator.validate(argument, input[key][:type]) end return true rescue => e raise DDLValidationError, "Cannot validate input %s: %s" % [key, e.to_s] end |
#validate_requirements ⇒ Object
100 101 102 103 104 105 106 107 108 109 110 111 112 113 |
# File 'lib/mcollective/ddl/base.rb', line 100 def validate_requirements if requirement = @requirements[:mcollective] if Util.mcollective_version == "@DEVELOPMENT_VERSION@" Log.warn("DDL requirements validation being skipped in development") return true end if Util.versioncmp(Util.mcollective_version, requirement) < 0 raise DDLValidationError, "%s plugin '%s' requires MCollective version %s or newer" % [@plugintype.to_s.capitalize, @pluginname, requirement] end end true end |