loom/README.md

# @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 [documentation](./docs/usage.md).

```js
import {
	interpolateTree,
	transform,
} from '@thefarce/loom'

const initial = htmlToAst('<p>Hello, {name}!</p>'),

const transformed = interpolateTree(
	transform(initial, ...transformers),
	{ name: 'Othello' },
);

console.log(astToHtml(transformed));
```

Running this script produces the following output:

```html
<p>Hello, Othello!</p>
```

## API

### interpolate(ast, data)

### transform(ast, plugins)

			See the [transformations documentation](./docs/transformations.md) for more
			information.

			Transform the AST according to plugins.

## 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.

### VIM

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