treesitter-modules.nvim

Original modules from nvim-treesitter master branch

Caution

With the release of neovim 0.12.0 there is likely nothing you need from this plugin. Consider reading the Do I Need This Plugin? section and avoiding this dependency entirely!

Install

lazy.nvim

{
    'MeanderingProgrammer/treesitter-modules.nvim',
    dependencies = { 'nvim-treesitter/nvim-treesitter' },
    ---@module 'treesitter-modules'
    ---@type ts.mod.UserConfig
    opts = {},
}

packer.nvim

use({
    'MeanderingProgrammer/treesitter-modules.nvim',
    after = { 'nvim-treesitter' },
    requires = { 'nvim-treesitter/nvim-treesitter' },
    config = function()
        require('treesitter-modules').setup({})
    end,
})

Setup

Default Configuration

require('treesitter-modules').setup({
    -- list of parser names, or 'all', that must be installed
    ensure_installed = {},
    -- list of parser names, or 'all', to ignore installing
    ignore_install = {},
    -- install parsers in ensure_installed synchronously
    sync_install = false,
    -- automatically install missing parsers when entering buffer
    auto_install = false,
    fold = {
        enable = false,
        disable = false,
    },
    highlight = {
        enable = false,
        disable = false,
        -- 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
        -- using this option may slow down your editor, and duplicate highlights
        -- instead of `true` it can also be a list of languages
        additional_vim_regex_highlighting = false,
    },
    incremental_selection = {
        enable = false,
        disable = false,
        -- set value to `false` to disable individual mapping
        -- node_decremental captures both node_incremental and scope_incremental
        keymaps = {
            init_selection = 'gnn',
            node_incremental = 'grn',
            scope_incremental = 'grc',
            node_decremental = 'grm',
        },
    },
    indent = {
        enable = false,
        disable = false,
    },
})

API

Instead of having this plugin create incremental selection keymaps for you via the configuration you can use API methods with the same name to create them yourself. This gives you control over over all associated properties (like mode and description) as well as when the keymaps get created and what buffers they exist for.

For example lets say we currently have the following configuration:

require('treesitter-modules').setup({
    highlight = { enable = true },
    incremental_selection = { enable = true },
})

We can create the same keymaps but without any descriptions and such that they exist for all buffers using the following configuration:

local ts = require('treesitter-modules')
ts.setup({
    highlight = { enable = true },
})
vim.keymap.set('n', 'gnn', ts.init_selection)
vim.keymap.set('x', 'grn', ts.node_incremental)
vim.keymap.set('x', 'grc', ts.scope_incremental)
vim.keymap.set('x', 'grm', ts.node_decremental)

Purpose

As nvim-treesitter moves towards a stable release they have made the decision to be less around providing functionality directly, and more towards providing the tools to enable functionality. Specifically they are focussed on making parsers and queries easily available, but not using those queries to enable highlighting for example.

This makes a lot of sense in terms of maintenance, combining functionality with what is essentially a package manager for parsers is a lot to put into one plugin and splits developer effort over a large area. However, as a downside, users will now need to write this common functionality within their individual configurations. It's not complex logic, but for someone newer it may serve as another barrier to entry.

This plugin aims to provide the functionality previously offered by nvim-treesitter through simple configuration. It can also serves as a concrete example of how to implement these functions within your own configuration. It is not meant to have total parity with the original, option names may be different, some options may not be available, some options may be new, and some may function slightly different.

Do I Need This Plugin?

The short answer to this question is always no, but in this particular case it depends on what features you care about, and what version of neovim you're using.

The new version of nvim-treesitter provides powerful and simple APIs to replace all the old builtin modules, the only exceptions to this is incremental selection.

As of neovim 0.12.0 incremental selection is largely covered by the an and in keymaps for more info see :h treesitter-defaults. You can always remap these.

The only remaining gaps are scope based incremental selection (neovim does node based) and the ability to auto install parsers. If these 2 very specific features do not matter to you then I would highly recommend implementing this yourself in your configuration, which is covered below.

All other features can be implemented in your configuration in about 20 lines of code. You can use the below examples as a sort of migration guide as well, they are written for lazy.nvim but should be simple to apply to other plugin managers.

Implementing Yourself

-- this is what you previously passed to ensure_installed
local languages = { 'c', 'lua', 'rust' }
return {
    'nvim-treesitter/nvim-treesitter',
    branch = 'main',
    build = ':TSUpdate',
    config = function()
        -- replicate `ensure_installed`, runs asynchronously, skips existing languages
        require('nvim-treesitter').install(languages)

        vim.api.nvim_create_autocmd('FileType', {
            group = vim.api.nvim_create_augroup('treesitter.setup', {}),
            callback = function(args)
                local buf = args.buf
                local filetype = args.match

                -- you need some mechanism to avoid running on buffers that do not
                -- correspond to a language (like oil.nvim buffers), this implementation
                -- checks if a parser exists for the current language
                local language = vim.treesitter.language.get_lang(filetype) or filetype
                if not vim.treesitter.language.add(language) then
                    return
                end

                -- replicate `fold = { enable = true }`
                vim.wo.foldmethod = 'expr'
                vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'

                -- replicate `highlight = { enable = true }`
                vim.treesitter.start(buf, language)

                -- replicate `indent = { enable = true }`
                vim.bo[buf].indentexpr = "v:lua.require'nvim-treesitter'.indentexpr()"

                -- `incremental_selection = { enable = true }` covered by 0.12.0
            end,
        })
    end,
}

Using this Plugin

-- this is what you previously passed to ensure_installed
local languages = { 'c', 'lua', 'rust' }
return {
    {
        'nvim-treesitter/nvim-treesitter',
        branch = 'main',
        build = ':TSUpdate',
    },
    {
        'MeanderingProgrammer/treesitter-modules.nvim',
        dependencies = { 'nvim-treesitter/nvim-treesitter' },
        opts = {
            ensure_installed = languages,
            fold = { enable = true },
            highlight = { enable = true },
            indent = { enable = true },
            incremental_selection = { enable = true },
        },
    },
}