Add IDL descriptions of abstract definitions · syntax-tree/unist@913b1bd (original) (raw)
1
1
`# ![Unist][logo]
`
2
2
``
3
``
`-
Unist (universal syntax tree) is the combination of three
`
4
``
`-
project, and more to come, which are the summation of at least
`
5
``
`-
[two][first-retext-commit] [years][first-remark-commit] of my work and the
`
6
``
`-
current epitome of that.
`
``
3
`+
Universal Syntax Tree.
`
``
4
+
``
5
`+
`
``
6
+
``
7
`+
Unist is the combination of three project, and more to come, which
`
``
8
`+
are the summation of at least [two][first-retext-commit]
`
``
9
`+
[years][first-remark-commit] of my work and the current epitome of that.
`
7
10
``
8
11
`It’s basically a system for processing input: parsing it into a syntax tree,
`
9
12
`transforming it by plug-ins, and compiling the tree to something else.
`
`@@ -13,32 +16,86 @@ This document explains some terminology relating to [retext][retext],
`
13
16
``
14
17
`## Unist nodes
`
15
18
``
16
``
`-
Unist nodes:
`
17
``
-
18
``
`` -
- must have a
typeproperty set to a to its namespace semantic
``
19
``
`` -
string;
``
20
``
-
21
``
`` -
- may have either a
valueproperty set to astringor achildren
``
22
``
`` -
property set to an array of zero or more Unist nodes;
``
23
``
-
24
``
`` -
- may have a
dataproperty set to aJSON.stringifyable object;
``
25
``
-
26
``
`` -
- may have a
positionproperty set to a an object containingstartand
``
27
``
`` -
end, both of which contain an object with line and column set
``
28
``
`-
to an integer referencing their respective (1-based) line and column
`
29
``
`` -
in the input file. Both may have an offset property set to its
``
30
``
`-
index from the beginning of the input.
`
31
``
`` -
The object at position may additionally have an indent property
``
32
``
`-
set to an array of integers higher than 0 (not including), in which
`
33
``
`-
case the node represents content which spans multiple lines prefixed
`
34
``
`-
with content which is not part of the node.
`
35
``
`-
If a node represents something not available in the original input, it
`
36
``
`` -
must not have a position.
``
37
``
-
38
19
`See [nlcst][nlcst] for more information on retext nodes,
`
39
20
`[mdast][mdast] for information on remark nodes, and
`
40
21
`` [hast#nodes][hast-nodes] for information on hast nodes.
``
41
22
``
``
23
`` +
Node
``
``
24
+
``
25
`+
Node represents any unit in the Unist hierarchy. It is an abstract
`
``
26
`` +
class. Interfaces inheriting from Node must have a type property,
``
``
27
`` +
and may have data or location properties. types are defined by
``
``
28
`+
their namespace.
`
``
29
+
``
30
```idl
``
31
`+
interface Node {
`
``
32
`+
type: string;
`
``
33
`+
data: Data?;
`
``
34
`+
position: Location?;
`
``
35
`+
}
`
``
36
```
``
37
+
``
38
`` +
Data
``
``
39
+
``
40
`+
Data represents data associated with any node. Data is a scope for plug-ins
`
``
41
`+
to store any information. Its only limitation being that each property should
`
``
42
`` +
by stringifyable: not throw when passed to JSON.stringify().
``
``
43
+
``
44
```idl
``
45
`+
interface Data { }
`
``
46
```
``
47
+
``
48
`` +
Location
``
``
49
+
``
50
`+
Location references a location of a node in a Unist file.
`
``
51
`+
If a location is not applicable, the location must be omitted.
`
``
52
`` +
Location consists of a start and end position. And, if
``
``
53
`` +
relevant, an indent property.
``
``
54
+
``
55
```idl
``
56
`+
interface Location {
`
``
57
`+
start: Position;
`
``
58
`+
end: Position;
`
``
59
`+
indent: [uint32 >= 1]?;
`
``
60
`+
}
`
``
61
```
``
62
+
``
63
`` +
Position
``
``
64
+
``
65
`` +
Position contains line and column set to a (1-based) integer
``
``
66
`` +
referencing a position in a Unist file. An offset (0-based)
``
``
67
`+
may be used.
`
``
68
+
``
69
```idl
``
70
`+
interface Position {
`
``
71
`+
line: uint32 >= 1;
`
``
72
`+
column: uint32 >= 1;
`
``
73
`+
offset: uint32 >= 0?;
`
``
74
`+
}
`
``
75
```
``
76
+
``
77
`` +
Parent
``
``
78
+
``
79
`+
Nodes containing child nodes inherit the Parent (Node)
`
``
80
`+
abstract interface.
`
``
81
+
``
82
```idl
``
83
`+
interface Parent <: Node {
`
``
84
`+
children: [Node];
`
``
85
`+
}
`
``
86
```
``
87
+
``
88
`` +
Text
``
``
89
+
``
90
`+
Nodes containing a value inherit the Text (Node)
`
``
91
`+
abstract interface.
`
``
92
+
``
93
```idl
``
94
`+
interface Text <: Node {
`
``
95
`+
value: string;
`
``
96
`+
}
`
``
97
```
``
98
+
42
99
`## Unist files
`
43
100
``
44
101
`Unist files are virtual files (such as [vfile][vfile])
`