hcl2shim

Documentation

Index

• Constants
• func ConfigValueFromHCL2(v cty.Value) interface{}
• func ConfigValueFromHCL2Block(v cty.Value, schema *configschema.Block) map[string]interface{}
• func ConvertJSONExpressionToHCL(expr hcl.Expression) (hcl.Expression, hcl.Diagnostics)
• func ExprIsNativeQuotedString(expr hcl.Expression) bool
• func FlatmapKeyFromPath(path cty.Path) string
• func FlatmapValueFromHCL2(v cty.Value) map[string]string
• func HCL2ValueFromConfigValue(v interface{}) cty.Value
• func HCL2ValueFromFlatmap(m map[string]string, ty cty.Type) (cty.Value, error)
• func MergeBodies(base, override hcl.Body) hcl.Body
• func RequiresReplace(attrs []string, ty cty.Type) ([]cty.Path, error)
• func SchemaForOverrides(schema *hcl.BodySchema) *hcl.BodySchema
• func SynthBody(filename string, values map[string]cty.Value) hcl.Body
• func ValuesSDKEquivalent(a, b cty.Value) bool
• type SingleAttrBody
  • func (b SingleAttrBody) Content(schema *hcl2.BodySchema) (*hcl2.BodyContent, hcl2.Diagnostics)
  • func (b SingleAttrBody) JustAttributes() (hcl2.Attributes, hcl2.Diagnostics)
  • func (b SingleAttrBody) MissingItemRange() hcl2.Range
  • func (b SingleAttrBody) PartialContent(schema *hcl2.BodySchema) (*hcl2.BodyContent, hcl2.Body, hcl2.Diagnostics)

Constants

const UnknownVariableValue = "74D93920-ED26-11E3-AC10-0800200C9A66"

UnknownVariableValue is a sentinel value that can be used to denote that the value of a variable is unknown at this time. RawConfig uses this information to build up data about unknown keys.

Functions

func ConfigValueFromHCL2

func ConfigValueFromHCL2(v cty.Value) interface{}

ConfigValueFromHCL2 converts a value from HCL2 (really, from the cty dynamic types library that HCL2 uses) to a value type that matches what would've been produced from the HCL-based interpolator for an equivalent structure.

This function will transform a cty null value into a Go nil value, which isn't a possible outcome of the HCL/HIL-based decoder and so callers may need to detect and reject any null values.

func ConfigValueFromHCL2Block

func ConfigValueFromHCL2Block(v cty.Value, schema *configschema.Block) map[string]interface{}

ConfigValueFromHCL2Block is like ConfigValueFromHCL2 but it works only for known object values and uses the provided block schema to perform some additional normalization to better mimic the shape of value that the old HCL1/HIL-based codepaths would've produced.

In particular, it discards the collections that we use to represent nested blocks (other than NestingSingle) if they are empty, which better mimics the HCL1 behavior because HCL1 had no knowledge of the schema and so didn't know that an unspecified block _could_ exist.

The given object value must conform to the schema's implied type or this function will panic or produce incorrect results.

This is primarily useful for the final transition from new-style values to tofu.ResourceConfig before calling to a legacy provider, since helper/schema (the old provider SDK) is particularly sensitive to these subtle differences within its validation code.

func ConvertJSONExpressionToHCL

func ConvertJSONExpressionToHCL(expr hcl.Expression) (hcl.Expression, hcl.Diagnostics)

ConvertJSONExpressionToHCL is used to convert HCL *json.expression into regular hcl syntax. Sometimes, we manually parse an expression instead of using the hcl library for parsing. In this case we need to handle json configs specially, as the values will be json strings rather than hcl.

func ExprIsNativeQuotedString

func ExprIsNativeQuotedString(expr hcl.Expression) bool

exprIsNativeQuotedString determines whether the given expression looks like it's a quoted string in the HCL native syntax.

This should be used sparingly only for situations where our legacy HCL decoding would've expected a keyword or reference in quotes but our new decoding expects the keyword or reference to be provided directly as an identifier-based expression.

func FlatmapKeyFromPath

func FlatmapKeyFromPath(path cty.Path) string

FlatmapKeyFromPath returns the flatmap equivalent of the given cty.Path for use in generating legacy style diffs.

func FlatmapValueFromHCL2

func FlatmapValueFromHCL2(v cty.Value) map[string]string

FlatmapValueFromHCL2 converts a value from HCL2 (really, from the cty dynamic types library that HCL2 uses) to a map compatible with what would be produced by the "flatmap" package.

The type of the given value informs the structure of the resulting map. The value must be of an object type or this function will panic.

Flatmap values can only represent maps when they are of primitive types, so the given value must not have any maps of complex types or the result is undefined.

func HCL2ValueFromConfigValue

func HCL2ValueFromConfigValue(v interface{}) cty.Value

HCL2ValueFromConfigValue is the opposite of configValueFromHCL2: it takes a value as would be returned from the old interpolator and turns it into a cty.Value so it can be used within, for example, an HCL2 EvalContext.

func HCL2ValueFromFlatmap

func HCL2ValueFromFlatmap(m map[string]string, ty cty.Type) (cty.Value, error)

HCL2ValueFromFlatmap converts a map compatible with what would be produced by the "flatmap" package to a HCL2 (really, the cty dynamic types library that HCL2 uses) object type.

The intended result type must be provided in order to guide how the map contents are decoded. This must be an object type or this function will panic.

Flatmap values can only represent maps when they are of primitive types, so the given type must not have any maps of complex types or the result is undefined.

The result may contain null values if the given map does not contain keys for all of the different key paths implied by the given type.

func MergeBodies

func MergeBodies(base, override hcl.Body) hcl.Body

MergeBodies creates a new HCL body that contains a combination of the given base and override bodies. Attributes and blocks defined in the override body take precedence over those of the same name defined in the base body.

If any block of a particular type appears in "override" then it will replace _all_ of the blocks of the same type in "base" in the new body.

func RequiresReplace

func RequiresReplace(attrs []string, ty cty.Type) ([]cty.Path, error)

RequiresReplace takes a list of flatmapped paths from a InstanceDiff.Attributes along with the corresponding cty.Type, and returns the list of the cty.Paths that are flagged as causing the resource replacement (RequiresNew). This will filter out redundant paths, paths that refer to flatmapped indexes (e.g. "#", "%"), and will return any changes within a set as the path to the set itself.

func SchemaForOverrides

func SchemaForOverrides(schema *hcl.BodySchema) *hcl.BodySchema

schemaForOverrides takes a *hcl.BodySchema and produces a new one that is equivalent except that any required attributes are forced to not be required.

This is useful for dealing with "override" config files, which are allowed to omit things that they don't wish to override from the main configuration.

The returned schema may have some pointers in common with the given schema, so neither the given schema nor the returned schema should be modified after using this function in order to avoid confusion.

Overrides are rarely used, so it's recommended to just create the override schema on the fly only when it's needed, rather than storing it in a global variable as we tend to do for a primary schema.

func SynthBody

func SynthBody(filename string, values map[string]cty.Value) hcl.Body

SynthBody produces a synthetic hcl.Body that behaves as if it had attributes corresponding to the elements given in the values map.

This is useful in situations where, for example, values provided on the command line can override values given in configuration, using MergeBodies.

The given filename is used in case any diagnostics are returned. Since the created body is synthetic, it is likely that this will not be a "real" filename. For example, if from a command line argument it could be a representation of that argument's name, such as "-var=...".

func ValuesSDKEquivalent

func ValuesSDKEquivalent(a, b cty.Value) bool

ValuesSDKEquivalent returns true if both of the given values seem equivalent as far as the legacy SDK diffing code would be concerned.

Since SDK diffing is a fuzzy, inexact operation, this function is also fuzzy and inexact. It will err on the side of returning false if it encounters an ambiguous situation. Ambiguity is most common in the presence of sets because in practice it is impossible to exactly correlate nonequal-but-equivalent set elements because they have no identity separate from their value.

This must be used _only_ for comparing values for equivalence within the SDK planning code. It is only meaningful to compare the "prior state" provided by OpenTofu Core with the "planned new state" produced by the legacy SDK code via shims. In particular it is not valid to use this function with their the config value or the "proposed new state" value because they contain only the subset of data that OpenTofu Core itself is able to determine.

Types

type SingleAttrBody

type SingleAttrBody struct {
	Name string
	Expr hcl2.Expression
}

SingleAttrBody is a weird implementation of hcl2.Body that acts as if it has a single attribute whose value is the given expression.

This is used to shim Resource.RawCount and Output.RawConfig to behave more like they do in the old HCL loader.

func (SingleAttrBody) Content

func (b SingleAttrBody) Content(schema *hcl2.BodySchema) (*hcl2.BodyContent, hcl2.Diagnostics)

func (SingleAttrBody) JustAttributes

func (b SingleAttrBody) JustAttributes() (hcl2.Attributes, hcl2.Diagnostics)

func (SingleAttrBody) MissingItemRange

func (b SingleAttrBody) MissingItemRange() hcl2.Range

func (SingleAttrBody) PartialContent

func (b SingleAttrBody) PartialContent(schema *hcl2.BodySchema) (*hcl2.BodyContent, hcl2.Body, hcl2.Diagnostics)