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 @@ + + + + + + + Module: MCollective::DDL + + + + + + + + + + + +
+
+ + + +
+ +
+ + + + + + + + + + + + + + + + +
+ +
+ + + + + +
+

Class Index + [+]

+
+
+ Quicksearch + +
+
+ + + +
+ + +
+
+ +
+

MCollective::DDL

+ +
+

+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 .ddl +

+
+   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. +

+ +
+ + + + + + + + + +
+

Public Class Methods

+ + +
+ + +
+ + load_and_cache(*args) + click to toggle source + +
+ +
+ +

(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
+
+ +
+ + +
+ + +
+ + +
+ + new(*args, &blk) + click to toggle source + +
+ +
+ +

+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
+
+ +
+ + +
+ + +
+ + +
+ + string_to_boolean(val) + click to toggle source + +
+ +
+ +

+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
+
+ +
+ + +
+ + +
+ + +
+ + string_to_number(val) + click to toggle source + +
+ +
+ +

+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
+
+ +
+ + +
+ + +
+ + +
+ + validation_fail!(code, default, level, args={}) + click to toggle source + +
+ +
+ +

+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.

+ +
+ +
+

[Validate]

+

Generated with the Darkfish + Rdoc Generator 1.1.6.

+
+ + + +