From 74919174cf99a2af593760ebd7102973cb5a4261 Mon Sep 17 00:00:00 2001 From: Yi Ming Date: Fri, 1 Nov 2024 15:28:07 +0800 Subject: [PATCH] docs(editor): add docs for `vim.gl`, `vim.bl`, `vim.wl`, `vim.tl` --- runtime/doc/lua.txt | 37 ++++++++++++++++++++++++++++++++++++ runtime/doc/news.txt | 1 + runtime/lua/vim/_options.lua | 37 ++++++++++++++++++++++++++++++++++++ 3 files changed, 75 insertions(+) diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 6ae1a1a3b8..38767669f3 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1259,6 +1259,43 @@ vim.t *vim.t* vim.v *vim.v* |v:| variables. Invalid or unset key returns `nil`. + *lua-scoped-variables* +Lua variables can be created with the same lifecycle as Vim variables like +|g:|, |b:|, |w:|, and |t:|. + +Example: >lua + + vim.bl[2].foo = { key = 'value' } -- Set local variable fo buffer 2 + vim.print(vim.bl[2].foo) -- "{ key = 'value' }" + vim.print(vim.bl[3].foo) -- "nil" + vim.api.nvim_buf_delete(2, {}) -- Delete buffer 2 + vim.print(vim.bl[2].foo) -- "nil" + +Note that these variables are stored as Lua data rather than VimScript data, +so they must be evaluated via function calls in VimScript. + +Example: > + let b:foo = b:lua_var_foo() " Retrieve the value of `vim.bl.foo` + echo b:foo " {'key': 'value'} + +vim.gl *vim.gl* + Global editor Lua variables. + Key with no value returns `nil`. + +vim.bl *vim.bl* + Buffer-scoped Lua variables for the current buffer. + Invalid or unset key returns `nil`. Can be indexed with + an integer to access variables for a specific buffer. + +vim.w *vim.wl* + Window-scoped Lua variables for the current window. + Invalid or unset key returns `nil`. Can be indexed with + an integer to access variables for a specific window. + +vim.tl *vim.tl* + Tabpage-scoped Lua variables for the current tabpage. + Invalid or unset key returns `nil`. Can be indexed with + an integer to access variables for a specific tabpage. *lua-options* diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index c01bb46de7..a6769408c9 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -69,6 +69,7 @@ EDITOR it moves to another help buffer. • Bells from a |terminal| buffer are now silent by default, unless 'belloff' option doesn't contain "term" or "all". +• Add |vim.gl|,|vim.bl|,|vim.wl|, |vim.tl| for scoped variables. EVENTS diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua index 77d7054626..84a97a781d 100644 --- a/runtime/lua/vim/_options.lua +++ b/runtime/lua/vim/_options.lua @@ -90,6 +90,43 @@ --- vim.v *vim.v* --- |v:| variables. --- Invalid or unset key returns `nil`. +--- *lua-scoped-variables* +--- Lua variables can be created with the same lifecycle as Vim variables like +--- |g:|, |b:|, |w:|, and |t:|. +--- +--- Example: >lua +--- +--- vim.bl[2].foo = { key = 'value' } -- Set local variable fo buffer 2 +--- vim.print(vim.bl[2].foo) -- "{ key = 'value' }" +--- vim.print(vim.bl[3].foo) -- "nil" +--- vim.api.nvim_buf_delete(2, {}) -- Delete buffer 2 +--- vim.print(vim.bl[2].foo) -- "nil" +--- +--- Note that these variables are stored as Lua data rather than VimScript data, +--- so they must be evaluated via function calls in VimScript. +--- +--- Example: > +--- let b:foo = b:lua_var_foo() " Retrieve the value of `vim.bl.foo` +--- echo b:foo " {'key': 'value'} +--- +---vim.gl *vim.gl* +--- Global editor Lua variables. +--- Key with no value returns `nil`. +--- +--- vim.bl *vim.bl* +--- Buffer-scoped Lua variables for the current buffer. +--- Invalid or unset key returns `nil`. Can be indexed with +--- an integer to access variables for a specific buffer. +--- +--- vim.w *vim.wl* +--- Window-scoped Lua variables for the current window. +--- Invalid or unset key returns `nil`. Can be indexed with +--- an integer to access variables for a specific window. +--- +--- vim.tl *vim.tl* +--- Tabpage-scoped Lua variables for the current tabpage. +--- Invalid or unset key returns `nil`. Can be indexed with +--- an integer to access variables for a specific tabpage. --- local api = vim.api