feat!: drop modules, general refactor and cleanup

1 files changed, 57 insertions, 427 deletions

diff --git a/doc/nvim-treesitter.txt b/doc/nvim-treesitter.txt
index f7a91b849..7054121b5 100644
--- a/doc/nvim-treesitter.txt
+++ b/doc/nvim-treesitter.txt
@@ -1,6 +1,4 @@
-*nvim-treesitter*  Treesitter configurations and abstraction layer for Neovim.
-
-Minimum version of neovim: nightly
+*nvim-treesitter.txt*         Treesitter parser and query installer for Neovim
 
 Authors:
   Kiyan Yazdani <yazdani.kiyan@protonmail.com>
@@ -15,38 +13,37 @@ Authors:
 ==============================================================================
 INTRODUCTION                                           *nvim-treesitter-intro*
 
-nvim-treesitter wraps the Neovim treesitter API to provide functionalities
-such as highlighting and incremental selection, and a command to easily
-install parsers.
+Nvim-treesitter provides functionalities for managing treesitter parsers and
+compatible queries for core features (highlighting, injections, fold, indent).
+
+WARNING: This is work in progress and requires the latest commit on Neovim
+`master`.
 
 ==============================================================================
 QUICK START                                       *nvim-treesitter-quickstart*
 
 Install the parser for your language
 
->
+>vim
   :TSInstall {language}
 <
 
 To get a list of supported languages
 
->
+>vim
   :TSInstallInfo
 <
 
-By default, everything is disabled.
-To enable supported features, put this in your `init.lua` file:
+To install supported parsers and queries, put this in your `init.lua` file:
 
->
+>lua
   require'nvim-treesitter.configs'.setup {
     -- A directory to install the parsers into.
-    -- If this is excluded or nil parsers are installed
-    -- to either the package dir, or the "site" dir.
-    -- If a custom path is used (not nil) it must be added to the runtimepath.
-    parser_install_dir = "/some/path/to/store/parsers",
+    -- Defaults to the `stdpath('data')/site` dir.
+    install_dir = "/some/path/to/store/parsers",
 
-    -- A list of parser names, or "all"
-    ensure_installed = { "c", "lua", "rust" },
+    -- A list of parser names, or "core", "stable", "community", "unstable"
+    ensure_install = { "core", "rust" },
 
     -- Install parsers synchronously (only applied to `ensure_installed`)
     sync_install = false,
@@ -54,174 +51,66 @@ To enable supported features, put this in your `init.lua` file:
     -- Automatically install missing parsers when entering buffer
     auto_install = false,
 
-    -- List of parsers to ignore installing (for "all")
+    -- List of parsers to ignore installing (for "core" etc.)
     ignore_install = { "javascript" },
 
-    highlight = {
-      -- `false` will disable the whole extension
-      enable = true,
-
-      -- list of language that will be disabled
-      disable = { "c", "rust" },
-
-      -- Setting this to true will run `:h syntax` and tree-sitter at the same time.
-      -- Set this to `true` if you depend on 'syntax' being enabled (like for indentation).
-      -- Using this option may slow down your editor, and you may see some duplicate highlights.
-      -- Instead of true it can also be a list of languages
-      additional_vim_regex_highlighting = false,
-    },
-  }
-  vim.opt.runtimepath:append("/some/path/to/store/parsers")
 <
-
-See |nvim-treesitter-modules| for a list of all available modules and its options.
+See |nvim-treesitter-commands| for a list of all available commands.
 
 ==============================================================================
-MODULES                                              *nvim-treesitter-modules*
-
-|nvim-treesitter| provides several functionalities via modules (and submodules),
-each module makes use of the query files defined for each language,
-
-All modules are disabled by default, and some provide default keymaps.
-Each module corresponds to an entry in the dictionary passed to the
-`nvim-treesitter.configs.setup` function, this should be in your `init.lua` file.
-
->
-  require'nvim-treesitter.configs'.setup {
-    -- Modules and its options go here
-    highlight = { enable = true },
-    incremental_selection = { enable = true },
-    textobjects = { enable = true },
-  }
-<
+COMMANDS                                            *nvim-treesitter-commands*
 
-All modules share some common options, like `enable` and `disable`.
-When `enable` is `true` this will enable the module for all supported languages,
-if you want to disable the module for some languages you can pass a list to the `disable` option.
+								  *:TSInstall*
+:TSInstall {language} ... ~
 
->
-  require'nvim-treesitter.configs'.setup {
-    highlight = {
-      enable = true,
-      disable = { "cpp", "lua" },
-    },
-  }
-<
+Install one or more treesitter parsers.
+You can use |:TSInstall| `all` to install all parsers. Use |:TSInstall!| to
+force the reinstallation of already installed parsers.
+							      *:TSInstallSync*
+:TSInstallSync {language} ... ~
 
-For more fine-grained control, `disable` can also take a function and
-whenever it returns `true`, the module is disabled for that buffer.
-The function is called once when a module starts in a buffer and receives the
-language and buffer number as arguments:
+Perform the |:TSInstall| operation synchronously.
 
->
-  require'nvim-treesitter.configs'.setup {
-    highlight = {
-      enable = true,
-      disable = function(lang, bufnr) -- Disable in large C++ buffers
-        return lang == "cpp" and vim.api.nvim_buf_line_count(bufnr) > 50000
-      end,
-    },
-  }
-<
+							      *:TSInstallInfo*
+:TSInstallInfo ~
 
-Options that define or accept a keymap use the same format you use to define
-keymaps in Neovim, so you can write keymaps as  `gd`, `<space>a`, `<leader>a`
-`<C-a>` (control + a), `<A-n>` (alt + n), `<CR>` (enter), etc.
+List information about currently installed parsers
 
-External plugins can provide their own modules with their own options,
-those can also be configured using the `nvim-treesitter.configs.setup`
-function.
+								   *:TSUpdate*
+:TSUpdate {language} ... ~
 
-------------------------------------------------------------------------------
-HIGHLIGHT                                      *nvim-treesitter-highlight-mod*
+Update the installed parser for one more {language} or all installed parsers
+if {language} is omitted. The specified parser is installed if it is not already
+installed.
 
-Consistent syntax highlighting.
+							       *:TSUpdateSync*
+:TSUpdateSync {language} ... ~
 
-Query files: `highlights.scm`.
-Supported options:
+Perform the |:TSUpdate| operation synchronously.
 
-- enable: `true` or `false`.
-- disable: list of languages.
-- additional_vim_regex_highlighting: `true` or `false`, or a list of languages.
-  Set this to `true` if you depend on 'syntax' being enabled
-  (like for indentation). Using this option may slow down your editor,
-  and you may see some duplicate highlights.
-  Defaults to `false`.
+								*:TSUninstall*
+:TSUninstall {language} ... ~
 
->
-  require'nvim-treesitter.configs'.setup {
-    highlight = {
-      enable = true,
-      custom_captures = {
-        -- Highlight the @foo.bar capture group with the "Identifier" highlight group.
-        ["foo.bar"] = "Identifier",
-      },
-      -- Setting this to true or a list of languages will run `:h syntax` and tree-sitter at the same time.
-      additional_vim_regex_highlighting = false,
-    },
-  }
-<
+Deletes the parser for one or more {language}. You can use 'all' for language
+to uninstall all parsers.
 
-You can also set custom highlight captures
->
-  lua <<EOF
-    require"nvim-treesitter.highlight".set_custom_captures {
-      -- Highlight the @foo.bar capture group with the "Identifier" highlight group.
-      ["foo.bar"] = "Identifier",
-    }
-  EOF
-<
-Note: The api is not stable yet.
+==============================================================================
+INDENTATION                                        *nvim-treesitter-indentation*
 
-------------------------------------------------------------------------------
-INCREMENTAL SELECTION              *nvim-treesitter-incremental-selection-mod*
+Indentation based on treesitter for the |=| operator.
+NOTE: this is an experimental feature and will be upstreamed to Neovim when
+stable.
 
-Incremental selection based on the named nodes from the grammar.
+To enable it for a supported parser, add the following to a corresponding
+`FileType` autocommand or `ftplugin/<lang>.lua`:  >lua
 
-Query files: `locals.scm`.
-Supported options:
-- enable: `true` or `false`.
-- disable: list of languages.
-- keymaps:
-  - init_selection: in normal mode, start incremental selection.
-    Defaults to `gnn`.
-  - node_incremental: in visual mode, increment to the upper named parent.
-    Defaults to `grn`.
-  - scope_incremental: in visual mode, increment to the upper scope
-    (as defined in `locals.scm`). Defaults to `grc`.
-  - node_decremental: in visual mode, decrement to the previous named node.
-    Defaults to `grm`.
+  vim.bo.indentexpr = 'v.lua:require'nvim-treesitter'.indentexpr()'
 
->
-  require'nvim-treesitter.configs'.setup {
-    incremental_selection = {
-      enable = true,
-      keymaps = {
-        init_selection = "gnn",
-        node_incremental = "grn",
-        scope_incremental = "grc",
-        node_decremental = "grm",
-      },
-    },
-  }
 <
 
-------------------------------------------------------------------------------
-INDENTATION                                  *nvim-treesitter-indentation-mod*
-
-Indentation based on treesitter for the |=| operator.
-NOTE: this is an experimental feature.
+Indentation for a language is controlled by `indents.scm` queries. The
+following captures are supported:
 
-Query files: `indents.scm`.
-Supported options:
-- enable: `true` or `false`.
-- disable: list of languages.
->
-  require'nvim-treesitter.configs'.setup {
-    indent = {
-      enable = true
-    },
-  }
 
 `@indent`				    *nvim-treesitter-indentation-queries*
 Queries can use the following captures: `@indent.begin` and `@indent.dedent`,
@@ -233,7 +122,7 @@ the indentation to 0.
 The `@indent.begin` specifies that the next line should be indented.  Multiple
 indents on the same line get collapsed. Eg.
 
->
+>query
   (
    (if_statement)
    (ERROR "else") @indent.begin
@@ -244,13 +133,13 @@ permits the next line to indent even when the block intended to be indented
 has no content yet, improving interactive typing.
 
 eg for python:
->
+>query
  ((if_statement) @indent.begin
    (#set! indent.immediate 1))
 <
 
 Will allow:
->
+>python
   if True:<CR>
       # Auto indent to here
 
@@ -291,7 +180,7 @@ and finally
 <
 To specify the delimiters to use `indent.open_delimiter` and
 `indent.close_delimiter` should be used.  Eg.
->
+>query
  ((argument_list) @indent.align
   (#set! indent.open_delimiter "(")
   (#set! indent.close_delimiter ")"))
@@ -302,13 +191,13 @@ the same indent as the natural next line.
 
 For example in python:
 
->
+>python
   if (a > b and
       c < d):
       pass
 
 Is not correct, whereas
->
+>python
   if (a > b and
 	c < d):
       pass
@@ -316,7 +205,7 @@ Is not correct, whereas
 Would be correctly indented.  This behavior may be chosen using
 `indent.avoid_last_matching_next`.  Eg.
 
->
+>query
  (if_statement
   condition: (parenthesized_expression) @indent.align
   (#set! indent.open_delimiter "(")
@@ -328,263 +217,4 @@ Could be used to specify that the last line of an `@indent.align` capture
 should be additionally indented to avoid clashing with the indent of the first
 line of the block inside an if.
 
-==============================================================================
-COMMANDS                                            *nvim-treesitter-commands*
-
-								  *:TSInstall*
-:TSInstall {language} ...~
-
-Install one or more treesitter parsers.
-You can use |:TSInstall| `all` to install all parsers. Use |:TSInstall!| to
-force the reinstallation of already installed parsers.
-							      *:TSInstallSync*
-:TSInstallSync {language} ...~
-
-Perform the |:TSInstall| operation synchronously.
-
-							      *:TSInstallInfo*
-:TSInstallInfo~
-
-List information about currently installed parsers
-
-								   *:TSUpdate*
-:TSUpdate {language} ...~
-
-Update the installed parser for one more {language} or all installed parsers
-if {language} is omitted. The specified parser is installed if it is not already
-installed.
-
-							       *:TSUpdateSync*
-:TSUpdateSync {language} ...~
-
-Perform the |:TSUpdate| operation synchronously.
-
-								*:TSUninstall*
-:TSUninstall {language} ...~
-
-Deletes the parser for one or more {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|
-
-								*:TSBufToggle*
-:TSBufToggle {module}~
-
-Toggle (enable if disabled, disable if enabled) {module} on the current
-buffer.
-A list of modules can be found at |:TSModuleInfo|
-
-								*:TSEnable*
-:TSEnable {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|
-
-							       *:TSDisable*
-:TSDisable {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|
-
-								*:TSToggle*
-:TSToggle {module} [{language}]~
-
-Toggle (enable if disabled, disable if enabled) {module} for the session.
-If {language} is specified, toggle 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 the state for the given module or all modules for the current session in
-a new buffer.
-
-These highlight groups are used by default:
->
-    highlight default TSModuleInfoGood guifg=LightGreen gui=bold
-    highlight default TSModuleInfoBad  guifg=Crimson
-    highlight default link TSModuleInfoHeader    Type
-    highlight default link TSModuleInfoNamespace Statement
-    highlight default link TSModuleInfoParser    Identifier
-<
-
-								*:TSEditQuery*
-:TSEditQuery {query-group} [{lang}]~
-
-Edit the query file for a {query-group} (e.g. highlights, locals) for given
-{lang}. If there are multiple files, the user is prompted to select one of them.
-If no such file exists, a buffer for a new file in the user's config directory
-is created. If {lang} is not specified, the language of the current buffer
-is used.
-
-						       *:TSEditQueryUserAfter*
-:TSEditQueryUserAfter {query-group} [{lang}]~
-
-Same as |:TSEditQuery| but edits a file in the `after` directory of the
-user's config directory. Useful to add custom extensions for the queries
-provided by a plugin.
-
-==============================================================================
-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.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_utils.get_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.goto_node*
-goto_node(node, goto_end, avoid_set_jump)~
-
-Sets cursor to the position of `node` in the current windows.
-If `goto_end` is truthy, the cursor is set to the end the node range.
-Setting `avoid_set_jump` to `true`, avoids setting the current cursor position
-to the jump list.
-
-							 *ts_utils.swap_nodes*
-swap_nodes(node_or_range1, node_or_range2, bufnr, cursor_to_second)~
-
-Swaps the nodes or ranges.
-set `cursor_to_second`  to true to move the cursor to the second node
-
-						*ts_utils.memoize_by_buf_tick*
-memoize_by_buf_tick(fn, options)~
-
-Caches the return value for a function and returns the cache value if the tick
-of the buffer has not changed from the previous.
-
-		`fn`: a function that takes any arguments
-		and returns a value to store.
-		`options?`: <table>
-                 - `bufnr`: a function/value that extracts the bufnr from the given arguments.
-                 - `key`: a function/value that extracts the cache key from the given arguments.
-		`returns`: a function to call with bufnr as argument to
-		retrieve the value from the cache
-
-						  *ts_utils.node_to_lsp_range*
-node_to_lsp_range(node)~
-
-Get an lsp formatted range from a node range
-
-							*ts_utils.node_length*
-node_length(node)~
-
-Get the byte length of node range
-
-						   *ts_utils.update_selection*
-update_selection(buf, node)~
-
-Set the selection to the node range
-
-						    *ts_utils.highlight_range*
-highlight_range(range, buf, hl_namespace, hl_group)~
-
-Set a highlight that spans the given range
-
-						     *ts_utils.highlight_node*
-highlight_node(node, buf, hl_namespace, hl_group)~
-
-Set a highlight that spans the given node's range
-
-==============================================================================
-FUNCTIONS                                          *nvim-treesitter-functions*
-
-						*nvim_treesitter#statusline()*
-nvim_treesitter#statusline(opts)~
-
-Returns a string describing the current position in the file. This
-could be used as a statusline indicator.
-Default options (lua syntax):
->
-  {
-    indicator_size = 100,
-    type_patterns = {'class', 'function', 'method'},
-    transform_fn = function(line, _node) return line:gsub('%s*[%[%(%{]*%s*$', '') end,
-    separator = ' -> ',
-    allow_duplicates = false
-  }
-<
-- `indicator_size` - How long should the string be. If longer, it is cut from
-  the beginning.
-- `type_patterns` - Which node type patterns to match.
-- `transform_fn` - Function used to transform the single item in line. By
-  default it removes opening brackets and spaces from end. Takes two arguments:
-  the text of the line in question, and the corresponding treesitter node.
-- `separator` - Separator between nodes.
-- `allow_duplicates` - Whether or not to remove duplicate components.
-
-						  *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#foldexpr()
-<
-
-This will respect your 'foldminlines' and 'foldnestmax' settings.
-
-Note: This is highly experimental, and folding can break on some types of
-      edits. If you encounter such breakage, hitting `zx` should fix folding.
-      In any case, feel free to open an issue with the reproducing steps.
-
-==============================================================================
-PERFORMANCE                                      *nvim-treesitter-performance*
-
-`nvim-treesitter` checks the 'runtimepath' on startup in order to discover
-available parsers and queries and index them. As a consequence, a very long
-'runtimepath' might result in delayed startup times.
-
-
 vim:tw=78:ts=8:expandtab:noet:ft=help:norl: