@thefarce/loom

What is this?

Loom is a tool for weaving form data with content data in nodejs. 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 should I use this?

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.

Installation

$ npm install @thefarce/loom

Usage Example

For more thorough usage examples, see the examples directory and refer to the transformers documentation and the interpolation documentation.

Simple Example

In this simple example, we will make two changes. First, we will replace the strong tag in our html fragment with a em tag. Second, we will replace the name variable in our template with the value Othello.

import { interpolateNode, transform } from '@thefarce/loom'
import { astToHtml, htmlToAst } from '@thefarce/loom-html5'

// Get our HTML fragment.
const ast = htmlToAst('<p>Hello, <strong>${name}</strong>!</p>', { fragment: true });

// Now we have an abstract syntax tree (AST) representation of our HTML
// fragment.  First, let's transform the <strong> tag to an <em> tag.

let updated = transform(
	// our initial syntax tree
  ast,
	// A transformer that checks if the node is an element and has a tag name
	// of "strong".  If so, we just change the tag name to "em".  It is
	// important that we return the updated node (or a new one).
	(node, context, next) => {
        if (node.type === 'element' && node.tagName === 'strong') {
          node.tagName = 'em';
          return { node, context };
		}
        next();
	},
);

// Now let's interpolate the value `name`.  There is another major mechanism
// for providing interpolation values; see the for more detailed information.
let interpolated = interpolateTree(
	updated, 
	{ name: 'Othello' }
);

console.log(astToHtml(interpolated));

Running this script produces the following output:

<p>Hello, <em>Othello</em>!</p>

API

Value Interpolation

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.

const name = 'Othello';
console.log(`Hello, ${name}!`);

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.

[^1]: There are a few exceptions. The type, data, and position values of a node will not be interpolated. You may interpolate them manually, of course.

AST Transformation

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.

Glossary

ast

The AST to be transformed. This can be any AST that conforms to the Unified.js specification.

Contributing to Loom

Contributions to Loom are welcome.

Community Guidelines

Contribute good code with full tests and docs, then submit a pull request. I don't care about any of your other behaviors.

VIM

This project contains a .vimrc file to help with development and maintainance. See that file for more information and instructions for use.