cumuliform 0.5.1 → 0.5.2

data/examples/import-fragments-base.rb

@@ -0,0 +1,38 @@
+FragmentBaseTemplate = Cumuliform.template do
+  def_fragment(:ami_param) do |opts|
+    parameter 'AMI' do
+      {
+        Description: 'AMI id',
+        Type: 'String',
+        Default: opts[:ami_id]
+      }
+    end
+  end
+
+  def_fragment(:instance_type) do |opts|
+    parameter 'InstanceType' do
+      {
+        Description: 'InstanceType',
+        Type: 'String',
+        Default: opts[:type],
+        AllowedValues: ['t2.small', 't2.medium', 't2.large']
+      }
+    end
+  end
+
+  def_fragment(:instance) do |opts|
+    resource 'MyInstance' do
+      {
+        Type: 'AWS::EC2::Instance',
+        Properties: {
+          ImageId: ref('AMI'),
+          InstanceType: ref('InstanceType')
+        }
+      }
+    end
+  end
+
+  fragment(:ami_param, ami_id: 'ami-accff2b1')
+  fragment(:instance_type, type: 'm4.medium')
+  fragment(:instance)
+end

data/examples/import-fragments-importer.rb

@@ -0,0 +1,18 @@
+require_relative './import-fragments-base.rb'
+
+Cumuliform.template do
+  import FragmentBaseTemplate
+
+  def_fragment(:instance_type) do |opts|
+    parameter 'InstanceType' do
+      {
+        Description: 'InstanceType',
+        Type: 'String',
+        Default: opts[:type],
+        AllowedValues: ['m3.medium', 'm4.large', 'm4.xlarge']
+      }
+    end
+  end
+
+  fragment(:instance_type, type: 'm3.medium')
+end

data/examples/import-importer.rb

@@ -0,0 +1,13 @@
+require_relative './import-base.rb'
+
+Cumuliform.template do
+  import BaseTemplate
+
+  parameter 'AMI' do
+    {
+      Description: 'A different AMI',
+      Type: 'String',
+      Default: 'ami-DIFFERENT'
+    }
+  end
+end

data/examples/module-helper.rb

@@ -0,0 +1,19 @@
+module AmiHelper
+  def ami
+    'ami-accff2b1'
+  end
+end
+
+Cumuliform.template do
+  helpers AmiHelper
+
+  resource 'MyInstance' do
+    {
+      Type: 'AWS::EC2::Instance',
+      Properties: {
+        ImageId: ami,
+        InstanceType: 'm3.medium'
+      }
+    }
+  end
+end

data/lib/cumuliform.rb

@@ -1,96 +1,4 @@
 # Simple AWS CloudFormation. Doesn't try to run the commands, doesn't try to
 # DSLize every last thing. Simple is the watch word
 
-require 'json'
-require 'set'
-require_relative 'cumuliform/error'
-require_relative 'cumuliform/fragments'
-require_relative 'cumuliform/functions'
-require_relative 'cumuliform/import'
-require_relative 'cumuliform/output'
-
-module Cumuliform
-  AWS_PSEUDO_PARAMS = %w{
-      AWS::AccountId AWS::NotificationARNs AWS::NoValue
-      AWS::Region AWS::StackId AWS::StackName
-  }
-  SECTIONS = {
-    "Parameters" => :parameter,
-    "Mappings" => :mapping,
-    "Conditions" => :condition,
-    "Resources" => :resource,
-    "Outputs" => :output
-  }
-
-  def self.template(&block)
-    template = Template.new
-    template.define(&block)
-  end
-
-  class Template
-    include Import
-    include Fragments
-    include Functions
-    include Output
-
-    def initialize
-      SECTIONS.each do |section_name, _|
-        instance_variable_set(:"@#{section_name}", Section.new(section_name, imports))
-      end
-    end
-
-    def helpers(*mods, &block)
-      if block_given?
-        mods << Module.new(&block)
-      end
-      mods.each do |mod|
-        self.class.include mod
-      end
-    end
-
-    def define(&block)
-      instance_exec(&block)
-      self
-    end
-
-    def logical_ids
-      @logical_ids ||= Set.new(AWS_PSEUDO_PARAMS)
-    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 has_local_logical_id?(logical_id)
-      logical_ids.include?(logical_id)
-    end
-
-    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
+require_relative 'cumuliform/dsl'

data/lib/cumuliform/dsl.rb

@@ -0,0 +1,32 @@
+require_relative 'template'
+require_relative 'dsl/fragments'
+require_relative 'dsl/functions'
+require_relative 'dsl/import'
+require_relative 'dsl/helpers'
+
+# Cumuliform is a simple tool for generating AWS CloudFormation templates. It's
+# concerned with making it easier and less error-prone to write templates by
+# providing features that verify references at template generation time, rather
+# than waiting for failures in stack creation. It also allows you to define and
+# reuse template fragments within one template, and between many templates.
+module Cumuliform
+  # Create a new template from the passed-in block
+  #
+  # @param block the template body
+  # @return [Template]
+  def self.template(&block)
+    template = Template.new
+    template.define(&block)
+  end
+
+  # The DSL modules contain all of the public DSL methods you'll use in your templates
+  module DSL
+  end
+
+  class Template
+    include DSL::Import
+    include DSL::Fragments
+    include DSL::Functions
+    include DSL::Helpers
+  end
+end

data/lib/cumuliform/dsl/fragments.rb

@@ -0,0 +1,67 @@
+require_relative '../error'
+
+module Cumuliform
+  module DSL
+    # DSL methods for creating and reusing template fragments
+    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
+end

data/lib/cumuliform/dsl/functions.rb

@@ -0,0 +1,256 @@
+require_relative '../error'
+
+module Cumuliform
+  module DSL
+    # DSL methods for working with CloudFormation Intrinsic and Ref functions
+    module Functions
+      # implements wrappers for the intrinsic functions Fn::*
+      class IntrinsicFunctions
+        # @api private
+        attr_reader :template
+
+        # @api private
+        def initialize(template)
+          @template = template
+        end
+
+        # Wraps Fn::FindInMap
+        #
+        # see http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-findinmap.html
+        #
+        # @param mapping_logical_id [String] The logical ID of the mapping we
+        #   want to look up a value from
+        # @param level_1_key [String] Key 1
+        # @param level_2_key [String] Key 2
+        # @return [Hash] the Fn::FindInMap object
+        def find_in_map(mapping_logical_id, level_1_key, level_2_key)
+          template.verify_mapping_logical_id!(mapping_logical_id)
+          {"Fn::FindInMap" => [mapping_logical_id, level_1_key, level_2_key]}
+        end
+
+        # Wraps Fn::GetAtt
+        #
+        # see http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html
+        #
+        # @param resource_logical_id [String] The Logical ID of resource we
+        #   want to get an attribute of
+        # @param attr_name [String] The name of the attribute to get the value
+        #   of
+        # @return [Hash] the Fn::GetAtt object
+        def get_att(resource_logical_id, attr_name)
+          template.verify_resource_logical_id!(resource_logical_id)
+          {"Fn::GetAtt" => [resource_logical_id, attr_name]}
+        end
+
+        # Wraps Fn::Join
+        #
+        # see http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-join.html
+        #
+        # @param separator [String] The separator string to join the array
+        #   elements with
+        # @param args [Array<String>] The array of strings to join
+        # @return [Hash] the Fn::Join object
+        def join(separator, args)
+          raise ArgumentError, "Second argument must be an Array" unless args.is_a?(Array)
+          {"Fn::Join" => [separator, args]}
+        end
+
+        # Wraps Fn::Base64
+        #
+        # see http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-base64.html
+        #
+        # The argument should either be a string or an intrinsic function that
+        # evaluates to a string when CloudFormation executes the template
+        #
+        # see http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-base64.html
+        #
+        # @param value [String, Hash<string-returning instrinsic function>] The
+        #   separator string to join the array  elements with
+        # @return [Hash] the Fn::Base64 object
+        def base64(value)
+          {"Fn::Base64" => value}
+        end
+
+        # Wraps Fn::GetAZs
+        #
+        # CloudFormation evaluates this to an array of availability zone names.
+        #
+        # see http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getavailabilityzones.html
+        #
+        # @param value [String, Hash<ref('AWS::Region')>] The AWS region to get
+        #   the array of Availability Zones of. Empty string (the default) is
+        #   equivalent to specifying `ref('AWS::Region')` which evaluates to
+        #   the region the stack is being created in
+        # @return [Hash] the Fn::GetAZs object
+        def get_azs(value = "")
+          {"Fn::GetAZs" => value}
+        end
+
+        # Wraps Fn::Equals
+        #
+        # see http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e86148
+        #
+        # The arguments should be the literal values or refs you want to
+        # compare. Returns true or false when CloudFormation evaluates the
+        # template.
+        #
+        # @param value [String, Hash<value-returning ref>]
+        # @param other_value [String, Hash<value-returning ref>]
+        # @return [Hash] the Fn::Equals object
+        def equals(value, other_value)
+          {"Fn::Equals" => [value, other_value]}
+        end
+
+        # Wraps Fn::If
+        #
+        # see http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e86223
+        #
+        # CloudFormation evaluates the Condition referred to the logical ID in
+        # the <tt>condition</tt> arg and returns the <tt>true_value</tt> if
+        # <tt>true</tt> and <tt>false_value</tt> otherwise. <tt>condition</tt>
+        # cannot be an <tt>Fn::Ref</tt>, but you can use our <tt>xref()</tt>
+        # helper to ensure the logical ID is valid.
+        #
+        # @param condition[String] the Logical ID of the Condition to be
+        #   checked
+        # @param true_value the value to be returned if <tt>condition</tt>
+        #   evaluates true
+        # @param false_value the value to be returned if <tt>condition</tt>
+        #   evaluates false
+        # @return [Hash] the Fn::If object
+        def if(condition, true_value, false_value)
+          {"Fn::If" => [condition, true_value, false_value]}
+        end
+
+        # Wraps Fn::Select
+        #
+        # see
+        # http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-select.html
+        #
+        # CloudFormation evaluates the <tt>index</tt> (which can be an
+        # integer-as-a-string or a <tt>ref</tt> which evaluates to a number)
+        # and returns the corresponding item from the array (which can be an
+        # array literal, or the result of <tt>Fn::GetAZs</tt>, or one of
+        # <tt>Fn::GetAtt</tt>, <tt>Fn::If</tt>, and <tt>Ref</tt> (if they would
+        # return an Array).
+        #
+        # @param index [Integer, Hash<value-returning ref>] The index to
+        #   retrieve from <tt>array</tt>
+        # @param array [Array, Hash<array-returning ref of intrinsic function>]
+        #   The array to retrieve from
+        # @return [Hash] the Fn::Select object
+        def select(index, array)
+          ref_style_index = index.is_a?(Hash) && index.has_key?("Fn::Ref")
+          positive_int_style_index = index.is_a?(Integer) && index >= 0
+          unless ref_style_index || positive_int_style_index
+            raise ArgumentError, "index must be a positive integer or Fn::Ref"
+          end
+          if positive_int_style_index
+            if array.is_a?(Array) && index >= array.length
+              raise IndexError, "index must be in the range 0 <= index < array.length"
+            end
+            index = index.to_s
+          end
+          {"Fn::Select" => [index, array]}
+        end
+
+        # Wraps Fn::And
+        #
+        # see
+        # http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e86066
+        #
+        # Behaves as a logical AND operator for CloudFormation conditions.
+        # Arguments should be other conditions or things that will evaluate to
+        # <tt>true</tt> or <tt>false</tt>.
+        #
+        # @overload and(condition_1, ..., condition_n)
+        #   @param condition_1 [Hash<boolean-returning ref, intrinsic function,
+        #     or condition>] Condition / value to be ANDed
+        #   @param condition_n [Hash<boolean-returning ref, intrinsic function,
+        #     or condition>] Condition / value to be ANDed (min 2, max 10
+        #     condition args)
+        # @return [Hash] the Fn::And object
+        def and(*conditions)
+          unless (2..10).cover?(conditions.length)
+            raise ArgumentError, "You must specify AT LEAST 2 and AT MOST 10 conditions"
+          end
+          {"Fn::And" => conditions}
+        end
+
+        # Wraps Fn::Or
+        #
+        # see
+        # http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e86490
+        #
+        # Behaves as a logical OR operator for CloudFormation conditions.
+        # Arguments should be other conditions or things that will evaluate to
+        # <tt>true</tt> or <tt>false</tt>.
+        #
+        # @overload or(condition_1, ..., condition_n)
+        #   @param condition_1 [Hash<boolean-returning ref, intrinsic function,
+        #     or condition>] Condition / value to be ORed
+        #   @param condition_n [Hash<boolean-returning ref, intrinsic function,
+        #     or condition>] Condition / value to be ORed (min 2, max 10
+        #     condition args)
+        # @return [Hash] the Fn::Or object
+        def or(*conditions)
+          unless (2..10).cover?(conditions.length)
+            raise ArgumentError, "You must specify AT LEAST 2 and AT MOST 10 conditions"
+          end
+          {"Fn::Or" => conditions}
+        end
+
+        # Wraps Fn::Not
+        #
+        # see
+        # http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#d0e86402
+        #
+        # Behaves as a logical NOT operator for CloudFormation conditions. The
+        # argument should be another condition or something that will evaluate
+        # to <tt>true</tt> or <tt>false</tt>
+        #
+        # @param condition [Hash<boolean-returning ref, intrinsic function, or
+        #   condition>] Condition / value to be NOTed
+        # @return [Hash] the Fn::Not object
+        def not(condition)
+          {"Fn::Not" => [condition]}
+        end
+      end
+
+      # Checks <tt>logical_id</tt> is present and either returns
+      # <tt>logical_id</tt> or raises Cumuliform::Error::NoSuchLogicalId.
+      #
+      # You can use it anywhere you need a string Logical ID and want the
+      # protection of having it be verified, for example in the
+      # <tt>cfn-init</tt> invocation in a Cfn::Init metadata block or the
+      # condition name field of, e.g. Fn::And.
+      #
+      # @param logical_id [String] the logical ID you want to check
+      # @return [String] the logical_id param
+      def xref(logical_id)
+        unless has_logical_id?(logical_id)
+          raise Error::NoSuchLogicalId, logical_id
+        end
+        logical_id
+      end
+
+      # Wraps Ref
+      #
+      # CloudFormation evaluates the <tt>Ref</tt> and returns the value of the
+      # Parameter or Resource with Logical ID <tt>logical_id</tt>.
+      #
+      # @param logical_id [String] The logical ID of the parameter or resource
+      # @return [Hash] the Ref object
+      def ref(logical_id)
+        {"Ref" => xref(logical_id)}
+      end
+
+      # returns an instance of IntrinsicFunctions which provides wrappers for
+      # Fn::* functions
+      # @return [IntrinsicFunctions] the DSL wrapper
+      def fn
+        @fn ||= IntrinsicFunctions.new(self)
+      end
+    end
+  end
+end