tbdiags

Documentation

Index

• func FormatCtyPath(path cty.Path) string
• func FormatError(err error) string
• func FormatErrorPrefixed(err error, prefix string) string
• type Description
• type Diagnostic
  • func SimpleWarning(msg string) Diagnostic
  • func Sourceless(severity Severity, summary, detail string) Diagnostic
• type Diagnostics
  • func (diags Diagnostics) Append(new ...interface{}) Diagnostics
  • func (diags Diagnostics) Err() error
  • func (diags Diagnostics) ErrWithWarnings() error
  • func (diags Diagnostics) HasErrors() bool
  • func (diags Diagnostics) NonFatalErr() error
  • func (diags Diagnostics) Sort()
• type NonFatalError
  • func (woe NonFatalError) Error() string
• type Severity
  • func (i Severity) String() string
• type Source
• type SourcePos
• type SourceRange
  • func (r SourceRange) StartString() string

Functions

func FormatCtyPath

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

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

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.

Types

type Description

type Description struct {
	Address string
	Summary string
	Detail  string
}

type Diagnostic

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

func SimpleWarning

func SimpleWarning(msg string) Diagnostic

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

func Sourceless

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.

type Diagnostics

type Diagnostics []Diagnostic

func (Diagnostics) Append

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

func (Diagnostics) Err

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

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) HasErrors

func (diags Diagnostics) HasErrors() bool

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

func (Diagnostics) NonFatalErr

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

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 NonFatalError

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

func (woe NonFatalError) Error() string

type Severity

type Severity rune

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

func (Severity) String

func (i Severity) String() string

type Source

type Source struct {
	Subject *SourceRange
	Context *SourceRange
}

type SourcePos

type SourcePos struct {
	Line, Column, Byte int
}

type SourceRange

type SourceRange struct {
	Filename   string
	Start, End SourcePos
}

func (SourceRange) StartString

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.