chef-resource 0.2.2

data/files/lib/chef_resource/resource/struct_resource.rb

@@ -0,0 +1,410 @@
+require 'chef_resource/errors'
+require 'chef_resource/resource'
+
+module ChefResource
+  module Resource
+    #
+    # A Resource with property_types and named getter/setters.
+    #
+    # The corresponding Type is
+    #
+    # @example
+    # class Address
+    #   include ChefResource::Resource::StructResource
+    #   extend ChefResource::Resource::StructResourceType
+    #   property :street
+    #   property :city
+    #   property :state
+    # end
+    # class Person
+    #   include ChefResource::Resource::StructResource
+    #   extend ChefResource::Resource::StructResourceType
+    #   property :name
+    #   property :home_address, Address
+    # end
+    #
+    # p = Person.open
+    # a = Address.open
+    # p.home_address = a # Sets p.updates[:home_address] = P::HomeAddress.open(p.address)
+    # p.home_address.city = 'Malarky' # p.address.updates[:city] = 'Malarky'
+    # p.update
+    # # first does p.home_address.update
+    # # -> sets p.home_address.current_resource.city -> a.city = 'Malarky'
+    # # sets p.current_resource.home_address = p.home_address.current_resource
+    #
+    module StructResource
+      include Resource
+
+      #
+      # Resource read/modify interface: reopen, identity, explicit_property_values
+      #
+
+      #
+      # Get a new copy of the Resource with only identity values set.
+      #
+      # Note: the Resource remains in :created state, not :identity_defined as
+      # one would get from `open`.  Call resource_identity_defined if you want
+      # to be able to retrieve actual values.
+      #
+      # This method is used by ResourceType.get() and Resource.reload.
+      #
+      def reopen_resource
+        # Create a new Resource of our same type, with just identity values.
+        resource = self.class.new
+        explicit_property_values.each do |name,value|
+          resource.explicit_property_values[name] = value if self.class.property_types[name].identity?
+        end
+        resource
+      end
+
+      #
+      # Get the identity string of the resource.
+      #
+      def resource_identity_string
+        positionals = []
+        named = {}
+        self.class.property_types.each do |name, type|
+          next if !explicit_property_values.has_key?(name)
+          if type.identity?
+            value = public_send(name)
+            if type.required?
+              positionals << value
+            else
+              named[name] = value
+            end
+          end
+        end
+        if named.empty?
+          if positionals.empty?
+            return ""
+          elsif positionals.size == 1
+            return positionals[0].to_s
+          end
+        end
+        (positionals.map { |value| value.inspect } +
+               named.map { |name,value| "#{name}: #{value.inspect}" }).join(",")
+      end
+
+      #
+      # Tell whether a particular attribute is set.
+      #
+      # @param name [Symbol] The name of the attribute
+      # @return [Boolean] Whether the attribute is set
+      #
+      def is_set?(name)
+        explicit_property_values.has_key?(name)
+      end
+
+      #
+      # Define the identity of this struct, based on the given arguments and
+      # block.  After this method, the identity is frozen.
+      #
+      # @param *args The arguments.  Generally the user passed you these from
+      #   some other function, and you are trusting the struct to do the right
+      #   thing with them.
+      # @param &define_identity_block A block that should run after the arguments
+      #   are parsed but before the resource identity is frozen.
+      #
+      def define_identity(*args, &define_identity_block)
+        #
+        # Process named arguments - open(..., a: 1, b: 2, c: 3, d: 4)
+        #
+        if args[-1].is_a?(Hash)
+          named_args = args.pop
+          named_args.each do |name, value|
+            type = self.class.property_types[name]
+            raise ArgumentError, "Property #{name} was passed to #{self.class}.define_identity, but does not exist on #{self.class}!" if !type
+            raise ArgumentError, "#{self.class}.open only takes identity properties, and #{name} is not an identity property on #{self.class}!" if !type.identity?
+            public_send(name, value)
+          end
+        end
+
+        #
+        # Process positional arguments - open(1, 2, 3, ...)
+        #
+        required_identity_properties = self.class.property_types.values.
+          select { |attr| attr.identity? && attr.required? }.
+          map { |attr| attr.property_name }
+
+        if args.size > required_identity_properties.size
+          raise ArgumentError, "Too many arguments to #{self.class}.define_identity! (#{args.size} for #{required_identity_properties.size})!"
+        end
+        required_identity_properties.each_with_index do |name, index|
+          if args.size > index
+            # If the argument was passed positionally (open(a, b, c ...)) set it from that.
+            if named_args && named_args.has_key?(name)
+              raise ArgumentError, "Property #{name} specified twice in #{self}.define_identity!  Both as argument ##{index} and as a named argument."
+            end
+            public_send(name, args[index])
+          else
+            # If the argument wasn't passed positionally, check whether it was passed in the hash.  If not, error.
+            if !named_args || !named_args.has_key?(name)
+              raise ArgumentError, "Required property #{name} not passed to #{self}.define_identity!"
+            end
+          end
+        end
+
+        #
+        # Run the block
+        #
+        instance_eval(&define_identity_block) if define_identity_block
+
+        #
+        # Freeze the identity properties
+        #
+        resource_identity_defined
+      end
+
+      #
+      # Reset changes to this struct (or to a property).
+      #
+      # Reset without parameters never resets identity properties--only normal
+      # properties.
+      #
+      # @param name Reset the property named `name`.  If not passed, resets
+      #    all properties.
+      # @raise PropertyDefinedError if the named property being referenced is
+      #   defined (i.e. we are in identity_defined or fully_defined state).
+      # @raise ResourceStateError if we are in fully_defined state.
+      #
+      def reset(name=nil)
+        if name
+          property_type = self.class.property_types[name]
+          if !property_type
+            raise ArgumentError, "#{self.class} does not have property #{name}, cannot reset!"
+          end
+          if property_type.identity?
+            if resource_state != :created
+              raise PropertyDefinedError.new("Identity property #{self.class}.#{name} cannot be reset after open() or get() has been called (after the identity has been fully defined).  Current sate: #{resource_state}", self, property_type)
+            end
+          else
+            if ![:created, :identity_defined].include?(resource_state)
+              raise PropertyDefinedError.new("Property #{self.class}.#{name} cannot be reset after the resource is fully defined.", self, property_type)
+            end
+          end
+
+          explicit_property_values.delete(name)
+        else
+          # We only ever reset non-identity values
+          if ![:created, :identity_defined].include?(resource_state)
+            raise ResourceStateError.new("#{self.class} cannot be reset after it is fully defined", self)
+          end
+          explicit_property_values.keep_if { |name,value| self.class.property_types[name].identity? }
+        end
+      end
+
+      #
+      # A hash of the changes the user has made to keys
+      #
+      def explicit_property_values
+        @explicit_property_values ||= {}
+      end
+
+      #
+      # Take an action to update the real resource, as long as the given keys have
+      # actually changed from their real values.  Their real values are obtained
+      # via `load` and `load_value`.
+      #
+      # @param *names [Symbol] A list of property names which must be different
+      #   from their actual / default value in order to set them.  If the last parameter is a String, it
+      #   is treated as the description of the update.
+      # @yield [new_values] a Set containing the list of keys whose values have
+      #   changed.  This block is run in the context of the Resource.  Its
+      #   return value is ignored.
+      # @return the list of changes, or nil if there are no changes
+      #
+      def converge(*names, &update_block)
+        #
+        # Grab the user's description from the last parameter, if it was passed
+        #
+        if names[-1].is_a?(String)
+          *names, description = *names if names[-1].is_a?(String)
+        end
+
+        #
+        # Decide on the header, and fix up the list of names to include all names
+        # if the user didn't pass any names
+        #
+        if names.empty?
+          change_header = ""
+          names = self.class.property_types.keys if names.empty?
+        else
+          change_header = "#{ChefResource.english_list(*names)}"
+        end
+
+        #
+        # Figure out if anything changed
+        #
+        exists = resource_exists?
+        changed_names = names.inject({}) do |h, name|
+          if explicit_property_values.has_key?(name)
+            type = self.class.property_types[name]
+
+            desired_value = public_send(name)
+            if exists
+              current_value = type.current_property_value(self)
+              if desired_value != current_value
+                h[name] = [ type.value_to_s(desired_value), type.value_to_s(current_value) ]
+              end
+            else
+              h[name] = [ type.value_to_s(desired_value), nil ]
+            end
+          end
+          h
+        end
+
+        #
+        # Skip the action if nothing was changed
+        #
+        if exists
+          if changed_names.empty?
+            skip_action "skipping #{change_header}: no values changed"
+            return nil
+          end
+        end
+
+        #
+        # Figure out the printout for what's changing:
+        #
+        # update file[x.txt]
+        #   set abc    to blah
+        #   set abcdef to 12
+        #   set a      to nil
+        #
+        description ||= exists ? "update #{change_header}" : "create #{change_header}"
+        name_width = changed_names.keys.map { |name| name.size }.max
+        description_lines = [ description ] +
+          changed_names.map do |name, (desired, current)|
+            "  set #{name.to_s.ljust(name_width)} to #{desired}#{current ? " (was #{current})" : ""}"
+          end
+
+        #
+        # Actually take the action
+        #
+        take_action(description_lines, &update_block)
+
+        changed_names
+      end
+
+      #
+      # Hash-like interface: to_h, to_hash, as_json, to_json, ==, [], []=
+      #
+
+      #
+      # Returns this struct as a hash, including all properties and their defaults.
+      #
+      # @param only [Symbol] Which values to include. Default: `:only_known`. One of:
+      #   - :only_known :: Values explicitly set by the user or current values.
+      #     If the current value has not been loaded, this will NOT load it or
+      #     show any of those values.
+      #   - :only_changed :: Values which the user has set and which have
+      #     actually changed from their current or default value.
+      #   - :only_explicit :: Values explicitly set by the user.
+      #   - :all :: All values, including default values.
+      #
+      def to_h(only=:only_known)
+        case only
+        when :only_changed
+          result = {}
+          explicit_property_values.each do |name, value|
+            current_property_value = self.class.property_types[name].current_property_value(self)
+            if value != current_property_value
+              result[name] = value
+            end
+          end
+          result
+
+        when :only_explicit
+          explicit_property_values.dup
+
+        when :all
+          result = {}
+          self.class.property_types.each_key do |name|
+            result[name] = public_send(name)
+          end
+          result
+
+        else
+          if current_resource_loaded?
+            current_resource.explicit_property_values.merge(explicit_property_values)
+          else
+            explicit_property_values.dup
+          end
+
+        end
+      end
+
+      #alias :to_hash :to_h
+
+      #
+      # as_json does most of the to_json heavy lifted. It exists here in case activesupport
+      # is loaded. activesupport will call as_json and skip over to_json. This ensure
+      # json is encoded as expected
+      #
+      # @param only_changed Returns only values which have actually changed from
+      #   their current or default value.
+      # @param only_explicit Returns only values which have been explicitly set
+      #   by the user.
+      #
+      def as_json(only_changed: false, only_explicit: false, **options)
+        to_h(only_changed: false, only_explicit: false)
+      end
+
+      #
+      # Serialize this object as a hash
+      #
+      # @param only_changed Returns only values which have actually changed from
+      #   their current or default value.
+      # @param only_explicit Returns only values which have been explicitly set
+      #   by the user.
+      #
+      def to_json(only_changed: false, only_explicit: false, **options)
+        results = as_json(only_changed: only_changed, only_explicit: only_explicit)
+        Chef::JSONCompat.to_json(results, **options)
+      end
+
+      #
+      # Returns true if these are the same type and their values are the same.
+      # Avoids comparing things that aren't modified in either struct.
+      #
+      def ==(other)
+        return false if !other.is_a?(self.class)
+
+        # Try to rule out differences via explicit_property_values first (this should
+        # handle any identity keys and prevent us from accidentally pulling on
+        # current_resource).
+        (explicit_property_values.keys & other.explicit_property_values.keys).each do |name|
+          return false if public_send(name) != other.public_send(name)
+        end
+
+        # If one struct has more desired (set) values than the other, compare
+        # the values to the current/default on the other.
+        (explicit_property_values.keys - other.explicit_property_values.keys).each do |name|
+          return false if public_send(name) != other.public_send(name)
+        end
+        (other.explicit_property_values.keys - explicit_property_values.keys).each do |attr|
+          return false if public_send(name) != other.public_send(name)
+        end
+      end
+
+      #
+      # Get the value of the given property from the struct
+      #
+      def [](name)
+        name = name.to_sym
+        if !property_types.has_key?(name)
+          raise ArgumentError, "#{name} is not a property of #{self.class}."
+        end
+
+        public_send(name)
+      end
+
+      #
+      # Set the value of the given property in the struct
+      #
+      def []=(name, value)
+        public_send(name.to_sym, value)
+      end
+    end
+  end
+end

data/files/lib/chef_resource/resource/struct_resource_base.rb

@@ -0,0 +1,11 @@
+require 'chef_resource/resource/struct_resource'
+require 'chef_resource/resource/struct_resource_type'
+
+module ChefResource
+  module Resource
+    class StructResourceBase
+      include StructResource
+      extend StructResourceType
+    end
+  end
+end

data/files/lib/chef_resource/resource/struct_resource_type.rb

@@ -0,0 +1,275 @@
+require 'chef_resource/errors'
+require 'chef_resource/resource/resource_type'
+require 'chef_resource/constants'
+require 'chef_resource/resource/struct_property_type'
+require 'chef_resource/camel_case'
+require 'chef_resource/simple_struct'
+
+module ChefResource
+  module Resource
+    #
+    # The Type for a StructResource.
+    #
+    module StructResourceType
+      include ResourceType
+
+      #
+      # Coerce the input into a struct of this type.
+      #
+      # Constructor form: required identity parameters first, and then non-required properties in a hash.
+      # - MyStruct.coerce(identity_attr, identity_attr2, ..., { attr1: value, attr2: value, ... }) -> open(identity1, identity2, ... { identity properties }), and set non-identity properties afterwards
+      #
+      # Hash form: a hash with names and values representing struct names and values.
+      # - MyStruct.coerce({ identity_attr: value, attr1: value, attr2: value, ... }) -> open({ identity properties }), and set non-identity properties afterwards
+      #
+      # nil:
+      # - MyStruct.coerce(nil) -> nil
+      #
+      # Resource of this type:
+      # - MyStruct.coerce(x = MyStruct.open) -> x
+      #
+      # Simple constructor form: identity parameters
+      # - MyStruct.coerce(identity_attr) -> open(identity_attr)
+      # - MyStruct.coerce(identity_attr, identity_attr2, ...) -> open(identity_attr, identity_attr2, ...)
+      # - MyStruct.coerce() -> open()
+      #
+      # Struct Form:
+      # - MyStruct.coerce(other_my_struct_instance)
+      #
+      def coerce(parent, *args)
+        if args[-1].is_a?(Hash)
+          #
+          # Constructor form: required identity parameters first, and then non-required properties in a hash.
+          # - MyStruct.coerce(identity_attr, identity_attr2, ..., { attr1: value, attr2: value, ... }) -> open(identity1, identity2, ... { identity properties }), and set non-identity properties afterwards
+          #
+          # Hash form: a hash with names and values representing struct names and values.
+          # - MyStruct.coerce({ identity_attr: value, attr1: value, attr2: value, ... }) -> open({ identity properties }), and set non-identity properties afterwards
+          #
+
+          # Split the identity properties from normal so we can call open() with
+          # just identity properties
+          explicit_property_values = args[-1]
+          identity_values = {}
+          explicit_property_values.each_key do |name|
+            type = property_types[name]
+            raise ValidationError, "#{self.class}.coerce was passed property #{name}, but #{name} is not a property on #{self.class}." if !type
+            identity_values[name] = explicit_property_values.delete(name) if type.identity?
+          end
+
+          # open the resource
+          resource = open(*args[0..-2], identity_values)
+
+          # Set the non-identity properties before returning
+          explicit_property_values.each do |name, value|
+            resource.public_send(name, value)
+          end
+
+          resource.resource_fully_defined
+
+          super(parent, resource)
+
+        elsif args.size == 1 && is_valid?(parent, args[0])
+          # nil:
+          # - MyStruct.coerce(nil) -> nil
+          #
+          # Resource of this type:
+          # - MyStruct.coerce(x = MyStruct.open) -> x
+          super(parent, args[0])
+
+        else
+          # Simple constructor form: identity parameters
+          # - MyStruct.coerce(identity_attr) -> open(identity_attr)
+          # - MyStruct.coerce(identity_attr, identity_attr2, ...) -> open(identity_attr, identity_attr2, ...)
+          # - MyStruct.coerce() -> open()
+          super(parent, open(*args))
+
+        end
+      end
+
+      #
+      # Struct.open() takes the identity properties of the struct and opens it up.
+      # Supports these forms:
+      #
+      # - open(identity1, identity2[, { identity3: value, identity4: value } ])
+      # - open({ identity1: value, identity2: value, identity3: value, identity4: value })
+      # - open() (if no identity properties)
+      #
+      #
+      # @example
+      #   class MyStruct
+      #     include ChefResource::Resource::StructResource
+      #     extend ChefResource::Resource::StructResourceType
+      #     property :x, identity: true
+      #     property :y, identity: true
+      #   end
+      #
+      #   # Allows these statements to work:
+      #   s = MyStruct.open(1, 2)
+      #   puts s.x # 1
+      #   puts s.y # 2
+      #   s = MyStruct.open(x: 3, y: 4)
+      #   puts s.x # 3
+      #   puts s.y # 4
+      #
+      def open(*args, &define_identity_block)
+        resource = new
+        resource.define_identity(*args, &define_identity_block)
+        resource
+      end
+
+      #
+      # Struct definition: MyStruct.property
+      #
+
+      #
+      # Create a property on this struct.
+      #
+      # Makes three method calls available to the struct:
+      # - `struct.name` - Get the value of `name`.
+      # - `struct.name <value...>` - Set `name`.
+      # - `struct.name = <value>` - Set `name`.
+      #
+      # If the property is marked as an identity property, it also modifies
+      # `Struct.open()` to take it as a named parameter.  Multiple identity
+      # property_types means multiple parameters to `open()`.
+      #
+      # @param name [String] The name of the property.
+      # @param type [Class] The type of the property.  If passed, the property
+      #   will use `type.open()`
+      # @param identity [Boolean] `true` if this is an identity
+      #   property.  Default: `false`
+      # @param required [Boolean] `true` if this is a required parameter.
+      #   Defaults to `true`.  Non-identity property_types do not support `required`
+      #   and will ignore it.  Non-required identity property_types will not be
+      #   available as positioned arguments in ResourceClass.open(); they can
+      #   only be specified by name (ResourceClass.open(x: 1))
+      # @param default [Object] The value to return if the user asks for the property
+      #   when it has not been set.  `nil` is a valid value for this.
+      # @param default [Proc] An optional block that will be called when
+      #   the user asks for a value that has not been set.  Called in the
+      #   context of the struct (instance_eval), so you can access other
+      #   properties of the struct to compute the value.  Value is *not* cached,
+      #   but rather is called every time.
+      #
+      # @example Property referencing a resource type by "snake case name"
+      #   class MyResource < StructResourceBase
+      #     property :blah, :my_resource
+      #   end
+      # @example Typeless, optionless property.
+      #   class MyResource < StructResourceBase
+      #     property :simple
+      #   end
+      #   x = MyResource.open
+      #   puts x.simple # nil
+      #   x.simple = 10
+      #   puts x.simple # 10
+      #
+      # @example Property with default
+      #   class MyResource < StructResourceBase
+      #     property :b, default: 10
+      #   end
+      #   x = MyResource.open
+      #   puts x.b # 10
+      #
+      # @example Property with default block
+      #   class MyResource < StructResourceBase
+      #     property :a, default: 3
+      #     property :b do
+      #       a * 2
+      #     end
+      #   end
+      #   x = MyResource.open
+      #   puts x.b # 6
+      #   x.a = 10
+      #   puts x.b # 20
+      #
+      # @example Property with identity
+      #   class MyResource < StructResourceBase
+      #     property :a, identity: true
+      #   end
+      #   x = MyResource.new(10)
+      #   puts x.a # 10
+      #
+      # @example Property with multiple identity
+      #   class MyResource < StructResourceBase
+      #     property :a, identity: true
+      #     property :b, identity: true
+      #   end
+      #   x = MyResource.open(10, 20)
+      #   puts x.a # 10
+      #   puts x.b # 20
+      #   x = MyResource.open(b: 2, a: 1)
+      #   puts x.a # 1
+      #   puts x.b # 2
+      #   x = MyResource.open
+      #   puts x.a # nil
+      #   puts x.b # nil
+      #   x = MyResource.open(1)
+      #   puts x.a # 1
+      #   puts x.b # nil
+      #
+      # @example Property with non-required identity
+      #   class MyResource < StructResourceBase
+      #     property :a, identity: true, required: false
+      #     property :b, identity: true
+      #   end
+      #   x = MyResource.open(1)
+      #   x.a # nil
+      #   x.b # 1
+      #
+      # @example Property with struct typed property
+      #   class Address < StructResourceBase
+      #     property :street
+      #     property :city
+      #     property :state
+      #     property :zip
+      #   end
+      #   class Person < StructResourceBase
+      #     property :name
+      #     property :home_address, Address
+      #   end
+      #   p = Person.open
+      #   p.home_address = Address.open
+      #
+      def property(name, type=nil, identity: nil, default: NOT_PASSED, required: NOT_PASSED, load_value: NOT_PASSED, **type_properties, &override_block)
+        parent = self
+        name = name.to_sym
+        result = self.type(name, type, **type_properties) do
+          extend StructPropertyType
+          self.property_parent_type = parent
+          self.property_name name
+          self.identity identity
+          self.default default unless default == NOT_PASSED
+          self.required required unless required == NOT_PASSED
+          self.load_value load_value unless load_value == NOT_PASSED
+          instance_eval(&override_block) if override_block
+        end
+        property_types[result.property_name] = result
+        result.emit_property_methods
+        result
+      end
+
+      extend SimpleStruct
+
+      #
+      # The property type for each property.
+      #
+      # TODO use real merging in the future.  This carries
+      # danger that someone could modify types on the parent.
+      # But it at least gets us basic inheritance for the
+      # normal case where people are adding new properties
+      # rather than overriding old ones.
+      #
+      property :property_types,
+        default: "@property_types = {}",
+        inherited: "@property_types = superclass.property_types.dup"
+
+      #
+      # The list of identity property types (property types with identity=true), in order.
+      #
+      def identity_property_types
+        property_types.values.select { |attr| attr.identity? }
+      end
+    end
+  end
+end