IntenseFinance/neovim
3
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-02-25 18:55:25 -06:00
Code Issues Packages Projects Releases Wiki Activity

feat(help): highlighted codeblocks

Browse Source
This commit is contained in:
Christian Clason 2022-11-22 13:50:50 +01:00
parent 89f0987bde
commit 5093f38c9f
6 changed files with 70 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
cmake.deps/CMakeLists.txt
View File

@ -203,8 +203,8 @@ set(TREESITTER_LUA_SHA256 930d0370dc15b66389869355c8e14305b9ba7aafd36edbfdb468c8
set(TREESITTER_VIM_URL https://github.com/vigoux/tree-sitter-viml/archive/55ff1b080c09edeced9b748cf4c16d0b49d17fb9.tar.gz)
set(TREESITTER_VIM_SHA256 1b1cd39e33c8fb02fa7fe3977e844883c2a8508a7edd621f2d21e39a9aeefa92)
set(TREESITTER_HELP_URL https://github.com/neovim/tree-sitter-vimdoc/archive/v1.2.5.tar.gz)
set(TREESITTER_HELP_SHA256 379d764937a0e3a38e3f9ce9a62c93ba24211a236c74181dd04ee3b4631472a8)
set(TREESITTER_HELP_URL https://github.com/neovim/tree-sitter-vimdoc/archive/ce20f13c3f12506185754888feaae3f2ad54c287.tar.gz)
set(TREESITTER_HELP_SHA256 2b8b166438cce66064aab56a744430b1f44871f43e47f70b51246d14bb826609)
set(TREESITTER_URL https://github.com/tree-sitter/tree-sitter/archive/v0.20.7.tar.gz)
set(TREESITTER_SHA256 b355e968ec2d0241bbd96748e00a9038f83968f85d822ecb9940cbe4c42e182e)

110
runtime/doc/lua.txt
View File

@ -12,7 +12,7 @@ Lua engine *lua* *Lua*
INTRODUCTION *lua-intro*
The Lua 5.1 script engine is builtin and always available. Try this command to
get an idea of what lurks beneath: >
get an idea of what lurks beneath: >vim
:lua print(vim.inspect(package.loaded))
@ -56,20 +56,20 @@ https://www.lua.org/doc/cacm2018.pdf
versatile control for both Lua and its host (Nvim).
*lua-call-function*
Lua functions can be called in multiple ways. Consider the function: >
Lua functions can be called in multiple ways. Consider the function: >lua
local foo = function(a, b)
print("A: ", a)
print("B: ", b)
end
The first way to call this function is: >
The first way to call this function is: >lua
foo(1, 2)
-- ==== Result ====
-- A: 1
-- B: 2
This way of calling a function is familiar from most scripting languages.
In Lua, any missing arguments are passed as `nil`. Example: >
In Lua, any missing arguments are passed as `nil`. Example: >lua
foo(1)
-- ==== Result ====
-- A: 1
@ -81,7 +81,7 @@ discarded.
It is also allowed to omit the parentheses (only) if the function takes
exactly one string (`"foo"`) or table literal (`{1,2,3}`). The latter is often
used to approximate the "named parameters" feature of languages like Python
("kwargs" or "keyword args"). Example: >
("kwargs" or "keyword args"). Example: >lua
local func_with_opts = function(opts)
local will_do_foo = opts.foo
local filename = opts.filename
@ -95,7 +95,7 @@ There is nothing special going on here except that parentheses are treated as
whitespace. But visually, this small bit of sugar gets reasonably close to
a "keyword args" interface.
It is of course also valid to call the function with parentheses: >
It is of course also valid to call the function with parentheses: >lua
func_with_opts({ foo = true, filename = "hello.world" })
<
@ -108,7 +108,7 @@ Lua intentionally does not support regular expressions, instead it has limited
"patterns" which avoid the performance pitfalls of extended regex.
|luaref-patterns|
Examples using |string.match()|: >
Examples using |string.match()|: >lua
print(string.match("foo123bar123", "%d+"))
-- 123
@ -205,7 +205,7 @@ Note:
- Although adjustments happen automatically, Nvim does not track current
values of |package.path| or |package.cpath|. If you happen to delete some
paths from there you can set 'runtimepath' to trigger an update: >
paths from there you can set 'runtimepath' to trigger an update: >vim
let &runtimepath = &runtimepath
- Skipping paths from 'runtimepath' which contain semicolons applies both to
@ -231,11 +231,11 @@ arguments separated by " " (space) instead of "\t" (tab).
chunk is evaluated as an expression and printed. `:lua =expr` is
equivalent to `:lua print(vim.inspect(expr))`
Examples: >
Examples: >vim
:lua vim.api.nvim_command('echo "Hello, Nvim!"')
< To see the Lua version: >
< To see the Lua version: >vim
:lua print(_VERSION)
< To see the LuaJIT version: >
< To see the LuaJIT version: >vim
:lua =jit.version
<
*:lua-heredoc*
@ -246,7 +246,7 @@ arguments separated by " " (space) instead of "\t" (tab).
be preceded by whitespace. You can omit [endmarker] after the "<<" and use
a dot "." after {script} (similar to |:append|, |:insert|).
Example: >
Example: >vim
function! CurrentLineInfo()
lua << EOF
local linenr = vim.api.nvim_win_get_cursor(0)[1]
@ -268,7 +268,7 @@ arguments separated by " " (space) instead of "\t" (tab).
that becomes the text of the corresponding buffer line. Default [range] is
the whole file: "1,$".
Examples: >
Examples: >vim
:luado return string.format("%s\t%d", line:reverse(), #line)
:lua require"lpeg"
@ -282,7 +282,7 @@ arguments separated by " " (space) instead of "\t" (tab).
The whole argument is used as the filename (like |:edit|), spaces do not
need to be escaped. Alternatively you can |:source| Lua files.
Examples: >
Examples: >vim
:luafile script.lua
:luafile %
<
@ -293,7 +293,7 @@ luaeval() *lua-eval* *luaeval()*
The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is
"luaeval". "luaeval" takes an expression string and an optional argument used
for _A inside expression and returns the result of the expression. It is
semantically equivalent in Lua to: >
semantically equivalent in Lua to: >lua
local chunkheader = "local _A = select(1, ...) return "
function luaeval (expstr, arg)
@ -307,11 +307,11 @@ converted to a |Blob|. Conversion of other Lua types is an error.
The magic global "_A" contains the second argument to luaeval().
Example: >
Example: >vim
:echo luaeval('_A[1] + _A[2]', [40, 2])
42
" 42
:echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123')
foo
" foo
<
Lua tables are used as both dictionaries and lists, so it is impossible to
determine whether empty table is meant to be empty list or empty dictionary.
@ -343,7 +343,7 @@ cases there is the following agreement:
form a 1-step sequence from 1 to N are ignored, as well as all
non-integral keys.
Examples: >
Examples: >vim
:echo luaeval('math.pi')
:function Rand(x,y) " random uniform between x and y
@ -360,16 +360,16 @@ treated specially.
Vimscript v:lua interface *v:lua-call*
From Vimscript the special `v:lua` prefix can be used to call Lua functions
which are global or accessible from global tables. The expression >
which are global or accessible from global tables. The expression >vim
v:lua.func(arg1, arg2)
is equivalent to the Lua chunk >
is equivalent to the Lua chunk >lua
return func(...)
where the args are converted to Lua values. The expression >
where the args are converted to Lua values. The expression >vim
v:lua.somemod.func(args)
is equivalent to the Lua chunk >
is equivalent to the Lua chunk >lua
return somemod.func(...)
In addition, functions of packages can be accessed like >
In addition, functions of packages can be accessed like >vim
v:lua.require'mypack'.func(arg1, arg2)
v:lua.require'mypack.submod'.func(arg1, arg2)
Note: Only single quote form without parens is allowed. Using
@ -378,11 +378,11 @@ is still valid as a function call of itself, in case require returns a useful
value).
The `v:lua` prefix may be used to call Lua functions as |method|s. For
example: >
example: >vim
arg1->v:lua.somemod.func(arg2)
<
You can use `v:lua` in "func" options like 'tagfunc', 'omnifunc', etc.
For example consider the following Lua omnifunc handler: >
For example consider the following Lua omnifunc handler: >lua
function mymod.omnifunc(findstart, base)
if findstart == 1 then
@ -397,7 +397,7 @@ Note: The module ("mymod" in the above example) must either be a Lua global,
or use the require syntax as specified above to access it from a package.
Note: `v:lua` without a call is not allowed in a Vimscript expression:
|Funcref|s cannot represent Lua functions. The following are errors: >
|Funcref|s cannot represent Lua functions. The following are errors: >vim
let g:Myvar = v:lua.myfunc " Error
call SomeFunc(v:lua.mycallback) " Error
@ -411,7 +411,7 @@ The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes
various functions and sub-modules. It is always loaded, thus `require("vim")`
is unnecessary.
You can peek at the module properties: >
You can peek at the module properties: >vim
:lua print(vim.inspect(vim))
@ -431,7 +431,7 @@ Result is something like this: >
...
}
To find documentation on e.g. the "deepcopy" function: >
To find documentation on e.g. the "deepcopy" function: >vim
:help vim.deepcopy()
@ -443,7 +443,7 @@ VIM.LOOP *lua-loop* *vim.loop*
`vim.loop` exposes all features of the Nvim event-loop. This is a low-level
API that provides functionality for networking, filesystem, and process
management. Try this command to see available functions: >
management. Try this command to see available functions: >vim
:lua print(vim.inspect(vim.loop))
<
@ -452,14 +452,14 @@ see |luv-intro| for a full reference manual.
*E5560* *lua-loop-callbacks*
It is an error to directly invoke `vim.api` functions (except |api-fast|) in
`vim.loop` callbacks. For example, this is an error: >
`vim.loop` callbacks. For example, this is an error: >lua
local timer = vim.loop.new_timer()
timer:start(1000, 0, function()
vim.api.nvim_command('echomsg "test"')
end)
<
To avoid the error use |vim.schedule_wrap()| to defer the callback: >
To avoid the error use |vim.schedule_wrap()| to defer the callback: >lua
local timer = vim.loop.new_timer()
timer:start(1000, 0, vim.schedule_wrap(function()
@ -471,7 +471,7 @@ wrapping.)
Example: repeating timer
1. Save this code to a file.
2. Execute it with ":luafile %". >
2. Execute it with ":luafile %". >lua
-- Create a timer handle (implementation detail: uv_timer_t).
local timer = vim.loop.new_timer()
@ -492,7 +492,7 @@ Example: File-change detection *watch-file*
3. Use ":Watch %" to watch any file.
4. Try editing the file from another text editor.
5. Observe that the file reloads in Nvim (because on_change() calls
|:checktime|). >
|:checktime|). >lua
local w = vim.loop.new_fs_event()
local function on_change(err, fname, status)
@ -515,7 +515,7 @@ Example: TCP echo-server *tcp-server*
1. Save this code to a file.
2. Execute it with ":luafile %".
3. Note the port number.
4. Connect from any TCP client (e.g. "nc 0.0.0.0 36795"): >
4. Connect from any TCP client (e.g. "nc 0.0.0.0 36795"): >lua
local function create_server(host, port, on_connect)
local server = vim.loop.new_tcp()
@ -564,16 +564,16 @@ VIM.HIGHLIGHT *lua-highlight*
Nvim includes a function for highlighting a selection on yank (see for example
https://github.com/machakann/vim-highlightedyank). To enable it, add
>
>vim
au TextYankPost * silent! lua vim.highlight.on_yank()
<
to your `init.vim`. You can customize the highlight group and the duration of
the highlight via
>
>vim
au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
<
If you want to exclude visual selections from highlighting on yank, use
>
>vim
au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
<
vim.highlight.on_yank({opts}) *vim.highlight.on_yank()*
@ -756,7 +756,7 @@ VIM *lua-builtin*
vim.api.{func}({...}) *vim.api*
Invokes Nvim |API| function {func} with arguments {...}.
Example: call the "nvim_get_current_line()" API function: >
Example: call the "nvim_get_current_line()" API function: >lua
print(tostring(vim.api.nvim_get_current_line()))
vim.version() *vim.version*
@ -881,7 +881,7 @@ vim.wait({time} [, {callback}, {interval}, {fast_only}]) *vim.wait()*
If {callback} errors, the error is raised.
Examples: >
Examples: >lua
---
-- Wait for 100 ms, allowing other events to process
@ -922,7 +922,7 @@ vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()*
used to handle messages when setting 'cmdheight' to zero (which is
likewise experimental).
Example (stub for a |ui-popupmenu| implementation): >
Example (stub for a |ui-popupmenu| implementation): >lua
ns = vim.api.nvim_create_namespace('my_fancy_pum')
@ -950,7 +950,7 @@ vim.type_idx *vim.type_idx*
vim.val_idx *vim.val_idx*
Value index for tables representing |Float|s. A table representing
floating-point value 1.0 looks like this: >
floating-point value 1.0 looks like this: >lua
{
[vim.type_idx] = vim.types.float,
[vim.val_idx] = 1.0,
@ -997,7 +997,7 @@ See also https://github.com/nanotee/nvim-lua-guide.
vim.call({func}, {...}) *vim.call()*
Invokes |vim-function| or |user-function| {func} with arguments {...}.
See also |vim.fn|.
Equivalent to: >
Equivalent to: >lua
vim.fn[func]({...})
vim.cmd({command})
@ -1005,7 +1005,7 @@ vim.cmd({command})
vim.fn.{func}({...}) *vim.fn*
Invokes |vim-function| or |user-function| {func} with arguments {...}.
To call autoload functions, use the syntax: >
To call autoload functions, use the syntax: >lua
vim.fn['some#function']({...})
<
Unlike vim.api.|nvim_call_function()| this converts directly between Vim
@ -1028,7 +1028,7 @@ from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
described below. In this way you can easily read and modify global Vimscript
variables from Lua.
Example: >
Example: >lua
vim.g.foo = 5 -- Set the g:foo Vimscript variable.
print(vim.g.foo) -- Get and print the g:foo Vimscript variable.
@ -1041,7 +1041,7 @@ Nvim. This is because the index into the namespace simply returns a copy.
Instead the whole dictionary must be written as one. This can be achieved by
creating a short-lived temporary.
Example: >
Example: >lua
vim.g.my_dict.field1 = 'value' -- Does not work
@ -1076,7 +1076,7 @@ vim.env *vim.env*
Environment variables defined in the editor session.
See |expand-env| and |:let-environment| for the Vimscript behavior.
Invalid or unset key returns `nil`.
Example: >
Example: >lua
vim.env.FOO = 'bar'
print(vim.env.TERM)
<
@ -1110,7 +1110,7 @@ vim.o *vim.o*
Note: this works on both buffer-scoped and window-scoped options using the
current buffer and window.
Example: >
Example: >lua
vim.o.cmdheight = 4
print(vim.o.columns)
print(vim.o.foo) -- error: invalid key
@ -1123,7 +1123,7 @@ vim.go *vim.go*
option value and thus is mostly useful for use with |global-local|
options.
Example: >
Example: >lua
vim.go.cmdheight = 4
print(vim.go.columns)
print(vim.go.bar) -- error: invalid key
@ -1135,7 +1135,7 @@ vim.bo[{bufnr}] *
Note: this is equivalent to both `:set` and `:setlocal`.
Example: >
Example: >lua
local bufnr = vim.api.nvim_get_current_buf()
vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true
print(vim.bo.comments)
@ -1146,11 +1146,11 @@ vim.wo[{winid}] *
Like `:set`. If [{winid}] is omitted then the current window is used.
Invalid {winid} or key is an error.
Note: this does not access |local-options| (`:setlocal`) instead use: >
Note: this does not access |local-options| (`:setlocal`) instead use: >lua
nvim_get_option_value(OPTION, { scope = 'local', win = winid })
nvim_set_option_value(OPTION, VALUE, { scope = 'local', win = winid }
<
Example: >
Example: >lua
local winid = vim.api.nvim_get_current_win()
vim.wo[winid].number = true -- same as vim.wo.number = true
print(vim.wo.foldmarker)
@ -1232,7 +1232,7 @@ Option:get()
values will be returned in exactly the same fashion.
For values that are comma-separated lists, an array will be returned with
the values as entries in the array: >
the values as entries in the array: >lua
vim.cmd [[set wildignore=*.pyc,*.o]]
vim.pretty_print(vim.opt.wildignore:get())
@ -1245,7 +1245,7 @@ Option:get()
-- Will ignore: *.o
<
For values that are comma-separated maps, a table will be returned with
the names as keys and the values as entries: >
the names as keys and the values as entries: >lua
vim.cmd [[set listchars=space:_,tab:>~]]
vim.pretty_print(vim.opt.listchars:get())
@ -1256,7 +1256,7 @@ Option:get()
end
<
For values that are lists of flags, a set will be returned with the flags
as keys and `true` as entries. >
as keys and `true` as entries. >lua
vim.cmd [[set formatoptions=njtcroql]]
vim.pretty_print(vim.opt.formatoptions:get())

2
runtime/queries/help/highlights.scm
View File

@ -17,7 +17,7 @@
text: (_) @text.literal)
(codeblock) @text.literal
(codeblock
">" @conceal (#set! conceal ""))
[">" (language)] @conceal (#set! conceal ""))
(block
"<" @conceal (#set! conceal ""))
(argument) @parameter

3
runtime/queries/help/injections.scm Normal file
View File

@ -0,0 +1,3 @@
(codeblock
(language) @language
(code) @content)

5
runtime/syntax/help.vim
View File

@ -14,10 +14,11 @@ set cpo&vim
syn match helpHeadline "^[A-Z.][-A-Z0-9 .,()_']*?\=\ze\(\s\+\*\|$\)"
syn match helpSectionDelim "^===.*===$"
syn match helpSectionDelim "^---.*--$"
" Neovim: support language annotation in codeblocks
if has("conceal")
syn region helpExample matchgroup=helpIgnore start=" >$" start="^>$" end="^[^ \t]"me=e-1 end="^<" concealends
syn region helpExample matchgroup=helpIgnore start=" >[a-z0-9]*$" start="^[a-z0-9]*>$" end="^[^ \t]"me=e-1 end="^<" concealends
else
syn region helpExample matchgroup=helpIgnore start=" >$" start="^>$" end="^[^ \t]"me=e-1 end="^<"
syn region helpExample matchgroup=helpIgnore start=" >[a-z0-9]*$" start="^[a-z0-9]*>$" end="^[^ \t]"me=e-1 end="^<"
endif
syn match helpHyperTextJump "\\\@<!|[#-)!+-~]\+|" contains=helpBar
syn match helpHyperTextEntry "\*[#-)!+-~]\+\*\s"he=e-1 contains=helpStar

7
scripts/gen_help_html.lua
View File

@ -489,7 +489,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
end
return string.format('<div class="help-para">\n%s\n</div>\n', text)
elseif node_name == 'line' then
if parent ~= 'codeblock' and (is_blank(text) or is_noise(text, stats.noise_lines)) then
if parent ~= 'code' and (is_blank(text) or is_noise(text, stats.noise_lines)) then
return '' -- Discard common "noise" lines.
end
-- XXX: Avoid newlines (too much whitespace) after block elements in old (preformatted) layout.
@ -535,7 +535,12 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
return s
elseif node_name == 'argument' then
return ('%s<code>{%s}</code>'):format(ws(), text)
-- TODO: use language for proper syntax highlighted code blocks
elseif node_name == 'codeblock' then
return text
elseif node_name == 'language' then
return ''
elseif node_name == 'code' then
if is_blank(text) then
return ''
end