Class: Chef::Property

Inherits:
Object
  • Object
show all
Defined in:
lib/chef/property.rb

Overview

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**options) ⇒ Property

Create a new property.

Parameters:

  • 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] :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.



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# 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

Instance Attribute Details

#options ⇒ Object (readonly)

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

See Also:



609
610
611
 
# File 'lib/chef/property.rb', line 609

def options
  @options
end

Class Method Details

.derive(**options) ⇒ Object

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

Examples:

Property.derive(default: 'hi')

Parameters:

  • options (Hash<Symbol,Object>) —

    Validation options. See Chef::Resource.property for the list of options.



51
52
53
 
# File 'lib/chef/property.rb', line 51

def self.derive(**options)
  new(**options)
end

.emit_deprecated_alias(from, to, message, declared_in) ⇒ Object

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

Parameters:

  • from (String) —

    Name of the deprecated property

  • to (String) —

    Name of the correct property

  • message (String) —

    Deprecation message to show to the cookbook author

  • declared_in (Class) —

    Class this property comes from



63
64
65
66
67
68
69
70
71
72
73
74
 
# 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

Instance Method Details

#call(resource, value = NOT_PASSED) ⇒ Object

Handle the property being called.

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

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.

Parameters:

  • resource (Chef::Resource) —

    The resource to get the property from.

  • value (defaults to: NOT_PASSED) —

    The value to set (or NOT_PASSED if it is a get).

Returns:

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



369
370
371
372
373
374
375
 
# 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) ⇒ Object

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.

Parameters:

  • resource (Chef::Resource) —

    The resource we're coercing against (to provide context for the coerce).

  • value —

    The value to coerce.

Returns:

  • The coerced value.

Raises:

  • Chef::Exceptions::ValidationFailed If the value is invalid for this property.



513
514
515
516
517
518
519
520
521
 
# 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 ⇒ Class

The class this property was defined in.

Returns:

  • (Class) 


193
194
195
 
# File 'lib/chef/property.rb', line 193

def declared_in
  options[:declared_in]
end

#default ⇒ Object

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



238
239
240
241
242
243
 
# 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 ⇒ String

A description of the default value of this property.

Returns:



250
251
252
 
# File 'lib/chef/property.rb', line 250

def default_description
  options[:default_description]
end

#derive(**modified_options) ⇒ Property

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

Parameters:

  • options (Hash<Symbol,Object>) —

    List of options that would be passed to #initialize.

Returns:



557
558
559
560
561
562
563
564
565
566
567
568
 
# 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 ⇒ String

A description of this property.

Returns:



202
203
204
 
# File 'lib/chef/property.rb', line 202

def description
  options[:description]
end

#desired_state? ⇒ Boolean

Whether this is part of desired state or not.

Defaults to true.

Returns:

  • (Boolean) 


279
280
281
282
283
 
# File 'lib/chef/property.rb', line 279

def desired_state?
  return true unless options.key?(:desired_state)

  options[:desired_state]
end

#emit_dsl ⇒ Object

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

Creates a getter and setter for the property.



575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
 
# 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 ⇒ Array, NilClass

The equal_to field of this property.

Returns:

  • (Array, NilClass) 


259
260
261
 
# File 'lib/chef/property.rb', line 259

def equal_to
  options[:equal_to]
end

#explicitly_accepts_nil?(resource) ⇒ Boolean

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.

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:

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

property :x, String

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

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

Parameters:

  • resource (Chef::Resource) —

    The resource we're coercing against (to provide context for the coerce).

Returns:

  • (Boolean) —

    Whether this value explicitly accepts nil.



649
650
651
652
653
654
 
# 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) ⇒ Object

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.

Parameters:

  • resource (Chef::Resource) —

    The resource to get the property from.

Returns:

  • The value of the property.

Raises:

  • Chef::Exceptions::ValidationFailed If the value is invalid for this property, or if the value is required and not set.



399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
 
# 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) ⇒ 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. 



657
658
659
660
661
662
663
 
# 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? ⇒ Boolean

Whether this property has a default value.

Returns:

  • (Boolean) 


299
300
301
 
# File 'lib/chef/property.rb', line 299

def has_default?
  options.key?(:default) || name_property?
end

#identity? ⇒ Boolean

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

Returns:

  • (Boolean) 


268
269
270
 
# File 'lib/chef/property.rb', line 268

def identity?
  options[:identity]
end

#instance_variable_name ⇒ Symbol

The instance variable associated with this property.

Defaults to @<name>

Returns:



222
223
224
225
226
227
228
 
# 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 ⇒ String

When this property was introduced

Returns:



211
212
213
 
# File 'lib/chef/property.rb', line 211

def introduced
  options[:introduced]
end

#is_set?(resource) ⇒ Boolean

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.

Parameters:

  • resource (Chef::Resource) —

    The resource to get the property from.

Returns:

  • (Boolean) 


482
483
484
 
# File 'lib/chef/property.rb', line 482

def is_set?(resource)
  value_is_set?(resource)
end

#name ⇒ String

The name of this property.

Returns:



184
185
186
 
# File 'lib/chef/property.rb', line 184

def name
  options[:name]
end

#name_property? ⇒ Boolean

Whether this is name_property or not.

Returns:

  • (Boolean) 


290
291
292
 
# File 'lib/chef/property.rb', line 290

def name_property?
  options[:name_property]
end

#required?(action = nil) ⇒ Boolean

Whether this property is required or not.

Returns:

  • (Boolean) 


308
309
310
311
312
313
314
 
# 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) ⇒ Object

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

Parameters:

  • resource (Chef::Resource) —

    The resource to get the property from.



492
493
494
 
# File 'lib/chef/property.rb', line 492

def reset(resource)
  reset_value(resource)
end

#reset_value(resource) ⇒ 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. 



684
685
686
687
688
689
690
691
692
 
# 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? ⇒ Boolean

Whether this property is sensitive or not.

Defaults to false.

Returns:

  • (Boolean) 


334
335
336
 
# File 'lib/chef/property.rb', line 334

def sensitive?
  options.fetch(:sensitive, false)
end

#set(resource, value) ⇒ Object

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.

Parameters:

  • resource (Chef::Resource) —

    The resource to set this property in.

  • value —

    The value to set.

Returns:

  • The value that was set, after coercion (if lazy, still returns the lazy value)

Raises:

  • Chef::Exceptions::ValidationFailed If the value is invalid for this property.



451
452
453
454
455
456
457
458
459
460
461
462
463
 
# 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) ⇒ 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. 



666
667
668
669
670
671
672
 
# 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? ⇒ Boolean

Whether this property should be skipped for documentation purposes.

Defaults to false.

Returns:

  • (Boolean) 


323
324
325
 
# File 'lib/chef/property.rb', line 323

def skip_docs?
  options.fetch(:skip_docs, false)
end

#to_s ⇒ Object 



175
176
177
 
# 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) ⇒ Object

Validate a value.

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

Parameters:

  • resource (Chef::Resource) —

    The resource we're validating against (to provide context for the validation).

  • value —

    The value to validate.

Raises:

  • Chef::Exceptions::ValidationFailed If the value is invalid for this property.



536
537
538
539
540
541
542
543
544
545
546
 
# 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 ⇒ Hash<Symbol,Object>

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

Returns:



343
344
345
346
347
 
# 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) ⇒ Boolean

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:

  • (Boolean) 


675
676
677
678
679
680
681
 
# 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