lexer: add Hint to Error, which is expanded as "%s" instead of "%q"

Signed-off-by: Alejandro Mery <amery@jpi.io>

README.md

@@ -1 +1,78 @@
 # asciigoat's core library
+
+[![Go Reference][godoc-badge]][godoc]
+[![Go Report Card][goreport-badge]][goreport]
+
+This package contains the basics for writing simple parsers of
+text languages heavily inspired by
+[Rob Pike](https://en.wikipedia.org/wiki/Rob_Pike)'s talk on
+[Lexical Scanning in Go](https://go.dev/talks/2011/lex.slide#1) in 2011 which
+you can [watch online](https://www.youtube.com/watch?v=HxaD_trXwRE) to get
+better understanding of the ideas behind **asciigoat**.
+
+**asciigoat** is [MIT](https://opensource.org/license/mit/) licensed.
+
+[godoc]: https://pkg.go.dev/asciigoat.org/core
+[godoc-badge]: https://pkg.go.dev/badge/asciigoat.org/core.svg
+[goreport]: https://goreportcard.com/report/asciigoat.org/core
+[goreport-badge]: https://goreportcard.com/badge/asciigoat.org/core
+
+[godoc-lexer-reader]: https://pkg.go.dev/asciigoat.org/core/lexer#Reader
+[godoc-readcloser]: https://pkg.go.dev/asciigoat.org/core#ReadCloser
+
+## Lexer
+
+### lexer.Reader
+
+The lexer package provides [`lexer.Reader`][godoc-lexer-reader] which is
+actually an [`io.RuneScanner`](https://pkg.go.dev/io#RuneScanner)
+that buffers accepted runes until you are ready to
+[emit](https://pkg.go.dev/asciigoat.org/core/lexer#Reader.Emit) or
+[discard](https://pkg.go.dev/asciigoat.org/core/lexer#Reader.Discard).
+
+### lexer.Position
+
+[`lexer.Position`](https://pkg.go.dev/asciigoat.org/core/lexer#Position)
+is a `(Line, Column)` pair with methods to facilitate tracking
+your position on the source [Reader](https://pkg.go.dev/io#Reader).
+
+### lexer.Error
+
+[`lexer.Error`](https://pkg.go.dev/asciigoat.org/core/lexer#Error)
+is an [unwrappable](https://pkg.go.dev/errors#Unwrap) error with a
+token position and hint attached.
+
+### lexer.StateFn
+
+At the heart of **asciigoat** we have _state functions_ as proposed on [Rob Pike's famous talk](https://www.youtube.com/watch?v=HxaD_trXwRE) which return the next _state function_ parsing is done.
+Additionally there is a [`Run()`](https://pkg.go.dev/asciigoat.org/lexer#Run) helper that implements the loop.
+
+### rune checkers
+
+_Rune checkers_ are simple functions that tell if a rune is of a class or it's not.
+Fundamental checkers are provided by the [`unicode` package](https://pkg.go.dev/unicode).
+
+Our [`lexer.Reader`][godoc-lexer-reader] uses them on its `Accept()` and `AcceptAll()` methods to
+make it easier to consume the _source_ document.
+
+To facilitate the declaration of _rune classes_ in the context of **asciigoat** powered parsers we include
+a series of rune checker factories.
+
+* `NewIsIn(string)`
+* `NewIsInRunes(...rune)`
+* `NewIsNot(checker)`
+* `NewIsOneOf(...checker)`
+
+## Others
+
+### ReadCloser
+
+[ReadCloser][godoc-readcloser] assists in providing a
+[io.Closer](https://pkg.go.dev/io#Closer) to Readers or buffers without on,
+or unearthing one if available so
+[io.ReadCloser](https://pkg.go.dev/io#ReadCloser) can be fulfilled.
+
+## See also
+
+* [asciigoat.org/ini](https://asciigoat.org/ini)
+* [oss.jpi.io](https://oss.jpi.io)

lexer/error.go

@@ -25,17 +25,27 @@ type Error struct {
 	Column   int
 
 	Content string
+	Hint    string
 	Err     error
 }
 
 func (err Error) Error() string {
 	var s []string
+	var prefix string
 
 	switch {
 	case err.Line > 0 || err.Column > 0:
-		s = append(s, fmt.Sprintf("%s:%v:%v", err.Filename, err.Line, err.Column))
+		if err.Filename != "" {
+			prefix = fmt.Sprintf("%s:%v:%v", err.Filename, err.Line, err.Column)
+		} else {
+			prefix = fmt.Sprintf("%v:%v", err.Line, err.Column)
+		}
 	case err.Filename != "":
-		s = append(s, err.Filename)
+		prefix = err.Filename
+	}
+
+	if prefix != "" {
+		s = append(s, prefix)
 	}
 
 	if err.Err != nil {
@@ -46,6 +56,10 @@ func (err Error) Error() string {
 		s = append(s, fmt.Sprintf("%q", err.Content))
 	}
 
+	if err.Hint != "" {
+		s = append(s, err.Hint)
+	}
+
 	return strings.Join(s, ": ")
 }
 

lexer/runes.go

@@ -21,6 +21,12 @@ func NewIsIn(s string) func(rune) bool {
 	}
 }
 
+// NewIsInRunes generates a rune condition checker that accepts
+// the runes specified
+func NewIsInRunes(s ...rune) func(rune) bool {
+	return NewIsIn(string(s))
+}
+
 // NewIsOneOf generates a run condition checker that accepts runes
 // accepted by any of the given checkers
 func NewIsOneOf(s ...func(rune) bool) func(rune) bool {