CHORUS/vendor/github.com/ipld/go-ipld-prime/HACKME.md

hackme
======

Design rational are documented here.

This doc is not necessary reading for users of this package,
but if you're considering submitting patches -- or just trying to understand
why it was written this way, and check for reasoning that might be dated --
then it might be useful reading.

It may also be an incomplete doc.  It's been written opportunistically.
If you don't understand the rationale for some things, try checking git history
(many of the commit messages are downright bookish), or get in touch via
a github issue, irc, matrix, etc and ask!


about NodeAssembler and NodeBuilder
-----------------------------------

See the godoc on these types.

In short, a `NodeBuilder` is for creating a new piece of memory;
a `NodeAssembler` is for instantiating some memory which you already have.

Generally, you'll start any function using a `NodeBuilder`, but then continue
and recurse by passing on the `NodeAssembler`.

See the `./HACKME_builderBehaviors.md` doc for more details on
high level rules and implementation patterns to look out for.



about NodePrototype
---------------

### NodePrototype promises information without allocations

You'll notice nearly every `ipld.NodePrototype` implementation is
a golang struct type with _zero fields_.

This is important.
Getting a NodePrototype is generally expected to be "free" (i.e., zero allocations),
while `NewBuilder` is allowed to be costly (usually causes at least one allocation).
Zero-member structs can be referred to by an interface without requiring an allocation,
which is how it's possible ensure `NodePrototype` are always "free" to refer to.

(Note that a `NodePrototype` that bundles some information like ADL configuration
will subvert this pattern -- but these are an exception, not the rule.)

### NodePrototype reported by a Node

`ipld.NodePrototype` is a type that opaquely represents some information about how
a node was constructed and is implemented.  The general contract for what
should happen when asking a node about its prototype
(via the `ipld.Node.Prototype() NodePrototype` interface) is that prototype should contain
effective instructions for how one could build a copy of that node, using
the same implementation details.

By example, if some node `n` was made as a `basicnode.plainString`,
then `n.Prototype()` will be `basicnode.Prototype.String`,
and `n.Prototype().NewBuilder().AssignString("xyz")` can be presumed to work.

Note there are also limits to this: if a node was built in a flexible way,
the prototype it reports later may only report what it is now, and not return
that same flexibility again.
By example, if something was made as an "any" -- i.e.,
via `basicnode.Prototype.Any.NewBuilder()`, and then *happened* to be assigned a string value --
the resulting node will still carry a `Prototype()` property that returns
`basicnode.Prototype.String` -- **not** `basicnode.Prototype.Any`.

#### NodePrototype meets generic transformation

One of the core purposes of the `NodePrototype` interface (and all the different
ways you can get it from existing data) is to enable the `traversal` package
(or other user-written packages like it) to do transformations on data.

// work-in-progress warning: generic transformations are not fully implemented.

When implementating a transformation that works over unknown data,
the signiture of function a user provides is roughly:
`func(oldValue Node, acceptableValues NodePrototype) (Node, error)`.
(This signiture may vary by the strategy taken by the transformation -- this
signiture is useful because it's capable of no-op'ing; an alternative signiture
might give the user a `NodeAssembler` instead of the `NodePrototype`.)

In this situation, the transformation system determines the `NodePrototype`
(or `NodeAssembler`) to use by asking the parent value of the one we're visiting.
This is because we want to give the update function the ability to create
any kind of value that would be accepted in this position -- not just create a
value of the same prototype as the one currently there!  It is for this reason
the `oldValue.Prototype()` property can't be used directly.

At the root of such a transformation, we use the `node.Prototype()` property to
determine how to get started building a new value.

#### NodePrototype meets recursive assemblers

Asking for a NodePrototype in a recursive assembly process tells you about what
kind of node would be accepted in an `AssignNode(Node)` call.
It does *not* make any remark on the fact it's a key assembler or value assembler
and might be wrapped with additional rules (such as map key uniqueness, field
name expectations, etc).

(Note that it's also not an exclusive statement about what `AssignNode(Node)` will
accept; e.g. in many situations, while a `Prototype.MyStringType` might be the prototype
returned, any string kinded node can be used in `AssignNode(Node)` and will be
appropriately converted.)

Any of these paths counts as "recursive assembly process":

- `MapAssembler.KeyPrototype()`
- `MapAssembler.ValuePrototype(string)`
- `MapAssembler.AssembleKey().Prototype()`
- `MapAssembler.AssembleValue().Prototype()`
- `ListAssembler.ValuePrototype()`
- `ListAssembler.AssembleValue().Prototype()`

### NodePrototype for carrying ADL configuration

// work-in-progress warning: this is an intention of the design, but not implemented.