Problem:
With incremental injection parsing, injected languages' parsers parse
only the relevant regions and stores the result in _trees with the index
of the corresponding region. Therefore, there can be holes in _trees.
Solution:
* Use generic table functions where appropriate.
* Fix type annotations and docs.
Problem
---
If a highlighter query returns a significant number of predicate
non-matches, the highlighter will scan well past the end of the window.
Solution
---
In the iterator returned from `iter_captures`, accept an optional
parameter `end_line`. If no parameter provided, the behavior is
unchanged, hence this is a non-invasive tweak.
Fixes: #25113nvim-treesitter/nvim-treesitter#5057
The name for_each_child is misleading and caused bugs.
After #25111, #25115, there are no more usages of `for_each_child` in Nvim.
In the future if we want to restore this functionality we can consider a
generalized vim.traverse(node, key, visitor) function.
Problem:
Treesitter highlighting is slow for large files with lots of injections.
Solution:
Only parse injections we are going to render during a redraw cycle.
---
- `LanguageTree:parse()` will no longer parse injections by default and
now requires an explicit range argument to be passed.
- `TSHighlighter` now parses injections incrementally during on_win
callbacks for the line range being rendered.
- Plugins which require certain injections to be parsed must run
`parser:parse({ start_row, end_row })` before using the tree.
* feat(treesitter): add injection language fallback
Problem: injection languages are often specified via aliases (e.g.,
filetype or in upper case), requiring custom directives.
Solution: include lookup logic (try as parser name, then filetype, then
lowercase) in LanguageTree itself and remove `#inject-language`
directive.
Co-authored-by: Lewis Russell <me@lewisr.dev>
Problem:
Lua functions that return multiple results are declared by using
multiple `@return` docstring directives. But the generated docs don't
make it obvious what this represents.
Solution:
- Generate a "Return (multiple)" heading for multiple-value functions.
- Fix `@note` directives randomly placed after `@return`.
Problem:
"playground" is new jargon that overlaps with existing concepts:
"dev" (`:help dev`) and "view" (also "scratch" `:help scratch-buffer`) .
Solution:
We should consistently use "dev" as the namespace for where "developer
tools" live. For purposes of a "throwaway sandbox object", we can use
the name "view".
- Rename `TSPlayground` => `TSView`
- Rename `playground.lua` => `dev.lua`
When injections are added or removed make sure to:
- invoke 'changedtree' callbacks for when new trees are added.
- invoke 'changedtree' callbacks for when trees are invalidated
- redraw regions when languagetree children are removed
Problem:
vim.treesitter.inspect_tree() and :InspectTree does not respect 'splitright'.
Solution:
- Change the default `command` from `topleft 60vnew` to `60vnew`.
- Change :InspectTree to respect command mods (`:vertical`, count, etc.).
Closes#22656
Never return the changes an only notify them using the `on_changedtree`
callback.
It is not guaranteed for a plugin that it'll be the first one to call
`tree:parse()` and thus get the changes.
Closes#19915
Problem:
gen_vimdoc.py / lua2dox.lua does not support @defgroup or \defgroup
except for "api-foo" modules.
Solution:
Modify `gen_vimdoc.py` to look for section names based on `helptag_fmt`.
TODO:
- Support @module ?
https://github.com/LuaLS/lua-language-server/wiki/Annotations#module
Problem:
Help tags like vim.treesitter.language.add() are confusing because
`vim.treesitter.language` is (thankfully) not a user-facing module.
Solution:
Ignore the "fstem" when generating "treesitter" tags.
Problem:
"show" is potentially a new verb that we can avoid (there is already
"open" and "echo"). Even if we can't avoid it, the behavior of
`show_tree` fits well in the "inspect" family of functions: a way for
users to introspect/reflect on the state of Nvim.
Existing "inspect" functions:
vim.inspect()
vim.inspect_pos()
vim.treesitter.inspect_language()
nvim__inspect_cell
Solution:
Rename `show_tree` to `inspect_tree`.
This function replaces both vim.treesitter.get_node_at_pos() and
vim.treesitter.get_node_at_cursor(). These two functions are similar
enough that they don't need separate interfaces. Even worse,
get_node_at_pos() returns a TSNode while get_node_at_cursor() returns a
string, so the two functions behave slightly differently.
vim.treesitter.get_node() combines these two into a more streamlined
interface. With no arguments, it returns the node under the cursor in
the current buffer. Optionally, it can accept a buffer number or a
position to get the node at a given position in a given buffer.
Problem:
vim.treesitter does not know how to map a specific filetype to a parser.
This creates problems since in a few places (including in vim.treesitter itself), the filetype is incorrectly used in place of lang.
Solution:
Add an API to enable this:
- Add vim.treesitter.language.add() as a replacement for vim.treesitter.language.require_language().
- Optional arguments are now passed via an opts table.
- Also takes a filetype (or list of filetypes) so we can keep track of what filetypes are associated with which langs.
- Deprecated vim.treesitter.language.require_language().
- Add vim.treesitter.language.get_lang() which returns the associated lang for a given filetype.
- Add vim.treesitter.language.register() to associate filetypes to a lang without loading the parser.
Problem: Some injections (like markdown) allow specifying arbitrary
language names for code blocks, which may be lead to errors when
looking for a corresponding parser in runtime path.
Solution: Validate that the language name only contains alphanumeric
characters and `_` (e.g., for `c_sharp`) and error otherwise.
Add a "show_tree" function to view a textual representation of the
nodes in a language tree in a window. Moving the cursor in the
window highlights the corresponding text in the source buffer, and
moving the cursor in the source buffer highlights the corresponding
nodes in the window.
Problem: Captures used by bundled parsers are not highlighted by default
Solution: Add links to default groups
A link is added for a capture if
* there is a default group of the same name (e.g., `@tag` -> `Tag`)
* it's used in a bundled query and doesn't have a reasonable fallback
(e.g., `@text.literal`)
Also add all linked groups to the treesitter docs.
Problem:
The {foo} parameters listed in `:help api` and similar generated docs,
are intended to be a "list" but they aren't prefixed with a list symbol.
This prevents parsers from understanding the list, which forces
generators like `gen_help_html.lua` to use hard-wrapped/preformatted
layout instead of a soft-wrapped "flow" layout.
Solution:
Modify gen_vimdoc.py to prefix {foo} parameters with a "•" symbol.
fix(treesitter): get_captures_at_position returns metadata
Return the full `metadata` table for the capture instead of just the
priority.
Further cleanup of related docs.
Use the first, not last, query for a language on runtimepath. Typically,
this implies that a user query will override a site plugin query, which
will override a bundled runtime query.
Problem: Treesitter queries for a given language in runtime were merged together,
leading to errors if they targeted different parser versions (e.g., bundled viml queries
and those shipped by nvim-treesitter).
Solution: Runtime queries now work as follows:
* The last query in the rtp without `; extends` in the header will be used as the base query
* All queries (without a specific order) with `; extends` are concatenated with the base query
BREAKING CHANGE: queries need to be updated if they are meant to extend other queries
* Add vim.treesitter.start() for starting treesitter highlighting via
ftplugin or autocommand (can be extended later for fold, indent,
matchpairs, ...)
* Add vim.treesitter.stop() for manually stopping treesitter
highlighting
* Enable treesitter highlighting for Lua if
`vim.g.ts_highlight_lua = true` is set in `init.lua`
This removes the support for defining links via
vim.treesitter.highlighter.hl_map (never documented, but plugins did
anyway), or the uppercase-only `@FooGroup.Bar` to `FooGroup` rule.
The fallback is now strictly `@foo.bar.lang` to `@foo.bar` to `@foo`,
and casing is irrelevant (as it already was outside of treesitter)
For compatibility, define default links to builting syntax groups
as defined by pre-existing color schemes
Previously the `offset!` directive populated the metadata in such a way
that the new range could be attributed to a specific capture. #14046
made it so the directive simply stored just the new range in the
metadata and information about what capture the range is based from is
lost.
This change reverts that whilst also correcting the docs.
This will check if the string after the variable in a @param is either
"number", "string", "table", "boolean" and "function" and if so add a
parenthesis around it. This will help separate the variable type with
the following text. Had all our functions been annotated with emmylua
then a more robust solution might have been preferable (such as always
assuming the third string is parameter type without making any checks).
I believe however this is a clear improvement over the current situation
and will suffice for now.
Co-authored-by: Sean Dewar <seandewar@users.noreply.github.com>
Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: Sebastian Volland <seb@baunz.net>
Co-authored-by: Lewis Russell <lewis6991@gmail.com>
Co-authored-by: zeertzjq <zeertzjq@outlook.com>
