This is the new *CloudFormation Template Reference Guide*. Please update your bookmarks and links. For help getting started with CloudFormation, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html). # `AWS::LanguageExtensions` transform This topic describes how to use the `AWS::LanguageExtensions` transform to enable additional functions and capabilities that are not available by default. The `AWS::LanguageExtensions` is a CloudFormation macro that, when referenced in your stack template, updates any intrinsic function defined by the transform to its resolved value within the template when you create or update a stack using a change set. By including this transform in your CloudFormation template, you can access additional features, such as `Fn::ForEach`, which allows for more advanced operations like iteration. You can also use intrinsic functions in places where they're typically not allowed, such as in `Ref` and `Fn::GetAtt` functions. ## Usage To use the `AWS::LanguageExtensions` transform, you must declare it at the top level of your CloudFormation template. You can't use `AWS::LanguageExtensions` as a transform embedded in any other template section. The declaration must use the literal string `AWS::LanguageExtensions` as its value. You can't use a parameter or function to specify a transform value. ### Syntax To declare this transform in your CloudFormation template, use the following syntax: ### JSON ``` { "Transform":"AWS::LanguageExtensions", "Resources":{ ... } } ``` ### YAML ``` Transform: AWS::LanguageExtensions Resources: ... ``` The `AWS::LanguageExtensions` transform is a standalone declaration with no additional parameters. ## Support for additional functions The `AWS::LanguageExtensions` transform supports the following additional functions: + [`Fn::ForEach`](intrinsic-function-reference-foreach.md) + [`Fn::Length`](intrinsic-function-reference-length.md) + [`Fn::ToJsonString`](intrinsic-function-reference-ToJsonString.md) ## Considerations When using the `AWS::LanguageExtensions` transform, keep the following considerations in mind: + When you update a stack that uses the `AWS::LanguageExtensions` transform, we recommend that you don't use the **Use existing template** option in the CloudFormation console, or the equivalent command line option `--use-previous-template`. The `AWS::LanguageExtensions` transform resolves parameters to literal values during processing. When you use `--use-previous-template`, CloudFormation uses this processed template with the old literal values, preventing new parameter values and Systems Manager parameter updates from being applied. Instead, provide the original template to ensure parameters are re-resolved with current values. + Short-form YAML syntax isn't supported within a template for intrinsic functions that are only available in the `AWS::LanguageExtensions` transform. Use explicit references to these functions. For example, use `Fn::Length` instead of `!Length`. + The AWS SAM CLI currently doesn't support the `Fn::ForEach` intrinsic function of the `AWS::LanguageExtensions` transform. + If you're using multiple transforms, use a list format. If you're using custom macros, place AWS-provided transforms after your custom macros. If you're using both the `AWS::LanguageExtensions` and `AWS::Serverless` transforms, the `AWS::LanguageExtensions` transform must come before the `AWS::Serverless` transform in the list. + Functions and attributes provided by the `AWS::LanguageExtensions` transform are only supported in the `Resources`, `Conditions`, and `Outputs` sections of your template. ## Examples The following examples show how to use the `AWS::LanguageExtensions` transform to use the `Fn::Length` intrinsic function, defined by the transform. ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Parameters": { "QueueList": { "Type": "CommaDelimitedList" }, "QueueNameParam": { "Description": "Name for your SQS queue", "Type": "String" } }, "Resources": { "Queue": { "Type": "AWS::SQS::Queue", "Properties": { "QueueName": { "Ref": "QueueNameParam" }, "DelaySeconds": { "Fn::Length": { "Ref": "QueueList" } } } } } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Parameters: QueueList: Type: CommaDelimitedList QueueNameParam: Description: Name for your SQS queue Type: String Resources: Queue: Type: AWS::SQS::Queue Properties: QueueName: !Ref QueueNameParam DelaySeconds: 'Fn::Length': !Ref QueueList ``` ## Related resources For more examples, see the following topics. + [`Fn::ForEach`](intrinsic-function-reference-foreach.md) + [`Fn::Length`](intrinsic-function-reference-length.md) + [`Fn::ToJsonString`](intrinsic-function-reference-ToJsonString.md) + [`Ref`](intrinsic-function-reference-ref.md) + [`Fn::GetAtt`](intrinsic-function-reference-getatt.md) + [`Fn::FindInMap enhancements`](intrinsic-function-reference-findinmap-enhancements.md) For general information about using macros, see [Perform custom processing on CloudFormation templates with template macros](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-macros.html) in the *AWS CloudFormation User Guide*. # `Fn::FindInMap enhancements` The `AWS::LanguageExtensions` transform enhances the functionality of the `Fn::FindInMap` intrinsic function in CloudFormation templates. The `Fn::FindInMap` function is used to retrieve a value from a mapping defined in the `Mappings` section of a CloudFormation template. However, the standard `Fn::FindInMap` function has limitations, such as the inability to handle missing mappings or use a `Fn::FindInMap` function with some intrinsic functions embedded inside it. The `AWS::LanguageExtensions` transform addresses these limitations by introducing the following enhancements: + **Default value support** – You can specify a default value to be returned if a mapping is not found. + **Intrinsic function support** – You can also use a wider range of intrinsic functions to define the fields of `Fn::FindInMap` than with the standard `Fn::FindInMap` function. ## Declaration ### JSON ``` { "Fn::FindInMap" : [ "MapName", "TopLevelKey", "SecondLevelKey", {"DefaultValue": "DefaultValue"} ] } ``` ### YAML Syntax for the full function name: ``` Fn::FindInMap: - MapName - TopLevelKey - SecondLevelKey - DefaultValue: DefaultValue ``` Syntax for the short form: ``` !FindInMap - MapName - TopLevelKey - SecondLevelKey - DefaultValue: DefaultValue ``` ## Parameters DefaultValue The value that `Fn::FindInMap` will resolve to if the `TopLevelKey` and/or `SecondLevelKey` can not be found from the `MapName` map. This field is optional. All parameters `MapName`, `TopLevelKey`, `SecondLevelKey`, and `DefaultValue` can be an intrinsic function as long as it's able to resolve to a valid value during the transform. ## Examples The following examples demonstrate how to define the fields of `Fn::FindInMap` when you add the `AWS::LanguageExtensions` transform. ### Using a default value The following is an example of using a default value in the `Fn::FindInMap` function. #### JSON ``` { //... "Transform": "AWS::LanguageExtensions", //... "Fn::FindInMap": [ "RegionMap", { "Ref": "AWS::Region" }, "InstanceType", { "DefaultValue": "t3.micro" } ] //... } ``` #### YAML ``` Transform: 'AWS::LanguageExtensions' #... !FindInMap - 'RegionMap' - !Ref 'AWS::Region' - 'InstanceType' - DefaultValue: t3.micro #... ``` #### Using intrinsic functions to define the top level key The following is an example of using a `Fn::FindInMap` function with the `Fn::Select` and `Fn::Split` intrinsic functions embedded inside it to define the top level key. ##### JSON ``` { //... "Transform": "AWS::LanguageExtensions", //... "Fn::FindInMap": [ "MyMap", { "Fn::Select": [ 0, { "Fn::Split": [ "|", { "Ref": "InputKeys" } ] } ] }, "SecondKey" ] //... } ``` ##### YAML ``` Transform: 'AWS::LanguageExtensions' #... !FindInMap: [MyMap, !Select [0, !Split [|, !Ref InputKeys]], SecondKey] #... ``` ## Supported functions You can use the following functions in the parameters of `Fn::FindInMap:` enhancements: + ``Fn::FindInMap`` + ``Fn::Join`` + ``Fn::Sub`` + ``Fn::If`` + ``Fn::Select`` + ``Fn::Length`` + ``Fn::ToJsonString`` + ``Fn::Split`` - Unless it’s used for the default value, `Fn::Split` has to be used in conjunction with intrinsic functions that produce a string, such as ``Fn::Join`` or ``Fn::Select``. + ``Ref`` ## Related resources For more information and examples that show how to use the `Fn::FindInMap` intrinsic function, see [`Fn::FindInMap`](intrinsic-function-reference-findinmap.md). For more information about the `AWS::LanguageExtensions` transform, see [`AWS::LanguageExtensions` transform](transform-aws-languageextensions.md).