Class: Puppet::Parameter

Inherits:
Object show all
Extended by:
Util, Util::Docs
Includes:
Util, Util::Errors, Util::Logging, Util::MethodHelper
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:

Defined Under Namespace

Classes: Boolean, PackageOptions, Path, Value, ValueCollection

Constant Summary

Constants included from Util::Docs

Util::Docs::HEADER_LEVELS

Constants included from Util

Util::AbsolutePathPosix, Util::AbsolutePathWindows, Util::DEFAULT_POSIX_MODE, Util::DEFAULT_WINDOWS_MODE

Constants included from Util::POSIX

Util::POSIX::LOCALE_ENV_VARS, Util::POSIX::USER_ENV_VARS

Constants included from Util::SymbolicFileMode

Util::SymbolicFileMode::SetGIDBit, Util::SymbolicFileMode::SetUIDBit, Util::SymbolicFileMode::StickyBit, Util::SymbolicFileMode::SymbolicMode, Util::SymbolicFileMode::SymbolicSpecialToBit

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes included from Util::Docs

#doc, #nodoc

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util::Docs

desc, dochook, doctable, markdown_definitionlist, markdown_header, nodoc?, pad, scrub

Methods included from Util

absolute_path?, activerecord_version, benchmark, binread, chuser, classproxy, deterministic_rand, execfail, execpipe, execute, exit_on_fail, logmethods, memory, path_to_uri, pretty_backtrace, proxy, replace_file, safe_posix_fork, symbolizehash, thinmark, uri_to_path, which, withenv, withumask

Methods included from Util::POSIX

#get_posix_field, #gid, #idfield, #methodbyid, #methodbyname, #search_posix_field, #uid

Methods included from Util::SymbolicFileMode

#normalize_symbolic_mode, #symbolic_mode_to_int, #valid_symbolic_mode?

Methods included from Util::MethodHelper

#requiredopts, #set_options, #symbolize_options

Methods included from Util::Logging

#clear_deprecation_warnings, #deprecation_warning, #format_exception, #get_deprecation_offender, #log_and_raise, #log_deprecations_to_file, #log_exception, #puppet_deprecation_warning, #send_log

Methods included from Util::Errors

#adderrorcontext, #devfail, #error_context, #exceptwrap, #fail

Constructor Details

#initialize(options = {}) ⇒ Parameter

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.

Parameters:

  • options (Hash{Symbol => Object]) (defaults to: {}) —

    Options, where ‘resource` is required

Options Hash (options):

  • :resource (Puppet::Resource) —

    The resource this parameter holds a value for. Required.

Raises:



344
345
346
347
348
349
350
351
352
353
354
 
# File 'lib/puppet/parameter.rb', line 344

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

.default ⇒ Object (readonly)

Returns The default value of the parameter as determined by the defaultto method, or nil if no default has been set.

Returns:

  • (Object) —

    The default value of the parameter as determined by the defaultto method, or nil if no default has been set.



51
52
53
 
# File 'lib/puppet/parameter.rb', line 51

def default
  @default
end

.metaparam ⇒ Boolean

Returns Flag indicating whether this parameter is a meta-parameter or not.

Returns:

  • (Boolean) —

    Flag indicating whether this parameter is a meta-parameter or not.



80
81
82
 
# File 'lib/puppet/parameter.rb', line 80

def metaparam
  @metaparam
end

.munger ⇒ Object (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

.name ⇒ Symbol (readonly)

Returns The parameter name as given when it was created.

Returns:

  • (Symbol) —

    The parameter name as given when it was created.



47
48
49
 
# File 'lib/puppet/parameter.rb', line 47

def name
  @name
end

.required_features ⇒ Array<Symbol> .required_features=(*args) ⇒ Array<Symbol>

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

Overloads:

  • .required_features ⇒ Array<Symbol>

    Returns the required _provider features_ as an array of lower case symbols

  • .required_features=(*args) ⇒ Array<Symbol>

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

    Parameters:

    • *args (Symbol) —

      one or more names of required provider features

Returns:

  • (Array<Symbol>) —

    The names of the _provider features_ required for this parameter to work. the returned names are always all lower case symbols.



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

def required_features
  @required_features
end

.validater ⇒ Object (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

.value_collection ⇒ Puppet::Parameter::ValueCollection (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).

Returns:



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

def value_collection
  @value_collection
end

Instance Attribute Details

#name ⇒ Symbol (readonly)

Note:

Since a Parameter defines the name at the class level, each Parameter class must be unique within a type’s inheritance chain.

Returns The parameter’s name as given when it was created.

Returns:

  • (Symbol) —

    The parameter’s name as given when it was created.



378
379
380
 
# File 'lib/puppet/parameter.rb', line 378

def name
  self.class.name
end

#parent ⇒ Puppet::Parameter

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.

Returns:

  • (Puppet::Parameter) —

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



309
310
311
 
# File 'lib/puppet/parameter.rb', line 309

def parent
  @parent
end

#resource ⇒ Puppet::Resource

Returns A reference to the resource this parameter is an attribute of (the _associated resource_).

Returns:

  • (Puppet::Resource) —

    A reference to the resource this parameter is an attribute of (the _associated resource_).



303
304
305
 
# File 'lib/puppet/parameter.rb', line 303

def resource
  @resource
end

Class Method Details

.aliasvalue(name, other) ⇒ Object

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



279
280
281
 
# File 'lib/puppet/parameter.rb', line 279

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

.defaultto(value) ⇒ void .defaultto({|| ... }) ⇒ void

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) ⇒ void

    Defines the default value with a literal value

    Parameters:

    • value (Object) —

      the literal value to use as the default value

  • .defaultto({|| ... }) ⇒ void

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

Raises:

See Also:



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

.desc(str) ⇒ String

Sets the documentation for this parameter.

Parameters:

  • str (String) —

    The documentation string to set

Returns:

  • (String) —

    the given ‘str` parameter

See Also:



155
156
157
 
# File 'lib/puppet/parameter.rb', line 155

def desc(str)
  @doc = str
end

.doc ⇒ String

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.

Returns:

  • (String) —

    Returns a documentation string.



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

def doc
  @doc ||= ""

  unless defined?(@addeddocvals)
    @doc = Puppet::Util::Docs.scrub(@doc)
    if vals = value_collection.doc
      @doc << "\n\n#{vals}"
    end

    if f = self.required_features
      @doc << "\n\nRequires features #{f.flatten.collect { |f| f.to_s }.join(" ")}."
    end
    @addeddocvals = true
  end

  @doc
end

.format_value_for_display(value) ⇒ String

Note:

this method does not protect against infinite structures.

Produces a String with the value formatted for display to a human. When the parameter value is a:

  • **single valued parameter value** the result is produced on the form ‘’value’‘ where value is the string form of the parameter’s value.

  • Array the list of values is enclosed in ‘[]`, and each produced value is separated by a comma.

  • Hash value is output with keys in sorted order enclosed in ‘{}` with each entry formatted on the form `’k’ => v` where ‘k` is the key in string form and v is the value of the key. Entries are comma separated.

For both Array and Hash this method is called recursively to format contained values.

Returns:

  • (String) —

    The formatted value in string form.



556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
 
# File 'lib/puppet/parameter.rb', line 556

def self.format_value_for_display(value)
  if value.is_a? Array
    formatted_values = value.collect {|value| format_value_for_display(value)}.join(', ')
    "[#{formatted_values}]"
  elsif value.is_a? Hash
    # Sorting the hash keys for display is largely for having stable
    # output to test against, but also helps when scanning for hash
    # keys, since they will be in ASCIIbetical order.
    hash = value.keys.sort {|a,b| a.to_s <=> b.to_s}.collect do |k|
      "'#{k}' => #{format_value_for_display(value[k])}"
    end.join(', ')

    "{#{hash}}"
  else
    "'#{value}'"
  end
end

.initvars ⇒ void

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



164
165
166
 
# File 'lib/puppet/parameter.rb', line 164

def initvars
  @value_collection = ValueCollection.new
end

.isnamevar ⇒ void

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.



203
204
205
206
 
# File 'lib/puppet/parameter.rb', line 203

def isnamevar
  @isnamevar = true
  @required = true
end

.isnamevar? ⇒ Boolean

Returns whether this parameter is the namevar or not.

Returns:

  • (Boolean) —

    Returns whether this parameter is the namevar or not.



211
212
213
 
# File 'lib/puppet/parameter.rb', line 211

def isnamevar?
  @isnamevar
end

.isrequired ⇒ void

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.



221
222
223
 
# File 'lib/puppet/parameter.rb', line 221

def isrequired
  @required = true
end

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

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.



176
177
178
179
180
181
182
 
# File 'lib/puppet/parameter.rb', line 176

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) ⇒ void

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.

Parameters:

  • names (Symbol, Regexp) —

    The set of valid literal values and/or patterns for the parameter.



268
269
270
 
# File 'lib/puppet/parameter.rb', line 268

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

.nodefault ⇒ void

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:



144
145
146
 
# File 'lib/puppet/parameter.rb', line 144

def nodefault
  undef_method :default if public_method_defined? :default
end

.proxymethods(*values) ⇒ Object

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.



287
288
289
290
291
292
293
 
# File 'lib/puppet/parameter.rb', line 287

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

.required? ⇒ Boolean

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

Returns:

  • (Boolean) —

    Returns whether this parameter is required or not.



240
241
242
 
# File 'lib/puppet/parameter.rb', line 240

def required?
  @required
end

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

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:



192
193
194
 
# File 'lib/puppet/parameter.rb', line 192

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

.validate({|| ... }) ⇒ void

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



255
256
257
 
# File 'lib/puppet/parameter.rb', line 255

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

Instance Method Details

#file ⇒ Integer

Returns the result of calling the same method on the associated resource.

Returns:

  • (Integer) —

    Returns the result of calling the same method on the associated resource.



324
325
326
 
# File 'lib/puppet/parameter.rb', line 324

def file
  resource.file
end

#isnamevar? ⇒ Object 



300
 
# File 'lib/puppet/parameter.rb', line 300

proxymethods("required?", "isnamevar?")

#line ⇒ Integer

Returns the result of calling the same method on the associated resource.

Returns:

  • (Integer) —

    Returns the result of calling the same method on the associated resource.



319
320
321
 
# File 'lib/puppet/parameter.rb', line 319

def line
  resource.line
end

#log(msg) ⇒ void

TODO:

is loglevel a metaparameter? it is looked up with ‘resource`

This method returns an undefined value.

Writes the given ‘msg` to the log with the loglevel indicated by the associated resource’s ‘loglevel` parameter.



361
362
363
 
# File 'lib/puppet/parameter.rb', line 361

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

#metaparam? ⇒ Boolean

Returns whether this parameter is a meta-parameter or not.

Returns:

  • (Boolean) —

    Returns whether this parameter is a meta-parameter or not.



366
367
368
 
# File 'lib/puppet/parameter.rb', line 366

def metaparam?
  self.class.metaparam
end

#munge(value) ⇒ Object

Note:

This method should not be overridden. Use the DSL method munge to define a munging method if required.

Munges the value to internal form. This implementation of ‘munge` provides exception handling around the specified munging of this parameter.

Parameters:

  • value (Object) —

    the DSL value to munge

Returns:

  • (Object) —

    the munged (internal) value



430
431
432
433
434
435
436
437
438
439
440
 
# File 'lib/puppet/parameter.rb', line 430

def munge(value)
  begin
    ret = unsafe_munge(value)
  rescue Puppet::Error => detail
    Puppet.debug "Reraising #{detail}"
    raise
  rescue => detail
    raise Puppet::DevError, "Munging failed for value #{value.inspect} in class #{self.name}: #{detail}", detail.backtrace
  end
  ret
end

#noop ⇒ Boolean

TODO:

How is noop mode set for a parameter? Is this of value in DSL to inhibit a parameter?

Returns true if this parameter, the associated resource, or overall puppet mode is ‘noop`.

Returns:

  • (Boolean) —

    Returns true if this parameter, the associated resource, or overall puppet mode is ‘noop`.



385
386
387
388
389
390
 
# File 'lib/puppet/parameter.rb', line 385

def noop
  @noop ||= false
  tmp = @noop || self.resource.noop || Puppet[:noop] || false
  #debug "noop is #{tmp}"
  tmp
end

#path ⇒ String

Returns a string representation of the resource’s containment path in the catalog.

Returns:



314
315
316
 
# File 'lib/puppet/parameter.rb', line 314

def path
  @path ||= '/' + pathbuilder.join('/')
end

#pathbuilder ⇒ Object

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.



397
398
399
400
401
402
403
 
# File 'lib/puppet/parameter.rb', line 397

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

#provider ⇒ Puppet::Provider

TODO:

The original comment says = _“Retrieve the resource’s provider. Some types don’t have providers, in which case we return the resource object itself.”_ This does not seem to be true, the default implementation that sets this value may be Type.provider= which always gets either the name of a provider or an instance of one.

Returns the provider of the associated resource.

Returns:



511
512
513
 
# File 'lib/puppet/parameter.rb', line 511

def provider
  @resource.provider
end

#remove ⇒ nil

TODO:

Why - what is the intent/purpose of this?

Sets the associated resource to nil.

Returns:

  • (nil) 


479
480
481
 
# File 'lib/puppet/parameter.rb', line 479

def remove
  @resource = nil
end

#required? ⇒ Object 



300
 
# File 'lib/puppet/parameter.rb', line 300

proxymethods("required?", "isnamevar?")

#tags ⇒ Array<Symbol>

TODO:

The original comment says = _“The properties need to return tags so that logs correctly collect them.”_ what if anything of that is of interest to document. Should tags and their relationship to logs be described. This is a more general concept.

Returns an array of the associated resource’s symbolic tags (including the parameter itself). At a minimun, the array contains the name of the parameter. If the associated resource has tags, these tags are also included in the array.

Returns:

  • (Array<Symbol>) —

    Returns an array of the associated resource’s symbolic tags (including the parameter itself).



523
524
525
526
527
528
529
530
531
 
# File 'lib/puppet/parameter.rb', line 523

def tags
  unless defined?(@tags)
    @tags = []
    # This might not be true in testing
    @tags = @resource.tags if @resource.respond_to? :tags
    @tags << self.name.to_s
  end
  @tags
end

#to_s ⇒ String

Returns The name of the parameter in string form.

Returns:

  • (String) —

    The name of the parameter in string form.



534
535
536
 
# File 'lib/puppet/parameter.rb', line 534

def to_s
  name.to_s
end

#unmunge(value) ⇒ Object

Unmunges the value by transforming it from internal form to DSL form. This is the default implementation of ‘unmunge` that simply returns the value without processing. The DSL method unmunge should be used to define an overriding method if required.

Returns:

  • (Object) —

    the unmunged value



419
420
421
 
# File 'lib/puppet/parameter.rb', line 419

def unmunge(value)
  value
end

#unsafe_munge(value) ⇒ Object

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.



410
411
412
 
# File 'lib/puppet/parameter.rb', line 410

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

#unsafe_validate(value) ⇒ void

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.

Parameters:

  • value (Object) —

    the value to check for validity

Raises:

  • (ArgumentError) —

    if the value is not valid



451
452
453
 
# File 'lib/puppet/parameter.rb', line 451

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

#validate(value) ⇒ void

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:



463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/puppet/parameter.rb', line 463

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

#value ⇒ Object

Returns Gets the value of this parameter after performing any specified unmunging.

Returns:

  • (Object) —

    Gets the value of this parameter after performing any specified unmunging.



484
485
486
 
# File 'lib/puppet/parameter.rb', line 484

def value
  unmunge(@value) unless @value.nil?
end

#value=(value) ⇒ Object

TODO:

This original comment _“All of the checking should possibly be late-binding (e.g., users might not exist when the value is assigned but might when it is asked for).”_ does not seem to be correct, the implementation calls both validate and munge on the given value, so no late binding.

Sets the given value as the value of this parameter. The given value is validated and then munged (if munging has been specified). The result is store as the value of this arameter.

Returns:

  • (Object) —

    The given ‘value` after munging.

Raises:



499
500
501
502
503
 
# File 'lib/puppet/parameter.rb', line 499

def value=(value)
  validate(value)

  @value = munge(value)
end

#version ⇒ Integer

Returns the result of calling the same method on the associated resource.

Returns:

  • (Integer) —

    Returns the result of calling the same method on the associated resource.



329
330
331
 
# File 'lib/puppet/parameter.rb', line 329

def version
  resource.version
end