format

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

• func Diagnostic(diag tfdiags.Diagnostic, sources map[string][]byte, ...) string
• func DiagnosticFromJSON(diag *viewsjson.Diagnostic, color *colorstring.Colorize, width int) string
• func DiagnosticPlain(diag tfdiags.Diagnostic, sources map[string][]byte, width int) string
• func DiagnosticPlainFromJSON(diag *viewsjson.Diagnostic, width int) string
• func DiagnosticWarningsCompact(diags tfdiags.Diagnostics, color *colorstring.Colorize) string
• func DiffActionSymbol(action plans.Action) string
• func HorizontalRule(color *colorstring.Colorize, width int) string
• func ObjectValueID(obj cty.Value) (k, v string)
• func ObjectValueIDOrName(obj cty.Value) (k, v string)
• func ObjectValueName(obj cty.Value) (k, v string)
• func OutputChanges(changes []*plans.OutputChangeSrc, color *colorstring.Colorize) string
• func ResourceChange(change *plans.ResourceInstanceChangeSrc, schema *configschema.Block, ...) string
• func ResourceInstanceDrift(addr addrs.AbsResourceInstance, before, after *states.ResourceInstance, ...) string
• func State(opts *StateOpts) string
• func WordWrap(str string, width int) string
• type StateOpts

Functions

func Diagnostic

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 DiagnosticFromJSON

func DiagnosticFromJSON(diag *viewsjson.Diagnostic, color *colorstring.Colorize, width int) string

func DiagnosticPlain

func DiagnosticPlain(diag tfdiags.Diagnostic, sources map[string][]byte, width int) string

DiagnosticPlain is an alternative to Diagnostic which minimises the use of virtual terminal formatting sequences.

It is intended for use in automation and other contexts in which diagnostic messages are parsed from the Terraform output.

func DiagnosticPlainFromJSON

func DiagnosticPlainFromJSON(diag *viewsjson.Diagnostic, width int) string

func DiagnosticWarningsCompact

func DiagnosticWarningsCompact(diags tfdiags.Diagnostics, color *colorstring.Colorize) string

DiagnosticWarningsCompact is an alternative to Diagnostic for when all of the given diagnostics are warnings and we want to show them compactly, with only two lines per warning and excluding all of the detail information.

The caller may optionally pre-process the given diagnostics with ConsolidateWarnings, in which case this function will recognize consolidated messages and include an indication that they are consolidated.

Do not pass non-warning diagnostics to this function, or the result will be nonsense.

func DiffActionSymbol

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 HorizontalRule

func HorizontalRule(color *colorstring.Colorize, width int) string

HorizontalRule returns a newline character followed by a number of horizontal line characters to fill the given width.

If the given colorize has colors enabled, the rule will also be given a dark grey color to attempt to visually de-emphasize it for sighted users.

This is intended for printing to the UI via mitchellh/cli.UI.Output, or similar, which will automatically append a trailing newline too.

func ObjectValueID

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

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

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 OutputChanges

func OutputChanges(
	changes []*plans.OutputChangeSrc,
	color *colorstring.Colorize,
) string

OutputChanges returns a string representation of a set of changes to output values for inclusion in user-facing plan output.

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

func ResourceChange

func ResourceChange(
	change *plans.ResourceInstanceChangeSrc,
	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 ResourceInstanceDrift

func ResourceInstanceDrift(
	addr addrs.AbsResourceInstance,
	before, after *states.ResourceInstance,
	schema *configschema.Block,
	color *colorstring.Colorize,
) string

ResourceInstanceDrift returns a string representation of a change to a particular resource instance that was made outside of Terraform, for reporting a change that has already happened rather than one that is planned.

The the two resource instances have equal current objects then the result will be an empty string to indicate that there is no drift to render.

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

func WordWrap

func WordWrap(str string, width int) string

WordWrap takes a string containing unbroken lines of text and inserts newline characters to try to make the text fit within the given width.

The string can already contain newline characters, for example if you are trying to render multiple paragraphs of text. (In that case, our usual style would be to have _two_ newline characters as the paragraph separator.)

As a special case, any line that begins with at least one space will be left unbroken. This allows including literal segments in the output, such as code snippets or filenames, where word wrapping would be confusing.

Types

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.