customdiff

Documentation

Overview

Package customdiff provides a set of reusable and composable functions to enable more "declarative" use of the CustomizeDiff mechanism available for resources in package helper/schema.

The intent of these helpers is to make the intent of a set of diff customizations easier to see, rather than lost in a sea of Go function boilerplate. They should _not_ be used in situations where they _obscure_ intent, e.g. by over-using the composition functions where a single function containing normal Go control flow statements would be more straightforward.

Index

• func All(funcs ...schema.CustomizeDiffFunc) schema.CustomizeDiffFunc
• func ComputedIf(key string, f ResourceConditionFunc) schema.CustomizeDiffFunc
• func ForceNewIf(key string, f ResourceConditionFunc) schema.CustomizeDiffFunc
• func ForceNewIfChange(key string, f ValueChangeConditionFunc) schema.CustomizeDiffFunc
• func If(cond ResourceConditionFunc, f schema.CustomizeDiffFunc) schema.CustomizeDiffFunc
• func IfValue(key string, cond ValueConditionFunc, f schema.CustomizeDiffFunc) schema.CustomizeDiffFunc
• func IfValueChange(key string, cond ValueChangeConditionFunc, f schema.CustomizeDiffFunc) schema.CustomizeDiffFunc
• func Sequence(funcs ...schema.CustomizeDiffFunc) schema.CustomizeDiffFunc
• func ValidateChange(key string, f ValueChangeValidationFunc) schema.CustomizeDiffFunc
• func ValidateValue(key string, f ValueValidationFunc) schema.CustomizeDiffFunc
• type ResourceConditionFunc
• type ValueChangeConditionFunc
• type ValueChangeValidationFunc
• type ValueConditionFunc
• type ValueValidationFunc

Functions

func All

func All(funcs ...schema.CustomizeDiffFunc) schema.CustomizeDiffFunc

All returns a CustomizeDiffFunc that runs all of the given CustomizeDiffFuncs and returns all of the errors produced.

If one function produces an error, functions after it are still run. If this is not desirable, use function Sequence instead.

If multiple functions returns errors, the result is a multierror.

For example:

&schema.Resource{
    // ...
    CustomizeDiff: customdiff.All(
        customdiff.ValidateChange("size", func (old, new, meta interface{}) error {
            // If we are increasing "size" then the new value must be
            // a multiple of the old value.
            if new.(int) <= old.(int) {
                return nil
            }
            if (new.(int) % old.(int)) != 0 {
                return fmt.Errorf("new size value must be an integer multiple of old value %d", old.(int))
            }
            return nil
        }),
        customdiff.ForceNewIfChange("size", func (old, new, meta interface{}) bool {
            // "size" can only increase in-place, so we must create a new resource
            // if it is decreased.
            return new.(int) < old.(int)
        }),
        customdiff.ComputedIf("version_id", func (d *schema.ResourceDiff, meta interface{}) bool {
            // Any change to "content" causes a new "version_id" to be allocated.
            return d.HasChange("content")
        }),
    ),
}

func ComputedIf

func ComputedIf(key string, f ResourceConditionFunc) schema.CustomizeDiffFunc

ComputedIf returns a CustomizeDiffFunc that sets the given key's new value as computed if the given condition function returns true.

func ForceNewIf

func ForceNewIf(key string, f ResourceConditionFunc) schema.CustomizeDiffFunc

ForceNewIf returns a CustomizeDiffFunc that flags the given key as requiring a new resource if the given condition function returns true.

The return value of the condition function is ignored if the old and new values of the field compare equal, since no attribute diff is generated in that case.

func ForceNewIfChange

func ForceNewIfChange(key string, f ValueChangeConditionFunc) schema.CustomizeDiffFunc

ForceNewIfChange returns a CustomizeDiffFunc that flags the given key as requiring a new resource if the given condition function returns true.

The return value of the condition function is ignored if the old and new values compare equal, since no attribute diff is generated in that case.

This function is similar to ForceNewIf but provides the condition function only the old and new values of the given key, which leads to more compact and explicit code in the common case where the decision can be made with only the specific field value.

func If

func If(cond ResourceConditionFunc, f schema.CustomizeDiffFunc) schema.CustomizeDiffFunc

If returns a CustomizeDiffFunc that calls the given condition function and then calls the given CustomizeDiffFunc only if the condition function returns true.

This can be used to include conditional customizations when composing customizations using All and Sequence, but should generally be used only in simple scenarios. Prefer directly writing a CustomizeDiffFunc containing a conditional branch if the given CustomizeDiffFunc is already a locally-defined function, since this avoids obscuring the control flow.

func IfValue

func IfValue(key string, cond ValueConditionFunc, f schema.CustomizeDiffFunc) schema.CustomizeDiffFunc

IfValue returns a CustomizeDiffFunc that calls the given condition function with the new values of the given key and then calls the given CustomizeDiffFunc only if the condition function returns true.

func IfValueChange

func IfValueChange(key string, cond ValueChangeConditionFunc, f schema.CustomizeDiffFunc) schema.CustomizeDiffFunc

IfValueChange returns a CustomizeDiffFunc that calls the given condition function with the old and new values of the given key and then calls the given CustomizeDiffFunc only if the condition function returns true.

func Sequence

func Sequence(funcs ...schema.CustomizeDiffFunc) schema.CustomizeDiffFunc

Sequence returns a CustomizeDiffFunc that runs all of the given CustomizeDiffFuncs in sequence, stopping at the first one that returns an error and returning that error.

If all functions succeed, the combined function also succeeds.

func ValidateChange

func ValidateChange(key string, f ValueChangeValidationFunc) schema.CustomizeDiffFunc

ValidateChange returns a CustomizeDiffFunc that applies the given validation function to the change for the given key, returning any error produced.

func ValidateValue

func ValidateValue(key string, f ValueValidationFunc) schema.CustomizeDiffFunc

ValidateValue returns a CustomizeDiffFunc that applies the given validation function to value of the given key, returning any error produced.

This should generally not be used since it is functionally equivalent to a validation function applied directly to the schema attribute in question, but is provided for situations where composing multiple CustomizeDiffFuncs together makes intent clearer than spreading that validation across the schema.

Types

type ResourceConditionFunc

type ResourceConditionFunc func(d *schema.ResourceDiff, meta interface{}) bool

ResourceConditionFunc is a function type that makes a boolean decision based on an entire resource diff.

type ValueChangeConditionFunc

type ValueChangeConditionFunc func(old, new, meta interface{}) bool

ValueChangeConditionFunc is a function type that makes a boolean decision by comparing two values.

type ValueChangeValidationFunc

type ValueChangeValidationFunc func(old, new, meta interface{}) error

ValueChangeValidationFunc is a function type that validates the difference (or lack thereof) between two values, returning an error if the change is invalid.

type ValueConditionFunc

type ValueConditionFunc func(value, meta interface{}) bool

ValueConditionFunc is a function type that makes a boolean decision based on a given value.

type ValueValidationFunc

type ValueValidationFunc func(value, meta interface{}) error

ValueValidationFunc is a function type that validates a particular value, returning an error if the value is invalid.