Merge remote-tracking branch 'upstream/master' into colorcolchar

1 files changed, 333 insertions, 215 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 7330453778..47249a484b 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -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))
 
@@ -21,20 +21,19 @@ Nvim includes a "standard library" |lua-stdlib| for Lua.  It complements the
 which can be used from Lua code (|lua-vimscript| |vim.api|). Together these
 "namespaces" form the Nvim programming interface.
 
-The |:source| and |:runtime| commands can run Lua scripts. Lua modules can be
-loaded with `require('name')`, which by convention usually returns a table.
-See |lua-require| for how Nvim finds and loads Lua modules.
-
-See this page for more insight into Nvim Lua:
-    https://github.com/nanotee/nvim-lua-guide
+Lua plugins and user config are automatically discovered and loaded, just like
+Vimscript. See |lua-guide| for practical guidance.
 
+You can also run Lua scripts from your shell using the |-l| argument: >
+    nvim -l foo.lua [args...]
+<
                                                                   *lua-compat*
 Lua 5.1 is the permanent interface for Nvim Lua.  Plugins need only consider
 Lua 5.1, not worry about forward-compatibility with future Lua versions.  If
 Nvim ever ships with Lua 5.4+, a Lua 5.1 compatibility shim will be provided
 so that old plugins continue to work transparently.
 
-------------------------------------------------------------------------------
+==============================================================================
 LUA CONCEPTS AND IDIOMS                                         *lua-concepts*
 
 Lua is very simple: this means that, while there are some quirks, once you
@@ -56,20 +55,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
@@ -78,25 +77,24 @@ In Lua, any missing arguments are passed as `nil`. Example: >
 Furthermore it is not an error if extra parameters are passed, they are just
 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*
+When calling a function, you can omit the parentheses if the function takes
+exactly one string literal (`"foo"`) or table literal (`{1,2,3}`). The latter
+is often used to approximate "named parameters" ("kwargs" or "keyword args")
+as in languages like Python and C#. Example: >lua
     local func_with_opts = function(opts)
         local will_do_foo = opts.foo
         local filename = opts.filename
-
         ...
     end
 
     func_with_opts { foo = true, filename = "hello.world" }
 <
-There is nothing special going on here except that parentheses are treated as
+There's 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" })
 <
 Nvim tends to prefer the keyword args style.
@@ -105,27 +103,22 @@ Nvim tends to prefer the keyword args style.
 LUA PATTERNS                                                    *lua-patterns*
 
 Lua intentionally does not support regular expressions, instead it has limited
-"patterns" which avoid the performance pitfalls of extended regex.
-|luaref-patterns|
+"patterns" |luaref-patterns| which avoid the performance pitfalls of extended
+regex. Lua scripts can also use Vim regex via |vim.regex()|.
 
-Examples using |string.match()|: >
+These examples use |string.match()| to demonstrate Lua patterns: >lua
 
     print(string.match("foo123bar123", "%d+"))
     -- 123
-
     print(string.match("foo123bar123", "[^%d]+"))
     -- foo
-
     print(string.match("foo123bar123", "[abc]+"))
     -- ba
-
     print(string.match("foo.bar", "%.bar"))
     -- .bar
 
-For more complex matching you can use Vim regex from Lua via |vim.regex()|.
-
 ==============================================================================
-IMPORTING LUA MODULES                                            *lua-require*
+IMPORTING LUA MODULES                                  *require()* *lua-require*
 
 Modules are searched for under the directories specified in 'runtimepath', in
 the order they appear.  Any "." in the module name is treated as a directory
@@ -139,8 +132,7 @@ back to Lua's default search mechanism. The first script found is run and
 
 The return value is cached after the first call to `require()` for each module,
 with subsequent calls returning the cached value without searching for, or
-executing any script. For further details on `require()`, see the Lua
-documentation at https://www.lua.org/manual/5.1/manual.html#pdf-require.
+executing any script. For further details on `require()`, see |luaref-require()|.
 
 For example, if 'runtimepath' is `foo,bar` and |package.cpath| was
 `./?.so;./?.dll` at startup, `require('mod')` searches these paths in order
@@ -205,7 +197,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 +223,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 +238,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 +260,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 +274,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 +285,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 +299,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 +335,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,29 +352,29 @@ 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 >
-    v:lua.func(arg1, arg2)
-is equivalent to the Lua chunk >
+which are global or accessible from global tables. The expression >vim
+    call v:lua.func(arg1, arg2)
+is equivalent to the Lua chunk >lua
     return func(...)
-where the args are converted to Lua values. The expression >
-    v:lua.somemod.func(args)
-is equivalent to the Lua chunk >
+where the args are converted to Lua values. The expression >vim
+    call v:lua.somemod.func(args)
+is equivalent to the Lua chunk >lua
     return somemod.func(...)
 
-In addition, functions of packages can be accessed like >
-    v:lua.require'mypack'.func(arg1, arg2)
-    v:lua.require'mypack.submod'.func(arg1, arg2)
+In addition, functions of packages can be accessed like >vim
+    call v:lua.require'mypack'.func(arg1, arg2)
+    call v:lua.require'mypack.submod'.func(arg1, arg2)
 Note: Only single quote form without parens is allowed. Using
 `require"mypack"` or `require('mypack')` as prefixes do NOT work (the latter
 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: >
-    arg1->v:lua.somemod.func(arg2)
+example: >vim
+    :eval 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
@@ -394,10 +386,10 @@ For example consider the following Lua omnifunc handler: >
     vim.api.nvim_buf_set_option(0, 'omnifunc', 'v:lua.mymod.omnifunc')
 
 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.
+or use require() as shown 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 +403,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 +423,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 +435,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 +444,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 +463,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 +484,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 +507,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 +556,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()*
@@ -609,6 +601,7 @@ vim.highlight.priorities                            *vim.highlight.priorities*
     Table with default priorities used for highlighting:
         • `syntax`: `50`, used for standard syntax highlighting
         • `treesitter`: `100`, used for tree-sitter-based highlighting
+        • `semantic_tokens`: `125`, used for LSP semantic token highlighting
         • `diagnostics`: `150`, used for code analysis such as diagnostics
         • `user`: `200`, used for user-triggered highlights such as LSP document
           symbols or `on_yank` autocommands
@@ -646,20 +639,19 @@ vim.diff({a}, {b}, {opts})                                        *vim.diff()*
     Run diff on strings {a} and {b}. Any indices returned by this function,
     either directly or via callback arguments, are 1-based.
 
-    Examples: >
-
+    Examples: >lua
         vim.diff('a\n', 'b\nc\n')
-        =>
-        @@ -1 +1,2 @@
-        -a
-        +b
-        +c
+        -- =>
+        -- @@ -1 +1,2 @@
+        -- -a
+        -- +b
+        -- +c
 
         vim.diff('a\n', 'b\nc\n', {result_type = 'indices'})
-        =>
-        {
-            {1, 1, 1, 2}
-        }
+        -- =>
+        -- {
+        --   {1, 1, 1, 2}
+        -- }
 <
     Parameters: ~
       • {a}      First string to compare
@@ -677,6 +669,9 @@ vim.diff({a}, {b}, {opts})                                        *vim.diff()*
                    • "unified": (default) String in unified format.
                    • "indices": Array of hunk locations.
                    Note: This option is ignored if `on_hunk` is used.
+                 • `linematch` (boolean): Run linematch on the resulting hunks
+                   from xdiff. Requires `result_type = indices`, ignored
+                   otherwise.
                  • `algorithm` (string):
                    Diff algorithm to use. Values:
                    • "myers"      the default algorithm
@@ -717,6 +712,22 @@ vim.mpack.decode({str})                                     *vim.mpack.decode*
     Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object.
 
 ------------------------------------------------------------------------------
+VIM.JSON                                                            *lua-json*
+
+The *vim.json* module provides encoding and decoding of Lua objects to and
+from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
+
+vim.json.encode({obj})                                       *vim.json.encode*
+    Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
+
+vim.json.decode({str}[, {opts}])                             *vim.json.decode*
+    Decodes (or "unpacks") the JSON-encoded {str} to a Lua object.
+
+    {opts} is a table with the key `luanil = { object: bool, array: bool }`
+    that controls whether `null` in JSON objects or arrays should be converted
+    to Lua `nil` instead of `vim.NIL`.
+
+------------------------------------------------------------------------------
 VIM.SPELL                                                          *lua-spell*
 
 vim.spell.check({str})                                     *vim.spell.check()*
@@ -727,13 +738,12 @@ vim.spell.check({str})                                     *vim.spell.check()*
     'spellfile', 'spellcapcheck' and 'spelloptions' which can all be local to
     the buffer. Consider calling this with |nvim_buf_call()|.
 
-    Example: >
-
+    Example: >lua
         vim.spell.check("the quik brown fox")
-        =>
-        {
-            {'quik', 'bad', 4}
-        }
+        -- =>
+        -- {
+        --     {'quik', 'bad', 5}
+        -- }
 <
     Parameters: ~
       • {str}    String to spell check.
@@ -753,7 +763,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*
@@ -878,7 +888,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
@@ -919,7 +929,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')
 
@@ -947,7 +957,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,
@@ -994,7 +1004,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})
@@ -1002,7 +1012,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
@@ -1025,7 +1035,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.
@@ -1038,7 +1048,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
 
@@ -1073,7 +1083,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)
 <
@@ -1107,7 +1117,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
@@ -1120,7 +1130,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
@@ -1132,7 +1142,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)
@@ -1143,11 +1153,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)
@@ -1156,9 +1166,8 @@ vim.wo[{winid}]                                                                *
 
 
 
-                                                                          *lua-vim-opt*
-                                                                     *lua-vim-optlocal*
-                                                                    *lua-vim-optglobal*
+                                                                        *vim.opt_local*
+                                                                       *vim.opt_global*
                                                                               *vim.opt*
 
 
@@ -1169,37 +1178,37 @@ offers object-oriented method for adding and removing entries.
     Examples: ~
 
     The following methods of setting a list-style option are equivalent:
-        In Vimscript:
-            `set wildignore=*.o,*.a,__pycache__`
-
-        In Lua using `vim.o`:
-            `vim.o.wildignore = '*.o,*.a,__pycache__'`
-
-        In Lua using `vim.opt`:
-            `vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }`
-
-    To replicate the behavior of |:set+=|, use: >
+        In Vimscript: >vim
+            set wildignore=*.o,*.a,__pycache__
+<
+        In Lua using `vim.o`: >lua
+            vim.o.wildignore = '*.o,*.a,__pycache__'
+<
+        In Lua using `vim.opt`: >lua
+            vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }
+<
+    To replicate the behavior of |:set+=|, use: >lua
 
         vim.opt.wildignore:append { "*.pyc", "node_modules" }
 <
-    To replicate the behavior of |:set^=|, use: >
+    To replicate the behavior of |:set^=|, use: >lua
 
         vim.opt.wildignore:prepend { "new_first_value" }
 <
-    To replicate the behavior of |:set-=|, use: >
+    To replicate the behavior of |:set-=|, use: >lua
 
         vim.opt.wildignore:remove { "node_modules" }
 <
     The following methods of setting a map-style option are equivalent:
-        In Vimscript:
-            `set listchars=space:_,tab:>~`
-
-        In Lua using `vim.o`:
-            `vim.o.listchars = 'space:_,tab:>~'`
-
-        In Lua using `vim.opt`:
-            `vim.opt.listchars = { space = '_', tab = '>~' }`
-
+        In Vimscript: >vim
+            set listchars=space:_,tab:>~
+<
+        In Lua using `vim.o`: >lua
+            vim.o.listchars = 'space:_,tab:>~'
+<
+        In Lua using `vim.opt`: >lua
+            vim.opt.listchars = { space = '_', tab = '>~' }
+<
 
 Note that |vim.opt| returns an `Option` object, not the value of the option,
 which is accessed through |vim.opt:get()|:
@@ -1207,15 +1216,15 @@ which is accessed through |vim.opt:get()|:
     Examples: ~
 
     The following methods of getting a list-style option are equivalent:
-        In Vimscript:
-            `echo wildignore`
-
-        In Lua using `vim.o`:
-            `print(vim.o.wildignore)`
-
-        In Lua using `vim.opt`:
-            `vim.pretty_print(vim.opt.wildignore:get())`
-
+        In Vimscript: >vim
+            echo wildignore
+<
+        In Lua using `vim.o`: >lua
+            print(vim.o.wildignore)
+<
+        In Lua using `vim.opt`: >lua
+            vim.pretty_print(vim.opt.wildignore:get())
+<
 
 In any of the above examples, to replicate the behavior |:setlocal|, use
 `vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use
@@ -1230,7 +1239,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())
@@ -1243,7 +1252,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())
@@ -1254,7 +1263,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())
@@ -1270,28 +1279,28 @@ Option:append(value)
 
     Append a value to string-style options. See |:set+=|
 
-    These are equivalent:
-        `vim.opt.formatoptions:append('j')`
-        `vim.opt.formatoptions = vim.opt.formatoptions + 'j'`
-
+    These are equivalent: >lua
+        vim.opt.formatoptions:append('j')
+        vim.opt.formatoptions = vim.opt.formatoptions + 'j'
+<
                                                            *vim.opt:prepend()*
 Option:prepend(value)
 
     Prepend a value to string-style options. See |:set^=|
 
-    These are equivalent:
-        `vim.opt.wildignore:prepend('*.o')`
-        `vim.opt.wildignore = vim.opt.wildignore ^ '*.o'`
-
+    These are equivalent: >lua
+        vim.opt.wildignore:prepend('*.o')
+        vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
+<
                                                             *vim.opt:remove()*
 Option:remove(value)
 
     Remove a value from string-style options. See |:set-=|
 
-    These are equivalent:
-        `vim.opt.wildignore:remove('*.pyc')`
-        `vim.opt.wildignore = vim.opt.wildignore - '*.pyc'`
-
+    These are equivalent: >lua
+        vim.opt.wildignore:remove('*.pyc')
+        vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
+<
 
 ==============================================================================
 Lua module: vim                                                      *lua-vim*
@@ -1302,7 +1311,7 @@ cmd({command})                                                     *vim.cmd()*
     Note that `vim.cmd` can be indexed with a command name to return a
     callable function to the command.
 
-    Example: >
+    Example: >lua
 
        vim.cmd('echo 42')
        vim.cmd([[
@@ -1436,7 +1445,7 @@ paste({lines}, {phase})                                          *vim.paste()*
     Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the
     |TUI|) pastes text into the editor.
 
-    Example: To remove ANSI color codes when pasting: >
+    Example: To remove ANSI color codes when pasting: >lua
 
      vim.paste = (function(overridden)
        return function(lines, phase)
@@ -1465,7 +1474,7 @@ paste({lines}, {phase})                                          *vim.paste()*
         |paste| @alias paste_phase -1 | 1 | 2 | 3
 
 pretty_print({...})                                       *vim.pretty_print()*
-    Prints given arguments in human-readable format. Example: >
+    Prints given arguments in human-readable format. Example: >lua
       -- Print highlight group Normal and store it's contents in a variable.
       local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
 <
@@ -1490,8 +1499,7 @@ region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})         *vim.region()*
                      end-inclusive
 
     Return: ~
-        table<integer, {}> region lua table of the form {linenr =
-        {startcol,endcol}}
+        (table) region Table of the form `{linenr = {startcol,endcol}}`
 
 schedule_wrap({cb})                                      *vim.schedule_wrap()*
     Defers callback `cb` until the Nvim API is safe to call.
@@ -1508,6 +1516,56 @@ schedule_wrap({cb})                                      *vim.schedule_wrap()*
         |vim.in_fast_event()|
 
 
+==============================================================================
+Lua module: inspector                                          *lua-inspector*
+
+inspect_pos({bufnr}, {row}, {col}, {filter})               *vim.inspect_pos()*
+    Get all the items at a given buffer position.
+
+    Can also be pretty-printed with `:Inspect!`.                   *:Inspect!*
+
+    Parameters: ~
+      • {bufnr}   (number|nil) defaults to the current buffer
+      • {row}     (number|nil) row to inspect, 0-based. Defaults to the row of
+                  the current cursor
+      • {col}     (number|nil) col to inspect, 0-based. Defaults to the col of
+                  the current cursor
+      • {filter}  (table|nil) a table with key-value pairs to filter the items
+                  • syntax (boolean): include syntax based highlight groups
+                    (defaults to true)
+                  • treesitter (boolean): include treesitter based highlight
+                    groups (defaults to true)
+                  • extmarks (boolean|"all"): include extmarks. When `all`,
+                    then extmarks without a `hl_group` will also be included
+                    (defaults to true)
+                  • semantic_tokens (boolean): include semantic tokens
+                    (defaults to true)
+
+    Return: ~
+        (table) a table with the following key-value pairs. Items are in
+        "traversal order":
+        • treesitter: a list of treesitter captures
+        • syntax: a list of syntax groups
+        • semantic_tokens: a list of semantic tokens
+        • extmarks: a list of extmarks
+        • buffer: the buffer used to get the items
+        • row: the row used to get the items
+        • col: the col used to get the items
+
+show_pos({bufnr}, {row}, {col}, {filter})                     *vim.show_pos()*
+    Show all the items at a given buffer position.
+
+    Can also be shown with `:Inspect`.                              *:Inspect*
+
+    Parameters: ~
+      • {bufnr}   (number|nil) defaults to the current buffer
+      • {row}     (number|nil) row to inspect, 0-based. Defaults to the row of
+                  the current cursor
+      • {col}     (number|nil) col to inspect, 0-based. Defaults to the col of
+                  the current cursor
+      • {filter}  (table|nil) see |vim.inspect_pos()|
+
+
 
 
 deep_equal({a}, {b})                                        *vim.deep_equal()*
@@ -1544,10 +1602,11 @@ defaulttable({create})                                    *vim.defaulttable()*
     If {create} is `nil`, this will create a defaulttable whose constructor
     function is this function, effectively allowing to create nested tables on
     the fly:
->
 
-    local a = vim.defaulttable()
-    a.b.c = 1
+    >lua
+
+     local a = vim.defaulttable()
+     a.b.c = 1
 <
 
     Parameters: ~
@@ -1573,7 +1632,7 @@ gsplit({s}, {sep}, {plain})                                     *vim.gsplit()*
     Parameters: ~
       • {s}      (string) String to split
       • {sep}    (string) Separator or pattern
-      • {plain}  (boolean) If `true` use `sep` literally (passed to
+      • {plain}  (boolean|nil) If `true` use `sep` literally (passed to
                  string.find)
 
     Return: ~
@@ -1581,6 +1640,7 @@ gsplit({s}, {sep}, {plain})                                     *vim.gsplit()*
 
     See also: ~
         |vim.split()|
+        |luaref-patterns|
         https://www.lua.org/pil/20.2.html
         http://lua-users.org/wiki/StringLibraryTutorial
 
@@ -1616,8 +1676,8 @@ list_slice({list}, {start}, {finish})                       *vim.list_slice()*
 
     Parameters: ~
       • {list}    (list) Table
-      • {start}   (number) Start range of slice
-      • {finish}  (number) End range of slice
+      • {start}   (number|nil) Start range of slice
+      • {finish}  (number|nil) End range of slice
 
     Return: ~
         (list) Copy of table sliced from start to finish (inclusive)
@@ -1634,22 +1694,29 @@ pesc({s})                                                         *vim.pesc()*
     See also: ~
         https://github.com/rxi/lume
 
+spairs({t})                                                     *vim.spairs()*
+    Enumerate a table sorted by its keys.
+
+    Parameters: ~
+      • {t}  (table) List-like table
+
+    Return: ~
+        iterator over sorted keys and their values
+
+    See also: ~
+        Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
+
 split({s}, {sep}, {kwargs})                                      *vim.split()*
     Splits a string at each instance of a separator.
 
-    Examples: >
+    Examples: >lua
 
-      split(":aa::b:", ":")     => {'','aa','','b',''}
-      split("axaby", "ab?")     => {'','x','y'}
-      split("x*yz*o", "*", {plain=true})  => {'x','yz','o'}
-      split("|x|y|z|", "|", {trimempty=true}) => {'x', 'y', 'z'}
+      split(":aa::b:", ":")                   --> {'','aa','','b',''}
+      split("axaby", "ab?")                   --> {'','x','y'}
+      split("x*yz*o", "*", {plain=true})      --> {'x','yz','o'}
+      split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
 <
 
-    @alias split_kwargs {plain: boolean, trimempty: boolean} | boolean | nil
-
-    See also: ~
-        |vim.gsplit()|
-
     Parameters: ~
       • {s}       (string) String to split
       • {sep}     (string) Separator or pattern
@@ -1662,6 +1729,9 @@ split({s}, {sep}, {kwargs})                                      *vim.split()*
     Return: ~
         string[] List of split components
 
+    See also: ~
+        |vim.gsplit()|
+
 startswith({s}, {prefix})                                   *vim.startswith()*
     Tests if `s` starts with `prefix`.
 
@@ -1696,10 +1766,11 @@ tbl_contains({t}, {value})                                *vim.tbl_contains()*
 
 tbl_count({t})                                               *vim.tbl_count()*
     Counts the number of non-nil values in table `t`.
->
 
-    vim.tbl_count({ a=1, b=2 }) => 2
-    vim.tbl_count({ 1, 2 }) => 2
+    >lua
+
+     vim.tbl_count({ a=1, b=2 })  --> 2
+     vim.tbl_count({ 1, 2 })      --> 2
 <
 
     Parameters: ~
@@ -1772,7 +1843,7 @@ tbl_get({o}, {...})                                            *vim.tbl_get()*
     Index into a table (first argument) via string keys passed as subsequent
     arguments. Return `nil` if the key does not exist.
 
-    Examples: >
+    Examples: >lua
 
       vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
       vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
@@ -1854,12 +1925,13 @@ trim({s})                                                         *vim.trim()*
         (string) String with whitespace removed from its beginning and end
 
     See also: ~
+        |luaref-patterns|
         https://www.lua.org/pil/20.2.html
 
 validate({opt})                                               *vim.validate()*
     Validates a parameter specification (types and values).
 
-    Usage example: >
+    Usage example: >lua
 
       function user.new(name, age, hobbies)
         vim.validate{
@@ -1871,25 +1943,25 @@ validate({opt})                                               *vim.validate()*
       end
 <
 
-    Examples with explicit argument values (can be run directly): >
+    Examples with explicit argument values (can be run directly): >lua
 
       vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
-         => NOP (success)
+         --> NOP (success)
 
       vim.validate{arg1={1, 'table'}}
-         => error('arg1: expected table, got number')
+         --> error('arg1: expected table, got number')
 
       vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
-         => error('arg1: expected even number, got 3')
+         --> error('arg1: expected even number, got 3')
 <
 
-    If multiple types are valid they can be given as a list. >
+    If multiple types are valid they can be given as a list. >lua
 
       vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
-         => NOP (success)
+         --> NOP (success)
 
       vim.validate{arg1={1, {'string', table'}}}
-         => error('arg1: expected string|table, got number')
+         --> error('arg1: expected string|table, got number')
 <
 
     Parameters: ~
@@ -1958,7 +2030,7 @@ Lua module: ui                                                        *lua-ui*
 input({opts}, {on_confirm})                                   *vim.ui.input()*
     Prompts the user for input
 
-    Example: >
+    Example: >lua
 
      vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
          vim.o.shiftwidth = tonumber(input)
@@ -1977,12 +2049,13 @@ input({opts}, {on_confirm})                                   *vim.ui.input()*
                         highlighting user inputs.
       • {on_confirm}  (function) ((input|nil) -> ()) Called once the user
                       confirms or abort the input. `input` is what the user
-                      typed. `nil` if the user aborted the dialog.
+                      typed (it might be an empty string if nothing was
+                      entered), or `nil` if the user aborted the dialog.
 
 select({items}, {opts}, {on_choice})                         *vim.ui.select()*
     Prompts the user to pick a single item from a collection of entries
 
-    Example: >
+    Example: >lua
 
      vim.ui.select({ 'tabs', 'spaces' }, {
          prompt = 'Select tabs or spaces:',
@@ -2045,10 +2118,7 @@ add({filetypes})                                          *vim.filetype.add()*
 
     See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
 
-    Note that Lua filetype detection is disabled when |g:do_legacy_filetype|
-    is set.
-
-    Example: >
+    Example: >lua
 
       vim.filetype.add({
         extension = {
@@ -2084,7 +2154,7 @@ add({filetypes})                                          *vim.filetype.add()*
       })
 <
 
-    To add a fallback match on contents (see |new-filetype-scripts|), use >
+    To add a fallback match on contents, use >lua
 
      vim.filetype.add {
        pattern = {
@@ -2123,19 +2193,20 @@ match({args})                                           *vim.filetype.match()*
 
     Each of the three options is specified using a key to the single argument
     of this function. Example:
->
 
-    -- Using a buffer number
-    vim.filetype.match({ buf = 42 })
+    >lua
 
-    -- Override the filename of the given buffer
-    vim.filetype.match({ buf = 42, filename = 'foo.c' })
+       -- Using a buffer number
+       vim.filetype.match({ buf = 42 })
 
-    -- Using a filename without a buffer
-    vim.filetype.match({ filename = 'main.lua' })
+       -- Override the filename of the given buffer
+       vim.filetype.match({ buf = 42, filename = 'foo.c' })
 
-    -- Using file contents
-    vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
+       -- Using a filename without a buffer
+       vim.filetype.match({ filename = 'main.lua' })
+
+       -- Using file contents
+       vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
 <
 
     Parameters: ~
@@ -2165,7 +2236,7 @@ match({args})                                           *vim.filetype.match()*
 Lua module: keymap                                                *lua-keymap*
 
 del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
-    Remove an existing mapping. Examples: >
+    Remove an existing mapping. Examples: >lua
 
        vim.keymap.del('n', 'lhs')
 
@@ -2181,7 +2252,7 @@ del({modes}, {lhs}, {opts})                                 *vim.keymap.del()*
         |vim.keymap.set()|
 
 set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
-    Add a new |mapping|. Examples: >
+    Add a new |mapping|. Examples: >lua
 
        -- Can add mapping to Lua functions
        vim.keymap.set('n', 'lhs', function() print("real lua function") end)
@@ -2200,14 +2271,14 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
        vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
 <
 
-    Note that in a mapping like: >
+    Note that in a mapping like: >lua
 
         vim.keymap.set('n', 'asdf', require('jkl').my_fun)
 <
 
     the `require('jkl')` gets evaluated during this call in order to access the function. If you
     want to avoid this cost at startup you can wrap it in a function, for
-    example: >
+    example: >lua
 
         vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
 <
@@ -2249,13 +2320,18 @@ basename({file})                                           *vim.fs.basename()*
     Return: ~
         (string) Basename of {file}
 
-dir({path})                                                     *vim.fs.dir()*
+dir({path}, {opts})                                             *vim.fs.dir()*
     Return an iterator over the files and directories located in {path}
 
     Parameters: ~
       • {path}  (string) An absolute or relative path to the directory to
                 iterate over. The path is first normalized
                 |vim.fs.normalize()|.
+      • {opts}  table|nil Optional keyword arguments:
+                • depth: integer|nil How deep the traverse (default 1)
+                • skip: (fun(dir_name: string): boolean)|nil Predicate to
+                  control traversal. Return false to stop searching the
+                  current directory. Only useful when depth > 1
 
     Return: ~
         Iterator over files and directories in {path}. Each iteration yields
@@ -2280,17 +2356,18 @@ find({names}, {opts})                                          *vim.fs.find()*
     searches are recursive and may search through many directories! If {stop}
     is non-nil, then the search stops when the directory given in {stop} is
     reached. The search terminates when {limit} (default 1) matches are found.
-    The search can be narrowed to find only files or or only directories by
+    The search can be narrowed to find only files or only directories by
     specifying {type} to be "file" or "directory", respectively.
 
     Parameters: ~
       • {names}  (string|table|fun(name: string): boolean) Names of the files
                  and directories to find. Must be base names, paths and globs
-                 are not supported. If a function it is called per file and
-                 dir within the traversed directories to test if they match.
+                 are not supported. The function is called per file and
+                 directory within the traversed directories to test if they
+                 match {names}.
       • {opts}   (table) Optional keyword arguments:
                  • path (string): Path to begin searching from. If omitted,
-                   the current working directory is used.
+                   the |current-directory| is used.
                  • upward (boolean, default false): If true, search upward
                    through parent directories. Otherwise, search through child
                    directories (recursively).
@@ -2298,13 +2375,14 @@ find({names}, {opts})                                          *vim.fs.find()*
                    reached. The directory itself is not searched.
                  • type (string): Find only files ("file") or directories
                    ("directory"). If omitted, both files and directories that
-                   match {name} are included.
+                   match {names} are included.
                  • limit (number, default 1): Stop the search after finding
                    this many matches. Use `math.huge` to place no limit on the
                    number of matches.
 
     Return: ~
-        (table) The paths of all matching files or directories
+        (table) Normalized paths |vim.fs.normalize()| of all matching files or
+        directories
 
 normalize({path})                                         *vim.fs.normalize()*
     Normalize a path to a standard format. A tilde (~) character at the
@@ -2312,16 +2390,16 @@ normalize({path})                                         *vim.fs.normalize()*
     backslash (\) characters are converted to forward slashes (/). Environment
     variables are also expanded.
 
-    Example: >
+    Examples: >lua
 
-     vim.fs.normalize('C:\Users\jdoe')
-     => 'C:/Users/jdoe'
+       vim.fs.normalize('C:\\Users\\jdoe')
+       --> 'C:/Users/jdoe'
 
-     vim.fs.normalize('~/src/neovim')
-     => '/home/jdoe/src/neovim'
+       vim.fs.normalize('~/src/neovim')
+       --> '/home/jdoe/src/neovim'
 
-     vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
-     => '/Users/jdoe/.config/nvim/init.vim'
+       vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
+       --> '/Users/jdoe/.config/nvim/init.vim'
 <
 
     Parameters: ~
@@ -2333,7 +2411,7 @@ normalize({path})                                         *vim.fs.normalize()*
 parents({start})                                            *vim.fs.parents()*
     Iterate over all the parents of the given file or directory.
 
-    Example: >
+    Example: >lua
 
      local root_dir
      for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
@@ -2354,4 +2432,44 @@ parents({start})                                            *vim.fs.parents()*
     Return: ~
         (function) Iterator
 
+
+==============================================================================
+Lua module: secure                                                *lua-secure*
+
+read({path})                                               *vim.secure.read()*
+    Attempt to read the file at {path} prompting the user if the file should
+    be trusted. The user's choice is persisted in a trust database at
+    $XDG_STATE_HOME/nvim/trust.
+
+    Parameters: ~
+      • {path}  (string) Path to a file to read.
+
+    Return: ~
+        (string|nil) The contents of the given file if it exists and is
+        trusted, or nil otherwise.
+
+    See also: ~
+        |:trust|
+
+trust({opts})                                             *vim.secure.trust()*
+    Manage the trust database.
+
+    The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
+
+    Parameters: ~
+      • {opts}  (table)
+                • action (string): "allow" to add a file to the trust database
+                  and trust it, "deny" to add a file to the trust database and
+                  deny it, "remove" to remove file from the trust database
+                • path (string|nil): Path to a file to update. Mutually
+                  exclusive with {bufnr}. Cannot be used when {action} is
+                  "allow".
+                • bufnr (number|nil): Buffer number to update. Mutually
+                  exclusive with {path}.
+
+    Return: ~
+        (boolean, string) success, msg:
+        • true and full path of target file if operation was successful
+        • false and error message on failure
+
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: