Class: Puppet::Parameter

Inherits:
Object
  • Object
show all
Includes:
Util::Errors
Defined in:
lib/puppet/parameter.rb

Overview

The Parameter class is the implementation of a resource's attributes of parameter kind. The Parameter class is also the base class for Property, and is used to describe meta-parameters (parameters that apply to all resource types). A Parameter (in contrast to a Property) has a single value where a property has both a current and a wanted value. The Parameter class methods are used to configure and create an instance of Parameter that represents one particular attribute data type; its valid value(s), and conversion to/from internal form.

The intention is that a new parameter is created by using the DSL method Type.newparam, or Type.newmetaparam if the parameter should be applicable to all resource types.

A Parameter that does not specify and valid values (via Parameter.newvalues) accepts any value.

See Also:

Direct Known Subclasses

Property

Defined Under Namespace

Classes: Value, ValueCollection

Constant Summary

Class Attribute Summary (collapse)

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from Util

exit_on_fail, exit_on_fail, which, which

Constructor Details

- (Parameter) initialize(options = {})

Note:

A parameter should be created via the DSL method Type::newparam

Initializes the parameter with a required resource reference and optional attribute settings. The option :resource must be specified or an exception is raised. Any additional options passed are used to initialize the attributes of this parameter by treating each key in the options hash as the name of the attribute to set, and the value as the value to set.

Options Hash (options):

  • :resource (Puppet::Resource)

    The resource this parameter holds a value for. Required.

Raises:

  • (Puppet::DevError)

    If resource is not specified in the options hash.



341
342
343
344
345
346
347
348
349
350
351
# File 'lib/puppet/parameter.rb', line 341

def initialize(options = {})
  options = symbolize_options(options)
  if resource = options[:resource]
    self.resource = resource
    options.delete(:resource)
  else
    raise Puppet::DevError, "No resource set for #{self.class.name}"
  end

  set_options(options)
end

Class Attribute Details

+ (Object) munger (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

TODO:

The term "munger" only appears in this location in the Puppet code base. There is munge and unmunge and they seem to work perfectly fine without this attribute declaration.

Unused?



44
45
46
# File 'lib/puppet/parameter.rb', line 44

def munger
  @munger
end

+ (Array<Symbol>) required_features + (Array<Symbol>) required_features=(*args)

Returns The names of the provider features required for this parameter to work. the returned names are always all lower case symbols.

Overloads:

  • + (Array<Symbol>) required_features

    Returns the required provider features as an array of lower case symbols

  • + (Array<Symbol>) required_features=(*args)

    Sets the requiredprovider_features from one or more values, or array. The given arguments are flattened, and internalized.

DSL:

  • type



72
73
74
# File 'lib/puppet/parameter.rb', line 72

def required_features
  @required_features
end

+ (Object) validater (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

TODO:

The term "validater" only appears in this location in the Puppet code base. There is validate which seems to works fine without this attribute declaration.

Unused?



37
38
39
# File 'lib/puppet/parameter.rb', line 37

def validater
  @validater
end

+ (Puppet::Parameter::ValueCollection) value_collection (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns The set of valid values (or an empty set that accepts any value).



77
78
79
# File 'lib/puppet/parameter.rb', line 77

def value_collection
  @value_collection
end

Instance Attribute Details

- (Puppet::Parameter) parent

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns A reference to the parameter's parent kept for backwards compatibility.



306
307
308
# File 'lib/puppet/parameter.rb', line 306

def parent
  @parent
end

Class Method Details

+ (Object) aliasvalue(name, other)

Makes the given name an alias for the given other name. Or said differently, the valid value other can now also be referred to via the given name. Aliasing may affect how the parameter's value is serialized/stored (it may store the other value instead of the alias).

DSL:

  • type



276
277
278
# File 'lib/puppet/parameter.rb', line 276

def aliasvalue(name, other)
  @value_collection.aliasvalue(name, other)
end

+ defaultto(value) + defaultto({|| ... })

This method returns an undefined value.

Defines how the default value of a parameter is computed. The computation of the parameter's default value is defined by providing a value or a block. A default of nil can not be used.

Overloads:

  • + defaultto(value)

    Defines the default value with a literal value

  • + defaultto({|| ... })

    Defines that the default value is produced by the given block. The given block should produce the default value.

Raises:

  • (Puppet::DevError)

    if value is nil, and no block is given.

See Also:

  • default

DSL:

  • type



97
98
99
100
101
102
103
104
105
106
107
# File 'lib/puppet/parameter.rb', line 97

def defaultto(value = nil, &block)
  if block
    define_method(:default, &block)
  else
    if value.nil?
      raise Puppet::DevError,
        "Either a default value or block must be provided"
    end
    define_method(:default) do value end
  end
end

+ (String) desc(str)

Sets the documentation for this parameter.

See Also:

DSL:

  • type



152
153
154
# File 'lib/puppet/parameter.rb', line 152

def desc(str)
  @doc = str
end

+ (String) doc

Produces a documentation string. If an enumeration of valid values has been defined, it is appended to the documentation for this parameter specified with the desc method.



115
116
117
118
119
120
121
122
123
124
125
126
127
128
# File 'lib/puppet/parameter.rb', line 115

def doc
  @doc ||= ""

  unless defined?(@addeddocvals)
    @doc += value_collection.doc

    if f = self.required_features
      @doc += "  Requires features #{f.flatten.collect { |f| f.to_s }.join(" ")}."
    end
    @addeddocvals = true
  end

  @doc
end

+ initvars

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Initializes the instance variables. Clears the internal value collection (set of allowed values).



161
162
163
# File 'lib/puppet/parameter.rb', line 161

def initvars
  @value_collection = ValueCollection.new
end

+ isnamevar

This method returns an undefined value.

Sets a marker indicating that this parameter is the namevar (unique identifier) of the type where the parameter is contained. This also makes the parameter a required value. The marker can not be unset once it has been set.

DSL:

  • type



200
201
202
203
# File 'lib/puppet/parameter.rb', line 200

def isnamevar
  @isnamevar = true
  @required = true
end

+ (Boolean) isnamevar?

Returns whether this parameter is the namevar or not.



208
209
210
# File 'lib/puppet/parameter.rb', line 208

def isnamevar?
  @isnamevar
end

+ isrequired

This method returns an undefined value.

Sets a marker indicating that this parameter is required. Once set, it is not possible to make a parameter optional.

DSL:

  • type



218
219
220
# File 'lib/puppet/parameter.rb', line 218

def isrequired
  @required = true
end

+ (Object) munge({|| ... })

Note:

This adds a method with the name unsafe_munge in the created parameter class. Later this method is called in a context where exceptions will be rescued and handled.

Defines an optional method used to convert the parameter value from DSL/string form to an internal form. If a munge method is not defined, the DSL/string value is used as is.

DSL:

  • type



173
174
175
176
177
178
179
# File 'lib/puppet/parameter.rb', line 173

def munge(&block)
  # I need to wrap the unsafe version in begin/rescue parameterments,
  # but if I directly call the block then it gets bound to the
  # class's context, not the instance's, thus the two methods,
  # instead of just one.
  define_method(:unsafe_munge, &block)
end

+ newvalues(*names)

Note:

Each call to this method adds to the set of valid values

This method returns an undefined value.

Defines valid values for the parameter (enumeration or regular expressions). The set of valid values for the parameter can be limited to a (mix of) literal values and regular expression patterns.

DSL:

  • type



265
266
267
# File 'lib/puppet/parameter.rb', line 265

def newvalues(*names)
  @value_collection.newvalues(*names)
end

+ nodefault

This method returns an undefined value.

Removes the default method if defined. Has no effect if the default method is not defined. This method is intended to be used in a DSL scenario where a parameter inherits from a parameter with a default value that is not wanted in the derived parameter (otherwise, simply do not define a default value method).

See Also:

DSL:

  • type



141
142
143
# File 'lib/puppet/parameter.rb', line 141

def nodefault
  undef_method :default if public_method_defined? :default
end

+ (Object) proxymethods(*values)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates instance (proxy) methods that delegates to a class method with the same name.



284
285
286
287
288
289
290
# File 'lib/puppet/parameter.rb', line 284

def self.proxymethods(*values)
  values.each { |val|
    define_method(val) do
      self.class.send(val)
    end
  }
end

+ (Boolean) required?

Returns whether this parameter is required or not. A parameter is required if a call has been made to the DSL method isrequired.



237
238
239
# File 'lib/puppet/parameter.rb', line 237

def required?
  @required
end

+ (Object) unmunge({|| ... })

Note:

This adds a method with the name unmunge in the created parameter class.

Defines an optional method used to convert the parameter value to DSL/string form from an internal form. If an unmunge method is not defined, the internal form is used.

See Also:

DSL:

  • type



189
190
191
# File 'lib/puppet/parameter.rb', line 189

def unmunge(&block)
  define_method(:unmunge, &block)
end

+ validate({|| ... })

This method returns an undefined value.

Defines an optional method that is used to validate the parameter's DSL/string value. Validation should raise appropriate exceptions, the return value of the given block is ignored. The easiest way to raise an appropriate exception is to call the method Util::Errors.fail with the message as an argument. To validate the munged value instead, just munge the value (munge(value)).

DSL:

  • type



252
253
254
# File 'lib/puppet/parameter.rb', line 252

def validate(&block)
  define_method(:unsafe_validate, &block)
end

Instance Method Details

- log(msg)

TODO:

is loglevel a metaparameter? it is looked up with resource[:loglevel]

This method returns an undefined value.

Writes the given msg to the log with the loglevel indicated by the associated resource's loglevel parameter.



358
359
360
# File 'lib/puppet/parameter.rb', line 358

def log(msg)
  send_log(resource[:loglevel], msg)
end

- (Object) pathbuilder

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns an array of strings representing the containment heirarchy (types/classes) that make up the path to the resource from the root of the catalog. This is mostly used for logging purposes.



394
395
396
397
398
399
400
# File 'lib/puppet/parameter.rb', line 394

def pathbuilder
  if @resource
    return [@resource.pathbuilder, self.name]
  else
    return [self.name]
  end
end

- (Object) unsafe_munge(value)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This is the default implementation of munge that simply produces the value (if it is valid). The DSL method munge should be used to define an overriding method if munging is required.



407
408
409
# File 'lib/puppet/parameter.rb', line 407

def unsafe_munge(value)
  self.class.value_collection.munge(value)
end

- unsafe_validate(value)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

This is the default implementation of validate that may be overridden by the DSL method validate. If no valid values have been defined, the given value is accepted, else it is validated against the literal values (enumerator) and/or patterns defined by calling newvalues.

Raises:

  • (ArgumentError)

    if the value is not valid



448
449
450
# File 'lib/puppet/parameter.rb', line 448

def unsafe_validate(value)
  self.class.value_collection.validate(value)
end

- validate(value)

TODO:

Better description of when the various exceptions are raised.ArgumentError is rescued and changed into Puppet::Error.

This method returns an undefined value.

Performs validation of the given value against the rules defined by this parameter. A protected validation method that only ever raises useful exceptions.

Raises:

  • (ArgumentError, TypeError, Puppet::DevError, Puppet::Error)

    under various conditions



460
461
462
463
464
465
466
467
468
469
470
# File 'lib/puppet/parameter.rb', line 460

def validate(value)
  begin
    unsafe_validate(value)
  rescue ArgumentError => detail
    fail detail.to_s
  rescue Puppet::Error, TypeError
    raise
  rescue => detail
    raise Puppet::DevError, "Validate method failed for class #{self.name}: #{detail}", detail.backtrace
  end
end