json

Documentation

Overview

Package json is the JSON parser for HCL. It parses JSON files and returns implementations of the core HCL structural interfaces in terms of the JSON data inside.

This is not a generic JSON parser. Instead, it deals with the mapping from the JSON information model to the HCL information model, using a number of hard-coded structural conventions.

In most cases applications will not import this package directly, but will instead access its functionality indirectly through functions in the main "hcl" package and in the "hclparse" package.

Index

• func IsJSONBody(maybeJSONBody hcl.Body) bool
• func IsJSONExpression(maybeJSONExpr hcl.Expression) bool
• func Parse(src []byte, filename string) (*hcl.File, hcl.Diagnostics)
• func ParseExpression(src []byte, filename string) (hcl.Expression, hcl.Diagnostics)
• func ParseExpressionWithStartPos(src []byte, filename string, start hcl.Pos) (hcl.Expression, hcl.Diagnostics)
• func ParseFile(filename string) (*hcl.File, hcl.Diagnostics)
• func ParseWithStartPos(src []byte, filename string, start hcl.Pos) (*hcl.File, hcl.Diagnostics)

Functions

func IsJSONBody

func IsJSONBody(maybeJSONBody hcl.Body) bool

IsJSONBody returns true if and only if the given body is one that originated in a JSON document.

Applications aiming to be syntax-agnostic should not use this function and should instead use the normal schema-driven or "just attributes' decoding APIs.

Howeer, JSON expressions do have a unique behavior whereby various different source JSON shapes can be interpreted in different ways depending on the given schema, and so in exceptional cases an application may need to perform some deeper analysis first in order to distinguish variants of different physical structure.

Caution: The normal HCL API allows for HCL body implementations that wrap other HCL body implementations. This function will return false if given an expression of some other type that encapsulates a JSON body, even if the wrapper implementation would in principle preserve the special decoding behavior of the wrapped body.

func IsJSONExpression

func IsJSONExpression(maybeJSONExpr hcl.Expression) bool

IsJSONExpression returns true if and only if the given expression is one that originated in a JSON document.

Applications aiming to be syntax-agnostic should not use this function and should instead use the normal expression evaluation or static analysis APIs.

However, JSON expressions do have a unique behavior whereby they interpret the source JSON differently depending on the hcl.EvalContext value passed to the Value method -- in particular, a nil hcl.EvalContext returns literal strings rather than interpreting them as HCL template syntax -- and so in exceptional cases an application may wish to rely on that behavior in situations where it specifically knows the expression originated in JSON, in case it needs to do some non-standard handling of the expression in that case.

Caution: The normal HCL API allows for HCL expression implementations that wrap other HCL expression implementations. This function will return false if given an expression of some other type that encapsulates a JSON expression, even if the wrapper implementation would in principle preserve the special evaluation behavior of the wrapped expression.

func Parse

func Parse(src []byte, filename string) (*hcl.File, hcl.Diagnostics)

Parse attempts to parse the given buffer as JSON and, if successful, returns a hcl.File for the HCL configuration represented by it.

This is not a generic JSON parser. Instead, it deals only with the profile of JSON used to express HCL configuration.

The returned file is valid only if the returned diagnostics returns false from its HasErrors method. If HasErrors returns true, the file represents the subset of data that was able to be parsed, which may be none.

func ParseExpression

func ParseExpression(src []byte, filename string) (hcl.Expression, hcl.Diagnostics)

ParseExpression parses the given buffer as a standalone JSON expression, returning it as an instance of Expression.

func ParseExpressionWithStartPos

func ParseExpressionWithStartPos(src []byte, filename string, start hcl.Pos) (hcl.Expression, hcl.Diagnostics)

ParseExpressionWithStartPos parses like json.ParseExpression, but unlike json.ParseExpression you can pass a start position of the given JSON expression as a hcl.Pos.

func ParseFile

func ParseFile(filename string) (*hcl.File, hcl.Diagnostics)

ParseFile is a convenience wrapper around Parse that first attempts to load data from the given filename, passing the result to Parse if successful.

If the file cannot be read, an error diagnostic with nil context is returned.

func ParseWithStartPos

func ParseWithStartPos(src []byte, filename string, start hcl.Pos) (*hcl.File, hcl.Diagnostics)

ParseWithStartPos attempts to parse like json.Parse, but unlike json.Parse you can pass a start position of the given JSON as a hcl.Pos.

In most cases json.Parse should be sufficient, but it can be useful for parsing a part of JSON with correct positions.