bindnode

Documentation

Overview

Package bindnode provides an datamodel.Node implementation via Go reflection.

This package is EXPERIMENTAL; its behavior and API might change as it's still in development.

Index

• func Prototype(ptrType interface{}, schemaType schema.Type) schema.TypedPrototype
• func Unwrap(node datamodel.Node) (ptr interface{})
• func Wrap(ptrVal interface{}, schemaType schema.Type) schema.TypedNode

Examples

• Prototype (OnlySchema)
• Prototype (Union)
• Wrap (NoSchema)
• Wrap (WithSchema)

Functions

func Prototype

func Prototype(ptrType interface{}, schemaType schema.Type) schema.TypedPrototype

Prototype implements a schema.TypedPrototype given a Go pointer type and an IPLD schema type. Note that the result is also an datamodel.NodePrototype.

If both the Go type and schema type are supplied, it is assumed that they are compatible with one another.

If either the Go type or schema type are nil, we infer the missing type from the other provided type. For example, we can infer an unnamed Go struct type for a schema struct tyep, and we can infer a schema Int type for a Go int64 type. The inferring logic is still a work in progress and subject to change. At this time, inferring IPLD Unions and Enums from Go types is not supported.

When supplying a non-nil ptrType, Prototype only obtains the Go pointer type from it, so its underlying value will typically be nil. For example:

proto := bindnode.Prototype((*goType)(nil), schemaType)

Example (OnlySchema)

package main

import (
	"os"

	"github.com/ipld/go-ipld-prime/codec/dagjson"
	"github.com/ipld/go-ipld-prime/datamodel"
	"github.com/ipld/go-ipld-prime/fluent/qp"
	"github.com/ipld/go-ipld-prime/node/bindnode"
	"github.com/ipld/go-ipld-prime/schema"
)

func main() {
	ts := schema.TypeSystem{}
	ts.Init()
	ts.Accumulate(schema.SpawnString("String"))
	ts.Accumulate(schema.SpawnInt("Int"))
	ts.Accumulate(schema.SpawnStruct("Person",
		[]schema.StructField{
			schema.SpawnStructField("Name", "String", false, false),
			schema.SpawnStructField("Age", "Int", true, false),
			schema.SpawnStructField("Friends", "List_String", false, false),
		},
		schema.SpawnStructRepresentationMap(nil),
	))
	ts.Accumulate(schema.SpawnList("List_String", "String", false))

	schemaType := ts.TypeByName("Person")
	proto := bindnode.Prototype(nil, schemaType)

	node, err := qp.BuildMap(proto, -1, func(ma datamodel.MapAssembler) {
		qp.MapEntry(ma, "Name", qp.String("Michael"))
		qp.MapEntry(ma, "Friends", qp.List(-1, func(la datamodel.ListAssembler) {
			qp.ListEntry(la, qp.String("Sarah"))
			qp.ListEntry(la, qp.String("Alex"))
		}))
	})
	if err != nil {
		panic(err)
	}

	nodeRepr := node.(schema.TypedNode).Representation()
	dagjson.Encode(nodeRepr, os.Stdout)

}

Output:

{"Friends":["Sarah","Alex"],"Name":"Michael"}

Example (Union)

package main

import (
	"fmt"
	"os"

	"github.com/ipld/go-ipld-prime/codec/dagjson"
	"github.com/ipld/go-ipld-prime/datamodel"
	"github.com/ipld/go-ipld-prime/fluent/qp"
	"github.com/ipld/go-ipld-prime/node/bindnode"
	"github.com/ipld/go-ipld-prime/schema"
)

func main() {
	ts := schema.TypeSystem{}
	ts.Init()
	ts.Accumulate(schema.SpawnString("String"))
	ts.Accumulate(schema.SpawnInt("Int"))
	ts.Accumulate(schema.SpawnUnion("StringOrInt",
		[]schema.TypeName{
			"String",
			"Int",
		},
		schema.SpawnUnionRepresentationKeyed(map[string]schema.TypeName{
			"hasString": "String",
			"hasInt":    "Int",
		}),
	))

	schemaType := ts.TypeByName("StringOrInt")

	type CustomIntType int64
	type StringOrInt struct {
		String *string
		Int    *CustomIntType // We can use custom types, too.
	}

	proto := bindnode.Prototype((*StringOrInt)(nil), schemaType)

	node, err := qp.BuildMap(proto.Representation(), -1, func(ma datamodel.MapAssembler) {
		qp.MapEntry(ma, "hasInt", qp.Int(123))
	})
	if err != nil {
		panic(err)
	}

	fmt.Print("Type level DAG-JSON: ")
	dagjson.Encode(node, os.Stdout)
	fmt.Println()

	fmt.Print("Representation level DAG-JSON: ")
	nodeRepr := node.(schema.TypedNode).Representation()
	dagjson.Encode(nodeRepr, os.Stdout)
	fmt.Println()

	// Inspect what the underlying Go value contains.
	union := bindnode.Unwrap(node).(*StringOrInt)
	switch {
	case union.String != nil:
		fmt.Printf("Go StringOrInt.String: %v\n", *union.String)
	case union.Int != nil:
		fmt.Printf("Go StringOrInt.Int: %v\n", *union.Int)
	}

}

Output:

Type level DAG-JSON: {"Int":123}
Representation level DAG-JSON: {"hasInt":123}
Go StringOrInt.Int: 123

func Unwrap

func Unwrap(node datamodel.Node) (ptr interface{})

Unwrap takes an datamodel.Node implemented by Prototype or Wrap, and returns a pointer to the inner Go value.

Unwrap returns nil if the node isn't implemented by this package.

func Wrap

func Wrap(ptrVal interface{}, schemaType schema.Type) schema.TypedNode

Wrap implements a schema.TypedNode given a non-nil pointer to a Go value and an IPLD schema type. Note that the result is also an datamodel.Node.

Wrap is meant to be used when one already has a Go value with data. As such, ptrVal must not be nil.

Similar to Prototype, if schemaType is non-nil it is assumed to be compatible with the Go type, and otherwise it's inferred from the Go type.

Example (NoSchema)

package main

import (
	"os"

	"github.com/ipld/go-ipld-prime/codec/dagjson"
	"github.com/ipld/go-ipld-prime/node/bindnode"
)

func main() {
	type Person struct {
		Name    string
		Age     int64 // TODO: optional to match other examples
		Friends []string
	}
	person := &Person{
		Name:    "Michael",
		Friends: []string{"Sarah", "Alex"},
	}
	node := bindnode.Wrap(person, nil)

	nodeRepr := node.Representation()
	dagjson.Encode(nodeRepr, os.Stdout)

}

Output:

{"Age":0,"Friends":["Sarah","Alex"],"Name":"Michael"}

Example (WithSchema)

package main

import (
	"os"

	"github.com/ipld/go-ipld-prime/codec/dagjson"
	"github.com/ipld/go-ipld-prime/node/bindnode"
	"github.com/ipld/go-ipld-prime/schema"
)

func main() {
	ts := schema.TypeSystem{}
	ts.Init()
	ts.Accumulate(schema.SpawnString("String"))
	ts.Accumulate(schema.SpawnInt("Int"))
	ts.Accumulate(schema.SpawnStruct("Person",
		[]schema.StructField{
			schema.SpawnStructField("Name", "String", false, false),
			schema.SpawnStructField("Age", "Int", true, false),
			schema.SpawnStructField("Friends", "List_String", false, false),
		},
		schema.SpawnStructRepresentationMap(nil),
	))
	ts.Accumulate(schema.SpawnList("List_String", "String", false))

	schemaType := ts.TypeByName("Person")

	type Person struct {
		Name    string
		Age     *int64 // optional
		Friends []string
	}
	person := &Person{
		Name:    "Michael",
		Friends: []string{"Sarah", "Alex"},
	}
	node := bindnode.Wrap(person, schemaType)

	nodeRepr := node.Representation()
	dagjson.Encode(nodeRepr, os.Stdout)

}

Output:

{"Friends":["Sarah","Alex"],"Name":"Michael"}