GitLab

This is a draft.  There's a LOT of hard design choices which are not
yet completely settled here.

Corresponding updates to the ipld/specs repo will be coming soon:
these implementations match a very recursive concept of selectors.
(https://github.com/ipld/specs/pull/116 is roughly this.)

There's so many things to go over, here.

- selectors at all
- selectFields is kind of a special case of unions
- selectPath as a concept is gone; is a degenerate case of selectFields
- we've added some new methods to help narrow down search spaces
- we have serial selector spec parsers...!  (very hand-rolled.)
- the idea of always reporting candidates vs definite match parents
  is dropped for now; it requires a different algo with different
  performance characteristics, so, we'll do it as such -- later.
- we ended up with unions being *in*!  They're going to be used
  internally by a bunch of other things -- see comment blocks in
  the code about that (tl;dr recursives imply a need of unions).

More docs will be coming in future commits; this is just a checkpoint
of the progress.
Signed-off-by: Eric Myhre <hash@exultant.us>

We now have both MapIterator and ListIterator interfaces.
Both return key-value (or index-value) pairs, rather than just keys.

List iterators may seem a tad redundant: you just loop over the length,
right?  Well, sure.  But there's one place a list iterator shines:
selecting only a subset of elements.  And indeed, we'll be doing
exactly that in the traversal/selector package; therefore, we
definitely need list iterators.

We might want keys-only iterators again in the future, but at present,
I'm deferring that.  It's definitely true that we should have iterators
returning values as a core feature, since they're likely to be more
efficiently supportable than "random" access (especially when we get to
some Advanced Layout data systems), so we'll implement those first.

Additionally, note that MapIterator now returns a Node for the key.
This is to account for that fact that when using the schema system and
typed nodes, map keys can be more *specific* types.  Such nodes are
still required to be kind==ReprKind_String, but string might not be
their *preferred* native format (think: tuples with serialized to be
delimiter-separated strings); we need to account for that.
(MapBuilder.Insert method already takes a Node parameter for similar
reasons: so it can take *typed* nodes.  Node.TraverseField accepting
a plain string is the oddball out here, and should be rectified.)
Signed-off-by: Eric Myhre <hash@exultant.us>

Outline of Traverse* funcs; comment about link loaders in TraversalConfig; confession of working draft of Selector interface; fixed typo in AdvVisitFn return types.

Yes, that's lot of things heaped in one commit.

Yes, (unfortunately,) they're all related.  Almost the entirety of this
has to manifest *at once*, all seamlessly connected, for any part of
it to get off the ground.

Note how very much is handwaved in the comments about TraversalConfig
having linkloader tools of some kind.  There's a lot to unpack there.
Getting it to work well, and let users of the library supply functions
that customize the parts that are interesting to the user, while *not*
getting them hamstrung by a bunch of details about multicodecs and
multihashing (unless they want to!)... requires careful design work.
Signed-off-by: Eric Myhre <hash@exultant.us>