cloud-templates 0.2.0 → 0.3.0

data/lib/aws/templates/cli.rb

@@ -0,0 +1,14 @@
+require 'json'
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    ##
+    # CLI namespace. See Cli::Processor
+    module Cli
+      def self.start(*args)
+        Cli::Interface.start(*args)
+      end
+    end
+  end
+end

data/lib/aws/templates/cli/formatter.rb

@@ -0,0 +1,21 @@
+require 'aws/templates/utils'
+require 'facets/string/pathize'
+
+module Aws
+  module Templates
+    module Cli
+      ##
+      # Pluggable formatters
+      #
+      # The module contains formatter factory method and default formatter (AsIs) definition.
+      # Formatters are classes implementing simple "format" method accepting object and returning
+      # its' formatted string version.
+      module Formatter
+        def self.format_as(type, *params)
+          require "aws/templates/cli/formatter/#{type.pathize}"
+          const_get(type).new(*params)
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/cli/formatter/json.rb

@@ -0,0 +1,20 @@
+require 'json'
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Cli
+      module Formatter
+        ##
+        # JSON formatter
+        #
+        # Transforms passed object into valid JSON document
+        class Json
+          def format(obj)
+            obj.to_json
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/cli/interface.rb

@@ -0,0 +1,92 @@
+require 'json'
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Cli
+      ##
+      # Templates CLI
+      #
+      # The class provides command-line utilities to use cloud templates and artifacts without
+      # knowledge of Ruby directly from command line.
+      # Commands:
+      # * render - It is used to setup and execute rendering of a single artifact. Also, different
+      #            formatters supported for output. By default, render output is not formatted
+      #            at all and is returned as is. JSON formatter is available out-of-box.
+      # * document - provide online documentation for selected artifact optionally using specific
+      #              documentation generator
+      class Interface < ::Thor
+        desc 'render ARTIFACT', 'Render ARTIFACT with RENDER and print result'
+
+        method_option :format,
+                      desc: 'Formatter used for final output',
+                      aliases: :f,
+                      required: false,
+                      default: 'Json',
+                      type: :string
+
+        method_option :options,
+                      desc: 'JSON-formatted options to pass to the artifact',
+                      aliases: :o,
+                      required: false,
+                      type: :string
+
+        method_option :render,
+                      desc: 'Render',
+                      aliases: :r,
+                      required: true,
+                      type: :string
+
+        def render(artifact_path)
+          say _format(
+            Templates::Utils.lookup_module(artifact_path),
+            Templates::Utils.lookup_module(options[:render]),
+            Aws::Templates::Cli::Formatter.format_as(options[:format]),
+            ::JSON.parse(options[:options] || _as_string(STDIN), symbolize_names: true)
+          )
+        end
+
+        desc 'document ARTIFACT', 'Show help for the ARTIFACT'
+
+        method_option :generator,
+                      desc: 'Generator to be used to generate the documentation',
+                      aliases: :g,
+                      required: false,
+                      default: 'Aws::Templates::Help::Rdoc',
+                      type: :string
+
+        method_option :parameters,
+                      desc: 'JSON-formatted generator optional parameters',
+                      aliases: :p,
+                      required: false,
+                      type: :string
+
+        def document(artifact_path)
+          artifact = Templates::Utils.lookup_module(artifact_path)
+          generator = Templates::Utils.lookup_module(options[:generator])
+          params = options[:parameters] && ::JSON.parse(options[:parameters], symbolize_names: true)
+
+          say(generator.show(artifact, params))
+        end
+
+        private
+
+        def _format(artifact, render, format, artifact_options)
+          format.format(render.view_for(artifact.new(artifact_options)).to_rendered)
+        end
+
+        def _as_string(obj)
+          if obj.respond_to?(:to_str)
+            obj.to_str
+          elsif obj.respond_to?(:to_io)
+            obj.to_io.read
+          elsif obj.respond_to?(:read)
+            obj.read
+          else
+            obj.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/composite.rb

@@ -1,7 +1,4 @@
-require 'aws/templates/artifact'
-require 'aws/templates/utils/artifact_storage'
-require 'aws/templates/utils/contextualized'
-require 'aws/templates/utils/dependency'
+require 'aws/templates/utils'
 
 module Aws
   module Templates
@@ -25,7 +22,9 @@ module Aws
     # supports inheritance as artifact does. So every component defined in
     # the parent class will be initialized properly in all children too.
     class Composite < Artifact
-      include Aws::Templates::Utils::Contextualized
+      include Templates::Utils::Contextualized
+      using Templates::Utils::Contextualized::Refinements
+      using Templates::Utils::Dependency::Refinements
 
       # propagate root to the components and set itself as the parent
       contextualize filter(:add, :root) & (filter(:override) { { parent: self } })
@@ -37,7 +36,7 @@ module Aws
       # Accessor returning dictionary of artifacts currently residing in
       # composite instance with labels as keys
       def artifacts
-        @artifacts ||= Utils::ArtifactStorage.new
+        @artifacts ||= Templates::Utils::ArtifactStorage.new
       end
 
       ##
@@ -168,9 +167,7 @@ module Aws
 
       def create_components; end
 
-      private
-
-      def create_artifact_object(type, params, &blk)
+      def create_artifact_object(type, params = nil, &blk)
         type.new(options.filter(&contextualize(params.to_filter)), &blk)
       end
     end

data/lib/aws/templates/exception.rb

@@ -0,0 +1,8 @@
+module Aws
+  module Templates
+    ##
+    # Namespace for framework-specific exceptions
+    module Exception
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # If something happens during parameter calculation
+      class NestedParameterException < ParameterException
+        def initialize(target_parameter)
+          super(
+            target_parameter,
+            'Exception was thrown by nested parameter while calculating ' \
+              "#{target_parameter.name} (#{target_parameter.description})"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # Options exception
+      #
+      # The parent of all exceptions Options method can throw
+      class OptionError < ArgumentError
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # Scalar is met while traversing Options path
+      #
+      # Path is not empty yet but we can't traverse deeper because the current value is a scalar
+      class OptionScalarOnTheWay < OptionError
+        attr_reader :value
+        attr_reader :path
+
+        def initialize(value, path)
+          @value = value
+          @path = path
+
+          super(
+            "Value #{value} is not a recursive data structure and we have still #{path} keys " \
+              'to look-up'
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # Recursive value is expected
+      #
+      # Value passed doesn't not support "recursive" contract. See Utils.recursive?
+      class OptionShouldBeRecursive < OptionError
+        attr_reader :value
+
+        def initialize(value)
+          @value = value
+          super("Value #{value} is not a recursive data structure")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # Deleted branch detected
+      #
+      # While traversing Options layers for a value, deleted branch marker was discovered.
+      class OptionValueDeleted < OptionError
+        attr_reader :path
+
+        def initialize(path)
+          @path = path
+          super(
+            "Deleted value was detected while traversing path. The path left untraversed: #{path}"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # Parameter already exists
+      #
+      # If you're trying to define a parameter in a parametrized artifact
+      # and this parameter either already defined for the class or defined
+      # in an ancestor.
+      class ParameterAlreadyExist < ParametrizedDSLError
+        # Parameter object of the conflicting parameter
+        attr_reader :parameter
+
+        def initialize(target_parameter)
+          @parameter = target_parameter
+          super(
+            "Parameter #{target_parameter.name} already in " \
+            "#{target_parameter.klass}."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # Parameter exception
+      #
+      # Happens during runtime if an error happens during parameter
+      # evaluation
+      class ParameterException < RuntimeError
+        # Parameter object
+        attr_reader :parameter
+
+        def message
+          cause.nil? ? super : "#{super} : #{cause.message}"
+        end
+
+        def initialize(target_parameter, custom_message)
+          @parameter = target_parameter
+          super(custom_message)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # Getter is not specified
+      #
+      # Getter wasn't specified neither for the individual parameter nor for the mixing instance nor
+      # for its class.
+      class ParameterGetterIsNotDefined < ParameterException
+        def initialize(target_parameter)
+          super(
+            target_parameter,
+            "Can't find getter for #{target_parameter.name} (#{target_parameter.description}): " \
+              'a getter should be attached either to the parameter or the instance ' \
+              'or the instance class'
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # A regular method and a parameter have the same name in a class
+      #
+      # A parameter was specified with the same name as exsiting method
+      # in the class or in an ancestor of the class.
+      class ParameterMethodNameConflict < ParametrizedDSLError
+        # Method object of the method specified
+        attr_reader :method_object
+
+        def initialize(target_method)
+          @method_object = target_method
+
+          super(
+            "Parameter name #{target_method.name} clashes with a method name in " \
+            "#{target_method.owner.name}"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+require 'aws/templates/utils'
+
+module Aws
+  module Templates
+    module Exception
+      ##
+      # Invalid parameter specification hash
+      #
+      # If unknown option is passed in a parameter description block
+      class ParameterSpecificationIsInvalid < ParametrizedDSLError
+        # Parameter object faulty options were specified for
+        attr_reader :parameter
+
+        # Options unknown to Parametrized
+        attr_reader :options
+
+        def initialize(target_parameter, opts)
+          @parameter = target_parameter
+          @options = opts
+
+          super(
+            'Unsupported options are in specification for ' \
+            "parameter #{target_parameter.name} in class " \
+            "#{target_parameter.klass} : #{opts}"
+          )
+        end
+      end
+    end
+  end
+end