treesitter-context

Introduction

There are three minor modes defined in this package.

• treesitter-context-mode

  This minor mode will show context in a child frame.

  Here context means which class/method/function you are looking at, which loops/conditions are surrounding the cursor, so you can have an overview of where you are.

• treesitter-context-focus-mode

  This minor mode will dim surrounding text of current syntax block.

• treesitter-context-fold-mode

  This minor mode supports folding code blocks.

  You may find yafolding useful, since it’s more general than treesitter-context-fold-mode.

In file treesitter-context-expand.el, it also defines an expand-region function, treesitter-context-mark-bigger-node, a treesit-based expand function.

You need Emacs 29.1 to run it, as treesitter-context use the builtin treesit.

It depends on posframe to show context.

Languages supported

• c
• cpp
• go
• java
• javascript
• json
• python
• rust
• typescript
• yaml
• toml

NOTE: Does not support folding in yaml and json buffers.

How to install and use

Clone this repo, add the path to `load-path`, then enable `treesitter-context-mode` and/or `treesitter-context-focus-mode` in a buffer or add it to the <lang>-ts-mode-hook, where <lang> is a language this package supports. Like

(add-hook 'rust-ts-mode-hook #'treesitter-context-mode)
(add-hook 'rust-ts-mode-hook #'treesitter-context-focus-mode)

Be sure your Emacs version is 29.1 and above (built with tree-sitter support), and install the tree-sitter parsers you need.

Customization

Variable	Default	Description
treesitter-context-idle-time	2.0	How many seconds to wait before refreshing context information
treesitter-context-show-context-always	t	Show context all the time if t, if nil only show context when outmost parent is invisible
treesitter-context-show-line-number	t	Show line number in the child frame
treesitter-context-frame-autohide-timeout	15	Child frame will hide itself after this many seconds
treesitter-context-frame-indent-offset	4	Indent offset in the child frame
treesitter-context-frame-min-width	60	Minimal width of the child frame
treesitter-context-frame-min-height	5	Minimal height of the child frame
treesitter-context-frame-font	nil	Font of the child frame
treesitter-context-java-show-modifiers	nil	If t, show modifiers of the classes/methods
treesitter-context-background-color	“#000000”	Background color of the context frame
treesitter-context-border-color	“#FFFFFF”	Context frame border color
treesitter-context-border-width	1	Context frame border width
treesitter-context-fold-ellipsis-content	“…”	Text to show in place of a folded block.
treesitter-context-fold-show-fringe-marks	t	Whether to show fold markers in the fringe or not.
treesitter-context-fold-unfold-when-fold-region	nil	When folding a region, whether unfold old foldings in this region or not.
treesitter-context-frame-font-fraction	nil	Fraction of font height in the child frame. Prefer this to `treesitter-context-frame-font’.

Commands

treesitter-context-fold-hide

Fold current code block.

treesitter-context-fold-show

Unfold current code block.

treesitter-context-fold-toggle

Toggle folding status of current code block.

CAUTION

• For some languages, such as go and java, treesitter-context cannot capture the “else” branch of the “if statement”, so if the cursor in an “else” block, treesitter-context will display the “if” branch information. Fixed now.

How to contribute

If you want to add support for another language <lang>, here is a guide.

1. Create a file, treesitter-context-<lang>.el. All of the following is in this file.
2. Add `treesitter-context–<lang>-node-types`, this is the node types you are interested.
3. Add `treesitter-context–<lang>-query`, the query patterns used to query nodes. See more information from Emacs Manual.
4. Implement `treesitter-context-collect-contexts`, current mojar mode specific method to collect context.
5. (Optional) Implement `treesitter-context-indent-context`. At the moment, this function is used to indent else , make sure the else has the same indentation with the previous if.
6. Add `treesitter-context–<lang>-focus-node-types`, this is the node types that should be focused.
7. Implement `treesitter-context-focus-bounds`, current mojar mode specific method to get focus bounds.
8. Add `treesitter-context–<lang>-fold-node-types`, this is the node types that should be folded.
9. Implement `treesitter-context-fold-get-region`, current mojar mode specific method to get the region to be folded.
10. `(add-to-list ‘treesitter-context–supported-mode ‘<lang>-ts-mode t)`, so treesitter-context knows that this language is supported.

License

GPLv3

Some images