meow-tree-sitter

meow-tree-sitter is a package that integrates the treesit library in Emacs 29+ 🌳 with Meow’s motions 🐱. Lots of functionality is ported from evil-textobj-tree-sitter.

Contents

• Status 📆
• Requirements ⚠️
• Installation 💾
• Quickstart 💨
• Configuration 🔧
  • Options ⚙️
  • Custom Keybinds ⌨️
  • Custom Queries ❓
• License 📜

Status 📆

This project is in a pretty stable state, and, for the foreseeable future, is feature-complete. As always, issues and pull requests are appreciated ❤️.

Requirements ⚠️

• Emacs 29+ ✍️ with treesit support 🌳
• Meow 🐱

Currently, the package only supports the native treesit library in Emacs 29+. Personally, I have no interest in supporting elisp-tree-sitter since I don’t use it, but pull requests are welcome 🙃.

Installation 💾

This package is now on MELPA 🎉. Installation should be as simple as any other package if MELPA is configured and set up. See MELPA’s “Getting started” if you do not have MELPA installed.

Alternatively, you can install the package manually as usual: clone the repository, add the location to load-path, and then (require 'meow-tree-sitter). If you have trouble with the queries/ directory (or want to use a custom queries folder), then customize the value of meow-tree-sitter-queries-dir.

Quickstart 💨

(add-to-list 'load-path "/path/to/meow-tree-sitter")
(require 'meow-tree-sitter)
(meow-tree-sitter-register-defaults)

Tree-sitter powered motions should now be accessible through Meow’s “thing” functionality, namely meow-bounds-of-thing and meow-inner-of-thing (bound to period and comma by default).

Configuration 🔧

meow-tree-sitter-register-defaults is the easiest way to get started, and will set up the default keybinds. Currently, this adds the following keys to Meow’s “things”:

a

class

f

function

t

test

y

entry

,

parameter

/

comment

Note that if any of these keys are currently being used, they will be overridden.

Options ⚙️

Evaluate (customize-group 'meow-tree-sitter) in Emacs to see these options in the Customize interface.

meow-tree-sitter-can-expand

Whether repeating a motion will expand an existing selection. Mainly useful for queries for multiple types of nodes. Defaults to t.

meow-tree-sitter-can-jump-forward

Whether to jump forward if there is no matching node within the current point/region. Can also be an integer to only jump forward if the next node is that many characters away. Defaults to t.

meow-tree-sitter-extra-queries

An alist of extra queries to use by default. Entries in this list override the default set of queries. Useful to support languages that don’t have queries by default. Defaults to nil.

meow-tree-sitter-major-mode-language-alist

An alist mapping major mode name (sans -ts-mode and -mode suffix) to tree-sitter language names. Only needed for languages that don’t match up by default.

meow-tree-sitter-queries-dir

The directory to look for the default set of queries that come with this package. Defaults to the queries/ subdirectory where the package file is located.

Custom Keybinds ⌨️

To register custom keybinds, use meow-tree-sitter-register-thing. The second argument should be the “type” of object to select, which is the first part of the name of a capture; see the queries for the default capture names.

(meow-tree-sitter-register-thing ?F "function")
(meow-tree-sitter-register-thing ?P "parameter")

Pass a list to query for multiple different types of objects.

(meow-tree-sitter-register-thing ?B '("function" "class"))

Custom Queries ❓

Custom queries must use the treesit query syntax, which is described here or within Emacs by evaluating (info "(elisp)Pattern Matching"). To support both “outer” and “inner” bounds of things in Meow, each query should have two captures: TYPE.inside and TYPE.around where TYPE is the “name” of the thing (the second parameter to meow-tree-sitter-register-thing).

To register a custom query, pass an alist to meow-tree-sitter-register-thing that maps language strings to queries. The query can be of any form that treesit-query-capture accepts.

(meow-tree-sitter-register-thing
 ?f "function"
 '(("python" . ((function_definition
                 body: (block) :? @function.inside) @function.around))
   ("rust" . "(function_item
                body: (_) @function.inside) @function.around")))

License 📜

Code in this repository is licensed under the GPLv3. The queries are taken from the helix project, which is licensed under the Mozilla Public License 2.0.