🚚 ts-query-loader

Auto enabling query (module) features of nvim-treesitter

🤔 Why ?

Since nvim-treesitter stop developing on master branch and rewritten in main branch. It DOES NOT auto-enable query features anymore.

Hence, this plugin provides some of functionalities to:

• Auto-enable all available queries features.
• Configure filtering query, parser from auto-enabling.
• Configure changing how query feature being enabled.
• Ensure installing a list of parser.

📜 Requirements

• nvim-treesitter main branch or its derivation.

📦 Installation

lazy.nvim

{
	"Corn207/ts-query-loader.nvim",
	version = "*", -- Choose latest stable version
	dependencies = {
		"nvim-treesitter/nvim-treesitter",
	},
	opts = {},
},

⚙️ Configuration

By default, no configuration is already enough. Below are several fields for general usage:

{
	queries = {
		highlights = { -- Name of query
			disabled = false, -- Prevent query from being enable
			disabled_parsers = {}, -- Prevent query with specific parsers
		},
		folds = {
			disabled = false,
			disabled_parsers = {},
		},
		indents = {
			disabled = false,
			disabled_parsers = {},
		},
	},
	ensure_installed = {}, -- Auto-install list of parser names
}

Note

Above table will be recusively merged to internal default option. Simply pass the table to opts = ... or require("ts-query-loader").setup(...).

The table can be partial, doesn't have to be full like above.

Example of internal default option table:

{
	queries = {
		highlights = {
			disabled = false,
			disabled_parsers = {},
			skip_ts_check = true, -- Refer to Technicality section
			handler = function() -- Run on found Filetype with matching Query
				vim.treesitter.start()
			end,
		},
		folds = {
			disabled = false,
			disabled_parsers = {},
			skip_ts_check = false,
			handler = function()
				vim.wo.foldexpr = "v:lua.vim.treesitter.foldexpr()"
			end,
		},
		indents = {
			disabled = false,
			disabled_parsers = {},
			skip_ts_check = false,
			handler = function()
				vim.bo.indentexpr = "v:lua.require'nvim-treesitter'.indentexpr()"
			end,
		},
	},
	ensure_installed = {},
	load_config_mode = "on_filetype", -- Refer to Technicality section
}

⚡ User commands

All in a form of subcommand in TSQueryLoader:

• options:
  • show: Show current merged from base and opts in setup().
  • load_default: Set default base options.
  • load: Set merged base and opts in setup().
• config:
  • show: Show config table of configured parser, query, filetype.
  • show_buf: Show filetype, parser, query for current buffer.
  • load_default: Set table to before any query is found supported.
  • load: Set table to contain all supported queries for parsers.
• autocmd:
  • create: Re-create all autocmds based on current config, options.
  • clear: Clear all autocmds of this plugin.
  • get_all: Show all autocmds set for found filetypes.

🛠️ Technicality

Seem this plugin is over-engineered, convoluted right?

Well, this solves me of some edge cases involving assign which filetype will use which parser, query and how it runs. It starts as a small snippet but then it grows as I often mess around treesitter. Also I don't mine the startup time ~1ms with more tools.

Parsers and queries is provided by nvim-treesitter. Each parser has several corresponding filetype and query. You can find them through:

• Installed parser through vim.api.nvim_get_runtime_file("parser/*.*", true)
• Parser's filetype through vim.treesitter.language.get_filetypes()
• Parser's supported query through vim.treesitter.query.get(). Same way as :checkhealth nvim-treesitter

This plugin mainly use above APIs, some table filtering, as recommended on nvim-treesitter docs.

The flow of plugin is somewhat:

• Find all installed parsers.
• Auto-install parsers from ensure_installed.
• Get all associated filetypes.
• Get all supported queries.
• Filter with options.
• Produce a final config table.
• Every time FileType event is triggered with found filetype above, run a handler (just a configured function in options) for each matching query.

Note

Note, the cost of running function to find parser's supported queries is high. Around 20ms for total of 20 parsers with 2 query checks per parser.

Default to skip highlights query because so far I found 0 parser that doesn't support it.

So I provide skip_ts_check field in options to bypass checking.

Furthermore, load_config_mode field controls when query is found. Greatly decrease startup time, defer to FileType event with only opening filetype.

🎯 Roadmap

• Deeper configuration for each filetype with its own handler, own parser.