From 9397e70b9e51ea17c71bd959e337e7e5892d97e1 Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Tue, 30 Aug 2022 14:46:38 +0200 Subject: [PATCH] docs(lua): present vim.o as default and vim.opt as special-purpose #19982 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. --- runtime/doc/lua.txt | 288 +++++++++++++++++++++++--------------------- 1 file changed, 151 insertions(+), 137 deletions(-) diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 28d5605c2d..499b3f9a6f 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1091,17 +1091,13 @@ vim.env *vim.env* print(vim.env.TERM) < + *lua-options* *lua-vim-options* - *lua-vim-opt* *lua-vim-set* - *lua-vim-optlocal* *lua-vim-setlocal* -In Vimscript, there is a way to set options |set-option|. In Lua, the -corresponding method is `vim.opt`. - -`vim.opt` provides several conveniences for setting and controlling options -from within Lua. +Vim options can be accessed through |vim.o|, which behaves like Vimscript +|:set|. Examples: ~ @@ -1110,148 +1106,26 @@ from within Lua. `set number` In Lua: - `vim.opt.number = true` + `vim.o.number = true` - To set an array of values: + To set a string value: In Vimscript: `set wildignore=*.o,*.a,__pycache__` - In Lua, there are two ways you can do this now. One is very similar to - the Vimscript form: - `vim.opt.wildignore = '*.o,*.a,__pycache__'` - - However, vim.opt also supports a more elegent way of setting - list-style options by using lua tables: - `vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }` - - To replicate the behavior of |:set+=|, use: > - - -- vim.opt supports appending options via the "+" operator - vim.opt.wildignore = vim.opt.wildignore + { "*.pyc", "node_modules" } - - -- or using the `:append(...)` method - vim.opt.wildignore:append { "*.pyc", "node_modules" } -< - To replicate the behavior of |:set^=|, use: > - - -- vim.opt supports prepending options via the "^" operator - vim.opt.wildignore = vim.opt.wildignore ^ { "new_first_value" } - - -- or using the `:prepend(...)` method - vim.opt.wildignore:prepend { "new_first_value" } -< - To replicate the behavior of |:set-=|, use: > - - -- vim.opt supports removing options via the "-" operator - vim.opt.wildignore = vim.opt.wildignore - { "node_modules" } - - -- or using the `:remove(...)` method - vim.opt.wildignore:remove { "node_modules" } -< - To set a map of values: - In Vimscript: - `set listchars=space:_,tab:>~` - In Lua: - `vim.opt.listchars = { space = '_', tab = '>~' }` + `vim.o.wildignore = '*.o,*.a,__pycache__'` - -In any of the above examples, to replicate the behavior |setlocal|, use -`vim.opt_local`. Additionally, to replicate the behavior of |setglobal|, use -`vim.opt_global`. - *vim.opt* - -|vim.opt| returns an Option object. - -For example: `local listchar_object = vim.opt.listchars` - -An `Option` has the following methods: - - - *vim.opt:get()* -Option:get() - - Returns a lua-representation of the option. Boolean, number and string - 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: > - vim.cmd [[set wildignore=*.pyc,*.o]] - - print(vim.inspect(vim.opt.wildignore:get())) - -- { "*.pyc", "*.o", } - - for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do - print("Will ignore:", ignore_pattern) - end - -- Will ignore: *.pyc - -- 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: > - vim.cmd [[set listchars=space:_,tab:>~]] - - print(vim.inspect(vim.opt.listchars:get())) - -- { space = "_", tab = ">~", } - - for char, representation in pairs(vim.opt.listchars:get()) do - print(char, "->", representation) - end -< - For values that are lists of flags, a set will be returned with the flags - as keys and `true` as entries. > - vim.cmd [[set formatoptions=njtcroql]] - - print(vim.inspect(vim.opt.formatoptions:get())) - -- { n = true, j = true, c = true, ... } - - local format_opts = vim.opt.formatoptions:get() - if format_opts.j then - print("J is enabled!") - end -< - *vim.opt:append()* -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'` - - *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'` - - *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'` - - -In general, using `vim.opt` will provide the expected result when the user is -used to interacting with editor |options| via `set`. There are still times -where the user may want to set particular options via a shorthand in Lua, -which is where |vim.o|, |vim.bo|, |vim.wo|, and |vim.go| come into play. - -The behavior of |vim.o|, |vim.bo|, |vim.wo|, and |vim.go| is designed to -follow that of |:set|, |:setlocal|, and |:setglobal| which can be seen in the -table below: +Similarly, there exist |vim.bo| and |vim.wo| for setting buffer-local and +window-local options, respectively, similarly to |:setlocal|. There is also +|vim.go| that only sets the global value of a |global-local| option, see +|:setglobal|. The following table summarizes this relation. lua command global_value local_value ~ vim.o :set set set vim.bo/vim.wo :setlocal - set vim.go :setglobal set - + vim.o *vim.o* Get or set editor options, like |:set|. Invalid key is an error. @@ -1303,6 +1177,146 @@ vim.wo[{winid}] * print(vim.wo.foldmarker) print(vim.wo.quux) -- error: invalid key < + + + + *lua-vim-opt* + *lua-vim-optlocal* + *lua-vim-optglobal* + *vim.opt* + + +A special interface |vim.opt| exists for conveniently interacting with list- +and map-style option from Lua: It allows accessing them as Lua tables and +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: > + + vim.opt.wildignore:append { "*.pyc", "node_modules" } +< + To replicate the behavior of |:set^=|, use: > + + vim.opt.wildignore:prepend { "new_first_value" } +< + To replicate the behavior of |:set-=|, use: > + + 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 = '>~' }` + + +Note that |vim.opt| returns an `Option` object, not the value of the option, +which is accessed through |Option: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 any of the above examples, to replicate the behavior |setlocal|, use +`vim.opt_local`. Additionally, to replicate the behavior of |setglobal|, use +`vim.opt_global`. + + + + *vim.opt:get()* +Option:get() + + Returns a lua-representation of the option. Boolean, number and string + 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: > + vim.cmd [[set wildignore=*.pyc,*.o]] + + vim.pretty_print(vim.opt.wildignore:get()) + -- { "*.pyc", "*.o", } + + for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do + print("Will ignore:", ignore_pattern) + end + -- Will ignore: *.pyc + -- 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: > + vim.cmd [[set listchars=space:_,tab:>~]] + + vim.pretty_print(vim.opt.listchars:get()) + -- { space = "_", tab = ">~", } + + for char, representation in pairs(vim.opt.listchars:get()) do + print(char, "->", representation) + end +< + For values that are lists of flags, a set will be returned with the flags + as keys and `true` as entries. > + vim.cmd [[set formatoptions=njtcroql]] + + vim.pretty_print(vim.opt.formatoptions:get()) + -- { n = true, j = true, c = true, ... } + + local format_opts = vim.opt.formatoptions:get() + if format_opts.j then + print("J is enabled!") + end +< + *vim.opt:append()* +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'` + + *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'` + + *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'` + + ============================================================================== Lua module: vim *lua-vim*