*nvim-treesitter-textobjects*  Syntax aware |text-objects|, select, move, swap, and peek support.

                                       Type |gO| to see the table of contents.

==============================================================================
MODULES					 *nvim-treesitter-textobjects-modules*

Available modules for |nvim-treesitter|.

------------------------------------------------------------------------------
				  *nvim-treesitter-text-objects-select-submod*
Text object selection~

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

Query files: `textobjects.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.
- lookahead: `true` or `false`, whether or not to look ahead for the textobject
- keymaps: map of keymaps to a tree-sitter query
  (`(function_definition) @function`) or capture group (`@function.inner`).
- selection_modes: map of capture group to `v`(charwise), `V`(linewise), or `<c-v>`(blockwise),
  choose a selection mode per capture, default is `v`(charwise).
- include_surrounding_whitespace: `true` or `false`, when `true` textobjects
  are extended to include preceding or succeeding whitespace, defaults is
  `false`. Can also be a function which gets passed a table with the keys
  `query_string` (`@function.inner`) and `selection_mode` (`v`) and returns
  `true` of `false`.

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

	-- Automatically jump forward to textobjects, 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",
	  -- you can optionally set descriptions to the mappings (used in the desc parameter of nvim_buf_set_keymap
	  ["ic"] = { query = "@class.inner", desc = "Select inner part of a class region" },
	},
	-- You can choose the select mode (default is charwise 'v')
	selection_modes = {
	  ['@parameter.outer'] = 'v', -- charwise
	  ['@function.outer'] = 'V', -- linewise
	  ['@class.outer'] = '<c-v>', -- blockwise
	},
	-- If you set this to `true` (default is `false`) then any textobject is
	-- extended to include preceding or succeeding whitespace. Succeeding
	-- whitespace has priority in order to act similarly to eg the built-in
	-- `ap`. Can also be a function (see above).
	include_surrounding_whitespace = true,
      },
    },
  }
  EOF
<

------------------------------------------------------------------------------
				    *nvim-treesitter-text-objects-swap-submod*
Swap text objects~

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

Query files: `textobjects.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.
- swap_next: map of keymaps to a list of tree-sitter capture groups (`{@parameter.inner}`). Capture groups that come earlier in the list are preferred.
- swap_previous: same as swap_next, but it will swap with the previous text
  object.

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

------------------------------------------------------------------------------
				    *nvim-treesitter-text-objects-move-submod*
Go to next/previous text object~

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.

Query files: `textobjects.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.
- set_jumps: whether to set jumps in the jumplist
- goto_next_start: map of keymaps to a list of tree-sitter capture groups (`{@function.outer, @class.outer}`).
  The one that starts closest to the cursor will be chosen, preferring row-proximity to column-proximity.
- goto_next_end: same as goto_next_start, but it jumps to the start of
  the text object.
- goto_previous_start: same as goto_next_start, but it jumps to the previous
  text object.
- goto_previous_end: same as goto_next_end, but it jumps to the previous
  text object.

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

------------------------------------------------------------------------------
			      *nvim-treesitter-textobjects-lsp_interop-submod*
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 https://github.com/neovim/neovim/pull/12720
  or its successor is merged)
Supported options:
- enable: `true` or `false`.
- border: 'none' (default), 'single', 'double', 'rounded', 'solid', 'shadow'.
  Deprecated. Should be placed in `floating_preview_opts` like so: `floating_preview_opts = {border = 'rounded'}`.
- floating_preview_opts: {} (default). Options to pass to `vim.lsp.util.open_floating_preview`. For example, `maximum_height`.
>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    textobjects = {
      lsp_interop = {
        enable = true,
        border = "none",
        floating_preview_opts = {},
        peek_definition_code = {
          ["<leader>df"] = "@function.outer",
          ["<leader>dF"] = "@class.outer",
        },
      },
    },
  }
  EOF
<
------------------------------------------------------------------------------
				       *nvim-treesitter-text-objects-override*
Overrriding or extending text objects~


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:
>
  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
<
Where '@custom-capture' can be defined in a scheme file
>
  ```scm
  -- after/queries/python/textobjects.scm
  (function_definition) @custom-capture
  ```
<

vim:tw=78:ts=8:expandtab:noet:ft=help:norl:
