cloud-templates 0.2.0 → 0.3.0

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

@@ -1,9 +1,4 @@
-require 'aws/templates/exceptions'
-require 'aws/templates/utils/parametrized/guarded'
-require 'aws/templates/utils/inheritable'
-require 'aws/templates/utils/dependent'
-require 'aws/templates/utils/inspectable'
-require 'set'
+require 'aws/templates/utils'
 
 module Aws
   module Templates
@@ -16,10 +11,13 @@ module Aws
       # value extraction, constraints checking and transformation. Essentially,
       # it's domain-specific extended implementation of attr_reader.
       module Parametrized
-        include Guarded
-        include Dependent
-        include Inheritable
-        include Inspectable
+        include Utils::Guarded
+        include Utils::Dependent
+        include Utils::Inheritable
+        include Utils::Inspectable
+        include Getter::Dsl
+        include Constraint::Dsl
+        include Transformation::Dsl
 
         ##
         # Parameter object
@@ -97,7 +95,12 @@ module Aws
           private
 
           def extract_value(instance)
-            raise ParameterGetterIsNotDefined.new(self) unless getter(instance)
+            unless getter(instance)
+              raise(
+                Templates::Exception::ParameterGetterIsNotDefined.new(self)
+              )
+            end
+
             execute_getter(instance, getter(instance))
           end
 
@@ -111,7 +114,7 @@ module Aws
             end
           end
 
-          ALLOWED_SPECIFICATION_ENTRIES = Set.new %i[description getter transform constraint]
+          ALLOWED_SPECIFICATION_ENTRIES = ::Set.new %i[description getter transform constraint]
 
           def set_specification(enclosing_class, specification) # :nodoc:
             @klass = enclosing_class
@@ -126,7 +129,7 @@ module Aws
           end
 
           def raise_wrong_options(wrong_options)
-            raise ParameterSpecificationIsInvalid.new(self, wrong_options)
+            raise Templates::Exception::ParameterSpecificationIsInvalid.new(self, wrong_options)
           end
 
           def process_specification(spec)
@@ -170,11 +173,15 @@ module Aws
         end
 
         instance_scope do
+          def guarded_get(instance, parameter_object)
+            guarded_for(instance, parameter_object) { parameter_object.get(self) }
+          end
+
           ##
           # Lazy initializer
           def dependencies
             if @dependencies.nil?
-              @dependencies = Set.new
+              @dependencies = ::Set.new
               depends_on(parameter_names.map { |name| send(name) })
             end
 
@@ -225,11 +232,9 @@ module Aws
           # The list includes both the class parameters and all ancestor
           # parameters.
           def list_all_parameter_names
-            ancestors
-              .select { |mod| mod.include?(Parametrized) }
-              .inject(Set.new) do |parameter_collection, mod|
-                parameter_collection.merge(mod.parameters.keys)
-              end
+            ancestors_with(Parametrized).inject(::Set.new) do |parameter_collection, mod|
+              parameter_collection.merge(mod.parameters.keys)
+            end
           end
 
           ##
@@ -248,10 +253,8 @@ module Aws
           # inheritance hierarchy.
           # * +parameter_alias+ - parameter name
           def get_parameter(parameter_alias)
-            ancestor =
-              ancestors
-              .select { |mod| mod.include?(Parametrized) }
-              .find { |mod| mod.parameters.key?(parameter_alias) }
+            ancestor = ancestors_with(Parametrized)
+                       .find { |mod| mod.parameters.key?(parameter_alias) }
 
             ancestor.parameters[parameter_alias] if ancestor
           end
@@ -277,9 +280,13 @@ module Aws
           def raise_already_exists(name)
             parameter_object = get_parameter(name)
 
-            raise(ParameterAlreadyExist.new(parameter_object)) if parameter_object
+            if parameter_object
+              raise(
+                Templates::Exception::ParameterAlreadyExist.new(parameter_object)
+              )
+            end
 
-            raise ParameterMethodNameConflict.new(instance_method(name))
+            raise Aws::Templates::Exception::ParameterMethodNameConflict.new(instance_method(name))
           end
         end
       end

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

@@ -0,0 +1,95 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Utils
+      module Parametrized
+        ##
+        # 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
+          ##
+          # 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) if pre_condition.check(value, instance)
+          rescue StandardError
+            raise Templates::Exception::ParameterValueInvalid.new(parameter, instance, value)
+          end
+
+          ##
+          # Change precondition of the constraint
+          #
+          # Pre-condition is a modifier to the main constraint. The constraint won't be evaluated
+          # if pre-condition is not met. Default condition is that value should be not nil meaning
+          # that if the value is nil then the constraint will be ignored.
+          def if(*params, &blk)
+            @pre_condition = Condition.for(
+              if params.empty?
+                raise 'Block must be specified' unless block_given?
+                blk
+              else
+                params.first
+              end
+            )
+
+            self
+          end
+
+          def pre_condition
+            @pre_condition ||= Condition.not_nil
+          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
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/parametrized/constraint/all_of.rb

@@ -0,0 +1,51 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Utils
+      module Parametrized
+        class Constraint
+          ##
+          # 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 < self
+            attr_reader :constraints
+
+            def initialize(constraints)
+              @constraints = constraints
+              self.if(Parametrized.any)
+            end
+
+            protected
+
+            def check(parameter, value, instance)
+              constraints.each do |c|
+                instance.instance_exec(parameter, value, &c)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/parametrized/constraint/condition.rb

@@ -0,0 +1,93 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Utils
+      module Parametrized
+        class Constraint
+          ##
+          # Condition
+          #
+          # Condition is a strategy which decides if some particular constraint should be enforced
+          # or not.
+          class Condition
+            ##
+            # Enforce constraint in all cases
+            class Unconditional < Condition
+              def check(_, _)
+                true
+              end
+            end
+
+            ##
+            # Do not evaluate constraint if value is nil
+            class NotNil < Condition
+              def check(value, _)
+                !value.nil?
+              end
+            end
+
+            ##
+            # If value is equal to the condition then evaluate constraint
+            class Equal < Condition
+              attr_reader :expected
+
+              def initialize(expected)
+                @expected = expected
+              end
+
+              def check(value, _)
+                value == expected
+              end
+            end
+
+            ##
+            # Check specified lambda if constraint should be evaluated
+            class Conditional < Condition
+              attr_reader :condition
+
+              def initialize(condition)
+                @condition = condition
+              end
+
+              def check(value, instance)
+                instance.instance_exec(value, &condition)
+              end
+            end
+
+            def check(_value, _instance)
+              raise 'Must be overriden'
+            end
+
+            ##
+            # Factory method for Unconditional singleton
+            def self.any
+              @unconditional ||= Unconditional.new
+            end
+
+            ##
+            # Factory method for NotNil singleton
+            def self.not_nil
+              @not_nil ||= NotNil.new
+            end
+
+            ##
+            # Factory method transforming arbitrary object into Condition object depending
+            # on object's concept.
+            def self.for(condition)
+              if condition.is_a?(self)
+                condition
+              elsif condition.respond_to?(:to_sym)
+                Equal.new(condition)
+              elsif condition.respond_to?(:to_proc)
+                Conditional.new(condition)
+              else
+                Equal.new(condition)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/parametrized/constraint/depends_on_value.rb

@@ -0,0 +1,60 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Utils
+      module Parametrized
+        class Constraint
+          ##
+          # 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 < self
+            ##
+            # Selector hash
+            attr_reader :selector
+
+            def initialize(selector)
+              @selector = selector
+              self.if(Parametrized.any)
+            end
+
+            protected
+
+            def check(parameter, value, instance)
+              return unless selector.key?(value)
+
+              instance.instance_exec(
+                parameter,
+                value,
+                &selector[value]
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/parametrized/constraint/dsl.rb

@@ -0,0 +1,86 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Utils
+      module Parametrized
+        class Constraint
+          ##
+          # 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
+          module Dsl
+            include Utils::Inheritable
+
+            class_scope do
+              ##
+              # Match-all precondition
+              #
+              # Any constraint with this precondition will process any value
+              def any
+                Constraint::Condition.any
+              end
+
+              ##
+              # Parameter shouldn't be nil
+              #
+              # alias for NotNil class
+              def not_nil
+                Parametrized::Constraint::NotNil.new
+              end
+
+              ##
+              # Parameter value should be in enumeration
+              #
+              # alias for Enum class
+              def enum(*items)
+                Parametrized::Constraint::Enum.new(items.flatten)
+              end
+
+              ##
+              # Parameter value should satisfy all specified constraints
+              #
+              # alias for AllOf class
+              def all_of(*constraints)
+                Parametrized::Constraint::AllOf.new(constraints)
+              end
+
+              ##
+              # Requires presence of the parameters if condition is satisfied
+              #
+              # alias for Requires class
+              def requires(*dependencies)
+                Parametrized::Constraint::Requires.new(dependencies)
+              end
+
+              ##
+              # Constraint depends on value
+              #
+              # alias for DependsOnValue class
+              def depends_on_value(selector)
+                Parametrized::Constraint::DependsOnValue.new(selector)
+              end
+
+              ##
+              # Constraint should satisfy the condition
+              #
+              # alias for SatisfiesCondition class
+              def satisfies(description, &cond_block)
+                Parametrized::Constraint::SatisfiesCondition.new(description, &cond_block)
+              end
+
+              ##
+              # Value should match the regular experession
+              #
+              # alias for Matches
+              def matches(rex)
+                Parametrized::Constraint::Matches.new(rex)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end