reverts e0d92b9cc2#28502
Problem:
`vim.ui.open()` has a `pcall()` like signature, under the assumption
that this is the Lua idiom for returning result-or-error. However, the
`result|nil, errmsg|nil` pattern:
- has precedent in:
- `io.open`
- `vim.uv` (`:help luv-error-handling`)
- has these advantages:
- Can be used with `assert()`:
```
local result, err = assert(foobar())
```
- Allows LuaLS to infer the type of `result`:
```
local result, err = foobar()
if err then
...
elseif result then
...
end
```
Solution:
- Revert to the `result|nil, errmsg|nil` pattern.
- Document the pattern in our guidelines.
Problem:
vim.iter has both `rfind()` and various `*back()` methods, which work
in "reverse" or "backwards" order. It's inconsistent to have both kinds
of names, and "back" is fairly uncommon (rust) compared to python
(rfind, rstrip, rsplit, …).
Solution:
- Remove `nthback()` and let `nth()` take a negative index.
- Because `rnth()` looks pretty obscure, and because it's intuitive
for a function named `nth()` to take negative indexes.
- Rename `xxback()` methods to `rxx()`.
- This informally groups the "list-iterator" functions under a common
`r` prefix, which helps discoverability.
- Rename `peekback()` to `pop()`, in duality with the existing `peek`.
Problem:
`vim.ui.open` unnecessarily invents a different success/failure
convention. Its return type was changed in 57adf8c6e0, so we might as
well change it to have a more conventional form.
Solution:
Change the signature to use the `pcall` convention of `status, result`.
vim.fs.root() is a function for finding a project root relative to a
buffer using one or more "root markers". This is useful for LSP and
could be useful for other "projects" designs, as well as for any plugins
which work with a "projects" concept.
Problem:
Besides being redundant with vim.iter():flatten(), `tbl_flatten` has
these problems:
- Has `tbl_` prefix but only accepts lists.
- Discards some results! Compare the following:
- iter.flatten():
```
vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()
```
- tbl_flatten:
```
vim.tbl_flatten({1, { { a = 2 } }, { 3 } })
```
Solution:
Deprecate tbl_flatten.
Note:
iter:flatten() currently fails ("flatten() requires a list-like table")
on this code from gen_lsp.lua:
local anonym = vim.iter({ -- remove nil
anonymous_num > 1 and '' or nil,
'---@class ' .. anonymous_classname,
}):flatten():totable()
Should we enhance :flatten() to work for arrays?
Problem:
The use-case for the convenience functions vim.iter.map(),
vim.iter.filter(), vim.iter.totable() is not clear.
Solution:
Drop them for now. We can revisit after 0.10 release.
Problem:
The order of the validation performed by vim.validate() is
unpredictable.
- harder to write reliable tests.
- confusing UX because validation result might return different errors randomly.
Solution:
Iterate the input using `vim.spairs()`.
Future:
Ideally, the caller could provide an "ordered dict".
Problem:
vim.ui.open "locks up" Nvim if the spawned process does not terminate. #27986
Solution:
- Change `vim.ui.open()`:
- Do not call `wait()`.
- Return a `SystemObj`. The caller can decide if it wants to `wait()`.
- Change `gx` to `wait()` only a short time.
- Allows `gx` to show a message if the command fails, without the
risk of waiting forever.
Backslashes are valid characters in unix style paths.
Fix the conversion of backslashes to forward slashes in several `vim.fs`
functions when not on Windows. On Windows, backslashes will still be converted
to forward slashes.
- Add :h fswatch-limitations that notifies user about default inotify
limitations on linux and how to adjust them
- Check for Event queue overflow message from fswatch and refer user to
new documentation
Signed-off-by: Tomas Slusny <slusnucky@gmail.com>
- Added `@inlinedoc` so single use Lua types can be inlined into the
functions docs. E.g.
```lua
--- @class myopts
--- @inlinedoc
---
--- Documentation for some field
--- @field somefield integer
--- @param opts myOpts
function foo(opts)
end
```
Will be rendered as
```
foo(opts)
Parameters:
- {opts} (table) Object with the fields:
- somefield (integer) Documentation
for some field
```
- Marked many classes with with `@nodoc` or `(private)`.
We can eventually introduce these when we want to.
Problem:
The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.
Solution:
Re-implement the flow using Lua, LPEG and treesitter.
- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
- LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
- LPEG for C parsing (see `scripts/cdoc_parser.lua`)
- Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
- Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
- `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
- Problem: One cannot easily write something like, for example:
`version_current >= {0, 10, 0}`; writing like
`not vim.version.lt(version_current, {0, 10, 0})` is verbose.
- Solution: add {`le`,`ge`} in addition to {`lt`,`gt`}.
- Also improve typing on the operator methods: allow `string` as well.
- Update the example in `vim.version.range()` docs: `ge` in place of
`gt` better matches the semantics of `range:has`.
