Skip to content

Commit

Permalink
feat(treesitter)!: deprecate top level indexes to modules (#22761)
Browse files Browse the repository at this point in the history 
The following top level Treesitter functions have been moved:
  - vim.treesitter.inspect_language() -> vim.treesitter.language.inspect()
  - vim.treesitter.get_query_files() -> vim.treesitter.query.get_files()
  - vim.treesitter.set_query() -> vim.treesitter.query.set()
  - vim.treesitter.query.set_query() -> vim.treesitter.query.set()
  - vim.treesitter.get_query() -> vim.treesitter.query.get()
  - vim.treesitter.query.get_query() -> vim.treesitter.query.get()
  - vim.treesitter.parse_query() -> vim.treesitter.query.parse()
  - vim.treesitter.query.parse_query() -> vim.treesitter.query.parse()
  - vim.treesitter.add_predicate() -> vim.treesitter.query.add_predicate()
  - vim.treesitter.add_directive() -> vim.treesitter.query.add_directive()
  - vim.treesitter.list_predicates() -> vim.treesitter.query.list_predicates()
  - vim.treesitter.list_directives() -> vim.treesitter.query.list_directives()
  - vim.treesitter.query.get_range() -> vim.treesitter.get_range()
  - vim.treesitter.query.get_node_text() -> vim.treesitter.get_node_text()
  • Loading branch information
@lewis6991
lewis6991 committed Mar 24, 2023
1 parent ee5008f commit cbbf8bd
Show file tree
Hide file tree
Showing 13 changed files with 258 additions and 177 deletions.
2 changes: 1 addition & 1 deletion runtime/doc/deprecated.txt
View file
Expand Up @@ -122,7 +122,7 @@ LSP FUNCTIONS
or |vim.lsp.buf.format()| instead.

TREESITTER FUNCTIONS
- *vim.treesitter.language.require_language()* Use |vim.treesitter.add()|
- *vim.treesitter.language.require_language()* Use |vim.treesitter.language.add()|
instead.
- *vim.treesitter.get_node_at_pos()* Use |vim.treesitter.get_node()|
instead.
Expand Down
24 changes: 20 additions & 4 deletions runtime/doc/news.txt
View file
Expand Up @@ -180,9 +180,9 @@ The following new APIs or features were added.
more complicated dynamic language injections.

• |vim.treesitter.get_node_text()| now accepts a `metadata` option for
writing custom directives using |vim.treesitter.add_directive()|.
writing custom directives using |vim.treesitter.query.add_directive()|.

• |vim.treesitter.add()| replaces `vim.treesitter.language.require_language`.
• |vim.treesitter.language.add()| replaces `vim.treesitter.language.require_language`.

• `require'bit'` is now always available |lua-bit|

Expand Down Expand Up @@ -217,7 +217,7 @@ The following new APIs or features were added.

• |vim.filetype.get_option()| to get the default option value for a specific
filetype. This is a wrapper around |nvim_get_option_value()| with caching.

• Added |nvim_get_hl()| for getting highlight group definitions in a format compatible with |nvim_set_hl()|.

==============================================================================
Expand Down Expand Up @@ -275,11 +275,27 @@ DEPRECATIONS *news-deprecations*
The following functions are now deprecated and will be removed in the next
release.

• |vim.treesitter.add()| replaces `vim.treesitter.language.require_language()`
• |vim.treesitter.language.add()| replaces `vim.treesitter.language.require_language()`

• |vim.treesitter.get_node_at_pos()| and |vim.treesitter.get_node_at_cursor()|
are both deprecated in favor of |vim.treesitter.get_node()|.

• `vim.api.nvim_get_hl_by_name()`, `vim.api.nvim_get_hl_by_id()` were deprecated, use |nvim_get_hl()| instead.

• The following top level Treesitter functions have been moved:
`vim.treesitter.inspect_language()` -> `vim.treesitter.language.inspect()`
`vim.treesitter.get_query_files()` -> `vim.treesitter.query.get_files()`
`vim.treesitter.set_query()` -> `vim.treesitter.query.set()`
`vim.treesitter.query.set_query()` -> `vim.treesitter.query.set()`
`vim.treesitter.get_query()` -> `vim.treesitter.query.get()`
`vim.treesitter.query.get_query()` -> `vim.treesitter.query.get()`
`vim.treesitter.parse_query()` -> `vim.treesitter.query.parse()`
`vim.treesitter.query.parse_query()` -> `vim.treesitter.query.parse()`
`vim.treesitter.add_predicate()` -> `vim.treesitter.query.add_predicate()`
`vim.treesitter.add_directive()` -> `vim.treesitter.query.add_directive()`
`vim.treesitter.list_predicates()` -> `vim.treesitter.query.list_predicates()`
`vim.treesitter.list_directives()` -> `vim.treesitter.query.list_directives()`
`vim.treesitter.query.get_range()` -> `vim.treesitter.get_range()`
`vim.treesitter.query.get_node_text()` -> `vim.treesitter.get_node_text()`

vim:tw=78:ts=8:sw=2:et:ft=help:norl:
96 changes: 48 additions & 48 deletions runtime/doc/treesitter.txt
View file
Expand Up @@ -26,7 +26,7 @@ If multiple parsers for the same language are found, the first one is used.
(This typically implies the priority "user config > plugins > bundled".
A parser can also be loaded manually using a full path: >lua

vim.treesitter.require_language("python", "/path/to/python.so")
vim.treesitter.language.add('python', { path = "/path/to/python.so" })
<
==============================================================================
TREESITTER TREES *treesitter-tree*
Expand Down Expand Up @@ -236,8 +236,8 @@ The following predicates are built in:
Each predicate has a `not-` prefixed predicate that is just the negation of
the predicate.

Further predicates can be added via |vim.treesitter.add_predicate()|.
Use |vim.treesitter.list_predicates()| to list all available predicates.
Further predicates can be added via |vim.treesitter.query.add_predicate()|.
Use |vim.treesitter.query.list_predicates()| to list all available predicates.


TREESITTER QUERY DIRECTIVES *treesitter-directives*
Expand Down Expand Up @@ -279,8 +279,8 @@ The following directives are built in:
((identifier) @constant (#offset! @constant 0 1 0 -1))
<

Further directives can be added via |vim.treesitter.add_directive()|.
Use |vim.treesitter.list_directives()| to list all available directives.
Further directives can be added via |vim.treesitter.query.add_directive()|.
Use |vim.treesitter.query.list_directives()| to list all available directives.


TREESITTER QUERY MODELINES *treesitter-query-modeline*
Expand Down Expand Up @@ -575,6 +575,22 @@ get_node_range({node_or_range}) *vim.treesitter.get_node_range()*
(integer) end_row
(integer) end_col

*vim.treesitter.get_node_text()*
get_node_text({node}, {source}, {opts})
Gets the text corresponding to a given node

Parameters: ~
• {node} |TSNode|
• {source} (integer|string) Buffer or string from which the {node} is
extracted
• {opts} (table|nil) Optional parameters.
• metadata (table) Metadata of a specific capture. This
would be set to `metadata[capture_id]` when using
|vim.treesitter.query.add_directive()|.

Return: ~
(string)

get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()*
Returns the parser for a specific buffer and filetype and attaches it to
the buffer
Expand All @@ -591,6 +607,19 @@ get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()*
Return: ~
|LanguageTree| object to use for parsing

get_range({node}, {source}, {metadata}) *vim.treesitter.get_range()*
Get the range of a |TSNode|. Can also supply {source} and {metadata} to
get the range with directives applied.

Parameters: ~
• {node} |TSNode|
• {source} integer|string|nil Buffer or string from which the {node}
is extracted
• {metadata} TSMetadata|nil

Return: ~
(table)

*vim.treesitter.get_string_parser()*
get_string_parser({str}, {lang}, {opts})
Returns a string parser
Expand Down Expand Up @@ -698,7 +727,7 @@ stop({bufnr}) *vim.treesitter.stop()*
==============================================================================
Lua module: vim.treesitter.language *lua-treesitter-language*

add({lang}, {opts}) *vim.treesitter.add()*
add({lang}, {opts}) *vim.treesitter.language.add()*
Asserts that a parser for the language {lang} is installed.

Parsers are searched in the `parser` runtime directory, or the provided
Expand All @@ -716,14 +745,14 @@ add({lang}, {opts}) *vim.treesitter.add()*
• symbol_name (string|nil) Internal symbol name for the
language to load

get_lang({filetype}) *vim.treesitter.get_lang()*
get_lang({filetype}) *vim.treesitter.language.get_lang()*
Parameters: ~
• {filetype} (string)

Return: ~
(string|nil)

inspect_language({lang}) *vim.treesitter.inspect_language()*
inspect({lang}) *vim.treesitter.language.inspect()*
Inspects the provided language.

Inspecting provides some useful information on the language like node
Expand All @@ -735,7 +764,7 @@ inspect_language({lang}) *vim.treesitter.inspect_language()*
Return: ~
(table)

register({lang}, {filetype}) *vim.treesitter.register()*
register({lang}, {filetype}) *vim.treesitter.language.register()*
Register a lang to be used for a filetype (or list of filetypes).

Parameters: ~
Expand All @@ -746,7 +775,7 @@ register({lang}, {filetype}) *vim.treesitter.register()*
==============================================================================
Lua module: vim.treesitter.query *lua-treesitter-query*

*vim.treesitter.add_directive()*
*vim.treesitter.query.add_directive()*
add_directive({name}, {handler}, {force})
Adds a new directive to be used in queries

Expand All @@ -768,35 +797,19 @@ add_directive({name}, {handler}, {force})
the predicate `{ "#set!", "conceal", "-" }`
• {force} (boolean|nil)

*vim.treesitter.add_predicate()*
*vim.treesitter.query.add_predicate()*
add_predicate({name}, {handler}, {force})
Adds a new predicate to be used in queries

Parameters: ~
• {name} (string) Name of the predicate, without leading #
• {handler} function(match:table<string,|TSNode|>, pattern:string,
bufnr:integer, predicate:string[])
• see |vim.treesitter.add_directive()| for argument
• see |vim.treesitter.query.add_directive()| for argument
meanings
• {force} (boolean|nil)

*vim.treesitter.get_node_text()*
get_node_text({node}, {source}, {opts})
Gets the text corresponding to a given node

Parameters: ~
• {node} |TSNode|
• {source} (integer|string) Buffer or string from which the {node} is
extracted
• {opts} (table|nil) Optional parameters.
• metadata (table) Metadata of a specific capture. This
would be set to `metadata[capture_id]` when using
|vim.treesitter.add_directive()|.

Return: ~
(string)

get_query({lang}, {query_name}) *vim.treesitter.get_query()*
get({lang}, {query_name}) *vim.treesitter.query.get()*
Returns the runtime query {query_name} for {lang}.

Parameters: ~
Expand All @@ -806,8 +819,8 @@ get_query({lang}, {query_name}) *vim.treesitter.get_query()*
Return: ~
Query|nil Parsed query

*vim.treesitter.get_query_files()*
get_query_files({lang}, {query_name}, {is_included})
*vim.treesitter.query.get_files()*
get_files({lang}, {query_name}, {is_included})
Gets the list of files used to make up a query

Parameters: ~
Expand All @@ -820,32 +833,19 @@ get_query_files({lang}, {query_name}, {is_included})
string[] query_files List of files to load for given query and
language

get_range({node}, {source}, {metadata}) *vim.treesitter.get_range()*
Get the range of a |TSNode|. Can also supply {source} and {metadata} to
get the range with directives applied.

Parameters: ~
• {node} |TSNode|
• {source} integer|string|nil Buffer or string from which the {node}
is extracted
• {metadata} TSMetadata|nil

Return: ~
(table)

list_directives() *vim.treesitter.list_directives()*
list_directives() *vim.treesitter.query.list_directives()*
Lists the currently available directives to use in queries.

Return: ~
string[] List of supported directives.

list_predicates() *vim.treesitter.list_predicates()*
list_predicates() *vim.treesitter.query.list_predicates()*
Lists the currently available predicates to use in queries.

Return: ~
string[] List of supported predicates.

parse_query({lang}, {query}) *vim.treesitter.parse_query()*
parse({lang}, {query}) *vim.treesitter.query.parse()*
Parse {query} as a string. (If the query is in a file, the caller should
read the contents into a string before calling).

Expand Down Expand Up @@ -935,7 +935,7 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop})
(fun(): integer, table<integer,TSNode>, table): pattern id, match,
metadata

set_query({lang}, {query_name}, {text}) *vim.treesitter.set_query()*
set({lang}, {query_name}, {text}) *vim.treesitter.query.set()*
Sets the runtime query named {query_name} for {lang}

This allows users to override any runtime files and/or configuration set
Expand Down

0 comments on commit cbbf8bd

Please sign in to comment.