Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
code-of-conduct.md Add `code-of-conduct.md` Nov 17, 2017
contributing.md Update links Dec 8, 2017
logo.svg Update logo Aug 31, 2017
readme.md Add `unist-util-flatmap` to list of plugins Jul 22, 2018

readme.md

Unist

Universal Syntax Tree.


Unist is the combination of three syntax trees, and more to come: mdast with remark for markdown, nlcst with retext for prose, and hast with rehype for HTML.

This document explains some terminology relating to unified and vfile as well.

This document may not be released. See releases for released documents. The latest released version is 1.1.0.

Table of Contents

Unist nodes

Subsets of Unist can define new properties on new nodes, and plug-ins and utilities can define new data properties on nodes. But, the values on those properties must be JSON values: string, number, object, array, true, false, or null. This means that the syntax tree should be able to be converted to and from JSON and produce the same tree. For example, in JavaScript, a tree should be able to be passed through JSON.parse(JSON.stringify(tree)) and result in the same values.

See nlcst for more information on retext nodes, mdast for information on remark nodes, and hast for information on rehype nodes.

Node

A Node represents any unit in the Unist hierarchy. It is an abstract interface. Interfaces extending Node must have a type property, and may have data or position properties. types are defined by their namespace.

Subsets of Unist are allowed to define properties on interfaces which extend Unist’s abstract interfaces. For example, mdast defines Link (Parent) with a url property.

interface Node {
  type: string;
  data: Data?;
  position: Position?;
}

Data

Data represents data associated with any node. Data is a scope for plug-ins to store any information. For example, remark-html uses hProperties to let other plug-ins specify properties added to the compiled HTML element.

interface Data { }

Position

Position references a range consisting of two points in a Unist file. Position consists of a start and end point. And, if relevant, an indent property.

When the value represented by a node is not present in the document corresponding to the syntax tree at the time of reading, it must not have positional information. These nodes are said to be generated.

interface Position {
  start: Point;
  end: Point;
  indent: [uint32 >= 1]?;
}

Point

Point references a point consisting of two indices in a Unist file: line and column, set to 1-based integers. An offset (0-based) may be used.

interface Point {
  line: uint32 >= 1;
  column: uint32 >= 1;
  offset: uint32 >= 0?;
}

Parent

Nodes containing other nodes (said to be children) extend the abstract interface Parent (Node).

interface Parent <: Node {
  children: [Node];
}

Text

Nodes containing a value extend the abstract interface Text (Node).

interface Text <: Node {
  value: string;
}

Glossary

Tree

A tree is a node and all of its descendants (if any).

Child

Node X is child of node Y, if Y’s children include X.

Parent

Node X is parent of node Y, if Y is a child of X.

Index

The index of a child is its number of preceding siblings, or 0 if it has none.

Sibling

Node X is a sibling of node Y, if X and Y have the same parent (if any).

The previous sibling of a child is its sibling at its index minus 1.

The next sibling of a child is its sibling at its index plus 1.

Root

The root of an object is itself, if without parent or the root of its parent.

The root of a tree is any node in that tree without parent.

Descendant

Node X is descendant of node Y, if X is a child of Y, or if X is a child of node Z that is a descendant of Y.

An inclusive descendant is a node or one of its descendants.

Ancestor

Node X is an ancestor of node Y, if Y is a descendant of X.

An inclusive ancestor is a node or one of its ancestors.

Head

The head of a node is its first child (if any).

Tail

The tail of a node is its last child (if any).

Unist files

Unist files are virtual files (such as vfile) representing documents at a certain location. They are not limited to existing files, nor to the file-system.

Unist utilities

Unist utilities are functions which work with unist nodes, agnostic of remark, retext, or rehype.

A list of vfile-related utilities can be found at vfile.

List of Utilities

Contribute

unist is built by people just like you! Check out contributing.md for ways to get started.

This project has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.

Want to chat with the community and contributors? Join us in Gitter!

Have an idea for a cool new utility or tool? That’s great! If you want feedback, help, or just to share it with the world you can do so by creating an issue in the syntax-tree/ideas repository!

Acknowledgments

The initial release of this project was authored by @wooorm.

Special thanks to @eush77 for their work, ideas, and incredibly valuable feedback!

Thanks to @azu, @blahah, @gibson042, @jlevy, and @mrzmmr for contributing commits since!

License

CC-BY-4.0 © Titus Wormer