objchange

func ActionForChange ¶ added in v0.13.0

func ActionForChange(before, after cty.Value) plans.Action

ActionForChange determines which plans.Action value best describes a change from the value given in before to the value given in after.

Because it has no context aside from the values, it can only return the basic actions NoOp, Create, Update, and Delete. Other codepaths with additional information might make this decision differently, such as by using the Replace action instead of the Update action where that makes sense.

If the after value is unknown then the action can't be properly decided, and so ActionForChange will conservatively return either Create or Update depending on whether the before value is null. The before value must always be fully known; ActionForChange will panic if it contains any unknown values.

func AllAttributesNull ¶

func AllAttributesNull(attrs map[string]*configschema.Attribute) cty.Value

AllAttributesNull returns a cty.Value of the object type implied by the given attriubutes that has all of its leaf attributes set to null.

func AllBlockAttributesNull ¶ added in v0.15.0

func AllBlockAttributesNull(schema *configschema.Block) cty.Value

AllBlockAttributesNull constructs a non-null cty.Value of the object type implied by the given schema that has all of its leaf attributes set to null and all of its nested block collections set to zero-length.

This simulates what would result from decoding an empty configuration block with the given schema, except that it does not produce errors

func AssertObjectCompatible ¶

func AssertObjectCompatible(schema *configschema.Block, planned, actual cty.Value) []error

AssertObjectCompatible checks whether the given "actual" value is a valid completion of the possibly-partially-unknown "planned" value.

This means that any known leaf value in "planned" must be equal to the corresponding value in "actual", and various other similar constraints.

Any inconsistencies are reported by returning a non-zero number of errors. These errors are usually (but not necessarily) cty.PathError values referring to a particular nested value within the "actual" value.

The two values must have types that conform to the given schema's implied type, or this function will panic.

func AssertPlanValid ¶

func AssertPlanValid(schema *configschema.Block, priorState, config, plannedState cty.Value) []error

AssertPlanValid checks checks whether a planned new state returned by a provider's PlanResourceChange method is suitable to achieve a change from priorState to config. It returns a slice with nonzero length if any problems are detected. Because problems here indicate bugs in the provider that generated the plannedState, they are written with provider developers as an audience, rather than end-users.

All of the given values must have the same type and must conform to the implied type of the given schema, or this function may panic or produce garbage results.

During planning, a provider may only make changes to attributes that are null (unset) in the configuration and are marked as "computed" in the resource type schema, in order to insert any default values the provider may know about. If the default value cannot be determined until apply time, the provider can return an unknown value. Providers are forbidden from planning a change that disagrees with any non-null argument in the configuration.

As a special exception, providers _are_ allowed to provide attribute values conflicting with configuration if and only if the planned value exactly matches the corresponding attribute value in the prior state. The provider can use this to signal that the new value is functionally equivalent to the old and thus no change is required.

func LongestCommonSubsequence ¶

func LongestCommonSubsequence(xs, ys []cty.Value) []cty.Value

LongestCommonSubsequence finds a sequence of values that are common to both x and y, with the same relative ordering as in both collections. This result is useful as a first step towards computing a diff showing added/removed elements in a sequence.

The approached used here is a "naive" one, assuming that both xs and ys will generally be small in most reasonable Terraform configurations. For larger lists the time/space usage may be sub-optimal.

A pair of lists may have multiple longest common subsequences. In that case, the one selected by this function is undefined.

func NormalizeObjectFromLegacySDK ¶

func NormalizeObjectFromLegacySDK(val cty.Value, schema *configschema.Block) cty.Value

NormalizeObjectFromLegacySDK takes an object that may have been generated by the legacy Terraform SDK (i.e. returned from a provider with the LegacyTypeSystem opt-out set) and does its best to normalize it for the assumptions we would normally enforce if the provider had not opted out.

In particular, this function guarantees that a value representing a nested block will never itself be unknown or null, instead representing that as a non-null value that may contain null/unknown values.

The input value must still conform to the implied type of the given schema, or else this function may produce garbage results or panic. This is usually okay because type consistency is enforced when deserializing the value returned from the provider over the RPC wire protocol anyway.

func PlannedDataResourceObject ¶

func PlannedDataResourceObject(schema *configschema.Block, config cty.Value) cty.Value

PlannedDataResourceObject is similar to proposedNewBlock but tailored for planning data resources in particular. Specifically, it replaces the values of any Computed attributes not set in the configuration with an unknown value, which serves as a placeholder for a value to be filled in by the provider when the data resource is finally read.

Data resources are different because the planning of them is handled entirely within Terraform Core and not subject to customization by the provider. This function is, in effect, producing an equivalent result to passing the proposedNewBlock result into a provider's PlanResourceChange function, assuming a fixed implementation of PlanResourceChange that just fills in unknown values as needed.

func ProposedNew ¶ added in v0.15.0

func ProposedNew(schema *configschema.Block, prior, config cty.Value) cty.Value

ProposedNew constructs a proposed new object value by combining the computed attribute values from "prior" with the configured attribute values from "config".

Both value must conform to the given schema's implied type, or this function will panic.

The prior value must be wholly known, but the config value may be unknown or have nested unknown values.

The merging of the two objects includes the attributes of any nested blocks, which will be correlated in a manner appropriate for their nesting mode. Note in particular that the correlation for blocks backed by sets is a heuristic based on matching non-computed attribute values and so it may produce strange results with more "extreme" cases, such as a nested set block where _all_ attributes are computed.