cloud-templates 0.2.0 → 0.3.0

data/lib/aws/templates/exception/parameter_value_invalid.rb

@@ -0,0 +1,37 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # A value failed constraints
+      class ParameterValueInvalid < ParameterException
+        attr_reader :value
+        attr_reader :object
+
+        def initialize(target_parameter, target_object, target_value)
+          @value = target_value
+          @object = target_object
+          super(
+            target_parameter,
+            message_text(target_parameter, target_object, target_value)
+          )
+        end
+
+        private
+
+        def message_text(target_parameter, target_object, target_value)
+          message = "Value '(#{target_value.inspect})' violates constraints specified for " \
+            "#{target_parameter.name} (#{target_parameter.description}) in " \
+            "#{target_parameter.klass}"
+
+          unless target_object.class == target_parameter.klass
+            message += " and inherited by #{target_object.class}"
+          end
+
+          message
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/exception/parametrized_dsl_error.rb

@@ -0,0 +1,14 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # Parameter definition exception
+      #
+      # Meta-programming exception related to Parametrized DSL
+      class ParametrizedDSLError < StandardError
+      end
+    end
+  end
+end

data/lib/aws/templates/exception/view_not_found.rb

@@ -0,0 +1,26 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # View was not found for the object
+      #
+      # View map was checked and there is no appropriate view class
+      # for the object class found in the registry.
+      class ViewNotFound < RuntimeError
+        # Instance of the object class render lookup was performed for
+        attr_reader :instance
+
+        def message
+          "Can't find any view for #{instance.inspect} of class #{instance.class}"
+        end
+
+        def initialize(target_instance)
+          super()
+          @instance = target_instance
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/help.rb

@@ -0,0 +1,43 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    ##
+    # Abstract help generator
+    #
+    # Implements basic functionality which is needed for programmatic help generation.
+    # Namely:
+    # * Module/entity class lookup
+    # * Final formatting
+    module Help
+      include Templates::Processor
+
+      ##
+      # Generate help for the entity
+      def process(entity, params = nil)
+        ancestors_list = entity.is_a?(::Module) ? entity.ancestors : entity.class.ancestors
+        ancestor = ancestors_list.find { |mod| handler?(mod) }
+        return unless ancestor
+
+        handler_for(ancestor).new(entity, params).provide
+      end
+
+      ##
+      # Generate help structure and format it
+      #
+      # It returns ready-to-be-displayed blob in specific format. Essentially, it processes entity
+      # and then formats the output of the processing.
+      def show(entity, params = nil)
+        format(process(entity, params), params)
+      end
+
+      ##
+      # Formatting routine
+      #
+      # Part of inversion-of-control. Must be overriden by a concrete implementation.
+      def format(_result, _params = nil)
+        raise Templates::Exception::NotImplementedError.new('The method should be overriden')
+      end
+    end
+  end
+end

data/lib/aws/templates/help/aggregate.rb

@@ -0,0 +1,74 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Help
+      ##
+      # Aggregated documentation provider
+      #
+      # A composite which generates documentation for entities which have a few documentation
+      # aspects which must be assembled in the resulting piece. Documentation aspects must have
+      # their own documentation providers. Aggregate will assemble them all according to the
+      # specified ordering.
+      class Aggregate < Provider
+        # DSL to declare aspects which should be displayed before entity-specific fragment
+        def self.before(*mods)
+          before_providers.concat(get_handlers_for(mods))
+        end
+
+        # DSL to declare aspects which should be displayed after entity-specific fragment
+        def self.after(*mods)
+          after_providers.concat(get_handlers_for(mods))
+        end
+
+        # The list of aspects to be displayed before entity-specific fragment
+        def self.before_providers
+          @before_providers ||= superclass < Aggregate ? superclass.before_providers.dup : []
+        end
+
+        # The list of aspects to be displayed after entity-specific fragment
+        def self.after_providers
+          @after_providers ||= superclass < Aggregate ? superclass.after_providers.dup : []
+        end
+
+        def provide
+          fragments = _process_through(self.class.before_providers)
+                      .push(fragment)
+                      .concat(_process_through(self.class.after_providers))
+
+          fragments.compact!
+
+          compose(fragments) unless fragments.empty?
+        end
+
+        # Get list of aspect handlers for the list of classes/modules
+        def self.get_handlers_for(mods)
+          mods.map { |mod| processor.handler_for(mod) }
+        end
+
+        protected
+
+        ##
+        # Compose documentation aspects
+        #
+        # Implements inversion-of-control to provide implementation-specific way of composing
+        # documentation fragments
+        def compose(_fragments)
+          raise Templates::Exception::NotImplementedError.new('The method should be overriden')
+        end
+
+        ##
+        # Entity-specific fragment
+        def fragment
+          raise Templates::Exception::NotImplementedError.new('The method should be overriden')
+        end
+
+        private
+
+        def _process_through(providers)
+          providers.map { |p| p.new(context, parameters).provide }
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/help/dsl.rb

@@ -0,0 +1,30 @@
+require 'aws/templates/utils'
+require 'facets/string/indent'
+
+module Aws
+  module Templates
+    module Help
+      ##
+      # Help description DSL
+      #
+      # Mixin to construct inheritable help documentation which can be rendered through
+      # standard rendering framework allowing different types of output to be produced.
+      module Dsl
+        include Templates::Utils::Inheritable
+
+        instance_scope do
+          def help
+            self.class.help
+          end
+        end
+
+        class_scope do
+          def help(str = nil)
+            return @help if str.nil?
+            @help = str.unindent
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/help/provider.rb

@@ -0,0 +1,15 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Help
+      ##
+      # Abstract help provider
+      class Provider < Templates::Processor::Handler
+        def provide
+          raise Templates::Exception::NotImplementedError.new('The method should be overriden')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+require 'aws/templates/utils'
+require 'rdoc'
+
+module Aws
+  module Templates
+    module Help
+      ##
+      # Rdoc-based help generator
+      #
+      # The generator uses RDoc utility classes internally to compose documentation blurbs.
+      # It supports all output formats as RDoc.
+      module Rdoc
+        extend Help
+        extend Texting
+
+        routing Routing
+
+        ##
+        # Compose a doc fragment for scalar value
+        #
+        # Abstract documentation provider for scalar values.
+        class Scalar < Provider
+          def provide
+            sub(parameters.nil? ? text(value) : text("_#{parameters}_ #{value}"))
+          end
+
+          protected
+
+          def value
+            raise 'Should be overriden'
+          end
+        end
+
+        ##
+        # Compose a doc fragment for lambda
+        class Calculable < Scalar
+          for_entity ::Proc
+
+          protected
+
+          def value
+            location = context.source_location
+
+            message = begin
+              "Calculated in #{context.binding.receiver}"
+            rescue ArgumentError
+              'Calculated'
+            end
+
+            location.nil? ? message : "#{message} (#{location.join(':')})"
+          end
+        end
+
+        ##
+        # Default help provider
+        #
+        # Does a few preliminary check and either use insection of the target object or, if it
+        # supports recursive concept, goes recursively into it and composes resulting list tree
+        # of descriptions.
+        class DefaultProvider < Provider
+          for_entity ::Object
+
+          def provide
+            return _recursive if Utils.recursive?(context)
+            _inspection
+          end
+
+          private
+
+          def _inspection
+            return '*deleted*' if context == Templates::Utils::Default.deleted
+            str = context.inspect
+            sub(parameters.nil? ? text(str) : text("_#{parameters}_ #{str}"))
+          end
+
+          def _recursive
+            container = context
+                        .keys
+                        .each_with_object(list) { |key, l| l << processed_for(context[key], key) }
+
+            parameters.nil? ? sub(container) : sub(text("_#{parameters}_"), container)
+          end
+        end
+
+        def self.format(result, params = nil)
+          formatter = formatter_for(params)
+
+          formatter.start_accepting
+
+          if result
+            result = list(:LABEL, result) if result.is_a?(RDoc::Markup::ListItem)
+            result.accept(formatter)
+          end
+
+          formatter.end_accepting
+        end
+
+        def self.formatter_for(params)
+          return RDoc::Markup::ToAnsi.new unless params && params.include?(:formatter)
+          Templates::Utils.lookup_module(params[:formatter]).new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Help
+      module Rdoc
+        ##
+        # Artifact documentation generator
+        #
+        # Aggregate which assembled different aspects of artifact documentation such as:
+        # * help blurb
+        # * parameters description
+        # * defaults description
+        class Artifact < Help::Aggregate
+          include Rdoc::Texting
+
+          register_in Rdoc
+          for_entity Templates::Artifact
+
+          after Templates::Help::Dsl, Templates::Utils::Parametrized, Templates::Utils::Default
+
+          protected
+
+          def fragment
+            sub(
+              text("\n*#{context.name}*"),
+              text("_Parents_: #{superclasses.map(&:to_s).join('->')}")
+            )
+          end
+
+          def compose(fragments)
+            list(:LABEL, *fragments)
+          end
+
+          private
+
+          def superclasses
+            Enumerator.new do |y|
+              s = context.superclass
+              while s && s <= Templates::Artifact
+                y << s
+                s = s.superclass
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Help
+      module Rdoc
+        ##
+        # Composite documentation provider
+        #
+        # Does the same as Artifact documentation aggregate adding context filters section as an
+        # aspect
+        class Composite < Rdoc::Artifact
+          for_entity Templates::Composite
+
+          after Templates::Utils::Contextualized
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module Aws
+  module Templates
+    module Help
+      module Rdoc
+        ##
+        # Contextualized namespace
+        module Contextualized
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/help/rdoc/contextualized/filter.rb

@@ -0,0 +1,19 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Help
+      module Rdoc
+        module Contextualized
+          ##
+          # Context filter documentation provider
+          #
+          # Abstract filter documentation provider
+          class Filter < Rdoc::Provider
+            for_entity Templates::Utils::Contextualized::Filter
+          end
+        end
+      end
+    end
+  end
+end