reflection: WIP

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

Makefile

@@ -0,0 +1,50 @@
+.PHONY: all clean generate fmt
+.PHONY: tidy get build test up
+
+GO ?= go
+GOFMT ?= gofmt
+GOFMT_FLAGS = -w -l -s
+GOGENERATE_FLAGS = -v
+
+GOPATH ?= $(shell $(GO) env GOPATH)
+GOBIN ?= $(GOPATH)/bin
+
+TMPDIR ?= $(CURDIR)/.tmp
+TOOLSDIR = $(CURDIR)/tools
+
+REVIVE_CONF ?= $(TOOLSDIR)/revive.toml
+REVIVE_RUN_ARGS ?= -config $(REVIVE_CONF) -formatter friendly
+REVIVE ?= $(GO) run -v github.com/mgechev/revive
+
+V = 0
+Q = $(if $(filter 1,$V),,@)
+M = $(shell if [ "$$(tput colors 2> /dev/null || echo 0)" -ge 8 ]; then printf "\033[34;1m▶\033[0m"; else printf "▶"; fi)
+
+all: get generate tidy build
+
+clean: ; $(info $(M) cleaning…)
+	rm -rf $(TMPDIR)
+
+fmt: ; $(info $(M) reformatting sources…)
+	$Q find . -name '*.go' | xargs -r $(GOFMT) $(GOFMT_FLAGS)
+
+tidy: | fmt ; $(info $(M) tidying up…)
+	$Q $(GO) mod tidy
+	$Q $(GO) vet ./...
+	$Q $(REVIVE) $(REVIVE_RUN_ARGS) ./...
+
+get: ; $(info $(M) downloading dependencies…)
+	$Q $(GO) get -v -tags tools ./...
+
+build: ; $(info $(M) building…)
+	$Q $(GO) build -v ./...
+
+test: ; $(info $(M) building…)
+	$Q $(GO) test ./...
+
+up: ; $(info $(M) updating dependencies…)
+	$Q $(GO) get -u -v ./...
+	$Q $(GO) mod tidy
+
+generate: ; $(info $(M) generating data…)
+	$Q git grep -l '^//go:generate' | sort -uV | xargs -r -n1 $(GO) generate $(GOGENERATE_FLAGS)

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)

go.mod

@@ -1,3 +1,23 @@
 module asciigoat.org/core
 
 go 1.19
+
+require (
+	github.com/fatih/structtag v1.2.0
+	github.com/mgechev/revive v1.3.3
+	github.com/pkg/errors v0.9.1
+)
+
+require (
+	github.com/BurntSushi/toml v1.3.2 // indirect
+	github.com/chavacava/garif v0.0.0-20230608123814-4bd63c2919ab // indirect
+	github.com/fatih/color v1.15.0 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.17 // indirect
+	github.com/mattn/go-runewidth v0.0.9 // indirect
+	github.com/mgechev/dots v0.0.0-20210922191527-e955255bf517 // indirect
+	github.com/mitchellh/go-homedir v1.1.0 // indirect
+	github.com/olekukonko/tablewriter v0.0.5 // indirect
+	golang.org/x/sys v0.11.0 // indirect
+	golang.org/x/tools v0.12.0 // indirect
+)

go.sum

@@ -0,0 +1,47 @@
+github.com/BurntSushi/toml v1.3.2 h1:o7IhLm0Msx3BaB+n3Ag7L8EVlByGnpq14C4YWiu/gL8=
+github.com/BurntSushi/toml v1.3.2/go.mod h1:CxXYINrC8qIiEnFrOxCa7Jy5BFHlXnUU2pbicEuybxQ=
+github.com/chavacava/garif v0.0.0-20230608123814-4bd63c2919ab h1:5JxePczlyGAtj6R1MUEFZ/UFud6FfsOejq7xLC2ZIb0=
+github.com/chavacava/garif v0.0.0-20230608123814-4bd63c2919ab/go.mod h1:XMyYCkEL58DF0oyW4qDjjnPWONs2HBqYKI+UIPD+Gww=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/fatih/color v1.15.0 h1:kOqh6YHBtK8aywxGerMG2Eq3H6Qgoqeo13Bk2Mv/nBs=
+github.com/fatih/color v1.15.0/go.mod h1:0h5ZqXfHYED7Bhv2ZJamyIOUej9KtShiJESRwBDUSsw=
+github.com/fatih/structtag v1.2.0 h1:/OdNE99OxoI/PqaW/SuSK9uxxT3f/tcSZgon/ssNSx4=
+github.com/fatih/structtag v1.2.0/go.mod h1:mBJUNpUnHmRKrKlQQlmCrh5PuhftFbNv8Ys4/aAZl94=
+github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.17 h1:BTarxUcIeDqL27Mc+vyvdWYSL28zpIhv3RoTdsLMPng=
+github.com/mattn/go-isatty v0.0.17/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-runewidth v0.0.9 h1:Lm995f3rfxdpd6TSmuVCHVb/QhupuXlYr8sCI/QdE+0=
+github.com/mattn/go-runewidth v0.0.9/go.mod h1:H031xJmbD/WCDINGzjvQ9THkh0rPKHF+m2gUSrubnMI=
+github.com/mgechev/dots v0.0.0-20210922191527-e955255bf517 h1:zpIH83+oKzcpryru8ceC6BxnoG8TBrhgAvRg8obzup0=
+github.com/mgechev/dots v0.0.0-20210922191527-e955255bf517/go.mod h1:KQ7+USdGKfpPjXk4Ga+5XxQM4Lm4e3gAogrreFAYpOg=
+github.com/mgechev/revive v1.3.3 h1:GUWzV3g185agbHN4ZdaQvR6zrLVYTUSA2ktvIinivK0=
+github.com/mgechev/revive v1.3.3/go.mod h1:NhpOtVtDbjYNDj697eDUBTobijCDHQKar4HDKc0TuTo=
+github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
+github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
+github.com/olekukonko/tablewriter v0.0.5 h1:P2Ga83D34wi1o9J6Wh1mRuqd4mF/x/lgBS7N7AbDhec=
+github.com/olekukonko/tablewriter v0.0.5/go.mod h1:hPp6KlRPjbx+hW8ykQs1w3UBbZlj6HuIJcUGPhkA7kY=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+golang.org/x/mod v0.12.0 h1:rmsUpXtvNzj340zd98LZ4KntptpfRHwpFOHG188oHXc=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.11.0 h1:eG7RXZHdqOJ1i+0lgLgCpSXAp6M3LYlAo6osgSi0xOM=
+golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/tools v0.12.0 h1:YW6HUoUmYBpwSgyaGaZq1fHjrBjX1rlpZ54T6mu2kss=
+golang.org/x/tools v0.12.0/go.mod h1:Sc0INKfu04TlqNoRA1hgpFZbhYXHPr4V5DzpSBTPqQM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

lexer/error.go

@@ -0,0 +1,70 @@
+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
+	Hint    string
+	Err     error
+}
+
+func (err Error) prefix() string {
+	switch {
+	case err.Line > 0 || err.Column > 0:
+		if err.Filename != "" {
+			return fmt.Sprintf("%s:%v:%v", err.Filename, err.Line, err.Column)
+		}
+
+		return fmt.Sprintf("%v:%v", err.Line, err.Column)
+	default:
+		return err.Filename
+	}
+}
+
+func (err Error) Error() string {
+	var s []string
+
+	prefix := err.prefix()
+	if prefix != "" {
+		s = append(s, prefix)
+	}
+
+	if err.Err != nil {
+		s = append(s, err.Err.Error())
+	}
+
+	if err.Content != "" {
+		s = append(s, fmt.Sprintf("%q", err.Content))
+	}
+
+	if err.Hint != "" {
+		s = append(s, err.Hint)
+	}
+
+	return strings.Join(s, ": ")
+}
+
+func (err Error) Unwrap() error {
+	return err.Err
+}

lexer/lexer.go

@@ -1,2 +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

@@ -198,6 +198,41 @@ func (b *Reader) PeekRune() (rune, int, error) {
 	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,47 @@
+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)
+	}
+}
+
+// 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 {
+	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)
+}

readcloser.go

@@ -0,0 +1,64 @@
+package core
+
+import (
+	"bytes"
+	"io"
+	"io/fs"
+	"strings"
+)
+
+// ReadCloser adds a Close() to Readers without one
+type ReadCloser struct {
+	r io.Reader
+}
+
+// Read passes the Read() call to the underlying [io.Reader]
+// and fail if it was Closed()
+func (rc *ReadCloser) Read(b []byte) (int, error) {
+	switch {
+	case rc.r != nil:
+		return rc.r.Read(b)
+	default:
+		return 0, fs.ErrClosed
+	}
+}
+
+// Close attempts to Close the underlying [io.Reader], or
+// remove it if it doesn't support Close() and fail
+// if closed twice
+func (rc *ReadCloser) Close() error {
+	switch {
+	case rc.r != nil:
+		rc.r = nil
+		return nil
+	default:
+		return fs.ErrClosed
+	}
+}
+
+// NewReadCloser wraps a [io.Reader] to satisfy
+// [io.ReadCloser] if needed
+func NewReadCloser(r io.Reader) io.ReadCloser {
+	switch p := r.(type) {
+	case io.ReadCloser:
+		return p
+	case nil:
+		return nil
+	default:
+		return &ReadCloser{
+			r: r,
+		}
+	}
+}
+
+// NewReadCloserBytes wraps a bytes slice to implement
+// a [io.ReadCloser]
+func NewReadCloserBytes(b []byte) io.ReadCloser {
+	return NewReadCloser(bytes.NewReader(b))
+}
+
+// NewReadCloserString wraps a string to implement
+// a [io.ReadCloser]
+func NewReadCloserString(s string) io.ReadCloser {
+	return NewReadCloser(strings.NewReader(s))
+}

reflection/error.go

@@ -0,0 +1,69 @@
+package reflection
+
+import (
+	"bytes"
+	"fmt"
+	"reflect"
+)
+
+// An InvalidUnmarshalError describes an invalid argument passed to New.
+// (It must be a non-nil pointer.)
+type InvalidUnmarshalError struct {
+	Method string
+	Prefix string
+
+	reflect.Type
+}
+
+func (e *InvalidUnmarshalError) Error() string {
+	var buf bytes.Buffer
+
+	if e.Prefix != "" {
+		_, _ = fmt.Fprintf(&buf, "%s: ", e.Prefix)
+	}
+
+	method := e.Method
+	if method == "" {
+		method = "New"
+	}
+
+	_, _ = fmt.Fprintf(&buf, "%s(", method)
+
+	switch {
+	case e.Type == nil:
+		_, _ = buf.WriteString("nil")
+	case e.Type.Kind() != reflect.Pointer:
+		_, _ = fmt.Fprintf(&buf, "%s %s", "non-pointer", e.Type.String())
+	default:
+		_, _ = fmt.Fprintf(&buf, "%s %s", "nil", e.Type.String())
+	}
+
+	_, _ = buf.WriteString(")")
+
+	return buf.String()
+}
+
+// An UnmarshalTypeError tells something went wrong while processing
+// a type.
+type UnmarshalTypeError struct {
+	Prefix string
+	Err    error
+
+	reflect.Type
+}
+
+func (e UnmarshalTypeError) Unwrap() error {
+	return e.Err
+}
+
+func (e UnmarshalTypeError) Error() string {
+	var buf bytes.Buffer
+
+	if e.Prefix != "" {
+		_, _ = fmt.Fprintf(&buf, "%s: ", e.Prefix)
+	}
+
+	_, _ = fmt.Fprintf(&buf, "%s: %s", e.Type.String(), e.Err)
+
+	return buf.String()
+}

reflection/reflect_help.go

@@ -0,0 +1,16 @@
+package reflection
+
+import (
+	"fmt"
+	"reflect"
+)
+
+func structFieldName(sf reflect.StructField) string {
+	if sf.Anonymous {
+		idx := sf.Index[len(sf.Index)-1]
+
+		return fmt.Sprintf("%s-%v", "anonymous", idx)
+	}
+
+	return sf.Name
+}

reflection/reflection.go

@@ -0,0 +1,40 @@
+// Package reflection helps Marshalling/Unmarshalling data to structs
+package reflection
+
+import (
+	"reflect"
+)
+
+// Reflection provides Marshalling/Unmarshalling oriented view
+// of a value
+type Reflection struct {
+	v reflect.Value
+
+	types map[reflect.Type]TypeInfo
+}
+
+// Value returns the object it reflects
+func (r *Reflection) Value() any {
+	return r.v.Interface()
+}
+
+// New creates a Reflection of the given pointer
+func New(v any) (*Reflection, error) {
+	rv := reflect.ValueOf(v)
+
+	if rv.Kind() != reflect.Pointer || rv.IsNil() {
+		err := &InvalidUnmarshalError{Type: rv.Type()}
+		return nil, err
+	}
+
+	r := &Reflection{
+		v:     rv,
+		types: make(map[reflect.Type]TypeInfo),
+	}
+
+	if err := r.scan(); err != nil {
+		return nil, err
+	}
+
+	return r, nil
+}

reflection/scan.go

@@ -0,0 +1,37 @@
+package reflection
+
+import (
+	"reflect"
+)
+
+func (r *Reflection) scanType(rt reflect.Type) error {
+	switch rt.Kind() {
+	case reflect.Pointer, reflect.Slice:
+		rt = rt.Elem()
+	}
+
+	if _, ok := r.types[rt]; ok {
+		// cached
+		return nil
+	}
+
+	ti, err := NewTypeInfo(rt)
+	if err != nil {
+		return &UnmarshalTypeError{Type: rt, Err: err}
+	}
+
+	r.types[rt] = ti
+
+	for i := range ti.fields {
+		err := r.scanType(ti.fields[i].sf.Type)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (r *Reflection) scan() error {
+	return r.scanType(r.v.Type())
+}

reflection/typeinfo.go

@@ -0,0 +1,108 @@
+package reflection
+
+import (
+	"log"
+	"reflect"
+
+	"github.com/fatih/structtag"
+	"github.com/pkg/errors"
+)
+
+// TypeInfo ...
+type TypeInfo struct {
+	rt reflect.Type
+
+	fields []TypeInfoField
+}
+
+// Type ...
+func (ti *TypeInfo) Type() reflect.Type {
+	return ti.rt
+}
+
+// Kind ...
+func (ti *TypeInfo) Kind() reflect.Kind {
+	return ti.rt.Kind()
+}
+
+// TypeInfoField ...
+type TypeInfoField struct {
+	sf   reflect.StructField
+	tags *structtag.Tags
+
+	Name string
+}
+
+// Type ...
+func (tif *TypeInfoField) Type() reflect.Type {
+	return tif.sf.Type
+}
+
+// Kind ...
+func (tif *TypeInfoField) Kind() reflect.Kind {
+	return tif.sf.Type.Kind()
+}
+
+// Tag ...
+func (tif *TypeInfoField) Tag(key string) (*structtag.Tag, bool) {
+	if tif.tags != nil {
+		tag, _ := tif.tags.Get(key)
+		if tag != nil {
+			return tag, true
+		}
+	}
+	return nil, false
+}
+
+// NewTypeInfo ...
+func NewTypeInfo(rt reflect.Type) (TypeInfo, error) {
+	log.Printf("%s.%s: %s (%s)", "reflection", "NewTypeInfo", rt, rt.Kind())
+
+	ti := TypeInfo{
+		rt: rt,
+	}
+
+	err := ti.init()
+	return ti, err
+}
+
+func (ti *TypeInfo) init() error {
+	switch ti.Kind() {
+	case reflect.Struct:
+		return ti.initStruct()
+	default:
+		return nil
+	}
+}
+
+func (ti *TypeInfo) initStruct() error {
+	// load fields
+	n := ti.rt.NumField()
+	fields := make([]TypeInfoField, 0, n)
+	for i := 0; i < n; i++ {
+		sf := ti.rt.Field(i)
+		tags, err := structtag.Parse(string(sf.Tag))
+
+		if err != nil {
+			// tag parse error
+			err = &UnmarshalTypeError{
+				Type: ti.rt,
+				Err:  errors.Wrap(err, structFieldName(sf)),
+			}
+			return err
+		}
+
+		if sf.IsExported() {
+			log.Printf("%s.%s:   [%v]: %q %s (%s)",
+				"reflection", "NewTypeInfo",
+				i, structFieldName(sf), sf.Type, sf.Type.Kind())
+
+			fields = append(fields, TypeInfoField{
+				sf:   sf,
+				tags: tags,
+			})
+		}
+	}
+	ti.fields = fields
+	return nil
+}

tools/revive.toml

@@ -0,0 +1,35 @@
+ignoreGeneratedHeader = false
+severity = "error"
+confidence = 0.8
+errorCode = 1
+warningCode = 0
+enableAllRules = true
+
+[rule.function-length]
+  arguments = [40,0]
+  severity = "warning"
+[rule.function-result-limit]
+  arguments = [3]
+[rule.argument-limit]
+  arguments = [5]
+[rule.cognitive-complexity]
+  arguments = [7]
+[rule.cyclomatic]
+  arguments = [10]
+[rule.line-length-limit]
+  arguments = [100]
+  severity = "warning"
+[rule.comment-spacings]
+  severity = "warning"
+[rule.empty-lines]
+  severity = "warning"
+
+# Disabled rules
+[rule.max-public-structs]
+  disabled = true
+[rule.file-header]
+  disabled = true
+[rule.add-constant]
+  disabled = true
+[rule.banned-characters]
+  disabled = true

tools/tools.go

@@ -0,0 +1,7 @@
+//go:build tools
+
+package tools
+
+import (
+	_ "github.com/mgechev/revive"
+)