From 7f81df44098a7fef93d6901a06b8312c5b8619d7 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sun, 9 Aug 2020 11:39:51 -0500 Subject: Docs: documentation for modules/submodules --- doc/nvim-treesitter.txt | 571 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 416 insertions(+), 155 deletions(-) (limited to 'doc') diff --git a/doc/nvim-treesitter.txt b/doc/nvim-treesitter.txt index 096d8698c..bc70d6d6c 100644 --- a/doc/nvim-treesitter.txt +++ b/doc/nvim-treesitter.txt @@ -2,16 +2,21 @@ Minimum version of neovim: nightly -Authors: Yazdani Kiyan , Vigouroux Thomas +Authors: Yazdani Kiyan + Vigouroux Thomas + https://github.com/nvim-treesitter/nvim-treesitter/graphs/contributors + + Type |gO| to see the table of contents. ============================================================================== -INTRODUCTION *nvim-treesitter-intro* +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. +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* +QUICK START *nvim-treesitter-quickstart* Install the parser for your language @@ -25,108 +30,364 @@ To get a list of supported languages :TSInstallInfo < -By default, everything is disabled. To enable support for features, in your `init.vim`: +By default, everything is disabled. +To enable supported features, put this in your `init.vim` file: > lua < + lua < + lua <a`, `a` +`` (control + a), `` (alt + n), `` (enter), etc. + +External plugins can provide their own modules with their own options, +those can also be configured using the `nvim-treesitter.configs.setup` +function. + +------------------------------------------------------------------------------ +HIGHLIGHT *nvim-treesitter-highlight-mod* + +Consistent syntax highlighting. + +Query files: `highlights.scm`. +Supported options: + +- enable: `true` or `false`. +- disable: list of languages. +- custom_captures: A map of user defined capture groups to highlight groups. + See |nvim-treesitter-query-extensions|. + +> + lua < + lua < textobject query) - swap_next = { - [""] = "@parameter.inner", - }, - swap_previous = { - [""] = "@parameter.inner", - }, - -- set mappings to go to start/end of adjacent textobjects (keymap -> textobject query) - goto_previous_start = { - ["[m"] = "@function.outer", - ["[["] = "@class.outer", - }, - goto_previous_end = { - ["[M"] = "@function.outer", - ["[]"] = "@class.outer", - }, - goto_next_start = { - ["]m"] = "@function.outer", - ["]]"] = "@class.outer", - }, - goto_next_end = { - ["]M"] = "@function.outer", - ["]["] = "@class.outer", - }, + init_selection = "gnn", + node_incremental = "grn", + scope_incremental = "grc", + node_decremental = "grm", + }, + }, + } + EOF +< + +------------------------------------------------------------------------------ +REFACTOR *nvim-treesitter-refactor-mod* + + *nvim-treesitter-highlight-definitions-submod* +Highlight definitions~ + +Highlights definition and usages of the current symbol under the cursor. + +Query files: `locals.scm`. +Supported options: +- enable: `true` or `false`. +- disable: list of languages. + +> + lua < + lua < + lua < + lua < + lua < + lua <a"] = "@parameter.inner", + }, + swap_previous = { + ["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. +- goto_next_start: map of keymaps to a tree-sitter capture group (`@function.outer`). +- 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 < local ts_utils = require 'nvim-treesitter.ts_utils' < Methods - *ts_utils.get_node_at_cursor* + *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* + *ts_utils.get_node_text* get_node_text(node, bufnr)~ Returns the text content of a `node`. - *ts_utils.is_parent* + *ts_utils.is_parent* is_parent(dest, source)~ Determines whether `dest` is a parent of `source`. Returns a boolean. - *ts_utils.get_named_children* + *ts_utils.get_named_children* get_named_children(node)~ Returns a table of named children of `node`. - *ts_utilsiget_next_node* + *ts_utilsiget_next_node* get_next_node(node, allow_switch_parent, allow_next_parent)~ Returns the next node within the same parent. @@ -245,7 +506,7 @@ 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* + *ts_utils.get_previous_node* get_previous_node(node, allow_switch_parents, allow_prev_parent)~ Returns the previous node within the same parent. @@ -255,15 +516,15 @@ as |ts_utils.get_next_node| but if the node is the first node. ============================================================================== FUNCTIONS *nvim-treesitter-functions* - *nvim_treesitter#statusline()* + *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 +Note: The `size` argument is optional. When specified, the string will not be longer than `size`. - *nvim_treesitter#foldexpr()* + *nvim_treesitter#foldexpr()* nvim_treesitter#foldexpr()~ Functions to be used to determine the fold level at a given line number. @@ -279,7 +540,7 @@ Note: This is highly experimental, and folding can break on some types of HIGHLIGHTS *nvim-treesitter-highlights* `TSError` - *hl-TSError* + *hl-TSError* For syntax/parser errors. You can deactivate highlighting of syntax errors by adding this to your @@ -287,112 +548,112 @@ init.vim: > highlight link TSError Normal `TSPunctDelimiter` - *hl-TSPunctDelimiter* + *hl-TSPunctDelimiter* For delimiters ie: `.` `TSPunctBracket` - *hl-TSPunctBracket* + *hl-TSPunctBracket* For brackets and parens. `TSPunctSpecial` - *hl-TSPunctSpecial* + *hl-TSPunctSpecial* For special punctutation that does not fall in the catagories before. `TSConstant` - *hl-TSConstant* + *hl-TSConstant* For constants `TSConstBuiltin` - *hl-TSConstBuiltin* + *hl-TSConstBuiltin* For constant that are built in the language: `nil` in Lua. `TSConstMacro` - *hl-TSConstMacro* + *hl-TSConstMacro* For constants that are defined by macros: `NULL` in C. `TSString` - *hl-TSString* + *hl-TSString* For strings. `TSStringRegex` - *hl-TSStringRegex* + *hl-TSStringRegex* For regexes. `TSStringEscape` - *hl-TSStringEscape* + *hl-TSStringEscape* For escape characters within a string. `TSCharacter` - *hl-TSCharacter* + *hl-TSCharacter* For characters. `TSNumber` - *hl-TSNumber* + *hl-TSNumber* For integers. `TSBoolean` - *hl-TSBoolean* + *hl-TSBoolean* For booleans. `TSFloat` - *hl-TSFloat* + *hl-TSFloat* For floats. `TSFunction` - *hl-TSFunction* + *hl-TSFunction* For function (calls and definitions). `TSFuncBuiltin` - *hl-TSFuncBuiltin* + *hl-TSFuncBuiltin* For builtin functions: `table.insert` in Lua. `TSFuncMacro` - *hl-TSFuncMacro* + *hl-TSFuncMacro* For macro defined fuctions (calls and definitions): each `macro_rules` in Rust. `TSParameter` - *hl-TSParameter* + *hl-TSParameter* For parameters of a function. `TSParameterReference` - *hl-TSParameterReference* + *hl-TSParameterReference* For references to parameters of a function. `TSMethod` - *hl-TSMethod* + *hl-TSMethod* For method calls and definitions. `TSField` - *hl-TSField* + *hl-TSField* For fields. `TSProperty` - *hl-TSProperty* + *hl-TSProperty* Same as `TSField`. `TSConstructor` - *hl-TSConstructor* + *hl-TSConstructor* For constructor calls and definitions: `{}` in Lua, and Java constructors. `TSConditional` - *hl-TSConditional* + *hl-TSConditional* For keywords related to conditionnals. `TSRepeat` - *hl-TSRepeat* + *hl-TSRepeat* For keywords related to loops. `TSLabel` - *hl-TSLabel* + *hl-TSLabel* For labels: `label:` in C and `:label:` in Lua. `TSOperator` - *hl-TSOperator* + *hl-TSOperator* For any operator: `+`, but also `->` and `*` in C. `TSKeyword` - *hl-TSKeyword* + *hl-TSKeyword* For keywords that don't fall in previous categories. `TSKeywordFunction` @@ -400,23 +661,23 @@ For keywords that don't fall in previous categories. For keywords used to define a fuction. `TSException` - *hl-TSException* + *hl-TSException* For exception related keywords. `TSType` - *hl-TSType* + *hl-TSType* For types. `TSTypeBuiltin` - *hl-TSTypeBuiltin* + *hl-TSTypeBuiltin* For builtin types (you guessed it, right ?). `TSStructure` - *hl-TSStructure* + *hl-TSStructure* This is left as an exercise for the reader. `TSInclude` - *hl-TSInclude* + *hl-TSInclude* For includes: `#include` in C, `use` or `extern crate` in Rust, or `require` in Lua. @@ -426,32 +687,32 @@ For C++/Dart attributes, annotations that can be attached to the code to denote some kind of meta information. `TSText` - *hl-TSText* + *hl-TSText* For strings considered text in a markup language. `TSStrong` - *hl-TSStrong* + *hl-TSStrong* For text to be represented with strong. `TSEmphasis` - *hl-TSEmphasis* + *hl-TSEmphasis* For text to be represented with emphasis. `TSUnderline` - *hl-TSUnderline* + *hl-TSUnderline* For text to be represented with an underline. `TSTitle` - *hl-TSTitle* + *hl-TSTitle* Text that is part of a title. `TSLiteral` - *hl-TSLiteral* + *hl-TSLiteral* Literal text. `TSURI` - *hl-TSURI* + *hl-TSURI* Any URI like a link or email. ============================================================================== @@ -475,4 +736,4 @@ the cursor. *hl-TSCurrentScope* Used by refactor.highlight_current_scope to highlight the current scope. -vim:tw=78:ts=8:noet:ft=help:norl: +vim:tw=78:ts=8:expandtab:noet:ft=help:norl: -- cgit v1.2.3-70-g09d2