How do I parse an HCL file in Go?

Use the hclsimple.DecodeFile function for simple decoding into Go structs, as shown in the README example, or the lower-level API for more control over parsing and evaluation.

What's the difference between HCL and YAML for configuration?

HCL is designed for structured configuration with built-in validation and expressions, making it more robust for complex, hierarchical configs, while YAML is more flexible but prone to syntax errors and lacks native validation.

Can I use HCL with programming languages other than Go?

HCL is primarily a Go library, but there are community ports for languages like Python or Java; however, official support and features are best in Go, so non-Go projects may face limitations.

How do I add variables and functions in HCL configs?

Variables and functions are provided by the calling application; in the syntax, use expressions like ${var.name} or function calls, as illustrated in the README with examples like sum = 1 + addend.

Is HCL only used by Terraform or HashiCorp tools?

While HCL originated with Terraform, it's a general-purpose toolkit used by various devops tools, but its adoption and ecosystem are most prominent within the HashiCorp suite.

What are the main changes in HCL 2.0 vs HCL 1.0?

HCL 2.0 merges HCL and HIL into a single language with a new parser and Go API, adding full expression support but breaking compatibility, requiring import versioning in Go modules.

HCL — Structured Configuration Language Toolkit

What is HCL?

HCL is a toolkit for creating structured configuration languages that are both human-readable and machine-friendly. It provides a syntax and API specifically designed for building configuration formats, primarily targeting devops tools and servers. It combines a native, human-friendly syntax with a JSON variant, allowing for dynamic expressions and structured validation.

Target Audience

Developers and devops engineers building or using configuration-driven tools, especially those in the HashiCorp ecosystem (like Terraform) or anyone needing a structured, readable configuration format.

Value Proposition

Developers choose HCL because it offers a balanced approach between simple serialization formats and full programming languages, providing human readability, machine parseability, and support for dynamic expressions without the complexity of a full scripting language.

HCL is the HashiCorp configuration language.

Use Cases

Best For

Defining infrastructure-as-code configurations for tools like Terraform
Creating human-readable configuration files for devops tools and servers
Building custom configuration languages for applications that need structured validation
Generating machine-friendly configuration via JSON while maintaining a human-editable native syntax
Adding expression support and dynamic variables to configuration files
Providing better error messages and validation in configuration parsers

Not Ideal For

Projects built in non-Go programming languages without available HCL ports
Simple configuration needs where flat JSON or YAML is sufficient and more interoperable
Applications requiring complex imperative scripting or full programming language capabilities in configs
Teams heavily invested in HCL 1.0 who want to avoid the breaking changes and migration effort to HCL 2.0

Pros & Cons

Pros

Human-Readable Syntax

The native syntax is inspired by libucl and nginx, designed for easy reading and writing, as shown in the clean, block-based config.hcl example.

JSON Interoperability

Supports a JSON-based variant that shares the same data model, allowing seamless mixing of human-authored native syntax and machine-generated JSON configs.

Dynamic Expression Language

Includes inline expressions for computation, variables, and functions, enabling declarative logic in configurations without full scripting, as demonstrated with arithmetic and string interpolation.

Structured Validation

Applications can define expected attribute names and block types, leading to better error messages and validation, which is a core part of HCL's philosophy for robust configs.

Cons

Breaking API Changes

HCL 2.0 has a completely new Go API with no direct migration path from HCL 1.0, requiring significant refactoring for upgrades, as noted in the version selection warning.

Go-Centric Implementation

Primarily a Go toolkit, so it's less suitable for projects in other languages without community ports, limiting its use outside the Go ecosystem.

Expression Limitations

While it supports expressions, it's not a full programming language; complex logic or advanced control flow might still require external scripting or application logic.

What is HCL?

Target Audience

Value Proposition

Use Cases

Best For

Defining infrastructure-as-code configurations for tools like Terraform
Creating human-readable configuration files for devops tools and servers
Building custom configuration languages for applications that need structured validation
Generating machine-friendly configuration via JSON while maintaining a human-editable native syntax
Adding expression support and dynamic variables to configuration files
Providing better error messages and validation in configuration parsers

Not Ideal For

Projects built in non-Go programming languages without available HCL ports
Simple configuration needs where flat JSON or YAML is sufficient and more interoperable
Applications requiring complex imperative scripting or full programming language capabilities in configs
Teams heavily invested in HCL 1.0 who want to avoid the breaking changes and migration effort to HCL 2.0

Pros & Cons

Pros

Human-Readable Syntax

The native syntax is inspired by libucl and nginx, designed for easy reading and writing, as shown in the clean, block-based config.hcl example.

JSON Interoperability

Supports a JSON-based variant that shares the same data model, allowing seamless mixing of human-authored native syntax and machine-generated JSON configs.

Dynamic Expression Language

Includes inline expressions for computation, variables, and functions, enabling declarative logic in configurations without full scripting, as demonstrated with arithmetic and string interpolation.

Structured Validation

Applications can define expected attribute names and block types, leading to better error messages and validation, which is a core part of HCL's philosophy for robust configs.

Cons

Breaking API Changes

HCL 2.0 has a completely new Go API with no direct migration path from HCL 1.0, requiring significant refactoring for upgrades, as noted in the version selection warning.

Go-Centric Implementation

Primarily a Go toolkit, so it's less suitable for projects in other languages without community ports, limiting its use outside the Go ecosystem.

Expression Limitations

While it supports expressions, it's not a full programming language; complex logic or advanced control flow might still require external scripting or application logic.

HCL

What is HCL?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

HCL

What is HCL?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?