HCL4j

https://github.com/wondrify/hcl4j
Admin
HCL4j is a parser for the Hashicorp Configuration Language on the JVM that converts HCL syntax into...
Tokens:12,775
Snippets:69
Trust Score:6.5
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### HCL Built-in Collection Functions

Source: https://context7.com/wondrify/hcl4j/llms.txt

Examples of using HCL4j's auto-registered Terraform-compatible collection functions. These are evaluated at parse time.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    my_list    = ["a", "b", "c", "d"]
    out_elem   = element(my_list, 2)
    out_len    = length(my_list)
    out_idx    = index(my_list, "c")
    out_one    = one(my_list)
    out_lookup = lookup({env = "prod", region = "us-east-1"}, "env", "default")
    out_flat   = flatten([["a","b"],["c"],["d","e"]])
    out_all    = alltrue([true, true, true])
    out_any    = anytrue([false, false, true])
    out_try    = try(null, null, "fallback")
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
// results.get("out_elem")   -> "c"
// results.get("out_len")    -> 4.0
// results.get("out_idx")    -> 2
// results.get("out_one")    -> "a"
// results.get("out_lookup") -> "prod"
// results.get("out_flat")   -> ["a","b","c","d","e"]
// results.get("out_all")    -> true
// results.get("out_any")    -> true
// results.get("out_try")    -> "fallback"
```

--------------------------------

### HCL Built-in String Functions

Source: https://context7.com/wondrify/hcl4j/llms.txt

Examples of using HCL4j's auto-registered Terraform-compatible string functions. These functions are evaluated at parse time.

```hcl
# All evaluated during parser.parse(hcl)
out_upper    = upper("hello")                        # -> "HELLO"
out_lower    = lower("WORLD")                        # -> "world"
out_format   = format("%s is %d years old", "Bob", 30)  # -> "Bob is 30 years old"
out_replace  = replace("hello world", "world", "HCL")   # -> "hello HCL"
out_substr   = substr("hello world", 0, 5)           # -> "hello"
out_split    = split(",", "a,b,c")                   # -> ["a","b","c"]
out_join     = join("-", ["a","b","c"])               # -> "a-b-c"
out_strrev   = strrev("abc")                         # -> "cba"
out_starts   = startswith("hello", "he")             # -> true
out_ends     = endswith("hello", "lo")               # -> true
out_regexall = regexall("[a-z]+", "123abc456def")    # -> ["abc","def"]
out_trim     = trim("  hello  ")                     # -> "  hello  "
out_uuid     = uuid()                                # -> random UUID string
```

--------------------------------

### HCL Built-in Numeric Functions

Source: https://context7.com/wondrify/hcl4j/llms.txt

Examples of using HCL4j's auto-registered Terraform-compatible numeric functions. These are evaluated at parse time.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    out_max      = max(1, 5, 3, 2)
    out_min      = min(1, 5, 3, 2)
    out_abs      = abs(-7.5)
    out_ceil     = ceil(4.2)
    out_floor    = floor(4.9)
    out_tonumber = tonumber("42")
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
// results.get("out_max")      -> 5.0
// results.get("out_min")      -> 1.0
// results.get("out_abs")      -> 7.5
// results.get("out_ceil")     -> 5.0
// results.get("out_floor")    -> 4.0
// results.get("out_tonumber") -> 42.0
```

--------------------------------

### HCLParser.registerDataLookup

Source: https://context7.com/wondrify/hcl4j/llms.txt

Registers a custom data source provider for HCL documents. This allows you to define how specific data blocks (e.g., `data \"vsphere_datacenter\"`) are resolved during parsing.

```APIDOC
## `HCLParser.registerDataLookup(String lookupName, HCLDataLookup dataLookup)`

Registers a custom data source provider. When the HCL document references a `data "<lookupName>" "<name>" { ... }` block, the registered `HCLDataLookup` lambda is called with the block's parsed properties and should return the resolved data as a `Map<String, Object>`.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;
import java.util.HashMap;

HCLParser parser = new HCLParser();

// Provide a mock resolver for "vsphere_datacenter" data sources
parser.registerDataLookup("vsphere_datacenter", (properties) -> {
    String name = (String) properties.get("name");
    Map<String, Object> result = new HashMap<>();
    result.put("id",   "datacenter-" + name.hashCode());
    result.put("name", name);
    return result;
});

String hcl = """
    data "vsphere_datacenter" "dc" {
      name = "labs-denver"
    }

    resource "vsphere_virtual_machine" "vm" {
      datacenter_id = data.vsphere_datacenter.dc.id
      name          = "my-vm"
    }
    """;

Map<String, Object> results = parser.parse(hcl);
// results.get("resource").get("vsphere_virtual_machine").get("vm").get("datacenter_id")
//   -> "datacenter-<hashcode of labs-denver>"
```
```

--------------------------------

### HCL String Function Usage in Java

Source: https://context7.com/wondrify/hcl4j/llms.txt

Demonstrates parsing HCL strings that utilize built-in string functions. The results are available in the parsed map.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    out_format  = format("Hello, %s!", "World")
    out_split   = split(",", "one,two,three")
    out_join    = join(" | ", ["alpha","beta","gamma"])
    out_regexall = regexall("[0-9]+", "a1b2c3d4")
    out_substr  = substr("hello world", 6, 5)
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
// results.get("out_format")   -> "Hello, World!"
// results.get("out_split")    -> ["one","two","three"]
// results.get("out_join")     -> "alpha | beta | gamma"
// results.get("out_regexall") -> ["1","2","3","4"]
// results.get("out_substr")   -> "world"
```

--------------------------------

### HCLParser.parse(String input)

Source: https://context7.com/wondrify/hcl4j/llms.txt

Parses HCL syntax from a raw Java String and returns a Map<String, Object> representing the full document tree. Throws HCLParserException for syntax errors and IOException on I/O failure.

```APIDOC
## HCLParser.parse(String input)

### Description
Parses HCL syntax from a raw Java `String` and returns a `Map<String, Object>` representing the full document tree. Throws `HCLParserException` for syntax errors and `IOException` on I/O failure.

### Method
```java
public Map<String, Object> parse(String input)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
import com.bertram.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    service \"myservice\" {
      description = \"test\"
      info {
        name      = \"my service\"
        maxMemory = 1024
        enabled   = true
        tags      = [\"web\", \"api\"]
      }
    }

    resource \"lbs\" {
      name = \"lb1\"
    }

    resource \"lbs\" {
      name = \"lb2\"
    }
    """;

HCLParser parser = new HCLParser();
Map<String, Object> results = parser.parse(hcl);

// results.get(\"service\")                         -> Map { \"myservice\" -> Map { ... } }
// results.get(\"service\").get(\"myservice\")
//        .get(\"info\").get(\"enabled\")             -> true
// results.get(\"service\").get(\"myservice\")
//        .get(\"info\").get(\"maxMemory\")           -> 1024.0
// results.get(\"resource\").get(\"lbs\")            -> List [ Map{name=lb1}, Map{name=lb2} ]
```

### Response
#### Success Response (200)
- **results** (Map<String, Object>) - A map representing the parsed HCL document.

#### Response Example
```json
{
  "service": {
    "myservice": {
      "description": "test",
      "info": {
        "name": "my service",
        "maxMemory": 1024.0,
        "enabled": true,
        "tags": ["web", "api"]
      }
    }
  },
  "resource": {
    "lbs": [
      {
        "name": "lb1"
      },
      {
        "name": "lb2"
      }
    ]
  }
}
```
```

--------------------------------

### Heredoc Strings in hcl4j

Source: https://context7.com/wondrify/hcl4j/llms.txt

Shows how hcl4j correctly parses both standard (`<<EOL`) and stripped (`<<-EOF`) heredoc multiline strings. Indentation is preserved in standard heredocs.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    variable {
      description = <<EOL
    This is a multiline
      string with indentation
    preserved as-is.
    EOL
    }

    resource "aws_launch_configuration" "web" {
      user_data = <<-EOF
                  #!/bin/bash
                  echo "Hello, World" > index.html
                  nohup busybox httpd -f -p 8080 &
                  EOF
    }
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
// results.get("variable").get("description") -> "This is a multiline\n  string...\n"
// results.get("resource").get("aws_launch_configuration").get("web").get("user_data") != null
```

--------------------------------

### HCLParser.parse(File input)

Source: https://context7.com/wondrify/hcl4j/llms.txt

Parses an HCL file from disk using UTF-8 encoding by default. Returns Map<String, Object>.

```APIDOC
## HCLParser.parse(File input)

### Description
Parses an HCL file from disk using UTF-8 encoding by default. Returns `Map<String, Object>`.

### Method
```java
public Map<String, Object> parse(File input)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **input** (File) - The HCL file to parse.

### Request Example
```java
import com.bertram.plugins.hcl4j.HCLParser;
import java.io.File;
import java.util.Map;

File terraformFile = new File("infrastructure/main.tf");
Map<String, Object> results = new HCLParser().parse(terraformFile);

// Access provider config
Map<?, ?> provider = (Map<?, ?>) results.get("provider");
// Access resource blocks
Map<?, ?> resources = (Map<?, ?>) results.get("resource");
```

### Response
#### Success Response (200)
- **results** (Map<String, Object>) - A map representing the parsed HCL document.

#### Response Example
```json
{
  "provider": {
    "aws": {
      "region": "us-east-1"
    }
  },
  "resource": {
    "aws_instance": {
      "web": {
        "ami": "ami-abc123",
        "instance_type": "t2.micro"
      }
    }
  }
}
```
```

--------------------------------

### Runtime Variable Evaluation in hcl4j

Source: https://context7.com/wondrify/hcl4j/llms.txt

Shows how hcl4j evaluates variables, locals, and cross-block references at parse time when variable values are provided. Use setVariable to inject runtime values.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

HCLParser parser = new HCLParser();
parser.setVariable("instance_size", "m4.xlarge");

String hcl = """
    variable "instance_size" { default = "t2.micro" }

    locals {
      base_tag  = "prod"
      my_tags   = ["A", "B", "C"]
      start     = 1
      end       = 3
    }

    resource "aws_instance" "app" {
      instance_type  = var.instance_size
      tag            = upper(local.base_tag)
      label          = lower(local.my_tags[1])
      has_c          = contains(local.my_tags, "C")
      math           = local.start + local.end
      ops            = 2 + (4 / 2)
    }
    """;

Map<String, Object> results = parser.parse(hcl);
Map<?, ?> app = (Map<?, ?>) ((Map<?, ?>) ((Map<?, ?>) results.get("resource"))
    .get("aws_instance")).get("app");

// app.get("instance_type") -> "m4.xlarge"   (from setVariable)
// app.get("tag")           -> "PROD"
// app.get("label")         -> "b"
// app.get("has_c")         -> true
// app.get("math")          -> 4.0
// app.get("ops")           -> 4.0
```

--------------------------------

### HCLParser.parse(String input, Boolean ignoreParserExceptions)

Source: https://context7.com/wondrify/hcl4j/llms.txt

Same as the single-argument `parse`, but when `ignoreParserExceptions` is `true` the parser returns a partial result map instead of throwing on syntax errors. Useful for tolerant processing of malformed or partially valid HCL.

```APIDOC
## HCLParser.parse(String input, Boolean ignoreParserExceptions)

### Description
Same as the single-argument `parse`, but when `ignoreParserExceptions` is `true` the parser returns a partial result map instead of throwing on syntax errors. Useful for tolerant processing of malformed or partially valid HCL.

### Method
```java
public Map<String, Object> parse(String input, Boolean ignoreParserExceptions)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **ignoreParserExceptions** (Boolean) - If true, parser returns partial results on syntax errors.

### Request Example
```java
import com.bertram.plugins.hcl4j.HCLParser;
import java.util.Map;

// HCL with a syntax quirk that would normally throw
String partialHcl = """
    resource \"aws_instance\" \"web\" {
      ami           = \"ami-abc123\"
      instance_type = \"t2.micro\"
    }
    """;

HCLParser parser = new HCLParser();
Map<String, Object> results = parser.parse(partialHcl, true); // ignoreParserExceptions = true

// Partial result is still returned even if later blocks have issues
// results.get(\"resource\") -> Map { \"aws_instance\" -> Map { \"web\" -> Map { ami=ami-abc123, ... } } }
```

### Response
#### Success Response (200)
- **results** (Map<String, Object>) - A partial or full map representing the parsed HCL document.

#### Response Example
```json
{
  "resource": {
    "aws_instance": {
      "web": {
        "ami": "ami-abc123",
        "instance_type": "t2.micro"
      }
    }
  }
}
```
```

--------------------------------

### Include hcl4j Dependency with Gradle

Source: https://github.com/wondrify/hcl4j/blob/master/README.md

Add the hcl4j dependency to your project's build.gradle file to use the HCL parser.

```groovy
dependencies {
	compile "com.bertramlabs.plugins:hcl4j:0.9.4"
}
```

--------------------------------

### Using Built-in Encoding Functions in hcl4j

Source: https://context7.com/wondrify/hcl4j/llms.txt

Demonstrates the use of base64encode, base64decode, jsonencode, and jsondecode functions within HCL. These functions are evaluated at parse time.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    out_b64enc  = base64encode("Hello, World!")
    out_b64dec  = base64decode(base64encode("Hello, World!"))
    out_json    = jsonencode({name = \"Alice\", age = 30})
    out_decoded = jsondecode(\"{\"key\": \"value\", \"count\": 3}\")
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
// results.get("out_b64enc")  -> "SGVsbG8sIFdvcmxkIQ=="
// results.get("out_b64dec")  -> "Hello, World!"
// results.get("out_json")    -> pretty-printed JSON string
// results.get("out_decoded") -> Map { "key" -> "value", "count" -> 3 }
```

--------------------------------

### HCLParser.setVariables(Map<String, Object> variableMap)

Source: https://context7.com/wondrify/hcl4j/llms.txt

Bulk-injects a map of variables into the parser's runtime context. This is a convenient way to set multiple variables at once.

```APIDOC
## `HCLParser.setVariables(Map<String, Object> variableMap)`

### Description
Bulk-injects a map of variables into the parser's runtime context. Equivalent to calling `setVariable` for each entry.

### Method
`setVariables`

### Parameters
#### Path Parameters
- **variableMap** (Map<String, Object>) - Required - A map where keys are variable names and values are their corresponding values.

### Request Example
```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;
import java.util.HashMap;

HCLParser parser = new HCLParser();
Map<String, Object> vars = new HashMap<>();
vars.put("env",     "production");
vars.put("region",  "eu-west-1");
vars.put("count",   2.0);
parser.setVariables(vars);

String hcl = """
    resource \"aws_instance\" \"web\" {
      count  = var.count
      region = var.region
      tags   = { Environment = var.env }
    }
    """;

Map<String, Object> results = parser.parse(hcl);
// results.get("resource").get("aws_instance").get("web").get("region") -> "eu-west-1"
```
```

--------------------------------

### Parse HCL File with HCLParser

Source: https://github.com/wondrify/hcl4j/blob/master/README.md

Use the HCLParser class to parse an HCL file into a Map. Ensure the file path and encoding are correctly specified.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;

File terraformFile = new File("terraform.tf");
Map results = new HCLParser().parse(terraformFile, "UTF-8");
```

--------------------------------

### Parse Multiple Resource Blocks

Source: https://context7.com/wondrify/hcl4j/llms.txt

When the same resource type and label combination appears multiple times, hcl4j automatically promotes the value to a `List<Map>`, consolidating them into a single entry in the parsed results. This is useful for managing multiple instances of the same resource type.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.List;
import java.util.Map;

String hcl = """
    resource "aws_security_group_rule" "allow_http" {
      type      = "ingress"
      from_port = 80
      to_port   = 80
      protocol  = "tcp"
    }

    resource "aws_security_group_rule" "allow_https" {
      type      = "ingress"
      from_port = 443
      to_port   = 443
      protocol  = "tcp"
    }

    resource "lb" { name = "lb1" }
    resource "lb" { name = "lb2" }
    resource "lb" { name = "lb3" }
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
Map<?, ?> lbs = (Map<?, ?>) ((Map<?, ?>) results.get("resource")).get("lb");
// lbs is a List<Map> with 3 entries
// ((List<?>) lbs).size() -> 3
```

--------------------------------

### Add HCL4j to Gradle Project

Source: https://context7.com/wondrify/hcl4j/llms.txt

Add HCL4j as a compile dependency in your Gradle project.

```groovy
// build.gradle
dependencies {
    compile "com.bertramlabs.plugins:hcl4j:0.9.9"
}
```

--------------------------------

### HCLParser.parse(File input, String charsetName)

Source: https://context7.com/wondrify/hcl4j/llms.txt

Parses an HCL file using a specified character set name (e.g., "UTF-8", "ISO-8859-1").

```APIDOC
## HCLParser.parse(File input, String charsetName)

### Description
Parses an HCL file using a specified character set name (e.g., "UTF-8", "ISO-8859-1").

### Method
```java
public Map<String, Object> parse(File input, String charsetName)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **input** (File) - The HCL file to parse.
- **charsetName** (String) - The character set name to use for reading the file.

### Request Example
```java
import com.bertram.plugins.hcl4j.HCLParser;
import java.io.File;
import java.util.Map;

File terraformFile = new File("main.tf");
Map<String, Object> results = new HCLParser().parse(terraformFile, "UTF-8");

// results contains the full parsed document
```

### Response
#### Success Response (200)
- **results** (Map<String, Object>) - A map representing the parsed HCL document.

#### Response Example
```json
{
  "variable": {
    "aws_region": {
      "default": "us-east-1"
    }
  }
}
```
```

--------------------------------

### Parse HCL String with HCLParser

Source: https://context7.com/wondrify/hcl4j/llms.txt

Parses HCL syntax from a Java String into a Map<String, Object>. Throws exceptions on syntax errors.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    service \"myservice\" {
      description = \"test\"
      info {
        name      = \"my service\"
        maxMemory = 1024
        enabled   = true
        tags      = [\"web\", \"api\"]
      }
    }

    resource \"lbs\" {
      name = \"lb1\"
    }

    resource \"lbs\" {
      name = \"lb2\"
    }
    """;

HCLParser parser = new HCLParser();
Map<String, Object> results = parser.parse(hcl);

// results.get("service")                         -> Map { "myservice" -> Map { ... } }
// results.get("service").get("myservice")
//        .get("info").get("enabled")             -> true
// results.get("service").get("myservice")
//        .get("info").get("maxMemory")           -> 1024.0
// results.get("resource").get("lbs")            -> List [ Map{name=lb1}, Map{name=lb2} ]
```

--------------------------------

### Set multiple variables

Source: https://context7.com/wondrify/hcl4j/llms.txt

Use `HCLParser.setVariables(Map<String, Object>)` to inject a map of variables into the parser's runtime context. This is equivalent to calling `setVariable` for each entry.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;
import java.util.HashMap;

HCLParser parser = new HCLParser();
Map<String, Object> vars = new HashMap<>();
vars.put("env",     "production");
vars.put("region",  "eu-west-1");
vars.put("count",   2.0);
parser.setVariables(vars);

String hcl = """
    resource \"aws_instance\" \"web\" {
      count  = var.count
      region = var.region
      tags   = { Environment = var.env }
    }
    """;

Map<String, Object> results = parser.parse(hcl);
// results.get("resource").get("aws_instance").get("web").get("region") -> "eu-west-1"
```

--------------------------------

### Register Custom Data Source with HCLParser

Source: https://context7.com/wondrify/hcl4j/llms.txt

Register a custom data source provider for HCL documents. The registered lambda is called when a data block references the specified lookup name.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;
import java.util.HashMap;

HCLParser parser = new HCLParser();

// Provide a mock resolver for "vsphere_datacenter" data sources
parser.registerDataLookup("vsphere_datacenter", (properties) -> {
    String name = (String) properties.get("name");
    Map<String, Object> result = new HashMap<>();
    result.put("id",   "datacenter-" + name.hashCode());
    result.put("name", name);
    return result;
});

String hcl = """
    data "vsphere_datacenter" "dc" {
      name = "labs-denver"
    }

    resource "vsphere_virtual_machine" "vm" {
      datacenter_id = data.vsphere_datacenter.dc.id
      name          = "my-vm"
    }
    """;

Map<String, Object> results = parser.parse(hcl);
// results.get("resource").get("vsphere_virtual_machine").get("vm").get("datacenter_id")
//   -> "datacenter-<hashcode of labs-denver>"
```

--------------------------------

### Built-in String Functions

Source: https://context7.com/wondrify/hcl4j/llms.txt

HCL4j automatically registers Terraform-compatible string functions that can be invoked using HCL expression syntax and are evaluated at parse time.

```APIDOC
## Built-in String Functions

HCL4j auto-registers Terraform-compatible string functions. All are invoked via HCL expression syntax and evaluated at parse time.

```hcl
# All evaluated during parser.parse(hcl)
out_upper    = upper("hello")                        # -> "HELLO"
out_lower    = lower("WORLD")                        # -> "world"
out_format   = format("%s is %d years old", "Bob", 30)  # -> "Bob is 30 years old"
out_replace  = replace("hello world", "world", "HCL")   # -> "hello HCL"
out_substr   = substr("hello world", 0, 5)           # -> "hello"
out_split    = split(",", "a,b,c")                   # -> ["a","b","c"]
out_join    = join("-", ["a","b","c"])               # -> "a-b-c"
out_strrev   = strrev("abc")                         # -> "cba"
out_starts   = startswith("hello", "he")             # -> true
out_ends     = endswith("hello", "lo")               # -> true
out_regexall = regexall("[a-z]+", "123abc456def")    # -> ["abc","def"]
out_trim     = trim("  hello  ")                     # -> "  hello  "
out_uuid     = uuid()                                # -> random UUID string
```

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    out_format  = format("Hello, %s!", "World")
    out_split   = split(",", "one,two,three")
    out_join    = join(" | ", ["alpha","beta","gamma"])
    out_regexall = regexall("[0-9]+", "a1b2c3d4")
    out_substr  = substr("hello world", 6, 5)
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
// results.get("out_format")   -> "Hello, World!"
// results.get("out_split")    -> ["one","two","three"]
// results.get("out_join")     -> "alpha | beta | gamma"
// results.get("out_regexall") -> ["1","2","3","4"]
// results.get("out_substr")   -> "world"
```
```

--------------------------------

### For Loop Tuple Expressions in hcl4j

Source: https://context7.com/wondrify/hcl4j/llms.txt

Demonstrates HCL `[for ...]` tuple expressions, which are evaluated at parse time to produce Java `List` objects. Supports iteration, filtering, and indexing.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    locals {
      numbers   = [0, 1, 2, 3]
      incremented = [for v in [0,1,2,3] : v + 1]
      filtered    = [for v in [0,1,2,3] : (v + 1) if v != 3]
      indexed     = [for i, v in [0,1,2,3] : "${i}:${v + 1}"]
      my_array    = [{name: "item1"}, {name: "item2"}, {name: "item3"}]
      names       = [for res in local.my_array : res.name]
    }
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
// results.get("locals").get("incremented") -> [1.0, 2.0, 3.0, 4.0]
// results.get("locals").get("filtered")    -> [1.0, 2.0, 3.0]
// results.get("locals").get("indexed")     -> ["0:1.0","1:2.0","2:3.0","3:4.0"]
// results.get("locals").get("names")       -> ["item1","item2","item3"]
```

--------------------------------

### Parse HCL File from Disk

Source: https://context7.com/wondrify/hcl4j/llms.txt

Parses an HCL file from disk using UTF-8 encoding by default. Returns a Map<String, Object> representing the document.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.io.File;
import java.util.Map;

File terraformFile = new File("infrastructure/main.tf");
Map<String, Object> results = new HCLParser().parse(terraformFile);

// Access provider config
Map<?, ?> provider = (Map<?, ?>) results.get("provider");
// Access resource blocks
Map<?, ?> resources = (Map<?, ?>) results.get("resource");
```

--------------------------------

### Parse Multiple `locals {}` Blocks

Source: https://context7.com/wondrify/hcl4j/llms.txt

Multiple `locals {}` blocks in an HCL document are merged into a single context. This allows local variables defined in one block to be referenced in subsequent blocks, including resource definitions.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    locals {
      domains = ["a.example.com", "b.example.com"]
    }

    locals {
      greeting = "Hello there"
    }

    resource "test_instance" "test" {
      message = local.greeting
      count   = length(local.domains)
    }
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
Map<?, ?> test = (Map<?, ?>) ((Map<?, ?>) ((Map<?, ?>) results.get("resource"))
    .get("test_instance")).get("test");
// test.get("message") -> "Hello there"
// test.get("count")   -> 2.0
```

--------------------------------

### HCLParser.parseVars(String input, Boolean ignoreParseException)

Source: https://context7.com/wondrify/hcl4j/llms.txt

Parses a `.tfvars`-style HCL string and loads top-level key/value pairs into the parser's variable context. These variables can then be referenced in subsequent `parse()` calls.

```APIDOC
## `HCLParser.parseVars(String input, Boolean ignoreParseException)`

### Description
Parses a `.tfvars`-style HCL string and loads all top-level key/value pairs into the parser's variable context. After calling `parseVars`, any subsequent `parse()` call on the same parser instance will resolve `var.*` references using these loaded values.

### Method
`parseVars`

### Parameters
#### Path Parameters
- **input** (String) - Required - The `.tfvars`-style HCL string to parse.
- **ignoreParseException** (Boolean) - Required - If true, parsing errors will be ignored.

### Request Example
```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String tfvars = "region = \"us-east-1\"\ninstance_type = \"t2.micro\"";

String hcl = """
    variable \"region\"        { default = \"us-west-2\" }
    variable \"instance_type\" { default = \"t3.micro\"  }

    resource \"aws_instance\" \"app\" {
      ami           = \"ami-abc123\"
      instance_type = var.instance_type
      region        = var.region
    }
    """;

HCLParser parser = new HCLParser();
parser.parseVars(tfvars, false);
Map<String, Object> results = parser.parse(hcl);

// results.get("resource").get("aws_instance").get("app").get("instance_type") -> "t2.micro"
// results.get("resource").get("aws_instance").get("app").get("region")        -> "us-east-1"
```
```

--------------------------------

### Conditional Expressions in hcl4j

Source: https://context7.com/wondrify/hcl4j/llms.txt

Illustrates the use of ternary operators and boolean logic for conditional evaluation at parse time. Nested ternary expressions are supported for complex conditions.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

HCLParser parser = new HCLParser();
parser.setVariable("instance_size", "m4.large");

String hcl = """
    worldVar = "world"
    test1    = 1 < 2 ? "yes" : "no"
    test2    = worldVar == "world" ? "found" : "missing"
    test3    = worldVar == "world" && 3 > 2 ? "both" : "neither"
    test4    = worldVar == "world" || false ? "either" : "neither"
    test5    = !(worldVar == "world")
    locals {
      size = "${var.instance_size == "m4.xlarge" ? "xlarge" : ( var.instance_size == "m4.large" ? "large" : "small" )}"
    }
    """;

Map<String, Object> results = parser.parse(hcl);
// results.get("test1")        -> "yes"
// results.get("test2")        -> "found"
// results.get("test3")        -> "both"
// results.get("test4")        -> "either"
// results.get("test5")        -> false
// results.get("locals").get("size") -> "large"
```

--------------------------------

### Built-in Collection Functions

Source: https://context7.com/wondrify/hcl4j/llms.txt

HCL4j provides built-in functions for manipulating collections within HCL expressions.

```APIDOC
## Built-in Collection Functions

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    my_list    = ["a", "b", "c", "d"]
    out_elem   = element(my_list, 2)
    out_len    = length(my_list)
    out_idx    = index(my_list, "c")
    out_one    = one(my_list)
    out_lookup = lookup({env = "prod", region = "us-east-1"}, "env", "default")
    out_flat   = flatten([["a","b"],["c"],["d","e"]])
    out_all    = alltrue([true, true, true])
    out_any    = anytrue([false, false, true])
    out_try    = try(null, null, "fallback")
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
// results.get("out_elem")   -> "c"
// results.get("out_len")    -> 4.0
// results.get("out_idx")    -> 2
// results.get("out_one")    -> "a"
// results.get("out_lookup") -> "prod"
// results.get("out_flat")   -> ["a","b","c","d","e"]
// results.get("out_all")    -> true
// results.get("out_any")    -> true
// results.get("out_try")    -> "fallback"
```
```

--------------------------------

### Built-in Numeric Functions

Source: https://context7.com/wondrify/hcl4j/llms.txt

HCL4j automatically registers Terraform-compatible numeric functions for use within HCL expressions.

```APIDOC
## Built-in Numeric Functions

Terraform-compatible numeric functions are registered automatically.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    out_max      = max(1, 5, 3, 2)
    out_min      = min(1, 5, 3, 2)
    out_abs      = abs(-7.5)
    out_ceil     = ceil(4.2)
    out_floor    = floor(4.9)
    out_tonumber = tonumber("42")
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
// results.get("out_max")      -> 5.0
// results.get("out_min")      -> 1.0
// results.get("out_abs")      -> 7.5
// results.get("out_ceil")     -> 5.0
// results.get("out_floor")    -> 4.0
// results.get("out_tonumber") -> 42.0
```
```

--------------------------------

### Parse HCL String Ignoring Syntax Errors

Source: https://context7.com/wondrify/hcl4j/llms.txt

Parses HCL from a String, returning a partial result map even if syntax errors are present when ignoreParserExceptions is true.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

// HCL with a syntax quirk that would normally throw
String partialHcl = """
    resource \"aws_instance\" \"web\" {
      ami           = \"ami-abc123\"
      instance_type = \"t2.micro\"
    }
    """;

HCLParser parser = new HCLParser();
Map<String, Object> results = parser.parse(partialHcl, true); // ignoreParserExceptions = true

// Partial result is still returned even if later blocks have issues
// results.get("resource") -> Map { "aws_instance" -> Map { "web" -> Map { ami=ami-abc123, ... } } }
```

--------------------------------

### Register a custom function

Source: https://context7.com/wondrify/hcl4j/llms.txt

Use `HCLParser.registerFunction(String, HCLFunction)` to register a custom function implementation. The `HCLFunction` interface is a `@FunctionalInterface` that accepts a list of arguments and returns an object.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

HCLParser parser = new HCLParser();

// Register a custom "double" function
parser.registerFunction("double", (arguments) -> {
    if (arguments.size() > 0 && arguments.get(0) instanceof Double) {
        return (Double) arguments.get(0) * 2;
    }
    return null;
});

// Override built-in "upper" with a custom implementation
parser.registerFunction("upper", (arguments) -> {
    if (arguments.size() > 0 && arguments.get(0) != null) {
        return "CUSTOM:" + arguments.get(0).toString().toUpperCase();
    }
    return null;
});

String hcl = """
    locals {
      doubled = double(21)
      shouted = upper(\"hello\")
    }
    """;

Map<String, Object> results = parser.parse(hcl);
// results.get("locals").get("doubled") -> 42.0
// results.get("locals").get("shouted") -> "CUSTOM:HELLO"
```

--------------------------------

### HCLParser.parse(Reader reader)

Source: https://context7.com/wondrify/hcl4j/llms.txt

Parses HCL content from a java.io.Reader. This method is useful for handling HCL from various sources, including strings and files, with flexible character-set management.

```APIDOC
## `HCLParser.parse(Reader reader)`

### Description
Parses HCL from a `java.io.Reader`, allowing flexible character-set handling or in-memory string readers.

### Method
`parse`

### Parameters
#### Path Parameters
- **reader** (java.io.Reader) - Required - The reader providing the HCL content.

### Response
#### Success Response (Map<String, Object>)
- A map representing the parsed HCL structure.

### Request Example
```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.io.StringReader;
import java.util.Map;

String hcl = "foo = \"Hello there\"\nbar = 42";
Map<String, Object> results = new HCLParser().parse(new StringReader(hcl));

// results.get("foo") -> "Hello there"
// results.get("bar") -> 42.0
```
```

--------------------------------

### Parse .tfvars style input

Source: https://context7.com/wondrify/hcl4j/llms.txt

Use `HCLParser.parseVars(String, Boolean)` to parse HCL strings in `.tfvars` format. These variables are then available for subsequent `parse()` calls on the same parser instance.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String tfvars = "region = \"us-east-1\"\ninstance_type = \"t2.micro\"";

String hcl = """
    variable \"region\"        { default = \"us-west-2\" }
    variable \"instance_type\" { default = \"t3.micro\"  }

    resource \"aws_instance\" \"app\" {
      ami           = \"ami-abc123\"
      instance_type = var.instance_type
      region        = var.region
    }
    """;

HCLParser parser = new HCLParser();
parser.parseVars(tfvars, false);
Map<String, Object> results = parser.parse(hcl);

// results.get("resource").get("aws_instance").get("app").get("instance_type") -> "t2.micro"
// results.get("resource").get("aws_instance").get("app").get("region")        -> "us-east-1"
```

--------------------------------

### Parse HCL File with Specified Charset

Source: https://context7.com/wondrify/hcl4j/llms.txt

Parses an HCL file from disk using a specified character set name, such as UTF-8 or ISO-8859-1.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.io.File;
import java.util.Map;

File terraformFile = new File("main.tf");
Map<String, Object> results = new HCLParser().parse(terraformFile, "UTF-8");

// results contains the full parsed document
```

--------------------------------

### Parse HCL with Comments

Source: https://context7.com/wondrify/hcl4j/llms.txt

Inline comments (`#`, `//`) and block comments are stripped during the lexing phase by hcl4j and do not affect the final parsed output. This ensures clean data structures are produced.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

String hcl = """
    # This is a top-level comment
    terraform {
      backend "s3" {
        bucket = "my-config-bucket"  # inline comment with hyphens my-bucket
        key    = "terraform.tfstate"
        region = "us-west-2"         // another style of comment
      }
    }
    """;

Map<String, Object> results = new HCLParser().parse(hcl);
Map<?, ?> s3 = (Map<?, ?>) ((Map<?, ?>) results.get("terraform")).get("backend").get("s3");
// s3.get("bucket") -> "my-config-bucket"
// s3.get("region") -> "us-west-2"
```

--------------------------------

### HCLParser.registerFunction(String functionName, HCLFunction function)

Source: https://context7.com/wondrify/hcl4j/llms.txt

Registers a custom function that can be used within HCL expressions. This allows extending the parser's capabilities with user-defined logic.

```APIDOC
## `HCLParser.registerFunction(String functionName, HCLFunction function)`

### Description
Registers a custom function implementation that will be called when the named function is encountered during HCL expression evaluation. The `HCLFunction` interface is a `@FunctionalInterface` accepting `List<Object>` arguments and returning `Object`.

### Method
`registerFunction`

### Parameters
#### Path Parameters
- **functionName** (String) - Required - The name of the function to register.
- **function** (HCLFunction) - Required - The implementation of the custom function.

### Request Example
```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.util.Map;

HCLParser parser = new HCLParser();

// Register a custom "double" function
parser.registerFunction("double", (arguments) -> {
    if (arguments.size() > 0 && arguments.get(0) instanceof Double) {
        return (Double) arguments.get(0) * 2;
    }
    return null;
});

// Override built-in "upper" with a custom implementation
parser.registerFunction("upper", (arguments) -> {
    if (arguments.size() > 0 && arguments.get(0) != null) {
        return "CUSTOM:" + arguments.get(0).toString().toUpperCase();
    }
    return null;
});

String hcl = """
    locals {
      doubled = double(21)
      shouted = upper(\"hello\")
    }
    """;

Map<String, Object> results = parser.parse(hcl);
// results.get("locals").get("doubled") -> 42.0
// results.get("locals").get("shouted") -> "CUSTOM:HELLO"
```
```

--------------------------------

### Parse HCL from a Reader

Source: https://context7.com/wondrify/hcl4j/llms.txt

Use `HCLParser.parse(Reader)` to parse HCL content from a `java.io.Reader`. This method is suitable for handling character sets or using in-memory string readers.

```java
import com.bertramlabs.plugins.hcl4j.HCLParser;
import java.io.StringReader;
import java.util.Map;

String hcl = "foo = \"Hello there\"\nbar = 42";
Map<String, Object> results = new HCLParser().parse(new StringReader(hcl));

// results.get("foo") -> "Hello there"
// results.get("bar") -> 42.0
```
Tokens:
Raw