NonGNU-devel ELPA - treesit-fold

Now that you know what kinds of folds are easily available in treesit-fold, you can go ahead and add new fold definitions to treesit-fold-range-alist and be good to go!

❔ Example

Let's look at a quick example of adding a new folding definition. Let's say you want to add folding to go-mode's field_declaration_list. The folding definition that is needed will be '(field_declaration_list . treesit-fold-range-seq). To add this to the treesit-fold-range-alist, you can do something like the following.

emacs-lisp (push '(field_declaration_list . treesit-fold-range-seq) (alist-get 'go-mode treesit-fold-range-alist))

Now the new fold definition should be usable by treesit-fold!

↔ Offset

With the functions listed above you'll be able to define most folding behavior that you'll want for most languages. However, sometimes you'll have a language where the delimiter is a word instead of a single character bracket and you want to offset your fold by a certain amount to accommodate it. That's where offsets come in. When adding a fold definition to a a language's fold alist, you can either provide the folding function directly as you've seen so far:

elisp '(block . treesit-fold-range-seq)

Or you can provide the folding function with an offset:

elisp '(block . (treesit-fold-range-seq 1 -3))

When a range is provided, it provides extra room on the ends of a fold. The way this works is most easily shown using an example. Lets say we want to write a fold for bash's for...do...done construct to look something like this:

```sh for i in 1 2 3 4 5 do echo "Welcome $i times" done

|

| '(do_group . )

V

for i in 1 2 3 4 5 do...done ```

The do...done block is represented in tree-sitter as the node named do_group. However, if we just use '(do_group . treesit-fold-range-seq), then we'll get results like the following:

emacs-lisp for i in 1 2 3 4 5 d...e

which is hard to read. Instead, we can use the definition '(do_group . (treesit-fold-range-seq 1 -3)) to offset the fold a bit to get our desired result!

🔍 Writing new fold functions

If the built in functions don't fit your needs, you can write your own fold parser! Folding functions take two parameters:

• node - the targeted tree-sitter node; in this example, block will be the targeting node.
• offset - (optional) a cons of two integers. This is handy when you have a similar rule with little of positioning adjustment.

Then the function needs to return a position range for the fold overlay in the form '(start-of-fold . end-of-fold). If nil is returned instead of a range, then no fold is created. This can be useful if you want to add extra conditional logic onto your fold.

As an example of a folding function, take a look at the definition of the basic treesit-fold-range-seq.

elisp (defun treesit-fold-range-seq (node offset) "..." (let ((beg (1+ (treesit-node-start node))) ; node beginning position (end (1- (treesit-node-end node)))) ; node end position (treesit-fold--cons-add (cons beg end) offset))) ; return fold range

🔌 Plugins

treesit-fold comes with a couple of useful little additions that can be used or turned off as desired.

⚖ Indicators Mode

This plugin adds interactive visual markers in the gutter that show where folds can be made. They can be clicked on to fold or unfold given nodes.

💾 Installation

treesit-fold-indicator-mode is loaded when treesit-fold-mode is and the functionality should be auto-loaded in, however if that's not working then you may want to explicitly declare the package in in your config.

• use-package

  elisp (use-package treesit-fold-indicators :straight (treesit-fold-indicators :type git :host github :repo "emacs-tree-sitter/treesit-fold"))

• elisp (add-to-list 'load-path "/path/to/lib") (require treesit-fold)

  or

  elisp (use-package treesit-fold-indicators :load-path "/path/to/lib")

🖥 Usage

You can then enable this manually by doing either of the following:

``` M-x treesit-fold-indicators-mode

M-x global-treesit-fold-indicators-mode ```

Please note that turning on treesit-fold-indicators-mode automatically turns on treesit-fold-mode as well. Though, turning off treesit-fold-indicators-mode does not turn off treesit-fold-mode

• To enable this automatically whenever a buffer has a tree-sitter parser, use the global indicator mode:

  elisp (global-treesit-fold-indicators-mode 1)

  Else, you can add a hook directly.

  elisp (add-hook 'c-ts-mode-hook #'treesit-fold-indicators-mode)

• To switch to left/right fringe: (Default is left-fringe)

  elisp (setq treesit-fold-indicators-fringe 'right-fringe)

• To lower/higher the fringe overlay's priority: (Default is 30)

  elisp (setq treesit-fold-indicators-priority 30)

• To apply different faces depending on some conditions: (Default is nil)

  For example, to coordinate line-reminder with this plugin.

  ```elisp (setq treesit-fold-indicators-face-function (lambda (pos &rest _) ;; Return the face of it's function. (line-reminder--get-face (line-number-at-pos pos t))))

  (setq line-reminder-add-line-function (lambda (&rest _) (null (treesit-fold--overlays-in treesit-fold-indicators-window (selected-window) (line-beginning-position) (line-end-position))))) ```

📝 Summary

This plugin automatically extracts summary from the comment/document string, so you can have a nice way to peek at what's inside the fold range.

🖥 Usage

• If you don't want this to happen, do: (Default is t)

  elisp (setq treesit-fold-summary-show nil)

• Summary are truncated by length: (Default is 60)

  elisp (setq treesit-fold-summary-max-length 60)

• The exceeding string are replace by: (Default is "...")

  elisp (setq treesit-fold-summary-exceeded-string "...")

• To change summary format: (Default is " <S> %s ")

  elisp (setq treesit-fold-summary-format " <S> %s ")

📝 Customization

Just like with fold definitions, you can create your own summary definitions. Summary definitions are defined in treesit-fold-summary-parsers-alist and has one summary function per major mode '(java-mode . fold-summary-function). The summary function takes in the doc string which is all the text from a doc node and then returns a string to be displayed in its stead. Unlike with the folding functions, there aren't a set of general summary functions to fall back on. However, there are lots of examples and helper functions present in treesit-fold-summary.el. Let's look at one example here.

emacs-lisp (defun treesit-fold-summary-javadoc (doc-str) "Extract summary from DOC-STR in Javadoc." (treesit-fold-summary--generic doc-str "*")) ;; strip the '*' and returns the first line

As can be seen treesit-fold-summary--generic is a very helpful function since it removes the provided delimiter and returns the first line. often this will be enough.

🌫 Line-Comment folding

This plugin makes line comment into foldable range.

🖥 Usage

M-x treesit-fold-line-comment-mode

🔰 Contribute

Ensure your buffer has a tree-sitter parser first, then treesit-explore-mode is useful to test out queries that determine what syntax nodes should be foldable and how to fold them. Emacs repository and Emacs tree-sitter manual has an excellent documentation on how to write tree-sitter queries.

🔬 Development

To run the test locally, you will need the following tools:

• Eask
• Make (optional)

Install all dependencies and development dependencies:

sh $ eask install-deps --dev

To test the package's installation:

sh $ eask package $ eask install

To test compilation:

sh $ eask compile

🪧 The following steps are optional, but we recommend you follow these lint results!

The built-in checkdoc linter:

sh $ eask lint checkdoc

The standard package linter:

sh $ eask lint package

📝 P.S. For more information, find the Eask manual at https://emacs-eask.github.io/.

❓ How to add a folding parser?

When adding a new folding parser, add the folding definition function to treesit-fold.el itself near where the other range functions live and then add the parser to treesit-fold-parsers.el file. Finally, if you are adding support for a new language, remember to add it to the treesit-fold-range-alist variable.

When creating a new parser, name it treesit-fold-parsers-<language>.

When creating a new folding function, name it treesit-fold-range-<language>-<feature> or something similar.

🔍 Where can I look for tree-sitter node?

Here are some techniques for finding your desired nodes in tree-sitter.

To look for the correct node you have three options:

• look at the tree-sitter-[lang]/grammar.js implementation. In the above example, block node is defined in the tree-sitter-c-sharp's grammar.js file.
• open a file of your language choice (ensure that it has a tree-sitter parser) in emacs and M-x treesit-explore-mode. This will display a buffer with the whole s-expr representing nodes at point from the current file/buffer.
• M-x treesit-inspect-node-at-point in your function to display what your function is seeing.
• use M-x treesit-inspect-mode which diplay in the mode-line the current node at point.

⚠️ Warning

Make sure you look into the correct repository. Some repositories are managed under https://github.com/tree-sitter/[lang].

❓ How to create a summary parser?

treesit-fold-summary.el module is used to extract and display a short description from the comment/docstring.

To create a summary parser, you just have to create a function that could extract comment syntax correctly then register this function to treesit-fold-summary-parsers-alist defined in treesit-fold-summary.el. The display and shortening will be handled by the module itself.

Functions should be named with the prefix treesit-fold-summary- followed by style name. For example, to create a summary parser for Javadoc style, then it should be named treesit-fold-summary-javadoc.

⚜️ License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

See LICENSE for details.