cloud-templates 0.2.0 → 0.3.0

data/lib/aws/templates/help/rdoc/texting.rb

@@ -0,0 +1,42 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Help
+      module Rdoc
+        ##
+        # Rdoc classes wrapper
+        #
+        # Creates simple DSL over Rdoc native classes so text blocks can be composed in idiomatic
+        # Ruby way.
+        module Texting
+          def sub(*parts)
+            item = ::RDoc::Markup::ListItem.new(nil, *parts)
+            yield item if block_given?
+            item
+          end
+
+          def text(str)
+            ::RDoc::Markup::Paragraph.new(str)
+          end
+
+          def list(type = :BULLET, *parts)
+            list = ::RDoc::Markup::List.new(type, *parts)
+            yield list if block_given?
+            list
+          end
+
+          def parsed_for(str)
+            sub { |s| RDoc::Markup.parse(str).each { |part| s << part } }
+          end
+
+          def document(*parts)
+            doc = ::RDoc::Markup::Document.new(*parts)
+            yield doc if block_given?
+            doc
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/processor.rb

@@ -0,0 +1,53 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    ##
+    # Abstract processor
+    #
+    # Processors are used in artifacts rendering and help generators. Processor embodies
+    # functionality required to register an entity handler and look-up the registry when the
+    # entity is processed.
+    module Processor
+      include Routing
+
+      ##
+      # Proxy for Registry handler_for method
+      def handler_for(*args)
+        registry.handler_for(*args)
+      end
+
+      ##
+      # Proxy for Registry handler? method
+      def handler?(*args)
+        registry.handler?(*args)
+      end
+
+      ##
+      # Handlder look-up logic.
+      #
+      # Should provide logic for processing entities.
+      def process(_entity, _params = nil)
+        raise Templates::Exception::NotImplementedError.new('The method should be overriden')
+      end
+
+      ##
+      # Define handler for entity
+      #
+      # Another way to define handlers for entities. Creates anonymous class and attaches as
+      # the handler to the specified entity.
+      def define_handler(entity, handler, &blk)
+        Class.new(handler, &blk).register_in(self).for_entity(entity)
+      end
+
+      ##
+      # Add handlers
+      #
+      # Add routing between handlers and correspondent entities from another entity which supports
+      # routing concept.
+      def routing(routes)
+        registry.merge(routes.registry)
+      end
+    end
+  end
+end

data/lib/aws/templates/processor/handler.rb

@@ -0,0 +1,104 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Processor
+      ##
+      # Basic entity handler
+      #
+      # Handler are classes encapsulating functionality of transforming entity into desired output.
+      # For instance, the same LDAP record can be transformed into JSON description or LDIF
+      # definition. The same help article can be written to output console or HTML.
+      #
+      # Each handler is attached to a registry object which stores correspondence
+      # between entities and their handlers. A handler is registered in a registry only when it is
+      # attached to an entity. Handler depend on entities but entities are not aware of handlers.
+      #
+      # Handlers are regular Ruby classes and all assumptions made about polymorphism, inheritance
+      # and incapsulation are true for them.
+      #
+      # Handler class itself is an abstract class which can't be instantiated directly.
+      class Handler
+        class << self
+          ##
+          # Render accessor
+          #
+          # Returns either processor of this handler class or processor of any ancestor.
+          def processor
+            @processor || (superclass.processor if superclass < Handler)
+          end
+
+          ##
+          # Register the hander class in a processor
+          #
+          # Registers the handler class in the processor
+          # * +r+ - processor registrar
+          def register_in(r)
+            @processor = r
+            self
+          end
+
+          ##
+          # Link the handler class to the entity
+          #
+          # Registers the link in the processor object of the handler class.
+          def for_entity(entity)
+            @entity = entity
+            processor.register(entity, self)
+            self
+          end
+
+          ##
+          # Entity the handler is registered for
+          attr_reader :entity
+        end
+
+        ##
+        # Context handler object is attached to
+        attr_reader :context
+
+        ##
+        # Assigned handler parameters
+        attr_reader :parameters
+
+        ##
+        # Execute in the context
+        #
+        # Executes passed block in the context. It helps against putting too much context-dependend
+        # method accesses in long blocks. Returns the value returned by the block.
+        def in_context(*args, &blk)
+          context.instance_exec(*args, &blk)
+        end
+
+        ##
+        # Create handler instance and link it to the context
+        def initialize(ctx, params = nil)
+          @context = ctx
+          @parameters = params
+        end
+
+        ##
+        # Alias for class method processor
+        def processor
+          self.class.processor
+        end
+
+        ##
+        # Process the object
+        #
+        # Processes passed object with the handler default processor
+        def processed_for(obj, parameters_override = nil)
+          processor.process(obj, parameters_override.nil? ? parameters : parameters_override)
+        end
+
+        ##
+        # Get handler for the entity
+        #
+        # Returns registered handler for the entity
+        def handler_for(entity)
+          processor.handler_for(entity)
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/processor/registry.rb

@@ -0,0 +1,74 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Processor
+      ##
+      # Handler registry
+      #
+      # Handler registries encapsulate differerent ways of transforming entities into
+      # domain-specific output. In nutshell, they are registries of Handler classes which are able
+      # to lookup proper Handler for a given entity.
+      class Registry
+        # Handler registry accessor
+        def registry
+          @registry ||= ::Concurrent::Map.new
+        end
+
+        ##
+        # Register pair entity-handler
+        #
+        # Invoked from inside of a Handler class at definition of the link between the handler class
+        # and an entity.
+        # * +entity+ - entity the handler claims to be able to process
+        # * +handler+ - handler class
+        def register(entity, handler)
+          registry.put_if_absent(_process_entity(entity), handler)
+        end
+
+        ##
+        # Try to look-up the handler
+        def handler_for(entity)
+          handler = self[entity]
+          raise "Handler is not found for #{entity}" unless handler
+          handler.reduce
+        end
+
+        ##
+        # Merge map with another recursive
+        def merge(recursive)
+          raise "#{recursive} is not recursive" unless Utils.recursive?(recursive)
+          recursive.keys.each { |k| register(k, recursive[k]) }
+          self
+        end
+
+        # All possible entity types
+        def keys
+          registry.keys
+        end
+
+        ##
+        # Look-up the handler
+        def [](entity)
+          return registry[entity] unless entity.is_a?(Module)
+          registry[entity.name] || registry[entity]
+        end
+
+        ##
+        # Check if handler exists
+        def include?(k)
+          !self[k].nil?
+        end
+
+        alias handler? include?
+
+        private
+
+        def _process_entity(entity)
+          return entity unless entity.is_a?(Module)
+          entity.name || entity.reduce
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/processor/routing.rb

@@ -0,0 +1,27 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Processor
+      ##
+      # Routing DSL
+      #
+      # Defines trivial methods to wire handlers with respective entities.
+      module Routing
+        ##
+        # Registry accessor
+        #
+        # All handlers and corresponding entities in a processor are stored in a registry.
+        def registry
+          @registry ||= Processor::Registry.new
+        end
+
+        ##
+        # Proxy for Registry register method
+        def register(*args)
+          registry.register(*args)
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/render.rb

@@ -1,6 +1,4 @@
-require 'aws/templates/exceptions'
-require 'aws/templates/render/registry'
-require 'aws/templates/render/view'
+require 'aws/templates/utils'
 
 module Aws
   module Templates
@@ -29,31 +27,36 @@ module Aws
     #      extend Aws::Templates::Render
     #    end
     module Render
+      include Templates::Processor
+
       ##
-      # Registry accessor
+      # Can object be rendered
       #
-      # All views and corresponding artifacts in a render are stored
-      # in a registry.
-      def registry
-        @registry ||= Registry.new
+      # Returns true if the object passed can be rendered by one of the views in the registry
+      def can_render?(instance)
+        instance.class.ancestors.any? { |ancestor| handler?(ancestor) }
       end
 
       ##
-      # Proxy for Registry register method
-      def register(*args)
-        registry.register(*args)
-      end
+      # Lookup a view for the artifact
+      #
+      # Searches registry for artifact's class and all its ancestors
+      # in the registry and returns the closest matching view
+      # * +instance+ - artifact instance to render
+      # * +params+ - assigned parameters; it can be arbitrary value;
+      #              it is propagated to selected render
+      def view_for(instance, params = nil)
+        return instance if instance.respond_to?(:to_rendered)
 
-      ##
-      # Proxy for Registry can_render? method
-      def can_render?(*args)
-        registry.can_render?(*args)
+        ancestor = instance.class.ancestors.find { |mod| handler?(mod) }
+
+        raise Templates::Exception::ViewNotFound.new(instance) unless ancestor
+
+        handler_for(ancestor).new(instance, params)
       end
 
-      ##
-      # Proxy for Registry view_for method
-      def view_for(*args)
-        registry.view_for(*args)
+      def process(entity, params = nil)
+        view_for(entity, params).to_rendered
       end
 
       ##
@@ -61,12 +64,11 @@ module Aws
       #
       # Another way to define views for artifacts. Creates anonymous class and attaches as the view
       # to the specified artifact
-      def define_view(artifact_class, view = nil, &blk)
-        Class
-          .new(view || Aws::Templates::Render::BasicView, &blk)
-          .register_in(self)
-          .artifact(artifact_class)
+      def define_handler(artifact_class, view = nil, &blk)
+        super(artifact_class, view || BasicView, &blk)
       end
+
+      alias define_view define_handler
     end
   end
 end

data/lib/aws/templates/render/basic_view.rb

@@ -0,0 +1,47 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Render
+      ##
+      # Basic render view
+      #
+      # Views are classes encapsulating functionality of transforming
+      # artifacts into domain-specific output. For instance, the same
+      # LDAP record can be transformed into JSON description or LDIF definition.
+      # Views can be attached to ancestors of an artifact and it expected
+      # that the library will look-up the closest ancestor having view attached
+      # if the render is invoked on a child.
+      #
+      # Each view is attached to a registry object which stores correspondence
+      # between artifact classes and their views, and optionally to an artifact.
+      # A view is registered in a registry only when it is attached to an artifact.
+      # Views depend on artifacts but artifacts are not aware of views.
+      # As the extreme case, a sole view can be attached to Artifact
+      # if you have universal way to render your domain objects.
+      #
+      # Views are regular Ruby classes and all assumptions made about
+      # polymorphism, inheritance and incapsulation are true for them.
+      #
+      # View class itself is an abstract class which can't be instantiated
+      # directly.
+      class BasicView < Templates::Processor::Handler
+        class << self
+          alias artifact for_entity
+        end
+
+        alias instance context
+        alias in_instance in_context
+        alias rendered_for processed_for
+
+        ##
+        # Render the instance of the artifact
+        #
+        # The method should be overriden and return rendered form of the attached instance
+        def to_rendered
+          raise Templates::Exception::NotImplementedError.new('The method should be overriden')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Render
+      ##
+      # Namespace for rendering utils
+      #
+      # Contains supplemental re-usable components which are not related to the core functionality.
+      module Utils
+      end
+    end
+  end
+end