/nvim-treesitter-textobjects

Primary LanguageSchemeApache License 2.0Apache-2.0

nvim-treesitter-textobjects

Syntax aware text-objects, select, move, swap, and peek support.

Warning: tree-sitter and nvim-treesitter are an experimental feature of nightly versions of Neovim. Please consider the experience with this plug-in as experimental until tree-sitter support in Neovim is stable! We recommend using the nightly builds of Neovim or the latest stable version.

Installation

You can install nvim-treesitter-textobjects with your favorite package manager, or using the default pack feature of Neovim!

Using a package manager

If you are using vim-plug, put this in your init.vim file:

Plug 'nvim-treesitter/nvim-treesitter', {'do': ':TSUpdate'}
Plug 'nvim-treesitter/nvim-treesitter-textobjects'

Text objects: select

Define your own text objects mappings similar to ip (inner paragraph) and ap (a paragraph).

lua <<EOF
require'nvim-treesitter.configs'.setup {
  textobjects = {
    select = {
      enable = true,

      -- Automatically jump forward to textobj, similar to targets.vim
      lookahead = true,

      keymaps = {
        -- You can use the capture groups defined in textobjects.scm
        ["af"] = "@function.outer",
        ["if"] = "@function.inner",
        ["ac"] = "@class.outer",
        ["ic"] = "@class.inner",
      },
    },
  },
}
EOF

Text objects: swap

Define your own mappings to swap the node under the cursor with the next or previous one, like function parameters or arguments.

lua <<EOF
require'nvim-treesitter.configs'.setup {
  textobjects = {
    swap = {
      enable = true,
      swap_next = {
        ["<leader>a"] = "@parameter.inner",
      },
      swap_previous = {
        ["<leader>A"] = "@parameter.inner",
      },
    },
  },
}
EOF

Text objects: move

Define your own mappings to jump to the next or previous text object. This is similar to ]m, [m, ]M, [M Neovim's mappings to jump to the next or previous function.

lua <<EOF
require'nvim-treesitter.configs'.setup {
  textobjects = {
    move = {
      enable = true,
      set_jumps = true, -- whether to set jumps in the jumplist
      goto_next_start = {
        ["]m"] = "@function.outer",
        ["]]"] = "@class.outer",
      },
      goto_next_end = {
        ["]M"] = "@function.outer",
        ["]["] = "@class.outer",
      },
      goto_previous_start = {
        ["[m"] = "@function.outer",
        ["[["] = "@class.outer",
      },
      goto_previous_end = {
        ["[M"] = "@function.outer",
        ["[]"] = "@class.outer",
      },
    },
  },
}
EOF

Textobjects: LSP interop

  • peek_definition_code: show textobject surrounding definition as determined using Neovim's built-in LSP in a floating window. Press the shortcut twice to enter the floating window (when neovim/neovim#12720 or its successor is merged)
lua <<EOF
require'nvim-treesitter.configs'.setup {
  textobjects = {
    lsp_interop = {
      enable = true,
      border = 'none',
      peek_definition_code = {
        ["<leader>df"] = "@function.outer",
        ["<leader>dF"] = "@class.outer",
      },
    },
  },
}
EOF

Overriding or extending textobjects

Textobjects are defined in the textobjects.scm files. You can extend or override those files by following the instructions at https://github.com/nvim-treesitter/nvim-treesitter#adding-queries. You can also use a custom capture for your own textobjects, and use it in any of the textobject modules, for example:

-- after/queries/python/textobjects.scm

(function_definition) @custom-capture
lua <<EOF
require'nvim-treesitter.configs'.setup {
  textobjects = {
    select = {
      enable = true,
      keymaps = {
        -- Your custom capture.
        ["aF"] = "@custom-capture",

        -- Built-in captures.
        ["af"] = "@function.outer",
        ["if"] = "@function.inner",
      },
    },
  },
}
EOF

Built-in Textobjects

  1. @block.inner
  2. @block.outer
  3. @call.inner
  4. @call.outer
  5. @class.inner
  6. @class.outer
  7. @comment.outer
  8. @conditional.inner
  9. @conditional.outer
  10. @frame.inner
  11. @frame.outer
  12. @function.inner
  13. @function.outer
  14. @loop.inner
  15. @loop.outer
  16. @parameter.inner
  17. @parameter.outer
  18. @scopename.inner
  19. @statement.outer
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
astro
bash 🟩 🟩 🟩 🟩 🟩 🟩 🟩
beancount
bibtex 🟩 🟩
c 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
c_sharp🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
clojure
cmake
comment
commonlisp
cooklang
cpp 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
css
cuda 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
d
dart 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
devicetree
dockerfile
dot
eex
elixir 🟩 🟩 🟩 🟩 🟩
elm 🟩 🟩 🟩 🟩 🟩 🟩
elvish
erlang
fennel 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
fish 🟩 🟩 🟩 🟩 🟩 🟩
foam 🟩 🟩 🟩 🟩
fortran
fusion
Godot (gdscript)
gleam
Glimmer and Ember
glsl 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
go🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
Godot Resources (gdresource)
gomod
gowork
graphql
hack
haskell
hcl🟩 🟩 🟩 🟩
heex
help
hjson
hocon
html 🟩 🟩 🟩 🟩
http
java 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
javascript🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
jsdoc
json
json5
JSON with comments
julia 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
kotlin
lalrpop
latex 🟩 🟩 🟩 🟩
ledger
llvm
lua🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
make
markdown🟩 🟩 🟩 🟩
ninja
nix
norg
ocaml
ocaml_interface
ocamllex
pascal
perl
php🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
phpdoc
pioasm
prisma
pug
python🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
ql 🟩 🟩 🟩 🟩 🟩
Tree-sitter query language
r 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
rasi
regex
rego
rst🟩 🟩 🟩 🟩 🟩 🟩 🟩
ruby🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
rust🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
scala 🟩 🟩 🟩 🟩 🟩 🟩 🟩
scheme
scss
slint
solidity
sparql
supercollider🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
surface
svelte
swift
teal
tlaplus
todotxt
toml
tsx🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
turtle
typescript🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
vala
verilog 🟩 🟩 🟩 🟩 🟩 🟩
vim🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩
vue 🟩 🟩 🟩
wgsl
yaml
yang
zig🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩 🟩