tfdiags

Documentation

Overview

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

• type Description
• type Diagnostic
  • func SimpleWarning(msg string) Diagnostic
• type Diagnostics
  • func (diags Diagnostics) Append(new ...interface{}) Diagnostics
  • func (diags Diagnostics) Err() error
  • func (diags Diagnostics) ForRPC() Diagnostics
  • func (diags Diagnostics) HasErrors() bool
• type Severity
  • func (i Severity) String() string
• type Source
• type SourcePos
• type SourceRange
  • func SourceRangeFromHCL(hclRange hcl.Range) SourceRange
  • func (r SourceRange) StartString() string
  • func (r SourceRange) ToHCL() hcl.Range

Types

type Description

type Description struct {
	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.

type Diagnostics

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

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

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

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

func (diags Diagnostics) HasErrors() bool

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

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 SourceRangeFromHCL

func SourceRangeFromHCL(hclRange hcl.Range) SourceRange

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

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.

func (SourceRange) ToHCL

func (r SourceRange) ToHCL() hcl.Range

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