path: root/doc/nvim-treesitter.txt

*nvim-treesitter* 

Minimum version of neovim: nightly

Authors: Yazdani Kiyan <yazdani.kiyan@protonmail.com>, Vigouroux Thomas <tomvig38@gmail.com>

==============================================================================
INTRODUCTION                                       *nvim-treesitter-intro*

nvim-treesitter wraps the neovim treesitter api to provide functionnalities such
as highlighting and incremental selection, and a command to easily install parsers.

==============================================================================
QUICK START                                        *nvim-treesitter-quickstart*

Install the parser for your language

>
  :TSInstall {language}
<

To get a list of supported languages

>
  :TSInstallInfo
<

By default, everything is disabled. To enable support for features, in your `init.vim`:

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    highlight = {
        enable = true,                    -- false will disable the whole extension
        disable = { 'c', 'rust' },        -- list of language that will be disabled
        custom_captures = {               -- mapping of user defined captures to highlight groups
          -- ["foo.bar"] = "Identifier"   -- highlight own capture @foo.bar with highlight group "Identifier", see :h nvim-treesitter-query-extensions
        },            
    },
    incremental_selection = {
        enable = true,
        disable = { 'cpp', 'lua' },
        keymaps = {                       -- mappings for incremental selection (visual mappings)
          init_selection = 'gnn',         -- maps in normal mode to init the node/scope selection
          node_incremental = "grn",       -- increment to the upper named parent
          scope_incremental = "grc",      -- increment to the upper scope (as defined in locals.scm)
          node_decremental = "grm",      -- decrement to the previous node
        }
    },
    refactor = {
      highlight_defintions = {
        enable = true
      },
      smart_rename = {
        enable = true,
        smart_rename = "grr"              -- mapping to rename reference under cursor
      },
      navigation = {
        enable = true,
        goto_definition = "gnd",          -- mapping to go to definition of symbol under cursor
        list_definitions = "gnD"          -- mapping to list all definitions in current file
      }
    },
    textobjects = { -- syntax-aware textobjects
	enable = true,
	disable = {},
	keymaps = {
	    ["iL"] = { -- you can define your own textobjects directly here
		python = "(function_definition) @function",
		cpp = "(function_definition) @function",
		c = "(function_definition) @function",
		java = "(method_declaration) @function"
	    },
	    -- or you use the queries from supported languages with textobjects.scm
	    ["af"] = "@function.outer",
	    ["if"] = "@function.inner",
	    ["aC"] = "@class.outer",
	    ["iC"] = "@class.inner",
	    ["ac"] = "@conditional.outer",
	    ["ic"] = "@conditional.inner",
	    ["ae"] = "@block.outer",
	    ["ie"] = "@block.inner",
	    ["al"] = "@loop.outer",
	    ["il"] = "@loop.inner",
	    ["is"] = "@statement.inner",
	    ["as"] = "@statement.outer",
	    ["ad"] = "@comment.outer",
	    ["am"] = "@call.outer",
	    ["im"] = "@call.inner"
	}
    },
    ensure_installed = 'all' -- one of 'all', 'language', or a list of languages
  }
  EOF
<
==============================================================================
USER QUERY EXTENSIONS                        *nvim-treesitter-query-extensions*

You can add your own query files by placing a query file in vim's runtime path
after `nvim-treesitter` is sourced.  If the language has a built in query file,
that file will be appended to or it will be used (useful for languages not yet
supported).

For example, you can add files to `<vim-config-dir>/after/queries/lua/highlights.scm`
to add more queries to lua highlights.  You can also manually add query paths
to the runtime path by adding this to your vim config `set rtp+='path/to/queries'`.


==============================================================================
COMMANDS                                          *nvim-treesitter-commands*

|:TSInstall| {language} ...                        *:TSInstall*

Install one or more treesitter parsers.
You can use |:TSInstall| `all` to install all parsers.

|:TSInstallInfo|                                   *:TSInstallInfo*

List informations about currently installed parsers

|:TSBufEnable| {module}                            *:TSBufEnable*

Enable {module} on the current buffer.
A list of modules can be found at |:TSModuleInfo|

|:TSBufDisable| {module}                           *:TSBufDisable*

Disable {module} on the current buffer
A list of modules can be found at |:TSModuleInfo|

|:TSBufEnableAll| {module} [{language}]            *:TSBufEnableAll*

Enable {module} for the session
if {language} is specified, enable module for the session only for this
particular language.
A list of modules can be found at |:TSModuleInfo|
A list of languages can be found at |:TSInstallInfo|

|:TSBufDisableAll| {module} [{language}]            *:TSBufDisableAll*

Disable {module} for the session
if {language} is specified, disable module for the session only for this
particular language.
A list of modules can be found at |:TSModuleInfo|
A list of languages can be found at |:TSInstallInfo|

|:TSModuleInfo| [{module}]                          *:TSModuleInfo*

List modules state for the current session.

==============================================================================
UTILS                                               *nvim-treesitter-utils*

Nvim treesitter has some wrapper functions that you can retrieve with:
>
    local ts_utils = require 'nvim-treesitter.ts_utils'
<
Methods

get_node_at_cursor(winnr)                         *ts_utils.get_node_at_cursor*
    winnr will be 0 if nil
    returns the node under the cursor

get_node_text(node, bufnr)                        *ts_utils.get_node_text*
    return the text content of a node

is_parent(dest, source)                           *ts_utils.is_parent*
    determines wether `dest` is a parent of `source` 
    return a boolean

get_named_children(node)                          *ts_utils.get_named_children*
    return a table of named children of `node`

get_next_node(node, allow_switch_parent, allow_next_parent) *ts_utils.get_next_node*
    return the next node within the same parent.
    if no node is found, returns `nil`.
    if `allow_switch_parent` is true, it will allow switching parent
    when the node is the last node
    if `allow_next_parent` is true, it will allow next parent if 
    the node is the last node and the next parent doesn't have children.

get_previous_node(node, allow_switch_parents, allow_prev_parent) *ts_utils.get_previous_node*
    return the previous node within the same parent.
    `allow_switch_parent` and `allow_prev_parent` follow the same rule
    as |ts_utils.get_next_node| but if the node is the first node.

containing_scope(node)                           *ts_utils.containing_scope*
    return the smallest scope containing the node

parent_scope(node, cursor_pos)                   *ts_utils.parent_scope*
    return the parent scope of the current scope that contains the node.
    `cursor_pos` should be `{ row = number, col = number }`

nested_scope(node, cursor_pos)                   *ts_utils.nested_scope*
    return the first scope within current scope that contains the node.
    `cursor_pos` should be `{ row = number, col = number }`

next_scope(node)                                 *ts_utils.next_scope*
    return the neighbour scope of the current node

previous_scope(node)                             *ts_utils.previous_scope*
    return the previous neighbour scope of the current node

==============================================================================
FUNCTIONS                                         *nvim-treesitter-functions*

|nvim_treesitter#statusline(size)|
						*nvim_treesitter#statusline()*

Returns a string describing the current position in the syntax tree. This
could be used as a statusline indicator.
Note: The `size` argument is optionnal. When specified, the string will not be
      longer than `size`.

|nvim_treesitter#foldexpr()|
						  *nvim_treesitter#foldexpr()*

Functions to be used to determine the fold level at a given line number.
To use it: >
  set foldmethod=expr
  set foldexpr=nvim_treesitter#foldexr()
<
Note: This is highly experimental, and folding can break on some types of
      edits. If you encounter such breakage, hiting `zx` should fix folding.
      In any case, feel free to open an issue with the reproducing steps.

==============================================================================
HIGHLIGHTS                                        *nvim-treesitter-highlights*

`TSError`
							          *hl-TSError*
For syntax/parser errors.

You can deactivate highlighting of syntax errors by adding this to your
init.vim: >
  highlight link TSError Normal

`TSPunctDelimiter`
							 *hl-TSPunctDelimiter*
For delimiters ie: `.`

`TSPunctBracket`
							   *hl-TSPunctBracket*
For brackets and parens.

`TSPunctSpecial`
							   *hl-TSPunctSpecial*
For special punctutation that does not fall in the catagories before.

`TSConstant`
							       *hl-TSConstant*
For constants

`TSConstBuiltin`
							   *hl-TSConstBuiltin*
For constant that are built in the language: `nil` in Lua.

`TSConstMacro`
							     *hl-TSConstMacro*
For constants that are defined by macros: `NULL` in C.

`TSString`
								 *hl-TSString*
For strings.

`TSStringRegex`
							    *hl-TSStringRegex*
For regexes.

`TSStringEscape`
							   *hl-TSStringEscape*
For escape characters within a string.

`TSCharacter`
							      *hl-TSCharacter*
For characters.

`TSNumber`
								 *hl-TSNumber*
For integers.

`TSBoolean`
								*hl-TSBoolean*
For booleans.

`TSFloat`
								  *hl-TSFloat*
For floats.

`TSFunction`
							       *hl-TSFunction*
For function (calls and definitions).

`TSFuncBuiltin`
							    *hl-TSFuncBuiltin*
For builtin functions: `table.insert` in Lua.

`TSFuncMacro`
							      *hl-TSFuncMacro*
For macro defined fuctions (calls and definitions): each `macro_rules` in
Rust.

`TSParameter`
							      *hl-TSParameter*
For parameters of a function.

`TSMethod`
								 *hl-TSMethod*
For method calls and definitions.

`TSField`
								  *hl-TSField*
For fields.

`TSProperty`
							       *hl-TSProperty*
Same as `TSField`.

`TSConstructor`
							    *hl-TSConstructor*
For constructor calls and definitions: `{}` in Lua, and Java constructors.

`TSConditional`
							    *hl-TSConditional*
For keywords related to conditionnals.

`TSRepeat`
								 *hl-TSRepeat*
For keywords related to loops.

`TSLabel`
								  *hl-TSLabel*
For labels: `label:` in C and `:label:` in Lua.

`TSOperator`
							       *hl-TSOperator*
For any operator: `+`, but also `->` and `*` in C.

`TSKeyword`
								*hl-TSKeyword*
For keywords that don't fall in previous categories.

`TSException`
							      *hl-TSException*
For exception related keywords.

`TSType`
								   *hl-TSType*
For types.

`TSTypeBuiltin`
							    *hl-TSTypeBuiltin*
For builtin types (you guessed it, right ?).

`TSStructure`
							      *hl-TSStructure*
This is left as an exercise for the reader.

`TSInclude`
								*hl-TSInclude*
For includes: `#include` in C, `use` or `extern crate` in Rust, or `require`
in Lua

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