v4.50.1 - HCL

SUMMARY.md

@@ -85,6 +85,7 @@
 * [Working with JSON](usage/convert.md)
 * [Working with Properties](usage/properties.md)
 * [Working with XML](usage/xml.md)
+* [Working with HCL](usage/hcl.md)
 * [Working with LUA](usage/lua.md)
 * [Working with TOML](usage/toml.md)
 * [Working with Shell Output](usage/shellvariables.md)

usage/hcl.md

@@ -0,0 +1,201 @@
+# HCL
+
+Encode and decode to and from [HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl).
+
+HCL is commonly used in HashiCorp tools like Terraform for configuration files. The yq HCL encoder and decoder support:
+- Blocks and attributes
+- String interpolation and expressions (preserved without quotes)
+- Comments (leading, head, and line comments)
+- Nested structures (maps and lists)
+- Syntax colorization when enabled
+
+
+## Parse HCL
+Given a sample.hcl file of:
+```hcl
+io_mode = "async"
+```
+then
+```bash
+yq -oy sample.hcl
+```
+will output
+```yaml
+io_mode: "async"
+```
+
+## Roundtrip: Sample Doc
+Given a sample.hcl file of:
+```hcl
+service "cat" {
+  process "main" {
+    command = ["/usr/local/bin/awesome-app", "server"]
+  }
+
+  process "management" {
+    command = ["/usr/local/bin/awesome-app", "management"]
+  }
+}
+
+```
+then
+```bash
+yq sample.hcl
+```
+will output
+```hcl
+service "cat" {
+  process "main" {
+    command = ["/usr/local/bin/awesome-app", "server"]
+  }
+  process "management" {
+    command = ["/usr/local/bin/awesome-app", "management"]
+  }
+}
+```
+
+## Roundtrip: With an update
+Given a sample.hcl file of:
+```hcl
+service "cat" {
+  process "main" {
+    command = ["/usr/local/bin/awesome-app", "server"]
+  }
+
+  process "management" {
+    command = ["/usr/local/bin/awesome-app", "management"]
+  }
+}
+
+```
+then
+```bash
+yq '.service.cat.process.main.command += "meow"' sample.hcl
+```
+will output
+```hcl
+service "cat" {
+  process "main" {
+    command = ["/usr/local/bin/awesome-app", "server", "meow"]
+  }
+  process "management" {
+    command = ["/usr/local/bin/awesome-app", "management"]
+  }
+}
+```
+
+## Parse HCL: Sample Doc
+Given a sample.hcl file of:
+```hcl
+service "cat" {
+  process "main" {
+    command = ["/usr/local/bin/awesome-app", "server"]
+  }
+
+  process "management" {
+    command = ["/usr/local/bin/awesome-app", "management"]
+  }
+}
+
+```
+then
+```bash
+yq -oy sample.hcl
+```
+will output
+```yaml
+service:
+  cat:
+    process:
+      main:
+        command:
+          - "/usr/local/bin/awesome-app"
+          - "server"
+      management:
+        command:
+          - "/usr/local/bin/awesome-app"
+          - "management"
+```
+
+## Parse HCL: with comments
+Given a sample.hcl file of:
+```hcl
+# Configuration
+port = 8080 # server port
+```
+then
+```bash
+yq -oy sample.hcl
+```
+will output
+```yaml
+# Configuration
+port: 8080 # server port
+```
+
+## Roundtrip: with comments
+Given a sample.hcl file of:
+```hcl
+# Configuration
+port = 8080
+```
+then
+```bash
+yq sample.hcl
+```
+will output
+```hcl
+# Configuration
+port = 8080
+```
+
+## Roundtrip: With templates, functions and arithmetic
+Given a sample.hcl file of:
+```hcl
+# Arithmetic with literals and application-provided variables
+sum = 1 + addend
+
+# String interpolation and templates
+message = "Hello, ${name}!"
+
+# Application-provided functions
+shouty_message = upper(message)
+```
+then
+```bash
+yq sample.hcl
+```
+will output
+```hcl
+# Arithmetic with literals and application-provided variables
+sum = 1 + addend
+# String interpolation and templates
+message = "Hello, ${name}!"
+# Application-provided functions
+shouty_message = upper(message)
+```
+
+## Roundtrip: Separate blocks with same name.
+Given a sample.hcl file of:
+```hcl
+resource "aws_instance" "web" {
+  ami = "ami-12345"
+}
+resource "aws_instance" "db" {
+  ami = "ami-67890"
+}
+```
+then
+```bash
+yq sample.hcl
+```
+will output
+```hcl
+resource "aws_instance" "web" {
+  ami = "ami-12345"
+}
+resource "aws_instance" "db" {
+  ami = "ami-67890"
+}
+```
+

usage/xml.md

@@ -53,7 +53,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -oy '.' sample.xml
+yq -oy sample.xml
 ```
 will output
 ```yaml
@@ -100,7 +100,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -oy '.' sample.xml
+yq -oy sample.xml
 ```
 will output
 ```yaml
@@ -157,7 +157,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -oy '.' sample.xml
+yq -oy sample.xml
 ```
 will output
 ```yaml
@@ -177,7 +177,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -oy '.' sample.xml
+yq -oy sample.xml
 ```
 will output
 ```yaml
@@ -196,7 +196,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq -oy '.' sample.xml
+yq -oy sample.xml
 ```
 will output
 ```yaml
@@ -225,7 +225,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq '.' sample.xml
+yq sample.xml
 ```
 will output
 ```xml
@@ -256,7 +256,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq --xml-skip-directives '.' sample.xml
+yq --xml-skip-directives sample.xml
 ```
 will output
 ```xml
@@ -292,7 +292,7 @@ for x --></x>
 ```
 then
 ```bash
-yq -oy '.' sample.xml
+yq -oy sample.xml
 ```
 will output
 ```yaml
@@ -327,7 +327,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq --xml-keep-namespace=false '.' sample.xml
+yq --xml-keep-namespace=false sample.xml
 ```
 will output
 ```xml
@@ -361,7 +361,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq --xml-raw-token=false '.' sample.xml
+yq --xml-raw-token=false sample.xml
 ```
 will output
 ```xml
@@ -542,7 +542,7 @@ for x --></x>
 ```
 then
 ```bash
-yq '.' sample.xml
+yq sample.xml
 ```
 will output
 ```xml
@@ -575,7 +575,7 @@ Given a sample.xml file of:
 ```
 then
 ```bash
-yq '.' sample.xml
+yq sample.xml
 ```
 will output
 ```xml