diff --git a/SUMMARY.md b/SUMMARY.md index 7fbdf962..8a5f7797 100644 --- a/SUMMARY.md +++ b/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) diff --git a/usage/hcl.md b/usage/hcl.md new file mode 100644 index 00000000..4d636a70 --- /dev/null +++ b/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" +} +``` + diff --git a/usage/xml.md b/usage/xml.md index c5bb6bc5..170f03ae 100644 --- a/usage/xml.md +++ b/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 --> ``` 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 --> ``` 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