Documentation
¶
Overview ¶
rot13adl is a demo ADL -- its purpose is to show what an ADL and its public interface can look like. It implements a "rot13" string: when creating data through the ADL, the user gives it a regular string; the ADL will create aninternal representation of it which has the characters altered in a reversable way.
It provides reference and example materal, but it's very unlikely you want to use it in real situations ;)
There are several ways to move data in and out of the ADL:
- treat it like a regular IPLD map:
- using the exported NodePrototype can be used to get a NodeBuilder which can accept keys and values;
- using the resulting Node and doing lookup operations on it like a regular map;
- load up raw substrate data and `Reify()` it into the synthesized form, and *then* treat it like a regular map:
- this is handy if the raw data already parsed into Nodes.
- optionally, use `SubstrateRootPrototype` as the prototype for loading the raw substrate data; any kind of Node is a valid input to Reify, but this one will generally have optimal performance.
- take the synthesized form and inspect its substrate data:
- the `Substrate()` method will return another ipld.Node which is the root of the raw substrate data, and can be walked normally like any other ipld.Node.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Prototype prototype
Prototype embeds a NodePrototype for every kind of Node implementation in this package. This includes both the synthesized node as well as the substrate root node (other substrate interior node prototypes are not exported here; it's unlikely they'll be useful outside of the scope of the ADL's implementation package.)
You can use it like this:
rot13adl.Prototype.Node.NewBuilder() //...
and:
rot13adl.Prototype.SubstrateRoot.NewBuilder() // ...
Functions ¶
func Reify ¶
func Reify(maybeSubstrateRoot ipld.Node) (ipld.Node, error)
Reify examines data in a Node to see if it matches the shape for valid substrate data for this ADL, and if so, synthesizes and returns the high-level view of the ADL. If it succeeds in recognizing the raw data as this ADL, Reify returns a new Node which exhibits the logical behaviors of the ADL; otherwise, it returns an error.
The input data can be any implementation of ipld.Node; it will be considered purely through that interface.
If your application is expecting ADL data, this pipeline can be optimized by using the SubstratePrototype right from the start when unmarshalling; then, Reify can detect if the rawRoot parameter is of that implementation, and it can save some processing work internally that can be known to already be done.
Reification will generally operate on the data in a single block (e.g. this function will not do any additional block loads and unmarshalling). This is important because some ADLs handle data so large that loading it all eagerly would be impractical (and in some cases outright impossible). However, it also necessarily implies that invalid data may lie beyond one of those lazy loads, and it won't be discovered at the time of Reify.
In this demo ADL, we don't have multi-block content at all, so of course we don't have any additional block loads! However, ADL implementations may vary in their approaches to lazy vs eager loading. All ADLs should document their exact semantics regarding this -- especially if it has any implications for boundaries of data validity checking.
REVIEW: this function is currently not conforming to any particular interface; if we evolve the contract for ADLs to include an interface for reficiation functions, might we need to add context and link loader systems as parameters to it? Not all implementations might need it, as per previous paragraph; but some might. Reification for multiblock ADLs might also need link loader systems as a parameter here so they can capture them as config and hold them for use in future operations that do lazy loading.
Source Files