locerr is a small library to make a nice-looking locational error in a source code. It provides a struct to represent a source file, a specific position in code and an error related to specific range or position in source.
This library is useful to provide a unified look for error messages raised by compilers, interpreters or translators.
By using locerr.Source
and locerr.Pos
types as position information, this library can provide
an error type which shows nice look error message.
- It shows the code snippet which caused an error
- Enable to add notes to error by nesting an error instance like pkg/errors
- Proper location is automatically added to error messages and notes
- Colorized label like 'Error:' or 'Note:'
- Windows is supported
It's important to make a good error when compilation or execution errors found. locerr helps it. This library is actually used in some my compiler implementation.
Please use go get
.
$ go get -u github.com/rhysd/locerr
As example, let's say to make a locational error for following pseudo code. In this code, function
foo
is defined with 1 parameter but called with 3 parameters.
function foo(x: bool): int {
return (if x then 42 else 21)
}
function main() {
foo(true,
42,
"test")
}
We can make a locational error with some notes using locerr as following.
package main
import (
"fmt"
"os"
"github.com/rhysd/locerr"
)
func main() {
// At first you should gain entire source as *locerr.Source instance.
code :=
`function foo(x: bool): int {
return (if x then 42 else 21)
}
function main() {
foo(true,
42,
"test")
}`
src := locerr.NewDummySource(code)
// You can get *locerr.Source instance from file (NewSourceFromFile) or stdin (NewSourceFromStdin) also.
// Let's say to find an error at some range in the source. 'start' indicates the head of the first argument.
// 'end' indicates the end of the last argument.
start := locerr.Pos{
Offset: 88,
Line: 6,
Column: 7,
File: src,
}
end := locerr.Pos{
Offset: 116,
Line: 9,
Column: 12,
File: src,
}
// NewError or other factory functions make a new error instance with the range. locerr.Error instance
// implements error interface so it can be handled like other error types.
err := locerr.ErrorIn(start, end, "Calling 'foo' with wrong number of argument")
// Assume that you find additional information (location of variable and its type). Then you can add some
// notes to the error. Notes can be added by wrapping errors like pkg/errors library.
prev := locerr.Pos{
Offset: 9,
Line: 1,
Column: 10,
File: src,
}
err = err.NoteAt(prev, "Defined with 1 parameter")
err = err.NoteAt(prev, "'foo' was defined as 'bool -> int'")
// Finally you can see the result!
// Get the error message as string. Note that this is only for non-Windows OS.
fmt.Println(err)
// Directly writes the error message into given file.
// This supports Windows. Useful to output from stdout or stderr.
err.PrintToFile(os.Stdout)
}
Above code should show the following output:
Error: Calling 'foo' with wrong number of argument (at <dummy>:6:7)
Note: Defined with 1 parameter (at <dummy>:1:10)
Note: 'foo' was defined as 'bool -> int' (at <dummy>:1:10)
> foo(true,
> 42,
> "test")
Labels such as 'Error:' or 'Notes:' are colorized. Main error message is emphasized with bold font. And source code location information (file name, line and column) is added with gray text. If the error has range information, the error shows code snippet which caused the error at the end of error message.
If you have only one position information rather than two, 'start' position and 'end' position,
ErrorAt
is available instead of ErrorIn
. ErrorAt
takes one Pos
instance.
err := locerr.ErrorAt(start, "Calling 'foo' with wrong number of argument")
In this case, line snippet is shown in error message. pos.Line
is used to get line from source text.
fmt.Println(err)
will show the following.
Error: Calling 'foo' with wrong number of argument (at <dummy>:6:7)
> foo(true,
$ go test ./
Note that go test -v
may fail because color sequences are not assumed in tests.
Fuzzing test using go-fuzz.
$ cd ./fuzz
$ go-fuzz-build github.com/rhysd/locerr/fuzz
$ go-fuzz -bin=./locerr_fuzz-fuzz.zip -workdir=fuzz
Last command starts fuzzing tests until stopped with ^C
. Every 3 seconds it reports the current
result. It makes 3 directories in fuzz
directory as the result, corpus
, crashers
and
suppressions
. crashers
contains the information about the crash caused by fuzzing.