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

In Files

Namespace

Methods

Files

Class Index

MCollective::DDL

Public Class Methods