Repository files navigation

HCL is a toolkit for creating structured configuration languages that areboth human- and machine-friendly, for use with command-line tools.Although intended to be generally useful, it is primarily targetedtowards devops tools, servers, etc.

NOTE: This is major version 2 of HCL, whose Go API is incompatible withmajor version 1. Both versions are available for selection in Go Modulesprojects. HCL 2cannot be imported from Go projects that are not using Go Modules. For more information, seeour version selection guide.

HCL has both anative syntax, intended to be pleasant to read and write forhumans, and a JSON-based variant that is easier for machines to generateand parse.

The HCL native syntax is inspired bylibucl,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 functionsfor more dynamic configuration languages.

HCL provides a set of constructs that can be used by a calling application toconstruct a configuration language. The application defines which attributenames and nested block types are expected, and HCL parses the configurationfile, verifies that it conforms to the expected structure, and returnshigh-level objects that the application can use for further processing.

package mainimport ("log""github.com/hashicorp/hcl/v2/hclsimple")typeConfigstruct {IOModestring`hcl:"io_mode"`ServiceServiceConfig`hcl:"service,block"`}typeServiceConfigstruct {Protocolstring`hcl:"protocol,label"`Typestring`hcl:"type,label"`ListenAddrstring`hcl:"listen_addr"`Processes  []ProcessConfig`hcl:"process,block"`}typeProcessConfigstruct {Typestring`hcl:"type,label"`Command []string`hcl:"command"`}funcmain() {varconfigConfigerr:=hclsimple.DecodeFile("config.hcl",nil,&config)iferr!=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 overthe parsing, decoding, and evaluation of configuration. For more information,seethe package documentation.

Newcomers to HCL often ask: why not JSON, YAML, etc?

Whereas JSON and YAML are formats for serializing data structures, HCL isa syntax and API specifically designed for building structured configurationformats.

HCL attempts to strike a compromise between generic serialization formatssuch as JSON and configuration formats built around full programming languagessuch as Ruby. HCL syntax is designed to be easily read and written by humans,and allowsdeclarative logic to permit its use in more complex applications.

HCL is intended as a base syntax for configuration formats builtaround key-value pairs and hierarchical blocks whose structure is well-definedby the calling application, and this definition of the configuration structureallows for better error messages and more convenient definition within thecalling application.

It can't be denied that JSON is very convenient as alingua francafor interoperability between different pieces of software. Because of this,HCL defines a common configuration model that can be parsed from either itsnative syntax or from a well-defined equivalent JSON structure. This allowsconfiguration to be provided as a mixture of human-authored configurationfiles in the native syntax and machine-generated files in JSON.

HCL is built around two primary concepts:attributes andblocks. Innative syntax, a configuration file for a hypothetical application might looksomething like this:

io_mode="async"service"http""web_proxy" {listen_addr="127.0.0.1:8080"process"main" {command=["/usr/local/bin/awesome-app","server"]  }process"mgmt" {command=["/usr/local/bin/awesome-app","mgmt"]  }}

The JSON equivalent of this configuration is the following:

{"io_mode":"async","service": {"http": {"web_proxy": {"listen_addr":"127.0.0.1:8080","process": {"main": {"command": ["/usr/local/bin/awesome-app","server"]          },"mgmt": {"command": ["/usr/local/bin/awesome-app","mgmt"]          },        }      }    }  }}

Regardless of which syntax is used, the API within the calling applicationis the same. It can either work directly with the low-level attributes andblocks, for more advanced use-cases, or it can use one of thedecoderpackages to declaratively extract into either Go structs or dynamic valuestructures.

Attribute values can be expressions as well as just literal values:

# Arithmetic with literals and application-provided variablessum=1+ addend# String interpolation and templatesmessage="Hello,${name}!"# Application-provided functionsshouty_message=upper(message)

Although JSON syntax doesn't permit direct use of expressions, the interpolationsyntax allows use of arbitrary expressions within JSON strings:

{"sum":"${1 + addend}","message":"Hello, ${name}!","shouty_message":"${upper(message)}"}

For more information, see the detailed specifications:

• Syntax-agnostic Information Model
• HCL Native Syntax
• JSON Representation

Version 2.0 of HCL combines the features of HCL 1.0 with those of theinterpolation language HIL to produce a single configuration language thatsupports arbitrary expressions.

This new version has a completely new parser and Go API, with no directmigration path. Although the syntax is similar, the implementation takes somevery different approaches to improve on some "rough edges" that existed withthe original implementation and to allow for more robust error handling.

It's possible to import both HCL 1 and HCL 2 into the same program using Go'ssemantic import versioning mechanism:

import (    hcl1"github.com/hashicorp/hcl"    hcl2"github.com/hashicorp/hcl/v2")

HCL was heavily inspired bylibucl,byVsevolod Stakhov.

HCL and HIL originate inHashiCorp Terraform,with the original parsers for each written byMitchell Hashimoto.

The original HCL parser was ported to pure Go (from yacc) byFatih Arslan. The structure-related portions ofthe new native syntax parser build on that work.

The original HIL parser was ported to pure Go (from yacc) byMartin Atkins. The expression-relatedportions of the new native syntax parser build on that work.

HCL 2, which merged the original HCL and HIL languages into this single newlanguage, builds on design and prototyping work byMartin Atkins inzcl.