errors

Documentation

Index

• func AsError(errorText string) func(loc *SrcLocation)
• func AsHelp(helpText string) func(loc *SrcLocation)
• func AsWarning(warningText string) func(loc *SrcLocation)
• type LocationKind
• type LocationOption
• type LocationType
• type RangeOption
  • func WithRangeSize(size int) RangeOption
• type SrcLocation
• type Template
  • func AtOptionalNode[T ast.Node](err Template, opt option.Option[T]) Template
  • func (t Template) AtGoNode(node goAst.Node, options ...LocationOption) Template
  • func (t Template) AtGoPos(start, end goToken.Pos, options ...LocationOption) Template
  • func (t Template) AtGoPosition(start, end goToken.Position, options ...LocationOption) Template
  • func (t Template) InFile(filepath string, options ...LocationOption) Template
  • func (t Template) WithDetails(details string) Template
  • func (t Template) Wrapping(err error) Template
• type TemplateOption
  • func AlwaysIncludeStack() TemplateOption
  • func MarkAsInternalError() TemplateOption
  • func PrependDetails(details string) TemplateOption
  • func WithDetails(details string) TemplateOption
• type TemplateRange
  • func Range(module string, defaultDetails string, options ...RangeOption) *TemplateRange
  • func (r *TemplateRange) New(title, summary string, options ...TemplateOption) Template
  • func (r *TemplateRange) Newf(title, summaryFmt string, options ...TemplateOption) func(summaryArgs ...any) Template

Functions

func AsError

func AsError(errorText string) func(loc *SrcLocation)

AsError allows you to set a SrcLocation's error text

Pass this option in when you give the error Template a src location

func AsHelp

func AsHelp(helpText string) func(loc *SrcLocation)

AsHelp allows you to set a SrcLocation's text and mark it as a helpful hint

Pass this option in when you give the error Template a src location

func AsWarning

func AsWarning(warningText string) func(loc *SrcLocation)

AsWarning allows you to set a SrcLocation's text and mark it as a warning

Pass this option in when you give the error Template a src location

Types

type LocationKind

type LocationKind uint8

LocationKind tells us what language and position markers we're using to identify the source

const (
	LocFile LocationKind = iota
	LocGoNode
	LocGoPos
	LocGoPositions
)

type LocationOption

type LocationOption func(*SrcLocation)

type LocationType

type LocationType uint8

LocationType represents if the locaton is the source of the error, a warning or a helpful hint

const (
	LocError LocationType = iota
	LocWarning
	LocHelp
)

type RangeOption

type RangeOption func(*rangeConfig)

func WithRangeSize

func WithRangeSize(size int) RangeOption

WithRangeSize sets the size of the range. The default is 100.

type SrcLocation

type SrcLocation struct {
	Kind            LocationKind
	LocType         LocationType
	Text            string
	Filepath        string
	GoNode          goAst.Node
	GoStartPos      goToken.Pos
	GoEndPos        goToken.Pos
	GoStartPosition goToken.Position
	GoEndPosition   goToken.Position
}

SrcLocation tells us where in the code base caused the error, warning or is a hint to the end user.

type Template

type Template struct {
	Code               int
	Title              string
	Summary            string
	Detail             string
	Cause              error
	Locations          []SrcLocation
	AlwaysIncludeStack bool
}

Template represents a template for a new error.

It itself is not an error, but can be used to initialize a new [errorinsrc.ErrInSrc].

func AtOptionalNode

func AtOptionalNode[T ast.Node](err Template, opt option.Option[T]) Template

AtOptionalNode returns an error at the given node if it is present. Otherwise, it returns the error unchanged.

func (Template) AtGoNode

func (t Template) AtGoNode(node goAst.Node, options ...LocationOption) Template

AtGoNode adds the given Go node to the template. If the node is nil, nothing happens.

You can use the [LocationOption]s to add additional information to the location.

Example:

errMyErrorTemplate.AtGoNode(node, errtmp.AsHelp("this is where it was defined before"))

func (Template) AtGoPos

func (t Template) AtGoPos(start, end goToken.Pos, options ...LocationOption) Template

AtGoPos adds the given start and end [token.Pos] to the template. If both positions are token.NoPos, nothing happens. If one of the two positions are token.NoPos, the other position will be used.

It is valid to use the same value for start and end positions, in which case the error will estimate which Node you are referencing.

Example:

errMyErrorTemplate.AtGoPos(start, token.NoPos, errtmp.AsHelp("this is where it was defined before"))

func (Template) AtGoPosition

func (t Template) AtGoPosition(start, end goToken.Position, options ...LocationOption) Template

AtGoPosition adds the given Go positions to the template.

It is valid to use the same value for start and end positions, in which case the error will estimate which Node you are referencing.

Example:

errMyErrorTemplate.AtGoPosition(start, end, errtmp.AsHelp("this is where it was defined before"))

func (Template) InFile

func (t Template) InFile(filepath string, options ...LocationOption) Template

InFile adds the given file as a src of the error location

Note: It is preferable to use one of the other location functions as they will render the source around the error, not just the file name

func (Template) WithDetails

func (t Template) WithDetails(details string) Template

WithDetails will replace the details of the template with the given details

func (Template) Wrapping

func (t Template) Wrapping(err error) Template

Wrapping wraps the given error with the template.

It will append the given error to the summary of the template as well as setting the cause of the template to the given error.

type TemplateOption

type TemplateOption func(*Template)

TemplateOption can be passed into the Range when creating a new Template

func AlwaysIncludeStack

func AlwaysIncludeStack() TemplateOption

AlwaysIncludeStack will setup a Template so it always includes a stack trace even in a production build of Encore.

func MarkAsInternalError

func MarkAsInternalError() TemplateOption

MarkAsInternalError will setup a template so it is reported as an internal error.

This means that the error will be reported to the user as an internal error with a link to the Encore issue tracker and will include a stack trace.

func PrependDetails

func PrependDetails(details string) TemplateOption

PrependDetails will setup a template so it prepends the given details to the range default

func WithDetails

func WithDetails(details string) TemplateOption

WithDetails will setup a template so it uses a different details to the range default

type TemplateRange

type TemplateRange struct {
	// contains filtered or unexported fields
}

TemplateRange is a helper for creating a range of error codes for a given module and generating templates for those errors.

func Range

func Range(
	module string,
	defaultDetails string,
	options ...RangeOption,
) *TemplateRange

Range creates a new error code range for a given module.

func (*TemplateRange) New

func (r *TemplateRange) New(title, summary string, options ...TemplateOption) Template

New creates a new template for an error in this range.

func (*TemplateRange) Newf

func (r *TemplateRange) Newf(title, summaryFmt string, options ...TemplateOption) func(summaryArgs ...any) Template

Newf creates a function to return a template for an error in this range where the summary is a format string.