chef 12.4.3 → 12.5.0.alpha.1

data/lib/chef/constants.rb

@@ -0,0 +1,27 @@
+#
+# Author:: John Keiser <jkeiser@chef.io>
+# Copyright:: Copyright (c) 2015 Opscode, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+class Chef
+  NOT_PASSED = Object.new
+  def NOT_PASSED.to_s
+    "NOT_PASSED"
+  end
+  def NOT_PASSED.inspect
+    to_s
+  end
+  NOT_PASSED.freeze
+end

data/lib/chef/delayed_evaluator.rb

@@ -0,0 +1,21 @@
+#
+# Author:: John Keiser <jkeiser@chef.io>
+# Copyright:: Copyright (c) 2015 Opscode, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+class Chef
+  class DelayedEvaluator < Proc
+  end
+end

data/lib/chef/dsl/recipe.rb

@@ -122,9 +122,9 @@ class Chef
 
       def describe_self_for_error
         if respond_to?(:name)
-          %Q[`#{self.class.name} "#{name}"']
+          %Q[`#{self.class} "#{name}"']
         elsif respond_to?(:recipe_name)
-          %Q[`#{self.class.name} "#{recipe_name}"']
+          %Q[`#{self.class} "#{recipe_name}"']
         else
           to_s
         end
@@ -176,6 +176,24 @@ class Chef
           raise NameError, "No resource, method, or local variable named `#{method_symbol}' for #{describe_self_for_error}"
         end
       end
+
+      module FullDSL
+        require 'chef/dsl/data_query'
+        require 'chef/dsl/platform_introspection'
+        require 'chef/dsl/include_recipe'
+        require 'chef/dsl/registry_helper'
+        require 'chef/dsl/reboot_pending'
+        require 'chef/dsl/audit'
+        require 'chef/dsl/powershell'
+        include Chef::DSL::DataQuery
+        include Chef::DSL::PlatformIntrospection
+        include Chef::DSL::IncludeRecipe
+        include Chef::DSL::Recipe
+        include Chef::DSL::RegistryHelper
+        include Chef::DSL::RebootPending
+        include Chef::DSL::Audit
+        include Chef::DSL::Powershell
+      end
     end
   end
 end

data/lib/chef/event_dispatch/base.rb

@@ -269,26 +269,37 @@ class Chef
       # def notifications_resolved
       # end
 
+      #
+      # Resource events and ordering:
+      #
+      # 1. Start the action
+      #    - resource_action_start
+      # 2. Check the guard
+      #    - resource_skipped: (goto 7) if only_if/not_if say to skip
+      # 3. Load the current resource
+      #    - resource_current_state_loaded
+      #    - resource_current_state_load_bypassed (if not why-run safe)
+      # 4. Check if why-run safe
+      #    - resource_bypassed: (goto 7) if not why-run safe
+      # 5. During processing:
+      #    - resource_update_applied: For each actual change (many per action)
+      # 6. Processing complete status:
+      #    - resource_failed if the resource threw an exception while running
+      #    - resource_failed_retriable: (goto 3) if resource failed and will be retried
+      #    - resource_updated if the resource was updated (resource_update_applied will have been called)
+      #    - resource_up_to_date if the resource was up to date (no resource_update_applied)
+      # 7. Processing complete:
+      #    - resource_completed
+      #
+
       # Called before action is executed on a resource.
       def resource_action_start(resource, action, notification_type=nil, notifier=nil)
       end
 
-      # Called when a resource fails, but will retry.
-      def resource_failed_retriable(resource, action, retry_count, exception)
-      end
-
-      # Called when a resource fails and will not be retried.
-      def resource_failed(resource, action, exception)
-      end
-
       # Called when a resource action has been skipped b/c of a conditional
       def resource_skipped(resource, action, conditional)
       end
 
-      # Called when a resource action has been completed
-      def resource_completed(resource)
-      end
-
       # Called after #load_current_resource has run.
       def resource_current_state_loaded(resource, action, current_resource)
       end
@@ -302,21 +313,34 @@ class Chef
       def resource_bypassed(resource, action, current_resource)
       end
 
-      # Called when a resource has no converge actions, e.g., it was already correct.
-      def resource_up_to_date(resource, action)
-      end
-
       # Called when a change has been made to a resource. May be called multiple
       # times per resource, e.g., a file may have its content updated, and then
       # its permissions updated.
       def resource_update_applied(resource, action, update)
       end
 
+      # Called when a resource fails, but will retry.
+      def resource_failed_retriable(resource, action, retry_count, exception)
+      end
+
+      # Called when a resource fails and will not be retried.
+      def resource_failed(resource, action, exception)
+      end
+
       # Called after a resource has been completely converged, but only if
       # modifications were made.
       def resource_updated(resource, action)
       end
 
+      # Called when a resource has no converge actions, e.g., it was already correct.
+      def resource_up_to_date(resource, action)
+      end
+
+      # Called when a resource action has been completed
+      def resource_completed(resource)
+      end
+
+
       # A stream has opened.
       def stream_opened(stream, options = {})
       end

data/lib/chef/event_dispatch/dsl.rb

@@ -0,0 +1,64 @@
+#
+# Author:: Ranjib Dey (<ranjib@linux.com>)
+# Copyright:: Copyright (c) 2015 Ranjib Dey
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+require 'chef/event_dispatch/base'
+require 'chef/exceptions'
+require 'chef/config'
+
+class Chef
+  module EventDispatch
+    class DSL
+      attr_reader :handler
+
+      def initialize(name)
+        klass = Class.new(Chef::EventDispatch::Base) do
+          attr_reader :name
+        end
+        @handler = klass.new
+        @handler.instance_variable_set(:@name, name)
+
+        # Use event.register API to add anonymous handler if Chef.run_context
+        # and associated event dispatcher is set, else fallback to
+        # Chef::Config[:hanlder]
+        if Chef.run_context && Chef.run_context.events
+          Chef::Log.debug("Registering handler '#{name}' using events api")
+          Chef.run_context.events.register(handler)
+        else
+          Chef::Log.debug("Registering handler '#{name}' using global config")
+          Chef::Config[:event_handlers] << handler
+        end
+      end
+
+      # Adds a new event handler derived from base handler
+      # with user defined block against a chef event
+      #
+      # @return [Chef::EventDispatch::Base] a base handler object
+      def on(event_type, &block)
+        validate!(event_type)
+        handler.define_singleton_method(event_type) do |*args|
+          instance_exec(*args, &block)
+        end
+      end
+
+      private
+      def validate!(event_type)
+        all_event_types = (Chef::EventDispatch::Base.instance_methods - Object.instance_methods)
+        raise Chef::Exceptions::InvalidEventType, "Invalid event type: #{event_type}" unless all_event_types.include?(event_type)
+      end
+    end
+  end
+end

data/lib/chef/exceptions.rb

@@ -17,12 +17,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'chef-config/exceptions'
+
 class Chef
   # == Chef::Exceptions
   # Chef's custom exceptions are all contained within the Chef::Exceptions
   # namespace.
   class Exceptions
 
+    ConfigurationError = ChefConfig::ConfigurationError
+
     # Backcompat with Chef::ShellOut code:
     require 'mixlib/shellout/exceptions'
 
@@ -68,7 +72,6 @@ class Chef
     class DuplicateRole < RuntimeError; end
     class ValidationFailed < ArgumentError; end
     class InvalidPrivateKey < ArgumentError; end
-    class ConfigurationError < ArgumentError; end
     class MissingKeyAttribute < ArgumentError; end
     class KeyCommandInputError < ArgumentError; end
     class InvalidKeyArgument < ArgumentError; end
@@ -100,6 +103,8 @@ class Chef
     class ProviderNotFound < RuntimeError; end
     NoProviderAvailable = ProviderNotFound
     class VerificationNotFound < RuntimeError; end
+    class InvalidEventType < ArgumentError; end
+    class MultipleIdentityError < RuntimeError; end
 
     # Can't find a Resource of this type that is valid on this platform.
     class NoSuchResourceType < NameError

data/lib/chef/formatters/doc.rb

@@ -22,6 +22,7 @@ class Chef
         @failed_audits = 0
         @start_time = Time.now
         @end_time = @start_time
+        @skipped_resources = 0
       end
 
       def elapsed_time
@@ -33,7 +34,7 @@ class Chef
       end
 
       def total_resources
-        @up_to_date_resources + @updated_resources
+        @up_to_date_resources + @updated_resources + @skipped_resources
       end
 
       def total_audits
@@ -236,6 +237,7 @@ class Chef
 
       # Called when a resource action has been skipped b/c of a conditional
       def resource_skipped(resource, action, conditional)
+        @skipped_resources += 1
         # TODO: more info about conditional
         puts " (skipped due to #{conditional.short_description})", :stream => resource
         unindent

data/lib/chef/guard_interpreter/resource_guard_interpreter.rb

@@ -68,7 +68,9 @@ class Chef
         run_action = action || @resource.action
 
         begin
-          # Coerce to an array to be safe.
+          # Coerce to an array to be safe. This could happen with a legacy
+          # resource or something overriding the default_action code in a
+          # subclass.
           Array(run_action).each {|action_to_run| @resource.run_action(action_to_run) }
           resource_updated = @resource.updated
         rescue Mixlib::ShellOut::ShellCommandFailed

data/lib/chef/http/http_request.rb

@@ -40,7 +40,7 @@ class Chef
 
       engine = defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby"
 
-      UA_COMMON = "/#{::Chef::VERSION} (#{engine}-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}; ohai-#{Ohai::VERSION}; #{RUBY_PLATFORM}; +http://opscode.com)"
+      UA_COMMON = "/#{::Chef::VERSION} (#{engine}-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}; ohai-#{Ohai::VERSION}; #{RUBY_PLATFORM}; +https://chef.io)"
       DEFAULT_UA = "Chef Client" << UA_COMMON
 
       USER_AGENT = "User-Agent".freeze

data/lib/chef/knife/bootstrap/templates/chef-full.erb

@@ -226,6 +226,6 @@ cat > /etc/chef/first-boot.json <<EOP
 <%= Chef::JSONCompat.to_json(first_boot) %>
 EOP
 
-echo "Starting first Chef Client run..."
+echo "Starting the first Chef Client run..."
 
 <%= start_chef %>'

data/lib/chef/knife/ssl_check.rb

@@ -73,11 +73,12 @@ class Chef
         exit 1
       end
 
-
       def verify_peer_socket
         @verify_peer_socket ||= begin
           tcp_connection = TCPSocket.new(host, port)
-          OpenSSL::SSL::SSLSocket.new(tcp_connection, verify_peer_ssl_context)
+          ssl_client = OpenSSL::SSL::SSLSocket.new(tcp_connection, verify_peer_ssl_context)
+          ssl_client.hostname = host
+          ssl_client
         end
       end
 

data/lib/chef/knife/user_edit.rb

@@ -57,7 +57,6 @@ EOF
         end
 
         original_user = Chef::UserV1.load(@user_name).to_hash
-
         # DEPRECATION NOTE
         # Remove this if statement and corrosponding code post OSC 11 support.
         #
@@ -73,7 +72,7 @@ EOF
             user.update
             ui.msg("Saved #{user}.")
           else
-            ui.msg("User unchaged, not saving.")
+            ui.msg("User unchanged, not saving.")
           end
         end
 

data/lib/chef/mixin/params_validate.rb

@@ -15,9 +15,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'chef/constants'
+require 'chef/property'
+require 'chef/delayed_evaluator'
+
 class Chef
-  class DelayedEvaluator < Proc
-  end
   module Mixin
     module ParamsValidate
 
@@ -32,20 +34,55 @@ class Chef
       # Would raise an exception if the value of :one above is not a kind_of? string.  Valid
       # map options are:
       #
-      # :default:: Sets the default value for this parameter.
-      # :callbacks:: Takes a hash of Procs, which should return true if the argument is valid.
-      #              The key will be inserted into the error message if the Proc does not return true:
-      #                 "Option #{key}'s value #{value} #{message}!"
-      # :kind_of:: Ensure that the value is a kind_of?(Whatever).  If passed an array, it will ensure
-      #            that the value is one of those types.
-      # :respond_to:: Ensure that the value has a given method.  Takes one method name or an array of
-      #               method names.
-      # :required:: Raise an exception if this parameter is missing. Valid values are true or false,
-      #             by default, options are not required.
-      # :regex:: Match the value of the parameter against a regular expression.
-      # :equal_to:: Match the value of the parameter with ==.  An array means it can be equal to any
-      #             of the values.
+      # @param opts [Hash<Symbol,Object>] Validation opts.
+      #   @option opts [Object,Array] :is An object, or list of
+      #     objects, that must match the value using Ruby's `===` operator
+      #     (`opts[:is].any? { |v| v === value }`). (See #_pv_is.)
+      #   @option opts [Object,Array] :equal_to An object, or list
+      #     of objects, that must be equal to the value using Ruby's `==`
+      #     operator (`opts[:is].any? { |v| v == value }`)  (See #_pv_equal_to.)
+      #   @option opts [Regexp,Array<Regexp>] :regex An object, or
+      #     list of objects, that must match the value with `regex.match(value)`.
+      #     (See #_pv_regex)
+      #   @option opts [Class,Array<Class>] :kind_of A class, or
+      #     list of classes, that the value must be an instance of.  (See
+      #     #_pv_kind_of.)
+      #   @option opts [Hash<String,Proc>] :callbacks A hash of
+      #     messages -> procs, all of which match the value. The proc must
+      #     return a truthy or falsey value (true means it matches).  (See
+      #     #_pv_callbacks.)
+      #   @option opts [Symbol,Array<Symbol>] :respond_to A method
+      #     name, or list of method names, the value must respond to.  (See
+      #     #_pv_respond_to.)
+      #   @option opts [Symbol,Array<Symbol>] :cannot_be A property,
+      #     or a list of properties, that the value cannot have (such as `:nil` or
+      #     `:empty`). The method with a questionmark at the end is called on the
+      #     value (e.g. `value.empty?`). If the value does not have this method,
+      #     it is considered valid (i.e. if you don't respond to `empty?` we
+      #     assume you are not empty).  (See #_pv_cannot_be.)
+      #   @option opts [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).
+      #     (See #_pv_coerce.) (See #_pv_coerce.)
+      #   @option opts [Boolean] :required `true` if this property
+      #     must be present and not `nil`; `false` otherwise. This is checked
+      #     after the resource is fully initialized. (See #_pv_required.)
+      #   @option opts [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. (See
+      #     #_pv_name_property.)
+      #   @option opts [Boolean] :name_attribute Same as `name_property`.
+      #   @option opts [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).  (See #_pv_default.)
+      #
       def validate(opts, map)
+        map = map.validation_options if map.is_a?(Property)
+
         #--
         # validate works by taking the keys in the validation map, assuming it's a hash, and
         # looking for _pv_:symbol as methods.  Assuming it find them, it calls the right
@@ -65,7 +102,7 @@ class Chef
             true
           when Hash
             validation.each do |check, carg|
-              check_method = "_pv_#{check.to_s}"
+              check_method = "_pv_#{check}"
               if self.respond_to?(check_method, true)
                 self.send(check_method, opts, key, carg)
               else
@@ -81,162 +118,352 @@ class Chef
         DelayedEvaluator.new(&block)
       end
 
-      def set_or_return(symbol, arg, validation)
-        iv_symbol = "@#{symbol.to_s}".to_sym
-        if arg == nil && self.instance_variable_defined?(iv_symbol) == true
-          ivar = self.instance_variable_get(iv_symbol)
-          if(ivar.is_a?(DelayedEvaluator))
-            validate({ symbol => ivar.call }, { symbol => validation })[symbol]
-          else
-            ivar
-          end
-        else
-          if(arg.is_a?(DelayedEvaluator))
-            val = arg
-          else
-            val = validate({ symbol => arg }, { symbol => validation })[symbol]
+      def set_or_return(symbol, value, validation)
+        property = SetOrReturnProperty.new(name: symbol, **validation)
+        property.call(self, value)
+      end
 
-            # Handle the case where the "default" was a DelayedEvaluator. In
-            # this case, the block yields an optional parameter of +self+,
-            # which is the equivalent of "new_resource"
-            if val.is_a?(DelayedEvaluator)
-              val = val.call(self)
-            end
-          end
-          self.instance_variable_set(iv_symbol, val)
+      private
+
+      def explicitly_allows_nil?(key, validation)
+        validation.has_key?(:is) && _pv_is({ key => nil }, key, validation[:is], raise_error: false)
+      end
+
+      # Return the value of a parameter, or nil if it doesn't exist.
+      def _pv_opts_lookup(opts, key)
+        if opts.has_key?(key.to_s)
+          opts[key.to_s]
+        elsif opts.has_key?(key.to_sym)
+          opts[key.to_sym]
+        else
+          nil
         end
       end
 
-      private
+      # Raise an exception if the parameter is not found.
+      def _pv_required(opts, key, is_required=true, explicitly_allows_nil=false)
+        if is_required
+          return true if opts.has_key?(key.to_s) && (explicitly_allows_nil || !opts[key.to_s].nil?)
+          return true if opts.has_key?(key.to_sym) && (explicitly_allows_nil || !opts[key.to_sym].nil?)
+          raise Exceptions::ValidationFailed, "Required argument #{key.inspect} is missing!"
+        end
+        true
+      end
 
-        # Return the value of a parameter, or nil if it doesn't exist.
-        def _pv_opts_lookup(opts, key)
-          if opts.has_key?(key.to_s)
-            opts[key.to_s]
-          elsif opts.has_key?(key.to_sym)
-            opts[key.to_sym]
-          else
-            nil
+      #
+      # List of things values must be equal to.
+      #
+      # Uses Ruby's `==` to evaluate (equal_to == value).  At least one must
+      # match for the value to be valid.
+      #
+      # `nil` passes this validation automatically.
+      #
+      # @return [Array,nil] List of things values must be equal to, or nil if
+      #   equal_to is unspecified.
+      #
+      def _pv_equal_to(opts, key, to_be)
+        value = _pv_opts_lookup(opts, key)
+        unless value.nil?
+          to_be = Array(to_be)
+          to_be.each do |tb|
+            return true if value == tb
           end
+          raise Exceptions::ValidationFailed, "Option #{key} must be equal to one of: #{to_be.join(", ")}!  You passed #{value.inspect}."
         end
+      end
 
-        # Raise an exception if the parameter is not found.
-        def _pv_required(opts, key, is_required=true)
-          if is_required
-            if (opts.has_key?(key.to_s) && !opts[key.to_s].nil?) ||
-                (opts.has_key?(key.to_sym) && !opts[key.to_sym].nil?)
-              true
-            else
-              raise Exceptions::ValidationFailed, "Required argument #{key} is missing!"
-            end
+      #
+      # List of things values must be instances of.
+      #
+      # Uses value.kind_of?(kind_of) to evaluate. At least one must match for
+      # the value to be valid.
+      #
+      # `nil` automatically passes this validation.
+      #
+      def _pv_kind_of(opts, key, to_be)
+        value = _pv_opts_lookup(opts, key)
+        unless value.nil?
+          to_be = Array(to_be)
+          to_be.each do |tb|
+            return true if value.kind_of?(tb)
           end
+          raise Exceptions::ValidationFailed, "Option #{key} must be a kind of #{to_be}!  You passed #{value.inspect}."
         end
+      end
 
-        def _pv_equal_to(opts, key, to_be)
-          value = _pv_opts_lookup(opts, key)
-          unless value.nil?
-            passes = false
-            Array(to_be).each do |tb|
-              passes = true if value == tb
-            end
-            unless passes
-              raise Exceptions::ValidationFailed, "Option #{key} must be equal to one of: #{to_be.join(", ")}!  You passed #{value.inspect}."
+      #
+      # List of method names values must respond to.
+      #
+      # Uses value.respond_to?(respond_to) to evaluate. At least one must match
+      # for the value to be valid.
+      #
+      def _pv_respond_to(opts, key, method_name_list)
+        value = _pv_opts_lookup(opts, key)
+        unless value.nil?
+          Array(method_name_list).each do |method_name|
+            unless value.respond_to?(method_name)
+              raise Exceptions::ValidationFailed, "Option #{key} must have a #{method_name} method!"
             end
           end
         end
+      end
 
-        # Raise an exception if the parameter is not a kind_of?(to_be)
-        def _pv_kind_of(opts, key, to_be)
-          value = _pv_opts_lookup(opts, key)
-          unless value.nil?
-            passes = false
-            Array(to_be).each do |tb|
-              passes = true if value.kind_of?(tb)
-            end
-            unless passes
-              raise Exceptions::ValidationFailed, "Option #{key} must be a kind of #{to_be}!  You passed #{value.inspect}."
+      #
+      # List of things that must not be true about the value.
+      #
+      # Calls `value.<thing>?` All responses must be false for the value to be
+      # valid.
+      # Values which do not respond to <thing>? are considered valid (because if
+      # a value doesn't respond to `:readable?`, then it probably isn't
+      # readable.)
+      #
+      # @example
+      #   ```ruby
+      #   property :x, cannot_be: [ :nil, :empty ]
+      #   x [ 1, 2 ] #=> valid
+      #   x 1        #=> valid
+      #   x []       #=> invalid
+      #   x nil      #=> invalid
+      #   ```
+      #
+      def _pv_cannot_be(opts, key, predicate_method_base_name)
+        value = _pv_opts_lookup(opts, key)
+        if !value.nil?
+          Array(predicate_method_base_name).each do |method_name|
+            predicate_method = :"#{method_name}?"
+
+            if value.respond_to?(predicate_method)
+              if value.send(predicate_method)
+                raise Exceptions::ValidationFailed, "Option #{key} cannot be #{predicate_method_base_name}"
+              end
             end
           end
         end
+      end
 
-        # Raise an exception if the parameter does not respond to a given set of methods.
-        def _pv_respond_to(opts, key, method_name_list)
-          value = _pv_opts_lookup(opts, key)
-          unless value.nil?
-            Array(method_name_list).each do |method_name|
-              unless value.respond_to?(method_name)
-                raise Exceptions::ValidationFailed, "Option #{key} must have a #{method_name} method!"
-              end
-            end
+      #
+      # The default value for a property.
+      #
+      # When the property is not assigned, this will be used.
+      #
+      # If this is a lazy value, it will either be passed the resource as a value,
+      # or if the lazy proc does not take parameters, it will be run in the
+      # context of the instance with instance_eval.
+      #
+      # @example
+      #   ```ruby
+      #   property :x, default: 10
+      #   ```
+      #
+      # @example
+      #   ```ruby
+      #   property :x
+      #   property :y, default: lazy { x+2 }
+      #   ```
+      #
+      # @example
+      #   ```ruby
+      #   property :x
+      #   property :y, default: lazy { |r| r.x+2 }
+      #   ```
+      #
+      def _pv_default(opts, key, default_value)
+        value = _pv_opts_lookup(opts, key)
+        if value.nil?
+          default_value = default_value.freeze if !default_value.is_a?(DelayedEvaluator)
+          opts[key] = default_value
+        end
+      end
+
+      #
+      # List of regexes values that must match.
+      #
+      # Uses regex.match() to evaluate. At least one must match for the value to
+      # be valid.
+      #
+      # `nil` passes regex validation automatically.
+      #
+      # @example
+      #   ```ruby
+      #   property :x, regex: [ /abc/, /xyz/ ]
+      #   ```
+      #
+      def _pv_regex(opts, key, regex)
+        value = _pv_opts_lookup(opts, key)
+        if !value.nil?
+          Array(regex).each do |r|
+            return true if r.match(value.to_s)
           end
+          raise Exceptions::ValidationFailed, "Option #{key}'s value #{value} does not match regular expression #{regex.inspect}"
         end
+      end
 
-        # Assert that parameter returns false when passed a predicate method.
-        # For example, :cannot_be => :blank will raise a Exceptions::ValidationFailed
-        # error value.blank? returns a 'truthy' (not nil or false) value.
-        #
-        # Note, this will *PASS* if the object doesn't respond to the method.
-        # So, to make sure a value is not nil and not blank, you need to do
-        # both :cannot_be => :blank *and* :cannot_be => :nil (or :required => true)
-        def _pv_cannot_be(opts, key, predicate_method_base_name)
-          value = _pv_opts_lookup(opts, key)
-          predicate_method = (predicate_method_base_name.to_s + "?").to_sym
-
-          if value.respond_to?(predicate_method)
-            if value.send(predicate_method)
-              raise Exceptions::ValidationFailed, "Option #{key} cannot be #{predicate_method_base_name}"
+      #
+      # List of procs we pass the value to.
+      #
+      # All procs must return true for the value to be valid. If any procs do
+      # not return true, the key will be used for the message: `"Property x's
+      # value :y <message>"`.
+      #
+      # @example
+      #   ```ruby
+      #   property :x, callbacks: { "is bigger than 10" => proc { |v| v <= 10 }, "is not awesome" => proc { |v| !v.awesome }}
+      #   ```
+      #
+      def _pv_callbacks(opts, key, callbacks)
+        raise ArgumentError, "Callback list must be a hash!" unless callbacks.kind_of?(Hash)
+        value = _pv_opts_lookup(opts, key)
+        if !value.nil?
+          callbacks.each do |message, zeproc|
+            if zeproc.call(value) != true
+              raise Exceptions::ValidationFailed, "Option #{key}'s value #{value} #{message}!"
             end
           end
         end
+      end
 
-        # Assign a default value to a parameter.
-        def _pv_default(opts, key, default_value)
-          value = _pv_opts_lookup(opts, key)
-          if value == nil
-            opts[key] = default_value
+      #
+      # Allows a parameter to default to the value of the resource name.
+      #
+      # @example
+      #   ```ruby
+      #    property :x, name_property: true
+      #   ```
+      #
+      def _pv_name_property(opts, key, is_name_property=true)
+        if is_name_property
+          if opts[key].nil?
+            opts[key] = self.instance_variable_get(:"@name")
           end
         end
+      end
+      alias :_pv_name_attribute :_pv_name_property
 
-        # Check a parameter against a regular expression.
-        def _pv_regex(opts, key, regex)
-          value = _pv_opts_lookup(opts, key)
-          if value != nil
-            passes = false
-            [ regex ].flatten.each do |r|
-              if value != nil
-                if r.match(value.to_s)
-                  passes = true
-                end
-              end
-            end
-            unless passes
-              raise Exceptions::ValidationFailed, "Option #{key}'s value #{value} does not match regular expression #{regex.inspect}"
-            end
+      #
+      # List of valid things values can be.
+      #
+      # Uses Ruby's `===` to evaluate (is === value).  At least one must match
+      # for the value to be valid.
+      #
+      # If a proc is passed, it is instance_eval'd in the resource, passed the
+      # value, and must return a truthy or falsey value.
+      #
+      # @example Class
+      #   ```ruby
+      #   property :x, String
+      #   x 'valid' #=> valid
+      #   x 1       #=> invalid
+      #   x nil     #=> invalid
+      #
+      # @example Value
+      #   ```ruby
+      #   property :x, [ :a, :b, :c, nil ]
+      #   x :a  #=> valid
+      #   x nil #=> valid
+      #   ```
+      #
+      # @example Regex
+      #   ```ruby
+      #   property :x, /bar/
+      #   x 'foobar' #=> valid
+      #   x 'foo'    #=> invalid
+      #   x nil      #=> invalid
+      #   ```
+      #
+      # @example Proc
+      #   ```ruby
+      #   property :x, proc { |x| x > y }
+      #   property :y, default: 2
+      #   x 3 #=> valid
+      #   x 1 #=> invalid
+      #   ```
+      #
+      # @example Property
+      #   ```ruby
+      #   type = Property.new(is: String)
+      #   property :x, type
+      #   x 'foo' #=> valid
+      #   x 1     #=> invalid
+      #   x nil   #=> invalid
+      #   ```
+      #
+      # @example RSpec Matcher
+      #   ```ruby
+      #   include RSpec::Matchers
+      #   property :x, a_string_matching /bar/
+      #   x 'foobar' #=> valid
+      #   x 'foo'    #=> invalid
+      #   x nil      #=> invalid
+      #   ```
+      #
+      def _pv_is(opts, key, to_be, raise_error: true)
+        return true if !opts.has_key?(key.to_s) && !opts.has_key?(key.to_sym)
+        value = _pv_opts_lookup(opts, key)
+        to_be = [ to_be ].flatten(1)
+        to_be.each do |tb|
+          case tb
+          when Proc
+            return true if instance_exec(value, &tb)
+          when Property
+            validate(opts, { key => tb.validation_options })
+            return true
+          else
+            return true if tb === value
           end
         end
 
-        # Check a parameter against a hash of proc's.
-        def _pv_callbacks(opts, key, callbacks)
-          raise ArgumentError, "Callback list must be a hash!" unless callbacks.kind_of?(Hash)
-          value = _pv_opts_lookup(opts, key)
-          if value != nil
-            callbacks.each do |message, zeproc|
-              if zeproc.call(value) != true
-                raise Exceptions::ValidationFailed, "Option #{key}'s value #{value} #{message}!"
-              end
-            end
+        if raise_error
+          raise Exceptions::ValidationFailed, "Option #{key} must be one of: #{to_be.join(", ")}!  You passed #{value.inspect}."
+        else
+          false
+        end
+      end
+
+      #
+      # Method to mess with a value before it is validated and stored.
+      #
+      # Allows you to transform values into a canonical form that is easy to
+      # work with.
+      #
+      # This is passed the value to transform, and is run in the context of the
+      # instance (so it has access to other resource properties). It must return
+      # the value that will be stored in the instance.
+      #
+      # @example
+      #   ```ruby
+      #   property :x, Integer, coerce: { |v| v.to_i }
+      #   ```
+      #
+      def _pv_coerce(opts, key, coercer)
+        if opts.has_key?(key.to_s)
+          opts[key.to_s] = instance_exec(opts[key], &coercer)
+        elsif opts.has_key?(key.to_sym)
+          opts[key.to_sym] = instance_exec(opts[key], &coercer)
+        end
+      end
+
+      # Used by #set_or_return to avoid emitting a deprecation warning for
+      # "value nil" and to keep default stickiness working exactly the same
+      # @api private
+      class SetOrReturnProperty < Chef::Property
+        def get(resource)
+          value = super
+          # All values are sticky, frozen or not
+          if !is_set?(resource)
+            set_value(resource, value)
           end
+          value
         end
 
-        # Allow a parameter to default to @name
-        def _pv_name_attribute(opts, key, is_name_attribute=true)
-          if is_name_attribute
-            if opts[key] == nil
-              opts[key] = self.instance_variable_get("@name")
-            end
+        def call(resource, value=NOT_PASSED)
+          # setting to nil does a get
+          if value.nil? && !explicitly_accepts_nil?(resource)
+            get(resource)
+          else
+            super
           end
         end
+      end
     end
   end
 end
-