L3N: Flat Trees!

Construct and traverse trees with a coherent set of functions.

L3 trees can express HTML, XML, JSON or functional programs.

The Concept

Many documents can be iterated as a flat sequence of nodes, be it an XML or HTML document, a piece of JSON or even a functional program (see Raddle). The way documents are traversed is in document order, just like a SAX parser: an event is emitted for when a branch opens or closes, or when a (text) leaf is completed.

This library stores all familiar document nodes as plain JSON by using a simple convention. Traversal of documents is exposed as an Observable stream (uses RxJS 6). This ensures that there's no difference between traversing an in-memory tree or connecting to a SAX-style parser: everything is a stream.

Each node that is emitted on the stream is wrapped in a transient container that provides a reference to the parent node (see the VNode class). In addition, the VNode interface exposes more relevant properties, such as its depth relative to the root or its position relative to its parent. These enable traversal across all DOM axes. Furthermore, node names and values may be indexed to increase performance.

This library provides an immutable alternative to plain JSON (via the pnode context) and a native DOM context for the browser. The traversal context may be switched by simply binding each accessor function to another context module.

For native DOM traversal in the browser, the VNode integrates with the canonical TreeWalker API (uses ES6 WeakMap).

Note: you should not create references to VNode instances, or they can't be garbage collected. Transform them functionally instead, by using RxJS or a specialized library (see Frink).

Install / setup

npm i l3n

The easiest way to get started is with the Node.js distribution:

``javascript
const l3 = require("l3n");

// Direct construction of a document-fragment, no Rx:

const frag = l3.t(
l3.e("div",
l3.a("class","greeting"),
l3.e("p","Hello")
)
)

console.log(frag.toString());

console.log(frag.toJS());
`

`javascript
// Alternatively, you can pass a 'document implementation context' to the faux VNode directly.
// Below example will create a persistent tree
const div = l3.e("div",
l3.a("class","greeting"),
l3.e("p","Hello")
).node(l3.pnode);

console.log(div.toString());

console.log(div.toJS());
`

API documentation (WIP)

Documentation index: index

Examples (ES modules)

`javascript
import { e, m, a, ensureDoc } from "l3n";

const div = e("div",
a("class","greeting"),
e("p","Hello")
);

const map = m(
a("greeting","Hello")
);
`

$3

`javascript
ensureDoc(div).subscribe(vnode => {
console.log(vnode.toString());
});
`

yields

`html

Hello

`

while

`javascript
ensureDoc(map).subscribe(vnode => {
console.log(vnode.toString());
});
`

yields

`html
Hello
`

$3

`javascript
ensureDoc(div).subscribe(vnode => {
console.log(vnode.toJS());
});
`

yields

`json
{
"$name":"div",
"class":"greeting",
"$children":[{
"$name":"p",
"$children":["Hello"]
}]
}
`

while

`javascript
ensureDoc(map).subscribe(vnode => {
console.log(vnode.toJS());
});
`

yields

`json
{
"greeting":"Hello"
}
`

Serialization rules

L3N serialization rules for JSON:

| Constant | VNode Type | Appearance |
| -------- | ------------------------- | ----------- |
| 1 | Element | {"$name":"qname","some-attr":"some-value","$children":[]} |
| 3 | teXt | "some-text" |
| 4 | Reference | {"$ref":"/some/path"} |
| 5 | List | [] |
| 6 | Map | {} |
| 7 | Processing instruction | {"$pi"":"xml-stylesheet "\"type\"=\"text/xsl\" \"href\"=\"some.xsl\""} |
| 8 | Comment | {"$comment":"some-comment"}|
| 12 | teXt | 123, true or null |
| 10 | doctype | {"$doctype":"serialized-doctype"} |
| 14 | Function call | {"$name":"some-function","$args":[]} |
| 15 | Quotation (AKA lambda) | {"$args":[]}
____

L3N serialization rules for XML:

| Constant | VNode Type | Appearance |
| -------- | ------------------------- | ----------- |
| 1 | Element | |
| 3 | teXt | some-text |
| 4 | Reference | |
| 5 | List | |
| 6 | Map | |
| 7 | Processing instruction | |
| 8 | Comment | |
| 10 | doctype | |
| 12 | teXt | 123 |
| 14 | Function call | |
| 15 | Quotation |
____

L3N serialization rules for HTML:

| Constant | VNode Type | Appearance |
| -------- | ------------------------- | ----------- |
| 1 | Element | |
| 2 | Key-value pair | v
| 3 | teXt | some-text |
| 4 | Reference | |
| 5 | List | |
| 6 | Map | value |
| 7 | Processing instruction | N/A |
| 8 | Comment | |
| 10 | doctype | |
| 12 | teXt | 123 |
| 14 | Function call | |
| 15 | Quotation | `