class Chef::Property

Type and validation information for a property on a resource.

A property named “x” manipulates the “@x” instance variable on a resource. The presence of the variable (‘instance_variable_defined?(@x)`) tells whether the variable is defined; it may have any actual value, constrained only by validation.

Properties may have validation, defaults, and coercion, and have full support for lazy values.

@see Chef::Resource.property @see Chef::DelayedEvaluator

Attributes

options[R]

The options this Property will use for get/set behavior and validation.

@see initialize for a list of valid options.

Public Class Methods

derive(**options) click to toggle source

Create a reusable property type that can be used in multiple properties in different resources.

@param options [Hash<Symbol,Object>] Validation options. See Chef::Resource.property for

the list of options.

@example

Property.derive(default: 'hi')
# File lib/chef/property.rb, line 51
def self.derive(**options)
  new(**options)
end
emit_deprecated_alias(from, to, message, declared_in) click to toggle source

This is to support deprecated_property_alias, by emitting an alias and a deprecation warning when called.

@param from [String] Name of the deprecated property @param to [String] Name of the correct property @param message [String] Deprecation message to show to the cookbook author @param declared_in [Class] Class this property comes from

# File lib/chef/property.rb, line 63
    def self.emit_deprecated_alias(from, to, message, declared_in)
      declared_in.class_eval <<-EOM, __FILE__, __LINE__ + 1
        def #{from}(value=NOT_PASSED)
          Chef.deprecated(:property, "#{message}")
          #{to}(value)
        end
        def #{from}=(value)
          Chef.deprecated(:property, "#{message}")
          #{to} = value
        end
      EOM
    end
new(**options) click to toggle source

Create a new property.

@param options [Hash<Symbol,Object>] Property options, including

control options here, as well as validation options (see
Chef::Mixin::ParamsValidate#validate for a description of validation
options).
@option options [Symbol] :name The name of this property.
@option options [Class] :declared_in The class this property comes from.
@option options [String] :description A description of the property.
@option options [Symbol] :instance_variable_name The instance variable
  tied to this property. Must include a leading `@`. Defaults to `@<name>`.
  `nil` means the property is opaque and not tied to a specific instance
  variable.
@option options [String] :introduced The release that introduced this property
@option options [Boolean] :desired_state `true` if this property is part of desired
  state. Defaults to `true`.
@option options [Boolean] :identity `true` if this property is part of object
  identity. Defaults to `false`.
@option options [Boolean] :name_property `true` if this
  property defaults to the same value as `name`. Equivalent to
  `default: lazy { name }`, except that #property_is_set? will
  return `true` if the property is set *or* if `name` is set.
@option options [Boolean] :nillable `true` opt-in to Chef-13 style behavior where
  attempting to set a nil value will really set a nil value instead of issuing
  a warning and operating like a getter [DEPRECATED]
@option options [Object] :default The value this property
  will return if the user does not set one. If this is `lazy`, it will
  be run in the context of the instance (and able to access other
  properties) and cached. If not, the value will be frozen with Object#freeze
  to prevent users from modifying it in an instance.
@option options [String] :default_description The description of the default value
  used in docs. Particularly useful when a default is computed or lazily eval'd.
@option options [Boolean] :skip_docs This property should not be included in any
  documentation output
@option options [Proc] :coerce A proc which will be called to
  transform the user input to canonical form. The value is passed in,
  and the transformed value returned as output. Lazy values will *not*
  be passed to this method until after they are evaluated. Called in the
  context of the resource (meaning you can access other properties).
@option options [Boolean, Array<Symbol>] :required `true` if this property
  must be present for *all* actions; `false` otherwise. Alternatively
  you may specify a list of actions the property is required for, when
  the property is only required for a subset of actions. This is checked
  after the resource is fully initialized.
@option options [String] :deprecated If set, this property is deprecated and
  will create a deprecation warning.
# File lib/chef/property.rb, line 124
def initialize(**options)
  options = options.inject({}) { |memo, (key, value)| memo[key.to_sym] = value; memo }
  @options = options
  options[:name] = options[:name].to_sym if options[:name]
  options[:instance_variable_name] = options[:instance_variable_name].to_sym if options[:instance_variable_name]

  # Replace name_attribute with name_property
  if options.key?(:name_attribute)
    # If we have both name_attribute and name_property and they differ, raise an error
    if options.key?(:name_property)
      raise ArgumentError, "name_attribute and name_property are functionally identical and both cannot be specified on a property at once. Use just one on property #{self}"
    end

    # replace name_property with name_attribute in place
    options = Hash[options.map { |k, v| k == :name_attribute ? [ :name_property, v ] : [ k, v ] }]
    @options = options
  end

  if options.key?(:default) && options.key?(:name_property)
    raise ArgumentError, "A property cannot be both a name_property/name_attribute and have a default value. Use one or the other on property #{self}"
  end

  if options[:name_property]
    options[:desired_state] = false unless options.key?(:desired_state)
  end

  # Recursively freeze the default if it isn't a lazy value.
  unless default.is_a?(DelayedEvaluator)
    visitor = lambda do |obj|
      case obj
      when Hash
        obj.each_value { |value| visitor.call(value) }
      when Array
        obj.each { |value| visitor.call(value) }
      end
      obj.freeze
    end
    visitor.call(default)
  end

  # Validate the default early, so the user gets a good error message, and
  # cache it so we don't do it again if so
  begin
    # If we can validate it all the way to output, do it.
    @stored_default = input_to_stored_value(nil, default, is_default: true)
  rescue Chef::Exceptions::CannotValidateStaticallyError
    # If the validation is not static (i.e. has procs), we will have to
    # coerce and validate the default each time we run
  end
end

Public Instance Methods

call(resource, value = NOT_PASSED) click to toggle source

Handle the property being called.

The base implementation does the property get-or-set:

“‘ruby resource.myprop # get resource.myprop value # set “`

Subclasses may implement this with any arguments they want, as long as the corresponding DSL calls it correctly.

@param resource [Chef::Resource] The resource to get the property from. @param value The value to set (or NOT_PASSED if it is a get).

@return The current value of the property. If it is a ‘set`, lazy values

will be returned without running, validating or coercing. If it is a
`get`, the non-lazy, coerced, validated value will always be returned.
# File lib/chef/property.rb, line 369
def call(resource, value = NOT_PASSED)
  if NOT_PASSED == value # see https://github.com/chef/chef/pull/8781 before changing this
    get(resource)
  else
    set(resource, value)
  end
end
coerce(resource, value) click to toggle source

Coerce an input value into canonical form for the property.

After coercion, the value is suitable for storage in the resource. You must validate values after coercion, however.

Does no special handling for lazy values.

@param resource [Chef::Resource] The resource we’re coercing against

(to provide context for the coerce).

@param value The value to coerce.

@return The coerced value.

@raise Chef::Exceptions::ValidationFailed If the value is invalid for

this property.
# File lib/chef/property.rb, line 513
def coerce(resource, value)
  if options.key?(:coerce)
    # nil is never coerced
    unless value.nil?
      value = exec_in_resource(resource, options[:coerce], value)
    end
  end
  value
end
declared_in() click to toggle source

The class this property was defined in.

@return [Class]

# File lib/chef/property.rb, line 193
def declared_in
  options[:declared_in]
end
default() click to toggle source

The raw default value for this resource.

Does not coerce or validate the default. Does not evaluate lazy values.

Defaults to ‘lazy { name }` if name_property is true; otherwise defaults to `nil`

# File lib/chef/property.rb, line 238
def default
  return options[:default] if options.key?(:default)
  return Chef::DelayedEvaluator.new { name } if name_property?

  nil
end
default_description() click to toggle source

A description of the default value of this property.

@return [String]

# File lib/chef/property.rb, line 250
def default_description
  options[:default_description]
end
derive(**modified_options) click to toggle source

Derive a new Property that is just like this one, except with some added or changed options.

@param options [Hash<Symbol,Object>] List of options that would be passed

to #initialize.

@return [Property] The new property type.

# File lib/chef/property.rb, line 557
def derive(**modified_options)
  # Since name_property, name_attribute and default override each other,
  # if you specify one of them in modified_options it overrides anything in
  # the original options.
  options = self.options
  if modified_options.key?(:name_property) ||
      modified_options.key?(:name_attribute) ||
      modified_options.key?(:default)
    options = options.reject { |k, v| %i{name_attribute name_property default}.include?(k) }
  end
  self.class.new(**options.merge(modified_options))
end
description() click to toggle source

A description of this property.

@return [String]

# File lib/chef/property.rb, line 202
def description
  options[:description]
end
desired_state?() click to toggle source

Whether this is part of desired state or not.

Defaults to true.

@return [Boolean]

# File lib/chef/property.rb, line 279
def desired_state?
  return true unless options.key?(:desired_state)

  options[:desired_state]
end
emit_dsl() click to toggle source

Emit the DSL for this property into the resource class (‘declared_in`).

Creates a getter and setter for the property.

# File lib/chef/property.rb, line 575
    def emit_dsl
      # We don't create the getter/setter if it's a custom property; we will
      # be using the existing getter/setter to manipulate it instead.
      return unless instance_variable_name

      # Properties may override existing properties up the inheritance hierarchy, but
      # properties must not override inherited methods like Object#hash.  When the Resource is
      # placed into the resource collection the ruby Hash object will call the
      # Object#hash method on the resource, and overriding that with a property will cause
      # very confusing results.
      if property_redefines_method?
        resource_name = declared_in.respond_to?(:resource_name) ? declared_in.resource_name : declared_in
        raise ArgumentError, "Property `#{name}` of resource `#{resource_name}` overwrites an existing method. A different name should be used for this property."
      end

      # We prefer this form because the property name won't show up in the
      # stack trace if you use `define_method`.
      declared_in.class_eval <<-EOM, __FILE__, __LINE__ + 1
        def #{name}(value=NOT_PASSED)
          raise "Property `#{name}` of `\#{self}` was incorrectly passed a block. Possible property-resource collision. To call a resource named `#{name}` either rename the property or else use `declare_resource(:#{name}, ...)`" if block_given?
          self.class.properties[#{name.inspect}].call(self, value)
        end
        def #{name}=(value)
          raise "Property `#{name}` of `\#{self}` was incorrectly passed a block. Possible property-resource collision. To call a resource named `#{name}` either rename the property or else use `declare_resource(:#{name}, ...)`" if block_given?
          self.class.properties[#{name.inspect}].set(self, value)
        end
      EOM
    end
equal_to() click to toggle source

The equal_to field of this property.

@return [Array, NilClass]

# File lib/chef/property.rb, line 259
def equal_to
  options[:equal_to]
end
explicitly_accepts_nil?(resource) click to toggle source

Find out whether this type accepts nil explicitly.

A type accepts nil explicitly if “is” allows nil, it validates as nil, and is not simply an empty type.

A type is presumed to accept nil if it does coercion (which must handle nil).

These examples accept nil explicitly: “‘ruby property :a, [ String, nil ] property :a, [ String, NilClass ] property :a, [ String, proc { |v| v.nil? } ] “`

This does not (because the “is” doesn’t exist or doesn’t have nil):

“‘ruby property :x, String “`

These do not, even though nil would validate fine (because they do not have “is”):

“‘ruby property :a property :a, equal_to: [ 1, 2, 3, nil ] property :a, kind_of: [ String, NilClass ] property :a, respond_to: [ ] property :a, callbacks: { “a” => proc { |v| v.nil? } } “`

@param resource [Chef::Resource] The resource we’re coercing against

(to provide context for the coerce).

@return [Boolean] Whether this value explicitly accepts nil.

@api private

# File lib/chef/property.rb, line 649
def explicitly_accepts_nil?(resource)
  options.key?(:coerce) ||
    (options.key?(:is) && Chef::Mixin::ParamsValidate.send(:_pv_is, { name => nil }, name, options[:is]))
rescue Chef::Exceptions::ValidationFailed, Chef::Exceptions::CannotValidateStaticallyError
  false
end
get(resource, nil_set: false) click to toggle source

Get the property value from the resource, handling lazy values, defaults, and validation.

  • If the property’s value is lazy, it is evaluated, coerced and validated.

  • If the property has no value, and is required, raises ValidationFailed.

  • If the property has no value, but has a lazy default, it is evaluated, coerced and validated. If the evaluated value is frozen, the resulting

  • If the property has no value, but has a default, the default value will be returned and frozen. If the default value is lazy, it will be evaluated, coerced and validated, and the result stored in the property.

  • If the property has no value, but is name_property, ‘resource.name` is retrieved, coerced, validated and stored in the property.

  • Otherwise, ‘nil` is returned.

@param resource [Chef::Resource] The resource to get the property from.

@return The value of the property.

@raise Chef::Exceptions::ValidationFailed If the value is invalid for

this property, or if the value is required and not set.
# File lib/chef/property.rb, line 399
def get(resource, nil_set: false)
  # If it's set, return it (and evaluate any lazy values)
  value = nil

  if is_set?(resource)
    value = get_value(resource)
    value = stored_value_to_output(resource, value)
  else
    # We are getting the default value.

    if has_default?
      # If we were able to cache the stored_default, grab it.
      if defined?(@stored_default)
        value = @stored_default
      else
        # Otherwise, we have to validate it now.
        value = input_to_stored_value(resource, default, is_default: true)
      end
      value = deep_dup(value)
      value = stored_value_to_output(resource, value)

      # If the value is mutable (non-frozen), we set it on the instance
      # so that people can mutate it.  (All constant default values are
      # frozen.)
      if !value.frozen? && !value.nil?
        set_value(resource, value)
      end
    end
  end

  if value.nil? && required?(resource_action(resource))
    raise Chef::Exceptions::ValidationFailed, "#{name} is a required property"
  else
    value
  end
end
get_value(resource) click to toggle source

@api private

# File lib/chef/property.rb, line 657
def get_value(resource)
  if instance_variable_name
    resource.instance_variable_get(instance_variable_name)
  else
    resource.send(name)
  end
end
has_default?() click to toggle source

Whether this property has a default value.

@return [Boolean]

# File lib/chef/property.rb, line 299
def has_default?
  options.key?(:default) || name_property?
end
identity?() click to toggle source

Whether this is part of the resource’s natural identity or not.

@return [Boolean]

# File lib/chef/property.rb, line 268
def identity?
  options[:identity]
end
instance_variable_name() click to toggle source

The instance variable associated with this property.

Defaults to ‘@<name>`

@return [Symbol]

# File lib/chef/property.rb, line 222
def instance_variable_name
  if options.key?(:instance_variable_name)
    options[:instance_variable_name]
  elsif name
    :"@#{name}"
  end
end
introduced() click to toggle source

When this property was introduced

@return [String]

# File lib/chef/property.rb, line 211
def introduced
  options[:introduced]
end
is_set?(resource) click to toggle source

Find out whether this property has been set.

This will be true if:

  • The user explicitly set the value

  • The property has a default, and the value was retrieved.

From this point of view, it is worth looking at this as “what does the user think this value should be.” In order words, if the user grabbed the value, even if it was a default, they probably based calculations on it. If they based calculations on it and the value changes, the rest of the world gets inconsistent.

@param resource [Chef::Resource] The resource to get the property from.

@return [Boolean]

# File lib/chef/property.rb, line 482
def is_set?(resource)
  value_is_set?(resource)
end
name() click to toggle source

The name of this property.

@return [String]

# File lib/chef/property.rb, line 184
def name
  options[:name]
end
name_property?() click to toggle source

Whether this is name_property or not.

@return [Boolean]

# File lib/chef/property.rb, line 290
def name_property?
  options[:name_property]
end
required?(action = nil) click to toggle source

Whether this property is required or not.

@return [Boolean]

# File lib/chef/property.rb, line 308
def required?(action = nil)
  if !action.nil? && options[:required].is_a?(Array)
    (options[:required] & Array(action)).any?
  else
    !!options[:required]
  end
end
reset(resource) click to toggle source

Reset the value of this property so that is_set? will return false and the default will be returned in the future.

@param resource [Chef::Resource] The resource to get the property from.

# File lib/chef/property.rb, line 492
def reset(resource)
  reset_value(resource)
end
reset_value(resource) click to toggle source

@api private

# File lib/chef/property.rb, line 684
def reset_value(resource)
  if instance_variable_name
    if value_is_set?(resource)
      resource.remove_instance_variable(instance_variable_name)
    end
  else
    raise ArgumentError, "Property #{name} has no instance variable defined and cannot be reset"
  end
end
sensitive?() click to toggle source

Whether this property is sensitive or not.

Defaults to false.

@return [Boolean]

# File lib/chef/property.rb, line 334
def sensitive?
  options.fetch(:sensitive, false)
end
set(resource, value) click to toggle source

Set the value of this property in the given resource.

Non-lazy values are coerced and validated before being set. Coercion and validation of lazy values is delayed until they are first retrieved.

@param resource [Chef::Resource] The resource to set this property in. @param value The value to set.

@return The value that was set, after coercion (if lazy, still returns

the lazy value)

@raise Chef::Exceptions::ValidationFailed If the value is invalid for

this property.
# File lib/chef/property.rb, line 451
def set(resource, value)
  value = set_value(resource, input_to_stored_value(resource, value))

  if options.key?(:deprecated)
    Chef.deprecated(:property, options[:deprecated])
  end

  if value.nil? && required?(resource_action(resource))
    raise Chef::Exceptions::ValidationFailed, "#{name} is a required property"
  else
    value
  end
end
set_value(resource, value) click to toggle source

@api private

# File lib/chef/property.rb, line 666
def set_value(resource, value)
  if instance_variable_name
    resource.instance_variable_set(instance_variable_name, value)
  else
    resource.send(name, value)
  end
end
skip_docs?() click to toggle source

Whether this property should be skipped for documentation purposes.

Defaults to false.

@return [Boolean]

# File lib/chef/property.rb, line 323
def skip_docs?
  options.fetch(:skip_docs, false)
end
to_s() click to toggle source
# File lib/chef/property.rb, line 175
def to_s
  "#{name || "<property type>"}#{declared_in ? " of resource #{declared_in.resource_name}" : ""}"
end
validate(resource, value) click to toggle source

Validate a value.

Calls Chef::Mixin::ParamsValidate#validate with validation_options as options.

@param resource [Chef::Resource] The resource we’re validating against

(to provide context for the validation).

@param value The value to validate.

@raise Chef::Exceptions::ValidationFailed If the value is invalid for

this property.
# File lib/chef/property.rb, line 536
def validate(resource, value)
  # nils are not validated unless we have an explicit default value
  if !value.nil? || has_default?
    if resource
      resource.validate({ name => value }, { name => validation_options })
    else
      name = self.name || :property_type
      Chef::Mixin::ParamsValidate.validate({ name => value }, { name => validation_options })
    end
  end
end
validation_options() click to toggle source

Validation options. (See Chef::Mixin::ParamsValidate#validate.)

@return [Hash<Symbol,Object>]

# File lib/chef/property.rb, line 343
def validation_options
  @validation_options ||= options.reject do |k, v|
    %i{declared_in name instance_variable_name desired_state identity default name_property coerce required nillable sensitive description introduced deprecated default_description skip_docs}.include?(k)
  end
end
value_is_set?(resource) click to toggle source

@api private

# File lib/chef/property.rb, line 675
def value_is_set?(resource)
  if instance_variable_name
    resource.instance_variable_defined?(instance_variable_name)
  else
    true
  end
end

Private Instance Methods

coerce_and_validate(resource, value) click to toggle source

Coerces and validates the value.

# File lib/chef/property.rb, line 748
def coerce_and_validate(resource, value)
  result = coerce(resource, value)
  validate(resource, result)

  result
end
deep_dup(value) click to toggle source

recursively dup the value

# File lib/chef/property.rb, line 756
def deep_dup(value)
  return value if value.is_a?(DelayedEvaluator)

  visitor = lambda do |obj|
    obj = obj.dup rescue obj
    case obj
    when Hash
      obj.each { |k, v| obj[k] = visitor.call(v) }
    when Array
      obj.each_with_index { |v, i| obj[i] = visitor.call(v) }
    end
    obj
  end
  visitor.call(value)
end
exec_in_resource(resource, proc, *args) click to toggle source
# File lib/chef/property.rb, line 715
def exec_in_resource(resource, proc, *args)
  if resource
    if proc.arity > args.size
      value = proc.call(resource, *args)
    else
      value = resource.instance_exec(*args, &proc)
    end
  else
    # If we don't have a resource yet, we can't exec in resource!
    raise Chef::Exceptions::CannotValidateStaticallyError, "Cannot validate or coerce without a resource"
  end
end
input_to_stored_value(resource, value, is_default: false) click to toggle source
# File lib/chef/property.rb, line 728
def input_to_stored_value(resource, value, is_default: false)
  if value.nil? && !is_default && !explicitly_accepts_nil?(resource)
    value = default
  end
  unless value.is_a?(DelayedEvaluator)
    value = coerce_and_validate(resource, value)
  end
  value
end
property_redefines_method?() click to toggle source
# File lib/chef/property.rb, line 696
def property_redefines_method?
  # We only emit deprecations if this property already exists as an instance method.
  # Weeding out class methods avoids unnecessary deprecations such Chef::Resource
  # defining a `name` property when there's an already-existing `name` method
  # for a Module.
  return false unless declared_in.instance_methods.include?(name)

  # Only emit deprecations for some well-known classes. This will still
  # allow more advanced users to subclass their own custom resources and
  # override their own properties.
  return false unless [ Object, BasicObject, Kernel, Chef::Resource ].include?(declared_in.instance_method(name).owner)

  # Allow top-level Chef::Resource properties, such as `name`, to be overridden.
  # As of this writing, `name` is the only Chef::Resource property created with the
  # `property` definition, but this will allow for future properties to be extended
  # as needed.
  !Chef::Resource.properties.key?(name)
end
resource_action(resource) click to toggle source

action from resource, if available

# File lib/chef/property.rb, line 773
def resource_action(resource)
  resource.action if resource.respond_to?(:action)
end
stored_value_to_output(resource, value) click to toggle source
# File lib/chef/property.rb, line 738
def stored_value_to_output(resource, value)
  # Crack open lazy values before giving the result to the user
  if value.is_a?(DelayedEvaluator)
    value = exec_in_resource(resource, value)
    value = coerce_and_validate(resource, value)
  end
  value
end