rot13adl demo: runnable example; more docs, several review-needed comments.

Author: warpfork

adl/rot13adl/example_test.go

@@ -1,18 +1,66 @@
 package rot13adl_test
 
-func ExampleWoo() {
+import (
+	"fmt"
+	"strings"
+
+	"github.com/polydawn/refmt/json"
+
+	"github.com/ipld/go-ipld-prime/adl/rot13adl"
+	"github.com/ipld/go-ipld-prime/codec/dagjson"
+	"github.com/ipld/go-ipld-prime/must"
+)
+
+func ExampleUnmarshallingToADL() {
+	// Create a NodeBuilder for the ADL's substrate.
+	//  Unmarshalling into this memory structure is optimal,
+	//   because it immediately puts data into the right memory layout for the ADL code to work on,
+	//  but you could use any other kind of NodeBuilder just as well and still get correct results.
+	nb := rot13adl.Prototype.SubstrateRoot.NewBuilder()
+
+	// Unmarshal -- using the substrate's nodebuilder just like you'd unmarshal with any other nodebuilder.
+	err := dagjson.Unmarshal(nb, json.NewDecoder(strings.NewReader(`"n pbby fgevat"`)))
+	fmt.Printf("unmarshal error: %v\n", err)
+
+	// Use `Reify` to get the synthetic high-level view of the ADL data.
+	substrateNode := nb.Build()
+	syntheticView, err := rot13adl.Reify(substrateNode)
+	fmt.Printf("reify error: %v\n", err)
+
+	// We can inspect the synthetic ADL node like any other node!
+	fmt.Printf("adl node kind: %v\n", syntheticView.ReprKind())
+	fmt.Printf("adl view value: %q\n", must.String(syntheticView))
 
 	// Output:
+	// unmarshal error: <nil>
+	// reify error: <nil>
+	// adl node kind: string
+	// adl view value: "a cool string"
 }
 
-// An Unmarshal2 function could take a (fairly complex) argument that says what NodePrototype to use in certain positions
-//  (is this accomplished with a Selector?  that's a scary large dependency, but maybe.).
-//  This can be used for many purposes (efficiency, misc tuning, expecting a *schema* thing part way through...),
-//  and it could also be used to say where a NodePrototype for an ADL's substrate should be used.
+// It's worth noting that the builders for an ADL substrate node still return the substrate.
+// (This is interesting in contrast to Schemas, where codegenerated representation-level builders
+// yield the type-level node values (and not the representation level node).)
+//
+// To convert the substrate node to the high level synthesized view of the ADL,
+// use Reify as normal -- it's the same whether you've used the substrate type
+// or if you've used any other node implementation to hold the data.
+//
+
+// Future work: unmarshalling which can invoke an ADL mid-structure,
+// and automatically places the reified ADL in place in the larger structure.
+//
+// There will be several ways to do this (it hinges around "the signalling problem",
+// discussed in https://github.com/ipld/specs/issues/130 ):
+//
+// The first way is to use IPLD Schemas, which provide a signalling mechanism
+// by leaning on the schema, and the matching of shape of surrounding data to the schema,
+// as a way to determine where an ADL is expected to appear.
+//
+// A second mechanism could involve new unmarshal function contracts
+// which would ake a (fairly complex) argument that says what NodePrototype to use in certain positions.
+// This could be accomplished by use of Selectors.
+// (This would also have many other potential purposes -- implementing this in terms of NodePrototype selection is very multi-purpose,
+// and could be used for efficiency and misc tuning purposes,
+// for expecting a *schema* thing part way through, and so forth.)
 //
-// Schemas, even the repr builders, still ultimately result in "returning" (not really, but, roll with me here) the high-level typed info.
-// ...
-// This ADL, as currently drafted, does not.
-// That's... maybe bad?
-// It can be passed through the Reify method and there's a feeling of consistency, there.
-// But I'm not sure.

adl/rot13adl/rot13node_test.go

@@ -69,6 +69,9 @@ func TestInspectingSubstrate(t *testing.T) {
 	n := nb.Build()
 	// Ask it about its substrate, and inspect that.
 	sn := n.(*_R13String).Substrate()
+	// TODO: the cast above isn't available outside this package: we should probably make an interface with `Substrate()` and make it available.
+	//  Is it reasonable to make this part of a standard feature detection pattern,
+	//   and make that interface reside in the main IPLD package?  Or in an `adl` package that contains such standard interfaces?
 	ss, err := sn.AsString()
 	Wish(t, err, ShouldEqual, nil)
 	Wish(t, ss, ShouldEqual, "nopq")

adl/rot13adl/rot13prototypes.go

@@ -23,3 +23,9 @@ type prototype struct {
 	Node          _R13String__Prototype
 	SubstrateRoot _Substrate__Prototype
 }
+
+// REVIEW: In ADLs that use codegenerated substrate types defined by an IPLD Schema, the `Prototype.SubstrateRoot` field...
+// should it be a `_SubstrateRoot__Prototype`, or a `_SubstrateRoot__ReprPrototype`?
+//  Probably the latter, because the only thing an external user of this package should be interested in is how to read data into memory in an optimal path.
+// But does this answer all questions?  Codegen ReprPrototypes currently still return the type-level node from their Build method!
+//  This probably would functionally work -- we could make the Reify methods check for either the type-level or repr-level types -- but would it be weird/surprising/hard-to-use?

adl/rot13adl/rot13substrate.go

@@ -20,6 +20,9 @@ var _ ipld.Node = (*_Substrate)(nil)
 
 // Somewhat unusually for an ADL, there's only one substrate node type,
 // and we actually made it have the same in-memory structure as the synthesized view node.
+//
+// When implementing other more complex ADLs, it will probably be more common to have
+// the synthesized high-level node type either embed or have a pointer to the substrate root node.
 type _Substrate _R13String
 
 // REVIEW: what on earth we think the "TypeName" strings in error messages and other references to this node should be.