GitLab

Hopefully this increases clarity and eases comprehension.

Notes and discussion can be found at
https://github.com/ipld/go-ipld-prime/issues/54 (and also
I suppose in some of our weekly video chats, but I'd have
to go on quite a dig to find the relevant links and time).

Many many refernces to 'ns' are also updated to 'np',
making the line count in this diff pretty wild.

See the changelog for discussion; this had already been on the docket
for a while now.

... and it will further become LookupByNode shortly, but that will be
a separate commit.

See the changelog for discussion; this had already been on the docket
for a while now.

Codegen update -- Assemblers, and many new representations

(It's a small diff -- just reflecting the fix for map returing absent.)

... almost.  In attempting to put the sections about absent value
handling into place, I realized there's a decently sizable bug there
already.  I'm going to document this for now, move on, and come back
to it later... so it will continue to take up space in a "wip" doc.
The description of the situation is at least cleaned up now.

I spent some time poking around at other applications that I'd want to
be able to use some of this stuff on, and the lines about "minimalist"
come from that.  I suspect that in ideal outcomes, I'd like to be able
to sometimes be able to generate the type structures and native/typed
APIs for a Schema definition... but perhaps not generate all the stuff
necessary for the interface monomorphization, because perhaps I just
want an enum purely for internal program purposes; surely we should be
able to just do that.  We'll see though.  Maybe that's scope creep
as much as anything else.

All "genparts*" files are reusable bits of template;
all other "gen[A-Z](.*)" files are per kind.

Includes one code fix, as well: generated maps now return 'nil' for
the value of lookups when returning an error for not-found.
(I waffled on this for a while, because it's arguable that `ipld.Undef`
is a perfectly reasonable sentinel value for this, and it's *arguable*
that any sentinel value is better than nil.  However... no.
A much, much clearer rule is "if a method returns an error, the value
is nil", and that the contrapositive is also true: and that's what
we're now going with and sticking with.)

Probably well overdue already.  Previous entries are from a quick skim
of the git log, but may well have missed many interesting things.
Will be more arduous about this going forward.

Previously, it was manually written prototypes of what gen "would" look like.

Now it's the real deal :3

Going to move it over to replace the (currently hand-written) gendemo
package shortly... but spread that over a few commits, in case the
diffs turn out interesting to look at.

Less comments emitted in gen result.

Touch up the 'do not edit' comment.

Some of them still lived over the "gendemo" package, and those are now
moved over here to the proper gen package.

Linked to more of the other documents from the main HACKME doc.

A fair amount of stuff is finished.

A fair amount of stuff isn't.

These are all the type kinds and representation strategies outlined in
https://specs.ipld.io/schemas/representations.html .

This is pretty similar to the extractions that made it fly for lists.

I've added a few more comments to the "genparts*" files, because on
further reflection, a lot of those methods are... less reusable than
the name might seem to claim.  We'll see how those evolve.

Altered TestMapsContainingMaps quite a bit to now also test that
representation mode is tracked correctly across both read and creation
recursions, in a similar way to how TestListsContainingLists does
(e.g., uses some structs towards the leaf nodes, so it can use the
rename directives to create visible differences).

Correct representational creation mode still coming up, as you can
see in the fixme comment.

Tests will come in the next commit along with the creation mode.

Test for lists-of-lists and that representation-mode recursion works for both assembly and traversal.

It does.

Having a nil pointer dereference cause a panic *during* error stringing
is really unpleasant.

We shouldn't "ever" have this problem, when the library is done.
But right no we certainly do.

Would cause the same memory to get reused inappropriately; need the nil
value there to kick the child assembler to do the new allocation on the
next round.

A lot of the coments in earlier commit messages about choosing a path
and cutting through it roughly and leaving DRY for latter still
applies (see f1eeeafb).

The hardest part of writing this was giving up on having shared code
in the output.  It just can't be done along the current edges without
giving up some performance at runtime, and that's generally not a trade
we want to make.  Maybe there's different cuts for function boundaries
that would do better -- but we'll leave that for later fun work.

I did at least get a bunch of templates to be textually shared.

Comments abound in the diff for future possibilities, as well as what's
not possible to go further on without making undesired trades.

Key coloration is easy because we already have key emission in one place,
and we already have size computation for alignment separated from emission.
Value coloration will be a little more involved.

They do.

Alignment just proceeds around them, leaving appropriate space based on
what other rows needed in order to align with each other.

If a column is absent at the end of a row, the whole row wraps up fast.

They do.

The first two example fixtures of what I wanted to achieve pass now :3
That's exciting.