Problem:
The way option scopes currently work is inflexible and does not allow for nested
option scopes or easily finding the value of an option at any arbitrary scope
without having to do long handwritten switch-case statements like in
`get_varp()`. `.indir` is also confusing and redundant since option indices for
each scope can be autogenerated.
Solution:
Expand option scopes in such a way that an option can support any amount of
scopes using a set of scope flags, similarly to how it's already done for option
types. Also make options contain information about its index at each scope it
supports. This allows for massively simplifying `get_varp()` and
`get_varp_scope()` in the future by just using a struct for options at each
scope. This would be done by creating a table that stores the offset of an
option's variable at a scope by using the option's index at that scope as a key.
This PR also autogenerates enums for option indices at each scope to remove the
need for `.indir` entirely, and also to allow easily iterating over options all
options that support any scope.
Ref: #29314
Problem:
There are three different ways of marking an option as hidden, `enable_if
= false`, `hidden = true` and `immutable = true`. These also have different
behaviors. Options hidden with `enable_if = false` can't have their value
fetched using Vim script or the API, but options hidden with `hidden = true` or
`immutable = true` can. On the other hand, options with `hidden = true` do not
error when trying to set their value, but options with `immutable = true` do.
Solution:
Remove `enable_if = false`, remove the `hidden` property for options, and use
`immutable = true` to mark an option as hidden instead. Also make hidden option
variable pointers always point to the default value, which allows fetching the
value of every hidden option using Vim script and the API. This does also mean
that trying to set a hidden option will now give an error instead of just being
ignored.
Problem:
Hidden options are documented despite being no-ops.
Solution:
Remove docs for hidden options.
Move tags for options that we plan to restore, to ":help nvim-missing".
Move tags for permanently removed options, to ":help nvim-removed".
Problem: testing of options can be further improved
Solution: split the generated option test into test_options_all.vim,
add more test cases, save and restore values, fix use-after-free
closes: vim/vim#158946eca04e9f1
Co-authored-by: Milly <milly.ca@gmail.com>
An implication of this current approach is that `NVIM_API_LEVEL` should be
bumped when a new Lua function is added.
TODO(future): add a lint check which requires `@since` on all new functions.
ref #25416
In the api_info() output:
:new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val')
...
{'return_type': 'ArrayOf(Integer, 2)', 'name': 'nvim_win_get_position', 'method': v:true, 'parameters': [['Window', 'window']], 'since': 1}
The `ArrayOf(Integer, 2)` return type didn't break clients when we added
it, which is evidence that clients don't use the `return_type` field,
thus renaming Dictionary => Dict in api_info() is not (in practice)
a breaking change.
This also makes shada reading slightly faster due to avoiding
some copying and allocation.
Use keysets to drive decoding of msgpack maps for shada entries.
Problem: No way to get the arity of a Vim function
(Austin Ziegler)
Solution: Enhance get() Vim script function to return the function
argument info using get(func, "arity") (LemonBoy)
fixes: vim/vim#15097closes: vim/vim#1510948b7d05a4f
Co-authored-by: LemonBoy <thatlemon@gmail.com>
Then we can just load metadata in C as a single msgpack blob. Which also
can be used directly as binarly data, instead of first unpacking all the
functions and ui_events metadata to immediately pack it again, which was
a bit of a silly walk (and one extra usecase of `msgpack_rpc_from_object`
which will get yak shaved in the next PR)
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:
When a function has multiple signatures, putting its tag at the last one
may make one think that's its only signature.
Solution:
When a function has multiple signatures, put its tag at the first one.
Problem: We have `P_(BOOL|NUM|STRING)` macros to represent an option's type, which is redundant because `OptValType` can already do that. The current implementation of option type flags is also too limited to allow adding multitype options in the future.
Solution: Remove `P_(BOOL|NUM|STRING)` and replace it with a new `type_flags` attribute in `vimoption_T`. Also do some groundwork for adding multitype options in the future.
Side-effects: Attempting to set an invalid keycode option (e.g. `set t_foo=123`) no longer gives an error.
Problem:
We don't enable stylua for many Lua scripts. Automating code-style is an
important tool for reducing time spent on accidental (non-essential)
complexity.
Solution:
- Enable lintlua for `scripts/` directory.
- Specify `call_parentheses = "Input"`, we should allow kwargs-style
function invocations.
In cases where the generated files depend on changes to Nvim itself,
generating the files with an older version of Nvim will fail because
those changes are not present in the older version.
For example, if a new option is added then the generator script should
be run with the version of Nvim that contains the new option, or else
the generation will fail.
Co-authored-by: dundargoc <gocdundar@gmail.com>
runtime(doc): documentation updates
This is a collection of various improvements to the help pages
closesvim/vim#12790596ad66d1d
Co-authored-by: Christian Brabandt <cb@256bit.org>
Co-authored-by: Houl <anwoku@yahoo.de>
Co-authored-by: Doug Kearns <dougkearns@gmail.com>
Co-authored-by: Adri Verhoef <a3@a3.xs4all.nl>
Problem: sidescrolloff and scrolloff options work slightly
different than other global-local options
Solution: Make it behave consistent for all global-local options
It was noticed, that sidescrolloff and scrolloff options behave
differently in comparison to other global-local window options like
'listchars'
So make those two behave like other global-local options. Also add some
extra documentation for a few special local-window options.
Add a few tests to make sure all global-local window options behave
similar
closes: vim/vim#12956closes: vim/vim#126434a8eb6e7a9
Co-authored-by: Christian Brabandt <cb@256bit.org>
* docs(options): take ownership of options.txt
- `src/nvim/options.lua` is now the source of truth
- generate runtime/lua/vim/_meta/options.lua
* fixup! zeer comments
* fixup! zeer comments (2)
* fixup! re-enable luacheck
* fixup! regen
Now that we "own" builtin.txt, we cant remove the repetitive mention of
Vimscript's UFCS syntax. It's noisy to mention this for each function,
and it's also not a Vimscript feature that should be encouraged.
Also change the builtin.txt heading to "NVIM REFERENCE MANUAL", which
indicates when a help file is Nvim-owned.
- eval.lua is now the source of truth.
- Formatting is much more consistent.
- Fixed Lua type generation for polymorphic functions (get(), etc).
- Removed "Overview" section from builtin.txt
- Can generate this if we really want it.
- Moved functions from sign.txt and testing.txt into builtin.txt.
- Removed the *timer* *timers* tags since libuv timers via vim.uv should be preferred.
- Removed the temp-file-name tag from tempname()
- Moved lueval() from lua.txt to builtin.txt.
* Fix indent
* fixup!
* fixup! fixup!
* fixup! better tag formatting
* fixup: revert changes no longer needed
* fixup! CI
---------
Co-authored-by: zeertzjq <zeertzjq@outlook.com>
