Skip to content

Commit f2b8587

Browse files
committed
Refactor to clarify wording around positional info
Previously, position and location were used interchangably, and confusingly. This commit drops the “location” term, uses “position” and “positional info” for the thing at `node.position`, and uses “point” for the thing at `position.start` and `position.end`. Closes GH-13.
1 parent 2557136 commit f2b8587

File tree

1 file changed

+18
-18
lines changed

1 file changed

+18
-18
lines changed

Diff for: readme.md

+18-18
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ See [**nlcst**][nlcst] for more information on **retext** nodes,
4444

4545
A Node represents any unit in the Unist hierarchy. It is an abstract
4646
interface. Interfaces extending **Node** must have a `type` property,
47-
and may have `data` or `location` properties. `type`s are defined by
47+
and may have `data` or `position` properties. `type`s are defined by
4848
their namespace.
4949

5050
Subsets of Unist are allowed to define properties on interfaces which
@@ -55,7 +55,7 @@ extend Unist’s abstract interfaces. For example, [mdast][] defines
5555
interface Node {
5656
type: string;
5757
data: Data?;
58-
position: Location?;
58+
position: Position?;
5959
}
6060
```
6161

@@ -70,32 +70,32 @@ compiled HTML element.
7070
interface Data { }
7171
```
7272

73-
#### `Location`
73+
#### `Position`
7474

75-
**Location** references a range consisting of two points in a [Unist
76-
file][file]. **Location** consists of a `start` and `end` position.
75+
**Position** references a range consisting of two points in a [Unist
76+
file][file]. **Position** consists of a `start` and `end` point.
7777
And, if relevant, an `indent` property.
7878

7979
When the value represented by a node is not present in the document
8080
corresponding to the syntax tree at the time of reading, it must not
81-
have a location. These nodes are said to be _generated_.
81+
have positional information. These nodes are said to be _generated_.
8282

8383
```idl
84-
interface Location {
85-
start: Position;
86-
end: Position;
84+
interface Position {
85+
start: Point;
86+
end: Point;
8787
indent: [uint32 >= 1]?;
8888
}
8989
```
9090

91-
#### `Position`
91+
#### `Point`
9292

93-
**Position** references a point consisting of two indices in a
93+
**Point** references a point consisting of two indices in a
9494
[Unist file][file]: `line` and `column`, set to 1-based integers. An
9595
`offset` (0-based) may be used.
9696

9797
```idl
98-
interface Position {
98+
interface Point {
9999
line: uint32 >= 1;
100100
column: uint32 >= 1;
101101
offset: uint32 >= 0?;
@@ -148,9 +148,9 @@ A list of **vfile**-related utilities can be found at [**vfile**][vfile].
148148
* [`unist-util-find-after`](https://github.com/syntax-tree/unist-util-find-after)
149149
— Find a node after another node
150150
* [`unist-util-find-all-after`](https://github.com/syntax-tree/unist-util-find-all-after)
151-
— Find nodes after another node or position
151+
— Find nodes after another node or index
152152
* [`unist-util-find-all-before`](https://github.com/syntax-tree/unist-util-find-all-before)
153-
— Find nodes before another node or position
153+
— Find nodes before another node or index
154154
* [`unist-util-find-all-between`](https://github.com/mrzmmr/unist-util-find-all-between)
155155
— Find nodes between two nodes or positions
156156
* [`unist-util-find-before`](https://github.com/syntax-tree/unist-util-find-before)
@@ -170,17 +170,17 @@ A list of **vfile**-related utilities can be found at [**vfile**][vfile].
170170
* [`unist-util-parents`](https://github.com/eush77/unist-util-parents)
171171
`parent` references on nodes
172172
* [`unist-util-position`](https://github.com/syntax-tree/unist-util-position)
173-
— Get the position of nodes
173+
— Get positional info of nodes
174174
* [`unist-util-remove`](https://github.com/eush77/unist-util-remove)
175175
— Remove nodes from Unist trees
176176
* [`unist-util-remove-position`](https://github.com/syntax-tree/unist-util-remove-position)
177-
— Remove `position`s from a unist tree
177+
— Remove positional info from a unist tree
178178
* [`unist-util-select`](https://github.com/eush77/unist-util-select)
179179
— Select nodes with CSS-like selectors
180180
* [`unist-util-source`](https://github.com/syntax-tree/unist-util-source)
181-
— Get the source of a value (node, location)
181+
— Get the source of a value (node or position) in a file
182182
* [`unist-util-stringify-position`](https://github.com/syntax-tree/unist-util-stringify-position)
183-
— Stringify a node, location, or position
183+
— Stringify a node, position, or point
184184
* [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)
185185
— Recursively walk over nodes
186186
* [`unist-util-visit-parents`](https://github.com/syntax-tree/unist-util-visit-parents)

0 commit comments

Comments
 (0)