summaryrefslogtreecommitdiff
path: root/book/src/guides/textobject.md
diff options
context:
space:
mode:
authorGokul Soumya2021-10-23 02:41:19 +0000
committerGitHub2021-10-23 02:41:19 +0000
commit4ee92cad19cc94f0751f91fa9391d1899353d740 (patch)
tree794be048905f5d5026ba1968dc0152d12473c024 /book/src/guides/textobject.md
parentc5298caa752dee136ab1a21dae27a702a00d8eea (diff)
Add treesitter textobjects (#728)
* Add treesitter textobject queries Only for Go, Python and Rust for now. * Add tree-sitter textobjects Only has functions and class objects as of now. * Fix tests * Add docs for tree-sitter textobjects * Add guide for creating new textobject queries * Add parameter textobject Only parameter.inside is implemented now, parameter.around will probably require custom predicates akin to nvim' `make-range` since we want to select a trailing comma too (a comma will be an anonymous node and matching against them doesn't work similar to named nodes) * Simplify TextObject cell init
Diffstat (limited to 'book/src/guides/textobject.md')
-rw-r--r--book/src/guides/textobject.md30
1 files changed, 30 insertions, 0 deletions
diff --git a/book/src/guides/textobject.md b/book/src/guides/textobject.md
new file mode 100644
index 00000000..50b3b574
--- /dev/null
+++ b/book/src/guides/textobject.md
@@ -0,0 +1,30 @@
+# Adding Textobject Queries
+
+Textobjects that are language specific ([like functions, classes, etc][textobjects])
+require an accompanying tree-sitter grammar and a `textobjects.scm` query file
+to work properly. Tree-sitter allows us to query the source code syntax tree
+and capture specific parts of it. The queries are written in a lisp dialect.
+More information on how to write queries can be found in the [official tree-sitter
+documentation](tree-sitter-queries).
+
+Query files should be placed in `runtime/queries/{language}/textobjects.scm`
+when contributing. Note that to test the query files locally you should put
+them under your local runtime directory (`~/.config/helix/runtime` on Linux
+for example).
+
+The following [captures][tree-sitter-captures] are recognized:
+
+| Capture Name |
+| --- |
+| `function.inside` |
+| `function.around` |
+| `class.inside` |
+| `class.around` |
+| `parameter.inside` |
+
+[Example query files][textobject-examples] can be found in the helix GitHub repository.
+
+[textobjects]: ../usage.md#textobjects
+[tree-sitter-queries]: https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax
+[tree-sitter-captures]: https://tree-sitter.github.io/tree-sitter/using-parsers#capturing-nodes
+[textobject-examples]: https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l=