terraform: github.com/hashicorp/terraform/tfdiags Index | Files

package tfdiags

import "github.com/hashicorp/terraform/tfdiags"

Package tfdiags is a utility package for representing errors and warnings in a manner that allows us to produce good messages for the user.

"diag" is short for "diagnostics", and is meant as a general word for feedback to a user about potential or actual problems.

A design goal for this package is for it to be able to provide rich messaging where possible but to also be pragmatic about dealing with generic errors produced by system components that _can't_ provide such rich messaging. As a consequence, the main types in this package -- Diagnostics and Diagnostic -- are designed so that they can be "smuggled" over an error channel and then be unpacked at the other end, so that error diagnostics (at least) can transit through APIs that are not aware of this package.

Index

Package Files

config_traversals.go contextual.go diagnostic.go diagnostic_base.go diagnostics.go doc.go error.go hcl.go rpc_friendly.go severity_string.go simple_warning.go source_range.go sourceless.go

func FormatCtyPath Uses

func FormatCtyPath(path cty.Path) string

FormatCtyPath is a helper function to produce a user-friendly string representation of a cty.Path. The result uses a syntax similar to the HCL expression language in the hope of it being familiar to users.

func FormatError Uses

func FormatError(err error) string

FormatError is a helper function to produce a user-friendly string representation of certain special error types that we might want to include in diagnostic messages.

This currently has special behavior only for cty.PathError, where a non-empty path is rendered in a HCL-like syntax as context.

func FormatErrorPrefixed Uses

func FormatErrorPrefixed(err error, prefix string) string

FormatErrorPrefixed is like FormatError except that it presents any path information after the given prefix string, which is assumed to contain an HCL syntax representation of the value that errors are relative to.

func GetAttribute Uses

func GetAttribute(d Diagnostic) cty.Path

GetAttribute extracts an attribute cty.Path from a diagnostic if it contains one. Normally this is not accessed directly, and instead the config body is added to the Diagnostic to create a more complete message for the user. In some cases however, we may want to know just the name of the attribute that generated the Diagnostic message. This returns a nil cty.Path if it does not exist in the Diagnostic.

type Description Uses

type Description struct {
    Summary string
    Detail  string
}

type Diagnostic Uses

type Diagnostic interface {
    Severity() Severity
    Description() Description
    Source() Source

    // FromExpr returns the expression-related context for the diagnostic, if
    // available. Returns nil if the diagnostic is not related to an
    // expression evaluation.
    FromExpr() *FromExpr
}

func AttributeValue Uses

func AttributeValue(severity Severity, summary, detail string, attrPath cty.Path) Diagnostic

AttributeValue returns a diagnostic about an attribute value in an implied current configuration context. This should be returned only from functions whose interface specifies a clear configuration context that this will be resolved in.

The given path is relative to the implied configuration context. To describe a top-level attribute, it should be a single-element cty.Path with a cty.GetAttrStep. It's assumed that the path is returning into a structure that would be produced by our conventions in the configschema package; it may return unexpected results for structures that can't be represented by configschema.

Since mapping attribute paths back onto configuration is an imprecise operation (e.g. dynamic block generation may cause the same block to be evaluated multiple times) the diagnostic detail should include the attribute name and other context required to help the user understand what is being referenced in case the identified source range is not unique.

The returned attribute will not have source location information until context is applied to the containing diagnostics using diags.InConfigBody. After context is applied, the source location is the value assigned to the named attribute, or the containing body's "missing item range" if no value is present.

func SimpleWarning Uses

func SimpleWarning(msg string) Diagnostic

SimpleWarning constructs a simple (summary-only) warning diagnostic.

func Sourceless Uses

func Sourceless(severity Severity, summary, detail string) Diagnostic

Sourceless creates and returns a diagnostic with no source location information. This is generally used for operational-type errors that are caused by or relate to the environment where Terraform is running rather than to the provided configuration.

func WholeContainingBody Uses

func WholeContainingBody(severity Severity, summary, detail string) Diagnostic

WholeContainingBody returns a diagnostic about the body that is an implied current configuration context. This should be returned only from functions whose interface specifies a clear configuration context that this will be resolved in.

The returned attribute will not have source location information until context is applied to the containing diagnostics using diags.InConfigBody. After context is applied, the source location is currently the missing item range of the body. In future, this may change to some other suitable part of the containing body.

type Diagnostics Uses

type Diagnostics []Diagnostic

Diagnostics is a list of diagnostics. Diagnostics is intended to be used where a Go "error" might normally be used, allowing richer information to be conveyed (more context, support for warnings).

A nil Diagnostics is a valid, empty diagnostics list, thus allowing heap allocation to be avoided in the common case where there are no diagnostics to report at all.

func (Diagnostics) Append Uses

func (diags Diagnostics) Append(new ...interface{}) Diagnostics

Append is the main interface for constructing Diagnostics lists, taking an existing list (which may be nil) and appending the new objects to it after normalizing them to be implementations of Diagnostic.

The usual pattern for a function that natively "speaks" diagnostics is:

// Create a nil Diagnostics at the start of the function
var diags diag.Diagnostics

// At later points, build on it if errors / warnings occur:
foo, err := DoSomethingRisky()
if err != nil {
    diags = diags.Append(err)
}

// Eventually return the result and diagnostics in place of error
return result, diags

Append accepts a variety of different diagnostic-like types, including native Go errors and HCL diagnostics. It also knows how to unwrap a multierror.Error into separate error diagnostics. It can be passed another Diagnostics to concatenate the two lists. If given something it cannot handle, this function will panic.

func (Diagnostics) Err Uses

func (diags Diagnostics) Err() error

Err flattens a diagnostics list into a single Go error, or to nil if the diagnostics list does not include any error-level diagnostics.

This can be used to smuggle diagnostics through an API that deals in native errors, but unfortunately it will lose naked warnings (warnings that aren't accompanied by at least one error) since such APIs have no mechanism through which to report these.

return result, diags.Error()

func (Diagnostics) ErrWithWarnings Uses

func (diags Diagnostics) ErrWithWarnings() error

ErrWithWarnings is similar to Err except that it will also return a non-nil error if the receiver contains only warnings.

In the warnings-only situation, the result is guaranteed to be of dynamic type NonFatalError, allowing diagnostics-aware callers to type-assert and unwrap it, treating it as non-fatal.

This should be used only in contexts where the caller is able to recognize and handle NonFatalError. For normal callers that expect a lack of errors to be signaled by nil, use just Diagnostics.Err.

func (Diagnostics) ForRPC Uses

func (diags Diagnostics) ForRPC() Diagnostics

ForRPC returns a version of the receiver that has been simplified so that it is friendly to RPC protocols.

Currently this means that it can be serialized with encoding/gob and subsequently re-inflated. It may later grow to include other serialization formats.

Note that this loses information about the original objects used to construct the diagnostics, so e.g. the errwrap API will not work as expected on an error-wrapped Diagnostics that came from ForRPC.

func (Diagnostics) HasErrors Uses

func (diags Diagnostics) HasErrors() bool

HasErrors returns true if any of the diagnostics in the list have a severity of Error.

func (Diagnostics) InConfigBody Uses

func (d Diagnostics) InConfigBody(body hcl.Body) Diagnostics

InConfigBody returns a copy of the receiver with any config-contextual diagnostics elaborated in the context of the given body.

func (Diagnostics) NonFatalErr Uses

func (diags Diagnostics) NonFatalErr() error

NonFatalErr is similar to Err except that it always returns either nil (if there are no diagnostics at all) or NonFatalError.

This allows diagnostics to be returned over an error return channel while being explicit that the diagnostics should not halt processing.

This should be used only in contexts where the caller is able to recognize and handle NonFatalError. For normal callers that expect a lack of errors to be signaled by nil, use just Diagnostics.Err.

func (Diagnostics) Sort Uses

func (diags Diagnostics) Sort()

Sort applies an ordering to the diagnostics in the receiver in-place.

The ordering is: warnings before errors, sourceless before sourced, short source paths before long source paths, and then ordering by position within each file.

Diagnostics that do not differ by any of these sortable characteristics will remain in the same relative order after this method returns.

type FromExpr Uses

type FromExpr struct {
    Expression  hcl.Expression
    EvalContext *hcl.EvalContext
}

type NonFatalError Uses

type NonFatalError struct {
    Diagnostics
}

NonFatalError is a special error type, returned by Diagnostics.ErrWithWarnings and Diagnostics.NonFatalErr, that indicates that the wrapped diagnostics should be treated as non-fatal. Callers can conditionally type-assert an error to this type in order to detect the non-fatal scenario and handle it in a different way.

func (NonFatalError) Error Uses

func (woe NonFatalError) Error() string

type Severity Uses

type Severity rune
const (
    Error   Severity = 'E'
    Warning Severity = 'W'
)

func (Severity) String Uses

func (i Severity) String() string

type Source Uses

type Source struct {
    Subject *SourceRange
    Context *SourceRange
}

type SourcePos Uses

type SourcePos struct {
    Line, Column, Byte int
}

type SourceRange Uses

type SourceRange struct {
    Filename   string
    Start, End SourcePos
}

func SourceRangeFromHCL Uses

func SourceRangeFromHCL(hclRange hcl.Range) SourceRange

SourceRangeFromHCL constructs a SourceRange from the corresponding range type within the HCL package.

func (SourceRange) StartString Uses

func (r SourceRange) StartString() string

StartString returns a string representation of the start of the range, including the filename and the line and column numbers.

func (SourceRange) ToHCL Uses

func (r SourceRange) ToHCL() hcl.Range

ToHCL constructs a HCL Range from the receiving SourceRange. This is the opposite of SourceRangeFromHCL.

Package tfdiags imports 13 packages (graph) and is imported by 206 packages. Updated 2019-06-09. Refresh now. Tools for package owners.