GitLab

As with parent commit: this is a checkpoint.  CI will not be passing.

Previously it was in the 'impl/typed' package, next to the
runtime-wrapper implementation of the interface.  This was strange.

Not only should those two things be separated just on principle,
this was also causing more import cycle problems down the road:
for example, the traversal package needs to consider the *interface*
for a schema-typed node in order to gracefully handle some features...
and if this also brings in a *concrete* dependency on the
runtime-wrapper implementation of typed nodes, not only is that
incorrect bloat, it becomes a show stopper because (currently, at
least) that implementation also in turn transitively imports the
ipldfree package for some of its scalars.  Ouchouch.

So.  Now the interface lives over in the 'schema' package, with all
the other interfaces for that feature set.  Where it probably always
should have been.

('typed.Maybe' also became known as 'schema.Maybe', which... does not
roll off the tongue as nicely.  But this is a minor concern and we
might reconsider the naming and appearance of that thing later anyway.)

Comments added addressing some of the root issues of why, and how to
try again more correctly next time.  (At least one open question
has been found that might take a few days to resolve.)

This commit happens now because they code being removed refered to
`schema.Type.ReprKind()` a lot, and that's the real issue I'm focused
on at the moment -- that's also going away in the next commit or so.
There's significantly more subtlety to the type-vs-representation
duality than the existence of such a method could accurately describe.

- `typed.Node` -> now lives in the `impl/typed` package, more like
other nodes.

- Most of the other essential parts of reasoning about types moved
to `schema` package.  ("typed.Type" seemed like a nasty stutter.)

- `typed.Universe` renamed to `schema.TypeSystem`.

- Current `Validate` method moved to `schema` package, but see new
comments about potential future homes of that code, and its
aspirational relationship to `typed.Node`.

Conspicuously *not* yet refactored or moved in this comment:

- The `typed/declaration` package -- though it will shortly be scrapped
and later reappear as `schema/ast`.  The dream is that it would be
neatest of all if we could generate it by codegen; but we'll see.
(This would seem to imply we'll have to make sufficient exported
methods for creating the `schema.Type` values... while we also want
to make those immutable.  We'll... see.)

- The `typed/gen` package is also untouched in this commit, but
should similarly move shortly.  The codegen really ought to be built
against the `schema.Type` reified interfaces.

Overall, this drops the sheer nesting depths of packages a fair bit,
which seems likely to be a good smell.

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>

Having a function called "Kind" return a "ReprKind" was inconsistent.

Also, we want to introduce a "Kind" method on `typed.Node` in the future.

No logical content to this change: you can safely refactor with sed.
Signed-off-by: Eric Myhre <hash@exultant.us>

An "immediate" rather than generative function is also available;
the docs contain caveats.

At the moment, these distinctions are a bit forced, but we want to be
ready for when we start getting truly huge maps where the generative
usage actually *matters* for either memory reasons, latency reasons,
or both.

Separated Length rather than trying to pull double-duty the Keys
method; the previous combination was just utterly silly.

The implementations in the bind package are stubs; that package is
going to take a lot of work, and so the focus is going to be entirely
on keeping the 'free' package viable; and we'll revisit bind and such
when there's more dev time budget.
Signed-off-by: Eric Myhre <hash@exultant.us>

ISTM that since we're talking about raw data more so than "objects" in
any kind of Alan-Kay/sending-messages/OOP sort of way, calling it
"struct" is more accurate communication.

(It's also a lot less likely to be confusing when mentioned in the same
context as javascript, since "object" and "map" tend to be collisiony
terms there; whereas "struct" just doensn't really have any prior
associations in that community as far as I know.)
Signed-off-by: Eric Myhre <hash@exultant.us>

...and all fields are correspondingly unexported.

We're going full immutability on almost all this stuff.  I simply can't
imagine handling and maintaining this any other way.

The typesystem.Type interface also got a few more standard methods.
I'm not sure if having a Universe backpointer is going to be useful
very often or not, but it seems reasonable enough to do; we'll
definitely *have* that information during consistency checking and
reification time, so it should turn out easy to keep it.

The validate_test.go code is now looking a bit janky.  We need
initializers for the typesystem.Type* values.  Those will be the
typedeclaration.* package... which we'll write next.

Note that I skipped any accessor methods on `Type*` objects which are
for representation details.  These might get filled in later, but I'm
gonna see how far I can get without them.  (So far, there's some
uses of the representation details in the validate method, but we've
located that in the typesystem package anyway, so that's... fine.)
Signed-off-by: Eric Myhre <hash@exultant.us>

See previous commit for more discussion of the child packages to come,
or the schema.md file in the docs dir, which describes similar.

Several large todos in comments.

Quite importantly: typed.Node is now an **interface**, not a concrete
struct itself.  The godoc comment should explain this nicely; long
story short, this is going to be relevant when we get to codegen and
other advanced form of native integration.
Signed-off-by: Eric Myhre <hash@exultant.us>

I need there to be separate packages for:

- the typed.Node interface, and any top level helpers;
- the typesystem implementation
- the typesystem *declarations* (distinct because it's what you
 construct when parsing the ast -- doens't contain pointers yet)
- and (eventually) a parser and a fmt package for the ts declarations.

And right now all those are heaped together.

Not sure where the validate method -- the thing that's actually touched
in this diff -- will end up.  Either the top level, or the typesystem
implementation package, probably.
Signed-off-by: Eric Myhre <hash@exultant.us>

This will be for the active path -- if we also follow through on the
idea of having a just-in-time checked Node wrapper, a lot of these
checks might end up duplicated.  We'll DRY that up when we get there.

Doing accumulation of errors.  Might get loud.  We can come back and
and early-halt parameters or other accumulation strategies later.

Added IsNull predicate to core Node interface.

Going to want enumerated error categories here for sure, but punting
on that until we get more examples of what all the errors *are*; then
I'll come back and tear all this 'fmt.Errorf' nonsense back out.
Signed-off-by: Eric Myhre <hash@exultant.us>

And ReprKind moves from the typed package to the ipld main package.
It's hard to get too much done without the standardization of ReprKind.

Between the Kind() and Keys() methods, it should now be possible to
perform traversals of unknown nodes.

This diff just worries about implementing all the Kind() methods.
Keys() has some additional questions to handle (namely, map ordering?).
Signed-off-by: Eric Myhre <hash@exultant.us>