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 [transformers documentation](./docs/usage.md) and the [interpolation
documentation](./docs/interpolation.md).

### Simple Example 

In this simple example, we will make two changes.  First, we will replace
the `div` tag in our html fragment with a `span` 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('<p>Hello, <div>{name}</div>!</p>', { fragment: true });

// Now we have an abstract syntax tree (AST) representation of our HTML
// fragment.  First, let's transform the div to a span.

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

// 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:

```html
<p>Hello, Othello!</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](./docs/interpolation.md) for more
detailed information.

```js
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](./docs/transformations.md) 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.