X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;ds=sidebyside;f=doc%2FMCollective%2FDDL.html;fp=doc%2FMCollective%2FDDL.html;h=8c2c02879ed1b5f203d5474ebe719865abcee4e3;hb=7c9314f502cde8daad23b61d10b24a542e04154a;hp=0000000000000000000000000000000000000000;hpb=d1f1649ba43c5cbc43c4beb2380096ba051d646a;p=packages%2Fprecise%2Fmcollective.git diff --git a/doc/MCollective/DDL.html b/doc/MCollective/DDL.html new file mode 100644 index 0000000..8c2c028 --- /dev/null +++ b/doc/MCollective/DDL.html @@ -0,0 +1,670 @@ + + + +
+ + ++A set of classes that helps create data description language files for +plugins. You can define meta data, actions, input and output describing the +behavior of your agent or other plugins +
++DDL files are used for input validation, +constructing outputs, producing online help, informing the various display +routines and so forth. +
+
+A sample DDL for an agent be seen below, you’d
+put this in your agent dir as
+ metadata :name => "SimpleRPC Service Agent", + :description => "Agent to manage services using the Puppet service provider", + :author => "R.I.Pienaar", + :license => "GPLv2", + :version => "1.1", + :url => "http://mcollective-plugins.googlecode.com/", + :timeout => 60 + + action "status", :description => "Gets the status of a service" do + display :always + + input :service, + :prompt => "Service Name", + :description => "The service to get the status for", + :type => :string, + :validation => '^[a-zA-Z\-_\d]+$', + :optional => true, + :maxlength => 30 + + output :status, + :description => "The status of service", + :display_as => "Service Status" + end ++
+There are now many types of DDL and ultimately all +pugins should have DDL files. The code is organized +so that any plugin type will magically just work - they will be an instane +of Base which has metadata and a few common +cases. +
++For plugin types that require more specific behaviors they can just add a +class here that inherits from Base and add +their specific behavior. +
++Base defines a specific behavior for input, +output and metadata which we’d like to keep standard across plugin +types so do not completely override the behavior of input. The methods are +written that they will gladly store extra content though so you add, do not +remove. See the AgentDDL class for an +example where agents want a :required argument to be always set. +
+ +(Not documented)
+ + + ++ # File lib/mcollective/ddl.rb, line 71 +71: def self.load_and_cache(*args) +72: Cache.setup(:ddl, 300) +73: +74: plugin = args.first +75: args.size > 1 ? type = args[1].to_s : type = "agent" +76: path = "%s/%s" % [type, plugin] +77: +78: begin +79: ddl = Cache.read(:ddl, path) +80: rescue +81: begin +82: klass = DDL.const_get("%sDDL" % type.capitalize) +83: rescue NameError +84: klass = Base +85: end +86: +87: ddl = Cache.write(:ddl, path, klass.new(*args)) +88: end +89: +90: return ddl +91: end+
+There used to be only one big nasty DDL class with a +bunch of mashed together behaviors. It’s been around for ages and we +would rather not ask all the users to change their DDL.new calls to some other factory method that +would have this exact same behavior. +
++So we override the behavior of new which is +a hugely sucky thing to do but ultimately it’s what would be least +disrupting to code out there today. We did though change DDL to a module to make it possibly a little less +suprising, possibly. +
+ + + ++ # File lib/mcollective/ddl.rb, line 67 +67: def self.new(*args, &blk) +68: load_and_cache(*args) +69: end+
+As we’re taking arguments on the command line we need a way to input +booleans, true on the cli is a string so this method will take the ddl, +find all arguments that are supposed to be boolean and if they are the +strings “true”/“yes” or +“false”/“no” turn them into the matching boolean +
+ + + ++ # File lib/mcollective/ddl.rb, line 98 + 98: def self.string_to_boolean(val) + 99: return true if ["true", "t", "yes", "y", "1"].include?(val.downcase) +100: return false if ["false", "f", "no", "n", "0"].include?(val.downcase) +101: +102: raise_code(:PLMC17, "%{value} does not look like a boolean argument", :debug, :value => val) +103: end+
+a generic string to number function, if a number looks like a float it +turns it into a float else an int. This is naive but should be sufficient +for numbers typed on the cli in most cases +
+ + + ++ # File lib/mcollective/ddl.rb, line 108 +108: def self.string_to_number(val) +109: return val.to_f if val =~ /^\d+\.\d+$/ +110: return val.to_i if val =~ /^\d+$/ +111: +112: raise_code(:PLMC16, "%{value} does not look like a numeric value", :debug, :value => val) +113: end+
+Various DDL implementations will validate and raise +on error, this is a utility method to correctly setup a DDLValidationError exceptions and raise +them +
+ + + ++ # File lib/mcollective/ddl.rb, line 117 +117: def self.validation_fail!(code, default, level, args={}) +118: exception = DDLValidationError.new(code, default, level, args) +119: exception.set_backtrace caller +120: +121: raise exception +122: end+
Disabled; run with --debug to generate this.
+ +Generated with the Darkfish + Rdoc Generator 1.1.6.
+