cumuliform 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dc898679239945b8548cd8b35fac0135ca1c07d4
-  data.tar.gz: 5e5996b0de7f64ba2deb495dcf306374af28947c
+  metadata.gz: abff1bdeb60a617a79f889e191789cc21dee2335
+  data.tar.gz: 8320b16dd011e3155aaeef164a4dce008634e46d
 SHA512:
-  metadata.gz: a1de59e26464fb7370af9cdac344ba606ababdc27ec608d0324cf976352c4eded31b1e78731d4ed40c4282029deb0f3b15b3e42a96e70d9c06bb782c310100a9
-  data.tar.gz: 5511163114e278987878e18844961a03fd8223fb6e20d328bc1653a194c87f3955ec9b5f74257b49f4fbfcb0561a91adecc0fddebe7fac956d07176bc92c0f3a
+  metadata.gz: 49b1742f90f29be0daacbd3c452cdda449100bc452ec831466661639c8fc28402e2cbdf833a04c5d4cecf1eeee97e4ccd03bf4717943032a4eb2813c407df54c
+  data.tar.gz: 20147ec9d4c9790d2ac5fc5fb78c5f3126582e2ed7c86c698be3bf25b6b7cf49bc625759e7a2e07d93309510fc1dba25f714ca1a2dc573e53eb514cce13f26f4

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [0.5.1] - 2015-12-03
+### Changed
+- Make some fragment-related functions private
+
+### Deprecate
+- Deprecate fragment definition use of `fragment()`: use `def_fragment()` for
+  that instead
+
+### Added
+- Add `def_fragment()` replacement for overloaded fragment-definition use of
+  `fragment()`
+- Better API doc and examples for intrinsic functions
+- API doc and examples for fragments
+
+## [0.5.0] - 2015-12-03
+Yanked - implemented 0.5.1's changes in a breaking way rather than deprecating
+
+## [0.4.0] - 2015-06-10
+### Added
+- Add example to README
+- Add command-line runner
+- Add Rake task class
+
+## [0.3.0] - 2015-05-27
+### Added
+- Initial public release covering all the basics (missing a couple of intrinsic
+  functions)

data/README.md

@@ -1,6 +1,6 @@
 # Cumuliform
 
-[![Build Status](https://travis-ci.org/tape-tv/cumuliform.svg?branch=master)](https://travis-ci.org/tape-tv/cumuliform) [![Code Climate](https://codeclimate.com/github/tape-tv/cumuliform/badges/gpa.svg)](https://codeclimate.com/github/tape-tv/cumuliform) [![Test Coverage](https://codeclimate.com/github/tape-tv/cumuliform/badges/coverage.svg)](https://codeclimate.com/github/tape-tv/cumuliform/coverage)
+[![Gem Version](https://badge.fury.io/rb/cumuliform.svg)](http://badge.fury.io/rb/cumuliform) [![Build Status](https://travis-ci.org/tape-tv/cumuliform.svg?branch=master)](https://travis-ci.org/tape-tv/cumuliform) [![Code Climate](https://codeclimate.com/github/tape-tv/cumuliform/badges/gpa.svg)](https://codeclimate.com/github/tape-tv/cumuliform) [![Test Coverage](https://codeclimate.com/github/tape-tv/cumuliform/badges/coverage.svg)](https://codeclimate.com/github/tape-tv/cumuliform/coverage)
 
 Amazon’s [CloudFormation AWS service][cf] provides a way to describe
 infrastructure stacks using a JSON template. We love CloudFormation, and use it
@@ -120,6 +120,8 @@ $ cumuliform simplest.rb simplest.cform
 }
 ```
 
+More detailed examples are below the section on Rake...
+
 # Rake tasks and the Command Line runner
 
 Cumuliform provides a very simple command-line runner to turn a `.rb` template
@@ -165,6 +167,617 @@ TARGETS = Rake::FileList['*.rb'].ext('.cform')
 task :cform => TARGETS
 ```
 
+# Examples
+
+## Simple top-level object declarations
+
+This example declares one of each of the top level objects Cumuliform
+supports. More details can be found in CloudFormation's [Template
+Anatomy documentation][cf-ta].
+
+[cf-ta]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html
+
+```ruby
+Cumuliform.template do
+  # See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html
+  parameter 'AMI' do
+    {
+      Description: 'The AMI id for our template (defaults to the stock Ubuntu 14.04 image in eu-central-1)',
+      Type: 'String',
+      Default: 'ami-accff2b1'
+    }
+  end
+
+  # See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html
+  mapping 'RegionAMI' do
+    {
+      'eu-central-1' => {
+        'hvm' => 'ami-accff2b1',
+        'pv' => 'ami-b6cff2ab'
+      },
+      'eu-west-1' => {
+        'hvm' => 'ami-47a23a30',
+        'pv' => 'ami-5da23a2a'
+      }
+    }
+  end
+
+  # See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html
+  condition 'Ireland' do
+    fn.equals(ref('AWS::Region'), 'eu-west-1')
+  end
+
+  # See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html
+  resource 'PrimaryInstance' do
+    {
+      Type: 'AWS::EC2::Instance',
+      Properties: {
+        ImageId: ref('AMI'),
+        InstanceType: 'm3.medium'
+      }
+    }
+  end
+
+  # See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html
+  output 'PrimaryInstanceID' do
+    {
+      Value: ref('PrimaryInstance')
+    }
+  end
+end
+```
+
+The generated template is:
+
+```json
+{
+  "Parameters": {
+    "AMI": {
+      "Description": "The AMI id for our template (defaults to the stock Ubuntu 14.04 image in eu-central-1)",
+      "Type": "String",
+      "Default": "ami-accff2b1"
+    }
+  },
+  "Mappings": {
+    "RegionAMI": {
+      "eu-central-1": {
+        "hvm": "ami-accff2b1",
+        "pv": "ami-b6cff2ab"
+      },
+      "eu-west-1": {
+        "hvm": "ami-47a23a30",
+        "pv": "ami-5da23a2a"
+      }
+    }
+  },
+  "Conditions": {
+    "Ireland": {
+      "Fn::Equals": [
+        {
+          "Ref": "AWS::Region"
+        },
+        "eu-west-1"
+      ]
+    }
+  },
+  "Resources": {
+    "PrimaryInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "ImageId": {
+          "Ref": "AMI"
+        },
+        "InstanceType": "m3.medium"
+      }
+    }
+  },
+  "Outputs": {
+    "PrimaryInstanceID": {
+      "Value": {
+        "Ref": "PrimaryInstance"
+      }
+    }
+  }
+}
+```
+
+Note that the optional `AWSTemplateFormatVersion`, `Description`, and
+`Metadata` sections are *not* currently supported.
+
+## Intrinsic functions
+
+Cumuliform provides convenience wrappers for all the intrinsic functions. See
+CloudFormation's [Intrinsic Function documentation][cf-if].
+
+[cf-if]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html
+
+```ruby
+Cumuliform.template do
+  mapping 'RegionAMI' do
+    {
+      'eu-central-1' => {
+        'hvm' => 'ami-accff2b1',
+        'pv' => 'ami-b6cff2ab'
+      },
+      'eu-west-1' => {
+        'hvm' => 'ami-47a23a30',
+        'pv' => 'ami-5da23a2a'
+      }
+    }
+  end
+
+  parameter 'VirtualizationMethod' do
+    {
+      Type: 'String',
+      Default: 'hvm'
+    }
+  end
+
+  resource 'PrimaryInstance' do
+    {
+      Type: 'AWS::EC2::Instance',
+      Properties: {
+        ImageId: fn.find_in_map('RegionAMI', ref('AWS::Region'),
+                                ref('VirtualizationMethod')),
+        InstanceType: 'm3.medium',
+        AvailabilityZone: fn.select(0, fn.get_azs),
+        UserData: fn.base64(
+          fn.join('', [
+            "#!/bin/bash -xe\n",
+            "apt-get update\n",
+            "apt-get -y install python-pip python-docutils\n",
+            "pip install https://s3.amazonaws.com/cloudformation-examples/aws-cfn-bootstrap-latest.tar.gz\n",
+            "/usr/local/bin/cfn-init",
+            " --region ", ref("AWS::Region"),
+            " --stack ", ref("AWS::StackId"),
+            " --resource #{xref('PrimaryInstance')}",
+            " --configsets db"
+          ])
+        ),
+        Metadata: {
+          'AWS::CloudFormation::Init' => {
+            configSets: { db: ['install'] },
+            install: {
+              commands: {
+                '01-apt' => {
+                  command: 'apt-get install postgresql postgresql-contrib'
+                },
+                '02-db' => {
+                  command: 'sudo -u postgres createdb the-db'
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  end
+
+  resource 'SiteDNS' do
+    {
+      Type: "AWS::Route53::RecordSet",
+      Properties: {
+        HostedZoneName: 'my-zone.example.org',
+        Name: 'service.my-zone.example.org',
+        ResourceRecords: [fn.get_att(xref('LoadBalancer'), 'DNSName')],
+        TTL: '900',
+        Type: 'CNAME'
+      }
+    }
+  end
+
+  resource 'LoadBalancer' do
+    {
+      Type: 'AWS::ElasticLoadBalancing::LoadBalancer',
+      Properties: {
+        AvailabilityZones: [fn.select(0, fn.get_azs)],
+        Listeners: [
+          {
+            InstancePort: 5432,
+            Protocol: 'TCP'
+          }
+        ],
+        Instances: [ref('PrimaryInstance')]
+      }
+    }
+  end
+end
+```
+
+The generated template is:
+
+```json
+{
+  "Parameters": {
+    "VirtualizationMethod": {
+      "Type": "String",
+      "Default": "hvm"
+    }
+  },
+  "Mappings": {
+    "RegionAMI": {
+      "eu-central-1": {
+        "hvm": "ami-accff2b1",
+        "pv": "ami-b6cff2ab"
+      },
+      "eu-west-1": {
+        "hvm": "ami-47a23a30",
+        "pv": "ami-5da23a2a"
+      }
+    }
+  },
+  "Resources": {
+    "PrimaryInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "ImageId": {
+          "Fn::FindInMap": [
+            "RegionAMI",
+            {
+              "Ref": "AWS::Region"
+            },
+            {
+              "Ref": "VirtualizationMethod"
+            }
+          ]
+        },
+        "InstanceType": "m3.medium",
+        "AvailabilityZone": {
+          "Fn::Select": [
+            "0",
+            {
+              "Fn::GetAZs": ""
+            }
+          ]
+        },
+        "UserData": {
+          "Fn::Base64": {
+            "Fn::Join": [
+              "",
+              [
+                "#!/bin/bash -xe\n",
+                "apt-get update\n",
+                "apt-get -y install python-pip python-docutils\n",
+                "pip install https://s3.amazonaws.com/cloudformation-examples/aws-cfn-bootstrap-latest.tar.gz\n",
+                "/usr/local/bin/cfn-init",
+                " --region ",
+                {
+                  "Ref": "AWS::Region"
+                },
+                " --stack ",
+                {
+                  "Ref": "AWS::StackId"
+                },
+                " --resource PrimaryInstance",
+                " --configsets db"
+              ]
+            ]
+          }
+        },
+        "Metadata": {
+          "AWS::CloudFormation::Init": {
+            "configSets": {
+              "db": [
+                "install"
+              ]
+            },
+            "install": {
+              "commands": {
+                "01-apt": {
+                  "command": "apt-get install postgresql postgresql-contrib"
+                },
+                "02-db": {
+                  "command": "sudo -u postgres createdb the-db"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "SiteDNS": {
+      "Type": "AWS::Route53::RecordSet",
+      "Properties": {
+        "HostedZoneName": "my-zone.example.org",
+        "Name": "service.my-zone.example.org",
+        "ResourceRecords": [
+          {
+            "Fn::GetAtt": [
+              "LoadBalancer",
+              "DNSName"
+            ]
+          }
+        ],
+        "TTL": "900",
+        "Type": "CNAME"
+      }
+    },
+    "LoadBalancer": {
+      "Type": "AWS::ElasticLoadBalancing::LoadBalancer",
+      "Properties": {
+        "AvailabilityZones": [
+          {
+            "Fn::Select": [
+              "0",
+              {
+                "Fn::GetAZs": ""
+              }
+            ]
+          }
+        ],
+        "Listeners": [
+          {
+            "InstancePort": 5432,
+            "Protocol": "TCP"
+          }
+        ],
+        "Instances": [
+          {
+            "Ref": "PrimaryInstance"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Condition functions
+
+Cumuliform provides convenience wrappers for all the Condition-related intrinsic functions. See
+CloudFormation's [Condition Function documentation][cf-cif].
+
+[cf-cif]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html
+
+```ruby
+Cumuliform.template do
+  parameter 'AMI' do
+    {
+      Type: 'String',
+      Default: 'ami-12345678'
+    }
+  end
+
+  parameter 'UtilAMI' do
+    {
+      Type: 'String',
+      Default: 'ami-abcdef12'
+    }
+  end
+
+  parameter 'InstanceType' do
+    {
+      Description: "The instance type",
+      Type: 'String',
+      Default: 'c4.large'
+    }
+  end
+
+  condition 'InEU' do
+    fn.or(
+      fn.equals('eu-central-1', ref('AWS::Region')),
+      fn.equals('eu-west-1', ref('AWS::Region'))
+    )
+  end
+
+  condition 'UtilBox' do
+    fn.and(
+      fn.equals('m4.large', ref('InstanceType')),
+      {"Condition": xref('InEU')}
+    )
+  end
+
+  condition 'WebBox' do
+    fn.not(ref('UtilBox'))
+  end
+
+  resource 'WebInstance' do
+    {
+      Type: "AWS::EC2::Instance",
+      Condition: xref('WebBox'),
+      Properties: {
+        ImageId: ref('AMI'),
+        InstanceType: ref('InstanceType')
+      }
+    }
+  end
+
+  resource 'UtilInstance' do
+    {
+      Type: "AWS::EC2::Instance",
+      Condition: xref('UtilBox'),
+      Properties: {
+        ImageId: ref('UtilAMI'),
+        InstanceType: ref('InstanceType')
+      }
+    }
+  end
+end
+```
+
+The generated template is:
+
+```json
+{
+  "Parameters": {
+    "AMI": {
+      "Type": "String",
+      "Default": "ami-12345678"
+    },
+    "UtilAMI": {
+      "Type": "String",
+      "Default": "ami-abcdef12"
+    },
+    "InstanceType": {
+      "Description": "The instance type",
+      "Type": "String",
+      "Default": "c4.large"
+    }
+  },
+  "Conditions": {
+    "InEU": {
+      "Fn::Or": [
+        {
+          "Fn::Equals": [
+            "eu-central-1",
+            {
+              "Ref": "AWS::Region"
+            }
+          ]
+        },
+        {
+          "Fn::Equals": [
+            "eu-west-1",
+            {
+              "Ref": "AWS::Region"
+            }
+          ]
+        }
+      ]
+    },
+    "UtilBox": {
+      "Fn::And": [
+        {
+          "Fn::Equals": [
+            "m4.large",
+            {
+              "Ref": "InstanceType"
+            }
+          ]
+        },
+        {
+          "Condition": "InEU"
+        }
+      ]
+    },
+    "WebBox": {
+      "Fn::Not": [
+        {
+          "Ref": "UtilBox"
+        }
+      ]
+    }
+  },
+  "Resources": {
+    "WebInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Condition": "WebBox",
+      "Properties": {
+        "ImageId": {
+          "Ref": "AMI"
+        },
+        "InstanceType": {
+          "Ref": "InstanceType"
+        }
+      }
+    },
+    "UtilInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Condition": "UtilBox",
+      "Properties": {
+        "ImageId": {
+          "Ref": "UtilAMI"
+        },
+        "InstanceType": {
+          "Ref": "InstanceType"
+        }
+      }
+    }
+  }
+}
+```
+
+### xref
+Quite often you'll need to use a Resource, Condition, or Parameter Logical ID
+outside of a `{ "Ref" => "LogicalID" }`. Because Logical IDs are one of the
+things we *can* check at evaluation time, we provide a function that simply
+takes a Logical ID, checks it, then returns it. If the Logical ID isn't there
+then it explodes with a `Cumuliform::Error::NoSuchLogicalId`.
+
+```ruby
+resource "Resource" do
+  {
+    Type: "AWS::EC2::Instance",
+    Condition: xref("TheCondition")
+  }
+end
+```
+
+## Fragments
+You'll often want to use a collection of resources several times in a template, and it can be pretty verbose and tedious. Cumuliform offers reusable fragments to allow you to reuse similar template chunks.
+
+You define them with `def_fragment()` and use them with `fragment()`. You pass a name and a block to `def_fragment`. You call `fragment()` with the name of a fragment and an optional hash of options to pass to the fragment block. The fragment block is called and its return value output into the template.
+
+Here's an example:
+
+```ruby
+Cumuliform.template do
+  parameter 'AMI' do
+    {
+      Description: 'The AMI id for our template (defaults to the stock Ubuntu 14.04 image in eu-central-1)',
+      Type: 'String',
+      Default: 'ami-accff2b1'
+    }
+  end
+
+  def_fragment(:instance) do |opts|
+    resource opts[:logical_id] do
+      {
+        Type: 'AWS::EC2::Instance',
+        Properties: {
+          ImageId: ref('AMI'),
+          InstanceType: opts[:instance_type]
+        }
+      }
+    end
+  end
+
+  fragment(:instance, logical_id: 'LittleInstance', instance_type: 't2.micro')
+  fragment(:instance, logical_id: 'BigInstance', instance_type: 'c4.xlarge')
+end
+```
+
+And the output:
+
+```json
+{
+  "Parameters": {
+    "AMI": {
+      "Description": "The AMI id for our template (defaults to the stock Ubuntu 14.04 image in eu-central-1)",
+      "Type": "String",
+      "Default": "ami-accff2b1"
+    }
+  },
+  "Resources": {
+    "LittleInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "ImageId": {
+          "Ref": "AMI"
+        },
+        "InstanceType": "t2.micro"
+      }
+    },
+    "BigInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "ImageId": {
+          "Ref": "AMI"
+        },
+        "InstanceType": "c4.xlarge"
+      }
+    }
+  }
+}
+```
+
+## Importing other templates
+_TODO_
+
+## Helpers
+_TODO_
+
+
 # Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/Rakefile

@@ -14,4 +14,5 @@ require 'cumuliform/rake_task'
 
 Cumuliform::RakeTask.rule(".cform" => ".rb")
 
+desc "Generate JSON from example templates"
 task :examples => EXAMPLE_TARGETS

data/cumuliform.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = %q{DSL library for generating AWS CloudFormation templates}
   spec.description   = <<-EOD
-Simple DSL for generation AWS CloudFormation templates with an emphasis
+Simple DSL for generating AWS CloudFormation templates with an emphasis
 on ensuring you don't shoot yourself in the foot by, e.g. referencing
 non-existent resources because you have a typo.
   EOD
@@ -26,4 +26,5 @@ non-existent resources because you have a typo.
   spec.add_development_dependency "bundler", "~> 1.9"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3"
+  spec.add_development_dependency "yard", ">= 0.8"
 end

data/examples/condition_functions.rb

@@ -0,0 +1,63 @@
+Cumuliform.template do
+  parameter 'AMI' do
+    {
+      Type: 'String',
+      Default: 'ami-12345678'
+    }
+  end
+
+  parameter 'UtilAMI' do
+    {
+      Type: 'String',
+      Default: 'ami-abcdef12'
+    }
+  end
+
+  parameter 'InstanceType' do
+    {
+      Description: "The instance type",
+      Type: 'String',
+      Default: 'c4.large'
+    }
+  end
+
+  condition 'InEU' do
+    fn.or(
+      fn.equals('eu-central-1', ref('AWS::Region')),
+      fn.equals('eu-west-1', ref('AWS::Region'))
+    )
+  end
+
+  condition 'UtilBox' do
+    fn.and(
+      fn.equals('m4.large', ref('InstanceType')),
+      {"Condition": xref('InEU')}
+    )
+  end
+
+  condition 'WebBox' do
+    fn.not(ref('UtilBox'))
+  end
+
+  resource 'WebInstance' do
+    {
+      Type: "AWS::EC2::Instance",
+      Condition: xref('WebBox'),
+      Properties: {
+        ImageId: ref('AMI'),
+        InstanceType: ref('InstanceType')
+      }
+    }
+  end
+
+  resource 'UtilInstance' do
+    {
+      Type: "AWS::EC2::Instance",
+      Condition: xref('UtilBox'),
+      Properties: {
+        ImageId: ref('UtilAMI'),
+        InstanceType: ref('InstanceType')
+      }
+    }
+  end
+end

data/examples/fragments.rb

@@ -0,0 +1,24 @@
+Cumuliform.template do
+  parameter 'AMI' do
+    {
+      Description: 'The AMI id for our template (defaults to the stock Ubuntu 14.04 image in eu-central-1)',
+      Type: 'String',
+      Default: 'ami-accff2b1'
+    }
+  end
+
+  def_fragment(:instance) do |opts|
+    resource opts[:logical_id] do
+      {
+        Type: 'AWS::EC2::Instance',
+        Properties: {
+          ImageId: ref('AMI'),
+          InstanceType: opts[:instance_type]
+        }
+      }
+    end
+  end
+
+  fragment(:instance, logical_id: 'LittleInstance', instance_type: 't2.micro')
+  fragment(:instance, logical_id: 'BigInstance', instance_type: 'c4.xlarge')
+end

data/examples/intrinsic_functions.rb

@@ -0,0 +1,90 @@
+Cumuliform.template do
+  mapping 'RegionAMI' do
+    {
+      'eu-central-1' => {
+        'hvm' => 'ami-accff2b1',
+        'pv' => 'ami-b6cff2ab'
+      },
+      'eu-west-1' => {
+        'hvm' => 'ami-47a23a30',
+        'pv' => 'ami-5da23a2a'
+      }
+    }
+  end
+
+  parameter 'VirtualizationMethod' do
+    {
+      Type: 'String',
+      Default: 'hvm'
+    }
+  end
+
+  resource 'PrimaryInstance' do
+    {
+      Type: 'AWS::EC2::Instance',
+      Properties: {
+        ImageId: fn.find_in_map('RegionAMI', ref('AWS::Region'),
+                                ref('VirtualizationMethod')),
+        InstanceType: 'm3.medium',
+        AvailabilityZone: fn.select(0, fn.get_azs),
+        UserData: fn.base64(
+          fn.join('', [
+            "#!/bin/bash -xe\n",
+            "apt-get update\n",
+            "apt-get -y install python-pip python-docutils\n",
+            "pip install https://s3.amazonaws.com/cloudformation-examples/aws-cfn-bootstrap-latest.tar.gz\n",
+            "/usr/local/bin/cfn-init",
+            " --region ", ref("AWS::Region"),
+            " --stack ", ref("AWS::StackId"),
+            " --resource #{xref('PrimaryInstance')}",
+            " --configsets db"
+          ])
+        ),
+        Metadata: {
+          'AWS::CloudFormation::Init' => {
+            configSets: { db: ['install'] },
+            install: {
+              commands: {
+                '01-apt' => {
+                  command: 'apt-get install postgresql postgresql-contrib'
+                },
+                '02-db' => {
+                  command: 'sudo -u postgres createdb the-db'
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  end
+
+  resource 'SiteDNS' do
+    {
+      Type: "AWS::Route53::RecordSet",
+      Properties: {
+        HostedZoneName: 'my-zone.example.org',
+        Name: 'service.my-zone.example.org',
+        ResourceRecords: [fn.get_att(xref('LoadBalancer'), 'DNSName')],
+        TTL: '900',
+        Type: 'CNAME'
+      }
+    }
+  end
+
+  resource 'LoadBalancer' do
+    {
+      Type: 'AWS::ElasticLoadBalancing::LoadBalancer',
+      Properties: {
+        AvailabilityZones: [fn.select(0, fn.get_azs)],
+        Listeners: [
+          {
+            InstancePort: 5432,
+            Protocol: 'TCP'
+          }
+        ],
+        Instances: [ref('PrimaryInstance')]
+      }
+    }
+  end
+end

data/examples/top-level-declarations.rb

@@ -0,0 +1,47 @@
+Cumuliform.template do
+  # See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html
+  parameter 'AMI' do
+    {
+      Description: 'The AMI id for our template (defaults to the stock Ubuntu 14.04 image in eu-central-1)',
+      Type: 'String',
+      Default: 'ami-accff2b1'
+    }
+  end
+
+  # See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html
+  mapping 'RegionAMI' do
+    {
+      'eu-central-1' => {
+        'hvm' => 'ami-accff2b1',
+        'pv' => 'ami-b6cff2ab'
+      },
+      'eu-west-1' => {
+        'hvm' => 'ami-47a23a30',
+        'pv' => 'ami-5da23a2a'
+      }
+    }
+  end
+
+  # See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html
+  condition 'Ireland' do
+    fn.equals(ref('AWS::Region'), 'eu-west-1')
+  end
+
+  # See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html
+  resource 'PrimaryInstance' do
+    {
+      Type: 'AWS::EC2::Instance',
+      Properties: {
+        ImageId: ref('AMI'),
+        InstanceType: 'm3.medium'
+      }
+    }
+  end
+
+  # See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html
+  output 'PrimaryInstanceID' do
+    {
+      Value: ref('PrimaryInstance')
+    }
+  end
+end

data/lib/cumuliform/fragments.rb

@@ -2,18 +2,39 @@ require_relative 'error'
 
 module Cumuliform
   module Fragments
-    def fragments
-      @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?
-        define_fragment(name, block)
+        warn "fragment definition form (with block) is deprecated. Use #def_fragment instead"
+        def_fragment(name, *args, &block)
       else
-        include_fragment(name, *args)
+        use_fragment(name, *args)
       end
     end
 
+    # @api private
     def find_fragment(name)
       local_fragment = fragments[name]
       imports.reverse.reduce(local_fragment) { |fragment, import|
@@ -21,24 +42,22 @@ module Cumuliform
       }
     end
 
-    def has_fragment?(name)
-      !find_fragment(name).nil?
-    end
-
     private
 
-    def define_fragment(name, block)
-      if fragments.has_key?(name)
-        raise Error::FragmentAlreadyDefined, name
-      end
-      fragments[name] = block
-    end
-
-    def include_fragment(name, opts = {})
+    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

data/lib/cumuliform/functions.rb

@@ -2,55 +2,199 @@ require_relative 'error'
 
 module Cumuliform
   module Functions
+    # implements wrappers for the intrinsic functions Fn::*
     class IntrinsicFunctions
       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
       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
       def select(index, array)
-        unless index.is_a?(Integer) && index >= 0
-          raise ArgumentError, "index must be a positive integer"
+        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 array.is_a?(Array) && index >= array.length
-          raise IndexError, "index must be in the range 0 <= index < array.length"
+        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.to_s, array]}
+        {"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>.
+      #
+      # @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)
+      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>.
+      #
+      # @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)
+      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
+      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
@@ -58,10 +202,17 @@ module Cumuliform
       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
     def ref(logical_id)
       {"Ref" => xref(logical_id)}
     end
 
+    # returns an instance of IntrinsicFunctions which provides wrappers for
+    # Fn::* functions
     def fn
       @fn ||= IntrinsicFunctions.new(self)
     end

data/lib/cumuliform/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cumuliform
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Matt Patterson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-06-10 00:00:00.000000000 Z
+date: 2015-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,8 +52,22 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
 description: |
-  Simple DSL for generation AWS CloudFormation templates with an emphasis
+  Simple DSL for generating AWS CloudFormation templates with an emphasis
   on ensuring you don't shoot yourself in the foot by, e.g. referencing
   non-existent resources because you have a typo.
 email:
@@ -66,6 +80,7 @@ files:
 - ".gitignore"
 - ".ruby-version"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -75,7 +90,11 @@ files:
 - bin/setup
 - cumuliform.gemspec
 - examples/Rakefile
+- examples/condition_functions.rb
+- examples/fragments.rb
+- examples/intrinsic_functions.rb
 - examples/simplest.rb
+- examples/top-level-declarations.rb
 - exe/cumuliform
 - lib/cumuliform.rb
 - lib/cumuliform/error.rb
@@ -111,3 +130,4 @@ signing_key:
 specification_version: 4
 summary: DSL library for generating AWS CloudFormation templates
 test_files: []
+has_rdoc: