From f4ae9b862e60f49111a42974c69b6612b0c033ca Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sat, 3 Nov 2018 18:17:38 +0100 Subject: [PATCH 01/40] Remove semicolons --- readme.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/readme.md b/readme.md index 82f3bdf..ff09160 100644 --- a/readme.md +++ b/readme.md @@ -89,9 +89,9 @@ Syntactic units in unist syntax trees are called nodes, and implement the ```idl interface Node { - type: string; - data: Data?; - position: Position?; + type: string + data: Data? + position: Position? } ``` @@ -121,9 +121,9 @@ For example, in JavaScript, a tree can be passed through ```idl interface Position { - start: Point; - end: Point; - indent: [number >= 1]?; + start: Point + end: Point + indent: [number >= 1]? } ``` @@ -161,9 +161,9 @@ end at line `2`, column `6`, offset `11`. ```idl interface Point { - line: number >= 1; - column: number >= 1; - offset: number >= 0?; + line: number >= 1 + column: number >= 1 + offset: number >= 0? } ``` @@ -188,7 +188,7 @@ implementing unist. ```idl interface Parent <: Node { - children: [Node]; + children: [Node] } ``` @@ -201,7 +201,7 @@ The `children` field is a list representing the children of a node. ```idl interface Literal <: Node { - value: any; + value: any } ``` From 7c0bda0a592f859d8a6008f8f780de4d9a9367e6 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sat, 3 Nov 2018 18:18:52 +0100 Subject: [PATCH 02/40] Move chat to spectrum --- contributing.md | 14 +++++++------- readme.md | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/contributing.md b/contributing.md index 3fdf373..d1b36dc 100644 --- a/contributing.md +++ b/contributing.md @@ -34,22 +34,22 @@ help you faster. ## Questions -Please chat and ask questions on Gitter! Jump in there and lurk, talk to us, +Please chat and ask questions on spectrum! Jump in there and lurk, talk to us, and help others. -* [**unified**](https://gitter.im/unifiedjs/Lobby) +* [**unified**](https://spectrum.chat/unified/unified) — Topics relating to [**unified**][unified] in general -* [**vfile**](https://gitter.im/vfile/Lobby) +* [**vfile**](https://spectrum.chat/unified/vfile) — Topics relating to [**vfile**][vfile]: virtual files -* [**syntax-tree**](https://gitter.im/syntax-tree/Lobby) +* [**syntax-tree**](https://spectrum.chat/unified/syntax-tree) — Topics relating to [**syntax-tree**][syntax-tree] and [**unist**][unist] -* [**remark**](https://gitter.im/remarkjs/Lobby) +* [**remark**](https://spectrum.chat/unified/remark) — Topics relating to the [**remark**][remark] ecosystem, markdown, and [**mdast**][mdast] -* [**rehype**](https://gitter.im/rehypejs/Lobby) +* [**rehype**](https://spectrum.chat/unified/rehype) — Topics relating to the [**rehype**][rehype] ecosystem, HTML, and [**hast**][hast] -* [**retext**](https://gitter.im/retextjs/Lobby) +* [**retext**](https://spectrum.chat/unified/retext) — Topics relating to the [**retext**][retext] ecosystem, natural language, and [**nlcst**][nlcst] diff --git a/readme.md b/readme.md index ff09160..4fef40d 100644 --- a/readme.md +++ b/readme.md @@ -399,7 +399,7 @@ 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][chat]! +Join us in [spectrum][chat]! Have an idea for a cool new utility or tool? That’s great! @@ -468,7 +468,7 @@ This work is licensed under a [ideas]: https://github.com/syntax-tree/ideas -[chat]: https://gitter.im/syntax-tree/Lobby +[chat]: https://spectrum.chat/unified/syntax-tree [license]: https://creativecommons.org/licenses/by/4.0/ From b187eb7846f7a4a8a1c1de8ef4f201464fb3bde9 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sat, 3 Nov 2018 18:19:43 +0100 Subject: [PATCH 03/40] Update logo --- logo.svg | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/logo.svg b/logo.svg index 06a6777..70ff38a 100644 --- a/logo.svg +++ b/logo.svg @@ -1,4 +1,4 @@ - - - + + + From 59b8f731519e259640ec53cf1195cfaf486aa2c2 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sat, 3 Nov 2018 18:20:20 +0100 Subject: [PATCH 04/40] Update references to logo --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 4fef40d..e3c93e4 100644 --- a/readme.md +++ b/readme.md @@ -458,7 +458,7 @@ This work is licensed under a -[logo]: https://cdn.rawgit.com/syntax-tree/unist/b2943b1/logo.svg +[logo]: https://raw.githubusercontent.com/syntax-tree/unist/b187eb7/logo.svg?sanitize=true [releases]: https://github.com/syntax-tree/unist/releases From 49032b9a775398fb61962d142a9f94313f4fad7a Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sun, 18 Nov 2018 20:30:30 +0100 Subject: [PATCH 05/40] Add definition of character Closes GH-21. --- readme.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/readme.md b/readme.md index e3c93e4..227d94b 100644 --- a/readme.md +++ b/readme.md @@ -173,6 +173,9 @@ The `line` field (1-indexed integer) represents a line in a source file. The `column` field (1-indexed integer) represents a column in a source file. The `offset` field (0-indexed integer) represents a character in a source file. +The term character means a (UTF-16) code unit which is defined in the +[Web IDL][webidl] specification. + #### `Data` ```idl From 4b3889b87c70875beaaad5cfebb8ea2dd7d1d9c4 Mon Sep 17 00:00:00 2001 From: Titus Date: Sat, 25 May 2019 11:49:25 +0200 Subject: [PATCH 06/40] Add terms for tree traversal, preorder, postorder Closes GH-22. Closes GH-23. Reviewed-by: Christian Murphy --- readme.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/readme.md b/readme.md index 227d94b..80936c9 100644 --- a/readme.md +++ b/readme.md @@ -23,6 +23,7 @@ The latest released version is [`2.0.0`][release]. * [Parent](#parent) * [Literal](#literal) * [Glossary](#glossary) +* [Tree traversal](#tree-traversal) * [Utilities](#utilities) * [List of Utilities](#list-of-utilities) * [References](#references) @@ -304,6 +305,102 @@ Files are provided by the host environment and not defined by unist. For example, see projects such as [**vfile**][vfile]. +###### Preorder + +In **preorder** (**NLR**) is [depth-first][traversal-depth] [tree +traversal][traversal] that performs the following steps for each node _N_: + +1. **N**: visit _N_ itself +2. **L**: traverse [_head_][term-head] (then its _next sibling_, recursively + moving forward until reaching _tail_) +3. **R**: traverse [_tail_][term-tail] + +###### Postorder + +In **postorder** (**LRN**) is [depth-first][traversal-depth] [tree +traversal][traversal] that performs the following steps for each node _N_: + +1. **L**: traverse [_head_][term-head] (then its _next sibling_, recursively + moving forward until reaching _tail_) +2. **R**: traverse [_tail_][term-tail] +3. **N**: visit _N_ itself + +## Tree traversal + +**Tree traversal** is a common task when working with a [_tree_][term-tree] to +search it. +Tree traversal is typically either _breadth-first_ or _depth-first_. + +In the following examples, we’ll work with this tree: + +```ascii + +---+ + | A | + +-+-+ + | + +-----+-----+ + | | + +-+-+ +-+-+ + | B | | F | + +-+-+ +-+-+ + | | + +-----+--+--+ | + | | | | + +-+-+ +-+-+ +-+-+ +-+-+ + | C | | D | | E | | G | + +---+ +---+ +---+ +---+ +``` + +###### Breadth-first traversal + +**Breadth-first traversal** is visiting a node and all its +[_siblings_][term-sibling] to broaden the search at that level, before +traversing [_children_][term-child]. + +For the syntax tree defined in the diagram, a breadth-first traversal first +searches the root of the tree (**A**), then its children (**B** and **F**), then +their children (**C**, **D**, **E**, and **G**). + +###### Depth-first traversal + +Alternatively, and more commonly, **depth-first traversal** is used. +The search is first deepened, by traversing [_children_][term-child], before +traversing [_siblings_][term-sibling]. + +For the syntax tree defined in the diagram, a depth-first traversal first +searches the root of the tree (**A**), then one of its children (**B** or +**F**), then their children (**C**, **D**, and **E**, or **G**). + +For a given node _N_ with [_children_][term-child], a **depth-first traversal** +performs three steps, simplified to only binary trees (every node has +[_head_][term-head] and [_tail_][term-tail], but no other children): + +* **N**: visit _N_ itself +* **L**: traverse [_head_][term-head] +* **R**: traverse [_tail_][term-tail] + +These steps can be done in any order, but for non-binary trees, **L** and **R** +occur together. +If **L** is done before **R**, the traversal is called _left-to-right_ +traversal, otherwise it is called _right-to-left_ traversal. +In the case of non-binary trees, the other children between _head_ and _tail_ +are processed in that order as well, so for _left-to-right_ traversal, first +_head_ is traversed (**L**), then its _next sibling_ is traversed, etcetera, +until finally _tail_ (**R**) is traversed. + +Because **L** and **R** occur together for non-binary trees, we can produce four +types of orders: NLR, NRL, LRN, RLN. + +NLR and LRN (the two _left-to-right_ traversal options) are most commonly used +and respectively named [_preorder_][term-preorder] and +[_postorder_][term-postorder]. + +For the syntax tree defined in the diagram, _preorder_ and _postorder_ traversal +thus first search the root of the tree (**A**), then its head (**B**), then its +children from left-to-right (**C**, **D**, and then **E**). +After all [_descendants_][term-descendant] of **B** are traversed, its next +sibling (**F**) is traversed and then finally its only child (**G**). + ## Utilities **Utilities** are functions that work with nodes. @@ -491,6 +588,10 @@ This work is licensed under a [term-tree]: #tree +[term-preorder]: #preorder + +[term-postorder]: #postorder + [term-child]: #child [term-parent]: #parent-1 @@ -501,6 +602,10 @@ This work is licensed under a [term-descendant]: #descendant +[term-head]: #head + +[term-tail]: #tail + [term-generated]: #generated [term-type]: #type @@ -509,6 +614,10 @@ This work is licensed under a [term-file]: #file +[traversal]: #tree-traversal + +[traversal-depth]: #depth-first-traversal + [list-of-utilities]: #list-of-utilities [webidl]: https://heycam.github.io/webidl/ From 1fc013b95e6d843fec72a0e3f8e013350642fc21 Mon Sep 17 00:00:00 2001 From: Titus Date: Mon, 27 May 2019 22:11:44 +0200 Subject: [PATCH 07/40] Add enter, exit terms Closes GH-24. Closes GH-25. --- readme.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/readme.md b/readme.md index 80936c9..5c6b482 100644 --- a/readme.md +++ b/readme.md @@ -325,6 +325,22 @@ traversal][traversal] that performs the following steps for each node _N_: 2. **R**: traverse [_tail_][term-tail] 3. **N**: visit _N_ itself +###### Enter + +**Enter** is a step right before other steps performed on a given node _N_ when +[**traversing**][traversal] a tree. + +For example, when performing _preorder_ traversal, **enter** is the first step +taken, right before visiting _N_ itself. + +###### Exit + +**Exit** is a step right after other steps performed on a given node _N_ when +[**traversing**][traversal] a tree. + +For example, when performing _preorder_ traversal, **exit** is the last step +taken, right after traversing the [_tail_][term-tail] of _N_. + ## Tree traversal **Tree traversal** is a common task when working with a [_tree_][term-tree] to From b36721e4a1ace4e6da39b8ba54e9914bc294c21e Mon Sep 17 00:00:00 2001 From: Titus Date: Mon, 27 May 2019 23:06:37 +0200 Subject: [PATCH 08/40] Add `unist-builder-blueprint-cli` to list of utilities --- readme.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/readme.md b/readme.md index 5c6b482..0e7db68 100644 --- a/readme.md +++ b/readme.md @@ -486,6 +486,8 @@ implementing unist: — Helper for creating trees * [`unist-builder-blueprint`](https://github.com/eush77/unist-builder-blueprint) — Convert trees to `unist-builder` notation +* [`unist-builder-blueprint-cli`](https://github.com/eush77/unist-builder-blueprint-cli) + — CLI to Convert trees to `unist-builder` notation ## References From e7ec8df6ec62cf87d007d1d13fb497a41c47b634 Mon Sep 17 00:00:00 2001 From: Titus Date: Mon, 27 May 2019 23:07:29 +0200 Subject: [PATCH 09/40] Add `unist-util-size` to list of utilities --- readme.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/readme.md b/readme.md index 0e7db68..fcc00b9 100644 --- a/readme.md +++ b/readme.md @@ -470,6 +470,8 @@ implementing unist: — Remove positional info from trees * [`unist-util-select`](https://github.com/eush77/unist-util-select) — Select nodes with CSS-like selectors +* [`unist-util-size`](https://github.com/syntax-tree/unist-util-size) + — Calculate the number of nodes in a tree * [`unist-util-source`](https://github.com/syntax-tree/unist-util-source) — Get the source of a value (node or position) in a file * [`unist-util-stringify-position`](https://github.com/syntax-tree/unist-util-stringify-position) From c1dfd06e0da2b8d52baf563e2119eb6182324108 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 29 May 2019 14:00:21 +0200 Subject: [PATCH 10/40] Update dev-dependencies --- package.json | 4 +- readme.md | 138 +++++++++++++++++++++++++-------------------------- 2 files changed, 71 insertions(+), 71 deletions(-) diff --git a/package.json b/package.json index e3e1826..86b5884 100644 --- a/package.json +++ b/package.json @@ -14,8 +14,8 @@ "Christian Murphy " ], "devDependencies": { - "remark-cli": "^5.0.0", - "remark-preset-wooorm": "^4.0.0" + "remark-cli": "^6.0.0", + "remark-preset-wooorm": "^5.0.0" }, "scripts": { "format": "remark . -qfo", diff --git a/readme.md b/readme.md index fcc00b9..18c90a4 100644 --- a/readme.md +++ b/readme.md @@ -78,7 +78,7 @@ unist relates to the [unified][], [remark][], [rehype][], and [retext][] projects in that unist syntax trees are used throughout their ecosystems. unist relates to the [vfile][] project in that it accepts unist nodes for -its message store, and that vfile can be a source [_file_][term-file] of a +its message store, and that vfile can be a source [*file*][term-file] of a syntax tree. ## Nodes @@ -97,7 +97,7 @@ interface Node { ``` The `type` field is a non-empty string representing the variant of a node. -This field can be used to determine the [_type_][term-type] a node implements. +This field can be used to determine the [*type*][term-type] a node implements. The `data` field represents information from the ecosystem. The value of the `data` field implements the [**Data**][dfn-data] interface. @@ -106,7 +106,7 @@ The `position` field represents the location of a node in a source document. The value of the `position` field implements the [**Position**][dfn-position] interface. The `position` field must not be present if a node is -[_generated_][term-generated]. +[*generated*][term-generated]. Specifications implementing unist are encouraged to define more fields. Ecosystems can define fields on [**Data**][dfn-data]. @@ -128,7 +128,7 @@ interface Position { } ``` -**Position** represents the location of a node in a source [_file_][term-file]. +**Position** represents the location of a node in a source [*file*][term-file]. The `start` field of **Position** represents the place of the first character of the parsed source region. @@ -141,8 +141,8 @@ The `indent` field of **Position** represents the start column at each index (plus start line) in the source region, for elements that span multiple lines. If the syntactic unit represented by a node is not present in the source -[_file_][term-file] at the time of parsing, the node is said to be -[_generated_][term-generated] and it must not have positional information. +[*file*][term-file] at the time of parsing, the node is said to be +[*generated*][term-generated] and it must not have positional information. For example, if the following value was represented as unist: @@ -168,7 +168,7 @@ interface Point { } ``` -**Point** represents one place in a source [_file_][term-file]. +**Point** represents one place in a source [*file*][term-file]. The `line` field (1-indexed integer) represents a line in a source file. The `column` field (1-indexed integer) represents a column in a source file. @@ -196,7 +196,7 @@ interface Parent <: Node { } ``` -Nodes containing other nodes (said to be [_children_][term-child]) extend the +Nodes containing other nodes (said to be [*children*][term-child]) extend the abstract interface **Parent** ([**Node**][dfn-node]). The `children` field is a list representing the children of a node. @@ -218,7 +218,7 @@ The `value` field can contain any value. ###### Tree -A **tree** is a node and all of its [_descendants_][term-descendant] (if any). +A **tree** is a node and all of its [*descendants*][term-descendant] (if any). ###### Child @@ -226,66 +226,66 @@ 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_][term-child] of X. +Node X is **parent** of node Y, if Y is a [*child*][term-child] of X. ###### Index -The **index** of a [_child_][term-child] is its number of preceding -[_siblings_][term-sibling], or `0` if it has none. +The **index** of a [*child*][term-child] is its number of preceding +[*siblings*][term-sibling], or `0` if it has none. ###### Sibling Node X is a **sibling** of node Y, if X and Y have the same -[_parent_][term-parent] (if any). +[*parent*][term-parent] (if any). -The **previous sibling** of a [_child_][term-child] is its **sibling** at its -[_index_][term-index] minus 1. +The **previous sibling** of a [*child*][term-child] is its **sibling** at its +[*index*][term-index] minus 1. -The **next sibling** of a [_child_][term-child] is its **sibling** at its -[_index_][term-index] plus 1. +The **next sibling** of a [*child*][term-child] is its **sibling** at its +[*index*][term-index] plus 1. ###### Root -The **root** of a node is itself, if without [_parent_][term-parent], or the -**root** of its [_parent_][term-parent]. +The **root** of a node is itself, if without [*parent*][term-parent], or the +**root** of its [*parent*][term-parent]. -The **root** of a [_tree_][term-tree] is any node in that [_tree_][term-tree] -without [_parent_][term-parent]. +The **root** of a [*tree*][term-tree] is any node in that [*tree*][term-tree] +without [*parent*][term-parent]. ###### Descendant -Node X is **descendant** of node Y, if X is a [_child_][term-child] of Y, or if -X is a [_child_][term-child] of node Z that is a **descendant** of Y. +Node X is **descendant** of node Y, if X is a [*child*][term-child] of Y, or if +X is a [*child*][term-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_][term-descendant] +Node X is an **ancestor** of node Y, if Y is a [*descendant*][term-descendant] of X. An **inclusive ancestor** is a node or one of its **ancestors**. ###### Head -The **head** of a node is its first [_child_][term-child] (if any). +The **head** of a node is its first [*child*][term-child] (if any). ###### Tail -The **tail** of a node is its last [_child_][term-child] (if any). +The **tail** of a node is its last [*child*][term-child] (if any). ###### Leaf -A **leaf** is a node with no [_children_][term-child]. +A **leaf** is a node with no [*children*][term-child]. ###### Branch -A **branch** is a node with one or more [_children_][term-child]. +A **branch** is a node with one or more [*children*][term-child]. ###### Generated -A node is **generated** if it does not have [_positional -information_][term-positional-info]. +A node is **generated** if it does not have [*positional +information*][term-positional-info]. ###### Type @@ -299,7 +299,7 @@ The **positional information** of a node is the value of its `position` field. A **file** is a source document that represents the original file that was parsed to produce the syntax tree. -[_Positional information_][term-positional-info] represents the place of a node +[*Positional information*][term-positional-info] represents the place of a node in this file. Files are provided by the host environment and not defined by unist. @@ -308,44 +308,44 @@ For example, see projects such as [**vfile**][vfile]. ###### Preorder In **preorder** (**NLR**) is [depth-first][traversal-depth] [tree -traversal][traversal] that performs the following steps for each node _N_: +traversal][traversal] that performs the following steps for each node *N*: -1. **N**: visit _N_ itself -2. **L**: traverse [_head_][term-head] (then its _next sibling_, recursively - moving forward until reaching _tail_) -3. **R**: traverse [_tail_][term-tail] +1. **N**: visit *N* itself +2. **L**: traverse [*head*][term-head] (then its *next sibling*, recursively + moving forward until reaching *tail*) +3. **R**: traverse [*tail*][term-tail] ###### Postorder In **postorder** (**LRN**) is [depth-first][traversal-depth] [tree -traversal][traversal] that performs the following steps for each node _N_: +traversal][traversal] that performs the following steps for each node *N*: -1. **L**: traverse [_head_][term-head] (then its _next sibling_, recursively - moving forward until reaching _tail_) -2. **R**: traverse [_tail_][term-tail] -3. **N**: visit _N_ itself +1. **L**: traverse [*head*][term-head] (then its *next sibling*, recursively + moving forward until reaching *tail*) +2. **R**: traverse [*tail*][term-tail] +3. **N**: visit *N* itself ###### Enter -**Enter** is a step right before other steps performed on a given node _N_ when +**Enter** is a step right before other steps performed on a given node *N* when [**traversing**][traversal] a tree. -For example, when performing _preorder_ traversal, **enter** is the first step -taken, right before visiting _N_ itself. +For example, when performing *preorder* traversal, **enter** is the first step +taken, right before visiting *N* itself. ###### Exit -**Exit** is a step right after other steps performed on a given node _N_ when +**Exit** is a step right after other steps performed on a given node *N* when [**traversing**][traversal] a tree. -For example, when performing _preorder_ traversal, **exit** is the last step -taken, right after traversing the [_tail_][term-tail] of _N_. +For example, when performing *preorder* traversal, **exit** is the last step +taken, right after traversing the [*tail*][term-tail] of *N*. ## Tree traversal -**Tree traversal** is a common task when working with a [_tree_][term-tree] to +**Tree traversal** is a common task when working with a [*tree*][term-tree] to search it. -Tree traversal is typically either _breadth-first_ or _depth-first_. +Tree traversal is typically either *breadth-first* or *depth-first*. In the following examples, we’ll work with this tree: @@ -370,8 +370,8 @@ In the following examples, we’ll work with this tree: ###### Breadth-first traversal **Breadth-first traversal** is visiting a node and all its -[_siblings_][term-sibling] to broaden the search at that level, before -traversing [_children_][term-child]. +[*siblings*][term-sibling] to broaden the search at that level, before +traversing [*children*][term-child]. For the syntax tree defined in the diagram, a breadth-first traversal first searches the root of the tree (**A**), then its children (**B** and **F**), then @@ -380,41 +380,41 @@ their children (**C**, **D**, **E**, and **G**). ###### Depth-first traversal Alternatively, and more commonly, **depth-first traversal** is used. -The search is first deepened, by traversing [_children_][term-child], before -traversing [_siblings_][term-sibling]. +The search is first deepened, by traversing [*children*][term-child], before +traversing [*siblings*][term-sibling]. For the syntax tree defined in the diagram, a depth-first traversal first searches the root of the tree (**A**), then one of its children (**B** or **F**), then their children (**C**, **D**, and **E**, or **G**). -For a given node _N_ with [_children_][term-child], a **depth-first traversal** +For a given node *N* with [*children*][term-child], a **depth-first traversal** performs three steps, simplified to only binary trees (every node has -[_head_][term-head] and [_tail_][term-tail], but no other children): +[*head*][term-head] and [*tail*][term-tail], but no other children): -* **N**: visit _N_ itself -* **L**: traverse [_head_][term-head] -* **R**: traverse [_tail_][term-tail] +* **N**: visit *N* itself +* **L**: traverse [*head*][term-head] +* **R**: traverse [*tail*][term-tail] These steps can be done in any order, but for non-binary trees, **L** and **R** occur together. -If **L** is done before **R**, the traversal is called _left-to-right_ -traversal, otherwise it is called _right-to-left_ traversal. -In the case of non-binary trees, the other children between _head_ and _tail_ -are processed in that order as well, so for _left-to-right_ traversal, first -_head_ is traversed (**L**), then its _next sibling_ is traversed, etcetera, -until finally _tail_ (**R**) is traversed. +If **L** is done before **R**, the traversal is called *left-to-right* +traversal, otherwise it is called *right-to-left* traversal. +In the case of non-binary trees, the other children between *head* and *tail* +are processed in that order as well, so for *left-to-right* traversal, first +*head* is traversed (**L**), then its *next sibling* is traversed, etcetera, +until finally *tail* (**R**) is traversed. Because **L** and **R** occur together for non-binary trees, we can produce four types of orders: NLR, NRL, LRN, RLN. -NLR and LRN (the two _left-to-right_ traversal options) are most commonly used -and respectively named [_preorder_][term-preorder] and -[_postorder_][term-postorder]. +NLR and LRN (the two *left-to-right* traversal options) are most commonly used +and respectively named [*preorder*][term-preorder] and +[*postorder*][term-postorder]. -For the syntax tree defined in the diagram, _preorder_ and _postorder_ traversal +For the syntax tree defined in the diagram, *preorder* and *postorder* traversal thus first search the root of the tree (**A**), then its head (**B**), then its children from left-to-right (**C**, **D**, and then **E**). -After all [_descendants_][term-descendant] of **B** are traversed, its next +After all [*descendants*][term-descendant] of **B** are traversed, its next sibling (**F**) is traversed and then finally its only child (**G**). ## Utilities From 7da0a2bd3558d31572725709e28713574c7f86a1 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 29 May 2019 14:00:35 +0200 Subject: [PATCH 11/40] Remove `name` from `package.json` --- package.json | 1 - 1 file changed, 1 deletion(-) diff --git a/package.json b/package.json index 86b5884..24045cb 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,4 @@ { - "name": "unist", "private": true, "version": "0.0.0", "description": "universal syntax tree", From df696b18d8d9089cab7d8e56d9c5d99eb2a3a4f6 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 29 May 2019 14:01:24 +0200 Subject: [PATCH 12/40] Update community health files --- code-of-conduct.md | 74 ------------------------ contributing.md | 138 --------------------------------------------- readme.md | 31 +++++----- 3 files changed, 16 insertions(+), 227 deletions(-) delete mode 100644 code-of-conduct.md delete mode 100644 contributing.md diff --git a/code-of-conduct.md b/code-of-conduct.md deleted file mode 100644 index 96d2d04..0000000 --- a/code-of-conduct.md +++ /dev/null @@ -1,74 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of -experience, nationality, personal appearance, race, religion, or sexual identity -and orientation. - -## Our Standards - -Examples of behaviour that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behaviour by participants include: - -* The use of sexualised language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others’ private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behaviour and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behaviour. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviours that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may -be further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behaviour may be -reported by contacting the project team at tituswormer@gmail.com. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an -incident. Further details of specific enforcement policies may be posted -separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project’s leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 1.4, available at . - -[homepage]: https://www.contributor-covenant.org diff --git a/contributing.md b/contributing.md deleted file mode 100644 index d1b36dc..0000000 --- a/contributing.md +++ /dev/null @@ -1,138 +0,0 @@ -# Contributing - -> This project has a [Code of Conduct][coc]. By interacting with this -> repository, organisation, or community you agree to abide by its terms. - -Hi! 👋 Exciting that you’re interested in contributing! Before doing so, take -a moment to read the following guidelines. And thanks for contributing to -**unist**! 👏👌✨ - -Before anything else: people involved with this project often do so for fun, -next to their day job: you are not entitled to free customer service. - -## Table of Contents - -* [Ecosystem](#ecosystem) -* [Questions](#questions) -* [Contributions](#contributions) - * [Improve documentation](#improve-documentation) - * [Improve issues](#improve-issues) - * [Give feedback on issues](#give-feedback-on-issues) - * [Write code](#write-code) -* [Submitting an issue](#submitting-an-issue) -* [Submitting a pull request](#submitting-a-pull-request) -* [Resources](#resources) - -## Ecosystem - -The ecosystem consists of several organisations and separate projects: most of -them are tiny, and many of them have a utility -([`mdast-util-to-hast`][mdast-util-to-hast]), a plugin -([`remark-rehype`][remark-rehype]), and relate to an ecosystem -([`remark`][remark]). Try and pick the right place to contribute to so we can -help you faster. - -## Questions - -Please chat and ask questions on spectrum! Jump in there and lurk, talk to us, -and help others. - -* [**unified**](https://spectrum.chat/unified/unified) - — Topics relating to [**unified**][unified] in general -* [**vfile**](https://spectrum.chat/unified/vfile) - — Topics relating to [**vfile**][vfile]: virtual files -* [**syntax-tree**](https://spectrum.chat/unified/syntax-tree) - — Topics relating to [**syntax-tree**][syntax-tree] and [**unist**][unist] -* [**remark**](https://spectrum.chat/unified/remark) - — Topics relating to the [**remark**][remark] ecosystem, markdown, - and [**mdast**][mdast] -* [**rehype**](https://spectrum.chat/unified/rehype) - — Topics relating to the [**rehype**][rehype] ecosystem, HTML, - and [**hast**][hast] -* [**retext**](https://spectrum.chat/unified/retext) - — Topics relating to the [**retext**][retext] ecosystem, natural language, - and [**nlcst**][nlcst] - -## Contributions - -There’s several ways to contribute, not just by writing code. - -### Improve documentation - -As a user of this project you’re perfect for helping us improve our docs. -Typo corrections, error fixes, better explanations, new examples, etcetera. -Anything! - -### Improve issues - -Some issues lack information, aren’t reproducible, or are just incorrect. -Help make them easier to resolve. - -### Give feedback on issues - -We’re always looking for more opinions on discussions in the issue tracker. - -### Write code - -Code contributions are very welcome. It’s often good to first create an issue -to report a bug or suggest a new feature before creating a pull request to -prevent you from doing unnecessary work. - -## Submitting an issue - -* The issue tracker is for issues. Use chat for support -* Search the issue tracker (including closed issues) before opening a new - issue -* Ensure you’re using the latest version of projects -* Use a clear and descriptive title -* Include as much information as possible: steps to reproduce the issue, - error message, version, operating system, etcetera -* The more time you put into an issue, the more we will -* The best issue report is a [failing test][unit-test] proving it - -## Submitting a pull request - -* Non-trivial changes are often best discussed in an issue first, to prevent - you from doing unnecessary work -* For ambitious tasks, you should try to get your work in front of the - community for feedback as soon as possible -* New features should be accompanied with tests and documentation -* Don’t include unrelated changes -* Lint and test before submitting code by running `$ npm test` -* Write a convincing description of why we should land your pull request: - it’s your job to convince us - -## Resources - -* [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) -* [Making your first contribution](https://medium.com/@vadimdemedes/making-your-first-contribution-de6576ddb190) -* [Using Pull Requests](https://help.github.com/articles/about-pull-requests/) -* [GitHub Help](https://help.github.com) - -[coc]: https://github.com/unifiedjs/unified/blob/master/code-of-conduct.md - -[vfile]: https://github.com/vfile - -[syntax-tree]: https://github.com/syntax-tree - -[unist]: https://github.com/syntax-tree/unist - -[mdast]: https://github.com/syntax-tree/mdast - -[nlcst]: https://github.com/syntax-tree/nlcst - -[hast]: https://github.com/syntax-tree/hast - -[unified]: https://github.com/unifiedjs/unified - -[remark]: https://github.com/remarkjs/remark - -[retext]: https://github.com/retextjs/retext - -[rehype]: https://github.com/rehypejs/rehype - -[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast - -[remark-rehype]: https://github.com/remarkjs/remark-rehype - -[unit-test]: https://twitter.com/sindresorhus/status/579306280495357953 diff --git a/readme.md b/readme.md index 18c90a4..3517e99 100644 --- a/readme.md +++ b/readme.md @@ -511,21 +511,18 @@ implementing unist: ## Contribute -**unist** is built by people just like you! -Check out [`contributing.md`][contributing] for ways to get started. +See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for +ways to get started. +See [`support.md`][support] for ways to get help. +Ideas for new utilities and tools can be posted in [`syntax-tree/ideas`][ideas]. + +A curated list of awesome syntax-tree, unist, hast, mdast, and nlcst resources +can be found in [awesome syntax-tree][awesome]. This project has a [Code of Conduct][coc]. 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 [spectrum][chat]! - -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`][ideas] repository! - ## Acknowledgments The initial release of this project was authored by @@ -578,17 +575,21 @@ This work is licensed under a -[logo]: https://raw.githubusercontent.com/syntax-tree/unist/b187eb7/logo.svg?sanitize=true +[health]: https://github.com/syntax-tree/.github -[releases]: https://github.com/syntax-tree/unist/releases +[contributing]: https://github.com/syntax-tree/.github/blob/master/contributing.md -[contributing]: contributing.md +[support]: https://github.com/syntax-tree/.github/blob/master/support.md -[coc]: code-of-conduct.md +[coc]: https://github.com/syntax-tree/.github/blob/master/code-of-conduct.md + +[awesome]: https://github.com/syntax-tree/awesome-syntax-tree [ideas]: https://github.com/syntax-tree/ideas -[chat]: https://spectrum.chat/unified/syntax-tree +[logo]: https://raw.githubusercontent.com/syntax-tree/unist/b187eb7/logo.svg?sanitize=true + +[releases]: https://github.com/syntax-tree/unist/releases [license]: https://creativecommons.org/licenses/by/4.0/ From 1a710fa9880c71e3f1d5a0f4578155b8b662ddc8 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 29 May 2019 14:01:45 +0200 Subject: [PATCH 13/40] Refactor license section --- readme.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/readme.md b/readme.md index 3517e99..e3247b2 100644 --- a/readme.md +++ b/readme.md @@ -569,9 +569,7 @@ for contributing to unist and related projects! ## License -Copyright © [Titus Wormer][author]. -This work is licensed under a -[Creative Commons Attribution 4.0 International License][license]. +[CC-BY-4.0][license] © [Titus Wormer][author] From 19dbf5f532ae06b552fc13bc04ee4f12b3595640 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 29 May 2019 14:08:05 +0200 Subject: [PATCH 14/40] Refactor prose --- readme.md | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/readme.md b/readme.md index e3247b2..ea9c36d 100644 --- a/readme.md +++ b/readme.md @@ -40,13 +40,13 @@ This specification is written in a [Web IDL][webidl]-like grammar. ### Syntax tree Syntax trees are representations of source code or even natural language. -These trees are abstractions that make it possible to analyse, transform, -and generate code. +These trees are abstractions that make it possible to analyse, transform, and +generate code. Syntax trees [come in two flavours][abstract-vs-concrete-trees]: -* **concrete syntax trees**: structures that represent every detail (such - as white-space in white-space insensitive languages) +* **concrete syntax trees**: structures that represent every detail (such as + white-space in white-space insensitive languages) * **abstract syntax trees**: structures that only represent details relating to the syntactic structure of code (such as ignoring whether a double or single quote was used in languages that support both, such as JavaScript). @@ -56,9 +56,9 @@ This specification can express both abstract and concrete syntax trees. ### Where this specification fits unist is not intended to be self-sufficient. -Instead, it is expected that other specifications implement unist and extend -it to express language specific nodes. -For example, see projects such as [**mdast**][mdast] (for markdown), +Instead, it is expected that other specifications implement unist and extend it +to express language specific nodes. +For example, see projects such as [**mdast**][mdast] (for Markdown), [**hast**][hast] (for HTML), and [**nlcst**][nlcst] (for natural language). unist relates to [JSON][] in that compliant syntax trees can be expressed @@ -71,15 +71,15 @@ utilities][list-of-utilities] for working with compliant syntax trees in JavaScript. The five most used utilities combined are downloaded ten million times each month. -However, unist is not limited to JavaScript and can be used in other -programming languages. +However, unist is not limited to JavaScript and can be used in other programming +languages. unist relates to the [unified][], [remark][], [rehype][], and [retext][] projects in that unist syntax trees are used throughout their ecosystems. -unist relates to the [vfile][] project in that it accepts unist nodes for -its message store, and that vfile can be a source [*file*][term-file] of a -syntax tree. +unist relates to the [vfile][] project in that it accepts unist nodes for its +message store, and that vfile can be a source [*file*][term-file] of a syntax +tree. ## Nodes @@ -130,8 +130,8 @@ interface Position { **Position** represents the location of a node in a source [*file*][term-file]. -The `start` field of **Position** represents the place of the first character -of the parsed source region. +The `start` field of **Position** represents the place of the first character of +the parsed source region. The `end` field of **Position** represents the place of the first character after the parsed source region, whether it exists or not. The value of the `start` and `end` fields implement the [**Point**][dfn-point] @@ -155,8 +155,8 @@ bravo end at line `1`, column `6`, offset `5`. The line feed would start at line `1`, column `6`, offset `5`, and end at line `2`, column `1`, offset `6`. -The last word (`bravo`) would start at line `2`, column `1`, offset `6`, and -end at line `2`, column `6`, offset `11`. +The last word (`bravo`) would start at line `2`, column `1`, offset `6`, and end +at line `2`, column `6`, offset `11`. #### `Point` @@ -421,8 +421,8 @@ sibling (**F**) is traversed and then finally its only child (**G**). **Utilities** are functions that work with nodes. -There are several projects that deal with nodes from specifications -implementing unist: +There are several projects that deal with nodes from specifications implementing +unist: * [mdast utilities](https://github.com/syntax-tree/mdast#list-of-utilities) * [hast utilities](https://github.com/syntax-tree/hast#list-of-utilities) @@ -493,18 +493,18 @@ implementing unist: ## References -* **JavaScript** +* **JavaScript**: [ECMAScript Language Specification][javascript]. Ecma International. -* **JSON** +* **JSON**: [The JavaScript Object Notation (JSON) Data Interchange Format][json], T. Bray. IETF. -* **XML** +* **XML**: [Extensible Markup Language][xml], T. Bray, J. Paoli, C. Sperberg-McQueen, E. Maler, F. Yergeau. W3C. -* **Web IDL** +* **Web IDL**: [Web IDL][webidl], C. McCormack. W3C. @@ -591,7 +591,7 @@ for contributing to unist and related projects! [license]: https://creativecommons.org/licenses/by/4.0/ -[author]: http://wooorm.com +[author]: https://wooorm.com [release]: https://github.com/syntax-tree/unist/releases/tag/2.0.0 From 252f2ae817a9eb0585e8d274106a4a3d1b22f733 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 29 May 2019 14:11:06 +0200 Subject: [PATCH 15/40] Update counts --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index ea9c36d..71877c4 100644 --- a/readme.md +++ b/readme.md @@ -69,7 +69,7 @@ formats, such as [XML][]. unist relates to [JavaScript][] in that it has a rich [ecosystem of utilities][list-of-utilities] for working with compliant syntax trees in JavaScript. -The five most used utilities combined are downloaded ten million times each +The five most used utilities combined are downloaded thirty million times each month. However, unist is not limited to JavaScript and can be used in other programming languages. From d75e9964e997799e2858552fe6025c6ceb35facc Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 18 Jul 2019 10:23:36 +0200 Subject: [PATCH 16/40] Update links --- readme.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/readme.md b/readme.md index 71877c4..93ad77d 100644 --- a/readme.md +++ b/readme.md @@ -432,7 +432,7 @@ unist: * [`unist-util-assert`](https://github.com/syntax-tree/unist-util-assert) — Assert nodes -* [`unist-util-filter`](https://github.com/eush77/unist-util-filter) +* [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter) — Create a new tree with all nodes that pass the given function * [`unist-util-find`](https://github.com/blahah/unist-util-find) — Find a node by condition @@ -450,25 +450,25 @@ unist: — Create a new tree by expanding a node into many * [`unist-util-generated`](https://github.com/syntax-tree/unist-util-generated) — Check if a node is generated -* [`unist-util-index`](https://github.com/eush77/unist-util-index) +* [`unist-util-index`](https://github.com/syntax-tree/unist-util-index) — Index nodes by property or computed key * [`unist-util-inspect`](https://github.com/syntax-tree/unist-util-inspect) — Node inspector * [`unist-util-is`](https://github.com/syntax-tree/unist-util-is) — Check if a node passes a test -* [`unist-util-map`](https://github.com/azu/unist-util-map) +* [`unist-util-map`](https://github.com/syntax-tree/unist-util-map) — Create a new tree by mapping nodes * [`unist-util-modify-children`](https://github.com/syntax-tree/unist-util-modify-children) — Modify direct children of a parent -* [`unist-util-parents`](https://github.com/eush77/unist-util-parents) +* [`unist-util-parents`](https://github.com/syntax-tree/unist-util-parents) — `parent` references on nodes * [`unist-util-position`](https://github.com/syntax-tree/unist-util-position) — Get positional info of nodes -* [`unist-util-remove`](https://github.com/eush77/unist-util-remove) +* [`unist-util-remove`](https://github.com/syntax-tree/unist-util-remove) — Remove nodes from trees * [`unist-util-remove-position`](https://github.com/syntax-tree/unist-util-remove-position) — Remove positional info from trees -* [`unist-util-select`](https://github.com/eush77/unist-util-select) +* [`unist-util-select`](https://github.com/syntax-tree/unist-util-select) — Select nodes with CSS-like selectors * [`unist-util-size`](https://github.com/syntax-tree/unist-util-size) — Calculate the number of nodes in a tree @@ -484,11 +484,11 @@ unist: — Visit direct children of a parent * [`unist-util-visit-all-after`](https://github.com/mrzmmr/unist-util-visit-all-after) — Visit nodes after another node -* [`unist-builder`](https://github.com/eush77/unist-builder) +* [`unist-builder`](https://github.com/syntax-tree/unist-builder) — Helper for creating trees -* [`unist-builder-blueprint`](https://github.com/eush77/unist-builder-blueprint) +* [`unist-builder-blueprint`](https://github.com/syntax-tree/unist-builder-blueprint) — Convert trees to `unist-builder` notation -* [`unist-builder-blueprint-cli`](https://github.com/eush77/unist-builder-blueprint-cli) +* [`unist-builder-blueprint-cli`](https://github.com/syntax-tree/unist-builder-blueprint-cli) — CLI to Convert trees to `unist-builder` notation ## References From 2c85ffc5f357dfc55b2159066bdfe6f62f92cf34 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 18 Jul 2019 10:44:35 +0200 Subject: [PATCH 17/40] Add more contributors --- readme.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index 93ad77d..63a2e69 100644 --- a/readme.md +++ b/readme.md @@ -530,7 +530,6 @@ The initial release of this project was authored by Special thanks to [**@eush77**](https://github.com/eush77) for their work, ideas, and incredibly valuable feedback! - Thanks to [**@anandthakker**](https://github.com/anandthakker), [**@anko**](https://github.com/anko), [**@arobase-che**](https://github.com/arobase-che), @@ -538,13 +537,18 @@ Thanks to [**@anandthakker**](https://github.com/anandthakker), [**@BarryThePenguin**](https://github.com/BarryThePenguin), [**@ben-eb**](https://github.com/ben-eb), [**@blahah**](https://github.com/blahah), +[**@blakeembrey**](https://github.com/blakeembrey), +[**@brainkim**](https://github.com/brainkim), [**@ChristianMurphy**](https://github.com/ChristianMurphy), +[**@davidtheclark**](https://github.com/davidtheclark), +[**@denysdovhan**](https://github.com/denysdovhan), [**@derhuerst**](https://github.com/derhuerst), [**@dozoisch**](https://github.com/dozoisch), -[**@eush77**](https://github.com/eush77), [**@fazouane-marouane**](https://github.com/fazouane-marouane), [**@gibson042**](https://github.com/gibson042), +[**@hrajchert**](https://github.com/hrajchert), [**@ikatyang**](https://github.com/ikatyang), +[**@inklesspen**](https://github.com/inklesspen), [**@izumin5210**](https://github.com/izumin5210), [**@jasonLaster**](https://github.com/jasonLaster), [**@JDvorak**](https://github.com/JDvorak), @@ -553,6 +557,8 @@ Thanks to [**@anandthakker**](https://github.com/anandthakker), [**@kmck**](https://github.com/kmck), [**@kt3k**](https://github.com/kt3k), [**@KyleAMathews**](https://github.com/KyleAMathews), +[**@luca3m**](https://github.com/luca3m), +[**@mattdesl**](https://github.com/mattdesl), [**@muraken720**](https://github.com/muraken720), [**@mrzmmr**](https://github.com/mrzmmr), [**@nwtn**](https://github.com/nwtn), @@ -560,8 +566,10 @@ Thanks to [**@anandthakker**](https://github.com/anandthakker), [**@Rokt33r**](https://github.com/Rokt33r), [**@Sarah-Seo**](https://github.com/Sarah-Seo), [**@sethvincent**](https://github.com/sethvincent), +[**@shawnbot**](https://github.com/shawnbot), [**@simov**](https://github.com/simov), [**@staltz**](https://github.com/staltz), +[**@TitanSnow**](https://github.com/TitanSnow), [**@tmcw**](https://github.com/tmcw), and [**@vhf**](https://github.com/vhf), From acff3920dbe69391b2a8c0d606ddb319c21a9072 Mon Sep 17 00:00:00 2001 From: Corbin Crutchley Date: Fri, 24 Jan 2020 05:38:57 -0800 Subject: [PATCH 18/40] Add `unist-util-flat-filter` to list of utilities Closes GH-26. Reviewed-by: Titus Wormer --- readme.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/readme.md b/readme.md index 63a2e69..f10aff8 100644 --- a/readme.md +++ b/readme.md @@ -446,6 +446,8 @@ unist: — Find nodes between two nodes or positions * [`unist-util-find-before`](https://github.com/syntax-tree/unist-util-find-before) — Find a node before another node +* [`unist-util-flat-filter`](https://github.com/unicorn-utterances/unist-util-flat-filter) + — Create a new tree with all nodes that pass the given function without references to the parent * [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap) — Create a new tree by expanding a node into many * [`unist-util-generated`](https://github.com/syntax-tree/unist-util-generated) From c3ba7cda3ed8580f5cd1ca290ce069c91df48750 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 13 Feb 2020 13:42:21 +0100 Subject: [PATCH 19/40] Update dev-dependencies --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 24045cb..fdcaf26 100644 --- a/package.json +++ b/package.json @@ -13,8 +13,8 @@ "Christian Murphy " ], "devDependencies": { - "remark-cli": "^6.0.0", - "remark-preset-wooorm": "^5.0.0" + "remark-cli": "^7.0.0", + "remark-preset-wooorm": "^6.0.0" }, "scripts": { "format": "remark . -qfo", From d249445f01f565f81e30369049863958815dd5a1 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 13 Feb 2020 13:42:30 +0100 Subject: [PATCH 20/40] Add references to xast --- readme.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/readme.md b/readme.md index f10aff8..ca06c83 100644 --- a/readme.md +++ b/readme.md @@ -19,9 +19,9 @@ The latest released version is [`2.0.0`][release]. * [Syntax tree](#syntax-tree) * [Where this specification fits](#where-this-specification-fits) * [Nodes](#nodes) - * [Node](#node) - * [Parent](#parent) - * [Literal](#literal) + * [`Node`](#node) + * [`Parent`](#parent) + * [`Literal`](#literal) * [Glossary](#glossary) * [Tree traversal](#tree-traversal) * [Utilities](#utilities) @@ -59,7 +59,8 @@ unist is not intended to be self-sufficient. Instead, it is expected that other specifications implement unist and extend it to express language specific nodes. For example, see projects such as [**mdast**][mdast] (for Markdown), -[**hast**][hast] (for HTML), and [**nlcst**][nlcst] (for natural language). +[**hast**][hast] (for HTML), [**xast**][xast] (for XML), and [**nlcst**][nlcst] +(for natural language). unist relates to [JSON][] in that compliant syntax trees can be expressed completely in JSON. @@ -426,6 +427,7 @@ unist: * [mdast utilities](https://github.com/syntax-tree/mdast#list-of-utilities) * [hast utilities](https://github.com/syntax-tree/hast#list-of-utilities) +* [xast utilities](https://github.com/syntax-tree/xast#list-of-utilities) * [nlcst utilities](https://github.com/syntax-tree/nlcst#list-of-utilities) ### List of Utilities @@ -447,7 +449,8 @@ unist: * [`unist-util-find-before`](https://github.com/syntax-tree/unist-util-find-before) — Find a node before another node * [`unist-util-flat-filter`](https://github.com/unicorn-utterances/unist-util-flat-filter) - — Create a new tree with all nodes that pass the given function without references to the parent + — Create a new tree with all nodes that pass the given function without + references to the parent * [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap) — Create a new tree by expanding a node into many * [`unist-util-generated`](https://github.com/syntax-tree/unist-util-generated) @@ -518,8 +521,8 @@ ways to get started. See [`support.md`][support] for ways to get help. Ideas for new utilities and tools can be posted in [`syntax-tree/ideas`][ideas]. -A curated list of awesome syntax-tree, unist, hast, mdast, and nlcst resources -can be found in [awesome syntax-tree][awesome]. +A curated list of awesome syntax-tree, unist, hast, xast, mdast, and nlcst +resources can be found in [awesome syntax-tree][awesome]. This project has a [Code of Conduct][coc]. By interacting with this repository, organisation, or community you agree to @@ -659,6 +662,8 @@ for contributing to unist and related projects! [hast]: https://github.com/syntax-tree/hast +[xast]: https://github.com/syntax-tree/xast + [nlcst]: https://github.com/syntax-tree/nlcst [mdast]: https://github.com/syntax-tree/mdast From b4469212d85b896be5eb1550c363b92b5fda1125 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Mon, 2 Mar 2020 14:42:31 +0100 Subject: [PATCH 21/40] Refactor prose --- readme.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/readme.md b/readme.md index ca06c83..5330030 100644 --- a/readme.md +++ b/readme.md @@ -25,7 +25,7 @@ The latest released version is [`2.0.0`][release]. * [Glossary](#glossary) * [Tree traversal](#tree-traversal) * [Utilities](#utilities) - * [List of Utilities](#list-of-utilities) + * [List of utilities](#list-of-utilities) * [References](#references) * [Contribute](#contribute) * [Acknowledgments](#acknowledgments) @@ -40,10 +40,10 @@ This specification is written in a [Web IDL][webidl]-like grammar. ### Syntax tree Syntax trees are representations of source code or even natural language. -These trees are abstractions that make it possible to analyse, transform, and +These trees are abstractions that make it possible to analyze, transform, and generate code. -Syntax trees [come in two flavours][abstract-vs-concrete-trees]: +Syntax trees [come in two flavors][abstract-vs-concrete-trees]: * **concrete syntax trees**: structures that represent every detail (such as white-space in white-space insensitive languages) @@ -425,12 +425,12 @@ sibling (**F**) is traversed and then finally its only child (**G**). There are several projects that deal with nodes from specifications implementing unist: -* [mdast utilities](https://github.com/syntax-tree/mdast#list-of-utilities) * [hast utilities](https://github.com/syntax-tree/hast#list-of-utilities) -* [xast utilities](https://github.com/syntax-tree/xast#list-of-utilities) +* [mdast utilities](https://github.com/syntax-tree/mdast#list-of-utilities) * [nlcst utilities](https://github.com/syntax-tree/nlcst#list-of-utilities) +* [xast utilities](https://github.com/syntax-tree/xast#list-of-utilities) -### List of Utilities +### List of utilities * [`unist-util-assert`](https://github.com/syntax-tree/unist-util-assert) — Assert nodes @@ -524,8 +524,8 @@ Ideas for new utilities and tools can be posted in [`syntax-tree/ideas`][ideas]. A curated list of awesome syntax-tree, unist, hast, xast, mdast, and nlcst resources can be found in [awesome syntax-tree][awesome]. -This project has a [Code of Conduct][coc]. -By interacting with this repository, organisation, or community you agree to +This project has a [code of conduct][coc]. +By interacting with this repository, organization, or community you agree to abide by its terms. ## Acknowledgments From dfbfb4cd7e137a33f794d8bd95e14882056cd081 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Mon, 2 Mar 2020 15:02:16 +0100 Subject: [PATCH 22/40] Update list of utilities --- readme.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index 5330030..ed90a74 100644 --- a/readme.md +++ b/readme.md @@ -449,8 +449,7 @@ unist: * [`unist-util-find-before`](https://github.com/syntax-tree/unist-util-find-before) — Find a node before another node * [`unist-util-flat-filter`](https://github.com/unicorn-utterances/unist-util-flat-filter) - — Create a new tree with all nodes that pass the given function without - references to the parent + — Flat map version of `unist-util-filter` * [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap) — Create a new tree by expanding a node into many * [`unist-util-generated`](https://github.com/syntax-tree/unist-util-generated) @@ -469,6 +468,8 @@ unist: — `parent` references on nodes * [`unist-util-position`](https://github.com/syntax-tree/unist-util-position) — Get positional info of nodes +* [`unist-util-reduce`](https://github.com/GenerousLabs/unist-util-reduce) + — Recursively reduce a tree * [`unist-util-remove`](https://github.com/syntax-tree/unist-util-remove) — Remove nodes from trees * [`unist-util-remove-position`](https://github.com/syntax-tree/unist-util-remove-position) From 1f87abaf061818f5626cd97b872f5b80a4cb9e9b Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 18 Jun 2020 16:23:12 +0200 Subject: [PATCH 23/40] Update dev-dependencies --- package.json | 4 ++-- readme.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package.json b/package.json index fdcaf26..b3ed39f 100644 --- a/package.json +++ b/package.json @@ -13,8 +13,8 @@ "Christian Murphy " ], "devDependencies": { - "remark-cli": "^7.0.0", - "remark-preset-wooorm": "^6.0.0" + "remark-cli": "^8.0.0", + "remark-preset-wooorm": "^7.0.0" }, "scripts": { "format": "remark . -qfo", diff --git a/readme.md b/readme.md index ed90a74..168960c 100644 --- a/readme.md +++ b/readme.md @@ -2,7 +2,7 @@ **Uni**versal **S**yntax **T**ree. -* * * +*** **unist** is a specification for syntax trees. It has a big [ecosystem of utilities][list-of-utilities] in JavaScript for From d9778a6d15319cd9281205648804a814a7ef2235 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 18 Jun 2020 16:23:36 +0200 Subject: [PATCH 24/40] Change `master` in links to `HEAD` --- readme.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/readme.md b/readme.md index 168960c..1007fc4 100644 --- a/readme.md +++ b/readme.md @@ -589,11 +589,11 @@ for contributing to unist and related projects! [health]: https://github.com/syntax-tree/.github -[contributing]: https://github.com/syntax-tree/.github/blob/master/contributing.md +[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md -[support]: https://github.com/syntax-tree/.github/blob/master/support.md +[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md -[coc]: https://github.com/syntax-tree/.github/blob/master/code-of-conduct.md +[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md [awesome]: https://github.com/syntax-tree/awesome-syntax-tree From 2392bcbdbd8bdaf3f13933d5e3884ca6ce949167 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 28 Oct 2020 13:12:24 +0100 Subject: [PATCH 25/40] Update dev-dependencies --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index b3ed39f..7cb8f76 100644 --- a/package.json +++ b/package.json @@ -13,8 +13,8 @@ "Christian Murphy " ], "devDependencies": { - "remark-cli": "^8.0.0", - "remark-preset-wooorm": "^7.0.0" + "remark-cli": "^9.0.0", + "remark-preset-wooorm": "^8.0.0" }, "scripts": { "format": "remark . -qfo", From 573275f37dd3f638166cbf0c4281b3ca20175a65 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 28 Oct 2020 13:20:41 +0100 Subject: [PATCH 26/40] Refactor prose --- readme.md | 277 +++++++++++++++++++++++++++--------------------------- 1 file changed, 138 insertions(+), 139 deletions(-) diff --git a/readme.md b/readme.md index 1007fc4..4617ee7 100644 --- a/readme.md +++ b/readme.md @@ -13,9 +13,9 @@ This document may not be released. See [releases][] for released documents. The latest released version is [`2.0.0`][release]. -## Table of Contents +## Contents -* [Introduction](#introduction) +* [Intro](#intro) * [Syntax tree](#syntax-tree) * [Where this specification fits](#where-this-specification-fits) * [Nodes](#nodes) @@ -31,7 +31,7 @@ The latest released version is [`2.0.0`][release]. * [Acknowledgments](#acknowledgments) * [License](#license) -## Introduction +## Intro This document defines a general-purpose format for syntax trees. Development of unist started in July 2015. @@ -58,9 +58,8 @@ This specification can express both abstract and concrete syntax trees. unist is not intended to be self-sufficient. Instead, it is expected that other specifications implement unist and extend it to express language specific nodes. -For example, see projects such as [**mdast**][mdast] (for Markdown), -[**hast**][hast] (for HTML), [**xast**][xast] (for XML), and [**nlcst**][nlcst] -(for natural language). +For example, see projects such as **[hast][]** (for HTML), **[nlcst][]** (for +natural language), **[mdast][]** (for Markdown), and **[xast][]** (for XML). unist relates to [JSON][] in that compliant syntax trees can be expressed completely in JSON. @@ -79,13 +78,13 @@ unist relates to the [unified][], [remark][], [rehype][], and [retext][] projects in that unist syntax trees are used throughout their ecosystems. unist relates to the [vfile][] project in that it accepts unist nodes for its -message store, and that vfile can be a source [*file*][term-file] of a syntax +message store, and that vfile can be a source *[file][term-file]* of a syntax tree. ## Nodes Syntactic units in unist syntax trees are called nodes, and implement the -[**Node**][dfn-node] interface. +**[Node][dfn-node]** interface. ### `Node` @@ -98,19 +97,19 @@ interface Node { ``` The `type` field is a non-empty string representing the variant of a node. -This field can be used to determine the [*type*][term-type] a node implements. +This field can be used to determine the *[type][term-type]* a node implements. The `data` field represents information from the ecosystem. -The value of the `data` field implements the [**Data**][dfn-data] interface. +The value of the `data` field implements the **[Data][dfn-data]** interface. The `position` field represents the location of a node in a source document. -The value of the `position` field implements the [**Position**][dfn-position] +The value of the `position` field implements the **[Position][dfn-position]** interface. The `position` field must not be present if a node is -[*generated*][term-generated]. +*[generated][term-generated]*. Specifications implementing unist are encouraged to define more fields. -Ecosystems can define fields on [**Data**][dfn-data]. +Ecosystems can define fields on **[Data][dfn-data]**. Any value in unist **must** be expressible in JSON values: `string`, `number`, `object`, `array`, `true`, `false`, or `null`. @@ -129,21 +128,21 @@ interface Position { } ``` -**Position** represents the location of a node in a source [*file*][term-file]. +**Position** represents the location of a node in a source *[file][term-file]*. The `start` field of **Position** represents the place of the first character of the parsed source region. The `end` field of **Position** represents the place of the first character after the parsed source region, whether it exists or not. -The value of the `start` and `end` fields implement the [**Point**][dfn-point] +The value of the `start` and `end` fields implement the **[Point][dfn-point]** interface. The `indent` field of **Position** represents the start column at each index (plus start line) in the source region, for elements that span multiple lines. If the syntactic unit represented by a node is not present in the source -[*file*][term-file] at the time of parsing, the node is said to be -[*generated*][term-generated] and it must not have positional information. +*[file][term-file]* at the time of parsing, the node is said to be +*[generated][term-generated]* and it must not have positional information. For example, if the following value was represented as unist: @@ -169,7 +168,7 @@ interface Point { } ``` -**Point** represents one place in a source [*file*][term-file]. +**Point** represents one place in a source *[file][term-file]*. The `line` field (1-indexed integer) represents a line in a source file. The `column` field (1-indexed integer) represents a column in a source file. @@ -197,8 +196,8 @@ interface Parent <: Node { } ``` -Nodes containing other nodes (said to be [*children*][term-child]) extend the -abstract interface **Parent** ([**Node**][dfn-node]). +Nodes containing other nodes (said to be *[children][term-child]*) extend the +abstract interface **Parent** (**[Node][dfn-node]**). The `children` field is a list representing the children of a node. @@ -211,7 +210,7 @@ interface Literal <: Node { ``` Nodes containing a value extend the abstract interface **Literal** -([**Node**][dfn-node]). +(**[Node][dfn-node]**). The `value` field can contain any value. @@ -219,7 +218,7 @@ The `value` field can contain any value. ###### Tree -A **tree** is a node and all of its [*descendants*][term-descendant] (if any). +A **tree** is a node and all of its *[descendants][term-descendant]* (if any). ###### Child @@ -227,66 +226,66 @@ 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*][term-child] of X. +Node X is **parent** of node Y, if Y is a *[child][term-child]* of X. ###### Index -The **index** of a [*child*][term-child] is its number of preceding -[*siblings*][term-sibling], or `0` if it has none. +The **index** of a *[child][term-child]* is its number of preceding +*[siblings][term-sibling]*, or `0` if it has none. ###### Sibling Node X is a **sibling** of node Y, if X and Y have the same -[*parent*][term-parent] (if any). +*[parent][term-parent]* (if any). -The **previous sibling** of a [*child*][term-child] is its **sibling** at its -[*index*][term-index] minus 1. +The **previous sibling** of a *[child][term-child]* is its **sibling** at its +*[index][term-index]* minus 1. -The **next sibling** of a [*child*][term-child] is its **sibling** at its -[*index*][term-index] plus 1. +The **next sibling** of a *[child][term-child]* is its **sibling** at its +*[index][term-index]* plus 1. ###### Root -The **root** of a node is itself, if without [*parent*][term-parent], or the -**root** of its [*parent*][term-parent]. +The **root** of a node is itself, if without *[parent][term-parent]*, or the +**root** of its *[parent][term-parent]*. -The **root** of a [*tree*][term-tree] is any node in that [*tree*][term-tree] -without [*parent*][term-parent]. +The **root** of a *[tree][term-tree]* is any node in that *[tree][term-tree]* +without *[parent][term-parent]*. ###### Descendant -Node X is **descendant** of node Y, if X is a [*child*][term-child] of Y, or if -X is a [*child*][term-child] of node Z that is a **descendant** of Y. +Node X is **descendant** of node Y, if X is a *[child][term-child]* of Y, or if +X is a *[child][term-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*][term-descendant] +Node X is an **ancestor** of node Y, if Y is a *[descendant][term-descendant]* of X. An **inclusive ancestor** is a node or one of its **ancestors**. ###### Head -The **head** of a node is its first [*child*][term-child] (if any). +The **head** of a node is its first *[child][term-child]* (if any). ###### Tail -The **tail** of a node is its last [*child*][term-child] (if any). +The **tail** of a node is its last *[child][term-child]* (if any). ###### Leaf -A **leaf** is a node with no [*children*][term-child]. +A **leaf** is a node with no *[children][term-child]*. ###### Branch -A **branch** is a node with one or more [*children*][term-child]. +A **branch** is a node with one or more *[children][term-child]*. ###### Generated -A node is **generated** if it does not have [*positional -information*][term-positional-info]. +A node is **generated** if it does not have *[positional +information][term-positional-info]*. ###### Type @@ -300,11 +299,11 @@ The **positional information** of a node is the value of its `position` field. A **file** is a source document that represents the original file that was parsed to produce the syntax tree. -[*Positional information*][term-positional-info] represents the place of a node +*[Positional information][term-positional-info]* represents the place of a node in this file. Files are provided by the host environment and not defined by unist. -For example, see projects such as [**vfile**][vfile]. +For example, see projects such as **[vfile][]**. ###### Preorder @@ -312,24 +311,24 @@ In **preorder** (**NLR**) is [depth-first][traversal-depth] [tree traversal][traversal] that performs the following steps for each node *N*: 1. **N**: visit *N* itself -2. **L**: traverse [*head*][term-head] (then its *next sibling*, recursively +2. **L**: traverse *[head][term-head]* (then its *next sibling*, recursively moving forward until reaching *tail*) -3. **R**: traverse [*tail*][term-tail] +3. **R**: traverse *[tail][term-tail]* ###### Postorder In **postorder** (**LRN**) is [depth-first][traversal-depth] [tree traversal][traversal] that performs the following steps for each node *N*: -1. **L**: traverse [*head*][term-head] (then its *next sibling*, recursively +1. **L**: traverse *[head][term-head]* (then its *next sibling*, recursively moving forward until reaching *tail*) -2. **R**: traverse [*tail*][term-tail] +2. **R**: traverse *[tail][term-tail]* 3. **N**: visit *N* itself ###### Enter **Enter** is a step right before other steps performed on a given node *N* when -[**traversing**][traversal] a tree. +**[traversing][traversal]** a tree. For example, when performing *preorder* traversal, **enter** is the first step taken, right before visiting *N* itself. @@ -337,14 +336,14 @@ taken, right before visiting *N* itself. ###### Exit **Exit** is a step right after other steps performed on a given node *N* when -[**traversing**][traversal] a tree. +**[traversing][traversal]** a tree. For example, when performing *preorder* traversal, **exit** is the last step -taken, right after traversing the [*tail*][term-tail] of *N*. +taken, right after traversing the *[tail][term-tail]* of *N*. ## Tree traversal -**Tree traversal** is a common task when working with a [*tree*][term-tree] to +**Tree traversal** is a common task when working with a *[tree][term-tree]* to search it. Tree traversal is typically either *breadth-first* or *depth-first*. @@ -371,8 +370,8 @@ In the following examples, we’ll work with this tree: ###### Breadth-first traversal **Breadth-first traversal** is visiting a node and all its -[*siblings*][term-sibling] to broaden the search at that level, before -traversing [*children*][term-child]. +*[siblings][term-sibling]* to broaden the search at that level, before +traversing *[children][term-child]*. For the syntax tree defined in the diagram, a breadth-first traversal first searches the root of the tree (**A**), then its children (**B** and **F**), then @@ -381,20 +380,20 @@ their children (**C**, **D**, **E**, and **G**). ###### Depth-first traversal Alternatively, and more commonly, **depth-first traversal** is used. -The search is first deepened, by traversing [*children*][term-child], before -traversing [*siblings*][term-sibling]. +The search is first deepened, by traversing *[children][term-child]*, before +traversing *[siblings][term-sibling]*. For the syntax tree defined in the diagram, a depth-first traversal first searches the root of the tree (**A**), then one of its children (**B** or **F**), then their children (**C**, **D**, and **E**, or **G**). -For a given node *N* with [*children*][term-child], a **depth-first traversal** +For a given node *N* with *[children][term-child]*, a **depth-first traversal** performs three steps, simplified to only binary trees (every node has -[*head*][term-head] and [*tail*][term-tail], but no other children): +*[head][term-head]* and *[tail][term-tail]*, but no other children): * **N**: visit *N* itself -* **L**: traverse [*head*][term-head] -* **R**: traverse [*tail*][term-tail] +* **L**: traverse *[head][term-head]* +* **R**: traverse *[tail][term-tail]* These steps can be done in any order, but for non-binary trees, **L** and **R** occur together. @@ -409,13 +408,13 @@ Because **L** and **R** occur together for non-binary trees, we can produce four types of orders: NLR, NRL, LRN, RLN. NLR and LRN (the two *left-to-right* traversal options) are most commonly used -and respectively named [*preorder*][term-preorder] and -[*postorder*][term-postorder]. +and respectively named *[preorder][term-preorder]* and +*[postorder][term-postorder]*. For the syntax tree defined in the diagram, *preorder* and *postorder* traversal thus first search the root of the tree (**A**), then its head (**B**), then its children from left-to-right (**C**, **D**, and then **E**). -After all [*descendants*][term-descendant] of **B** are traversed, its next +After all *[descendants][term-descendant]* of **B** are traversed, its next sibling (**F**) is traversed and then finally its only child (**G**). ## Utilities @@ -433,69 +432,69 @@ unist: ### List of utilities * [`unist-util-assert`](https://github.com/syntax-tree/unist-util-assert) - — Assert nodes + — assert nodes * [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter) - — Create a new tree with all nodes that pass the given function + — create a new tree with all nodes that pass the given function * [`unist-util-find`](https://github.com/blahah/unist-util-find) - — Find a node by condition + — find a node by condition * [`unist-util-find-after`](https://github.com/syntax-tree/unist-util-find-after) - — Find a node after another node + — find a node after another node * [`unist-util-find-all-after`](https://github.com/syntax-tree/unist-util-find-all-after) - — Find nodes after another node or index + — find nodes after another node or index * [`unist-util-find-all-before`](https://github.com/syntax-tree/unist-util-find-all-before) - — Find nodes before another node or index + — find nodes before another node or index * [`unist-util-find-all-between`](https://github.com/mrzmmr/unist-util-find-all-between) - — Find nodes between two nodes or positions + — find nodes between two nodes or positions * [`unist-util-find-before`](https://github.com/syntax-tree/unist-util-find-before) - — Find a node before another node + — find a node before another node * [`unist-util-flat-filter`](https://github.com/unicorn-utterances/unist-util-flat-filter) - — Flat map version of `unist-util-filter` + — flat map version of `unist-util-filter` * [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap) - — Create a new tree by expanding a node into many + — create a new tree by expanding a node into many * [`unist-util-generated`](https://github.com/syntax-tree/unist-util-generated) - — Check if a node is generated + — check if a node is generated * [`unist-util-index`](https://github.com/syntax-tree/unist-util-index) - — Index nodes by property or computed key + — index nodes by property or computed key * [`unist-util-inspect`](https://github.com/syntax-tree/unist-util-inspect) - — Node inspector + — node inspector * [`unist-util-is`](https://github.com/syntax-tree/unist-util-is) - — Check if a node passes a test + — check if a node passes a test * [`unist-util-map`](https://github.com/syntax-tree/unist-util-map) - — Create a new tree by mapping nodes + — create a new tree by mapping nodes * [`unist-util-modify-children`](https://github.com/syntax-tree/unist-util-modify-children) - — Modify direct children of a parent + — modify direct children of a parent * [`unist-util-parents`](https://github.com/syntax-tree/unist-util-parents) — `parent` references on nodes * [`unist-util-position`](https://github.com/syntax-tree/unist-util-position) - — Get positional info of nodes + — get positional info of nodes * [`unist-util-reduce`](https://github.com/GenerousLabs/unist-util-reduce) - — Recursively reduce a tree + — recursively reduce a tree * [`unist-util-remove`](https://github.com/syntax-tree/unist-util-remove) - — Remove nodes from trees + — remove nodes from trees * [`unist-util-remove-position`](https://github.com/syntax-tree/unist-util-remove-position) - — Remove positional info from trees + — remove positional info from trees * [`unist-util-select`](https://github.com/syntax-tree/unist-util-select) - — Select nodes with CSS-like selectors + — select nodes with CSS-like selectors * [`unist-util-size`](https://github.com/syntax-tree/unist-util-size) - — Calculate the number of nodes in a tree + — calculate the number of nodes in a tree * [`unist-util-source`](https://github.com/syntax-tree/unist-util-source) - — Get the source of a value (node or position) in a file + — get the source of a value (node or position) in a file * [`unist-util-stringify-position`](https://github.com/syntax-tree/unist-util-stringify-position) - — Stringify a node, position, or point + — stringify a node, position, or point * [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit) - — Recursively walk over nodes + — recursively walk over nodes * [`unist-util-visit-parents`](https://github.com/syntax-tree/unist-util-visit-parents) - — Recursively walk over nodes, with a stack of parents + — recursively walk over nodes, with a stack of parents * [`unist-util-visit-children`](https://github.com/syntax-tree/unist-util-visit-children) - — Visit direct children of a parent + — visit direct children of a parent * [`unist-util-visit-all-after`](https://github.com/mrzmmr/unist-util-visit-all-after) - — Visit nodes after another node + — visit nodes after another node * [`unist-builder`](https://github.com/syntax-tree/unist-builder) - — Helper for creating trees + — helper for creating trees * [`unist-builder-blueprint`](https://github.com/syntax-tree/unist-builder-blueprint) - — Convert trees to `unist-builder` notation + — convert trees to `unist-builder` notation * [`unist-builder-blueprint-cli`](https://github.com/syntax-tree/unist-builder-blueprint-cli) - — CLI to Convert trees to `unist-builder` notation + — CLI to convert trees to `unist-builder` notation ## References @@ -532,53 +531,53 @@ abide by its terms. ## Acknowledgments The initial release of this project was authored by -[**@wooorm**](https://github.com/wooorm). +**[@wooorm](https://github.com/wooorm)**. -Special thanks to [**@eush77**](https://github.com/eush77) for their work, +Special thanks to **[@eush77](https://github.com/eush77)** for their work, ideas, and incredibly valuable feedback! -Thanks to [**@anandthakker**](https://github.com/anandthakker), -[**@anko**](https://github.com/anko), -[**@arobase-che**](https://github.com/arobase-che), -[**@azu**](https://github.com/azu), -[**@BarryThePenguin**](https://github.com/BarryThePenguin), -[**@ben-eb**](https://github.com/ben-eb), -[**@blahah**](https://github.com/blahah), -[**@blakeembrey**](https://github.com/blakeembrey), -[**@brainkim**](https://github.com/brainkim), -[**@ChristianMurphy**](https://github.com/ChristianMurphy), -[**@davidtheclark**](https://github.com/davidtheclark), -[**@denysdovhan**](https://github.com/denysdovhan), -[**@derhuerst**](https://github.com/derhuerst), -[**@dozoisch**](https://github.com/dozoisch), -[**@fazouane-marouane**](https://github.com/fazouane-marouane), -[**@gibson042**](https://github.com/gibson042), -[**@hrajchert**](https://github.com/hrajchert), -[**@ikatyang**](https://github.com/ikatyang), -[**@inklesspen**](https://github.com/inklesspen), -[**@izumin5210**](https://github.com/izumin5210), -[**@jasonLaster**](https://github.com/jasonLaster), -[**@JDvorak**](https://github.com/JDvorak), -[**@jlevy**](https://github.com/jlevy), -[**@justjake**](https://github.com/justjake), -[**@kmck**](https://github.com/kmck), -[**@kt3k**](https://github.com/kt3k), -[**@KyleAMathews**](https://github.com/KyleAMathews), -[**@luca3m**](https://github.com/luca3m), -[**@mattdesl**](https://github.com/mattdesl), -[**@muraken720**](https://github.com/muraken720), -[**@mrzmmr**](https://github.com/mrzmmr), -[**@nwtn**](https://github.com/nwtn), -[**@rhysd**](https://github.com/rhysd), -[**@Rokt33r**](https://github.com/Rokt33r), -[**@Sarah-Seo**](https://github.com/Sarah-Seo), -[**@sethvincent**](https://github.com/sethvincent), -[**@shawnbot**](https://github.com/shawnbot), -[**@simov**](https://github.com/simov), -[**@staltz**](https://github.com/staltz), -[**@TitanSnow**](https://github.com/TitanSnow), -[**@tmcw**](https://github.com/tmcw), +Thanks to **[@anandthakker](https://github.com/anandthakker)**, +**[@anko](https://github.com/anko)**, +**[@arobase-che](https://github.com/arobase-che)**, +**[@azu](https://github.com/azu)**, +**[@BarryThePenguin](https://github.com/BarryThePenguin)**, +**[@ben-eb](https://github.com/ben-eb)**, +**[@blahah](https://github.com/blahah)**, +**[@blakeembrey](https://github.com/blakeembrey)**, +**[@brainkim](https://github.com/brainkim)**, +**[@ChristianMurphy](https://github.com/ChristianMurphy)**, +**[@davidtheclark](https://github.com/davidtheclark)**, +**[@denysdovhan](https://github.com/denysdovhan)**, +**[@derhuerst](https://github.com/derhuerst)**, +**[@dozoisch](https://github.com/dozoisch)**, +**[@fazouane-marouane](https://github.com/fazouane-marouane)**, +**[@gibson042](https://github.com/gibson042)**, +**[@hrajchert](https://github.com/hrajchert)**, +**[@ikatyang](https://github.com/ikatyang)**, +**[@inklesspen](https://github.com/inklesspen)**, +**[@izumin5210](https://github.com/izumin5210)**, +**[@jasonLaster](https://github.com/jasonLaster)**, +**[@JDvorak](https://github.com/JDvorak)**, +**[@jlevy](https://github.com/jlevy)**, +**[@justjake](https://github.com/justjake)**, +**[@kmck](https://github.com/kmck)**, +**[@kt3k](https://github.com/kt3k)**, +**[@KyleAMathews](https://github.com/KyleAMathews)**, +**[@luca3m](https://github.com/luca3m)**, +**[@mattdesl](https://github.com/mattdesl)**, +**[@muraken720](https://github.com/muraken720)**, +**[@mrzmmr](https://github.com/mrzmmr)**, +**[@nwtn](https://github.com/nwtn)**, +**[@rhysd](https://github.com/rhysd)**, +**[@Rokt33r](https://github.com/Rokt33r)**, +**[@Sarah-Seo](https://github.com/Sarah-Seo)**, +**[@sethvincent](https://github.com/sethvincent)**, +**[@shawnbot](https://github.com/shawnbot)**, +**[@simov](https://github.com/simov)**, +**[@staltz](https://github.com/staltz)**, +**[@TitanSnow](https://github.com/TitanSnow)**, +**[@tmcw](https://github.com/tmcw)**, and -[**@vhf**](https://github.com/vhf), +**[@vhf](https://github.com/vhf)**, for contributing to unist and related projects! ## License From 367da2e6bb93113e236e99834763f03ed0e9addd Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sun, 14 Feb 2021 14:07:00 +0100 Subject: [PATCH 27/40] Update `logo.svg` --- logo.svg | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/logo.svg b/logo.svg index 70ff38a..12fa5f9 100644 --- a/logo.svg +++ b/logo.svg @@ -1,4 +1,13 @@ - - - + + + + + From 53741ec751eaaca5b50eb1bcabe2411d0344c8d2 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sun, 14 Feb 2021 14:07:32 +0100 Subject: [PATCH 28/40] Update reference to `logo.svg` --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 4617ee7..5e079a7 100644 --- a/readme.md +++ b/readme.md @@ -598,7 +598,7 @@ for contributing to unist and related projects! [ideas]: https://github.com/syntax-tree/ideas -[logo]: https://raw.githubusercontent.com/syntax-tree/unist/b187eb7/logo.svg?sanitize=true +[logo]: https://raw.githubusercontent.com/syntax-tree/unist/367da2e/logo.svg?sanitize=true [releases]: https://github.com/syntax-tree/unist/releases From de068476e1697242591b61cc11943baa10081dee Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 14 Apr 2021 12:34:34 +0200 Subject: [PATCH 29/40] Add bb --- .github/workflows/bb.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .github/workflows/bb.yml diff --git a/.github/workflows/bb.yml b/.github/workflows/bb.yml new file mode 100644 index 0000000..291ab09 --- /dev/null +++ b/.github/workflows/bb.yml @@ -0,0 +1,13 @@ +name: bb +on: + issues: + types: [opened, reopened, edited, closed, labeled, unlabeled] + pull_request: + types: [opened, reopened, edited, closed, labeled, unlabeled] +jobs: + main: + runs-on: ubuntu-latest + steps: + - uses: unifiedjs/beep-boop-beta@main + with: + repo-token: ${{secrets.GITHUB_TOKEN}} From b18b8016d42d8fabff4e2c3780365f8d9457f535 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 14 Apr 2021 12:35:16 +0200 Subject: [PATCH 30/40] Update dotfile --- .npmrc | 1 + 1 file changed, 1 insertion(+) create mode 100644 .npmrc diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000..43c97e7 --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +package-lock=false From afa368f2b84b804895fd250758056019a738ce1a Mon Sep 17 00:00:00 2001 From: Titus Date: Tue, 1 Jun 2021 10:37:43 +0200 Subject: [PATCH 31/40] Use `pull_request_target` in bb --- .github/workflows/bb.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/bb.yml b/.github/workflows/bb.yml index 291ab09..0198fc3 100644 --- a/.github/workflows/bb.yml +++ b/.github/workflows/bb.yml @@ -2,7 +2,7 @@ name: bb on: issues: types: [opened, reopened, edited, closed, labeled, unlabeled] - pull_request: + pull_request_target: types: [opened, reopened, edited, closed, labeled, unlabeled] jobs: main: From 3d0d9bbcf10c9e4851dc4d51f4cb8e66dbb4cf99 Mon Sep 17 00:00:00 2001 From: Goran Date: Thu, 23 Sep 2021 09:43:29 -0400 Subject: [PATCH 32/40] Add `unist-util-ancestor` to list of utilities Closes GH-53. Reviewed-by: Titus Wormer --- readme.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/readme.md b/readme.md index 5e079a7..1844403 100644 --- a/readme.md +++ b/readme.md @@ -431,6 +431,8 @@ unist: ### List of utilities +* [`unist-util-ancestor`](https://github.com/gorango/unist-util-ancestor) + — get the common ancestor of one or more nodes * [`unist-util-assert`](https://github.com/syntax-tree/unist-util-assert) — assert nodes * [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter) From 26f03953a3a2b22a68a7e7f389a9293ee443c127 Mon Sep 17 00:00:00 2001 From: Corbin Crutchley Date: Thu, 28 Apr 2022 10:10:17 -0700 Subject: [PATCH 33/40] Add `unist-util-replace-all-between` to list of utilities Closes GH-68. Reviewed-by: Christian Murphy Reviewed-by: Titus Wormer --- readme.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/readme.md b/readme.md index 1844403..5faff83 100644 --- a/readme.md +++ b/readme.md @@ -475,6 +475,8 @@ unist: — remove nodes from trees * [`unist-util-remove-position`](https://github.com/syntax-tree/unist-util-remove-position) — remove positional info from trees +* [`unist-util-replace-all-between`](https://github.com/unicorn-utterances/unist-util-replace-all-between) + — replace nodes between two nodes or positions * [`unist-util-select`](https://github.com/syntax-tree/unist-util-select) — select nodes with CSS-like selectors * [`unist-util-size`](https://github.com/syntax-tree/unist-util-size) From d3957542bd23f5db6cff302a63e39456de7ff17b Mon Sep 17 00:00:00 2001 From: Kevin Wang Date: Thu, 28 Jul 2022 12:46:15 -0400 Subject: [PATCH 34/40] Refactor diagram to use mermaid Closes GH-74. Reviewed-by: Titus Wormer --- readme.md | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/readme.md b/readme.md index 5faff83..6d60400 100644 --- a/readme.md +++ b/readme.md @@ -349,22 +349,12 @@ Tree traversal is typically either *breadth-first* or *depth-first*. In the following examples, we’ll work with this tree: -```ascii - +---+ - | A | - +-+-+ - | - +-----+-----+ - | | - +-+-+ +-+-+ - | B | | F | - +-+-+ +-+-+ - | | - +-----+--+--+ | - | | | | - +-+-+ +-+-+ +-+-+ +-+-+ - | C | | D | | E | | G | - +---+ +---+ +---+ +---+ +```mermaid +graph TD + A-->B-->C + B-->D + B-->E + A-->F-->G ``` ###### Breadth-first traversal From d617e477caea9f6f0b662361c9879877b9348a73 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sat, 4 Feb 2023 09:53:44 +0100 Subject: [PATCH 35/40] Update dev-dependencies --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 7cb8f76..29da553 100644 --- a/package.json +++ b/package.json @@ -13,8 +13,8 @@ "Christian Murphy " ], "devDependencies": { - "remark-cli": "^9.0.0", - "remark-preset-wooorm": "^8.0.0" + "remark-cli": "^11.0.0", + "remark-preset-wooorm": "^9.0.0" }, "scripts": { "format": "remark . -qfo", From d3936a01f973d3eecc0b95b61512caa90de220d6 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sat, 4 Feb 2023 16:51:24 +0100 Subject: [PATCH 36/40] Add section on types --- readme.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/readme.md b/readme.md index 6d60400..58bff65 100644 --- a/readme.md +++ b/readme.md @@ -18,6 +18,7 @@ The latest released version is [`2.0.0`][release]. * [Intro](#intro) * [Syntax tree](#syntax-tree) * [Where this specification fits](#where-this-specification-fits) +* [Types](#types) * [Nodes](#nodes) * [`Node`](#node) * [`Parent`](#parent) @@ -81,6 +82,15 @@ unist relates to the [vfile][] project in that it accepts unist nodes for its message store, and that vfile can be a source *[file][term-file]* of a syntax tree. +## Types + +If you are using TypeScript, you can use the unist types by installing them +with npm: + +```sh +npm install @types/unist +``` + ## Nodes Syntactic units in unist syntax trees are called nodes, and implement the From 8ca4c8bdb5576fddaf4e97c182393f08cbfb48ef Mon Sep 17 00:00:00 2001 From: Titus Date: Thu, 15 Jun 2023 12:35:48 +0200 Subject: [PATCH 37/40] Remove `indent` on positions Closes GH-98. Reviewed-by: Remco Haszing Reviewed-by: Christian Murphy --- readme.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/readme.md b/readme.md index 58bff65..2f0689e 100644 --- a/readme.md +++ b/readme.md @@ -134,7 +134,6 @@ For example, in JavaScript, a tree can be passed through interface Position { start: Point end: Point - indent: [number >= 1]? } ``` @@ -147,9 +146,6 @@ after the parsed source region, whether it exists or not. The value of the `start` and `end` fields implement the **[Point][dfn-point]** interface. -The `indent` field of **Position** represents the start column at each index -(plus start line) in the source region, for elements that span multiple lines. - If the syntactic unit represented by a node is not present in the source *[file][term-file]* at the time of parsing, the node is said to be *[generated][term-generated]* and it must not have positional information. From 200d49abce246bd2f338bd5560faa1b674eb659e Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 15 Jun 2023 15:45:16 +0200 Subject: [PATCH 38/40] Remove two archived utilities --- readme.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/readme.md b/readme.md index 2f0689e..bc1a2e8 100644 --- a/readme.md +++ b/readme.md @@ -491,10 +491,6 @@ unist: — visit nodes after another node * [`unist-builder`](https://github.com/syntax-tree/unist-builder) — helper for creating trees -* [`unist-builder-blueprint`](https://github.com/syntax-tree/unist-builder-blueprint) - — convert trees to `unist-builder` notation -* [`unist-builder-blueprint-cli`](https://github.com/syntax-tree/unist-builder-blueprint-cli) - — CLI to convert trees to `unist-builder` notation ## References From 50d129555a4f671af988f63c4dde470405c1f4f4 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 15 Jun 2023 15:45:25 +0200 Subject: [PATCH 39/40] Update some links --- readme.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/readme.md b/readme.md index bc1a2e8..5cd229c 100644 --- a/readme.md +++ b/readme.md @@ -515,7 +515,6 @@ unist: See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for ways to get started. See [`support.md`][support] for ways to get help. -Ideas for new utilities and tools can be posted in [`syntax-tree/ideas`][ideas]. A curated list of awesome syntax-tree, unist, hast, xast, mdast, and nlcst resources can be found in [awesome syntax-tree][awesome]. @@ -584,16 +583,14 @@ for contributing to unist and related projects! [health]: https://github.com/syntax-tree/.github -[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md +[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md -[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md +[support]: https://github.com/syntax-tree/.github/blob/main/support.md -[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md +[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md [awesome]: https://github.com/syntax-tree/awesome-syntax-tree -[ideas]: https://github.com/syntax-tree/ideas - [logo]: https://raw.githubusercontent.com/syntax-tree/unist/367da2e/logo.svg?sanitize=true [releases]: https://github.com/syntax-tree/unist/releases @@ -648,13 +645,13 @@ for contributing to unist and related projects! [list-of-utilities]: #list-of-utilities -[webidl]: https://heycam.github.io/webidl/ +[webidl]: https://webidl.spec.whatwg.org -[json]: https://tools.ietf.org/html/rfc7159 +[json]: https://datatracker.ietf.org/doc/html/rfc7159 [xml]: https://www.w3.org/TR/xml/ -[javascript]: https://www.ecma-international.org/ecma-262/9.0/index.html +[javascript]: https://262.ecma-international.org/9.0/ [hast]: https://github.com/syntax-tree/hast From 7db7a3f395e78fc88fb2bbca7a144a23d757083a Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 15 Jun 2023 15:59:09 +0200 Subject: [PATCH 40/40] 3.0.0 --- readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index 5cd229c..263b5be 100644 --- a/readme.md +++ b/readme.md @@ -11,7 +11,7 @@ It’s implemented by several other specifications. This document may not be released. See [releases][] for released documents. -The latest released version is [`2.0.0`][release]. +The latest released version is [`3.0.0`][release]. ## Contents @@ -599,7 +599,7 @@ for contributing to unist and related projects! [author]: https://wooorm.com -[release]: https://github.com/syntax-tree/unist/releases/tag/2.0.0 +[release]: https://github.com/syntax-tree/unist/releases/tag/3.0.0 [abstract-vs-concrete-trees]: https://eli.thegreenplace.net/2009/02/16/abstract-vs-concrete-syntax-trees/