Functions page

Author: covracer

examples/python/documentation/functions.py

@@ -2,37 +2,50 @@
 # SPDX-License-Identifier: MPL-2.0
 
 from constructs import Construct
-from cdktf import TerraformStack, App, TerraformVariable, Token
+from cdktf import Op, TerraformStack, TerraformVariable, Token
+
 # DOCS_BLOCK_START:functions-usage-example
 from cdktf import Fn, TerraformOutput
 from imports.aws.provider import AwsProvider
 from imports.aws.data_aws_availability_zones import DataAwsAvailabilityZones
 # DOCS_BLOCK_END:functions-usage-example
+from imports.aws.instance import Instance
+
 
 class FunctionsStack(TerraformStack):
     def __init__(self, scope: Construct, id: str):
         super().__init__(scope, id)
-        AwsProvider(self, "aws", 
+        AwsProvider(self, "aws",
             region="us-east-1"
         )
 
         # DOCS_BLOCK_START:functions-usage-example
-
         zones = DataAwsAvailabilityZones(self, 'zones',
-                    state="available",
-                )
+            state="available",
+        )
 
         TerraformOutput(self, 'first-zone',
             value=Fn.element(zones.names, 0)
         )
-
         # DOCS_BLOCK_END:functions-usage-example
 
+        # DOCS_BLOCK_START:conditional
+        Instance(
+            self,
+            'web',
+            ami='ami-2757f631',
+            count=Token.as_number(
+                Fn.conditional(Op.eq(Token.as_any('terraform.workspace'), 'prod'), 2, 1)
+            ),
+            instance_type='t2.micro',
+        )
+        # DOCS_BLOCK_END:conditional
+
         # INTERNAL NOTE: Due to an JSII bug, we have to pass the variable as a string_value in Python
         # We can remove it, once https://github.com/aws/jsii/pull/4209 is released
         # DOCS_BLOCK_START:functions-lookup
         v = TerraformVariable(self, "complex-object",
-            type = 'object({users: list(object({name: string}))})',
+            type='object({users: list(object({name: string}))})',
         )
         TerraformOutput(self, 'users',
             value=Fn.lookup(v.string_value, "users")
@@ -50,4 +63,3 @@ def __init__(self, scope: Construct, id: str):
             value=Fn.raw_string('${TEMPLATE}')
         )
         # DOCS_BLOCK_END:functions-raw-string
-

examples/typescript/documentation/functions.ts

@@ -5,12 +5,19 @@ import { TerraformStack, TerraformVariable } from "cdktf";
 import { Construct } from "constructs";
 import { AwsProvider } from "@cdktf/provider-aws/lib/aws-provider";
 // DOCS_BLOCK_END:functions
+// DOCS_BLOCK_START:conditional
+import { Token } from "cdktf";
+import { Instance } from "@cdktf/provider-aws/lib/instance"
+// DOCS_BLOCK_END:conditional
+// DOCS_BLOCK_START:conditional,operators,functions,functions-raw
+import { Fn } from "cdktf";
+// DOCS_BLOCK_END:conditional,operators,functions,functions-raw
 // DOCS_BLOCK_START:operators,functions,functions-raw
-import { Fn, TerraformOutput } from "cdktf";
+import { TerraformOutput } from "cdktf";
 // DOCS_BLOCK_END:operators,functions,functions-raw
-// DOCS_BLOCK_START:operators,functions-raw
+// DOCS_BLOCK_START:conditional,operators,functions-raw
 import { Op } from "cdktf";
-// DOCS_BLOCK_END:operators,functions-raw
+// DOCS_BLOCK_END:conditional,operators,functions-raw
 // DOCS_BLOCK_START:functions-raw,functions
 import { DataAwsAvailabilityZones } from "@cdktf/provider-aws/lib/data-aws-availability-zones";
 // DOCS_BLOCK_END:functions-raw,functions
@@ -37,6 +44,16 @@ export class FunctionsStack extends TerraformStack {
     });
     // DOCS_BLOCK_END:functions
 
+    // DOCS_BLOCK_START:conditional
+    new AwsInstance(this, "web", {
+        ami: "ami-2757f631",
+        count: Token.as_number(
+            Fn.conditional(Op.eq(Token.as_any("terraform.workspace"), "prod"), 2, 1)
+        ),
+        instance_type: "t2.micro",
+    });
+    // DOCS_BLOCK_END:conditional
+
     // DOCS_BLOCK_START:functions-lookup
     const v = new TerraformVariable(this, "complex_object", {
       type: "object({users: list(object({name: string}))})",

website/docs/cdktf/concepts/functions.mdx

@@ -159,6 +159,16 @@ func NewFunctionsStack(scope constructs.Construct, name string) cdktf.TerraformS
 
 ## Special functions
 
+### Conditional Expressions
+The ternary [conditional expression](/terraform/language/expressions/conditionals) is supported in CDKTF as a function. Its first argument for the condition or predicate is usually an [operator](/terraform/cdktf/concepts/functions#operators) such as `Op.eq()` to ensure a runtime comparison. Programming language operators like `==` will be evaluated at synthesis time and the result hardcoded into the generated JSON or HCL. Depending on usage, output and inputs may need their [Token](/terraform/cdktf/concepts/tokens) types specified.
+
+<!-- #NEXT_CODE_BLOCK_SOURCE:python examples/typescript/documentation#functions-conditional -->
+<!-- #NEXT_CODE_BLOCK_SOURCE:python examples/python/documentation#functions-conditional -->
+
+<CodeTabs>
+</CodeTabs>
+
+
 ### Property Access Helpers
 
 To access nested properties from untyped objects or other datasources that return a dynamic datatype, use the Terraform function `lookup` or, for nested access, the function "Fn.lookupNested()" which is a function offered by CDKTF that allows to avoid nesting `Fn.lookup` calls.
@@ -169,6 +179,8 @@ To access nested properties from untyped objects or other datasources that retur
 <!-- #NEXT_CODE_BLOCK_SOURCE:csharp examples/csharp/documentation#functions-lookup -->
 <!-- #NEXT_CODE_BLOCK_SOURCE:go examples/go/documentation#functions-lookup -->
 
+<CodeTabs>
+
 ```ts
 const v = new TerraformVariable(this, "complex_object", {
   type: "object({users: list(object({name: string}))})",
@@ -230,6 +242,8 @@ cdktf.NewTerraformOutput(stack, jsii.String("first-user-name"), &cdktf.Terraform
 })
 ```
 
+</CodeTabs>
+
 ### Raw string helper
 
 Another helper function offered by CDKTF is `Fn.rawString` which can be used to escape raw strings that contain characters that CDKTF or Terraform would try to interpret otherwise.
@@ -240,6 +254,8 @@ Another helper function offered by CDKTF is `Fn.rawString` which can be used to
 <!-- #NEXT_CODE_BLOCK_SOURCE:csharp examples/csharp/documentation#functions-raw-string -->
 <!-- #NEXT_CODE_BLOCK_SOURCE:go examples/go/documentation#functions-raw-string -->
 
+<CodeTabs>
+
 ```ts
 new TerraformOutput(this, "quotes", {
   value: Fn.rawString(`"b"`),
@@ -287,6 +303,8 @@ cdktf.NewTerraformOutput(stack, jsii.String("template"), &cdktf.TerraformOutputC
 })
 ```
 
+</CodeTabs>
+
 ## Operators
 
 Use the `Op` object to include operators like `!`, `+`, and `-`.

website/docs/cdktf/concepts/tokens.mdx

@@ -21,7 +21,7 @@ You may need to use Tokens for:
 - [Module outputs](/terraform/cdktf/concepts/modules) for boolean, string, lists, maps, and other complex types.
 - Resource attributes (such as `id`).
 - Terraform outputs based on resource attributes.
-- Using Terraform's `null` type and [terraform.workspace](/terraform/language/expressions/references#filesystem-and-workspace-info).
+- Using Terraform's `null` type and [terraform.workspace](/terraform/language/state/workspaces#current-workspace-interpolation).
 
 ### Example
 
@@ -226,27 +226,30 @@ In the code below, the outer `Token.as_number()` avoids:
 The inner `Token.as_any()` avoids generating extra quotes `"terraform.workspace"` and extra dollar signs `"$${terraform.workspace}"`.
 
 <CodeTabs>
-```python
-from cdktf import App, Fn, Op, TerraformStack, Token
-from cdktf_cdktf_provider_null.resource import Resource
-
+<!-- #NEXT_CODE_BLOCK_SOURCE:python examples/python/documentation#functions-conditional -->
+<!-- #NEXT_CODE_BLOCK_SOURCE:ts examples/typescript/documentation#functions-conditional -->
 
-stack = TerraformStack(App(), 'stack')
-Resource(
-    stack,
-    'this',
-    count=Token.as_number(
-        Fn.conditional(
-            Op.eq(Token.as_any('terraform.workspace'), 'prod'), 1, 0
+```python
+        Instance(
+            self,
+            'web',
+            ami='ami-2757f631',
+            count=Token.as_number(
+                Fn.conditional(Op.eq(Token.as_any('terraform.workspace'), 'prod'), 2, 1)
+            ),
+            instance_type='t2.micro',
         )
-    ),
-)
-print(stack.to_hcl_terraform()['hcl'])
+```
+
+```ts
+foo
 ```
 
 ```terraform
-resource "null_resource" "this" {
-  count = (terraform.workspace == "prod") ? 1 : 0
+resource "aws_instance" "web" {
+  ami = "ami-2757f631"
+  count = (terraform.workspace == "prod") ? 2 : 1
+  instance_type = "t2.micro"
 }
 ```
 </CodeTabs>