diag

Documentation

Overview

Package diag contains building blocks for formatting and processing diagnostic information.

Index

• Variables
• func PackErrors[T ErrorTag](errs []*Error[T]) error
• func ShowError(w io.Writer, err error)
• type Context
  • func NewContext(name, source string, r Ranger) *Context
  • func (c *Context) Show(indent string) string
• type Error
  • func UnpackErrors[T ErrorTag](err error) []*Error[T]
  • func (e *Error[T]) Error() string
  • func (e *Error[T]) Range() Ranging
  • func (e *Error[T]) Show(indent string) string
• type ErrorTag
• type RangeError
• type Ranger
• type Ranging
  • func MixedRanging(a, b Ranger) Ranging
  • func PointRanging(p int) Ranging
  • func (r Ranging) Range() Ranging
• type Shower

Variables

var (
	ContextBodyStartMarker = "\033[1;4m"
	ContextBodyEndMarker   = "\033[m"
)

Variables controlling the style used in *Context.Show. Can be overridden in tests.

Functions

func PackErrors

func PackErrors[T ErrorTag](errs []*Error[T]) error

PackErrors packs multiple instances of Error with the same tag into one error:

• If called with no errors, it returns nil.

• If called with one error, it returns that error itself.

• If called with more than one Error, it returns an error that combines all of them. The returned error also implements Shower, and its Error and Show methods only print the tag once.

func ShowError

func ShowError(w io.Writer, err error)

ShowError shows an error. It uses the Show method if the error implements Shower. Otherwise, it prints the error in bold and red, with a trailing newline.

Types

type Context

type Context struct {
	Name string
	Ranging
	// 1-based line and column numbers of the start position.
	StartLine, StartCol int
	// 1-based line and column numbers of the end position, inclusive. Note that
	// if the range is zero-width, EndCol will be StartCol - 1.
	EndLine, EndCol int
	// The relevant text, text before its the first line and the text after its
	// last line.
	Body, Head, Tail string
}

Context stores information derived from a range in some text. It is used for errors that point to a part of the source code, including parse errors, compilation errors and a single traceback entry in an exception.

Context values should only be constructed using NewContext.

func NewContext

func NewContext(name, source string, r Ranger) *Context

NewContext creates a new Context.

func (*Context) Show

func (c *Context) Show(indent string) string

Show shows the context.

If the body has only one line, it returns one line like:

foo.elv:12:7-11: lorem ipsum

If the body has multiple lines, it shows the body in an indented block:

foo.elv:12:1-13:5
  lorem
  ipsum

The body is underlined.

type Error

type Error[T ErrorTag] struct {
	Message string
	Context Context
	// Indicates whether the error may be caused by partial input. More
	// formally, this field should be true iff there exists a string x such that
	// appending it to the input eliminates the error.
	Partial bool
}

Error represents an error with context that can be showed.

func UnpackErrors

func UnpackErrors[T ErrorTag](err error) []*Error[T]

UnpackErrors returns the constituent Error instances in an error if it is built from PackErrors. Otherwise it returns nil.

func (*Error[T]) Error

func (e *Error[T]) Error() string

Error returns a plain text representation of the error.

func (*Error[T]) Range

func (e *Error[T]) Range() Ranging

Range returns the range of the error.

func (*Error[T]) Show

func (e *Error[T]) Show(indent string) string

Show shows the error.

type ErrorTag

type ErrorTag interface {
	ErrorTag() string
}

ErrorTag is used to parameterize Error into different concrete types. The ErrorTag method is called with a zero receiver, and its return value is used in Error.Error and Error.Show.

type RangeError

type RangeError interface {
	error
	Ranger
}

RangeError combines error with Ranger.

type Ranger

type Ranger interface {
	// Range returns the range associated with the value.
	Range() Ranging
}

Ranger wraps the Range method.

type Ranging

type Ranging struct {
	From int
	To   int
}

Ranging represents a range [From, To) within an indexable sequence. Structs can embed Ranging to satisfy the Ranger interface.

Ideally, this type would be called Range. However, doing that means structs embedding this type will have Range as a field instead of a method, thus not implementing the Ranger interface.

func MixedRanging

func MixedRanging(a, b Ranger) Ranging

MixedRanging returns a Ranging from the start position of a to the end position of b.

func PointRanging

func PointRanging(p int) Ranging

PointRanging returns a zero-width Ranging at the given point.

func (Ranging) Range

func (r Ranging) Range() Ranging

Range returns the Ranging itself.

type Shower

type Shower interface {
	// Show takes an indentation string and shows.
	Show(indent string) string
}

Shower wraps the Show function.