From d0b612f360125785eb95afaa51620c5c7695e381 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Sun, 16 Jul 2023 09:27:39 +0100
Subject: refactor: rename _meta.lua to _options.lua

---
 runtime/lua/vim/_options.lua | 575 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 575 insertions(+)
 create mode 100644 runtime/lua/vim/_options.lua

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
new file mode 100644
index 0000000000..41e6e8be86
--- /dev/null
+++ b/runtime/lua/vim/_options.lua
@@ -0,0 +1,575 @@
+local api = vim.api
+
+-- TODO(tjdevries): Improve option metadata so that this doesn't have to be hardcoded.
+--                  Can be done in a separate PR.
+local key_value_options = {
+  fillchars = true,
+  fcs = true,
+  listchars = true,
+  lcs = true,
+  winhighlight = true,
+  winhl = true,
+}
+
+--- Convert a vimoption_T style dictionary to the correct OptionType associated with it.
+---@return string
+local function get_option_metatype(name, info)
+  if info.type == 'string' then
+    if info.flaglist then
+      return 'set'
+    elseif info.commalist then
+      if key_value_options[name] then
+        return 'map'
+      end
+      return 'array'
+    end
+    return 'string'
+  end
+  return info.type
+end
+
+local options_info = setmetatable({}, {
+  __index = function(t, k)
+    local info = api.nvim_get_option_info(k)
+    info.metatype = get_option_metatype(k, info)
+    rawset(t, k, info)
+    return rawget(t, k)
+  end,
+})
+
+vim.env = setmetatable({}, {
+  __index = function(_, k)
+    local v = vim.fn.getenv(k)
+    if v == vim.NIL then
+      return nil
+    end
+    return v
+  end,
+
+  __newindex = function(_, k, v)
+    vim.fn.setenv(k, v)
+  end,
+})
+
+local function opt_validate(option_name, target_scope)
+  local scope = options_info[option_name].scope
+  if scope ~= target_scope then
+    local scope_to_string = { buf = 'buffer', win = 'window' }
+    error(
+      string.format(
+        [['%s' is a %s option, not a %s option. See ":help %s"]],
+        option_name,
+        scope_to_string[scope] or scope,
+        scope_to_string[target_scope] or target_scope,
+        option_name
+      )
+    )
+  end
+end
+
+local function new_buf_opt_accessor(bufnr)
+  return setmetatable({}, {
+    __index = function(_, k)
+      if bufnr == nil and type(k) == 'number' then
+        return new_buf_opt_accessor(k)
+      end
+      opt_validate(k, 'buf')
+      return api.nvim_get_option_value(k, { buf = bufnr or 0 })
+    end,
+
+    __newindex = function(_, k, v)
+      opt_validate(k, 'buf')
+      return api.nvim_set_option_value(k, v, { buf = bufnr or 0 })
+    end,
+  })
+end
+
+vim.bo = new_buf_opt_accessor()
+
+local function new_win_opt_accessor(winid, bufnr)
+  return setmetatable({}, {
+    __index = function(_, k)
+      if bufnr == nil and type(k) == 'number' then
+        if winid == nil then
+          return new_win_opt_accessor(k)
+        else
+          return new_win_opt_accessor(winid, k)
+        end
+      end
+
+      if bufnr ~= nil and bufnr ~= 0 then
+        error('only bufnr=0 is supported')
+      end
+
+      opt_validate(k, 'win')
+      -- TODO(lewis6991): allow passing both buf and win to nvim_get_option_value
+      return api.nvim_get_option_value(k, {
+        scope = bufnr and 'local' or nil,
+        win = winid or 0,
+      })
+    end,
+
+    __newindex = function(_, k, v)
+      opt_validate(k, 'win')
+      -- TODO(lewis6991): allow passing both buf and win to nvim_set_option_value
+      return api.nvim_set_option_value(k, v, {
+        scope = bufnr and 'local' or nil,
+        win = winid or 0,
+      })
+    end,
+  })
+end
+
+vim.wo = new_win_opt_accessor()
+
+-- vim global option
+--  this ONLY sets the global option. like `setglobal`
+vim.go = setmetatable({}, {
+  __index = function(_, k)
+    return api.nvim_get_option_value(k, { scope = 'global' })
+  end,
+  __newindex = function(_, k, v)
+    return api.nvim_set_option_value(k, v, { scope = 'global' })
+  end,
+})
+
+-- vim `set` style options.
+--  it has no additional metamethod magic.
+vim.o = setmetatable({}, {
+  __index = function(_, k)
+    return api.nvim_get_option_value(k, {})
+  end,
+  __newindex = function(_, k, v)
+    return api.nvim_set_option_value(k, v, {})
+  end,
+})
+
+---@brief [[
+--- vim.opt, vim.opt_local and vim.opt_global implementation
+---
+--- To be used as helpers for working with options within neovim.
+--- For information on how to use, see :help vim.opt
+---
+---@brief ]]
+
+--- Preserves the order and does not mutate the original list
+local function remove_duplicate_values(t)
+  local result, seen = {}, {}
+  for _, v in ipairs(t) do
+    if not seen[v] then
+      table.insert(result, v)
+    end
+
+    seen[v] = true
+  end
+
+  return result
+end
+
+-- Check whether the OptionTypes is allowed for vim.opt
+-- If it does not match, throw an error which indicates which option causes the error.
+local function assert_valid_value(name, value, types)
+  local type_of_value = type(value)
+  for _, valid_type in ipairs(types) do
+    if valid_type == type_of_value then
+      return
+    end
+  end
+
+  error(
+    string.format(
+      "Invalid option type '%s' for '%s', should be %s",
+      type_of_value,
+      name,
+      table.concat(types, ' or ')
+    )
+  )
+end
+
+local function passthrough(_, x)
+  return x
+end
+
+local function tbl_merge(left, right)
+  return vim.tbl_extend('force', left, right)
+end
+
+local function tbl_remove(t, value)
+  if type(value) == 'string' then
+    t[value] = nil
+  else
+    for _, v in ipairs(value) do
+      t[v] = nil
+    end
+  end
+
+  return t
+end
+
+local valid_types = {
+  boolean = { 'boolean' },
+  number = { 'number' },
+  string = { 'string' },
+  set = { 'string', 'table' },
+  array = { 'string', 'table' },
+  map = { 'string', 'table' },
+}
+
+-- Map of functions to take a Lua style value and convert to vimoption_T style value.
+-- Each function takes (info, lua_value) -> vim_value
+local to_vim_value = {
+  boolean = passthrough,
+  number = passthrough,
+  string = passthrough,
+
+  set = function(info, value)
+    if type(value) == 'string' then
+      return value
+    end
+
+    if info.flaglist and info.commalist then
+      local keys = {}
+      for k, v in pairs(value) do
+        if v then
+          table.insert(keys, k)
+        end
+      end
+
+      table.sort(keys)
+      return table.concat(keys, ',')
+    else
+      local result = ''
+      for k, v in pairs(value) do
+        if v then
+          result = result .. k
+        end
+      end
+
+      return result
+    end
+  end,
+
+  array = function(info, value)
+    if type(value) == 'string' then
+      return value
+    end
+    if not info.allows_duplicates then
+      value = remove_duplicate_values(value)
+    end
+    return table.concat(value, ',')
+  end,
+
+  map = function(_, value)
+    if type(value) == 'string' then
+      return value
+    end
+
+    local result = {}
+    for opt_key, opt_value in pairs(value) do
+      table.insert(result, string.format('%s:%s', opt_key, opt_value))
+    end
+
+    table.sort(result)
+    return table.concat(result, ',')
+  end,
+}
+
+--- Convert a Lua value to a vimoption_T value
+local function convert_value_to_vim(name, info, value)
+  if value == nil then
+    return vim.NIL
+  end
+
+  assert_valid_value(name, value, valid_types[info.metatype])
+
+  return to_vim_value[info.metatype](info, value)
+end
+
+-- Map of OptionType to functions that take vimoption_T values and convert to Lua values.
+-- Each function takes (info, vim_value) -> lua_value
+local to_lua_value = {
+  boolean = passthrough,
+  number = passthrough,
+  string = passthrough,
+
+  array = function(info, value)
+    if type(value) == 'table' then
+      if not info.allows_duplicates then
+        value = remove_duplicate_values(value)
+      end
+
+      return value
+    end
+
+    -- Empty strings mean that there is nothing there,
+    -- so empty table should be returned.
+    if value == '' then
+      return {}
+    end
+
+    -- Handles unescaped commas in a list.
+    if string.find(value, ',,,') then
+      local left, right = unpack(vim.split(value, ',,,'))
+
+      local result = {}
+      vim.list_extend(result, vim.split(left, ','))
+      table.insert(result, ',')
+      vim.list_extend(result, vim.split(right, ','))
+
+      table.sort(result)
+
+      return result
+    end
+
+    if string.find(value, ',^,,', 1, true) then
+      local left, right = unpack(vim.split(value, ',^,,', true))
+
+      local result = {}
+      vim.list_extend(result, vim.split(left, ','))
+      table.insert(result, '^,')
+      vim.list_extend(result, vim.split(right, ','))
+
+      table.sort(result)
+
+      return result
+    end
+
+    return vim.split(value, ',')
+  end,
+
+  set = function(info, value)
+    if type(value) == 'table' then
+      return value
+    end
+
+    -- Empty strings mean that there is nothing there,
+    -- so empty table should be returned.
+    if value == '' then
+      return {}
+    end
+
+    assert(info.flaglist, 'That is the only one I know how to handle')
+
+    if info.flaglist and info.commalist then
+      local split_value = vim.split(value, ',')
+      local result = {}
+      for _, v in ipairs(split_value) do
+        result[v] = true
+      end
+
+      return result
+    else
+      local result = {}
+      for i = 1, #value do
+        result[value:sub(i, i)] = true
+      end
+
+      return result
+    end
+  end,
+
+  map = function(info, raw_value)
+    if type(raw_value) == 'table' then
+      return raw_value
+    end
+
+    assert(info.commalist, 'Only commas are supported currently')
+
+    local result = {}
+
+    local comma_split = vim.split(raw_value, ',')
+    for _, key_value_str in ipairs(comma_split) do
+      local key, value = unpack(vim.split(key_value_str, ':'))
+      key = vim.trim(key)
+
+      result[key] = value
+    end
+
+    return result
+  end,
+}
+
+--- Converts a vimoption_T style value to a Lua value
+local function convert_value_to_lua(info, option_value)
+  return to_lua_value[info.metatype](info, option_value)
+end
+
+local prepend_methods = {
+  number = function()
+    error("The '^' operator is not currently supported for")
+  end,
+
+  string = function(left, right)
+    return right .. left
+  end,
+
+  array = function(left, right)
+    for i = #right, 1, -1 do
+      table.insert(left, 1, right[i])
+    end
+
+    return left
+  end,
+
+  map = tbl_merge,
+  set = tbl_merge,
+}
+
+--- Handles the '^' operator
+local function prepend_value(info, current, new)
+  return prepend_methods[info.metatype](
+    convert_value_to_lua(info, current),
+    convert_value_to_lua(info, new)
+  )
+end
+
+local add_methods = {
+  number = function(left, right)
+    return left + right
+  end,
+
+  string = function(left, right)
+    return left .. right
+  end,
+
+  array = function(left, right)
+    for _, v in ipairs(right) do
+      table.insert(left, v)
+    end
+
+    return left
+  end,
+
+  map = tbl_merge,
+  set = tbl_merge,
+}
+
+--- Handles the '+' operator
+local function add_value(info, current, new)
+  return add_methods[info.metatype](
+    convert_value_to_lua(info, current),
+    convert_value_to_lua(info, new)
+  )
+end
+
+local function remove_one_item(t, val)
+  if vim.tbl_islist(t) then
+    local remove_index = nil
+    for i, v in ipairs(t) do
+      if v == val then
+        remove_index = i
+      end
+    end
+
+    if remove_index then
+      table.remove(t, remove_index)
+    end
+  else
+    t[val] = nil
+  end
+end
+
+local remove_methods = {
+  number = function(left, right)
+    return left - right
+  end,
+
+  string = function()
+    error('Subtraction not supported for strings.')
+  end,
+
+  array = function(left, right)
+    if type(right) == 'string' then
+      remove_one_item(left, right)
+    else
+      for _, v in ipairs(right) do
+        remove_one_item(left, v)
+      end
+    end
+
+    return left
+  end,
+
+  map = tbl_remove,
+  set = tbl_remove,
+}
+
+--- Handles the '-' operator
+local function remove_value(info, current, new)
+  return remove_methods[info.metatype](convert_value_to_lua(info, current), new)
+end
+
+local function create_option_accessor(scope)
+  local option_mt
+
+  local function make_option(name, value)
+    local info = assert(options_info[name], 'Not a valid option name: ' .. name)
+
+    if type(value) == 'table' and getmetatable(value) == option_mt then
+      assert(name == value._name, "must be the same value, otherwise that's weird.")
+
+      value = value._value
+    end
+
+    return setmetatable({
+      _name = name,
+      _value = value,
+      _info = info,
+    }, option_mt)
+  end
+
+  option_mt = {
+    -- To set a value, instead use:
+    --  opt[my_option] = value
+    _set = function(self)
+      local value = convert_value_to_vim(self._name, self._info, self._value)
+      api.nvim_set_option_value(self._name, value, { scope = scope })
+    end,
+
+    get = function(self)
+      return convert_value_to_lua(self._info, self._value)
+    end,
+
+    append = function(self, right)
+      self._value = add_value(self._info, self._value, right)
+      self:_set()
+    end,
+
+    __add = function(self, right)
+      return make_option(self._name, add_value(self._info, self._value, right))
+    end,
+
+    prepend = function(self, right)
+      self._value = prepend_value(self._info, self._value, right)
+      self:_set()
+    end,
+
+    __pow = function(self, right)
+      return make_option(self._name, prepend_value(self._info, self._value, right))
+    end,
+
+    remove = function(self, right)
+      self._value = remove_value(self._info, self._value, right)
+      self:_set()
+    end,
+
+    __sub = function(self, right)
+      return make_option(self._name, remove_value(self._info, self._value, right))
+    end,
+  }
+  option_mt.__index = option_mt
+
+  return setmetatable({}, {
+    __index = function(_, k)
+      return make_option(k, api.nvim_get_option_value(k, {}))
+    end,
+
+    __newindex = function(_, k, v)
+      make_option(k, v):_set()
+    end,
+  })
+end
+
+vim.opt = create_option_accessor()
+vim.opt_local = create_option_accessor('local')
+vim.opt_global = create_option_accessor('global')
-- 
cgit 


From 0ac3c4d6314df5fe40571a83e157a425ab7ce16d Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Sat, 15 Jul 2023 16:55:32 +0100
Subject: docs(lua): move function docs to lua files

---
 runtime/lua/vim/_options.lua | 381 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 367 insertions(+), 14 deletions(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index 41e6e8be86..d498ae0a2c 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -1,3 +1,108 @@
+---@defgroup lua-vimscript
+---
+---@brief Nvim Lua provides an interface or "bridge" to Vimscript variables and
+---functions, and editor commands and options.
+---
+---Objects passed over this bridge are COPIED (marshalled): there are no
+---"references". |lua-guide-variables| For example, using \`vim.fn.remove()\` on
+---a Lua list copies the list object to Vimscript and does NOT modify the Lua
+---list:
+---<pre>lua
+---    local list = { 1, 2, 3 }
+---    vim.fn.remove(list, 0)
+---    vim.print(list)  --> "{ 1, 2, 3 }"
+---</pre>
+
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---vim.call({func}, {...})                                           *vim.call()*
+---    Invokes |vim-function| or |user-function| {func} with arguments {...}.
+---    See also |vim.fn|.
+---    Equivalent to: >lua
+---        vim.fn[func]({...})
+---<
+---vim.cmd({command})
+---    See |vim.cmd()|.
+---
+---vim.fn.{func}({...})                                                  *vim.fn*
+---    Invokes |vim-function| or |user-function| {func} with arguments {...}.
+---    To call autoload functions, use the syntax: >lua
+---        vim.fn['some\#function']({...})
+---<
+---    Unlike vim.api.|nvim_call_function()| this converts directly between Vim
+---    objects and Lua objects. If the Vim function returns a float, it will be
+---    represented directly as a Lua number. Empty lists and dictionaries both
+---    are represented by an empty table.
+---
+---    Note: |v:null| values as part of the return value is represented as
+---    |vim.NIL| special value
+---
+---    Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only
+---    enumerates functions that were called at least once.
+---
+---    Note: The majority of functions cannot run in |api-fast| callbacks with some
+---    undocumented exceptions which are allowed.
+---
+---                                                           *lua-vim-variables*
+---The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed
+---from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
+---described below. In this way you can easily read and modify global Vimscript
+---variables from Lua.
+---
+---Example: >lua
+---
+---    vim.g.foo = 5     -- Set the g:foo Vimscript variable.
+---    print(vim.g.foo)  -- Get and print the g:foo Vimscript variable.
+---    vim.g.foo = nil   -- Delete (:unlet) the Vimscript variable.
+---    vim.b[2].foo = 6  -- Set b:foo for buffer 2
+---<
+---
+---Note that setting dictionary fields directly will not write them back into
+---Nvim. This is because the index into the namespace simply returns a copy.
+---Instead the whole dictionary must be written as one. This can be achieved by
+---creating a short-lived temporary.
+---
+---Example: >lua
+---
+---    vim.g.my_dict.field1 = 'value'  -- Does not work
+---
+---    local my_dict = vim.g.my_dict   --
+---    my_dict.field1 = 'value'        -- Instead do
+---    vim.g.my_dict = my_dict         --
+---
+---vim.g                                                                  *vim.g*
+---    Global (|g:|) editor variables.
+---    Key with no value returns `nil`.
+---
+---vim.b                                                                  *vim.b*
+---    Buffer-scoped (|b:|) 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.w*
+---    Window-scoped (|w:|) 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.t                                                                  *vim.t*
+---    Tabpage-scoped (|t:|) variables for the current tabpage.
+---    Invalid or unset key returns `nil`. Can be indexed with
+---    an integer to access variables for a specific tabpage.
+---
+---vim.v                                                                  *vim.v*
+---    |v:| variables.
+---    Invalid or unset key returns `nil`.
+---
+---vim.env                                                              *vim.env*
+---    Environment variables defined in the editor session.
+---    See |expand-env| and |:let-environment| for the Vimscript behavior.
+---    Invalid or unset key returns `nil`.
+---    Example: >lua
+---        vim.env.FOO = 'bar'
+---        print(vim.env.TERM)
+---<
+---</pre>
+
 local api = vim.api
 
 -- TODO(tjdevries): Improve option metadata so that this doesn't have to be hardcoded.
@@ -13,6 +118,7 @@ local key_value_options = {
 
 --- Convert a vimoption_T style dictionary to the correct OptionType associated with it.
 ---@return string
+---@private
 local function get_option_metatype(name, info)
   if info.type == 'string' then
     if info.flaglist then
@@ -51,6 +157,7 @@ vim.env = setmetatable({}, {
   end,
 })
 
+---@private
 local function opt_validate(option_name, target_scope)
   local scope = options_info[option_name].scope
   if scope ~= target_scope then
@@ -67,6 +174,7 @@ local function opt_validate(option_name, target_scope)
   end
 end
 
+---@private
 local function new_buf_opt_accessor(bufnr)
   return setmetatable({}, {
     __index = function(_, k)
@@ -84,8 +192,7 @@ local function new_buf_opt_accessor(bufnr)
   })
 end
 
-vim.bo = new_buf_opt_accessor()
-
+---@private
 local function new_win_opt_accessor(winid, bufnr)
   return setmetatable({}, {
     __index = function(_, k)
@@ -120,30 +227,118 @@ local function new_win_opt_accessor(winid, bufnr)
   })
 end
 
-vim.wo = new_win_opt_accessor()
-
--- vim global option
---  this ONLY sets the global option. like `setglobal`
-vim.go = setmetatable({}, {
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---` `                                                                *lua-options*
+---                                                             *lua-vim-options*
+---                                                                 *lua-vim-set*
+---                                                            *lua-vim-setlocal*
+---
+---Vim options can be accessed through |vim.o|, which behaves like Vimscript
+---|:set|.
+---
+---    Examples: ~
+---
+---    To set a boolean toggle:
+---        Vimscript: `set number`
+---        Lua:       `vim.o.number = true`
+---
+---    To set a string value:
+---        Vimscript: `set wildignore=*.o,*.a,__pycache__`
+---        Lua:       `vim.o.wildignore = '*.o,*.a,__pycache__'`
+---
+---Similarly, there is |vim.bo| and |vim.wo| for setting buffer-scoped and
+---window-scoped options. Note that this must NOT be confused with
+---|local-options| and |:setlocal|. There is also |vim.go| that only accesses the
+---global value of a |global-local| option, see |:setglobal|.
+---</pre>
+
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---vim.o                                                                  *vim.o*
+---    Get or set |options|. Like `:set`. Invalid key is an error.
+---
+---    Note: this works on both buffer-scoped and window-scoped options using the
+---    current buffer and window.
+---
+---    Example: >lua
+---        vim.o.cmdheight = 4
+---        print(vim.o.columns)
+---        print(vim.o.foo)     -- error: invalid key
+---<
+---</pre>
+vim.o = setmetatable({}, {
   __index = function(_, k)
-    return api.nvim_get_option_value(k, { scope = 'global' })
+    return api.nvim_get_option_value(k, {})
   end,
   __newindex = function(_, k, v)
-    return api.nvim_set_option_value(k, v, { scope = 'global' })
+    return api.nvim_set_option_value(k, v, {})
   end,
 })
 
--- vim `set` style options.
---  it has no additional metamethod magic.
-vim.o = setmetatable({}, {
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---vim.go                                                                *vim.go*
+---    Get or set global |options|. Like `:setglobal`. Invalid key is
+---    an error.
+---
+---    Note: this is different from |vim.o| because this accesses the global
+---    option value and thus is mostly useful for use with |global-local|
+---    options.
+---
+---    Example: >lua
+---        vim.go.cmdheight = 4
+---        print(vim.go.columns)
+---        print(vim.go.bar)     -- error: invalid key
+---<
+---</pre>
+vim.go = setmetatable({}, {
   __index = function(_, k)
-    return api.nvim_get_option_value(k, {})
+    return api.nvim_get_option_value(k, { scope = 'global' })
   end,
   __newindex = function(_, k, v)
-    return api.nvim_set_option_value(k, v, {})
+    return api.nvim_set_option_value(k, v, { scope = 'global' })
   end,
 })
 
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---vim.bo[{bufnr}]                                                                *vim.bo*
+---    Get or set buffer-scoped |options| for the buffer with number {bufnr}.
+---    Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
+---    buffer is used. Invalid {bufnr} or key is an error.
+---
+---    Note: this is equivalent to both `:set` and `:setlocal`.
+---
+---    Example: >lua
+---        local bufnr = vim.api.nvim_get_current_buf()
+---        vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
+---        print(vim.bo.comments)
+---        print(vim.bo.baz)                 -- error: invalid key
+---</pre>
+vim.bo = new_buf_opt_accessor()
+
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---vim.wo[{winid}][{bufnr}]                                                       *vim.wo*
+---    Get or set window-scoped |options| for the window with handle {winid} and
+---    buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
+---    `:set` otherwise. If [{winid}] is omitted then the current window is
+---    used. Invalid {winid}, {bufnr} or key is an error.
+---
+---    Note: only {bufnr} with value `0` (the current buffer in the window) is
+---    supported.
+---
+---    Example: >lua
+---        local winid = vim.api.nvim_get_current_win()
+---        vim.wo[winid].number = true    -- same as vim.wo.number = true
+---        print(vim.wo.foldmarker)
+---        print(vim.wo.quux)             -- error: invalid key
+---        vim.wo[winid][0].spell = false -- like ':setlocal nospell'
+---<
+---</pre>
+vim.wo = new_win_opt_accessor()
+
 ---@brief [[
 --- vim.opt, vim.opt_local and vim.opt_global implementation
 ---
@@ -153,6 +348,7 @@ vim.o = setmetatable({}, {
 ---@brief ]]
 
 --- Preserves the order and does not mutate the original list
+--- @private
 local function remove_duplicate_values(t)
   local result, seen = {}, {}
   for _, v in ipairs(t) do
@@ -168,6 +364,7 @@ end
 
 -- Check whether the OptionTypes is allowed for vim.opt
 -- If it does not match, throw an error which indicates which option causes the error.
+--- @private
 local function assert_valid_value(name, value, types)
   local type_of_value = type(value)
   for _, valid_type in ipairs(types) do
@@ -186,14 +383,17 @@ local function assert_valid_value(name, value, types)
   )
 end
 
+--- @private
 local function passthrough(_, x)
   return x
 end
 
+--- @private
 local function tbl_merge(left, right)
   return vim.tbl_extend('force', left, right)
 end
 
+--- @private
 local function tbl_remove(t, value)
   if type(value) == 'string' then
     t[value] = nil
@@ -275,6 +475,7 @@ local to_vim_value = {
 }
 
 --- Convert a Lua value to a vimoption_T value
+--- @private
 local function convert_value_to_vim(name, info, value)
   if value == nil then
     return vim.NIL
@@ -390,6 +591,7 @@ local to_lua_value = {
 }
 
 --- Converts a vimoption_T style value to a Lua value
+--- @private
 local function convert_value_to_lua(info, option_value)
   return to_lua_value[info.metatype](info, option_value)
 end
@@ -416,6 +618,7 @@ local prepend_methods = {
 }
 
 --- Handles the '^' operator
+--- @private
 local function prepend_value(info, current, new)
   return prepend_methods[info.metatype](
     convert_value_to_lua(info, current),
@@ -445,6 +648,7 @@ local add_methods = {
 }
 
 --- Handles the '+' operator
+--- @private
 local function add_value(info, current, new)
   return add_methods[info.metatype](
     convert_value_to_lua(info, current),
@@ -452,6 +656,7 @@ local function add_value(info, current, new)
   )
 end
 
+--- @private
 local function remove_one_item(t, val)
   if vim.tbl_islist(t) then
     local remove_index = nil
@@ -495,13 +700,16 @@ local remove_methods = {
 }
 
 --- Handles the '-' operator
+--- @private
 local function remove_value(info, current, new)
   return remove_methods[info.metatype](convert_value_to_lua(info, current), new)
 end
 
+--- @private
 local function create_option_accessor(scope)
   local option_mt
 
+  --- @private
   local function make_option(name, value)
     local info = assert(options_info[name], 'Not a valid option name: ' .. name)
 
@@ -570,6 +778,151 @@ local function create_option_accessor(scope)
   })
 end
 
+---@addtogroup lua-vimscript
+---@brief <pre>help
+---` `                                                                       *vim.opt_local*
+---                                                                       *vim.opt_global*
+---                                                                              *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: >vim
+---            set wildignore=*.o,*.a,__pycache__
+---<
+---        In Lua using `vim.o`: >lua
+---            vim.o.wildignore = '*.o,*.a,__pycache__'
+---<
+---        In Lua using `vim.opt`: >lua
+---            vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }
+---<
+---    To replicate the behavior of |:set+=|, use: >lua
+---
+---        vim.opt.wildignore:append { "*.pyc", "node_modules" }
+---<
+---    To replicate the behavior of |:set^=|, use: >lua
+---
+---        vim.opt.wildignore:prepend { "new_first_value" }
+---<
+---    To replicate the behavior of |:set-=|, use: >lua
+---
+---        vim.opt.wildignore:remove { "node_modules" }
+---<
+---    The following methods of setting a map-style option are equivalent:
+---        In Vimscript: >vim
+---            set listchars=space:_,tab:>~
+---<
+---        In Lua using `vim.o`: >lua
+---            vim.o.listchars = 'space:_,tab:>~'
+---<
+---        In Lua using `vim.opt`: >lua
+---            vim.opt.listchars = { space = '_', tab = '>~' }
+---<
+---
+---Note that |vim.opt| returns an `Option` object, not the value of the option,
+---which is accessed through |vim.opt:get()|:
+---
+---    Examples: ~
+---
+---    The following methods of getting a list-style option are equivalent:
+---        In Vimscript: >vim
+---            echo wildignore
+---<
+---        In Lua using `vim.o`: >lua
+---            print(vim.o.wildignore)
+---<
+---        In Lua using `vim.opt`: >lua
+---            vim.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`.
+---</pre>
+
+--- @diagnostic disable-next-line:unused-local used for gen_vimdoc
+local Option = {}
+
+---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: <pre>lua
+---    vim.cmd [[set wildignore=*.pyc,*.o]]
+---
+---    vim.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
+---</pre>
+---
+---For values that are comma-separated maps, a table will be returned with
+---the names as keys and the values as entries: <pre>lua
+---    vim.cmd [[set listchars=space:_,tab:>~]]
+---
+---    vim.print(vim.opt.listchars:get())
+---    --  { space = "_", tab = ">~", }
+---
+---    for char, representation in pairs(vim.opt.listchars:get()) do
+---        print(char, "=>", representation)
+---    end
+---</pre>
+---
+---For values that are lists of flags, a set will be returned with the flags
+---as keys and `true` as entries. <pre>lua
+---    vim.cmd [[set formatoptions=njtcroql]]
+---
+---    vim.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
+---</pre>
+---@return string|integer|boolean|nil value of option
+---@diagnostic disable-next-line:unused-local used for gen_vimdoc
+function Option:get() end
+
+---Append a value to string-style options. See |:set+=|
+---
+---These are equivalent: <pre>lua
+---    vim.opt.formatoptions:append('j')
+---    vim.opt.formatoptions = vim.opt.formatoptions + 'j'
+---</pre>
+---@param value string Value to append
+--- @diagnostic disable-next-line:unused-local used for gen_vimdoc
+function Option:append(value) end
+
+---Prepend a value to string-style options. See |:set^=|
+---
+---These are equivalent: <pre>lua
+---    vim.opt.wildignore:prepend('*.o')
+---    vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
+---</pre>
+---@param value string Value to prepend
+---@diagnostic disable-next-line:unused-local used for gen_vimdoc
+function Option:prepend(value) end
+
+---Remove a value from string-style options. See |:set-=|
+---
+---These are equivalent: <pre>lua
+---    vim.opt.wildignore:remove('*.pyc')
+---    vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
+---</pre>
+---@param value string Value to remove
+---@diagnostic disable-next-line:unused-local used for gen_vimdoc
+function Option:remove(value) end
+
 vim.opt = create_option_accessor()
 vim.opt_local = create_option_accessor('local')
 vim.opt_global = create_option_accessor('global')
-- 
cgit 


From 69d49727d7766d799aa1989bf67e763258b868e6 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Mon, 17 Jul 2023 16:32:56 +0100
Subject: fix: luacheck

---
 runtime/lua/vim/_options.lua | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index d498ae0a2c..6dbe4cf64a 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -846,7 +846,7 @@ end
 ---</pre>
 
 --- @diagnostic disable-next-line:unused-local used for gen_vimdoc
-local Option = {}
+local Option = {} -- luacheck: no unused
 
 ---Returns a Lua-representation of the option. Boolean, number and string
 ---values will be returned in exactly the same fashion.
@@ -901,7 +901,7 @@ function Option:get() end
 ---</pre>
 ---@param value string Value to append
 --- @diagnostic disable-next-line:unused-local used for gen_vimdoc
-function Option:append(value) end
+function Option:append(value) end -- luacheck: no unused
 
 ---Prepend a value to string-style options. See |:set^=|
 ---
@@ -911,7 +911,7 @@ function Option:append(value) end
 ---</pre>
 ---@param value string Value to prepend
 ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
-function Option:prepend(value) end
+function Option:prepend(value) end -- luacheck: no unused
 
 ---Remove a value from string-style options. See |:set-=|
 ---
@@ -921,7 +921,7 @@ function Option:prepend(value) end
 ---</pre>
 ---@param value string Value to remove
 ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
-function Option:remove(value) end
+function Option:remove(value) end -- luacheck: no unused
 
 vim.opt = create_option_accessor()
 vim.opt_local = create_option_accessor('local')
-- 
cgit 


From be74807eef13ff8c90d55cf8b22b01d6d33b1641 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Tue, 18 Jul 2023 15:42:30 +0100
Subject: docs(lua): more improvements (#24387)

* docs(lua): teach lua2dox how to table

* docs(lua): teach gen_vimdoc.py about local functions

No more need to mark local functions with @private

* docs(lua): mention @nodoc and @meta in dev-lua-doc

* fixup!

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>

---------

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
---
 runtime/lua/vim/_options.lua | 142 ++++++++++++++++++-------------------------
 1 file changed, 58 insertions(+), 84 deletions(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index 6dbe4cf64a..d54e8b447c 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -92,15 +92,6 @@
 ---vim.v                                                                  *vim.v*
 ---    |v:| variables.
 ---    Invalid or unset key returns `nil`.
----
----vim.env                                                              *vim.env*
----    Environment variables defined in the editor session.
----    See |expand-env| and |:let-environment| for the Vimscript behavior.
----    Invalid or unset key returns `nil`.
----    Example: >lua
----        vim.env.FOO = 'bar'
----        print(vim.env.TERM)
----<
 ---</pre>
 
 local api = vim.api
@@ -118,7 +109,6 @@ local key_value_options = {
 
 --- Convert a vimoption_T style dictionary to the correct OptionType associated with it.
 ---@return string
----@private
 local function get_option_metatype(name, info)
   if info.type == 'string' then
     if info.flaglist then
@@ -143,6 +133,14 @@ local options_info = setmetatable({}, {
   end,
 })
 
+---Environment variables defined in the editor session.
+---See |expand-env| and |:let-environment| for the Vimscript behavior.
+---Invalid or unset key returns `nil`.
+---Example: <pre>lua
+---    vim.env.FOO = 'bar'
+---    print(vim.env.TERM)
+---</pre>
+---@param var string
 vim.env = setmetatable({}, {
   __index = function(_, k)
     local v = vim.fn.getenv(k)
@@ -157,7 +155,6 @@ vim.env = setmetatable({}, {
   end,
 })
 
----@private
 local function opt_validate(option_name, target_scope)
   local scope = options_info[option_name].scope
   if scope ~= target_scope then
@@ -174,7 +171,6 @@ local function opt_validate(option_name, target_scope)
   end
 end
 
----@private
 local function new_buf_opt_accessor(bufnr)
   return setmetatable({}, {
     __index = function(_, k)
@@ -192,7 +188,6 @@ local function new_buf_opt_accessor(bufnr)
   })
 end
 
----@private
 local function new_win_opt_accessor(winid, bufnr)
   return setmetatable({}, {
     __index = function(_, k)
@@ -253,19 +248,15 @@ end
 ---global value of a |global-local| option, see |:setglobal|.
 ---</pre>
 
----@addtogroup lua-vimscript
----@brief <pre>help
----vim.o                                                                  *vim.o*
----    Get or set |options|. Like `:set`. Invalid key is an error.
+---Get or set |options|. Like `:set`. Invalid key is an error.
 ---
----    Note: this works on both buffer-scoped and window-scoped options using the
----    current buffer and window.
+---Note: this works on both buffer-scoped and window-scoped options using the
+---current buffer and window.
 ---
----    Example: >lua
----        vim.o.cmdheight = 4
----        print(vim.o.columns)
----        print(vim.o.foo)     -- error: invalid key
----<
+---Example: <pre>lua
+---    vim.o.cmdheight = 4
+---    print(vim.o.columns)
+---    print(vim.o.foo)     -- error: invalid key
 ---</pre>
 vim.o = setmetatable({}, {
   __index = function(_, k)
@@ -276,21 +267,17 @@ vim.o = setmetatable({}, {
   end,
 })
 
----@addtogroup lua-vimscript
----@brief <pre>help
----vim.go                                                                *vim.go*
----    Get or set global |options|. Like `:setglobal`. Invalid key is
----    an error.
----
----    Note: this is different from |vim.o| because this accesses the global
----    option value and thus is mostly useful for use with |global-local|
----    options.
----
----    Example: >lua
----        vim.go.cmdheight = 4
----        print(vim.go.columns)
----        print(vim.go.bar)     -- error: invalid key
----<
+---Get or set global |options|. Like `:setglobal`. Invalid key is
+---an error.
+---
+---Note: this is different from |vim.o| because this accesses the global
+---option value and thus is mostly useful for use with |global-local|
+---options.
+---
+---Example: <pre>lua
+---    vim.go.cmdheight = 4
+---    print(vim.go.columns)
+---    print(vim.go.bar)     -- error: invalid key
 ---</pre>
 vim.go = setmetatable({}, {
   __index = function(_, k)
@@ -301,41 +288,36 @@ vim.go = setmetatable({}, {
   end,
 })
 
----@addtogroup lua-vimscript
----@brief <pre>help
----vim.bo[{bufnr}]                                                                *vim.bo*
----    Get or set buffer-scoped |options| for the buffer with number {bufnr}.
----    Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
----    buffer is used. Invalid {bufnr} or key is an error.
----
----    Note: this is equivalent to both `:set` and `:setlocal`.
----
----    Example: >lua
----        local bufnr = vim.api.nvim_get_current_buf()
----        vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
----        print(vim.bo.comments)
----        print(vim.bo.baz)                 -- error: invalid key
+---Get or set buffer-scoped |options| for the buffer with number {bufnr}.
+---Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
+---buffer is used. Invalid {bufnr} or key is an error.
+---
+---Note: this is equivalent to both `:set` and `:setlocal`.
+---
+---Example: <pre>lua
+---    local bufnr = vim.api.nvim_get_current_buf()
+---    vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
+---    print(vim.bo.comments)
+---    print(vim.bo.baz)                 -- error: invalid key
 ---</pre>
+---@param bufnr integer|nil
 vim.bo = new_buf_opt_accessor()
 
----@addtogroup lua-vimscript
----@brief <pre>help
----vim.wo[{winid}][{bufnr}]                                                       *vim.wo*
----    Get or set window-scoped |options| for the window with handle {winid} and
----    buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
----    `:set` otherwise. If [{winid}] is omitted then the current window is
----    used. Invalid {winid}, {bufnr} or key is an error.
----
----    Note: only {bufnr} with value `0` (the current buffer in the window) is
----    supported.
----
----    Example: >lua
----        local winid = vim.api.nvim_get_current_win()
----        vim.wo[winid].number = true    -- same as vim.wo.number = true
----        print(vim.wo.foldmarker)
----        print(vim.wo.quux)             -- error: invalid key
----        vim.wo[winid][0].spell = false -- like ':setlocal nospell'
----<
+---Get or set window-scoped |options| for the window with handle {winid} and
+---buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
+---`:set` otherwise. If [{winid}] is omitted then the current window is
+---used. Invalid {winid}, {bufnr} or key is an error.
+---
+---Note: only {bufnr} with value `0` (the current buffer in the window) is
+---supported.
+---
+---Example: <pre>lua
+---    local winid = vim.api.nvim_get_current_win()
+---    vim.wo[winid].number = true    -- same as vim.wo.number = true
+---    print(vim.wo.foldmarker)
+---    print(vim.wo.quux)             -- error: invalid key
+---    vim.wo[winid][0].spell = false -- like ':setlocal nospell'
+---
 ---</pre>
 vim.wo = new_win_opt_accessor()
 
@@ -348,7 +330,6 @@ vim.wo = new_win_opt_accessor()
 ---@brief ]]
 
 --- Preserves the order and does not mutate the original list
---- @private
 local function remove_duplicate_values(t)
   local result, seen = {}, {}
   for _, v in ipairs(t) do
@@ -364,7 +345,6 @@ end
 
 -- Check whether the OptionTypes is allowed for vim.opt
 -- If it does not match, throw an error which indicates which option causes the error.
---- @private
 local function assert_valid_value(name, value, types)
   local type_of_value = type(value)
   for _, valid_type in ipairs(types) do
@@ -383,17 +363,14 @@ local function assert_valid_value(name, value, types)
   )
 end
 
---- @private
 local function passthrough(_, x)
   return x
 end
 
---- @private
 local function tbl_merge(left, right)
   return vim.tbl_extend('force', left, right)
 end
 
---- @private
 local function tbl_remove(t, value)
   if type(value) == 'string' then
     t[value] = nil
@@ -475,7 +452,6 @@ local to_vim_value = {
 }
 
 --- Convert a Lua value to a vimoption_T value
---- @private
 local function convert_value_to_vim(name, info, value)
   if value == nil then
     return vim.NIL
@@ -591,7 +567,6 @@ local to_lua_value = {
 }
 
 --- Converts a vimoption_T style value to a Lua value
---- @private
 local function convert_value_to_lua(info, option_value)
   return to_lua_value[info.metatype](info, option_value)
 end
@@ -618,7 +593,6 @@ local prepend_methods = {
 }
 
 --- Handles the '^' operator
---- @private
 local function prepend_value(info, current, new)
   return prepend_methods[info.metatype](
     convert_value_to_lua(info, current),
@@ -648,7 +622,6 @@ local add_methods = {
 }
 
 --- Handles the '+' operator
---- @private
 local function add_value(info, current, new)
   return add_methods[info.metatype](
     convert_value_to_lua(info, current),
@@ -656,7 +629,6 @@ local function add_value(info, current, new)
   )
 end
 
---- @private
 local function remove_one_item(t, val)
   if vim.tbl_islist(t) then
     local remove_index = nil
@@ -700,16 +672,13 @@ local remove_methods = {
 }
 
 --- Handles the '-' operator
---- @private
 local function remove_value(info, current, new)
   return remove_methods[info.metatype](convert_value_to_lua(info, current), new)
 end
 
---- @private
 local function create_option_accessor(scope)
   local option_mt
 
-  --- @private
   local function make_option(name, value)
     local info = assert(options_info[name], 'Not a valid option name: ' .. name)
 
@@ -923,6 +892,11 @@ function Option:prepend(value) end -- luacheck: no unused
 ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
 function Option:remove(value) end -- luacheck: no unused
 
+---@private
 vim.opt = create_option_accessor()
+
+---@private
 vim.opt_local = create_option_accessor('local')
+
+---@private
 vim.opt_global = create_option_accessor('global')
-- 
cgit 


From 24e3ee9d07e1433cb13b4d96ec20999f5f02b204 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Sat, 22 Jul 2023 09:52:13 +0100
Subject: fix(api/options): validate buf and win

Fixes #24398
---
 runtime/lua/vim/_options.lua | 36 +++++++-----------------------------
 1 file changed, 7 insertions(+), 29 deletions(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index d54e8b447c..e1c125baf2 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -124,14 +124,12 @@ local function get_option_metatype(name, info)
   return info.type
 end
 
-local options_info = setmetatable({}, {
-  __index = function(t, k)
-    local info = api.nvim_get_option_info(k)
-    info.metatype = get_option_metatype(k, info)
-    rawset(t, k, info)
-    return rawget(t, k)
-  end,
-})
+--- @param name string
+local function get_options_info(name)
+  local info = api.nvim_get_option_info(name)
+  info.metatype = get_option_metatype(name, info)
+  return info
+end
 
 ---Environment variables defined in the editor session.
 ---See |expand-env| and |:let-environment| for the Vimscript behavior.
@@ -155,34 +153,16 @@ vim.env = setmetatable({}, {
   end,
 })
 
-local function opt_validate(option_name, target_scope)
-  local scope = options_info[option_name].scope
-  if scope ~= target_scope then
-    local scope_to_string = { buf = 'buffer', win = 'window' }
-    error(
-      string.format(
-        [['%s' is a %s option, not a %s option. See ":help %s"]],
-        option_name,
-        scope_to_string[scope] or scope,
-        scope_to_string[target_scope] or target_scope,
-        option_name
-      )
-    )
-  end
-end
-
 local function new_buf_opt_accessor(bufnr)
   return setmetatable({}, {
     __index = function(_, k)
       if bufnr == nil and type(k) == 'number' then
         return new_buf_opt_accessor(k)
       end
-      opt_validate(k, 'buf')
       return api.nvim_get_option_value(k, { buf = bufnr or 0 })
     end,
 
     __newindex = function(_, k, v)
-      opt_validate(k, 'buf')
       return api.nvim_set_option_value(k, v, { buf = bufnr or 0 })
     end,
   })
@@ -203,7 +183,6 @@ local function new_win_opt_accessor(winid, bufnr)
         error('only bufnr=0 is supported')
       end
 
-      opt_validate(k, 'win')
       -- TODO(lewis6991): allow passing both buf and win to nvim_get_option_value
       return api.nvim_get_option_value(k, {
         scope = bufnr and 'local' or nil,
@@ -212,7 +191,6 @@ local function new_win_opt_accessor(winid, bufnr)
     end,
 
     __newindex = function(_, k, v)
-      opt_validate(k, 'win')
       -- TODO(lewis6991): allow passing both buf and win to nvim_set_option_value
       return api.nvim_set_option_value(k, v, {
         scope = bufnr and 'local' or nil,
@@ -680,7 +658,7 @@ local function create_option_accessor(scope)
   local option_mt
 
   local function make_option(name, value)
-    local info = assert(options_info[name], 'Not a valid option name: ' .. name)
+    local info = assert(get_options_info(name), 'Not a valid option name: ' .. name)
 
     if type(value) == 'table' and getmetatable(value) == option_mt then
       assert(name == value._name, "must be the same value, otherwise that's weird.")
-- 
cgit 


From 2e92065686f62851318150a315591c30b8306a4b Mon Sep 17 00:00:00 2001
From: Gregory Anders <8965202+gpanders@users.noreply.github.com>
Date: Thu, 14 Sep 2023 08:23:01 -0500
Subject: docs: replace <pre> with ``` (#25136)

---
 runtime/lua/vim/_options.lua | 231 ++++++++++++++++++++++++-------------------
 1 file changed, 129 insertions(+), 102 deletions(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index e1c125baf2..7b44f6b35f 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -7,11 +7,12 @@
 ---"references". |lua-guide-variables| For example, using \`vim.fn.remove()\` on
 ---a Lua list copies the list object to Vimscript and does NOT modify the Lua
 ---list:
----<pre>lua
----    local list = { 1, 2, 3 }
----    vim.fn.remove(list, 0)
----    vim.print(list)  --> "{ 1, 2, 3 }"
----</pre>
+---
+--- ```lua
+--- local list = { 1, 2, 3 }
+--- vim.fn.remove(list, 0)
+--- vim.print(list)  --> "{ 1, 2, 3 }"
+--- ```
 
 ---@addtogroup lua-vimscript
 ---@brief <pre>help
@@ -131,13 +132,17 @@ local function get_options_info(name)
   return info
 end
 
----Environment variables defined in the editor session.
----See |expand-env| and |:let-environment| for the Vimscript behavior.
----Invalid or unset key returns `nil`.
----Example: <pre>lua
----    vim.env.FOO = 'bar'
----    print(vim.env.TERM)
----</pre>
+--- Environment variables defined in the editor session.
+--- See |expand-env| and |:let-environment| for the Vimscript behavior.
+--- Invalid or unset key returns `nil`.
+---
+--- Example:
+---
+--- ```lua
+--- vim.env.FOO = 'bar'
+--- print(vim.env.TERM)
+--- ```
+---
 ---@param var string
 vim.env = setmetatable({}, {
   __index = function(_, k)
@@ -226,16 +231,18 @@ end
 ---global value of a |global-local| option, see |:setglobal|.
 ---</pre>
 
----Get or set |options|. Like `:set`. Invalid key is an error.
+--- Get or set |options|. Like `:set`. Invalid key is an error.
 ---
----Note: this works on both buffer-scoped and window-scoped options using the
----current buffer and window.
+--- Note: this works on both buffer-scoped and window-scoped options using the
+--- current buffer and window.
 ---
----Example: <pre>lua
----    vim.o.cmdheight = 4
----    print(vim.o.columns)
----    print(vim.o.foo)     -- error: invalid key
----</pre>
+--- Example:
+---
+--- ```lua
+--- vim.o.cmdheight = 4
+--- print(vim.o.columns)
+--- print(vim.o.foo)     -- error: invalid key
+--- ```
 vim.o = setmetatable({}, {
   __index = function(_, k)
     return api.nvim_get_option_value(k, {})
@@ -245,18 +252,20 @@ vim.o = setmetatable({}, {
   end,
 })
 
----Get or set global |options|. Like `:setglobal`. Invalid key is
----an error.
+--- Get or set global |options|. Like `:setglobal`. Invalid key is
+--- an error.
 ---
----Note: this is different from |vim.o| because this accesses the global
----option value and thus is mostly useful for use with |global-local|
----options.
+--- Note: this is different from |vim.o| because this accesses the global
+--- option value and thus is mostly useful for use with |global-local|
+--- options.
 ---
----Example: <pre>lua
----    vim.go.cmdheight = 4
----    print(vim.go.columns)
----    print(vim.go.bar)     -- error: invalid key
----</pre>
+--- Example:
+---
+--- ```lua
+--- vim.go.cmdheight = 4
+--- print(vim.go.columns)
+--- print(vim.go.bar)     -- error: invalid key
+--- ```
 vim.go = setmetatable({}, {
   __index = function(_, k)
     return api.nvim_get_option_value(k, { scope = 'global' })
@@ -266,37 +275,39 @@ vim.go = setmetatable({}, {
   end,
 })
 
----Get or set buffer-scoped |options| for the buffer with number {bufnr}.
----Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
----buffer is used. Invalid {bufnr} or key is an error.
+--- Get or set buffer-scoped |options| for the buffer with number {bufnr}.
+--- Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
+--- buffer is used. Invalid {bufnr} or key is an error.
 ---
----Note: this is equivalent to both `:set` and `:setlocal`.
+--- Note: this is equivalent to both `:set` and `:setlocal`.
 ---
----Example: <pre>lua
----    local bufnr = vim.api.nvim_get_current_buf()
----    vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
----    print(vim.bo.comments)
----    print(vim.bo.baz)                 -- error: invalid key
----</pre>
----@param bufnr integer|nil
+--- Example:
+---
+--- ```lua
+--- local bufnr = vim.api.nvim_get_current_buf()
+--- vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
+--- print(vim.bo.comments)
+--- print(vim.bo.baz)                 -- error: invalid key
+--- ```
 vim.bo = new_buf_opt_accessor()
 
----Get or set window-scoped |options| for the window with handle {winid} and
----buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
----`:set` otherwise. If [{winid}] is omitted then the current window is
----used. Invalid {winid}, {bufnr} or key is an error.
+--- Get or set window-scoped |options| for the window with handle {winid} and
+--- buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
+--- `:set` otherwise. If [{winid}] is omitted then the current window is
+--- used. Invalid {winid}, {bufnr} or key is an error.
 ---
----Note: only {bufnr} with value `0` (the current buffer in the window) is
----supported.
+--- Note: only {bufnr} with value `0` (the current buffer in the window) is
+--- supported.
 ---
----Example: <pre>lua
----    local winid = vim.api.nvim_get_current_win()
----    vim.wo[winid].number = true    -- same as vim.wo.number = true
----    print(vim.wo.foldmarker)
----    print(vim.wo.quux)             -- error: invalid key
----    vim.wo[winid][0].spell = false -- like ':setlocal nospell'
+--- Example:
 ---
----</pre>
+--- ```lua
+--- local winid = vim.api.nvim_get_current_win()
+--- vim.wo[winid].number = true    -- same as vim.wo.number = true
+--- print(vim.wo.foldmarker)
+--- print(vim.wo.quux)             -- error: invalid key
+--- vim.wo[winid][0].spell = false -- like ':setlocal nospell'
+--- ```
 vim.wo = new_win_opt_accessor()
 
 ---@brief [[
@@ -795,77 +806,93 @@ end
 --- @diagnostic disable-next-line:unused-local used for gen_vimdoc
 local Option = {} -- luacheck: no unused
 
----Returns a Lua-representation of the option. Boolean, number and string
----values will be returned in exactly the same fashion.
+--- 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: <pre>lua
----    vim.cmd [[set wildignore=*.pyc,*.o]]
+--- For values that are comma-separated lists, an array will be returned with
+--- the values as entries in the array:
 ---
----    vim.print(vim.opt.wildignore:get())
----    -- { "*.pyc", "*.o", }
+--- ```lua
+--- vim.cmd [[set wildignore=*.pyc,*.o]]
 ---
----    for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do
----        print("Will ignore:", ignore_pattern)
----    end
----    -- Will ignore: *.pyc
----    -- Will ignore: *.o
----</pre>
+--- vim.print(vim.opt.wildignore:get())
+--- -- { "*.pyc", "*.o", }
 ---
----For values that are comma-separated maps, a table will be returned with
----the names as keys and the values as entries: <pre>lua
----    vim.cmd [[set listchars=space:_,tab:>~]]
+--- for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do
+---     print("Will ignore:", ignore_pattern)
+--- end
+--- -- Will ignore: *.pyc
+--- -- Will ignore: *.o
+--- ```
 ---
----    vim.print(vim.opt.listchars:get())
----    --  { space = "_", tab = ">~", }
+--- For values that are comma-separated maps, a table will be returned with
+--- the names as keys and the values as entries:
 ---
----    for char, representation in pairs(vim.opt.listchars:get()) do
----        print(char, "=>", representation)
----    end
----</pre>
+--- ```lua
+--- vim.cmd [[set listchars=space:_,tab:>~]]
 ---
----For values that are lists of flags, a set will be returned with the flags
----as keys and `true` as entries. <pre>lua
----    vim.cmd [[set formatoptions=njtcroql]]
+--- vim.print(vim.opt.listchars:get())
+--- --  { space = "_", tab = ">~", }
 ---
----    vim.print(vim.opt.formatoptions:get())
----    -- { n = true, j = true, c = true, ... }
+--- 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.
+---
+--- ```lua
+--- vim.cmd [[set formatoptions=njtcroql]]
+---
+--- vim.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
+--- ```
 ---
----    local format_opts = vim.opt.formatoptions:get()
----    if format_opts.j then
----        print("J is enabled!")
----    end
----</pre>
 ---@return string|integer|boolean|nil value of option
 ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
 function Option:get() end
 
----Append a value to string-style options. See |:set+=|
+--- Append a value to string-style options. See |:set+=|
+---
+--- These are equivalent:
+---
+--- ```lua
+--- vim.opt.formatoptions:append('j')
+--- vim.opt.formatoptions = vim.opt.formatoptions + 'j'
+--- ```
 ---
----These are equivalent: <pre>lua
----    vim.opt.formatoptions:append('j')
----    vim.opt.formatoptions = vim.opt.formatoptions + 'j'
----</pre>
 ---@param value string Value to append
---- @diagnostic disable-next-line:unused-local used for gen_vimdoc
+---@diagnostic disable-next-line:unused-local used for gen_vimdoc
 function Option:append(value) end -- luacheck: no unused
 
----Prepend a value to string-style options. See |:set^=|
+--- Prepend a value to string-style options. See |:set^=|
+---
+--- These are equivalent:
+---
+--- ```lua
+--- vim.opt.wildignore:prepend('*.o')
+--- vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
+--- ```
 ---
----These are equivalent: <pre>lua
----    vim.opt.wildignore:prepend('*.o')
----    vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
----</pre>
 ---@param value string Value to prepend
 ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
 function Option:prepend(value) end -- luacheck: no unused
 
----Remove a value from string-style options. See |:set-=|
+--- Remove a value from string-style options. See |:set-=|
+---
+--- These are equivalent:
+---
+--- ```lua
+--- vim.opt.wildignore:remove('*.pyc')
+--- vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
+--- ```
 ---
----These are equivalent: <pre>lua
----    vim.opt.wildignore:remove('*.pyc')
----    vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
----</pre>
 ---@param value string Value to remove
 ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
 function Option:remove(value) end -- luacheck: no unused
-- 
cgit 


From 4ab9c5fa46845807a2dc6dd91fc5fb78ccc70856 Mon Sep 17 00:00:00 2001
From: Phelipe Teles <39670535+phelipetls@users.noreply.github.com>
Date: Sat, 16 Sep 2023 19:35:12 -0300
Subject: fix(lua): not using global value in vim.opt_global (#25196)

---
 runtime/lua/vim/_options.lua | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index 7b44f6b35f..6a3413b597 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -727,7 +727,10 @@ local function create_option_accessor(scope)
 
   return setmetatable({}, {
     __index = function(_, k)
-      return make_option(k, api.nvim_get_option_value(k, {}))
+      -- vim.opt_global must get global value only
+      -- vim.opt_local may fall back to global value like vim.opt
+      local opts = { scope = scope == 'global' and 'global' or nil }
+      return make_option(k, api.nvim_get_option_value(k, opts))
     end,
 
     __newindex = function(_, k, v)
-- 
cgit 


From db51548036ebe4b01c5b78aeca7a76aa71ab4fbe Mon Sep 17 00:00:00 2001
From: Maria José Solano <majosolano99@gmail.com>
Date: Sun, 24 Sep 2023 21:39:59 -0700
Subject: docs: do not use deprecated functions #25334

---
 runtime/lua/vim/_options.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index 6a3413b597..b83a8dd4b1 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -127,7 +127,7 @@ end
 
 --- @param name string
 local function get_options_info(name)
-  local info = api.nvim_get_option_info(name)
+  local info = api.nvim_get_option_info2(name, {})
   info.metatype = get_option_metatype(name, info)
   return info
 end
-- 
cgit