Merge pull request #81 from ipld/fluent-reflect

Introduce fluent.Reflect convenience functions.

fluent/doc.go

@@ -6,10 +6,13 @@
 
 	Note that the fluent package creates wrapper objects in order to provide
 	the API conveniences that it does, and this comes at some cost to performance.
-	If you're optimizing for performance, using the fluent interfaces may be inadvisable.
+	If you're optimizing for performance, using some of the features of the
+	fluent package may be inadvisable (and some moreso than others).
 	However, as with any performance questions, benchmark before making decisions;
 	its entirely possible that your performance bottlenecks will be elsewhere
 	and there's no reason to deny yourself syntactic sugar if the costs don't
 	detectably affect the bottom line.
+	Various feature of the package will also attempt to document how costly they are in relative terms
+	(e.g. the fluent.Reflect helper methods are very costly;
 */
 package fluent

fluent/reflect.go

+package fluent
+
+import (
+	"fmt"
+	"reflect"
+	"sort"
+
+	"github.com/ipld/go-ipld-prime"
+)
+
+// Reflect creates a new Node by looking at a golang value with reflection
+// and converting it into IPLD Data Model.
+// This is a quick-and-dirty way to get data into the IPLD Data Model;
+// it's useful for rapid prototyping and demos,
+// but note that this feature is not intended to be suitable for "production" use
+// due to low performance and lack of configurability.
+//
+// The concrete type of the returned Node is determined by
+// the NodePrototype argument provided by the caller.
+//
+// No type information from the golang value will be observable in the result.
+//
+// The reflection will walk over any golang value, but is not configurable.
+// Golang maps become IPLD maps; golang slices and arrays become IPLD lists;
+// and golang structs become IPLD maps too.
+// When converting golang structs to IPLD maps, the field names will become the map keys.
+// Pointers and interfaces will be traversed transparently and are not visible in the output.
+//
+// An error will be returned if the process of assembling the Node returns any errors
+// (for example, if the NodePrototype is for a schema-constrained Node,
+// any validation errors from the schema will cause errors to be returned).
+//
+// A panic will be raised if there is any difficulty examining the golang value via reflection
+// (for example, if the value is a struct with unexported fields,
+// or if a non-data type like a channel or function is encountered).
+//
+// Some configuration (in particular, what to do about map ordering) is available via the Reflector struct.
+// That structure has a method of the same name and signiture as this one on it.
+// (This function is a shortcut for calling that method on a Reflector struct with default configuration.)
+//
+// Performance remarks: performance of this function will generally be poor.
+// In general, creating data in golang types and then *flipping* it to IPLD form
+// involves handling the data at least twice, and so will always be slower
+// than just creating the same data in IPLD form programmatically directly.
+// In particular, reflection is generally not fast, and this feature has
+// not been optimized for either speed nor allocation avoidance.
+// Other features in the fluent package will typically out-perform this,
+// and using NodeAssemblers directly (without any fluent tools) will be much faster.
+// Only use this function if performance is not of consequence.
+func Reflect(np ipld.NodePrototype, i interface{}) (ipld.Node, error) {
+	return defaultReflector.Reflect(np, i)
+}
+
+// ReflectIntoAssembler is similar to Reflect, but takes a NodeAssembler parameter
+// instead of a Node Prototype.
+// This may be useful if you need more direct control over allocations,
+// or want to fill in only part of a larger node assembly process using the reflect tool.
+// Data is accumulated by the NodeAssembler parameter, so no Node is returned.
+func ReflectIntoAssembler(na ipld.NodeAssembler, i interface{}) error {
+	return defaultReflector.ReflectIntoAssembler(na, i)
+}
+
+var defaultReflector = Reflector{
+	MapOrder: func(x, y string) bool {
+		return x < y
+	},
+}
+
+// Reflector allows configuration of the Reflect family of functions
+// (`Reflect`, `ReflectIntoAssembler`, etc).
+type Reflector struct {
+	// MapOrder is used to decide a deterministic order for inserting entries to maps.
+	// (This is used when converting golang maps, since their iteration order is randomized;
+	// it is not used when converting other types such as structs, since those have a stable order.)
+	// MapOrder should return x < y in the same way as sort.Interface.Less.
+	//
+	// If using a default Reflector (e.g. via the package-scope functions),
+	// this function is a simple natural golang string sort: it performs `x < y` on the strings.
+	MapOrder func(x, y string) bool
+}
+
+// Reflect is as per the package-scope function of the same name and signature,
+// but using the configuration in the Reflector struct.
+// See the package-scope function for documentation.
+func (rcfg Reflector) Reflect(np ipld.NodePrototype, i interface{}) (ipld.Node, error) {
+	nb := np.NewBuilder()
+	if err := rcfg.ReflectIntoAssembler(nb, i); err != nil {
+		return nil, err
+	}
+	return nb.Build(), nil
+}
+
+// ReflectIntoAssembler is as per the package-scope function of the same name and signature,
+// but using the configuration in the Reflector struct.
+// See the package-scope function for documentation.
+func (rcfg Reflector) ReflectIntoAssembler(na ipld.NodeAssembler, i interface{}) error {
+	// Cover the most common values with a type-switch, as it's faster than reflection.
+	switch x := i.(type) {
+	case map[string]string:
+		keys := make([]string, 0, len(x))
+		for k := range x {
+			keys = append(keys, k)
+		}
+		sort.Sort(sortableStrings{keys, rcfg.MapOrder})
+		ma, err := na.BeginMap(len(x))
+		if err != nil {
+			return err
+		}
+		for _, k := range keys {
+			va, err := ma.AssembleEntry(k)
+			if err != nil {
+				return err
+			}
+			if err := va.AssignString(x[k]); err != nil {
+				return err
+			}
+		}
+		return ma.Finish()
+	case map[string]interface{}:
+		keys := make([]string, 0, len(x))
+		for k := range x {
+			keys = append(keys, k)
+		}
+		sort.Sort(sortableStrings{keys, rcfg.MapOrder})
+		ma, err := na.BeginMap(len(x))
+		if err != nil {
+			return err
+		}
+		for _, k := range keys {
+			va, err := ma.AssembleEntry(k)
+			if err != nil {
+				return err
+			}
+			if err := rcfg.ReflectIntoAssembler(va, x[k]); err != nil {
+				return err
+			}
+		}
+		return ma.Finish()
+	case []string:
+		la, err := na.BeginList(len(x))
+		if err != nil {
+			return err
+		}
+		for _, v := range x {
+			if err := la.AssembleValue().AssignString(v); err != nil {
+				return err
+			}
+		}
+		return la.Finish()
+	case []interface{}:
+		la, err := na.BeginList(len(x))
+		if err != nil {
+			return err
+		}
+		for _, v := range x {
+			if err := rcfg.ReflectIntoAssembler(la.AssembleValue(), v); err != nil {
+				return err
+			}
+		}
+		return la.Finish()
+	case string:
+		return na.AssignString(x)
+	case []byte:
+		return na.AssignBytes(x)
+	case int:
+		return na.AssignInt(x)
+	case nil:
+		return na.AssignNull()
+	}
+	// That didn't fly?  Reflection time.
+	rv := reflect.ValueOf(i)
+	switch rv.Kind() {
+	case reflect.Bool:
+		return na.AssignBool(rv.Bool())
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return na.AssignInt(int(rv.Int()))
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		return na.AssignInt(int(rv.Uint()))
+	case reflect.Float32, reflect.Float64:
+		return na.AssignFloat(rv.Float())
+	case reflect.String:
+		return na.AssignString(rv.String())
+	case reflect.Slice, reflect.Array:
+		if rv.Type().Elem().Kind() == reflect.Uint8 { // byte slices are a special case
+			return na.AssignBytes(rv.Bytes())
+		}
+		l := rv.Len()
+		la, err := na.BeginList(l)
+		if err != nil {
+			return err
+		}
+		for i := 0; i < l; i++ {
+			if err := rcfg.ReflectIntoAssembler(la.AssembleValue(), rv.Index(i).Interface()); err != nil {
+				return err
+			}
+		}
+		return la.Finish()
+	case reflect.Map:
+		// the keys slice for sorting keeps things in reflect.Value form, because unboxing is cheap,
+		//  but re-boxing is not cheap, and the MapIndex method requires reflect.Value again later.
+		keys := make([]reflect.Value, 0, rv.Len())
+		itr := rv.MapRange()
+		for itr.Next() {
+			k := itr.Key()
+			if k.Kind() != reflect.String {
+				return fmt.Errorf("cannot convert a map with non-string keys (%T)", i)
+			}
+			keys = append(keys, k)
+		}
+		sort.Sort(sortableReflectStrings{keys, rcfg.MapOrder})
+		ma, err := na.BeginMap(rv.Len())
+		if err != nil {
+			return err
+		}
+		for _, k := range keys {
+			va, err := ma.AssembleEntry(k.String())
+			if err != nil {
+				return err
+			}
+			if err := rcfg.ReflectIntoAssembler(va, rv.MapIndex(k).Interface()); err != nil {
+				return err
+			}
+		}
+		return ma.Finish()
+	case reflect.Struct:
+		l := rv.NumField()
+		ma, err := na.BeginMap(l)
+		if err != nil {
+			return err
+		}
+		for i := 0; i < l; i++ {
+			fn := rv.Type().Field(i).Name
+			fv := rv.Field(i)
+			va, err := ma.AssembleEntry(fn)
+			if err != nil {
+				return err
+			}
+			if err := rcfg.ReflectIntoAssembler(va, fv.Interface()); err != nil {
+				return err
+			}
+		}
+		return ma.Finish()
+	case reflect.Ptr:
+		if rv.IsNil() {
+			return na.AssignNull()
+		}
+		return rcfg.ReflectIntoAssembler(na, rv.Elem())
+	case reflect.Interface:
+		return rcfg.ReflectIntoAssembler(na, rv.Elem())
+	}
+	// Some kints of values -- like Uintptr, Complex64/128, Channels, etc -- are not supported by this function.
+	return fmt.Errorf("fluent.Reflect: unsure how to handle type %T (kind: %v)", i, rv.Kind())
+}
+
+type sortableStrings struct {
+	a    []string
+	less func(x, y string) bool
+}
+
+func (a sortableStrings) Len() int           { return len(a.a) }
+func (a sortableStrings) Swap(i, j int)      { a.a[i], a.a[j] = a.a[j], a.a[i] }
+func (a sortableStrings) Less(i, j int) bool { return a.less(a.a[i], a.a[j]) }
+
+type sortableReflectStrings struct {
+	a    []reflect.Value
+	less func(x, y string) bool
+}
+
+func (a sortableReflectStrings) Len() int           { return len(a.a) }
+func (a sortableReflectStrings) Swap(i, j int)      { a.a[i], a.a[j] = a.a[j], a.a[i] }
+func (a sortableReflectStrings) Less(i, j int) bool { return a.less(a.a[i].String(), a.a[j].String()) }

fluent/reflect_test.go

+package fluent_test
+
+import (
+	"testing"
+
+	. "github.com/warpfork/go-wish"
+
+	ipld "github.com/ipld/go-ipld-prime"
+	"github.com/ipld/go-ipld-prime/fluent"
+	"github.com/ipld/go-ipld-prime/must"
+	basicnode "github.com/ipld/go-ipld-prime/node/basic"
+)
+
+func TestReflect(t *testing.T) {
+	t.Run("Map", func(t *testing.T) {
+		n, err := fluent.Reflect(basicnode.Prototype.Any, map[string]interface{}{
+			"k1": "fine",
+			"k2": "super",
+			"k3": map[string]string{
+				"k31": "thanks",
+				"k32": "for",
+				"k33": "asking",
+			},
+		})
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, n.ReprKind(), ShouldEqual, ipld.ReprKind_Map)
+		t.Run("CorrectContents", func(t *testing.T) {
+			Wish(t, n.Length(), ShouldEqual, 3)
+			Wish(t, must.String(must.Node(n.LookupByString("k1"))), ShouldEqual, "fine")
+			Wish(t, must.String(must.Node(n.LookupByString("k2"))), ShouldEqual, "super")
+			n := must.Node(n.LookupByString("k3"))
+			Wish(t, n.Length(), ShouldEqual, 3)
+			Wish(t, must.String(must.Node(n.LookupByString("k31"))), ShouldEqual, "thanks")
+			Wish(t, must.String(must.Node(n.LookupByString("k32"))), ShouldEqual, "for")
+			Wish(t, must.String(must.Node(n.LookupByString("k33"))), ShouldEqual, "asking")
+		})
+		t.Run("CorrectOrder", func(t *testing.T) {
+			itr := n.MapIterator()
+			k, _, _ := itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "k1")
+			k, _, _ = itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "k2")
+			k, v, _ := itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "k3")
+			itr = v.MapIterator()
+			k, _, _ = itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "k31")
+			k, _, _ = itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "k32")
+			k, _, _ = itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "k33")
+		})
+	})
+	t.Run("Struct", func(t *testing.T) {
+		type Woo struct {
+			A string
+			B string
+		}
+		type Whee struct {
+			X string
+			Z string
+			M Woo
+		}
+		n, err := fluent.Reflect(basicnode.Prototype.Any, Whee{
+			X: "fine",
+			Z: "super",
+			M: Woo{"thanks", "really"},
+		})
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, n.ReprKind(), ShouldEqual, ipld.ReprKind_Map)
+		t.Run("CorrectContents", func(t *testing.T) {
+			Wish(t, n.Length(), ShouldEqual, 3)
+			Wish(t, must.String(must.Node(n.LookupByString("X"))), ShouldEqual, "fine")
+			Wish(t, must.String(must.Node(n.LookupByString("Z"))), ShouldEqual, "super")
+			n := must.Node(n.LookupByString("M"))
+			Wish(t, n.Length(), ShouldEqual, 2)
+			Wish(t, must.String(must.Node(n.LookupByString("A"))), ShouldEqual, "thanks")
+			Wish(t, must.String(must.Node(n.LookupByString("B"))), ShouldEqual, "really")
+		})
+		t.Run("CorrectOrder", func(t *testing.T) {
+			itr := n.MapIterator()
+			k, _, _ := itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "X")
+			k, _, _ = itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "Z")
+			k, v, _ := itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "M")
+			itr = v.MapIterator()
+			k, _, _ = itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "A")
+			k, _, _ = itr.Next()
+			Wish(t, must.String(k), ShouldEqual, "B")
+		})
+	})
+	t.Run("NamedString", func(t *testing.T) {
+		type Foo string
+		type Bar struct {
+			Z Foo
+		}
+		n, err := fluent.Reflect(basicnode.Prototype.Any, Bar{"foo"})
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, n.ReprKind(), ShouldEqual, ipld.ReprKind_Map)
+		Wish(t, must.String(must.Node(n.LookupByString("Z"))), ShouldEqual, "foo")
+	})
+	t.Run("Interface", func(t *testing.T) {
+		type Zaz struct {
+			Z interface{}
+		}
+		n, err := fluent.Reflect(basicnode.Prototype.Any, Zaz{map[string]interface{}{"wow": "wee"}})
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, n.ReprKind(), ShouldEqual, ipld.ReprKind_Map)
+		n, err = n.LookupByString("Z")
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, n.ReprKind(), ShouldEqual, ipld.ReprKind_Map)
+		Wish(t, must.String(must.Node(n.LookupByString("wow"))), ShouldEqual, "wee")
+	})
+	t.Run("Bytes", func(t *testing.T) {
+		n, err := fluent.Reflect(basicnode.Prototype.Any, []byte{0x1, 0x2, 0x3})
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, n.ReprKind(), ShouldEqual, ipld.ReprKind_Bytes)
+		b, err := n.AsBytes()
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, b, ShouldEqual, []byte{0x1, 0x2, 0x3})
+	})
+	t.Run("NamedBytes", func(t *testing.T) {
+		type Foo []byte
+		type Bar struct {
+			Z Foo
+		}
+		n, err := fluent.Reflect(basicnode.Prototype.Any, Bar{[]byte{0x1, 0x2, 0x3}})
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, n.ReprKind(), ShouldEqual, ipld.ReprKind_Map)
+		n, err = n.LookupByString("Z")
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, n.ReprKind(), ShouldEqual, ipld.ReprKind_Bytes)
+		b, err := n.AsBytes()
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, b, ShouldEqual, []byte{0x1, 0x2, 0x3})
+	})
+	t.Run("InterfaceContainingBytes", func(t *testing.T) {
+		type Zaz struct {
+			Z interface{}
+		}
+		n, err := fluent.Reflect(basicnode.Prototype.Any, Zaz{[]byte{0x1, 0x2, 0x3}})
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, n.ReprKind(), ShouldEqual, ipld.ReprKind_Map)
+		n, err = n.LookupByString("Z")
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, n.ReprKind(), ShouldEqual, ipld.ReprKind_Bytes)
+		b, err := n.AsBytes()
+		Wish(t, err, ShouldEqual, nil)
+		Wish(t, b, ShouldEqual, []byte{0x1, 0x2, 0x3})
+	})
+}