cumuliform 0.5.1 → 0.5.2

data/lib/cumuliform/dsl/helpers.rb

@@ -0,0 +1,70 @@
+require_relative '../error'
+
+module Cumuliform
+  module DSL
+    # Contains DSL methods for including modules containing simple helper methods
+    #
+    # Helper methods are isolated from the template object, so they can't
+    # call other DSL methods. They're really intended for wrapping code that
+    # is used in several places but requires complex setup, for example a
+    # third-party API that issues tokens you need to include in your template
+    # in some way.
+    module Helpers
+      # Add helper methods to the template.
+      #
+      # @overload helpers(mod, ...)
+      #   Include one or more helper modules
+      #   @param mod [Module] Module containing helper methods to include
+      # @overload helpers(&block)
+      #   @param block [lambda] Block containing helper method definitins to include
+      def helpers(*mods, &block)
+        if block_given?
+          mods << Module.new(&block)
+        end
+        mods.each do |mod|
+          helpers_class.class_eval {
+            include mod
+          }
+        end
+      end
+
+      protected
+
+      # @api private
+      def has_helper?(meth)
+        helpers_instance.respond_to?(meth)
+      end
+
+      # @api private
+      def template_for_helper(meth)
+        return self if has_helper?(meth)
+        imports.reverse.find { |template|
+          template.template_for_helper(meth)
+        }
+      end
+
+      # @api private
+      def send_helper(meth, *args)
+        helpers_instance.send(meth, *args)
+      end
+
+      private
+
+      def helpers_class
+        @helpers_class ||= Class.new
+      end
+
+      def helpers_instance
+        @helpers_instance ||= helpers_class.new
+      end
+
+      def method_missing(meth, *args)
+        if template = template_for_helper(meth)
+          template.send_helper(meth, *args)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/cumuliform/dsl/import.rb

@@ -0,0 +1,34 @@
+require_relative '../error'
+
+module Cumuliform
+  module DSL
+    # DSL methods for importing other templates
+    module Import
+      # Import another Cumuliform::Template into this one
+      #
+      # @param template [Template] the template to import
+      def import(template)
+        imports << template
+      end
+
+      # @api private
+      def has_logical_id?(logical_id)
+        (imports.reverse).inject(logical_ids.include?(logical_id)) { |found, template|
+          found || template.has_logical_id?(logical_id)
+        }
+      end
+
+      # @api private
+      def verify_logical_id!(logical_id)
+        raise Error::NoSuchLogicalId, logical_id unless has_logical_id?(logical_id)
+        true
+      end
+
+      private
+
+      def imports
+        @imports ||= []
+      end
+    end
+  end
+end

data/lib/cumuliform/error.rb

@@ -1,44 +1,63 @@
 module Cumuliform
   module Error
+    # The base error class for id-related errors
     class IDError < StandardError
+      # The logical ID this error refers to
       attr_reader :id
 
+      # Initialize a new IDError for the given ID
+      #
+      # @param id [String] CloudFormation logical ID
       def initialize(id)
         @id = id
       end
     end
 
+    # raised when a logical ID already exists
     class DuplicateLogicalID < IDError
+      # returns human-readable error message
       def to_s
         "Existing item with logical ID '#{id}'"
       end
     end
 
+    # raised when a lookup for a logical ID fails
     class NoSuchLogicalId < IDError
+      # returns human-readable error message
       def to_s
         "No such logical ID '#{id}'"
       end
     end
 
+    # raised when a Fragment with the same ID has already been defined
     class FragmentAlreadyDefined < IDError
+      # returns human-readable error message
       def to_s
         "Fragment '#{id}' already defined"
       end
     end
 
+    # raised when a Fragment lookup fails
     class FragmentNotFound < IDError
+      # returns human-readable error message
       def to_s
         "No fragment with name '#{id}'"
       end
     end
 
+    # raised when an item (e.g. Resource or Parameter) to be output contains
+    # nothing
     class EmptyItem < IDError
+      # returns human-readable error message
       def to_s
         "Empty item '#{id}'"
       end
     end
 
+    # raised when the template has no Resources defined at all (CloudFormation
+    # requires at least one resource)
     class NoResourcesDefined < StandardError
+      # returns human-readable error message
       def to_s
         "No resources defined"
       end

data/lib/cumuliform/output.rb

@@ -2,10 +2,15 @@
 # DSLize every last thing. Simple is the watch word
 
 require 'json'
-require 'set'
 
 module Cumuliform
+  # Manages converting the Cumuliform::Template into a CloudFormation JSON
+  # string
   module Output
+    # Processes the template and returns a hash representing the CloudFormation
+    # template
+    #
+    # @return [Hash] Hash representing the CloudFormation template
     def to_hash
       output = {}
       SECTIONS.each do |section_name, _|
@@ -17,6 +22,10 @@ module Cumuliform
       output
     end
 
+    # Generates the JSON representation of the template from the Hash
+    # representation provided by #to_hash
+    #
+    # @return [String] JSON representation of the CloudFormation template
     def to_json
       JSON.pretty_generate(to_hash)
     end

data/lib/cumuliform/rake_task.rb

@@ -1,9 +1,13 @@
 require 'cumuliform/runner'
 
 module Cumuliform
+  # Creates a Rake rule task for converting a Cumuliform template file into a
+  # CloudFormation JSON file
   module RakeTask
     extend self
 
+    # Rake task lib for generating Cumuliform processing rule
+    # @api private
     class TaskLib < Rake::TaskLib
       include ::Rake::DSL if defined?(::Rake::DSL)
 
@@ -16,6 +20,8 @@ module Cumuliform
       end
     end
 
+    # Define a new Rake rule task to process Cumuliform templates into
+    # CloudFormation JSON
     def rule(*args)
       TaskLib.new.define_rule(args)
     end

data/lib/cumuliform/runner.rb

@@ -2,7 +2,14 @@ require 'cumuliform'
 require 'pathname'
 
 module Cumuliform
+  # The Runner class reads a template, execute it and write the generated JSON
+  # to a file
   class Runner
+    # Processes an IO object which will, when read, return a Cumuliform
+    # template file.
+    #
+    # @param io [IO] The IO-like object containing the template
+    # @return [Template] the parsed Cumuliform::Template object
     def self.process_io(io)
       mod = Module.new
       path = io.respond_to?(:path) ? io.path : nil
@@ -10,6 +17,11 @@ module Cumuliform
       template = mod.class_eval(*args)
     end
 
+    # Reads the template file at <tt>input_path</tt>, parses and executes it to generate CloudFormation JSON which is written to <tt>output_path</tt>
+    #
+    # @param input_path [String] The path to the input Cumuliform template file
+    # @param output_path [String] The path to the output CloudFormation JSON template file
+    # @return [void]
     def self.process(input_path, output_path)
       input_path = Pathname.new(input_path)
       output_path = Pathname.new(output_path)

data/lib/cumuliform/{import.rb → section.rb}

@@ -1,29 +1,5 @@
-require_relative 'error'
-
 module Cumuliform
-  module Import
-    def import(template)
-      imports << template
-    end
-
-    def has_logical_id?(logical_id)
-      (imports.reverse).inject(logical_ids.include?(logical_id)) { |found, template|
-        found || template.has_logical_id?(logical_id)
-      }
-    end
-
-    def verify_logical_id!(logical_id)
-      raise Error::NoSuchLogicalId, logical_id unless has_logical_id?(logical_id)
-      true
-    end
-
-    private
-
-    def imports
-      @imports ||= []
-    end
-  end
-
+  # @api private
   class Section
     attr_reader :name, :imports, :items
 

data/lib/cumuliform/sections.rb

@@ -0,0 +1,52 @@
+require_relative 'section'
+
+module Cumuliform
+  SECTIONS = {
+    "Parameters" => :parameter,
+    "Mappings" => :mapping,
+    "Conditions" => :condition,
+    "Resources" => :resource,
+    "Outputs" => :output
+  }
+
+  # @api private
+  module Sections
+    def initialize
+      SECTIONS.each do |section_name, _|
+        instance_variable_set(:"@#{section_name}", Section.new(section_name, imports))
+      end
+    end
+
+    def get_section(name)
+      instance_variable_get(:"@#{name}")
+    end
+
+    SECTIONS.each do |section_name, method_name|
+      error_class = Class.new(Error::IDError) do
+        def to_s
+          "No logical ID '#{id}' in section"
+        end
+      end
+      Error.const_set("NoSuchLogicalIdIn#{section_name}", error_class)
+
+      define_method method_name, ->(logical_id, &block) {
+        add_to_section(section_name, logical_id, block)
+      }
+
+      define_method :"verify_#{method_name}_logical_id!", ->(logical_id) {
+        raise error_class, logical_id unless get_section(section_name).member?(logical_id)
+        true
+      }
+    end
+
+    private
+
+    def add_to_section(section_name, logical_id, block)
+      if has_local_logical_id?(logical_id)
+        raise Error::DuplicateLogicalID, logical_id
+      end
+      logical_ids << logical_id
+      get_section(section_name)[logical_id] = block
+    end
+  end
+end

data/lib/cumuliform/template.rb

@@ -0,0 +1,36 @@
+# Simple AWS CloudFormation. Doesn't try to run the commands, doesn't try to
+# DSLize every last thing. Simple is the watch word
+
+require 'set'
+require_relative 'error'
+require_relative 'sections'
+require_relative 'output'
+
+module Cumuliform
+  AWS_PSEUDO_PARAMS = %w{
+      AWS::AccountId AWS::NotificationARNs AWS::NoValue
+      AWS::Region AWS::StackId AWS::StackName
+  }
+
+  # Represents a single CloudFormation template
+  class Template
+    include Output
+    include Sections
+
+    # @api private
+    def define(&block)
+      instance_exec(&block)
+      self
+    end
+
+    private
+
+    def logical_ids
+      @logical_ids ||= Set.new(AWS_PSEUDO_PARAMS)
+    end
+
+    def has_local_logical_id?(logical_id)
+      logical_ids.include?(logical_id)
+    end
+  end
+end

data/lib/cumuliform/version.rb

@@ -1,3 +1,3 @@
 module Cumuliform
-  VERSION = "0.5.1"
+  VERSION = "0.5.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cumuliform
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
 platform: ruby
 authors:
 - Matt Patterson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-12-03 00:00:00.000000000 Z
+date: 2016-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -90,20 +90,31 @@ files:
 - bin/setup
 - cumuliform.gemspec
 - examples/Rakefile
+- examples/block-helper.rb
 - examples/condition_functions.rb
 - examples/fragments.rb
+- examples/import-base.rb
+- examples/import-fragments-base.rb
+- examples/import-fragments-importer.rb
+- examples/import-importer.rb
 - examples/intrinsic_functions.rb
+- examples/module-helper.rb
 - examples/simplest.rb
 - examples/top-level-declarations.rb
 - exe/cumuliform
 - lib/cumuliform.rb
+- lib/cumuliform/dsl.rb
+- lib/cumuliform/dsl/fragments.rb
+- lib/cumuliform/dsl/functions.rb
+- lib/cumuliform/dsl/helpers.rb
+- lib/cumuliform/dsl/import.rb
 - lib/cumuliform/error.rb
-- lib/cumuliform/fragments.rb
-- lib/cumuliform/functions.rb
-- lib/cumuliform/import.rb
 - lib/cumuliform/output.rb
 - lib/cumuliform/rake_task.rb
 - lib/cumuliform/runner.rb
+- lib/cumuliform/section.rb
+- lib/cumuliform/sections.rb
+- lib/cumuliform/template.rb
 - lib/cumuliform/version.rb
 homepage: https://www.github.com/tape-tv/cumuliform
 licenses:
@@ -125,7 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: DSL library for generating AWS CloudFormation templates

data/lib/cumuliform/fragments.rb

@@ -1,63 +0,0 @@
-require_relative 'error'
-
-module Cumuliform
-  module Fragments
-    # Define a fragment for later use.
-    #
-    # Essentially stores a block under the name given for later use.
-    #
-    # @param name [Symbol] name of the fragment to define
-    # @yieldparam opts [Hash] will yield the options hash passed to
-    #   <tt>#fragment()</tt> when called
-    # @raise [Error::FragmentAlreadyDefined] if the <tt>name</tt> is not unique
-    #   in this template
-    def def_fragment(name, &block)
-      if fragments.has_key?(name)
-        raise Error::FragmentAlreadyDefined, name
-      end
-      fragments[name] = block
-    end
-
-    # Use an already-defined fragment
-    #
-    # Retrieves the block stored under <tt>name</tt> and calls it, passing any options.
-    #
-    # @param name [Symbol] The name of the fragment to use
-    # @param opts [Hash] Options to be passed to the fragment
-    # @return [Object<JSON-serialisable>] the return value of the called block
-    def fragment(name, *args, &block)
-      if block_given?
-        warn "fragment definition form (with block) is deprecated. Use #def_fragment instead"
-        def_fragment(name, *args, &block)
-      else
-        use_fragment(name, *args)
-      end
-    end
-
-    # @api private
-    def find_fragment(name)
-      local_fragment = fragments[name]
-      imports.reverse.reduce(local_fragment) { |fragment, import|
-        fragment || import.find_fragment(name)
-      }
-    end
-
-    private
-
-    def use_fragment(name, opts = {})
-      unless has_fragment?(name)
-        raise Error::FragmentNotFound, name
-      end
-      instance_exec(opts, &find_fragment(name))
-    end
-
-
-    def fragments
-      @fragments ||= {}
-    end
-
-    def has_fragment?(name)
-      !find_fragment(name).nil?
-    end
-  end
-end