Merge pull request 'lexer: constants and helpers' (#9)

Reviewed-on: #9

lexer/error.go

@@ -0,0 +1,54 @@
+package lexer
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+)
+
+var (
+	_ error = (*Error)(nil)
+)
+
+var (
+	// ErrUnacceptableRune indicates the read rune isn't acceptable in the context
+	ErrUnacceptableRune = errors.New("rune not acceptable in context")
+
+	// ErrNotImplemented indicates something hasn't been implemented yet
+	ErrNotImplemented = errors.New("not implemented")
+)
+
+// Error represents a generic parsing error
+type Error struct {
+	Filename string
+	Line     int
+	Column   int
+
+	Content string
+	Err     error
+}
+
+func (err Error) Error() string {
+	var s []string
+
+	switch {
+	case err.Line > 0 || err.Column > 0:
+		s = append(s, fmt.Sprintf("%s:%v:%v", err.Filename, err.Line, err.Column))
+	case err.Filename != "":
+		s = append(s, err.Filename)
+	}
+
+	if err.Err != nil {
+		s = append(s, err.Err.Error())
+	}
+
+	if err.Content != "" {
+		s = append(s, fmt.Sprintf("%q", err.Content))
+	}
+
+	return strings.Join(s, ": ")
+}
+
+func (err Error) Unwrap() error {
+	return err.Err
+}

lexer/lexer.go

@@ -0,0 +1,31 @@
+// Package lexer provides basic helpers to implement parsers
+package lexer
+
+import (
+	"errors"
+	"io"
+)
+
+// StateFn is a State Function of the parser
+type StateFn func() (StateFn, error)
+
+// Run runs a state machine until the state function either
+// returns nil or an error
+func Run(fn StateFn) error {
+	for fn != nil {
+		var err error
+
+		fn, err = fn()
+		switch {
+		case errors.Is(err, io.EOF):
+			// EOF
+			return nil
+		case err != nil:
+			// failed
+			return err
+		}
+	}
+
+	// ended
+	return nil
+}

lexer/position.go

@@ -0,0 +1,66 @@
+package lexer
+
+import "fmt"
+
+// Position indicates a line and column pair on a file.
+// Counting starts at 1.
+type Position struct {
+	Line   int
+	Column int
+}
+
+// String generates a pretty "(Line, Column)"" representation of the Position
+func (p Position) String() string {
+	if p.Line == 0 {
+		p.Reset()
+	}
+
+	return fmt.Sprintf("(%v, %v)", p.Line, p.Column)
+}
+
+// GoString generates a string representation of the Position for %#v usage
+func (p Position) GoString() string {
+	if p.Line == 0 {
+		p.Reset()
+	}
+
+	return fmt.Sprintf("lexer.Position{%v, %v}", p.Line, p.Column)
+}
+
+// Reset places a position at (1,1)
+func (p *Position) Reset() {
+	p.Line, p.Column = 1, 1
+}
+
+// Step moves the column one place
+func (p *Position) Step() {
+	if p.Line == 0 {
+		p.Reset()
+	}
+
+	p.Column++
+}
+
+// StepN moves the column N places forward
+func (p *Position) StepN(n int) {
+	if p.Line == 0 {
+		p.Reset()
+	}
+
+	switch {
+	case n > 0:
+		p.Column += n
+	default:
+		panic(fmt.Errorf("invalid %v increment", n))
+	}
+}
+
+// StepLine moves position to the start of the next line
+func (p *Position) StepLine() {
+	if p.Line == 0 {
+		p.Reset()
+	}
+
+	p.Line++
+	p.Column = 1
+}

lexer/reader.go

@@ -1,7 +1,8 @@
-package runes
+package lexer
 
 import (
 	"bytes"
+	"errors"
 	"io"
 	"strings"
 	"unicode/utf8"
@@ -18,7 +19,14 @@ const (
 
 // implemented interfaces
 var (
-	_ io.RuneReader = (*Reader)(nil)
+	_ io.RuneReader  = (*Reader)(nil)
+	_ io.RuneScanner = (*Reader)(nil)
+)
+
+var (
+	// ErrInvalidUnreadRune indicates UnreadRune() was calls after an
+	// action other than a successful ReadRune()
+	ErrInvalidUnreadRune = errors.New("invalid UnreadRune() call")
 )
 
 // Reader is a RuneReader aimed at implementing text parsers
@@ -28,6 +36,8 @@ type Reader struct {
 	buf    []byte
 	off    int
 	cursor int
+
+	lastRuneSize int
 }
 
 // String returns what's already Read but not yet emitted or discarded
@@ -54,6 +64,9 @@ func (b *Reader) Discard() {
 		// step
 		b.off = b.cursor
 	}
+
+	// and prevent UnreadRune()
+	b.lastRuneSize = -1
 }
 
 // ready tells how many bytes are ready to decode
@@ -139,6 +152,8 @@ func (b *Reader) ReadRune() (rune, int, error) {
 	for {
 		err := b.needsBytes(count)
 		if err != nil {
+			b.lastRuneSize = -1
+
 			return 0, 0, err
 		}
 
@@ -153,9 +168,71 @@ func (b *Reader) ReadRune() (rune, int, error) {
 
 	// decode rune
 	r, l := utf8.DecodeRune(b.buf[b.cursor:])
+	// step over
+	b.cursor += l
+	// and remember for UnreadRune()
+	b.lastRuneSize = l
+
 	return r, l, nil
 }
 
+// UnreadRune moves the cursor where it was before the last call to ReadRune
+func (b *Reader) UnreadRune() error {
+	if b.lastRuneSize > 0 {
+		b.cursor -= b.lastRuneSize
+		b.lastRuneSize = -1
+		return nil
+	}
+
+	return ErrInvalidUnreadRune
+}
+
+// PeekRune returns information about the next rune without moving the
+// cursor
+func (b *Reader) PeekRune() (rune, int, error) {
+	r, l, err := b.ReadRune()
+	if err != nil {
+		return r, l, err
+	}
+	err = b.UnreadRune()
+	return r, l, err
+}
+
+// Accept consumes a rune from the source if it meets the condition.
+// it returns true if the condition was met and false if it wasn't.
+func (b *Reader) Accept(cond func(r rune) bool) bool {
+	r, _, err := b.ReadRune()
+	switch {
+	case err != nil:
+		return false
+	case cond(r):
+		return true
+	default:
+		_ = b.UnreadRune()
+		return false
+	}
+}
+
+// AcceptAll consumes runes from the source as long as they meet the
+// condition. it returns true if the condition was met for at least one rune,
+// and false if it wasn't.
+func (b *Reader) AcceptAll(cond func(r rune) bool) bool {
+	var accepted bool
+
+	for {
+		r, _, err := b.ReadRune()
+		switch {
+		case err != nil:
+			return accepted
+		case cond(r):
+			accepted = true
+		default:
+			_ = b.UnreadRune()
+			return accepted
+		}
+	}
+}
+
 // NewReader creates a new runes [Reader] using the given [io.Reader]
 func NewReader(r io.Reader) *Reader {
 	if r == nil {

lexer/runes.go

@@ -0,0 +1,41 @@
+package lexer
+
+import (
+	"strings"
+	"unicode"
+)
+
+// NewIsNot generates a rune condition checker that reverses the
+// decision of the given checker.
+func NewIsNot(cond func(rune) bool) func(rune) bool {
+	return func(r rune) bool {
+		return !cond(r)
+	}
+}
+
+// NewIsIn generates a rune condition checker that accepts runes
+// contained on the provided string
+func NewIsIn(s string) func(rune) bool {
+	return func(r rune) bool {
+		return strings.ContainsRune(s, r)
+	}
+}
+
+// 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 {
+	return func(r rune) bool {
+		for _, cond := range s {
+			if cond(r) {
+				return true
+			}
+		}
+		return false
+	}
+}
+
+// IsSpace reports whether the rune is a space character as
+// defined by Unicode's White Space property
+func IsSpace(r rune) bool {
+	return unicode.IsSpace(r)
+}

runes/docs.go

@@ -1,2 +0,0 @@
-// Package runes helps us work with runes
-package runes