fork of https://github.com/hashicorp/hcl because issue : https://github.com/hashicorp/hcl/issues/290 these code permit use of "nested" field decoding which is just composite struct
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
RouxAntoine b54debed5c
feat: Support composite struct with nested keyword
1 month ago
.circleci Add win tests to CircleCI; Remove Appveyor (#435) 4 months ago
cmd specsuite: Fix some regressions 1 month ago
ext ext/userfunc: Fix the package documentation link in the README 7 months ago
gohcl feat: Support composite struct with nested keyword 1 month ago
guide Change module path to github.com/hashicorp/hcl/v2 1 year ago
hcldec hcldec: add ValidateSpec 10 months ago
hcled Unfold the "hcl" directory up into the root 1 year ago
hclparse hclparse: Go package documentation 1 year ago
hclsimple hclsimple: Simple one-shot parse/decode/evaluate API 1 year ago
hclsyntax feat: Support composite struct with nested keyword 1 month ago
hcltest add an ExprMap method to the mock expression 2 months ago
hclwrite Use Unicode 13 text segmentation rules 1 month ago
integrationtest ext/customdecode: Custom expression decoding extension 1 year ago
json Use Unicode 13 text segmentation rules 1 month ago
specsuite specsuite: Fix some regressions 1 month ago
CHANGELOG.md v2.9.0 release 1 month ago
LICENSE Relicense under MPL, rather than MIT 3 years ago
README.md hcl: Fix the simple example in the README 7 months ago
diagnostic.go FIX: a couple of typos 1 year ago
diagnostic_text.go Unfold the "hcl" directory up into the root 1 year ago
diagnostic_text_test.go Unfold the "hcl" directory up into the root 1 year ago
didyoumean.go Unfold the "hcl" directory up into the root 1 year ago
doc.go hclsimple: Simple one-shot parse/decode/evaluate API 1 year ago
eval_context.go Unfold the "hcl" directory up into the root 1 year ago
expr_call.go Unfold the "hcl" directory up into the root 1 year ago
expr_list.go Unfold the "hcl" directory up into the root 1 year ago
expr_map.go Unfold the "hcl" directory up into the root 1 year ago
expr_unwrap.go Unfold the "hcl" directory up into the root 1 year ago
go.mod specsuite: Fix some regressions 1 month ago
go.sum specsuite: Fix some regressions 1 month ago
merged.go Unfold the "hcl" directory up into the root 1 year ago
merged_test.go Unfold the "hcl" directory up into the root 1 year ago
ops.go avoid panics with marked index values 1 month ago
ops_test.go avoid panics with marked index values 1 month ago
pos.go Unfold the "hcl" directory up into the root 1 year ago
pos_scanner.go Use Unicode 13 text segmentation rules 1 month ago
pos_scanner_test.go Unfold the "hcl" directory up into the root 1 year ago
pos_test.go Unfold the "hcl" directory up into the root 1 year ago
schema.go feat: Support composite struct with nested keyword 1 month ago
spec.md Unfold the "hcl" directory up into the root 1 year ago
static_expr.go Unfold the "hcl" directory up into the root 1 year ago
structure.go Unfold the "hcl" directory up into the root 1 year ago
structure_at_pos.go Unfold the "hcl" directory up into the root 1 year ago
traversal.go Unfold the "hcl" directory up into the root 1 year ago
traversal_for_expr.go Unfold the "hcl" directory up into the root 1 year ago
traversal_for_expr_test.go Unfold the "hcl" directory up into the root 1 year ago

README.md

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.

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 allows for better error messages and more convenient definition within the calling application.

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

Information Model and Syntax

HCL is built around two primary concepts: attributes and blocks. In native syntax, a configuration file for a hypothetical application might look something 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 application is the same. It can either work directly with the low-level attributes and blocks, for more advanced use-cases, or it can use one of the decoder packages to declaratively extract into either Go structs or dynamic value structures.

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

# Arithmetic with literals and application-provided variables
sum = 1 + addend

# String interpolation and templates
message = "Hello, ${name}!"

# Application-provided functions
shouty_message = upper(message)

Although JSON syntax doesn't permit direct use of expressions, the interpolation syntax 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:

Changes in 2.0

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

This new version has a completely new parser and Go API, with no direct migration path. Although the syntax is similar, the implementation takes some very different approaches to improve on some “rough edges” that existed with the 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's semantic import versioning mechanism:

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

Acknowledgements

HCL was heavily inspired by libucl, by Vsevolod Stakhov.

HCL and HIL originate in HashiCorp Terraform, with the original parsers for each written by Mitchell Hashimoto.

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

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

HCL 2, which merged the original HCL and HIL languages into this single new language, builds on design and prototyping work by Martin Atkins in zcl.