cloud-templates 0.1.0

data/lib/aws/templates/utils/options.rb

@@ -0,0 +1,279 @@
+require 'set'
+require 'aws/templates/exceptions'
+require 'aws/templates/utils'
+require 'aws/templates/utils/memoized'
+
+module Aws
+  module Templates
+    module Utils
+      # rubocop:disable Metrics/ClassLength
+
+      ##
+      # Options hash-like class
+      #
+      # Implements the core mechanism of hash lookup, merge, and transformation.
+      #
+      # It supports nested hash lookup with index function and wildcard
+      # hash definitions on any level of nested hierarchy so you can define
+      # fallback values right in the input hash. The algorithm will try to
+      # select the best combination if it doesn't see the exact match
+      # during lookup.
+      class Options
+        include Memoized
+
+        ##
+        # Get a parameter from resulting hash or any nested part of it
+        #
+        # The method can access resulting hash as a tree performing
+        # traverse as needed. Also, it handles nil-pointer situations
+        # correctly so you will get no exception but just 'nil' even when
+        # the whole branch you're trying to access don't exist or contains
+        # non-hash value somewhere in the middle. Also, the method
+        # recognizes asterisk (*) hash records which is an analog of
+        # match-all or default values for some sub-branch.
+        #
+        # * +path+ - an array representing path of the value in the nested
+        #            hash
+        #
+        # ==== Example
+        #
+        #    opts = Options.new(
+        #      'a' => {
+        #        'b' => 'c',
+        #        '*' => { '*' => 2 }
+        #      },
+        #      'd' => 1
+        #    )
+        #    opts.to_hash # => { 'a' => { 'b' => 'c', '*' => { '*' => 2 } }, 'd' => 1 }
+        #    opts['a'] # => Options.new('b' => 'c', '*' => { '*' => 2 })
+        #    opts['a', 'b'] # => 'c'
+        #    opts['d', 'e'] # => nil
+        #    # multi-level wildcard match
+        #    opts['a', 'z', 'r'] # => 2
+        def [](*path)
+          @structures.reverse_each.inject(nil) do |memo, container|
+            ret = begin
+              Utils.lookup(container, path.dup)
+            rescue OptionValueDeleted, OptionScalarOnTheWay
+              # we discovered that this layer either have value deleted or parent was overriden
+              # by a scalar. Either way we just return what we have in the memo
+              break memo
+            end
+
+            # if current container doesn't have this value - let's go to the next iteration
+            next memo if ret.nil?
+
+            # if found value is a scalar then either we return it as is or return memo
+            # if memo is not nil it means that we've found hierarchical objects before
+            break(memo.nil? ? ret : memo) unless Utils.recursive?(ret)
+
+            # value is not a scalar. it means we need to keep merging them
+            memo.nil? ? Options.new(ret) : memo.unshift_layer!(ret)
+          end
+        end
+
+        def dependency?
+          !dependencies.empty?
+        end
+
+        def dependencies
+          memoize(:dependencies) do
+            select_recursively(&:dependency?)
+              .inject(Set.new) { |acc, elem| acc.merge(elem.dependencies) }
+          end
+        end
+
+        def select_recursively(&blk)
+          Utils.select_recursively(self, &blk)
+        end
+
+        ##
+        # Set the parameter with the path to the value
+        #
+        # The method can access resulting hash as a tree performing
+        # traverse as needed. When stubled uponAlso, it handles non-existent
+        # keys correctly creating sub-branches as necessary. If a non-hash
+        # and non-nil value discovered in the middle of the path, an exception
+        # will be thrown. The method doesn't give any special meaning
+        # to wildcards keys so you can set wildcard parameters also.
+        #
+        # * +path+ - an array representing path of the value in the nested
+        #            hash
+        # * +value+ - value to set the parameter to
+        #
+        # ==== Example
+        #
+        #    opts = Options.new({})
+        #    opts.to_hash # => {}
+        #    opts['a', 'b'] = 'c'
+        #    opts['a', '*', '*'] = 2
+        #    opts['d'] = 1
+        #    opts.to_hash # => { 'a' => { 'b' => 'c', '*' => { '*' => 2 } }, 'd' => 1 }
+        def []=(*path_and_value)
+          value = path_and_value.pop
+          path = path_and_value
+          dirty!.cow! # mooo
+          Utils.set_recursively(@structures.last, value, path)
+        end
+
+        ##
+        # Delete a branch
+        #
+        # Delete a branch in the options. Rather than deleting it from hash, the path is assigned
+        # with special marker that it was deleted. It helps avoid hash recalculation leading to
+        # memory thrashing simultaneously maintaining semantics close to Hash#delete
+        def delete(*path)
+          self[*path] = DELETED_MARKER
+        end
+
+        ##
+        # Transforms to hash object
+        #
+        # Produces a hash out of Options object merging COW layers iteratively and calculating them
+        # recursively.
+        def to_hash
+          memoize(:to_hash) do
+            _process_hashed(@structures.inject({}) { |acc, elem| Utils.merge(acc, elem) })
+          end
+        end
+
+        ##
+        # Create filter
+        #
+        # Gets hash representstion of the Options instance and transforms it to filter
+        def to_filter
+          to_hash.to_filter
+        end
+
+        ##
+        # Top-level keys
+        #
+        # Produces a list of top-level keys from all layers. Deleted branches are not included.
+        def keys
+          memoize(:keys) do
+            @structures
+              .each_with_object(Set.new) do |container, keyset|
+                container.keys.each do |k|
+                  container[k] == DELETED_MARKER ? keyset.delete(k) : keyset.add(k)
+                end
+              end
+              .to_a
+          end
+        end
+
+        ##
+        # If top-level key exists
+        #
+        # Checks if top-level key exists. Deleted branches are excluded.
+        def include?(k)
+          found = @structures.reverse_each.find { |container| container.include?(k) }
+          !found.nil? && (found[k] != DELETED_MARKER)
+        end
+
+        ##
+        # Merge Options with object
+        #
+        # Create new Options object which is a merge of the target Options instance with an object.
+        # The object must be "recusrsive" meaning it should satisfy minimum contract for
+        # "recursive". See Utils::recursive? for details
+        def merge(other)
+          self.class.new(*@structures, other)
+        end
+
+        ##
+        # Merge Options with object in-place
+        #
+        # Put the passed object as the top layer of the current instance.
+        # The object must be "recursive" meaning it should satisfy minimum contract for
+        # "recursive". See Utils::recursive? for details
+        def merge!(other)
+          raise OptionShouldBeRecursive.new(other) unless Utils.recursive?(other)
+          @structures << other
+          dirty!
+        end
+
+        ##
+        # Filter options
+        #
+        # Filter options with provided Proc. The proc should accept one parameter satisfying
+        # "recursive" contract. See Utils.recursive
+        def filter
+          Options.new(yield self)
+        end
+
+        ##
+        # Initialize Options with list of recursive structures (See Options#recursive?)
+        def initialize(*structures)
+          @structures = structures.map do |container|
+            if Utils.recursive?(container)
+              container
+            elsif Utils.hashable?(container)
+              container.to_hash
+            else
+              raise OptionShouldBeRecursive.new(container)
+            end
+          end
+        end
+
+        ##
+        # Duplicate the options
+        #
+        # Duplicates the object itself and puts another layer of hash map. All original hash maps
+        # are not touched if the duplicate is modified.
+        def dup
+          Options.new(*@structures)
+        end
+
+        ##
+        # Squash all layers into one
+        #
+        # Options is designed with very specific goal to be memory-friendly and re-use merged
+        # objects as immutable layers. However, after some particular threshold of layer's stack
+        # size, performance of index operations can suffer significantly. To mitigate this user can
+        # use the method to squash all layers into one aggregated hash.
+        #
+        # The method performs in-place stack modification
+        def compact!
+          @structures = [to_hash]
+          self
+        end
+
+        ##
+        # Put the layer to the bottom of the stack
+        #
+        # However it doesn't resemble exact semantics, the method is similar to reverse_merge!
+        # from ActiveSupport. It puts the "recursive" object passed to the bottom of the layer
+        # stack of the Options instance effectively making it the least prioritized layer.
+        def unshift_layer!(layer)
+          raise OptionShouldBeRecursive.new(layer) unless Utils.recursive?(layer)
+          @structures.unshift(layer)
+          dirty!
+        end
+
+        def cow!
+          unless @is_cowed
+            @structures << {}
+            @is_cowed = true
+          end
+
+          self
+        end
+
+        private
+
+        # :nodoc: process hashable recursively removing all keys marked as deleted
+        def _process_hashed(hashed)
+          hashed.each_pair do |key, value|
+            if value == DELETED_MARKER
+              hashed.delete(key)
+            elsif Utils.hashable?(value)
+              _process_hashed(value.to_hash).freeze
+            end
+          end
+
+          hashed
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/parametrized/constraints.rb

@@ -0,0 +1,423 @@
+require 'aws/templates/exceptions'
+require 'aws/templates/utils/parametrized'
+require 'set'
+require 'singleton'
+
+module Aws
+  module Templates
+    module Utils
+      module Parametrized #:nodoc:
+        ##
+        # Constraint functor class
+        #
+        # A constraint is a Proc which accepts one parameter which is a value
+        # which needs to be checked and ir is expected to throw an exception
+        # if the value is not in compliance with the constraint
+        #
+        # The class implements functor pattern through to_proc method and
+        # closure. Essentially, all constraints can be used everywhere where
+        # a block is expected.
+        #
+        # It provides protected method check which should be overriden in
+        # all concrete constraint classes.
+        class Constraint
+          ##
+          # Check if passed value is not nil
+          #
+          # === Example
+          #
+          #    class Piece
+          #      include Aws::Templates::Utils::Parametrized
+          #
+          #      parameter :param1, :constraint => not_nil
+          #    end
+          #
+          #    i = Piece.new(:param1 => 3)
+          #    i.param1 # => 3
+          #    i = Piece.new
+          #    i.param1 # throws ParameterValueInvalid
+          class NotNil < Constraint
+            include Singleton
+
+            protected
+
+            def check(_, value, _)
+              raise('required but was not found in input hash') if value.nil?
+            end
+          end
+
+          ##
+          # Check if passed value is in the enumeration values.
+          #
+          # === Example
+          #
+          #    class Piece
+          #      include Aws::Templates::Utils::Parametrized
+          #
+          #      parameter :param1, :constraint => enum([1,'2',3])
+          #    end
+          #
+          #    i = Piece.new(:param1 => 3)
+          #    i.param1 # => 3
+          #    i = Piece.new(:param1 => 4)
+          #    i.param1 # throws ParameterValueInvalid
+          class Enum < Constraint
+            attr_reader :set
+
+            def initialize(list)
+              @set = Set.new(list)
+            end
+
+            protected
+
+            def check(_, value, _)
+              return if value.nil? || set.include?(value)
+
+              raise(
+                "Value #{value.inspect} is not in the set of allowed " \
+                "values #{set.inspect}"
+              )
+            end
+          end
+
+          ##
+          # Switch-like variant check
+          #
+          # Recursive check implementing switch-based semantics for defining
+          # checks need to be performed depending on parameter's value.
+          #
+          # === Example
+          #
+          #    class Piece
+          #      include Aws::Templates::Utils::Parametrized
+          #      parameter :param2
+          #      parameter :param1,
+          #        :constraint => depends_on_value(
+          #          1 => lambda { |v| raise 'Too big' if param2 > 3 },
+          #          2 => lambda { |v| raise 'Too small' if param2 < 2 }
+          #        )
+          #    end
+          #
+          #    i = Piece.new(:param1 => 1, :param2 => 1)
+          #    i.param1 # => 1
+          #    i = Piece.new(:param1 => 1, :param2 => 5)
+          #    i.param1 # raise ParameterValueInvalid
+          #    i = Piece.new(:param1 => 2, :param2 => 1)
+          #    i.param1 # raise ParameterValueInvalid
+          #    i = Piece.new(:param1 => 2, :param2 => 5)
+          #    i.param1 # => 2
+          class DependsOnValue < Constraint
+            ##
+            # Selector hash
+            attr_reader :selector
+
+            def initialize(selector)
+              @selector = selector
+            end
+
+            protected
+
+            def check(parameter, value, instance)
+              return unless selector.key?(value)
+
+              instance.instance_exec(
+                parameter,
+                value,
+                &selector[value]
+              )
+            end
+          end
+
+          ##
+          # Check presence of parameters if the condition is met
+          #
+          # Requires presence of the methods passed as dependencies in the
+          # current scope with non-nil returning values. Default condition
+          # for the value is not to be nil. The condition can be either
+          # a block or a value.
+          #
+          # === Example
+          #
+          #    class Piece
+          #      include Aws::Templates::Utils::Parametrized
+          #      parameter :param2
+          #      parameter :param1, :constraint => requires(:param2)
+          #    end
+          #
+          #    i = Piece.new(:param2 => 1)
+          #    i.param1 # => nil
+          #    i = Piece.new(:param1 => 1)
+          #    i.param1 # raise ParameterValueInvalid
+          #    i = Piece.new(:param1 => 2, :param2 => 1)
+          #    i.param1 # => 2
+          class Requires < Constraint
+            attr_reader :dependencies
+            attr_reader :condition
+
+            def initialize(dependencies)
+              @dependencies = dependencies
+              @condition = method(:not_nil?)
+            end
+
+            def if(*params, &blk)
+              if params.empty?
+                @condition = blk
+              else
+                test = params.first
+                @condition = ->(v) { v == test }
+              end
+
+              self
+            end
+
+            protected
+
+            def not_nil?(value)
+              !value.nil?
+            end
+
+            def check(parameter, value, instance)
+              return unless instance.instance_exec(value, &condition)
+
+              dependencies.each do |pname|
+                next unless instance.send(pname).nil?
+
+                raise(
+                  "#{pname} is required when #{parameter.name} value " \
+                  "is set to #{value.inspect}"
+                )
+              end
+            end
+          end
+
+          ##
+          # Check if value satisfies the condition
+          #
+          # Checks if value satisfies the condition defined in the block
+          # which should return true if the condition is met and false if it's
+          # not. If value fails the check, an exception will be thrown
+          # with attached condition description. The description is a part
+          # of constraint definition.
+          #
+          # The block is evaluated in the functor's invocation context.
+          #
+          # === Example
+          #
+          #    class Piece
+          #      include Aws::Templates::Utils::Parametrized
+          #      parameter :param1,
+          #        :constraint => satisfies('Mediocre value') { |v| v < 100 }
+          #    end
+          #
+          #    i = Piece.new(:param2 => 1)
+          #    i.param1 # => 1
+          #    i = Piece.new(:param1 => 101)
+          #    i.param1 # raise ParameterValueInvalid
+          class SatisfiesCondition < Constraint
+            attr_reader :condition
+            attr_reader :description
+
+            def initialize(description, &cond_block)
+              @condition = cond_block
+              @description = description
+            end
+
+            protected
+
+            def check(parameter, value, instance)
+              return if value.nil? || instance.instance_exec(value, &condition)
+
+              raise(
+                "#{value.inspect} doesn't satisfy the condition " \
+                "#{description} for parameter #{parameter.name}"
+              )
+            end
+          end
+
+          ##
+          # Check if value matches the regular expression
+          #
+          # Checks if value matches the regular expression. If value doesn't match, an exception
+          # will be thrown with attached description of regular expression and value converted to
+          # string.
+          #
+          # === Example
+          #
+          #    class Piece
+          #      include Aws::Templates::Utils::Parametrized
+          #      parameter :param1, constraint: matches('A+')
+          #    end
+          #
+          #    i = Piece.new(:param1 => 'Ask')
+          #    i.param1 # => 'Ask'
+          #    i = Piece.new(:param1 => 'Bar')
+          #    i.param1 # raise ParameterValueInvalid
+          class Matches < Constraint
+            attr_reader :expression
+
+            def initialize(rex)
+              @expression = Regexp.new(rex)
+            end
+
+            protected
+
+            def check(parameter, value, _)
+              return if value.nil? || (expression =~ value.to_s)
+              raise "#{value} doesn't match #{expression} for parameter #{parameter.name}"
+            end
+          end
+
+          ##
+          # Aggregate constraint
+          #
+          # It is used to perform checks against a list of constraints-functors
+          # or lambdas.
+          #
+          # === Example
+          #
+          #    class Piece
+          #      include Aws::Templates::Utils::Parametrized
+          #      parameter :param1,
+          #        :constraint => all_of(
+          #          not_nil,
+          #          satisfies("Should be moderate") { |v| v < 100 }
+          #        )
+          #    end
+          #
+          #    i = Piece.new(:param1 => nil)
+          #    i.param1 # raise ParameterValueInvalid
+          #    i = Piece.new(:param1 => 200)
+          #    i.param1 # raise ParameterValueInvalid with description
+          #    i = Piece.new(:param1 => 50)
+          #    i.param1 # => 50
+          class AllOf < Constraint
+            attr_reader :constraints
+
+            def initialize(constraints)
+              @constraints = constraints
+            end
+
+            protected
+
+            def check(parameter, value, instance)
+              constraints.each do |c|
+                instance.instance_exec(parameter, value, &c)
+              end
+            end
+          end
+
+          ##
+          # Creates closure with checker invocation
+          #
+          # It's an interface method required for Constraint to expose
+          # functor properties. It encloses invocation of Constraint check_wrapper
+          # method into a closure. The closure itself is executed in the context
+          # of Parametrized instance which provides proper set "self" variable.
+          #
+          # The closure itself accepts 2 parameters:
+          # * +parameter+ - the Parameter object which the constraint is evaluated
+          #                 against
+          # * +value+ - parameter value to be checked
+          # ...where instance is assumed from self
+          def to_proc
+            constraint = self
+
+            lambda do |parameter, value|
+              constraint.check_wrapper(parameter, value, self)
+            end
+          end
+
+          ##
+          # Wraps constraint-dependent method
+          #
+          # It wraps constraint-dependent "check" method into a rescue block
+          # to standardize exception type and information provided by failed
+          # constraint validation
+          # * +parameter+ - the Parameter object which the constraint is evaluated
+          #                 against
+          # * +value+ - parameter value to be checked
+          # * +instance+ - the instance value is checked for
+          def check_wrapper(parameter, value, instance)
+            check(parameter, value, instance)
+          rescue StandardError
+            raise ParameterValueInvalid.new(parameter, instance, value)
+          end
+
+          protected
+
+          ##
+          # Constraint-dependent check
+          #
+          # * +parameter+ - the Parameter object which the constraint is evaluated
+          #                 against
+          # * +value+ - parameter value to be checked
+          # * +instance+ - the instance value is checked for
+          def check(parameter, value, instance); end
+        end
+
+        ##
+        # Syntax sugar for constraints definition
+        #
+        # It injects the methods as class-scope methods into mixing classes.
+        # The methods are factories to create particular type of constraint
+        class_scope do
+          ##
+          # Parameter shouldn't be nil
+          #
+          # alias for NotNil class
+          def not_nil
+            Constraint::NotNil.instance
+          end
+
+          ##
+          # Parameter value should be in enumeration
+          #
+          # alias for Enum class
+          def enum(*items)
+            Constraint::Enum.new(items.flatten)
+          end
+
+          ##
+          # Parameter value should satisfy all specified constraints
+          #
+          # alias for AllOf class
+          def all_of(*constraints)
+            Constraint::AllOf.new(constraints)
+          end
+
+          ##
+          # Requires presence of the parameters if condition is satisfied
+          #
+          # alias for Requires class
+          def requires(*dependencies)
+            Constraint::Requires.new(dependencies)
+          end
+
+          ##
+          # Constraint depends on value
+          #
+          # alias for DependsOnValue class
+          def depends_on_value(selector)
+            Constraint::DependsOnValue.new(selector)
+          end
+
+          ##
+          # Constraint should satisfy the condition
+          #
+          # alias for SatisfiesCondition class
+          def satisfies(description, &cond_block)
+            Constraint::SatisfiesCondition.new(description, &cond_block)
+          end
+
+          ##
+          # Value should match the regular experession
+          #
+          # alias for Matches
+          def matches(rex)
+            Constraint::Matches.new(rex)
+          end
+        end
+      end
+    end
+  end
+end