GitLab

Port 2021 07 21

See merge request !1

This CID has not been verified - dag-json w/ sha2-512 capped at 4 bytes for
a block that's non-trivial to reconstruct manually.

After experimenting with quip and qp for a few months, we seem to agree
that qp is a bit nicer to use. Remove quip, since it's largely redundant
going forward.

Since the qp docs referenced quip, redo that to stand on its own ground.

Fixes #185.

Moving from bindnode, and adding a Type method for consistency with
TypedNode.

Fixes #181.

Before, we envisioned exposing the following APIs:

	Prototype
	PrototypeNoSchema
	PrototypeOnlySchema
	Wrap
	WrapNoSchema

The names were long, though, and perhaps a bit confusing too. Instead,
just expose Prototype and Wrap, and allow either of the parameters to be
nil to infer its value. This makes the API easier to navigate, and we
can concentrate documentation in fewer places.

Now there's two main entrypoints: Prototype if one wants a high-level
prototype to create nodes of a certain shape, and Wrap if one wants to
expose an existing Go value as an IPLD node. Whether one supplies only
an IPLD Schema, only a Go type/value, or both, is their choice. The only
exception is Wrap, which always requires a Go value by definition.

Wrap works now, too, and gains an example. It's the same idea as the
previous Prototype example, but it builds the value via a Go composite
literal rather than fluent/qp on the IPLD side.

Another noteworthy change is that we now return TypedPrototype and
TypedNode rather than the regular NodePrototype and Node interfaces,
since bindnode always works with a schema - even when it's inferred.
The big advantage here is that one can call the Representation method
directly on the result without having to type assert, like the example
does.

Including LookupBySegment and LookupByNode for both maps and lists, but
also As<T> for the representation form of all scalar kinds.

While at it, expand the interface implementation assertions, too.

Note that we had to make the node/basic tests external,
for the sake of testing LookupByNode without inserting an import cycle.

In particular, calling non-scalar Node and Assembler methods should
always fail.

While at it, remove some unused code, since unions always have
representation strategies.

Brings up code coverage in bindnode from 72.7% to 75%.

It covers AssignKind, AssignNode, and AsKind for every combination of
assembler kind and method.

We also verify that a constructed scalar node behaves the same with
AsKind when using its representation, like the old test.

There's effectively a triple loop as a test table, so the subtest name
has up to three components separated by dashes, such as:

	TestSchema/Scalars/Bytes-AssignNode-String

We also use this test as a demo of quicktest instead of go-wish.

Finally, adapt bindnode to pass these tests just like codegen. This was
mainly a bunch of TODOs in the relevant methods.

We add node/tests.SchemaTestAll to simplify this task, meaning we don't
need to duplicate all test func declarations in node/bindnode.
SchemaTestAll is also flexible enough to allow running multiple
sub-tests per schema test in the future.

There were two remaining places in node/tests that still weren't using
ipld.DeepEqual, so fix those.

Finally, bindnode needed a couple of changes to fully support
ipld.DeepEqual. Most notable is iteration over maps, which required a
bit of a refactor to keep ordered keys.

Along with a generic Engine interface, so that they can be reused for
other ipld.Node implementations, such as bindnode.

node/bindnode will start using these in a follow-up commit, since this
one is large enough as is.

Tested that all three forms of testing schema/gen/go still work:

	go test

	CGO_ENABLED=0 go test

	go test -tags=skipgenbehavtests

Per https://github.com/ipld/go-ipld-prime/issues/175 and some discussions today.

Also touched up the docs for Next vs Done a bit while I was in the area;
they're not significantly changed, but there were some dangling antecedents
that didn't read very well, and now it's a bit better.

Lots of TODOs and polishing to do, but it passes the schema/gen/go tests
with minimal changes.

Follow-up commits will continue filling in the gaps and adding
documentation, notably examples. We'll also make the tests run by
default, after a bit of refactoring.

The funciton is carefully documented via godoc, so I'm not going to
attempt to document it here again. But as a high-level summary, it's
like a reflect.DeepEqual applied to the ipld.Node interface rather than
reflect.Value.

The only other two noteworthy details are that errors are treated as
panics, and Links are compared directly via ==.

Finally, we add table-driven tests to ensure all edge cases work.

Fixes #173.

Add enumerate methods to the multicodec registries.