reflective: Add Reflection{} placeholder and the New() factory

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

lexer/error.go

@@ -25,17 +25,29 @@ type Error struct {
 	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
 
-	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)
+	prefix := err.prefix()
+	if prefix != "" {
+		s = append(s, prefix)
 	}
 
 	if err.Err != nil {
@@ -46,6 +58,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, ": ")
 }
 

reflective/docs.go

@@ -0,0 +1,2 @@
+// Package reflective assists reflection-driven unmarshalling
+package reflective

reflective/error.go

@@ -0,0 +1,69 @@
+package reflective
+
+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()
+}

reflective/reflection.go

@@ -0,0 +1,27 @@
+package reflective
+
+import "reflect"
+
+// Reflection provides Marshalling/Unmarshalling oriented view
+// of a value
+type Reflection struct {
+	v reflect.Value
+}
+
+// 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,
+	}
+
+	return r, nil
+}