format

package
v0.12.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 12, 2019 License: MPL-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package format contains helpers for formatting various Terraform structures for human-readabout output.

This package is used by the official Terraform CLI in formatting any output and is exported to encourage non-official frontends to mimic the output formatting as much as possible so that text formats of Terraform structures have a consistent look and feel.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Diagnostic added in v0.10.8

func Diagnostic(diag tfdiags.Diagnostic, sources map[string][]byte, color *colorstring.Colorize, width int) string

Diagnostic formats a single diagnostic message.

The width argument specifies at what column the diagnostic messages will be wrapped. If set to zero, messages will not be wrapped by this function at all. Although the long-form text parts of the message are wrapped, not all aspects of the message are guaranteed to fit within the specified terminal width.

func DiffActionSymbol added in v0.10.4

func DiffActionSymbol(action plans.Action) string

DiffActionSymbol returns a string that, once passed through a colorstring.Colorize, will produce a result that can be written to a terminal to produce a symbol made of three printable characters, possibly interspersed with VT100 color codes.

func ObjectValueID added in v0.12.0

func ObjectValueID(obj cty.Value) (k, v string)

ObjectValueID takes a value that is assumed to be an object representation of some resource instance object and attempts to heuristically find an attribute of it that is likely to be a unique identifier in the remote system that it belongs to which will be useful to the user.

If such an attribute is found, its name and string value intended for display are returned. Both returned strings are empty if no such attribute exists, in which case the caller should assume that the resource instance address within the Terraform configuration is the best available identifier.

This is only a best-effort sort of thing, relying on naming conventions in our resource type schemas. The result is not guaranteed to be unique, but should generally be suitable for display to an end-user anyway.

This function will panic if the given value is not of an object type.

func ObjectValueIDOrName added in v0.12.0

func ObjectValueIDOrName(obj cty.Value) (k, v string)

ObjectValueIDOrName is a convenience wrapper around both ObjectValueID and ObjectValueName (in that preference order) to try to extract some sort of human-friendly descriptive string value for an object as additional context about an object when it is being displayed in a compact way (where not all of the attributes are visible.)

Just as with the two functions it wraps, it is a best-effort and may return two empty strings if no suitable attribute can be found for a given object.

func ObjectValueName added in v0.12.0

func ObjectValueName(obj cty.Value) (k, v string)

ObjectValueName takes a value that is assumed to be an object representation of some resource instance object and attempts to heuristically find an attribute of it that is likely to be a human-friendly name in the remote system that it belongs to which will be useful to the user.

If such an attribute is found, its name and string value intended for display are returned. Both returned strings are empty if no such attribute exists, in which case the caller should assume that the resource instance address within the Terraform configuration is the best available identifier.

This is only a best-effort sort of thing, relying on naming conventions in our resource type schemas. The result is not guaranteed to be unique, but should generally be suitable for display to an end-user anyway.

Callers that use both ObjectValueName and ObjectValueID at the same time should be prepared to get the same attribute key and value from both in some cases, since there is overlap betweek the id-extraction and name-extraction heuristics.

This function will panic if the given value is not of an object type.

func ResourceChange added in v0.12.0

func ResourceChange(
	change *plans.ResourceInstanceChangeSrc,
	tainted bool,
	schema *configschema.Block,
	color *colorstring.Colorize,
) string

ResourceChange returns a string representation of a change to a particular resource, for inclusion in user-facing plan output.

The resource schema must be provided along with the change so that the formatted change can reflect the configuration structure for the associated resource.

If "color" is non-nil, it will be used to color the result. Otherwise, no color codes will be included.

func State

func State(opts *StateOpts) string

State takes a state and returns a string

Types

type AttributeDiff added in v0.10.4

type AttributeDiff struct {
	// Path is a dot-delimited traversal through possibly many levels of list and map structure,
	// intended for display purposes only.
	Path string

	Action plans.Action

	OldValue string
	NewValue string

	NewComputed bool
	Sensitive   bool
	ForcesNew   bool
}

AttributeDiff is a representation of an attribute diff optimized for display, in conjunction with DisplayInstanceDiff.

type InstanceDiff added in v0.10.4

type InstanceDiff struct {
	Addr   *terraform.ResourceAddress
	Action plans.Action

	// Attributes describes changes to the attributes of the instance.
	//
	// For destroy diffs this is always nil.
	Attributes []*AttributeDiff

	Tainted bool
	Deposed bool
}

InstanceDiff is a representation of an instance diff optimized for display, in conjunction with DisplayPlan.

type Plan

type Plan struct {
	Resources []*InstanceDiff
}

Plan is a representation of a plan optimized for display to an end-user, as opposed to terraform.Plan which is for internal use.

DisplayPlan excludes implementation details that may otherwise appear in the main plan, such as destroy actions on data sources (which are there only to clean up the state).

func NewPlan added in v0.10.4

func NewPlan(changes *plans.Changes) *Plan

NewPlan produces a display-oriented Plan from a terraform.Plan.

func (*Plan) ActionCounts added in v0.10.4

func (p *Plan) ActionCounts() map[plans.Action]int

ActionCounts returns the number of diffs for each action type

func (*Plan) Empty added in v0.10.4

func (p *Plan) Empty() bool

Empty returns true if there is at least one resource diff in the receiving plan.

func (*Plan) Format added in v0.10.4

func (p *Plan) Format(color *colorstring.Colorize) string

Format produces and returns a text representation of the receiving plan intended for display in a terminal.

If color is not nil, it is used to colorize the output.

func (*Plan) Stats added in v0.10.4

func (p *Plan) Stats() PlanStats

Stats returns statistics about the plan

type PlanStats added in v0.10.4

type PlanStats struct {
	ToAdd, ToChange, ToDestroy int
}

PlanStats gives summary counts for a Plan.

type StateOpts

type StateOpts struct {
	// State is the state to format. This is required.
	State *states.State

	// Schemas are used to decode attributes. This is required.
	Schemas *terraform.Schemas

	// Color is the colorizer. This is optional.
	Color *colorstring.Colorize
}

StateOpts are the options for formatting a state.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL