Functions
cfnpp contains a handful of built-in functions for controlling the output of your stack.
This page details the general syntax and outlines all valid functions except for Merge Functions. The difference is outlined below.
Syntax
Functions are specified using YAML's "tagging" syntax. Any value beginning with a exclamation mark (!) is treated as a tag, as in:
Property: !Tag tagvalue
Property2: !Tag
- TagValue1
- TagValue2
Tags/functions can be passed a literal or an entire block of YAML as appropriate.
Merge Functions vs. Regular Functions
There are two points in the compilation process where functions are processed.
Merge functions are processed for each stack that is merged/included. They are given access to both the existing document state and the document being merged in and are able to therefore control the merging process.
Regular functions are only processed after all merging is complete. They see the final document created by the merging process and merge functions are are able to then mutate that document as appropriate.
Functions
The following functions are currently available.
!expr
Evaluates an expression and inserts the result into the document.
If the expression resolves to a single value, then a scalar will be inserted. If the expression resolves to multiple values, then an array will be inserted.
Example
cfnpp:
variables:
A: 1
B: 2
Foo: "cfn"
Bar: "pp"
ProgramName: !expr cfn pp concat
AGreaterThanB: !expr A B gt
FooEqualsBar: !expr Foo Bar eq
ProgramNameParts: !expr Foo Bar
outputs:
AGreaterThanB: False
FooEqualsBar: False
ProgramNameParts:
- cfn
- pp
!if
Allows you to conditionally include/not include parts of the document.
This function expects to receive its arguments as an array of two or three elements. The first is the expression to evaluate, the second is the value if the expression is true, and the third (optional) is the value if the expression is false.
Example
cfnpp:
variables:
UseSecurity: False
UseMultiAz: True
Resources:
MyResource:
Name: A Resource
SecurityLevel: !if
- UseSecurity
- 5
AvailabilityZones: !if
- UseMultiAz
-
- us-east-1a
- us-east-1b
-
- us-east-1a
outputs:
Resources:
MyResource:
Name: A Resource
# SecurityLevel is dropped because there was no 'false' value
AvailabilityZones:
- us-east-1a
- us-east-1b
!param
Creates a reference to a CloudFormation parameter.
Example
Resources:
MyResource:
Name: !param Name
outputs:
Resources:
MyResource:
Name: { Ref: Name }
!unset
Causes a property to be removed unconditionally.
This is as opposed to simply setting to null or some other value.
All tags require values (YAML does not allow a naked !unset), so a value must be passed but it is ignored.
Example
Resources:
MyResource:
Name: A Resource
SecurityLevel: 5
merging:
Resources:
MyResource:
SecurityLevel: !unset ~
outputs:
Resources:
MyResource:
Name: A Resource
!var
Places the value of a variable into your document.
Example
cfnpp:
variables:
SecurityLevel: 5
AvailabilityZones:
- us-east-1a
- us-east-1b
Resources:
MyResource:
Name: A Resource
SecurityLevel: !var SecurityLevel
AvailabilityZones: !var AvailabilityZones
outputs:
Resource:
MyResource:
Name: A Resource
SecurityLevel: 5
AvailabilityZones:
- us-east-1a
- us-east-1b