refacto: expose a function to set custom capture for the higlighter

BREAKING: deprecate custom_captures from highlight config.
This allows plugin authors to extend the map. It also avoids settings
user configuration specific values during the highlighter
initialization (SOC).
Not sure how much value this brings, and might potentially break a lot
of people configurations. This is questionable.

4 files changed, 31 insertions, 19 deletions

diff --git a/README.md b/README.md
index ca0719c5b..05df7a1e4 100644
--- a/README.md
+++ b/README.md
@@ -273,10 +273,6 @@ Consistent syntax highlighting.
 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 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.
@@ -286,6 +282,17 @@ require'nvim-treesitter.configs'.setup {
 }
 ```
 
+You can add custom highlight captures with:
+
+```vim
+lua <<EOF
+  require"nvim-treesitter.highlight".set_custom_captures {
+    -- Highlight the @foo.bar capture group with the "Identifier" highlight group.
+    ["foo.bar"] = "Identifier",
+  }
+EOF
+```
+
 #### Incremental selection
 
 Incremental selection based on the named nodes from the grammar.
diff --git a/doc/nvim-treesitter.txt b/doc/nvim-treesitter.txt
index f3f03bfe8..e7f7932cf 100644
--- a/doc/nvim-treesitter.txt
+++ b/doc/nvim-treesitter.txt
@@ -71,7 +71,6 @@ 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,
-you can add your own queries too, see |nvim-treesitter-query-extensions|.
 
 All modules are disabled by default, and some provide default keymaps.
 Each module corresponds to an entry in the dictionary passed to the
@@ -133,8 +132,6 @@ 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|.
 - 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,
@@ -154,6 +151,16 @@ Supported options:
     },
   }
 <
+
+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.
 
 ------------------------------------------------------------------------------
diff --git a/lua/nvim-treesitter/configs.lua b/lua/nvim-treesitter/configs.lua
index 8f0f885a1..7e6b0a7b9 100644
--- a/lua/nvim-treesitter/configs.lua
+++ b/lua/nvim-treesitter/configs.lua
@@ -22,8 +22,9 @@ local is_initialized = false
 local builtin_modules = {
   highlight = {
     module_path = "nvim-treesitter.highlight",
-    enable = false,
+    -- @deprecated: use `highlight.set_custom_captures` instead
     custom_captures = {},
+    enable = false,
     is_supported = function(lang)
       return queries.has_highlights(lang)
     end,
diff --git a/lua/nvim-treesitter/highlight.lua b/lua/nvim-treesitter/highlight.lua
index ce7cf8117..b71a64eec 100644
--- a/lua/nvim-treesitter/highlight.lua
+++ b/lua/nvim-treesitter/highlight.lua
@@ -114,10 +114,6 @@ local function enable_syntax(bufnr)
   api.nvim_buf_set_option(bufnr, "syntax", "ON")
 end
 
-function M.get_config()
-  return configs.get_module "highlight"
-end
-
 function M.stop(bufnr)
   if ts.highlighter.active[bufnr] then
     ts.highlighter.active[bufnr]:destroy()
@@ -126,18 +122,13 @@ end
 
 function M.start(bufnr, lang)
   local parser = parsers.get_parser(bufnr, lang)
-  local config = M.get_config()
-
-  for k, v in pairs(config.custom_captures) do
-    hlmap[k] = v
-  end
-
   ts.highlighter.new(parser, {})
 end
 
 function M.attach(bufnr, lang)
+  local config = configs.get_module "highlight"
   M.start(bufnr, lang)
-  if should_enable_vim_regex(M.get_config(), lang) then
+  if should_enable_vim_regex(config, lang) then
     enable_syntax(bufnr)
   end
 end
@@ -147,4 +138,10 @@ function M.detach(bufnr)
   enable_syntax(bufnr)
 end
 
+function M.set_custom_captures(captures)
+  for k, v in pairs(captures) do
+    hlmap[k] = v
+  end
+end
+
 return M