*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_definitions = {
	  enable = true
	},
	highlight_current_scope = {
	  enable = true
	},
	smart_rename = {
	  enable = true,
	  keymaps = {
	    smart_rename = "grr"          -- mapping to rename reference under cursor
	  }
	},
	navigation = {
	  enable = true,
	  keymaps = {
	    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*
:TSInstall| {language} ...~

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

							      *:TSInstallInfo*
:TSInstallInfo~

List informations about currently installed parsers

							           *:TSUpdate*
:TSUpdate {language}~

Update the installed parser of {language} or all installed parsers
if {language} is omitted.

							        *:TSUninstall*
:TSUninstall {language}~

Deletes the parser for corresponding {language}. You can use 'all' for
language to uninstall all parsers.

								*:TSBufEnable*
:TSBufEnable {module}~

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

							       *:TSBufDisable*
:TSBufDisable {module}~

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

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

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*
:TSBufDisableAll {module} [{language}]~

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*
:TSModuleInfo [{module}]~

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
						 *ts_utils.get_node_at_cursor*
get_node_at_cursor(winnr)~

`winnr` will be 0 if nil.
Returns the node under the cursor.

						      *ts_utils.get_node_text*
get_node_text(node, bufnr)~

Returns the text content of a `node`.

							  *ts_utils.is_parent*
is_parent(dest, source)~

Determines whether `dest` is a parent of `source`.
Returns a boolean.

						 *ts_utils.get_named_children*
get_named_children(node)~

Returns a table of named children of `node`.

						      *ts_utilsiget_next_node*
get_next_node(node, allow_switch_parent, allow_next_parent)~

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

						  *ts_utils.get_previous_node*
get_previous_node(node, allow_switch_parents, allow_prev_parent)~

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

						   *ts_utils.containing_scope*
containing_scope(node)~

Returns the smallest scope containing the node.

						       *ts_utils.parent_scope*
parent_scope(node, cursor_pos)~

Returns the parent scope of the current scope that contains the node.
`cursor_pos` should be `{ row = number, col = number }`

						       *ts_utils.nested_scope*
nested_scope(node, cursor_pos)~

Returns the first scope within current scope that contains the node.
`cursor_pos` should be `{ row = number, col = number }`

							 *ts_utils.next_scope*
next_scope(node)~

Returns the neighbour scope of the current node.

						     *ts_utils.previous_scope*
previous_scope(node)~

Returns the previous neighbour scope of the current node.

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

						*nvim_treesitter#statusline()*
nvim_treesitter#statusline(size)~

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

`TSText`
								   *hl-TSText*
For strings considered text in a markup language.

`TSStrong`
								 *hl-TSStrong*
For text to be represented with strong.

`TSEmphasis`
							       *hl-TSEmphasis*
For text to be represented with emphasis.

`TSUnderline`
							       *hl-TSUnderline*
For text to be represented with an underline.

`TSTitle`

Text that is part of a title.

`TSLiteral`
								*hl-TSLiteral*
Literal text.

`TSURI`
								    *hl-TSURI*
Any URI like a link or email.

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