+2
日增长
5,839
stars
678
forks
326
watchers
496
prs
356
issues
39
releases
README
HCL
HCL is a toolkit for creating structured configuration languages that are
both human- and machine-friendly, for use with command-line tools.
Although intended to be generally useful, it is primarily targeted
towards devops tools, servers, etc.
NOTE: This is major version 2 of HCL, whose Go API is incompatible with
major version 1. Both versions are available for selection in Go Modules
projects. HCL 2 _cannot_ be imported from Go projects that are not using Go Modules. For more information, see
our version selection guide.
HCL has both a _native syntax_, intended to be pleasant to read and write for
humans, and a JSON-based variant that is easier for machines to generate
and parse.
The HCL native syntax is inspired by libucl,
nginx configuration,
and others.
It includes an expression syntax that allows basic inline computation and,
with support from the calling application, use of variables and functions
for more dynamic configuration languages.
HCL provides a set of constructs that can be used by a calling application to
construct a configuration language. The application defines which attribute
names and nested block types are expected, and HCL parses the configuration
file, verifies that it conforms to the expected structure, and returns
high-level objects that the application can use for further processing.
go
package main
import (
"log"
"github.com/hashicorp/hcl/v2/hclsimple"
)
type Config struct {
IOMode string hcl:"io_mode"
Service ServiceConfig hcl:"service,block"
}
type ServiceConfig struct {
Protocol string hcl:"protocol,label"
Type string hcl:"type,label"
ListenAddr string hcl:"listen_addr"
Processes []ProcessConfig hcl:"process,block"
}
type ProcessConfig struct {
Type string hcl:"type,label"
Command []string hcl:"command"
}
func main() {
var config Config
err := hclsimple.DecodeFile("config.hcl", nil, &config)
if err != nil {
log.Fatalf("Failed to load configuration: %s", err)
}
log.Printf("Configuration is %v", config)
}
A lower-level API is available for applications that need more control over
the parsing, decoding, and evaluation of configuration. For more information,
see the package documentation.
Why?
Newcomers to HCL often ask: why not JSON, YAML, etc?
Whereas JSON and YAML are formats for serializing data structures, HCL is
a syntax and API specifically designed for building structured configuration
formats.
HCL attempts to strike a compromise between generic serialization formats
such as JSON and configuration formats built around full programming languages
such as Ruby. HCL syntax is designed to be easily read and written by humans,
and allows _declarative_ logic to permit its use in more complex applications.
HCL is intended as a base syntax for configuration formats built
around key-value pairs and hierarchical blocks whose structure is well-defined
by the calling application, and this definition of the configuration structure
Top issues
#211The ability to split a long string over multiple lines36 comments · 2017-09-17#285Removing multiple newlines from EOF?14 comments · 2019-08-16#299Serialize hcl.Body to send over wire protocol for processing elsewhere11 comments · 2019-01-23#291Can't decode into map[string]interface{}11 comments · 2019-05-28#164Slices of structs not supported without a key a some sort..11 comments · 2016-11-02#627how to convert HCL2 into json?9 comments · 2023-09-19#293Is it possible to convert a JSON Schema to an hcldec?9 comments · 2018-07-02#565doc error: gohcl.EvalContext not implemented, but mentioned in the doc3 comments · 2022-11-01
Latest release
v2.25.0 v2.25.0 2026-09-15Enhancements Go: Upgrade compatibility from 1.24 to 1.25 (798) hclwrite: Export LeadComments()/LineComments() (807) hclwrite: body.SetAttribute return new attribute (806) hclwrite: Block.SetType sets type (808) Prepare for Unicode 17 support in Go 1.27 (814) Bug Fixes DiagnosticWriter: Skip marked values when writing diagnostics (739) hclsyntax: Set CloseBraceRange to last label in error-recovered blocks (786) hclsyntax: Add partially complete items in nested ObjectConsItem on error (785) Internal deps: bump golang.org/x/crypto from 0.38.0 to 0.45.0 (774)