export query parsing error type for getting offset and token

README.md

@@ -130,6 +130,7 @@ func main() {
 ```
 
 - Firstly, use [`gojq.Parse(string) (*Query, error)`](https://pkg.go.dev/github.com/itchyny/gojq#Parse) to get the query from a string.
+  - Use [`gojq.ParseError`](https://pkg.go.dev/github.com/itchyny/gojq#ParseError) to get the error position and token of the parsing error.
 - Secondly, get the result iterator
   - using [`query.Run`](https://pkg.go.dev/github.com/itchyny/gojq#Query.Run) or [`query.RunWithContext`](https://pkg.go.dev/github.com/itchyny/gojq#Query.RunWithContext)
   - or alternatively, compile the query using [`gojq.Compile`](https://pkg.go.dev/github.com/itchyny/gojq#Compile) and then [`code.Run`](https://pkg.go.dev/github.com/itchyny/gojq#Code.Run) or [`code.RunWithContext`](https://pkg.go.dev/github.com/itchyny/gojq#Code.RunWithContext). You can reuse the `*Code` against multiple inputs to avoid compilation of the same query. But for arguments of `code.Run`, do not give values sharing same data between multiple calls.

cli/error.go

@@ -2,12 +2,14 @@ package cli
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"strconv"
 	"strings"
 	"unicode/utf8"
 
+	"github.com/itchyny/gojq"
 	"github.com/mattn/go-runewidth"
 )
 
@@ -73,10 +75,9 @@ type queryParseError struct {
 
 func (err *queryParseError) Error() string {
 	var offset int
-	if e, ok := err.err.(interface{ Token() (string, int) }); ok {
-		var token string
-		token, offset = e.Token()
-		offset -= len(token) - 1
+	var e *gojq.ParseError
+	if errors.As(err.err, &e) {
+		offset = e.Offset - len(e.Token) + 1
 	}
 	linestr, line, column := getLineByOffset(err.contents, offset)
 	if err.fname != "<arg>" || containsNewline(err.contents) {

lexer.go

@@ -521,37 +521,34 @@ func quoteAndEscape(src string, quote bool, controls int) []byte {
 	return buf
 }
 
-type parseError struct {
-	offset    int
-	token     string
+// ParseError represents a description of a query parsing error.
+type ParseError struct {
+	Offset    int    // the error occurred after reading Offset bytes
+	Token     string // the Token that caused the error (may be empty)
 	tokenType int
 }
 
-func (err *parseError) Error() string {
+func (err *ParseError) Error() string {
 	switch err.tokenType {
 	case eof:
 		return "unexpected EOF"
 	case tokInvalid:
-		return "invalid token " + jsonMarshal(err.token)
+		return "invalid token " + jsonMarshal(err.Token)
 	case tokInvalidEscapeSequence:
-		return `invalid escape sequence "` + err.token + `" in string literal`
+		return `invalid escape sequence "` + err.Token + `" in string literal`
 	case tokUnterminatedString:
 		return "unterminated string literal"
 	default:
-		return "unexpected token " + jsonMarshal(err.token)
+		return "unexpected token " + jsonMarshal(err.Token)
 	}
 }
 
-func (err *parseError) Token() (string, int) {
-	return err.token, err.offset
-}
-
 func (l *lexer) Error(string) {
 	offset, token := l.offset, l.token
 	if l.tokenType != eof && l.tokenType < utf8.RuneSelf {
 		token = string(rune(l.tokenType))
 	}
-	l.err = &parseError{offset, token, l.tokenType}
+	l.err = &ParseError{offset, token, l.tokenType}
 }
 
 func isWhite(ch byte) bool {

parser.go.y

@@ -3,10 +3,10 @@ package gojq
 
 // Parse a query string, and returns the query struct.
 //
-// If parsing failed, the returned error has the method Token() (string, int),
-// which reports the invalid token and the byte offset in the query string. The
-// token is empty if the error occurred after scanning the entire query string.
-// The byte offset is the scanned bytes when the error occurred.
+// If parsing failed, it returns an error of type [*ParseError], which has
+// the byte offset and the invalid token. The byte offset is the scanned bytes
+// when the error occurred. The token is empty if the error occurred after
+// scanning the entire query string.
 func Parse(src string) (*Query, error) {
 	l := newLexer(src)
 	if yyParse(l) > 0 {