A module for weaving form data with content data
npm install @thefarce/loomLoom is a tool for weaving form data with content data in Node.js. It does this by using elements of the Unified.js toolkit for parsing text into abstract syntax trees (AST).
The fundamental idea of Loom is that presentation and content are orthogonal dimensions of data. A communication has values in these two dimensions integrated into a coherent whole.
When you want to blend form (such as HTML) with content (such as JSON) into a single document. Unlike other systems, Loom does not require writing to or reading from files.
$ npm install @thefarce/loom
For more thorough usage examples, see the examples directory and refer to the transformations documentation and the interpolation documentation.
In this simple example, we will make two changes. First, we will replace the strong tag in our HTML fragment with an em tag. Second, we will replace the name variable in our template with the value Othello.
``js
import { interpolateTree, transform } from '@thefarce/loom'
import { astToHtml, htmlToAst } from '@thefarce/loom-html5'
// Get our HTML fragment.
const ast = htmlToAst('
Hello, ${name}!
', { fragment: true });// Now we have an abstract syntax tree (AST) representation of our HTML
// fragment. First, let's transform the tag to an tag.
// Note that transform() takes three parameters:
// 1) The AST to transform
// 2) The initial context (here, an empty object {} )
// 3) An array of transformer functions
let updated = await transform(
ast,
{},
[
(node, context, next) => {
if (node.type === 'element' && node.tagName === 'strong') {
node.tagName = 'em';
return { node, context };
}
return next();
},
]
);
// Now let's interpolate the value name.
// Note that interpolateTree() is async and requires await.
// There is another major mechanism for providing interpolation values;
// see the docs for more detailed information.
let intercepted = await interpolateTree(
updated,
{ name: 'Othello' }
);
console.log(astToHtml(interpolated));
`
Running this script produces the following output:
` Hello, Othello!html`
Interpolation is the process of executing code within the AST's values. This uses a syntax identical to JavaScript's backtick interpolation. For example, in the following script, JavaScript will replace ${name} with the value Othello:
See the interpolation documentation for more detailed information.
`jsHello, \${name}!
const name = 'Othello';
console.log();`
This interpolation uses variables in scope to expand values. Loom interpolation works the same way: any string[^1] in the AST will be replaced with the value in the data. All interpolation functions are asynchronous and return Promises.
[^1]: The type, data, and position values of a node will not be interpolated automatically. You may still update them manually if desired.
Transformation is the process of making systematic changes to an AST. This is accomplished by creating "transformer functions" (or "transformers") that apply changes to a node based on its content.
See the transformations documentation for more detailed information.
The AST to be transformed. This can be any AST that conforms to the Unified.js specification.
Contributions to Loom are welcome.
Contribute good code with full tests and docs, then submit a pull request. I don't care about any of your other behaviors.
This project contains a .vimrc` file to help with development and maintenance. See that file for more information and instructions for use.