mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-06 19:38:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #19685 from ii14/gen_vimdoc_indentation

Browse Source 
docs: change gen_vimdoc indentation level
This commit is contained in:
Christian Clason
2022-08-11 14:34:00 +02:00
committed by GitHub
parent 94c3176478 ea333badd2
commit d1fb0dd8b9
6 changed files with 5007 additions and 5561 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2054
runtime/doc/api.txt
View File

File diff suppressed because it is too large Load Diff

408
runtime/doc/diagnostic.txt
View File

@@ -304,14 +304,13 @@ Example: >
Lua module: vim.diagnostic *diagnostic-api* Lua module: vim.diagnostic *diagnostic-api*
config({opts}, {namespace}) *vim.diagnostic.config()* config({opts}, {namespace}) *vim.diagnostic.config()*
Configure diagnostic options globally or for a specific Configure diagnostic options globally or for a specific diagnostic
diagnostic namespace. namespace.
Configuration can be specified globally, per-namespace, or Configuration can be specified globally, per-namespace, or ephemerally
ephemerally (i.e. only for a single call to (i.e. only for a single call to |vim.diagnostic.set()| or
|vim.diagnostic.set()| or |vim.diagnostic.show()|). Ephemeral |vim.diagnostic.show()|). Ephemeral configuration has highest priority,
configuration has highest priority, followed by namespace followed by namespace configuration, and finally global configuration.
configuration, and finally global configuration.
For example, if a user enables virtual text globally with > For example, if a user enables virtual text globally with >
@@ -326,48 +325,41 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
then virtual text will not be enabled for those diagnostics. then virtual text will not be enabled for those diagnostics.
Note: Note:
Each of the configuration options below accepts one of the Each of the configuration options below accepts one of the following:
following:
• `false`: Disable this feature • `false`: Disable this feature
• `true`: Enable this feature, use default settings. • `true`: Enable this feature, use default settings.
• `table`: Enable this feature with overrides. Use an • `table`: Enable this feature with overrides. Use an empty table to
empty table to use default values. use default values.
• `function`: Function with signature (namespace, bufnr) • `function`: Function with signature (namespace, bufnr) that returns
that returns any of the above. any of the above.
Parameters: ~ Parameters: ~
{opts} (table|nil) When omitted or "nil", retrieve {opts} (table|nil) When omitted or "nil", retrieve the current
the current configuration. Otherwise, a configuration. Otherwise, a configuration table with the
configuration table with the following keys: following keys:
• underline: (default true) Use underline for • underline: (default true) Use underline for
diagnostics. Options: diagnostics. Options:
• severity: Only underline diagnostics • severity: Only underline diagnostics matching the
matching the given severity given severity |diagnostic-severity|
|diagnostic-severity|
• virtual_text: (default true) Use virtual • virtual_text: (default true) Use virtual text for
text for diagnostics. If multiple diagnostics. If multiple diagnostics are set for a
diagnostics are set for a namespace, one namespace, one prefix per diagnostic + the last
prefix per diagnostic + the last diagnostic diagnostic message are shown. Options:
message are shown. Options: • severity: Only show virtual text for diagnostics
• severity: Only show virtual text for matching the given severity |diagnostic-severity|
diagnostics matching the given severity • source: (boolean or string) Include the diagnostic
|diagnostic-severity| source in virtual text. Use "if_many" to only show
• source: (boolean or string) Include the sources if there is more than one diagnostic source
diagnostic source in virtual text. Use in the buffer. Otherwise, any truthy value means to
"if_many" to only show sources if there always show the diagnostic source.
is more than one diagnostic source in the • spacing: (number) Amount of empty spaces inserted at
buffer. Otherwise, any truthy value means the beginning of the virtual text.
to always show the diagnostic source. • prefix: (string) Prepend diagnostic message with
• spacing: (number) Amount of empty spaces prefix.
inserted at the beginning of the virtual • format: (function) A function that takes a diagnostic
text. as input and returns a string. The return value is
• prefix: (string) Prepend diagnostic the text used to display the diagnostic. Example: >
message with prefix.
• format: (function) A function that takes
a diagnostic as input and returns a
string. The return value is the text used
to display the diagnostic. Example: >
function(diagnostic) function(diagnostic)
if diagnostic.severity == vim.diagnostic.severity.ERROR then if diagnostic.severity == vim.diagnostic.severity.ERROR then
@@ -377,60 +369,53 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
end end
< <
• signs: (default true) Use signs for • signs: (default true) Use signs for diagnostics.
diagnostics. Options: Options:
• severity: Only show signs for diagnostics • severity: Only show signs for diagnostics matching
matching the given severity the given severity |diagnostic-severity|
|diagnostic-severity| • priority: (number, default 10) Base priority to use
• priority: (number, default 10) Base for signs. When {severity_sort} is used, the priority
priority to use for signs. When of a sign is adjusted based on its severity.
{severity_sort} is used, the priority of Otherwise, all signs use the same priority.
a sign is adjusted based on its severity.
Otherwise, all signs use the same
priority.
• float: Options for floating windows. See • float: Options for floating windows. See
|vim.diagnostic.open_float()|. |vim.diagnostic.open_float()|.
• update_in_insert: (default false) Update • update_in_insert: (default false) Update diagnostics in
diagnostics in Insert mode (if false, Insert mode (if false, diagnostics are updated on
diagnostics are updated on InsertLeave) InsertLeave)
• severity_sort: (default false) Sort • severity_sort: (default false) Sort diagnostics by
diagnostics by severity. This affects the severity. This affects the order in which signs and
order in which signs and virtual text are virtual text are displayed. When true, higher
displayed. When true, higher severities are severities are displayed before lower severities (e.g.
displayed before lower severities (e.g.
ERROR is displayed before WARN). Options: ERROR is displayed before WARN). Options:
• reverse: (boolean) Reverse sort order • reverse: (boolean) Reverse sort order
{namespace} (number|nil) Update the options for the given {namespace} (number|nil) Update the options for the given namespace.
namespace. When omitted, update the global When omitted, update the global diagnostic options.
diagnostic options.
disable({bufnr}, {namespace}) *vim.diagnostic.disable()* disable({bufnr}, {namespace}) *vim.diagnostic.disable()*
Disable diagnostics in the given buffer. Disable diagnostics in the given buffer.
Parameters: ~ Parameters: ~
{bufnr} (number|nil) Buffer number, or 0 for current {bufnr} (number|nil) Buffer number, or 0 for current buffer. When
buffer. When omitted, disable diagnostics in omitted, disable diagnostics in all buffers.
all buffers. {namespace} (number|nil) Only disable diagnostics for the given
{namespace} (number|nil) Only disable diagnostics for the namespace.
given namespace.
enable({bufnr}, {namespace}) *vim.diagnostic.enable()* enable({bufnr}, {namespace}) *vim.diagnostic.enable()*
Enable diagnostics in the given buffer. Enable diagnostics in the given buffer.
Parameters: ~ Parameters: ~
{bufnr} (number|nil) Buffer number, or 0 for current {bufnr} (number|nil) Buffer number, or 0 for current buffer. When
buffer. When omitted, enable diagnostics in omitted, enable diagnostics in all buffers.
all buffers. {namespace} (number|nil) Only enable diagnostics for the given
{namespace} (number|nil) Only enable diagnostics for the namespace.
given namespace.
fromqflist({list}) *vim.diagnostic.fromqflist()* fromqflist({list}) *vim.diagnostic.fromqflist()*
Convert a list of quickfix items to a list of diagnostics. Convert a list of quickfix items to a list of diagnostics.
Parameters: ~ Parameters: ~
{list} (table) A list of quickfix items from {list} (table) A list of quickfix items from |getqflist()| or
|getqflist()| or |getloclist()|. |getloclist()|.
Return: ~ Return: ~
array of diagnostics |diagnostic-structure| array of diagnostics |diagnostic-structure|
@@ -439,14 +424,12 @@ get({bufnr}, {opts}) *vim.diagnostic.get()*
Get current diagnostics. Get current diagnostics.
Parameters: ~ Parameters: ~
{bufnr} (number|nil) Buffer number to get diagnostics {bufnr} (number|nil) Buffer number to get diagnostics from. Use 0 for
from. Use 0 for current buffer or nil for all current buffer or nil for all buffers.
buffers.
{opts} (table|nil) A table with the following keys: {opts} (table|nil) A table with the following keys:
• namespace: (number) Limit diagnostics to the • namespace: (number) Limit diagnostics to the given
given namespace. namespace.
• lnum: (number) Limit diagnostics to the given • lnum: (number) Limit diagnostics to the given line number.
line number.
• severity: See |diagnostic-severity|. • severity: See |diagnostic-severity|.
Return: ~ Return: ~
@@ -465,8 +448,7 @@ get_namespaces() *vim.diagnostic.get_namespaces()*
Get current diagnostic namespaces. Get current diagnostic namespaces.
Return: ~ Return: ~
(table) A list of active diagnostic namespaces (table) A list of active diagnostic namespaces |vim.diagnostic|.
|vim.diagnostic|.
get_next({opts}) *vim.diagnostic.get_next()* get_next({opts}) *vim.diagnostic.get_next()*
Get the next diagnostic closest to the cursor position. Get the next diagnostic closest to the cursor position.
@@ -478,8 +460,7 @@ get_next({opts}) *vim.diagnostic.get_next()*
(table) Next diagnostic (table) Next diagnostic
get_next_pos({opts}) *vim.diagnostic.get_next_pos()* get_next_pos({opts}) *vim.diagnostic.get_next_pos()*
Return the position of the next diagnostic in the current Return the position of the next diagnostic in the current buffer.
buffer.
Parameters: ~ Parameters: ~
{opts} (table) See |vim.diagnostic.goto_next()| {opts} (table) See |vim.diagnostic.goto_next()|
@@ -497,37 +478,32 @@ get_prev({opts}) *vim.diagnostic.get_prev()*
(table) Previous diagnostic (table) Previous diagnostic
get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()* get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()*
Return the position of the previous diagnostic in the current Return the position of the previous diagnostic in the current buffer.
buffer.
Parameters: ~ Parameters: ~
{opts} (table) See |vim.diagnostic.goto_next()| {opts} (table) See |vim.diagnostic.goto_next()|
Return: ~ Return: ~
(table) Previous diagnostic position as a (row, col) (table) Previous diagnostic position as a (row, col) tuple.
tuple.
goto_next({opts}) *vim.diagnostic.goto_next()* goto_next({opts}) *vim.diagnostic.goto_next()*
Move to the next diagnostic. Move to the next diagnostic.
Parameters: ~ Parameters: ~
{opts} (table|nil) Configuration table with the following {opts} (table|nil) Configuration table with the following keys:
keys: • namespace: (number) Only consider diagnostics from the given
• namespace: (number) Only consider diagnostics namespace.
from the given namespace. • cursor_position: (cursor position) Cursor position as a
• cursor_position: (cursor position) Cursor (row, col) tuple. See |nvim_win_get_cursor()|. Defaults to
position as a (row, col) tuple. See the current cursor position.
|nvim_win_get_cursor()|. Defaults to the current • wrap: (boolean, default true) Whether to loop around file or
cursor position. not. Similar to 'wrapscan'.
• wrap: (boolean, default true) Whether to loop
around file or not. Similar to 'wrapscan'.
• severity: See |diagnostic-severity|. • severity: See |diagnostic-severity|.
• float: (boolean or table, default true) If • float: (boolean or table, default true) If "true", call
"true", call |vim.diagnostic.open_float()| after |vim.diagnostic.open_float()| after moving. If a table, pass
moving. If a table, pass the table as the {opts} the table as the {opts} parameter to
parameter to |vim.diagnostic.open_float()|. |vim.diagnostic.open_float()|. Unless overridden, the float
Unless overridden, the float will show will show diagnostics at the new cursor position (as if
diagnostics at the new cursor position (as if
"cursor" were passed to the "scope" option). "cursor" were passed to the "scope" option).
• win_id: (number, default 0) Window ID • win_id: (number, default 0) Window ID
@@ -540,21 +516,18 @@ goto_prev({opts}) *vim.diagnostic.goto_prev()*
hide({namespace}, {bufnr}) *vim.diagnostic.hide()* hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
Hide currently displayed diagnostics. Hide currently displayed diagnostics.
This only clears the decorations displayed in the buffer. This only clears the decorations displayed in the buffer. Diagnostics can
Diagnostics can be redisplayed with |vim.diagnostic.show()|. be redisplayed with |vim.diagnostic.show()|. To completely remove
To completely remove diagnostics, use diagnostics, use |vim.diagnostic.reset()|.
|vim.diagnostic.reset()|.
To hide diagnostics and prevent them from re-displaying, use To hide diagnostics and prevent them from re-displaying, use
|vim.diagnostic.disable()|. |vim.diagnostic.disable()|.
Parameters: ~ Parameters: ~
{namespace} (number|nil) Diagnostic namespace. When {namespace} (number|nil) Diagnostic namespace. When omitted, hide
omitted, hide diagnostics from all diagnostics from all namespaces.
namespaces. {bufnr} (number|nil) Buffer number, or 0 for current buffer. When
{bufnr} (number|nil) Buffer number, or 0 for current omitted, hide diagnostics in all buffers.
buffer. When omitted, hide diagnostics in all
buffers.
*vim.diagnostic.match()* *vim.diagnostic.match()*
match({str}, {pat}, {groups}, {severity_map}, {defaults}) match({str}, {pat}, {groups}, {severity_map}, {defaults})
@@ -565,8 +538,7 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
WARNING filename:27:3: Variable 'foo' does not exist WARNING filename:27:3: Variable 'foo' does not exist
< <
This can be parsed into a diagnostic |diagnostic-structure| This can be parsed into a diagnostic |diagnostic-structure| with: >
with: >
local s = "WARNING filename:27:3: Variable 'foo' does not exist" local s = "WARNING filename:27:3: Variable 'foo' does not exist"
local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
@@ -577,81 +549,66 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
Parameters: ~ Parameters: ~
{str} (string) String to parse diagnostics from. {str} (string) String to parse diagnostics from.
{pat} (string) Lua pattern with capture groups. {pat} (string) Lua pattern with capture groups.
{groups} (table) List of fields in a {groups} (table) List of fields in a |diagnostic-structure| to
|diagnostic-structure| to associate with associate with captures from {pat}.
captures from {pat}. {severity_map} (table) A table mapping the severity field from
{severity_map} (table) A table mapping the severity field {groups} with an item from |vim.diagnostic.severity|.
from {groups} with an item from {defaults} (table|nil) Table of default values for any fields not
|vim.diagnostic.severity|. listed in {groups}. When omitted, numeric values
{defaults} (table|nil) Table of default values for default to 0 and "severity" defaults to ERROR.
any fields not listed in {groups}. When
omitted, numeric values default to 0 and
"severity" defaults to ERROR.
Return: ~ Return: ~
diagnostic |diagnostic-structure| or `nil` if {pat} fails diagnostic |diagnostic-structure| or `nil` if {pat} fails to match
to match {str}. {str}.
open_float({opts}, {...}) *vim.diagnostic.open_float()* open_float({opts}, {...}) *vim.diagnostic.open_float()*
Show diagnostics in a floating window. Show diagnostics in a floating window.
Parameters: ~ Parameters: ~
{opts} (table|nil) Configuration table with the same keys {opts} (table|nil) Configuration table with the same keys as
as |vim.lsp.util.open_floating_preview()| in |vim.lsp.util.open_floating_preview()| in addition to the
addition to the following: following:
• bufnr: (number) Buffer number to show • bufnr: (number) Buffer number to show diagnostics from.
diagnostics from. Defaults to the current Defaults to the current buffer.
buffer. • namespace: (number) Limit diagnostics to the given namespace
• namespace: (number) Limit diagnostics to the • scope: (string, default "line") Show diagnostics from the
given namespace whole buffer ("buffer"), the current cursor line ("line"),
• scope: (string, default "line") Show diagnostics or the current cursor position ("cursor"). Shorthand
from the whole buffer ("buffer"), the current versions are also accepted ("c" for "cursor", "l" for
cursor line ("line"), or the current cursor "line", "b" for "buffer").
position ("cursor"). Shorthand versions are also • pos: (number or table) If {scope} is "line" or "cursor", use
accepted ("c" for "cursor", "l" for "line", "b" this position rather than the cursor position. If a number,
for "buffer"). interpreted as a line number; otherwise, a (row, col) tuple.
• pos: (number or table) If {scope} is "line" or • severity_sort: (default false) Sort diagnostics by severity.
"cursor", use this position rather than the Overrides the setting from |vim.diagnostic.config()|.
cursor position. If a number, interpreted as a • severity: See |diagnostic-severity|. Overrides the setting
line number; otherwise, a (row, col) tuple. from |vim.diagnostic.config()|.
• severity_sort: (default false) Sort diagnostics • header: (string or table) String to use as the header for
by severity. Overrides the setting from the floating window. If a table, it is interpreted as a
[text, hl_group] tuple. Overrides the setting from
|vim.diagnostic.config()|. |vim.diagnostic.config()|.
• severity: See |diagnostic-severity|. Overrides • source: (boolean or string) Include the diagnostic source in
the setting from |vim.diagnostic.config()|. the message. Use "if_many" to only show sources if there is
• header: (string or table) String to use as the more than one source of diagnostics in the buffer.
header for the floating window. If a table, it Otherwise, any truthy value means to always show the
is interpreted as a [text, hl_group] tuple.
Overrides the setting from
|vim.diagnostic.config()|.
• source: (boolean or string) Include the
diagnostic source in the message. Use "if_many"
to only show sources if there is more than one
source of diagnostics in the buffer. Otherwise,
any truthy value means to always show the
diagnostic source. Overrides the setting from diagnostic source. Overrides the setting from
|vim.diagnostic.config()|. |vim.diagnostic.config()|.
• format: (function) A function that takes a • format: (function) A function that takes a diagnostic as
diagnostic as input and returns a string. The input and returns a string. The return value is the text
return value is the text used to display the used to display the diagnostic. Overrides the setting from
diagnostic. Overrides the setting from
|vim.diagnostic.config()|. |vim.diagnostic.config()|.
• prefix: (function, string, or table) Prefix each • prefix: (function, string, or table) Prefix each diagnostic
diagnostic in the floating window. If a in the floating window. If a function, it must have the
function, it must have the signature signature (diagnostic, i, total) -> (string, string), where
(diagnostic, i, total) -> (string, string), {i} is the index of the diagnostic being evaluated and
where {i} is the index of the diagnostic being {total} is the total number of diagnostics displayed in the
evaluated and {total} is the total number of window. The function should return a string which is
diagnostics displayed in the window. The prepended to each diagnostic in the window as well as an
function should return a string which is (optional) highlight group which will be used to highlight
prepended to each diagnostic in the window as the prefix. If {prefix} is a table, it is interpreted as a
well as an (optional) highlight group which will [text, hl_group] tuple as in |nvim_echo()|; otherwise, if
be used to highlight the prefix. If {prefix} is {prefix} is a string, it is prepended to each diagnostic in
a table, it is interpreted as a [text, hl_group] the window with no highlight. Overrides the setting from
tuple as in |nvim_echo()|; otherwise, if
{prefix} is a string, it is prepended to each
diagnostic in the window with no highlight.
Overrides the setting from
|vim.diagnostic.config()|. |vim.diagnostic.config()|.
Return: ~ Return: ~
@@ -660,19 +617,16 @@ open_float({opts}, {...}) *vim.diagnostic.open_float()*
reset({namespace}, {bufnr}) *vim.diagnostic.reset()* reset({namespace}, {bufnr}) *vim.diagnostic.reset()*
Remove all diagnostics from the given namespace. Remove all diagnostics from the given namespace.
Unlike |vim.diagnostic.hide()|, this function removes all Unlike |vim.diagnostic.hide()|, this function removes all saved
saved diagnostics. They cannot be redisplayed using diagnostics. They cannot be redisplayed using |vim.diagnostic.show()|. To
|vim.diagnostic.show()|. To simply remove diagnostic simply remove diagnostic decorations in a way that they can be
decorations in a way that they can be re-displayed, use re-displayed, use |vim.diagnostic.hide()|.
|vim.diagnostic.hide()|.
Parameters: ~ Parameters: ~
{namespace} (number|nil) Diagnostic namespace. When {namespace} (number|nil) Diagnostic namespace. When omitted, remove
omitted, remove diagnostics from all diagnostics from all namespaces.
namespaces. {bufnr} (number|nil) Remove diagnostics for the given buffer.
{bufnr} (number|nil) Remove diagnostics for the given When omitted, diagnostics are removed for all buffers.
buffer. When omitted, diagnostics are removed
for all buffers.
set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()* set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()*
Set diagnostics for the given namespace and buffer. Set diagnostics for the given namespace and buffer.
@@ -689,30 +643,28 @@ setloclist({opts}) *vim.diagnostic.setloclist()*
Add buffer diagnostics to the location list. Add buffer diagnostics to the location list.
Parameters: ~ Parameters: ~
{opts} (table|nil) Configuration table with the following {opts} (table|nil) Configuration table with the following keys:
keys: • namespace: (number) Only add diagnostics from the given
• namespace: (number) Only add diagnostics from namespace.
the given namespace. • winnr: (number, default 0) Window number to set location
• winnr: (number, default 0) Window number to set list for.
location list for. • open: (boolean, default true) Open the location list after
• open: (boolean, default true) Open the location setting.
list after setting. • title: (string) Title of the location list. Defaults to
• title: (string) Title of the location list. "Diagnostics".
Defaults to "Diagnostics".
• severity: See |diagnostic-severity|. • severity: See |diagnostic-severity|.
setqflist({opts}) *vim.diagnostic.setqflist()* setqflist({opts}) *vim.diagnostic.setqflist()*
Add all diagnostics to the quickfix list. Add all diagnostics to the quickfix list.
Parameters: ~ Parameters: ~
{opts} (table|nil) Configuration table with the following {opts} (table|nil) Configuration table with the following keys:
keys: • namespace: (number) Only add diagnostics from the given
• namespace: (number) Only add diagnostics from namespace.
the given namespace. • open: (boolean, default true) Open quickfix list after
• open: (boolean, default true) Open quickfix list setting.
after setting. • title: (string) Title of quickfix list. Defaults to
• title: (string) Title of quickfix list. Defaults "Diagnostics".
to "Diagnostics".
• severity: See |diagnostic-severity|. • severity: See |diagnostic-severity|.
*vim.diagnostic.show()* *vim.diagnostic.show()*
@@ -720,31 +672,27 @@ show({namespace}, {bufnr}, {diagnostics}, {opts})
Display diagnostics for the given namespace and buffer. Display diagnostics for the given namespace and buffer.
Parameters: ~ Parameters: ~
{namespace} (number|nil) Diagnostic namespace. When {namespace} (number|nil) Diagnostic namespace. When omitted, show
omitted, show diagnostics from all diagnostics from all namespaces.
namespaces. {bufnr} (number|nil) Buffer number, or 0 for current buffer.
{bufnr} (number|nil) Buffer number, or 0 for When omitted, show diagnostics in all buffers.
current buffer. When omitted, show {diagnostics} (table|nil) The diagnostics to display. When omitted,
diagnostics in all buffers. use the saved diagnostics for the given namespace and
{diagnostics} (table|nil) The diagnostics to display. buffer. This can be used to display a list of
When omitted, use the saved diagnostics for diagnostics without saving them or to display only a
the given namespace and buffer. This can be subset of diagnostics. May not be used when {namespace}
used to display a list of diagnostics or {bufnr} is nil.
without saving them or to display only a
subset of diagnostics. May not be used when
{namespace} or {bufnr} is nil.
{opts} (table|nil) Display options. See {opts} (table|nil) Display options. See
|vim.diagnostic.config()|. |vim.diagnostic.config()|.
toqflist({diagnostics}) *vim.diagnostic.toqflist()* toqflist({diagnostics}) *vim.diagnostic.toqflist()*
Convert a list of diagnostics to a list of quickfix items that Convert a list of diagnostics to a list of quickfix items that can be
can be passed to |setqflist()| or |setloclist()|. passed to |setqflist()| or |setloclist()|.
Parameters: ~ Parameters: ~
{diagnostics} (table) List of diagnostics {diagnostics} (table) List of diagnostics |diagnostic-structure|.
|diagnostic-structure|.
Return: ~ Return: ~
array of quickfix list items |setqflist-what| array of quickfix list items |setqflist-what|
vim:tw=78:ts=8:ft=help:norl: vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

1273
runtime/doc/lsp.txt
View File

File diff suppressed because it is too large Load Diff

673
runtime/doc/lua.txt
View File

File diff suppressed because it is too large Load Diff

300
runtime/doc/treesitter.txt
View File

@@ -64,16 +64,15 @@ be very frequent. Rather a plugin that does any kind of analysis on a tree
should use a timer to throttle too frequent updates. should use a timer to throttle too frequent updates.
tsparser:set_included_regions({region_list}) *tsparser:set_included_regions()* tsparser:set_included_regions({region_list}) *tsparser:set_included_regions()*
Changes the regions the parser should consider. This is used for Changes the regions the parser should consider. This is used for language
language injection. {region_list} should be of the form injection. {region_list} should be of the form (all zero-based): >
(all zero-based): >
{ {
{node1, node2}, {node1, node2},
... ...
} }
< <
`node1` and `node2` are both considered part of the same region and `node1` and `node2` are both considered part of the same region and will
will be parsed together with the parser in the same context. be parsed together with the parser in the same context.
Tree methods *lua-treesitter-tree* Tree methods *lua-treesitter-tree*
@@ -102,10 +101,10 @@ tsnode:prev_named_sibling() *tsnode:prev_named_sibling()*
Get the node's previous named sibling. Get the node's previous named sibling.
tsnode:iter_children() *tsnode:iter_children()* tsnode:iter_children() *tsnode:iter_children()*
Iterates over all the direct children of {tsnode}, regardless of Iterates over all the direct children of {tsnode}, regardless of whether
whether they are named or not. they are named or not.
Returns the child node plus the eventual field name corresponding to Returns the child node plus the eventual field name corresponding to this
this child node. child node.
tsnode:field({name}) *tsnode:field()* tsnode:field({name}) *tsnode:field()*
Returns a table of the nodes corresponding to the {name} field. Returns a table of the nodes corresponding to the {name} field.
@@ -114,27 +113,27 @@ tsnode:child_count() *tsnode:child_count()*
Get the node's number of children. Get the node's number of children.
tsnode:child({index}) *tsnode:child()* tsnode:child({index}) *tsnode:child()*
Get the node's child at the given {index}, where zero represents the Get the node's child at the given {index}, where zero represents the first
first child. child.
tsnode:named_child_count() *tsnode:named_child_count()* tsnode:named_child_count() *tsnode:named_child_count()*
Get the node's number of named children. Get the node's number of named children.
tsnode:named_child({index}) *tsnode:named_child()* tsnode:named_child({index}) *tsnode:named_child()*
Get the node's named child at the given {index}, where zero represents Get the node's named child at the given {index}, where zero represents the
the first named child. first named child.
tsnode:start() *tsnode:start()* tsnode:start() *tsnode:start()*
Get the node's start position. Return three values: the row, column Get the node's start position. Return three values: the row, column and
and total byte count (all zero-based). total byte count (all zero-based).
tsnode:end_() *tsnode:end_()* tsnode:end_() *tsnode:end_()*
Get the node's end position. Return three values: the row, column Get the node's end position. Return three values: the row, column and
and total byte count (all zero-based). total byte count (all zero-based).
tsnode:range() *tsnode:range()* tsnode:range() *tsnode:range()*
Get the range of the node. Return four values: the row, column Get the range of the node. Return four values: the row, column of the
of the start position, then the row, column of the end position. start position, then the row, column of the end position.
tsnode:type() *tsnode:type()* tsnode:type() *tsnode:type()*
Get the node's type as a string. Get the node's type as a string.
@@ -143,13 +142,13 @@ tsnode:symbol() *tsnode:symbol()*
Get the node's type as a numerical id. Get the node's type as a numerical id.
tsnode:named() *tsnode:named()* tsnode:named() *tsnode:named()*
Check if the node is named. Named nodes correspond to named rules in Check if the node is named. Named nodes correspond to named rules in the
the grammar, whereas anonymous nodes correspond to string literals grammar, whereas anonymous nodes correspond to string literals in the
in the grammar. grammar.
tsnode:missing() *tsnode:missing()* tsnode:missing() *tsnode:missing()*
Check if the node is missing. Missing nodes are inserted by the Check if the node is missing. Missing nodes are inserted by the parser in
parser in order to recover from certain kinds of syntax errors. order to recover from certain kinds of syntax errors.
tsnode:has_error() *tsnode:has_error()* tsnode:has_error() *tsnode:has_error()*
Check if the node is a syntax error or contains any syntax errors. Check if the node is a syntax error or contains any syntax errors.
@@ -160,22 +159,22 @@ tsnode:sexpr() *tsnode:sexpr()*
tsnode:id() *tsnode:id()* tsnode:id() *tsnode:id()*
Get an unique identifier for the node inside its own tree. Get an unique identifier for the node inside its own tree.
No guarantees are made about this identifier's internal No guarantees are made about this identifier's internal representation,
representation, except for being a primitive lua type with value except for being a primitive lua type with value equality (so not a
equality (so not a table). Presently it is a (non-printable) string. table). Presently it is a (non-printable) string.
Note: the id is not guaranteed to be unique for nodes from different Note: the id is not guaranteed to be unique for nodes from different
trees. trees.
*tsnode:descendant_for_range()* *tsnode:descendant_for_range()*
tsnode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) tsnode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
Get the smallest node within this node that spans the given range of Get the smallest node within this node that spans the given range of (row,
(row, column) positions column) positions
*tsnode:named_descendant_for_range()* *tsnode:named_descendant_for_range()*
tsnode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) tsnode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
Get the smallest named node within this node that spans the given Get the smallest named node within this node that spans the given range of
range of (row, column) positions (row, column) positions
Query *lua-treesitter-query* Query *lua-treesitter-query*
@@ -216,27 +215,24 @@ Here is a list of built-in predicates :
This will match if the provided vim regex matches the text This will match if the provided vim regex matches the text
corresponding to a node: > corresponding to a node: >
((identifier) @constant (#match? @constant "^[A-Z_]+$")) ((identifier) @constant (#match? @constant "^[A-Z_]+$"))
< Note: the `^` and `$` anchors will respectively match the < Note: the `^` and `$` anchors will respectively match the start and
start and end of the node's text. end of the node's text.
`lua-match?` *ts-predicate-lua-match?* `lua-match?` *ts-predicate-lua-match?*
This will match the same way than |match?| but using lua This will match the same way than |match?| but using lua regexes.
regexes.
`contains?` *ts-predicate-contains?* `contains?` *ts-predicate-contains?*
Will check if any of the following arguments appears in the Will check if any of the following arguments appears in the text
text corresponding to the node: > corresponding to the node: >
((identifier) @foo (#contains? @foo "foo")) ((identifier) @foo (#contains? @foo "foo"))
((identifier) @foo-bar (#contains @foo-bar "foo" "bar")) ((identifier) @foo-bar (#contains @foo-bar "foo" "bar"))
< <
`any-of?` *ts-predicate-any-of?* `any-of?` *ts-predicate-any-of?*
Will check if the text is the same as any of the following Will check if the text is the same as any of the following arguments: >
arguments: >
((identifier) @foo (#any-of? @foo "foo" "bar")) ((identifier) @foo (#any-of? @foo "foo" "bar"))
< <
This is the recommended way to check if the node matches one This is the recommended way to check if the node matches one of many
of many keywords for example, as it has been optimized for keywords for example, as it has been optimized for this.
this.
< <
*lua-treesitter-not-predicate* *lua-treesitter-not-predicate*
Each predicate has a `not-` prefixed predicate that is just the negation of Each predicate has a `not-` prefixed predicate that is just the negation of
@@ -264,9 +260,9 @@ predicate sets metadata on the match or node : >
Built-in directives: Built-in directives:
`set!` *ts-directive-set!* `set!` *ts-directive-set!*
Sets key/value metadata for a specific match or capture. Sets key/value metadata for a specific match or capture. Value is
Value is accessible as either `metadata[key]` (match accessible as either `metadata[key]` (match specific) or
specific) or `metadata[capture_id][key]` (capture specific). `metadata[capture_id][key]` (capture specific).
Parameters: ~ Parameters: ~
{capture_id} (optional) {capture_id} (optional)
@@ -278,9 +274,9 @@ Built-in directives:
((node1) @left (node2) @right (#set! "type" "pair")) ((node1) @left (node2) @right (#set! "type" "pair"))
< <
`offset!` *ts-directive-offset!* `offset!` *ts-directive-offset!*
Takes the range of the captured node and applies an offset. Takes the range of the captured node and applies an offset. This will
This will generate a new range object for the captured node generate a new range object for the captured node as
as `metadata[capture_id].range`. `metadata[capture_id].range`.
Parameters: ~ Parameters: ~
{capture_id} {capture_id}
@@ -359,14 +355,13 @@ Lua module: vim.treesitter *lua-treesitter-core*
get_parser({bufnr}, {lang}, {opts}) *get_parser()* get_parser({bufnr}, {lang}, {opts}) *get_parser()*
Gets the parser for this bufnr / ft combination. Gets the parser for this bufnr / ft combination.
If needed this will create the parser. Unconditionally attach If needed this will create the parser. Unconditionally attach the provided
the provided callback callback
Parameters: ~ Parameters: ~
{bufnr} The buffer the parser should be tied to {bufnr} The buffer the parser should be tied to
{lang} The filetype of this parser {lang} The filetype of this parser
{opts} Options object to pass to the created language {opts} Options object to pass to the created language tree
tree
Return: ~ Return: ~
The parser The parser
@@ -386,15 +381,15 @@ Lua module: vim.treesitter.language *treesitter-language*
inspect_language({lang}) *inspect_language()* inspect_language({lang}) *inspect_language()*
Inspects the provided language. Inspects the provided language.
Inspecting provides some useful information on the language Inspecting provides some useful information on the language like node
like node names, ... names, ...
Parameters: ~ Parameters: ~
{lang} The language. {lang} The language.
require_language({lang}, {path}, {silent}) *require_language()* require_language({lang}, {path}, {silent}) *require_language()*
Asserts that the provided language is installed, and Asserts that the provided language is installed, and optionally provide a
optionally provide a path for the parser path for the parser
Parsers are searched in the `parser` runtime directory. Parsers are searched in the `parser` runtime directory.
@@ -410,31 +405,30 @@ Lua module: vim.treesitter.query *treesitter-query*
add_directive({name}, {handler}, {force}) *add_directive()* add_directive({name}, {handler}, {force}) *add_directive()*
Adds a new directive to be used in queries Adds a new directive to be used in queries
Handlers can set match level data by setting directly on the Handlers can set match level data by setting directly on the metadata
metadata object `metadata.key = value`, additionally, handlers object `metadata.key = value`, additionally, handlers can set node level
can set node level data by using the capture id on the data by using the capture id on the metadata table
metadata table `metadata[capture_id].key = value` `metadata[capture_id].key = value`
Parameters: ~ Parameters: ~
{name} the name of the directive, without leading # {name} the name of the directive, without leading #
{handler} the handler function to be used signature will {handler} the handler function to be used signature will be (match,
be (match, pattern, bufnr, predicate, metadata) pattern, bufnr, predicate, metadata)
add_predicate({name}, {handler}, {force}) *add_predicate()* add_predicate({name}, {handler}, {force}) *add_predicate()*
Adds a new predicate to be used in queries Adds a new predicate to be used in queries
Parameters: ~ Parameters: ~
{name} the name of the predicate, without leading # {name} the name of the predicate, without leading #
{handler} the handler function to be used signature will {handler} the handler function to be used signature will be (match,
be (match, pattern, bufnr, predicate) pattern, bufnr, predicate)
get_node_text({node}, {source}) *get_node_text()* get_node_text({node}, {source}) *get_node_text()*
Gets the text corresponding to a given node Gets the text corresponding to a given node
Parameters: ~ Parameters: ~
{node} the node {node} the node
{source} The buffer or string from which the node is {source} The buffer or string from which the node is extracted
extracted
get_query({lang}, {query_name}) *get_query()* get_query({lang}, {query_name}) *get_query()*
Returns the runtime query {query_name} for {lang}. Returns the runtime query {query_name} for {lang}.
@@ -453,8 +447,7 @@ get_query_files({lang}, {query_name}, {is_included})
Parameters: ~ Parameters: ~
{lang} The language {lang} The language
{query_name} The name of the query to load {query_name} The name of the query to load
{is_included} Internal parameter, most of the time left {is_included} Internal parameter, most of the time left as `nil`
as `nil`
list_directives() *list_directives()* list_directives() *list_directives()*
Lists the currently available directives to use in queries. Lists the currently available directives to use in queries.
@@ -467,22 +460,21 @@ list_predicates() *list_predicates()*
The list of supported predicates. The list of supported predicates.
parse_query({lang}, {query}) *parse_query()* parse_query({lang}, {query}) *parse_query()*
Parse {query} as a string. (If the query is in a file, the Parse {query} as a string. (If the query is in a file, the caller should
caller should read the contents into a string before calling). read the contents into a string before calling).
Returns a `Query` (see |lua-treesitter-query|) object which Returns a `Query` (see |lua-treesitter-query|) object which can be used to
can be used to search nodes in the syntax tree for the search nodes in the syntax tree for the patterns defined in {query} using
patterns defined in {query} using `iter_*` methods below. `iter_*` methods below.
Exposes `info` and `captures` with additional context about {query}. Exposes `info` and `captures` with additional context about {query}.
• `captures` contains the list of unique capture names defined • `captures` contains the list of unique capture names defined in {query}.
in {query}. -`info.captures` also points to `captures`. -`info.captures` also points to `captures`.
• `info.patterns` contains information about predicates. • `info.patterns` contains information about predicates.
Parameters: ~ Parameters: ~
{lang} (string) The language {lang} (string) The language
{query} (string) A string containing the query (s-expr {query} (string) A string containing the query (s-expr syntax)
syntax)
Return: ~ Return: ~
The query The query
@@ -491,19 +483,16 @@ parse_query({lang}, {query}) *parse_query()*
Query:iter_captures({self}, {node}, {source}, {start}, {stop}) Query:iter_captures({self}, {node}, {source}, {start}, {stop})
Iterate over all captures from all matches inside {node} Iterate over all captures from all matches inside {node}
{source} is needed if the query contains predicates, then the {source} is needed if the query contains predicates, then the caller must
caller must ensure to use a freshly parsed tree consistent ensure to use a freshly parsed tree consistent with the current text of
with the current text of the buffer (if relevant). {start_row} the buffer (if relevant). {start_row} and {end_row} can be used to limit
and {end_row} can be used to limit matches inside a row range matches inside a row range (this is typically used with root node as the
(this is typically used with root node as the node, i e to get node, i e to get syntax highlight matches in the current viewport). When
syntax highlight matches in the current viewport). When omitted the start and end row values are used from the given node.
omitted the start and end row values are used from the given
node.
The iterator returns three values, a numeric id identifying The iterator returns three values, a numeric id identifying the capture,
the capture, the captured node, and metadata from any the captured node, and metadata from any directives processing the match.
directives processing the match. The following example shows The following example shows how to get captures by name:
how to get captures by name:
> >
for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do
@@ -530,13 +519,12 @@ Query:iter_captures({self}, {node}, {source}, {start}, {stop})
Query:iter_matches({self}, {node}, {source}, {start}, {stop}) Query:iter_matches({self}, {node}, {source}, {start}, {stop})
Iterates the matches of self on a given range. Iterates the matches of self on a given range.
Iterate over all matches within a node. The arguments are the Iterate over all matches within a node. The arguments are the same as for
same as for |query:iter_captures()| but the iterated values |query:iter_captures()| but the iterated values are different: an
are different: an (1-based) index of the pattern in the query, (1-based) index of the pattern in the query, a table mapping capture
a table mapping capture indices to nodes, and metadata from indices to nodes, and metadata from any directives processing the match.
any directives processing the match. If the query has more If the query has more than one pattern the capture table might be sparse,
than one pattern the capture table might be sparse, and e.g. and e.g. `pairs()` method should be used over `ipairs`. Here an example
`pairs()` method should be used over `ipairs`. Here an example
iterating over all captures in every match: iterating over all captures in every match:
> >
@@ -566,13 +554,12 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop})
set_query({lang}, {query_name}, {text}) *set_query()* set_query({lang}, {query_name}, {text}) *set_query()*
Sets the runtime query {query_name} for {lang} Sets the runtime query {query_name} for {lang}
This allows users to override any runtime files and/or This allows users to override any runtime files and/or configuration set
configuration set by plugins. by plugins.
Parameters: ~ Parameters: ~
{lang} string: The language to use for the query {lang} string: The language to use for the query
{query_name} string: The name of the query (i.e. {query_name} string: The name of the query (i.e. "highlights")
"highlights")
{text} string: The query text (unparsed). {text} string: The query text (unparsed).
@@ -585,8 +572,7 @@ new({tree}, {opts}) *highlighter.new()*
Parameters: ~ Parameters: ~
{tree} The language tree to use for highlighting {tree} The language tree to use for highlighting
{opts} Table used to configure the highlighter {opts} Table used to configure the highlighter
• queries: Table to overwrite queries used by the • queries: Table to overwrite queries used by the highlighter
highlighter
TSHighlighter:destroy({self}) *TSHighlighter:destroy()* TSHighlighter:destroy({self}) *TSHighlighter:destroy()*
Removes all internal references to the highlighter Removes all internal references to the highlighter
@@ -608,8 +594,7 @@ Lua module: vim.treesitter.languagetree *treesitter-languagetree*
LanguageTree:add_child({self}, {lang}) *LanguageTree:add_child()* LanguageTree:add_child({self}, {lang}) *LanguageTree:add_child()*
Adds a child language to this tree. Adds a child language to this tree.
If the language already exists as a child, it will first be If the language already exists as a child, it will first be removed.
removed.
Parameters: ~ Parameters: ~
{lang} The language to add. {lang} The language to add.
@@ -625,8 +610,8 @@ LanguageTree:contains({self}, {range}) *LanguageTree:contains()*
Determines whether {range} is contained in this language tree Determines whether {range} is contained in this language tree
Parameters: ~ Parameters: ~
{range} A range, that is a `{ start_line, start_col, {range} A range, that is a `{ start_line, start_col, end_line,
end_line, end_col }` table. end_col }` table.
{self} {self}
LanguageTree:destroy({self}) *LanguageTree:destroy()* LanguageTree:destroy({self}) *LanguageTree:destroy()*
@@ -641,27 +626,22 @@ LanguageTree:destroy({self}) *LanguageTree:destroy()*
*LanguageTree:for_each_child()* *LanguageTree:for_each_child()*
LanguageTree:for_each_child({self}, {fn}, {include_self}) LanguageTree:for_each_child({self}, {fn}, {include_self})
Invokes the callback for each LanguageTree and it's children Invokes the callback for each LanguageTree and it's children recursively
recursively
Parameters: ~ Parameters: ~
{fn} The function to invoke. This is invoked {fn} The function to invoke. This is invoked with arguments
with arguments (tree: LanguageTree, lang: (tree: LanguageTree, lang: string)
string) {include_self} Whether to include the invoking tree in the results.
{include_self} Whether to include the invoking tree in
the results.
{self} {self}
LanguageTree:for_each_tree({self}, {fn}) *LanguageTree:for_each_tree()* LanguageTree:for_each_tree({self}, {fn}) *LanguageTree:for_each_tree()*
Invokes the callback for each treesitter trees recursively. Invokes the callback for each treesitter trees recursively.
Note, this includes the invoking language tree's trees as Note, this includes the invoking language tree's trees as well.
well.
Parameters: ~ Parameters: ~
{fn} The callback to invoke. The callback is invoked {fn} The callback to invoke. The callback is invoked with arguments
with arguments (tree: TSTree, languageTree: (tree: TSTree, languageTree: LanguageTree)
LanguageTree)
{self} {self}
LanguageTree:included_regions({self}) *LanguageTree:included_regions()* LanguageTree:included_regions({self}) *LanguageTree:included_regions()*
@@ -677,8 +657,7 @@ LanguageTree:invalidate({self}, {reload}) *LanguageTree:invalidate()*
{self} {self}
LanguageTree:is_valid({self}) *LanguageTree:is_valid()* LanguageTree:is_valid({self}) *LanguageTree:is_valid()*
Determines whether this tree is valid. If the tree is invalid, Determines whether this tree is valid. If the tree is invalid, call `parse()` . This will return the updated tree.
call `parse()` . This will return the updated tree.
Parameters: ~ Parameters: ~
{self} {self}
@@ -698,10 +677,9 @@ LanguageTree:language_for_range({self}, {range})
{self} {self}
LanguageTree:parse({self}) *LanguageTree:parse()* LanguageTree:parse({self}) *LanguageTree:parse()*
Parses all defined regions using a treesitter parser for the Parses all defined regions using a treesitter parser for the language this
language this tree represents. This will run the injection tree represents. This will run the injection query for this language to
query for this language to determine if any child languages determine if any child languages should be created.
should be created.
Parameters: ~ Parameters: ~
{self} {self}
@@ -710,19 +688,17 @@ LanguageTree:register_cbs({self}, {cbs}) *LanguageTree:register_cbs()*
Registers callbacks for the parser. Registers callbacks for the parser.
Parameters: ~ Parameters: ~
{cbs} (table) An |nvim_buf_attach()|-like table argument {cbs} (table) An |nvim_buf_attach()|-like table argument with the
with the following keys : following keys :
• `on_bytes` : see |nvim_buf_attach()|, but this will be • `on_bytes` : see |nvim_buf_attach()|, but this will be called after the parsers callback.
called after the parsers callback. • `on_changedtree` : a callback that will be called every time
• `on_changedtree` : a callback that will be the tree has syntactical changes. It will only be passed one
called every time the tree has syntactical argument, which is a table of the ranges (as node ranges)
changes. It will only be passed one argument,
which is a table of the ranges (as node ranges)
that changed. that changed.
• `on_child_added` : emitted when a child is added • `on_child_added` : emitted when a child is added to the
to the tree. tree.
• `on_child_removed` : emitted when a child is • `on_child_removed` : emitted when a child is removed from
removed from the tree. the tree.
{self} {self}
LanguageTree:remove_child({self}, {lang}) *LanguageTree:remove_child()* LanguageTree:remove_child({self}, {lang}) *LanguageTree:remove_child()*
@@ -734,58 +710,50 @@ LanguageTree:remove_child({self}, {lang}) *LanguageTree:remove_child()*
*LanguageTree:set_included_regions()* *LanguageTree:set_included_regions()*
LanguageTree:set_included_regions({self}, {regions}) LanguageTree:set_included_regions({self}, {regions})
Sets the included regions that should be parsed by this Sets the included regions that should be parsed by this parser. A region
parser. A region is a set of nodes and/or ranges that will be is a set of nodes and/or ranges that will be parsed in the same context.
parsed in the same context.
For example, `{ { node1 }, { node2} }` is two separate For example, `{ { node1 }, { node2} }` is two separate regions. This will
regions. This will be parsed by the parser in two different be parsed by the parser in two different contexts... thus resulting in two
contexts... thus resulting in two separate trees. separate trees.
`{ { node1, node2 } }` is a single region consisting of two `{ { node1, node2 } }` is a single region consisting of two nodes. This
nodes. This will be parsed by the parser in a single will be parsed by the parser in a single context... thus resulting in a
context... thus resulting in a single tree. single tree.
This allows for embedded languages to be parsed together This allows for embedded languages to be parsed together across different
across different nodes, which is useful for templating nodes, which is useful for templating languages like ERB and EJS.
languages like ERB and EJS.
Note, this call invalidates the tree and requires it to be Note, this call invalidates the tree and requires it to be parsed again.
parsed again.
Parameters: ~ Parameters: ~
{regions} (table) list of regions this tree should manage {regions} (table) list of regions this tree should manage and parse.
and parse.
{self} {self}
LanguageTree:source({self}) *LanguageTree:source()* LanguageTree:source({self}) *LanguageTree:source()*
Returns the source content of the language tree (bufnr or Returns the source content of the language tree (bufnr or string).
string).
Parameters: ~ Parameters: ~
{self} {self}
LanguageTree:trees({self}) *LanguageTree:trees()* LanguageTree:trees({self}) *LanguageTree:trees()*
Returns all trees this language tree contains. Does not Returns all trees this language tree contains. Does not include child
include child languages. languages.
Parameters: ~ Parameters: ~
{self} {self}
new({source}, {lang}, {opts}) *languagetree.new()* new({source}, {lang}, {opts}) *languagetree.new()*
Represents a single treesitter parser for a language. The Represents a single treesitter parser for a language. The language can
language can contain child languages with in its range, hence contain child languages with in its range, hence the tree.
the tree.
Parameters: ~ Parameters: ~
{source} Can be a bufnr or a string of text to {source} Can be a bufnr or a string of text to parse
parse
{lang} The language this tree represents {lang} The language this tree represents
{opts} Options table {opts} Options table
{opts.injections} A table of language to injection query {opts.injections} A table of language to injection query strings.
strings. This is useful for overriding This is useful for overriding the built-in runtime
the built-in runtime file searching for file searching for the injection language query per
the injection language query per
language. language.
vim:tw=78:ts=8:ft=help:norl: vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

20
scripts/gen_vimdoc.py
View File

@@ -26,7 +26,7 @@ Each function :help block is formatted as follows:
- Max width of 78 columns (`text_width`). - Max width of 78 columns (`text_width`).
- Indent with spaces (not tabs). - Indent with spaces (not tabs).
- Indent of 16 columns for body text. - Indent of 4 columns for body text (`indentation`).
- Function signature and helptag (right-aligned) on the same line. - Function signature and helptag (right-aligned) on the same line.
- Signature and helptag must have a minimum of 8 spaces between them. - Signature and helptag must have a minimum of 8 spaces between them.
- If the signature is too long, it is placed on the line after the helptag. - If the signature is too long, it is placed on the line after the helptag.
@@ -80,6 +80,7 @@ LOG_LEVELS = {
} }
text_width = 78 text_width = 78
indentation = 4
script_path = os.path.abspath(__file__) script_path = os.path.abspath(__file__)
base_dir = os.path.dirname(os.path.dirname(script_path)) base_dir = os.path.dirname(os.path.dirname(script_path))
out_dir = os.path.join(base_dir, 'tmp-{target}-doc') out_dir = os.path.join(base_dir, 'tmp-{target}-doc')
@@ -456,7 +457,7 @@ def max_name(names):
return max(len(name) for name in names) return max(len(name) for name in names)
def update_params_map(parent, ret_map, width=62): def update_params_map(parent, ret_map, width=text_width - indentation):
"""Updates `ret_map` with name:desc key-value pairs extracted """Updates `ret_map` with name:desc key-value pairs extracted
from Doxygen XML node `parent`. from Doxygen XML node `parent`.
""" """
@@ -483,7 +484,8 @@ def update_params_map(parent, ret_map, width=62):
return ret_map return ret_map
def render_node(n, text, prefix='', indent='', width=62, fmt_vimhelp=False): def render_node(n, text, prefix='', indent='', width=text_width - indentation,
fmt_vimhelp=False):
"""Renders a node as Vim help text, recursively traversing all descendants.""" """Renders a node as Vim help text, recursively traversing all descendants."""
def ind(s): def ind(s):
@@ -562,7 +564,7 @@ def render_node(n, text, prefix='', indent='', width=62, fmt_vimhelp=False):
return text return text
def para_as_map(parent, indent='', width=62, fmt_vimhelp=False): def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=False):
"""Extracts a Doxygen XML <para> node to a map. """Extracts a Doxygen XML <para> node to a map.
Keys: Keys:
@@ -656,7 +658,8 @@ def para_as_map(parent, indent='', width=62, fmt_vimhelp=False):
return chunks, xrefs return chunks, xrefs
def fmt_node_as_vimhelp(parent, width=62, indent='', fmt_vimhelp=False): def fmt_node_as_vimhelp(parent, width=text_width - indentation, indent='',
fmt_vimhelp=False):
"""Renders (nested) Doxygen <para> nodes as Vim :help text. """Renders (nested) Doxygen <para> nodes as Vim :help text.
NB: Blank lines in a docstring manifest as <para> tags. NB: Blank lines in a docstring manifest as <para> tags.
@@ -838,7 +841,8 @@ def extract_from_xml(filename, target, width, fmt_vimhelp):
log.debug( log.debug(
textwrap.indent( textwrap.indent(
re.sub(r'\n\s*\n+', '\n', re.sub(r'\n\s*\n+', '\n',
desc.toprettyxml(indent=' ', newl='\n')), ' ' * 16)) desc.toprettyxml(indent=' ', newl='\n')),
' ' * indentation))
fn = { fn = {
'annotations': list(annotations), 'annotations': list(annotations),
@@ -918,7 +922,7 @@ def fmt_doxygen_xml_as_vimhelp(filename, target):
doc += '\n<' doc += '\n<'
func_doc = fn['signature'] + '\n' func_doc = fn['signature'] + '\n'
func_doc += textwrap.indent(clean_lines(doc), ' ' * 16) func_doc += textwrap.indent(clean_lines(doc), ' ' * indentation)
# Verbatim handling. # Verbatim handling.
func_doc = re.sub(r'^\s+([<>])$', r'\1', func_doc, flags=re.M) func_doc = re.sub(r'^\s+([<>])$', r'\1', func_doc, flags=re.M)
@@ -1114,7 +1118,7 @@ def main(config, args):
docs += '\n\n\n' docs += '\n\n\n'
docs = docs.rstrip() + '\n\n' docs = docs.rstrip() + '\n\n'
docs += ' vim:tw=78:ts=8:ft=help:norl:\n' docs += f' vim:tw=78:ts=8:sw={indentation}:sts={indentation}:et:ft=help:norl:\n'
doc_file = os.path.join(base_dir, 'runtime', 'doc', doc_file = os.path.join(base_dir, 'runtime', 'doc',
CONFIG[target]['filename']) CONFIG[target]['filename'])