cloud-templates 0.1.0

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

@@ -0,0 +1,240 @@
+require 'aws/templates/exceptions'
+require 'aws/templates/utils/parametrized/guarded'
+require 'aws/templates/utils/inheritable'
+require 'aws/templates/utils/dependent'
+require 'set'
+
+module Aws
+  module Templates
+    module Utils
+      ##
+      # 'parameter' DSL to specify artifact parameters checks
+      #
+      # The module provides the basic class-level methods to define
+      # so-called parameters. A parameter is a reader-like method of
+      # value extraction, constraints checking and transformation. Essentially,
+      # it's domain-specific extended implementation of attr_reader.
+      module Parametrized
+        include Guarded
+        include Inheritable
+        include Dependent
+
+        ##
+        # Parameter object
+        #
+        # The object incorporates parameter specification and basic logic for
+        # value extraction, checking and transformation.  Parameter objects
+        # are created at each parameter description.
+        class Parameter
+          attr_reader :name
+          attr_accessor :description
+
+          def getter(instance = nil)
+            @getter || (
+              instance &&
+              (
+                (instance.respond_to?(:getter) && instance.getter) ||
+                (instance.class.respond_to?(:getter) && instance.class.getter)
+              )
+            )
+          end
+
+          attr_accessor :transform
+          attr_accessor :constraint
+          attr_accessor :klass
+
+          ##
+          # Create a parameter object with given specification
+          #
+          # * +name+ - parameter name
+          # * +enclosing_class+ - the class the parameter was declared at
+          # * +specification+ - parameter specification; it includes:
+          # ** +:description+ - human-readable parameter description
+          # ** +:getter+ - getter Proc which will be used for parameter extraction
+          #                from input hash or plain value. The Proc shouldn't
+          #                expect any arguments and it will be executed in
+          #                the instance context. If a plain value is passed
+          #                it will be used as is. If the argument is not specified
+          #                then value will be extracted from the input hash by
+          #                the parameter name (see Getter for more information)
+          # ** +:transform+ - transform Proc which will be used for transforming
+          #                   extracted value. It should expect single parameter
+          #                   and it will be executed in instance context.
+          #                   if not specified not transformation will be
+          #                   performed (see Transformation for more information)
+          # ** +:constraint+ - constraint Proc which will be used to check
+          #                    the value after transformation step. The Proc
+          #                    is expected to receive one arg and throw an
+          #                    exception if constraints are not met
+          #                    (see Constraint for more information)
+          def initialize(name, enclosing_class, specification = {})
+            @name = name
+            set_specification(enclosing_class, specification)
+          end
+
+          ##
+          # Get the parameter value from the instance
+          #
+          # It is used internally in auto-generated accessors to get the value
+          # from input hash. The method extracts value from the hash and
+          # pushes it through transformation and constraint stages. Also,
+          # you can specify value as the optional parameter so getter even
+          # if present will be ignored. It relies on presence of options
+          # accessor in the instance.
+          # * +instance+ - instance to extract the parameter value from
+          def get(instance)
+            process_value(instance, extract_value(instance))
+          end
+
+          def process_value(instance, value)
+            value = instance.instance_exec(self, value, &transform) if transform
+            instance.instance_exec(self, value, &constraint) if constraint
+            value
+          end
+
+          private
+
+          def extract_value(instance)
+            raise ParameterGetterIsNotDefined.new(self) unless getter(instance)
+            execute_getter(instance, getter(instance))
+          end
+
+          def execute_getter(instance, getter)
+            if getter.respond_to?(:to_hash)
+              getter
+            elsif getter.respond_to?(:to_proc)
+              instance.instance_exec(self, &getter)
+            else
+              getter
+            end
+          end
+
+          ALLOWED_SPECIFICATION_ENTRIES = Set.new %i[description getter transform constraint]
+
+          def set_specification(enclosing_class, specification) # :nodoc:
+            @klass = enclosing_class
+
+            wrong_options = specification.keys.reject do |option_name|
+              ALLOWED_SPECIFICATION_ENTRIES.include?(option_name)
+            end
+
+            raise_wrong_options(wrong_options) unless wrong_options.empty?
+
+            process_specification(specification)
+          end
+
+          def raise_wrong_options(wrong_options)
+            raise ParameterSpecificationIsInvalid.new(self, wrong_options)
+          end
+
+          def process_specification(spec)
+            @description = spec[:description] if spec.key?(:description)
+            @getter = spec[:getter] if spec.key?(:getter)
+            @transform = spec[:transform] if spec.key?(:transform)
+            @constraint = spec[:constraint] if spec.key?(:constraint)
+          end
+        end
+
+        instance_scope do
+          ##
+          # Lazy initializer
+          def dependencies
+            if @dependencies.nil?
+              @dependencies = Set.new
+              depends_on(parameter_names.map { |name| send(name) })
+            end
+
+            @dependencies
+          end
+
+          ##
+          # Parameter names list
+          #
+          # Instance-level alias for list_all_parameter_names
+          def parameter_names
+            self.class.list_all_parameter_names
+          end
+
+          ##
+          # Validate all parameters
+          #
+          # Performs calculation of all specified parameters to check options validity
+          def validate
+            parameter_names.each { |name| send(name) }
+          end
+
+          attr_reader :getter
+        end
+
+        ##
+        # Class-level mixins
+        #
+        # It's a DSL extension to declaratively define parameters.
+        class_scope do
+          ##
+          # List all defined parameter names
+          #
+          # 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
+          end
+
+          ##
+          # Parameters defined in the class
+          #
+          # Returns map from parameter name to parameter object of the parameters
+          # defined only in the class.
+          def parameters
+            @parameters ||= {}
+          end
+
+          ##
+          # Get parameter object by name
+          #
+          # Look-up by the parameter object name recursively through class
+          # 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.parameters[parameter_alias] if ancestor
+          end
+
+          ##
+          # Class-level parameter declaration method
+          #
+          # Being a part of parameter declaration DSL, it constructs
+          # parameter object, stores it in parameters class level registry
+          # and creates a reader method for it. It will throw exception
+          # if the parameter name is already occupied by a method or a parameter
+          # with the name already exists in the class or any ancestor
+          # * +parameter_alias+ - parameter name
+          # * +specification+ - parameter specification hash
+          def parameter(name, spec = {})
+            raise_already_exists(name) if method_defined?(name)
+
+            parameter_object = Parameter.new(name, self, spec)
+            parameters[name] = parameter_object
+            define_method(name) { guarded_get(self, parameter_object) }
+          end
+
+          def raise_already_exists(name)
+            parameter_object = get_parameter(name)
+
+            raise(ParameterAlreadyExist.new(parameter_object)) if parameter_object
+
+            raise ParameterMethodNameConflict.new(instance_method(name))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/utils.rb

@@ -0,0 +1,219 @@
+require 'aws/templates/exceptions'
+
+module Aws
+  module Templates
+    ##
+    # Variable utility functions used through the code
+    module Utils
+      RECURSIVE_METHODS = %i[keys [] include?].freeze
+
+      ##
+      # If the object is "recursive"
+      #
+      # Checks if object satisfies "recursive" concept. See RECURSIVE_METHODS for the list
+      # of methods
+      def self.recursive?(obj)
+        RECURSIVE_METHODS.all? { |m| obj.respond_to?(m) }
+      end
+
+      ##
+      # If the object is "scalar"
+      #
+      # Checks if object satisfies "scalar" concept.
+      def self.scalar?(obj)
+        !obj.respond_to?(:[])
+      end
+
+      ##
+      # If object is hashable
+      #
+      # Checks if object can be transformed into Hash
+      def self.hashable?(obj)
+        obj.respond_to?(:to_hash)
+      end
+
+      PARAMETRIZED_METHODS = [:parameter_names].freeze
+
+      ##
+      # If the object is "parametrized"
+      #
+      # Checks if object satisfies "parametrized" concept. See PARAMETRIZED_METHODS for the list
+      # of methods
+      def self.parametrized?(obj)
+        PARAMETRIZED_METHODS.all? { |m| obj.respond_to?(m) }
+      end
+
+      ##
+      # If object is a list
+      #
+      # Checks if object can be transformed into Array
+      def self.list?(obj)
+        obj.respond_to?(:to_ary)
+      end
+
+      ##
+      # Duplicate hash recursively
+      #
+      # Duplicate the hash and all nested hashes recursively
+      def self.deep_dup(original)
+        return original unless Utils.hashable?(original)
+
+        duplicate = original.dup.to_hash
+        duplicate.each_pair { |k, v| duplicate[k] = deep_dup(v) }
+
+        duplicate
+      end
+
+      ##
+      # Merges two nested hashes
+      #
+      # The core element of the whole framework. The principle is simple:
+      # both arguments are transformed to hashes if they support :to_hash
+      # method, the resulting hashes are merged with the standard method
+      # with creating a new hash. Second element takes preference if the
+      # function reached bottom level of recursion with only scalars left.
+      #
+      # Raises ArgumentError if a and b have incompatible types hence
+      # they can't be merged
+      #
+      # ==== Example
+      #
+      #    Options.merge('a', 'b') # => 'b'
+      #    Options.merge({'1'=>'2'}, {'3'=>'4'}) # => {'1'=>'2', '3'=>'4'}
+      #    Options.merge(
+      #      { '1' => { '2' => '3' } },
+      #      { '1' => { '4' => '5' } }
+      #    ) # => { '1' => { '2' => '3', '4'=>'5' } }
+      ##
+      # Recursively merge two "recursive" objects
+      # PS: Yes I know that there is "merge" method for *hashes*.
+      def self.merge(a, b)
+        return hashify(b) unless Utils.recursive?(a) && Utils.recursive?(b)
+        _merge_back(_merge_forward(a, b), b)
+      end
+
+      def self._merge_forward(a, b)
+        a.keys.each_with_object({}) do |k, hsh|
+          hsh[k] = b[k].nil? ? hashify(a[k]) : merge(a[k], b[k])
+        end
+      end
+
+      def self._merge_back(result, b)
+        b.keys.reject { |k| result.include?(k) }.each_with_object(result) { |k, res| res[k] = b[k] }
+      end
+
+      def self.hashify(v)
+        return v unless Utils.recursive?(v)
+        v.keys.each_with_object({}) { |k, hsh| hsh[k] = hashify(v[k]) }
+      end
+
+      ##
+      # Deletion marker
+      #
+      # Since Options use lazy merging (effectively keeping all hashes passed during
+      # initialization immutable) and iterates through all of them during value look-up, we need
+      # a way of marking some branch as deleted when deletion operation is invoked on an Options
+      # object. So, the algorithm marks branch with the object to stop iteration during look-up.
+      DELETED_MARKER = Object.new
+
+      ##
+      # 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 self.lookup(value, path)
+        # we stop lookup and return nil if nil is encountered
+        return if value.nil?
+        # value was deleted in this layer
+        raise OptionValueDeleted.new(path) if value == DELETED_MARKER
+        # we reached our target! returning it
+        return value if path.nil? || path.empty?
+        # we still have some part of path to traverse but scalar was found
+        raise OptionScalarOnTheWay.new(value, path) if Utils.scalar?(value)
+
+        _lookup_recursively(value, path.dup)
+      end
+
+      def self._lookup_recursively(value, path)
+        current_key = path.shift
+
+        # is there a value defined for the key in the current recursive structure?
+        if value.include?(current_key)
+          # yes - look-up the rest of the path
+          return_value = lookup(value[current_key], path)
+          # if value was still not found - resorting to wildcard path
+          return_value.nil? ? lookup(value[:*], path) : return_value
+        elsif value.include?(:*)
+          # if there is no key but the recursive has a default value defined - dive into the
+          # wildcard branch
+          lookup(value[:*], path)
+        end
+      end
+
+      ##
+      # Sets a value in hierarchy
+      #
+      # Sets a path in a nested recursive hash structure to the specified value
+      #
+      # * +container+ - container with the specified path
+      # * +value+ - the value to set the path to
+      # * +path+ - path containing the target value
+      def self.set_recursively(container, value, path)
+        last_key = path.pop
+
+        last_branch = path.inject(container) do |obj, current_key|
+          raise OptionScalarOnTheWay.new(obj, path) unless Utils.recursive?(obj)
+          if obj.include?(current_key)
+            obj[current_key]
+          else
+            obj[current_key] = {}
+          end
+        end
+
+        last_branch[last_key] = value
+      end
+
+      ##
+      # Select object recursively
+      #
+      # Selects objects recursively from the specified container with specified block predicate.
+      #
+      # * +container+ - container to recursively select items from
+      # * +blk+ - the predicate
+      def self.select_recursively(container, &blk)
+        container.keys.each_with_object([]) do |k, collection|
+          value = container[k]
+          if blk.call(value)
+            collection << value
+          elsif Utils.recursive?(value)
+            collection.concat(select_recursively(value, &blk))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates.rb

@@ -0,0 +1,16 @@
+require 'aws/templates/artifact'
+require 'aws/templates/composite'
+require 'aws/templates/render'
+require 'aws/templates/utils/named'
+require 'aws/templates/utils/parametrized/constraints'
+require 'aws/templates/utils/parametrized/transformations'
+require 'aws/templates/utils/parametrized/getters'
+
+##
+# :main: README.md
+module Aws
+  ##
+  # Main namespace for the library-related functionality
+  module Templates
+  end
+end

data/spec/aws/templates/artifact_spec.rb

@@ -0,0 +1,161 @@
+require 'spec_helper'
+require 'aws/templates/artifact'
+
+module TestTest
+  module A; end
+  module B; end
+end
+
+describe Aws::Templates::Artifact do
+  let(:artifact_class) do
+    Class.new(Aws::Templates::Artifact) do
+      default a: 'b',
+              b: proc { options[:c].upcase }
+
+      parameter :c
+      parameter :d
+    end
+  end
+
+  let(:dependency) do
+    Struct.new(:"dependency?", :dependencies)
+  end
+
+  let(:just_object) do
+    Struct.new(:root)
+  end
+
+  context 'featuring class is created' do
+    let(:featuring_class) { artifact_class.featuring(TestTest::A, TestTest::B) }
+
+    it 'returns correct class name' do
+      expect(featuring_class.to_s).to match(/Subclass.*TestTest..B.*TestTest..A/)
+    end
+  end
+
+  context 'instance created' do
+    let(:params) do
+      {
+        c: 'qwe',
+        d: {
+          e: {
+            f: { a: dependency.new(true, [just_object.new(2)]) },
+            g: { d: dependency.new(true, [just_object.new(1)]) }
+          }
+        }
+      }
+    end
+
+    let(:instance) { artifact_class.new(params) }
+
+    context 'label is not specified' do
+      it 'contains auto-generated label' do
+        expect(instance.label).not_to be_nil
+      end
+    end
+
+    context 'root is not specified' do
+      it 'root is not empty' do
+        expect(instance.root).not_to be_nil
+      end
+      it 'doesn\'t have any dependencies' do
+        expect(instance.dependencies).to be_empty
+      end
+    end
+    context 'label is specified' do
+      before { params[:label] = 'b' }
+      it 'contains passed label' do
+        expect(instance.label).to be == 'b'
+      end
+    end
+    context 'root is specified' do
+      before { params[:root] = 1 }
+      it 'contains one dependency' do
+        expect(instance.dependencies).to be == [just_object.new(1)].to_set
+      end
+      it 'contains passed root' do
+        expect(instance.root).to be == 1
+      end
+    end
+    context 'different root is specified' do
+      before { params[:root] = 2 }
+      it 'contains one dependency' do
+        expect(instance.dependencies).to be == [just_object.new(2)].to_set
+      end
+    end
+    context 'no overrides specified' do
+      before { params.merge!(root: 3, label: 'thing') }
+
+      let(:expected) do
+        {
+          label: 'thing',
+          a: 'b',
+          b: 'QWE',
+          c: 'qwe',
+          d: {
+            e: {
+              f: { a: dependency.new(true, [just_object.new(2)]) },
+              g: { d: dependency.new(true, [just_object.new(1)]) }
+            }
+          },
+          root: 3
+        }
+      end
+
+      it 'calculates with defaults' do
+        expect(instance.options.to_hash).to be == expected
+      end
+    end
+    context 'override is present in input hash' do
+      before { params.merge!(root: 3, label: 'thing', a: 'rty') }
+
+      let(:expected) do
+        {
+          label: 'thing',
+          a: 'rty',
+          b: 'QWE',
+          c: 'qwe',
+          d: {
+            e: {
+              f: { a: dependency.new(true, [just_object.new(2)]) },
+              g: { d: dependency.new(true, [just_object.new(1)]) }
+            }
+          },
+          root: 3
+        }
+      end
+
+      it 'calculates with defaults' do
+        expect(instance.options.to_hash).to be == expected
+      end
+    end
+  end
+
+  context 'instance of child class created' do
+    let(:child_class) do
+      Class.new(artifact_class) do
+        default a: 'c',
+                c: proc { options[:d].tr(' ', '.') }
+      end
+    end
+
+    let(:params) { { root: 3, label: 'thing', d: 'q w e' } }
+
+    let(:child_instance) { child_class.new(params) }
+
+    let(:expected) do
+      {
+        root: 3,
+        label: 'thing',
+        a: 'c',
+        b: 'Q.W.E',
+        c: 'q.w.e',
+        d: 'q w e'
+      }
+    end
+
+    it 'overlays overrides' do
+      expect(child_instance.options.to_hash).to be == expected
+    end
+  end
+end