errors

Documentation

Overview

Package errors provides a location tracking and error formatting system. It provides a way to keep track of the in-file position of the physical text that in-memory data structures were derived from, and a way to use this positional information to create informative and easy to read errors.

Index

• func Format(err error) string
• type Error
  • func Errorf(position Position, format string, variables ...any) Error
• type Position
  • func (pos Position) Format() string
  • func (pos Position) String() string
  • func (pos Position) Union(other Position) Position

Functions

func Format

func Format(err error) string

Format returns a formatted string representing an error. This string may take up multiple lines and contain ANSI escape codes. If err does not fulfill the Error interface, err.Error() is returned instead.

When the error fulfills the Error interface, the formatted output will be of the general form:

FILE:ROW+1:START+1: MESSAGE
ROW+1 | LINE
        ^^^^

Where the position of the underline (^^^^) corresponds to the start and end fields in the error's position. Note that the row and column numbers as displayed are increased by one from their normal zero-indexed state, because most editors display row and column numbers starting at 1:1. Additionally, because normal error messages do not produce trailing line breaks, neither does this function.

Types

type Error

type Error interface {
	error
	Position() Position
}

Error is an error that contains positional information.

func Errorf

func Errorf(position Position, format string, variables ...any) Error

Errorf produces an error with a fmt'd message.

type Position

type Position struct {
	File string // The name of the file
	Line string // the text of the line the position is on

	Row   int // Line number, starting at 0
	Start int // Starting column number, starting at 0
	End   int // Terminating column number, starting at 0
}

Position stores the position of something within a file. For memory's sake, positions in the same file should be created using the same File string, and positions on the same line should be created using the same Line string.

func (Position) Format

func (pos Position) Format() string

Format produces a formatted printout of where the position is in its file.

func (Position) String

func (pos Position) String() string

String returns a string representation of the position of the form:

FILE:ROW+1:START+1

Note that the row and column numbers as displayed are increased by one from their normal zero-indexed state, because most editors display row and column numbers starting at 1:1.

func (Position) Union

func (pos Position) Union(other Position) Position

Union attempts to return the union of two positions. Since a position cannot span multiple lines or files, the resulting position will be on the same line and in the same file as the method reciever.