Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/skissue/meow-tree-sitter

Tree-sitter powered :deciduous_tree: motions for Meow :cat:
https://github.com/skissue/meow-tree-sitter

emacs emacs-lisp emacs-package keybindings modal-editing tree-sitter

Last synced: 4 months ago
JSON representation

Tree-sitter powered :deciduous_tree: motions for Meow :cat:

Awesome Lists containing this project

README 

        
#+title: meow-tree-sitter

#+author: skissue



[[https://melpa.org/#/meow-tree-sitter][file:https://melpa.org/packages/meow-tree-sitter-badge.svg]]

[[https://stable.melpa.org/#/meow-tree-sitter][file:https://stable.melpa.org/packages/meow-tree-sitter-badge.svg]]



=meow-tree-sitter= is a package that integrates the ~treesit~ library in Emacs 29+ 🌳 with [[https://github.com/meow-edit/meow][Meow]]'s motions 🐱. Lots of functionality is ported from [[https://github.com/meain/evil-textobj-tree-sitter][evil-textobj-tree-sitter]].



* Contents

:PROPERTIES:

:TOC:      :include all :depth 3 :force (nothing) :ignore (this) :local (nothing)

:END:

:CONTENTS:

- [[#status-][Status 📆]]

- [[#requirements-️][Requirements ⚠️]]

- [[#installation-][Installation 💾]]

- [[#quickstart-][Quickstart 💨]]

- [[#configuration-][Configuration 🔧]]

  - [[#options-️][Options ⚙️]]

  - [[#custom-keybinds-️][Custom Keybinds ⌨️]]

  - [[#custom-queries-][Custom Queries ❓]]

- [[#license-][License 📜]]

:END:



* 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 🌳

+ [[https://github.com/meow-edit/meow][Meow]] 🐱



Currently, the package only supports the native ~treesit~ library in Emacs 29+. Personally, I have no interest in supporting [[https://github.com/emacs-tree-sitter/elisp-tree-sitter][elisp-tree-sitter]] since I don't use it, but pull requests are welcome 🙃.



* Installation 💾

This package is [[https://melpa.org/#/meow-tree-sitter][now on MELPA]] 🎉. Installation should be as simple as any other package if MELPA is configured and set up. See [[https://melpa.org/#/getting-started][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 💨

#+begin_src elisp

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

(require 'meow-tree-sitter)

(meow-tree-sitter-register-defaults)

#+end_src



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



** 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 [[file:queries/][queries]] for the default capture names.

#+begin_src elisp

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

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

#+end_src



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

#+begin_src elisp

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

#+end_src



** Custom Queries ❓

Custom queries must use the ~treesit~ query syntax, which is described [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Pattern-Matching.html][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.

#+begin_src elisp

(meow-tree-sitter-register-thing

 ?f "function"

 '(("python" . ((function_definition

                 body: (block) :? @function.inside) @function.around))

   ("rust" . "(function_item

                body: (_) @function.inside) @function.around")))

#+end_src



* License 📜

Code in this repository is licensed under the GPLv3. The queries are taken from the [[https://github.com/helix-editor/helix/tree/master/runtime/queries][helix]] project, which is licensed under the Mozilla Public License 2.0.