branch: elpa/clojure-ts-mode
commit 6ddcd2cc0f5e7da401e9bc77d6572239362dfb10
Author: dannyfreeman <danny@dfreeman.email>
Commit: dannyfreeman <danny@dfreeman.email>
Further documentation on syntax trees and nodes
---
doc/design.md | 11 ++++++++++-
1 file changed, 10 insertions(+), 1 deletion(-)
diff --git a/doc/design.md b/doc/design.md
index 99bf6d68da..7fcab67764 100644
--- a/doc/design.md
+++ b/doc/design.md
@@ -6,6 +6,9 @@ Clojure-ts-mode is based on the tree-sitter-clojure grammar.
If you want to contribute to clojure-ts-mode, it is recommend that you
familiarize yourself with how tree-sitter works.
The official documentation is a great place to start:
https://tree-sitter.github.io/tree-sitter/
+These guides for Emacs tree-sitter development are also useful
+- https://casouri.github.io/note/2023/tree-sitter-starter-guide/index.html
+- `Developing major modes with tree-sitter` (From the Emacs 29+ Manual, `C-h
i`, search for `tree-sitter`)
In short:
Tree-sitter is a tool that generates parser libraries for programming
languages, and provides an API for interacting with those parsers.
@@ -18,7 +21,12 @@ Emacs can use these generated parsers to provide major modes
with things like sy
- Parser: A dynamic library compiled from C source code that is generated by
the tree-sitter tool. A parser reads source code for a particular language and
produces a syntax tree.
- Grammar: The rules that define how a parser will create the syntax tree for
a language. The grammar is written in javascript. Tree-sitter tooling consumes
the grammar as input and outputs C source (which can be compiled into a parser)
- Syntax Tree: a tree data structure comprised of syntax nodes that represents
some source code text.
+ - Concrete Syntax Tree: Syntax trees that contain nodes for every token in
the source code, including things likes brackets and parentheses. Tree-sitter
creates Concrete Syntax Trees.
+ - Abstract Syntax Tree: A syntax tree with less important details removed.
An AST may contain a node for a list, but not individual parentheses.
Tree-sitter does not create Abstract Syntax Trees.
- Syntax Node: A node in a syntax tree. It represents some subset of a source
code text. Each node has a type, defined by the grammar used to produce it.
Some common node types represent language constructs like strings, integers,
operators.
+ - Named Syntax Node: A node that can be identified by a name given to it
in the tree-sitter Grammar. In clojure-ts-mode, `list_lit` is a named node for
lists.
+ - Anonymous Syntax Node: A node that cannot be identified by a name. In
the Grammar these are identified by simple strings, not by complex Grammar
rules. In clojure-ts-mode, `"("` and `")"` are anonymous nodes.n
+- Font Locking: What Emacs calls "Syntax Highlighting".
## tree-sitter-clojure
@@ -123,7 +131,8 @@ And the primary downside: Semantics must be
(re)-implemented in tools that consu
#### Further Reading
-https://github.com/sogaiu/tree-sitter-clojure/blob/master/doc/scope.md
+- https://github.com/sogaiu/tree-sitter-clojure/blob/master/doc/scope.md
+-
https://tree-sitter.github.io/tree-sitter/using-parsers#named-vs-anonymous-nodes
## Syntax Highlighting
