* feat(lua): allow vim.wo to be double indexed
Problem: `vim.wo` does not implement `setlocal`
Solution: Allow `vim.wo` to be double indexed
Co-authored-by: Christian Clason <c.clason@uni-graz.at>
Problem:
The parent commit added a new vim.get_visual_selection() function to
improve visual star. But that is redundant with vim.region(). Any
current limitations of vim.region() should be fixed instead of adding
a new function.
Solution:
Delete vim.get_visual_selection().
Use vim.region() to get the visual selection.
TODO: fails with visual "block" selections.
Problem:
Visual mode "*", "#" mappings don't work on text with "/", "\", "?", and
newlines.
Solution:
Get the visual selection and escape it as a search pattern.
Add functions vim.get_visual_selection and _search_for_visual_selection.
Fix#21676
Problem:
Showing an error via vim.notify() makes it awkward for callers such as
lsp/handlers.lua to avoid showing redundant errors.
Solution:
Return the message instead of showing it. Let the caller decide whether
and when to show the message.
---
Rejected experiment: move vim.ui.open() to vim.env.open()
Problem:
`vim.ui` is where user-interface "providers" live, which can be
overridden. It would also be useful to have a "providers" namespace for
platform-specific features such as "open", clipboard, python, and the other
providers listed in `:help providers`. We could overload `vim.ui` to
serve that purpose as the single "providers" namespace, but
`vim.ui.nodejs()` for example seems awkward.
Solution:
`vim.env` currently has too narrow of a purpose. Overload it to also be
a namespace for `vim.env.open`.
diff --git a/runtime/lua/vim/_meta.lua b/runtime/lua/vim/_meta.lua
index 913f1fe20348..17d05ff37595 100644
--- a/runtime/lua/vim/_meta.lua
+++ b/runtime/lua/vim/_meta.lua
@@ -37,8 +37,28 @@ local options_info = setmetatable({}, {
end,
})
-vim.env = setmetatable({}, {
- __index = function(_, k)
+vim.env = setmetatable({
+ open = setmetatable({}, {
+ __call = function(_, uri)
+ print('xxxxx'..uri)
+ return true
+ end,
+ __tostring = function()
+ local v = vim.fn.getenv('open')
+ if v == vim.NIL then
+ return nil
+ end
+ return v
+ end,
+ })
+ },
+ {
+ __index = function(t, k, ...)
+ if k == 'open' then
+ error()
+ -- vim.print({...})
+ -- return rawget(t, k)
+ end
local v = vim.fn.getenv(k)
if v == vim.NIL then
return nil
Enforce consistent terminology (defined in
`gen_help_html.lua:spell_dict`) for common misspellings.
This does not spellcheck English in general (perhaps a future TODO,
though it may be noisy).
Problem:
- `vim.json` exposes various global options which:
- affect all Nvim Lua plugins (especially the LSP client)
- are undocumented and untested
- can cause confusing problems such as: cc76ae3abe
- `vim.json` exposes redundant mechanisms:
- `vim.json.null` is redundant with `vim.NIL`.
- `array_mt` is redundant because Nvim uses a metatable
(`vim.empty_dict()`) for empty dict instead, which `vim.json` is
configured to use by default (see `as_empty_dict`).
Example:
```
:lua vim.print(vim.json.decode('{"bar":[],"foo":{}}'))
--> { bar = {}, foo = vim.empty_dict() }
```
Thus we don't need to also decorate empty arrays with `array_mt`.
Solution:
Remove the functions from the public vim.json interface.
Comment-out the implementation code to minimize drift from upstream.
TODO:
- Expose the options as arguments to `vim.json.new()`
Co-authored by: zeertzjq <zeertzjq@outlook.com>
Co-authored by: Steven Todd McIntyre II <114119064+stmii@users.noreply.github.com>
Co-authored by: nobe4 <nobe4@users.noreply.github.com>
- docs: mention --luadev-mod to run with lua runtime files
When changing a lua file in the ./runtime folder, a new contributor
might expect changes to be applied to the built Neovim binary.
feat(lua): add vim.system()
Problem:
Handling system commands in Lua is tedious and error-prone:
- vim.fn.jobstart() is vimscript and comes with all limitations attached to typval.
- vim.loop.spawn is too low level
Solution:
Add vim.system().
Partly inspired by Python's subprocess module
Does not expose any libuv objects.
vim.version.range() couldn't parse them correctly.
For example, vim.version.range('<0.9.0'):has('0.9.0') returned `true`.
fix: range:has() accepts vim.version()
So that it's possible to compare a range with:
vim.version.range(spec):has(vim.version())
Problem: Heredoc for interfaces does not support "trim".
Solution: Update the script heredoc support to be same as the :let command.
(Yegappan Lakshmanan, closesvim/vim#5916)
6c2b7b8055
Packing and unpacking return values impairs performance considerably.
In an attempt to avoid creating tables as much as possible we can
instead pass return values between functions (which does not require
knowing the number of values a function might return). This makes the
code more complex, but improves benchmark numbers non-trivially.
This was originally meant as a convenience but prevents possible
functionality. For example:
-- Get the keys of the table with even values
local t = { a = 1, b = 2, c = 3, d = 4 }
vim.iter(t):map(function(k, v)
if v % 2 == 0 then return k end
end):totable()
The example above would not work, because the map() function returns
only a single value, and cannot be converted back into a table (there
are many such examples like this).
Instead, to convert an iterator into a map-like table, users can use
fold():
vim.iter(t):fold({}, function(t, k, v)
t[k] = v
return t
end)
vim.iter wraps a table or iterator function into an `Iter` object with
methods such as `filter`, `map`, and `fold` which can be chained to
produce iterator pipelines that do not create new tables at each step.
feat(lua)!: add stricter vim.tbl_islist(), rename vim.tbl_isarray()
Problem: `vim.tbl_islist` allows gaps in tables with integer keys
("arrays").
Solution: Rename `vim.tbl_islist` to `vim.tbl_isarray`, add new
`vim.tbl.islist` that checks for consecutive integer keys that start
from 1.
* feat(lua): vim.tbl_contains supports general tables and predicates
Problem: `vim.tbl_contains` only works for list-like tables (integer
keys without gaps) and primitive values (in particular, not for nested
tables).
Solution: Rename `vim.tbl_contains` to `vim.list_contains` and add new
`vim.tbl_contains` that works for general tables and optionally allows
`value` to be a predicate function that is checked for every key.
Whenever we run fs_stat() on a path, save this information in the loader
so it can be re-used.
- Loader.loadfile: Remove arguments `hash` as it is no longer needed.
- Loader.loader: Use _G.loadstring instead of Loader.load
This allows plugins to wrap loadstring to inspection and profiling
- factor out read file logic
Problem:
- vim.split has more features than vim.gsplit.
- Cannot inspect the "separator" segments of vim.split or vim.gsplit.
Solution:
- Move common implementation from vim.split into vim.gsplit.
- TODO: deprecate vim.split in favor of vim.totable(vim.gsplit())?
- Introduce `keepsep` parameter.
Related: 84f66909e4
existing behavior of
:=
and
:[range]=
are unchanged. `|` is still allowed with this usage.
However,
:=p
and similar are changed in a way which could be construed as a breaking
change. Allowing |ex-flags| for := in the first place was a mistake as
any form of := DOES NOT MOVE THE CURSOR. So it would print one line number
and then print a completely different line contents after that.
Problem:
"tmux 3.2a" (output from "tmux -V") is not parsed easily.
Solution:
With `strict=false`, discard everything before the first digit.
- rename Semver => Version
- rename vim.version.version() => vim.version._version()
- rename matches() => has()
- remove `opts` from cmp()
Problem:
vim.deprecate() shows ":help deprecated" for third-party plugins. ":help
deprecated" only describes deprecations in Nvim, and is unrelated to any
3rd party deprecations.
Solution:
If `plugin` is specified, don't show ":help deprecated".
fix#22235
Problem:
The function name `vim.pretty_print`:
1. is verbose, which partially defeats its purpose as sugar
2. does not draw from existing precedent or any sort of convention
(except external projects like penlight or python?), which reduces
discoverability, and degrades signaling about best practices.
Solution:
- Rename to `vim.print`.
- Change the behavior so that
1. strings are printed without quotes
2. each arg is printed on its own line
3. tables are indented with 2 instead of 4 spaces
- Example:
:lua ='a', 'b', 42, {a=3}
a
b
42
{
a = 3
}
Comparison of alternatives:
- `vim.print`:
- pro: consistent with Lua's `print()`
- pro: aligns with potential `nvim_print` API function which will
replace nvim_echo, nvim_notify, etc.
- con: behaves differently than Lua's `print()`, slightly misleading?
- `vim.echo`:
- pro: `:echo` has similar "pretty print" behavior.
- con: inconsistent with Lua idioms.
- `vim.p`:
- pro: very short, fits with `vim.o`, etc.
- con: not as discoverable as "echo"
- con: less opportunity for `local p = vim.p` because of potential shadowing.
also make implicit submodules "uri" and "_inspector" work with completion
this is needed for `:lua=vim.uri_<tab>` wildmenu completion
to work even before uri or _inspector functions are used.
- version.cmp(): assert valid version
- add test for loading vim.version (the other tests use shared.lua in
the test runner)
- reduce test scopes, reword test descriptions
Problem:
No easy way to find files under certain directories (ex: grab all files under
`test/`) or exclude the content of certain paths (ex. `build/`, `.git/`)
Solution:
Pass the full `path` as an arg to the predicate.
Problem:
Build is not reproducible, because generated source files (.c/.h/) are not
deterministic, mostly because Lua pairs() is unordered by design (for security).
https://github.com/LuaJIT/LuaJIT/issues/626#issuecomment-707005671https://www.lua.org/manual/5.1/manual.html#pdf-next
> The order in which the indices are enumerated is not specified [...]
>
>> The hardening of the VM deliberately randomizes string hashes. This in
>> turn randomizes the iteration order of tables with string keys.
Solution:
- Update the code generation scripts to be deterministic.
- That is only a partial solution: the exported function
(funcs_metadata.generated.h) and ui event
(ui_events_metadata.generated.h) metadata have some mpack'ed
tables, which are not serialized deterministically.
- As a workaround, introduce `PRG_GEN_LUA` cmake setting, so you can
inject a modified build of luajit (with LUAJIT_SECURITY_PRN=0)
that preserves table order.
- Longer-term we should change the mpack'ed data structure so it no
longer uses tables keyed by strings.
Closes#20124
Co-Authored-By: dundargoc <gocdundar@gmail.com>
Co-Authored-By: Arnout Engelen <arnout@bzzt.net>
Problem:
Nvim has Lua but the "nvim" CLI can't easily be used to execute Lua
scripts, especially scripts that take arguments or produce output.
Solution:
- support "nvim -l [args...]" for running scripts. closes#15749
- exit without +q
- remove lua2dox_filter
- remove Doxyfile. This wasn't used anyway, because the doxygen config
is inlined in gen_vimdoc.py (`Doxyfile` variable).
- use "nvim -l" in docs-gen CI job
Examples:
$ nvim -l scripts/lua2dox.lua --help
Lua2DoX (0.2 20130128)
...
$ echo "print(vim.inspect(_G.arg))" | nvim -l - --arg1 --arg2
$ echo 'print(vim.inspect(vim.api.nvim_buf_get_text(1,0,0,-1,-1,{})))' | nvim +"put ='text'" -l -
TODO?
-e executes Lua code
-l loads a module
-i enters REPL _after running the other arguments_.
* credit to @smolck and @theHamsta for their contributions in laying the
groundwork for this feature and for their work on some of the helper
utility functions and tests
Add introductory guide explaining how to use Lua in Neovim:
where to put Lua files, how to set variables and options, how
to create mappings, autocommands, and user commands.
Adapted with kind permission from
https://github.com/nanotee/nvim-lua-guide
Introduce vim.secure.trust() to programmatically manage the trust
database. Use this function in a new :trust ex command which can
be used as a simple frontend.
Resolves: https://github.com/neovim/neovim/issues/21092
Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: ii14 <ii14@users.noreply.github.com>
This function accepts a path to a file and prompts the user if the file
is trusted. If the user confirms that the file is trusted, the contents
of the file are returned. The user's decision is stored in a trust
database at $XDG_STATE_HOME/nvim/trust. When this function is invoked
with a path that is already marked as trusted in the trust database, the
user is not prompted for a response.
fix(vim.ui.input): return empty string when inputs nothing
The previous behavior of `vim.ui.input()` when typing <CR> with
no text input (with an intention of having the empty string as input)
was to execute `on_confirm(nil)`, conflicting with its documentation.
Inputting an empty string should now correctly execute `on_confirm('')`.
This should be clearly distinguished from cancelling or aborting the
input UI, in which case `on_confirm(nil)` is executed as before.
Problem:
- pesc() returns multiple results, it should return a single result.
- tbl_islist() returns non-boolean in some branches.
- Docstring: @generic must be declared first
Solution:
Constrain docstring annotations.
Fix return types.
Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
Made obsolete by now graduated `filetype.lua` (enabled by default).
Note that changes or additions to the filetype detection still need to
be made through a PR to vim/vim as we port the _logic_ as well as tests.
- Improve generated HTML by updating parser which includes fixes for
single "'" and single "|":
https://github.com/neovim/tree-sitter-vimdoc/pull/31
- Updated parser also fixes the conceal issue for "help" highlight
queries https://github.com/neovim/tree-sitter-vimdoc/issues/23 by
NOT including whitespace in nodes.
- But this means we need to restore the getws() function which scrapes
leading whitespace from the original input (buffer).
Problem:
The {foo} parameters listed in `:help api` and similar generated docs,
are intended to be a "list" but they aren't prefixed with a list symbol.
This prevents parsers from understanding the list, which forces
generators like `gen_help_html.lua` to use hard-wrapped/preformatted
layout instead of a soft-wrapped "flow" layout.
Solution:
Modify gen_vimdoc.py to prefix {foo} parameters with a "•" symbol.
Makes it possible to use `vim.fs.find` to find files where only a
substring is known.
This is useful for `vim.lsp.start` to get the `root_dir` for languages
where the project-file is only known by its extension, not by the full
name.
For example in .NET projects there is usually a `<projectname>.csproj`
file in the project root.
Example:
vim.fs.find(function(x) return vim.endswith(x, '.csproj') end, { upward = true })
Problem: People are confused about `vim.o` and `vim.opt`
Solution: Clarify that `vim.o` is the default interface, with `vim.opt`
specifically meant for interacting with list-style options.
docs(lua): update vim.{go,bo,wo} documentation
* document indexing by buffer/window handle
* correct wrapper information (`nvim_buf_{g,s}et_value` now)
* make clear what is considered "invalid key" (consistently)
based on http://www.vim.org/scripts/script.php?script_id=1291
reformatted to match Nvim documentation style; removed irrelevant sections
Co-authored-by: dundargoc <gocundar@gmail.com>
Co-authored-by: Christian Clason <c.clason@uni-graz.at>
Co-authored-by: Lewis Russell <lewis6991@gmail.com>
* Problem
Quotes are special in doxygen, and should be escaped. *Sometimes* they
cause doc generation issues. Like in #17785
* Solution
Replace double quotes with single quotes
* revert to filetype.vim by setting `g:do_legacy_filetype`
* skip either filetype.lua or filetype.vim via `g:did_load_filetypes`
(Running both is no longer required and therefore no longer supported.)
This is necessary in cases where filetype detection acts recursively.
For example, when matching files that end with .bak, the "root" of
the filename is matched again against the same buffer (e.g. a buffer
named "foo.c.bak" will be matched again with the filename "foo.c", using
the same underlying buffer).
This enables vim.filetype.match to match based on a buffer (most
accurate) or simply a filename or file contents, which are less accurate
but may still be useful for some scenarios.
When matching based on a buffer, the buffer's name and contents are both
used to do full filetype matching. When using a filename, if the file
exists the file is loaded into a buffer and full filetype detection is
performed. If the file does not exist then filetype matching is only
performed against the filename itself. Content-based matching does the
equivalent of scripts.vim, and matches solely based on file contents
without any information from the name of the file itself (e.g. for
shebangs).
BREAKING CHANGE: use `vim.filetype.match({buf = bufnr})` instead
of `vim.filetype.match(name, bufnr)`
Many filetypes from filetype.vim set buffer-local variables, meaning
vim.filetype.match cannot be used without side effects. Instead of
setting these buffer-local variables in the filetype detection functions
themselves, have vim.filetype.match return an optional function value
that, when called, sets these variables. This allows vim.filetype.match
to work without side effects.
This will check if the string after the variable in a @param is either
"number", "string", "table", "boolean" and "function" and if so add a
parenthesis around it. This will help separate the variable type with
the following text. Had all our functions been annotated with emmylua
then a more robust solution might have been preferable (such as always
assuming the third string is parameter type without making any checks).
I believe however this is a clear improvement over the current situation
and will suffice for now.
This is primarily intended to act as documentation for the developer so
they know exactly when and what to remove. This will help prevent the
situation of deprecated code lingering for far too long as developers
don't have to worry if a function is safe to remove.
vim.tbl_get takes a table with subsequent string arguments (variadic) that
index into the table. If the value pointed to by the set of keys exists,
the function returns the value. If the set of keys does not exist, the
function returns nil.
Problem: The eval.txt help file is way too big.
Solution: Move the builtin function details to a separate file.
1cae5a0a03
Note: Neovim-specific references to |functions| were changed to
|builtin-functions|. This included updates to:
1. test/functional/vimscript/functions_spec.lua
2. test/functional/vimscript/eval_spec.lua
3. runtime/doc/lua.txt
Co-authored-by: Sean Dewar <seandewar@users.noreply.github.com>
Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: Sebastian Volland <seb@baunz.net>
Co-authored-by: Lewis Russell <lewis6991@gmail.com>
Co-authored-by: zeertzjq <zeertzjq@outlook.com>
This introduces two new functions `vim.keymap.set` & `vim.keymap.del`
differences compared to regular set_keymap:
- remap is used as opposite of noremap. By default it's true for <Plug> keymaps and false for others.
- rhs can be lua function.
- mode can be a list of modes.
- replace_keycodes option for lua function expr maps. (Default: true)
- handles buffer specific keymaps
Examples:
```lua
vim.keymap.set('n', 'asdf', function() print("real lua function") end)
vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, {buffer=true})
vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", {silent = true, buffer = 5 })
vim.keymap.set('i', '<Tab>', function()
return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
end, {expr = true})
vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
vim.keymap.del('n', 'asdf')
vim.keymap.del({'n', 'i', 'v'}, '<leader>w', {buffer = 5 })
```
Corrects lua.txt help file to say that require() searches runtimepath
and loads the first module found, not the last.
Also adds additional clarification on require() and module search order.
Closes#15480
* vim.ui.input is an overridable function that prompts for user input
* take an opts table and the `on_confirm` callback, see `:help vim.ui.input` for more details
* defaults to a wrapper around vim.fn.input(opts)
* switches the built-in client's rename handler to use vim.ui.input by default
Problem:
1. "unpack" has an unrelated meaning in Lua:
https://www.lua.org/manual/5.1/manual.html#pdf-unpack
2. We already have msgpackparse()/msgpackdump() and
json_encode()/json_decode(), so introducing another name for the same
thing is entropy.
Solution:
- Rename vim.mpack.pack/unpack => vim.mpack.encode/decode
Caveat:
This is incongruent with the `Unpacker` and `Packer` functions.
- It's probably too invasive to rename those.
- They also aren't part of our documented interface.
- This commit is "reversible" in the sense that we can always revert
it and add `vim.mpack.encode/decode` as _aliases_ to
`vim.mpack.pack/unpack`, at any time in the future, if we want
stricter fidelity with upstream libmpack. Meanwhile,
`vim.mpack.encode/decode` is currently the total _documented_
interface of `vim.mpack`, so this change serves the purpose of
consistent naming in the Nvim stdlib.
The spacing fix drew attention to a couple of places that were using
incorrect formatting such as the key listing for `nvim_open_win`, so
those were fixed too.
vim.bo can target a specific buffer by indexing with a number, e.g:
`vim.bo[2].filetype` can get/set the filetype for buffer 2. This change
replicates that behaviour for the variable namespace.
Continuation of https://github.com/neovim/neovim/pull/15202
A plugin like telescope could override it with a fancy implementation
and then users would get the telescope-ui within each plugin that
utilizes the vim.ui.select function.
There are some plugins which override the `textDocument/codeAction`
handler solely to provide a different UI. With custom client commands and
soon codeAction resolve support, it becomes more difficult to implement
the handler right - so having a dedicated way to override the picking
function will be useful.
The `split()` VimL function trims empty items from the returned list by
default, so that, e.g.
split("\nhello\nworld\n\n", "\n")
returns
["hello", "world"]
The Lua implementation of vim.split does not do this. For example,
vim.split("\nhello\nworld\n\n", "\n")
returns
{'', 'hello', 'world', '', ''}
Add an optional parameter to the vim.split function that, when true,
trims these empty elements from the front and back of the returned
table. This is only possible for vim.split and not vim.gsplit; because
vim.gsplit is an iterator, there is no way for it to know if the current
item is the last non-empty item.
Note that in order to preserve backward compatibility, the parameter for
the Lua vim.split function is `trimempty`, while the VimL function uses
`keepempty` (i.e. they are opposites). This means there is a disconnect
between these two functions that may surprise users.
Strings that previously decoded into a msgpack special for representing
BINs with NULs now convert to Blobs. It shouldn't be possible to decode
into this special anymore after this change?
Notably, Lua strings with NULs now convert to Blobs when passed to VimL.
Analogous to nodejs's `on('data', …)` interface, here on_key is the "add
listener" interface.
ref 3ccdbc570d#12536
BREAKING_CHANGE: vim.register_keystroke_callback() is now an error.
The official developer documentation in in :h dev-lua-doc specifies to
use "--@" for special/magic tokens. However, this format is not
consistent with EmmyLua notation (used by some Lua language servers) nor
with the C version of the magic docstring tokens which use three comment
characters.
Further, the code base is currently split between usage of "--@",
"---@", and "--- @". In an effort to remain consistent, change all Lua
magic tokens to use "---@" and update the developer documentation
accordingly.
