branch: elpa/treesit-fold
commit dcd5b9fe5c2cb72261ff6c714beb8d0198b8522b
Merge: 3d1be710a6 551bfeb13a
Author: Jen-Chieh Shen <[email protected]>
Commit: GitHub <[email protected]>
Merge pull request #9 from jcs-elpa/docs/tutorial
docs(README): order contribute section
---
README.md | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 129 insertions(+), 11 deletions(-)
diff --git a/README.md b/README.md
index 1e2c25c76c..b78563e615 100644
--- a/README.md
+++ b/README.md
@@ -22,9 +22,15 @@ to provide code folding base on the tree-sitter syntax tree.
- [🔍 Methods 2. Manual](#🔍-methods-2-manual)
- [📇 Commands](#📇-commands)
- [🔨 Supported languages](#🔨-supported-languages)
- - [🔰 Contribution](#🔰-contribution)
- [⚖️ Indicators Mode](#⚖️-indicators-mode)
- [📝 Summary](#📝-summary)
+ - [🔰 Contribute](#🔰-contribute)
+ - [❓ How to create a folding
parser?](#❓-how-to-create-a-folding-parser)
+ - [🔍 Where can I look for tree-sitter
node?](#🔍-where-can-i-look-for-tree-sitter-node)
+ - [🔍 How do I create the function for the corresponding
node?](#🔍-how-do-i-create-the-function-for-the-corresponding-node)
+ - [🔍 Register to folding parsers
alist!](#🔍-register-to-folding-parsers-alist)
+ - [❓ How to create a summary
parser?](#❓-how-to-create-a-summary-parser)
+ - [🔍 Register to summary parsers
alist!](#🔍-register-to-summary-parsers-alist)
<!-- markdown-toc end -->
@@ -84,16 +90,6 @@ then in Emacs:
* Emacs Lisp
* XML (upstream)
-## 🔰 Contribute
-
-[](http://makeapullrequest.com)
-[](https://github.com/bbatsov/emacs-lisp-style-guide)
-
-Enable `tree-sitter-mode` first, then `tree-sitter-query-builder` is useful to
test
-out queries that determine what syntax nodes should be foldable and how to fold
-them.
[emacs-tree-sitter](https://ubolonton.github.io/emacs-tree-sitter/syntax-highlighting/queries/)
-has an excellent documentation on how to write `tree-sitter` queries.
-
## ⚖️ Indicators Mode
<p align="center">
@@ -171,3 +167,125 @@ To change summary format: (Default is `" <S> %s "`)
```el
(setq ts-fold-summary-format " <S> %s ")
```
+
+## 🔰 Contribute
+
+[](http://makeapullrequest.com)
+[](https://github.com/bbatsov/emacs-lisp-style-guide)
+
+Enable `tree-sitter-mode` first, then `tree-sitter-query-builder` is useful to
test
+out queries that determine what syntax nodes should be foldable and how to fold
+them.
[emacs-tree-sitter](https://ubolonton.github.io/emacs-tree-sitter/syntax-highlighting/queries/)
+has an excellent documentation on how to write `tree-sitter` queries.
+
+### ❓ How to create a folding parser?
+
+Parsers are ruled in the `ts-fold-parsers.el` file. Parser function follow
+with the prefix `ts-fold-parsers-` plus the `language name`. For example, if
+you want to create a parser for `C` programming language. It should be named
+`ts-fold-parsers-c`.
+
+The parser is consist of an association list (alist), each item is consist
+of tree-sitter `node` and a function that returns the folding range. See
+the following example:
+
+```elisp
+(defun ts-fold-parsers-csharp ()
+ "Rule sets for C#."
+ '((block . ts-fold-range-seq)
+ ...))
+```
+
+`block` is the tree-sitter node, and `ts-fold-range-seq` is the function
+that will return the folding range.
+
+Let's move into details,
+
+#### 🔍 Where can I look for tree-sitter node?
+
+To look for the correct node, you should look at the
`tree-sitter-[lang]/grammar.js`
+implementation. In the above example, `block` node is defined in the
+[tree-sitter-c-sharp](https://github.com/tree-sitter/tree-sitter-c-sharp)'s
+`grammar.js` file.
+
+> ⚠️ Warning
+>
+> Make sure you look into the correct repository. Repositories are managed
+> under
[tree-sitter-langs](https://github.com/emacs-tree-sitter/tree-sitter-langs)'s
+> using the git submodule. Some tree-sitter module aren't using the latest
version!
+
+#### 🔍 How do I create the function for the corresponding node?
+
+Function takes 2 arguments, `node` and `offset`.
+
+* `node` - the targeting tree-sitter node; in this example, `block` will be the
+targeting node.
+* `offset` - (optiona) a cons consist of two integers. This is handy when you
have
+a similar rule with little of positioning adjustment.
+
+`tree-sitter-[lang]` parsers are generally integrated with different authors,
+hence their naming and ruling are slightly different (+1/-1 position).
+
+Let's look at function `ts-fold-range-seq` for better understanding,
+
+```elisp
+(defun ts-fold-range-seq (node offset)
+ "..."
+ (let ((beg (1+ (tsc-node-start-position node))) ; node beginning position
(from Rust layer)
+ (end (1- (tsc-node-end-position node)))) ; node end position (from
Rust layer)
+ (ts-fold--cons-add (cons beg end) offset))) ; return fold range
+```
+
+#### 🔍 Register to folding parsers alist!
+
+Don't forget to add your parser to the entry alist with the corresponding
+`major-mode`.
+
+```elisp
+(defcustom ts-fold-range-alist
+ `((agda-mode . ,(ts-fold-parsers-agda))
+ (sh-mode . ,(ts-fold-parsers-bash))
+ (c-mode . ,(ts-fold-parsers-c))
+ (c++-mode . ,(ts-fold-parsers-c++))
+ ...
+```
+
+This variable is defined in package main file, `ts-fold.el`.
+
+### ❓ How to create a summary parser?
+
+`ts-fold-summary.el` module is use to extract and display a short description
+from the comment/docstring.
+
+To create summary parser, you would just have to create a function that could
+remove comment syntax correctly, then register it to
`ts-fold-summary-parsers-alist`
+defined in `ts-fold-summary.el`. The display and shortening will be handled
+by the module itself.
+
+Function should follow with prefix `ts-fold-summary-` and the `style name`.
+For example, to create summary parser for Javadoc style, then it should be
+named `ts-fold-summary-javadoc`.
+
+Let's see the implementation,
+
+```elisp
+(defun ts-fold-summary-javadoc (doc-str)
+ "..."
+ (ts-fold-summary--generic doc-str "*")) ; strip all asterisk
+```
+
+The above summary parser for Javadoc simply remove `*` from any given point.
+
+#### 🔍 Register to summary parsers alist!
+
+Like folding parsers, you should register your summary parser to the entry
alist
+with the corresponding `major-mode`.
+
+```elisp
+(defcustom ts-fold-summary-parsers-alist
+ `((actionscript-mode . ts-fold-summary-javadoc)
+ (bat-mode . ts-fold-summary-batch)
+ (c-mode . ts-fold-summary-c)
+ (c++-mode . ts-fold-summary-c)
+ ...
+```
