Module: 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 <agent name>.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. -

- -

- - -

- -

Methods

- -

- load_and_cache - new - string_to_boolean - string_to_number - validation_fail! -

- -

Classes and Modules

- - Class MCollective::DDL::AgentDDL
-Class MCollective::DDL::Base
-Class MCollective::DDL::DataDDL
-Class MCollective::DDL::DiscoveryDDL
-Class MCollective::DDL::ValidatorDDL
- -

- - - - - - - - -

Public Class methods

- -

- - -

- - load_and_cache(*args) - -

- -

[Source]

-    # 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) - -

- -

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

[Source]

-    # File lib/mcollective/ddl.rb, line 67
-67:     def self.new(*args, &blk)
-68:       load_and_cache(*args)
-69:     end
-

- -

- - -

- - string_to_boolean(val) - -

- -

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

[Source]

-     # 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) - -

- -

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

[Source]

-     # 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={}) - -

- -

-Various DDL implementations will validate and raise -on error, this is a utility method to correctly setup a DDLValidationError exceptions and raise -them -

[Source]

-     # 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
-

- - -