feat: Improving locals documentation

docs/_docs/02_features/locals.md

@@ -12,11 +12,10 @@ nav_title_link: /docs/
 
 ## Locals
 
-You can use locals to bind a name to an expression, so you can reuse that expression without having to repeat it multiple times (keeping your Terragrunt configuration DRY).
-config. For example, suppose that you need to use the AWS region in multiple inputs. You can bind the name `aws_region`
+You can use locals to bind a name to an expression, so you can reuse that expression without having to repeat it multiple times (keeping your Terragrunt configuration DRY). For example, suppose that you need to use the name of an AWS region in multiple inputs. You can bind the name `aws_region`
 using locals:
 
-```
+```hcl
 locals {
   aws_region = "us-east-1"
 }
@@ -29,7 +28,7 @@ inputs = {
 
 You can use any valid terragrunt expression in the `locals` configuration. The `locals` block also supports referencing other `locals`:
 
-```
+```hcl
 locals {
   x = 2
   y = 40
@@ -39,14 +38,14 @@ locals {
 
 ### Including globally defined locals
 
-Currently you can only reference `locals` defined in the same config file. `terragrunt` does not automatically include
+Currently you can only reference `locals` defined in the same config file. Terragrunt does not automatically include
 `locals` defined in the parent config of an `include` block into the current context. If you wish to reuse variables
-globally, consider using `yaml` or `json` files that are included and merged using the `terraform` built in functions
-available to `terragrunt`.
+globally, consider using YAML or JSON files that are included and merged using the OpenTofu/Terraform built in functions
+available to Terragrunt.
 
 For example, suppose you had the following directory tree:
 
-```
+```tree
 .
 ├── terragrunt.hcl
 ├── mysql
@@ -58,7 +57,7 @@ For example, suppose you had the following directory tree:
 Instead of adding the `locals` block to the parent `terragrunt.hcl` file, you can define a file `common_vars.yaml`
 that contains the global variables you wish to pull in:
 
-```
+```tree
 .
 ├── terragrunt.hcl
 ├── common_vars.yaml
@@ -70,14 +69,49 @@ that contains the global variables you wish to pull in:
 
 You can then include them into the `locals` block of the child terragrunt config using `yamldecode` and `file`:
 
+```yml
+# common_vars.yaml
+region: us-east-1
 ```
-# child terragrunt.hcl
+
+```hcl
+# mysql/terragrunt.hcl
 locals {
   common_vars = yamldecode(file(find_in_parent_folders("common_vars.yaml")))
-  region = "us-east-1"
+  region      = local.common_vars.region # <-- us-east-1
 }
 ```
 
 This configuration will load in the `common_vars.yaml` file and bind it to the attribute `common_vars` so that it is available
 in the current context. Note that because `locals` is a block, there is not currently a way to merge the map into the top
 level.
+
+### Reading from other HCL files
+
+In addition to reading from files like YAML and JSON, which are useful serialization formats for plain data, you can also read from other HCL files. This is useful if you want to share more complex data between configurations, some of which may be computed.
+
+For example, suppose you have the following directory tree:
+
+```tree
+.
+├── computed.hcl
+├── child
+│   └── terragrunt.hcl
+```
+
+You can read the `computed.hcl` file from the `child` terragrunt configuration:
+
+```hcl
+# computed.hcl
+locals {
+  computed_value = run_cmd("--terragrunt-quiet", "python3", "-c", "print('Hello,')")
+}
+```
+
+```hcl
+locals {
+  parent_computed_value = read_terragrunt_config(find_in_parent_folders("computed.hcl"))
+  message = "${local.parent_computed_value.computed_value} world!" # <-- Hello world!
+}
+
+Note that this can be a powerful feature, but it can easily lead to performance issues if you are not careful, as each read will require a full parse of the HCL file and potentially execute expensive computation. Use this feature judiciously.