feat(api): nvim_set_option_value(operation=...) #39849

Problem:
`nvim_set_option_value` cannot "update" options similar to `:set opt=`,
`:set opt+=`, etc. The Lua impls of "vim.opt" / "vim.o" have incomplete,
bespoke reimplementations of those operations.

ref #38420

Solution:
- Add `operation` param to `nvim_set_option_value`, which may be "set",
  "append", "prepend", or "remove".
- Use this feature to implement `vim.opt` / `vim.o`.

runtime/doc/api.txt

@@ -3596,6 +3596,11 @@ nvim_set_option_value({name}, {value}, {opts})
       • {value}  (`any`) New option value
       • {opts}   (`vim.api.keyset.option`) Optional parameters
                  • buf: Buffer number. Used for setting buffer local option.
+                 • dry_run: (`boolean?`, default: false) If true, then the
+                   option value won't be set.
+                 • operation: One of "set", "append", "prepend", or "remove".
+                   Corresponds to |:set=|, |:set+=|, |:set^=|, and |:set-=|.
+                   Default is "set".
                  • scope: One of "global" or "local". Analogous to
                    |:setglobal| and |:setlocal|, respectively.
                  • tab: |tab-ID| for tab-local options (currently only
@@ -3604,6 +3609,9 @@ nvim_set_option_value({name}, {value}, {opts})
                    it is switched-to.
                  • win: |window-ID|. Used for setting window local option.
 
+    Return: ~
+        (`any`) Option value
+
 
 ==============================================================================
 Tabpage Functions                                                *api-tabpage*

runtime/doc/lua.txt

@@ -961,6 +961,12 @@ Vim options can be accessed through |vim.o|, which behaves like Vimscript
     To set a string value:
         Vimscript: `set wildignore=*.o,*.a,__pycache__`
         Lua:       `vim.o.wildignore = '*.o,*.a,__pycache__'`
+        Lua (alt): `vim.o.wildignore = { '*.o', '*.a', '__pycache__' }`
+
+    To set a key:value type option:
+        Vimscript: `set listchars=eol:~,space:-`
+        Lua:       `vim.o.listchars = 'eol:~,space:-'`
+        Lua (alt): `vim.o.listchars = { eol = '~', space = '-' }`
 
 Similarly, there is |vim.bo| and |vim.wo| for setting buffer-scoped and
 window-scoped options. Note that this must NOT be confused with

runtime/doc/news.txt

@@ -69,6 +69,8 @@ API
 • |nvim_create_autocmd()|, |nvim_exec_autocmds()| and |nvim_clear_autocmds()|
   no longer treat an empty non-nil pattern as nil.
 • |nvim_clear_autocmds()| no longer treats an empty array event as nil.
+• |vim.o|, |vim.opt|, and |nvim_set_option_value()| expand `~` and environment
+  variables (|expand-env|).
 
 DIAGNOSTICS
 
@@ -105,6 +107,9 @@ LUA
 
 • "standalone" Lua interpreter mode `nvim -ll` was removed. Use |-l| script
   mode instead.
+• |vim.opt| no longer supports chaining multiple infix operators (e.g.
+  `vim.opt.wildignore + '*.o' + '*.obj'`). Instead, use tables:
+  `vim.opt.wildignore + {'*.o', '*.obj'}`
 
 OPTIONS
 
@@ -148,6 +153,9 @@ API
 • |nvim_buf_set_extmark()| `virt_lines_overflow` accepts "wrap" to enable
   wrapping onto extra rows and "auto" which enables horizontal scrolling when
   'nowrap' is set and wrapping when 'wrap' is set.
+• |nvim_set_option_value()| accepts a new `operation` field to modify the
+  existing option value.
+• |nvim_set_option_value()| returns the new option value.
 
 BUILD
 
@@ -260,6 +268,7 @@ LUA
 • |vim.log| provides a logging interface.
 • |vim.pack.get()| output includes revision of a pending update.
 • |vim.pack.get()| can fetch new updates before computing the output.
+• |vim.o| now accepts table style values for assignment.
 
 OPTIONS