ctxerr

README

ctxerr

ctxerr is a Go library and CLI utility for pretty-printing linter/parser errors.

Instead of just describing what's wrong, it lets you point at the wrong input:

narf.txt:1:8: string is missing closing quote
 1 | "foo bar
   |         ^ missing closing quote

• Create pretty error messages for linters, parsers, etc. by pointing at the relevant position in the source code.
• Parse existing error messages into Ctx structs.
• CLI utility ctx scans STDIN for linter errors and enhances them with the reported source line.

---

• Installation
• Documentation
• Changes
• License

Installation

Library

go get -u github.com/nochso/ctxerr

CLI utility ctx

go install github.com/nochso/ctxerr/cmd/ctx

Documentation

Library

The GoDoc pages contain plenty of examples.

CLI utility ctx

$ ctx -h
ctx 1.0.0-beta
Pretty prints parser errors from stdin.

Possible input:
  path/file.ext:1:5: some error on line 1, column 5
  file.ext:123: column is optional and so is the message:
  file.ext:1

Usage:
  ctx < log.txt
  gometalinter . | ctx

Flags:
  -context NUM
        print NUM lines of context surrounding an error. negative for all, positive for limited and 0 for none (default)
  -no-color
        disable any color output
  -pessimistic
        print only matching errors, ignore everything else

Changes

All notable changes to this project will be documented in the changelog.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

License

This project is released under the MIT license.

Documentation

Index

• Variables
• type Ctx
  • func New(input string, region Region) Ctx
  • func NewFromPath(path string, region Region) (Ctx, error)
  • func Parse(line string) (*Ctx, error)
  • func (c Ctx) Error() string
  • func (c Ctx) ErrorLine() string
• type Position
  • func (p Position) String() string
• type Region
  • func Point(line, col int) Region
  • func Range(startLine, startCol, endLine, endCol int) Region
  • func (r Region) String() string

Examples

• Ctx.Error
• Ctx.Error (ContextAll)
• Ctx.Error (ContextLimited)
• Ctx.Error (ContextLimitedMultiline)
• Ctx.Error (Hint)
• Ctx.Error (Path)
• Ctx.Error (Tabwidth)
• Ctx.ErrorLine
• New
• NewFromPath
• Point
• Range
• Range (Multiline)

Variables

var (
	// DefaultGutter separates line numbers from content.
	DefaultGutter = " | "
	// DefaultPointer is the rune that points up at a region.
	DefaultPointer = '^'
	// DefaultContext is the default amount of context lines surrounding an error.
	// It is used by New* functions.
	DefaultContext = 0
	// NoColor disables color output.
	NoColor bool
)

var (
	// ErrNoMatch is returned by Parse when no file path or position can be found.
	ErrNoMatch = fmt.Errorf("line does not match position pattern: %s", matchRegionColon.String())
)

Types

type Ctx

type Ctx struct {
	Lines []string
	// Context is the maximum amount of context lines surrounding the marked region.
	//
	//	 0: no lines of context.
	//	-1: all lines, the full input string
	//	 3: limited context of 3 lines
	Context int
	Region
	// Path to the source of the context (optional).
	Path string
	// Hint that is displayed near the region markers (optional).
	Hint string
	// Err is the error that occurred at this region (optional).
	Err error
}

Ctx points to runes in (multiline) strings.

func New

func New(input string, region Region) Ctx

New returns a new Ctx pointing to a region in an input string.

Use functions Point and Range to create a Region.

Example

fmt.Println(New("source code containing error", Range(1, 24, 1, 28)))

Output:

1:24-28:
1 | source code containing error
  |                        ^^^^^

func NewFromPath

func NewFromPath(path string, region Region) (Ctx, error)

NewFromPath returns a new Ctx pointing to a region in the given file. Returns an error when the file does not exist or could not be read.

Example

cerr, err := NewFromPath("LICENSE", Range(1, 1, 1, 3))
if err != nil {
	fmt.Println(err)
	return
}
cerr.Context = 0
fmt.Println(cerr)

Output:

LICENSE:1:1-3:
1 | MIT License
  | ^^^

func Parse

func Parse(line string) (*Ctx, error)

Parse a single line with at least a file path and position. Returns error ErrNoMatch when this does not appear to be an error line. Otherwise will return parsing errors or nil on success.

foo.go:15:1: message
foo.go[1, 2]: message

func (Ctx) Error

func (c Ctx) Error() string

Error formats a summary of this context error.

Example

err := New("ab!cd", Point(1, 3))
err.Err = fmt.Errorf("not a letter")
fmt.Println(err)

Output:

not a letter
1:3:
1 | ab!cd
  |   ^

Example (ContextAll)

in := `1st
2nd
3rd has an error
4th
5th`
ctx := New(in, Point(3, 12))
ctx.Context = -1
fmt.Println(ctx)

Output:

3:12:
1 | 1st
2 | 2nd
3 | 3rd has an error
  |            ^
4 | 4th
5 | 5th

Example (ContextLimited)

in := `1st
2nd
3rd has an error
4th
5th`
ctx := New(in, Point(3, 12))
ctx.Context = 1
fmt.Println(ctx)

Output:

3:12:
2 | 2nd
3 | 3rd has an error
  |            ^
4 | 4th

Example (ContextLimitedMultiline)

in := `1st
2nd
3rd has an error
4th still has an error
5th`
ctx := New(in, Range(3, 1, 4, 22))
ctx.Context = 1
fmt.Println(ctx)

Output:

3:1-4:22:
2 | 2nd
3 | 3rd has an error
  | ^^^^^^^^^^^^^^^^
4 | 4th still has an error
  | ^^^^^^^^^^^^^^^^^^^^^^
5 | 5th

Example (Hint)

ctx := New("010101102110", Point(1, 9))
ctx.Hint = "don't worry, bender"
fmt.Println(ctx)

Output:

1:9:
1 | 010101102110
  |         ^ don't worry, bender

Example (Path)

ctx := New("42", Point(1, 1))
ctx.Path = "/tmp/ctxerr/answer.txt"
fmt.Println(ctx)

Output:

/tmp/ctxerr/answer.txt:1:1:
1 | 42
  | ^

Example (Tabwidth)

in := "\tfoo\tbar"
ctx := New(in, Point(1, 5))
fmt.Println(ctx)

Output:

1:5:
1 |     foo    bar
  |        ^^^^

func (Ctx) ErrorLine

func (c Ctx) ErrorLine() string

ErrorLine returns a single line error message.

Example

ctx := New("foo", Point(1, 1))
ctx.Err = fmt.Errorf("something went wrong")
ctx.Path = "bar.txt"
fmt.Println(ctx.ErrorLine())

Output:

bar.txt:1:1: something went wrong

type Position

type Position struct {
	Line, Col int
}

Position of a single point in a multiline string.

func (Position) String

func (p Position) String() string

String representation of a Position.

1
1:2

type Region

type Region struct {
	Start, End Position
}

Region defines a selection of runes (utf8 codepoints) in a string.

func Point

func Point(line, col int) Region

Point returns a Region pointing to a specific rune. Line and column are one-based.

Example

fmt.Println(New("00100", Point(1, 3)))

Output:

1:3:
1 | 00100
  |   ^

func Range

func Range(startLine, startCol, endLine, endCol int) Region

Range returns a Region pointing to a range of runes. Line and column are one-based.

Example

fmt.Println(New("01110", Range(1, 2, 1, 4)))

Output:

1:2-4:
1 | 01110
  |  ^^^

Example (Multiline)

fmt.Println(New("00001\n11110", Range(1, 5, 2, 4)))

Output:

1:5-2:4:
1 | 00001
  |     ^
2 | 11110
  | ^^^^

func (Region) String

func (r Region) String() string

String representation of a region.

3       // complete 3rd line
1-3     // lines 1 through 3
1:1     // pointer
1:1-2   // range on single line
1:1-2:1 // range over multiple lines