refactor(api/marks)!: add opts param for feature extensibility (#16146)

In the future we might want to extend the concept of named marks and
adding opts reduces the need of changing the function signature in the
furute.

runtime/doc/api.txt

@@ -1078,7 +1078,7 @@ nvim_get_keymap({mode})                                    *nvim_get_keymap()*
                     Array of maparg()-like dictionaries describing mappings.
                     The "buffer" key is always zero.
 
-nvim_get_mark({name})                                        *nvim_get_mark()*
+nvim_get_mark({name}, {opts})                                *nvim_get_mark()*
                 Return a tuple (row, col, buffer, buffername) representing the
                 position of the uppercase/file named mark. See |mark-motions|.
 
@@ -1090,6 +1090,7 @@ nvim_get_mark({name})                                        *nvim_get_mark()*
 
                 Parameters: ~
                     {name}  Mark name
+                    {opts}  Optional parameters. Reserved for future use.
 
                 Return: ~
                     4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if
@@ -2420,7 +2421,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement})
                     {replacement}      Array of lines to use as replacement
 
                                                          *nvim_buf_set_mark()*
-nvim_buf_set_mark({buffer}, {name}, {line}, {col})
+nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts})
                 Sets a named mark in the given buffer, all marks are allowed
                 file/uppercase, visual, last change, etc. See |mark-motions|.
 
@@ -2434,6 +2435,7 @@ nvim_buf_set_mark({buffer}, {name}, {line}, {col})
                     {name}    Mark name
                     {line}    Line number
                     {col}     Column/row number
+                    {opts}    Optional parameters. Reserved for future use.
 
                 Return: ~
                     true if the mark was set, else false.

src/nvim/api/buffer.c

@@ -1161,10 +1161,12 @@ Boolean nvim_buf_del_mark(Buffer buffer, String name, Error *err)
 /// @param name       Mark name
 /// @param line       Line number
 /// @param col        Column/row number
+/// @param opts       Optional parameters. Reserved for future use.
 /// @return true if the mark was set, else false.
 /// @see |nvim_buf_del_mark()|
 /// @see |nvim_buf_get_mark()|
-Boolean nvim_buf_set_mark(Buffer buffer, String name, Integer line, Integer col, Error *err)
+Boolean nvim_buf_set_mark(Buffer buffer, String name, Integer line, Integer col, Dictionary opts,
+                          Error *err)
   FUNC_API_SINCE(8)
 {
   bool res = false;

src/nvim/api/vim.c

@@ -2013,11 +2013,12 @@ Boolean nvim_del_mark(String name, Error *err)
 ///
 /// @note fails with error if a lowercase or buffer local named mark is used.
 /// @param name       Mark name
+/// @param opts       Optional parameters. Reserved for future use.
 /// @return 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is
 /// not set.
 /// @see |nvim_buf_set_mark()|
 /// @see |nvim_del_mark()|
-Array nvim_get_mark(String name, Error *err)
+Array nvim_get_mark(String name, Dictionary opts, Error *err)
   FUNC_API_SINCE(8)
 {
   Array rv = ARRAY_DICT_INIT;

test/functional/api/buffer_spec.lua

@@ -711,46 +711,46 @@ describe('api/buf', function()
   describe('nvim_buf_set_mark', function()
     it('works with buffer local marks', function()
       curbufmeths.set_lines(-1, -1, true, {'a', 'bit of', 'text'})
-      eq(true, curbufmeths.set_mark('z', 1, 1))
+      eq(true, curbufmeths.set_mark('z', 1, 1, {}))
       eq({1, 1}, curbufmeths.get_mark('z'))
     end)
     it('works with file/uppercase marks', function()
       curbufmeths.set_lines(-1, -1, true, {'a', 'bit of', 'text'})
-      eq(true, curbufmeths.set_mark('Z', 3, 1))
+      eq(true, curbufmeths.set_mark('Z', 3, 1, {}))
       eq({3, 1}, curbufmeths.get_mark('Z'))
     end)
     it('fails when invalid marks names are used', function()
-      eq(false, pcall(curbufmeths.set_mark, '!', 1, 0))
+      eq(false, pcall(curbufmeths.set_mark, '!', 1, 0, {}))
-      eq(false, pcall(curbufmeths.set_mark, 'fail', 1, 0))
+      eq(false, pcall(curbufmeths.set_mark, 'fail', 1, 0, {}))
     end)
     it('fails when invalid buffer number is used', function()
-      eq(false, pcall(meths.buf_set_mark, 99, 'a', 1, 1))
+      eq(false, pcall(meths.buf_set_mark, 99, 'a', 1, 1, {}))
     end)
   end)
 
   describe('nvim_buf_del_mark', function()
     it('works with buffer local marks', function()
       curbufmeths.set_lines(-1, -1, true, {'a', 'bit of', 'text'})
-      curbufmeths.set_mark('z', 3, 1)
+      curbufmeths.set_mark('z', 3, 1, {})
       eq(true, curbufmeths.del_mark('z'))
       eq({0, 0}, curbufmeths.get_mark('z'))
     end)
     it('works with file/uppercase marks', function()
       curbufmeths.set_lines(-1, -1, true, {'a', 'bit of', 'text'})
-      curbufmeths.set_mark('Z', 3, 3)
+      curbufmeths.set_mark('Z', 3, 3, {})
       eq(true, curbufmeths.del_mark('Z'))
       eq({0, 0}, curbufmeths.get_mark('Z'))
     end)
     it('returns false in marks not set in this buffer', function()
       local abuf = meths.create_buf(false,true)
       bufmeths.set_lines(abuf, -1, -1, true, {'a', 'bit of', 'text'})
-      bufmeths.set_mark(abuf, 'A', 2, 2)
+      bufmeths.set_mark(abuf, 'A', 2, 2, {})
       eq(false, curbufmeths.del_mark('A'))
       eq({2, 2}, bufmeths.get_mark(abuf, 'A'))
     end)
     it('returns false if mark was not deleted', function()
       curbufmeths.set_lines(-1, -1, true, {'a', 'bit of', 'text'})
-      curbufmeths.set_mark('z', 3, 1)
+      curbufmeths.set_mark('z', 3, 1, {})
       eq(true, curbufmeths.del_mark('z'))
       eq(false, curbufmeths.del_mark('z'))  -- Mark was already deleted
     end)

test/functional/api/vim_spec.lua

@@ -2389,7 +2389,7 @@ describe('API', function()
     it('works', function()
       local buf = meths.create_buf(false,true)
       meths.buf_set_lines(buf, -1, -1, true, {'a', 'bit of', 'text'})
-      eq(true, meths.buf_set_mark(buf, 'F', 2, 2))
+      eq(true, meths.buf_set_mark(buf, 'F', 2, 2, {}))
       eq(true, meths.del_mark('F'))
       eq({0, 0}, meths.buf_get_mark(buf, 'F'))
     end)
@@ -2403,9 +2403,9 @@ describe('API', function()
     it('works', function()
       local buf = meths.create_buf(false,true)
       meths.buf_set_lines(buf, -1, -1, true, {'a', 'bit of', 'text'})
-      meths.buf_set_mark(buf, 'F', 2, 2)
+      meths.buf_set_mark(buf, 'F', 2, 2, {})
       meths.buf_set_name(buf, "mybuf")
-      local mark = meths.get_mark('F')
+      local mark = meths.get_mark('F', {})
       -- Compare the path tail ony
       assert(string.find(mark[4], "mybuf$"))
       eq({2, 2, buf.id, mark[4]}, mark)
@@ -2417,7 +2417,7 @@ describe('API', function()
     end)
     it('returns the expected when mark is not set', function()
       eq(true, meths.del_mark('A'))
-      eq({0, 0, 0, ''}, meths.get_mark('A'))
+      eq({0, 0, 0, ''}, meths.get_mark('A', {}))
     end)
     it('works with deleted buffers', function()
       local fname = tmpname()
@@ -2425,12 +2425,12 @@ describe('API', function()
       nvim("command", "edit " .. fname)
       local buf = meths.get_current_buf()
 
-      meths.buf_set_mark(buf, 'F', 2, 2)
+      meths.buf_set_mark(buf, 'F', 2, 2, {})
       nvim("command", "new") -- Create new buf to avoid :bd failing
       nvim("command", "bd! " .. buf.id)
       os.remove(fname)
 
-      local mark = meths.get_mark('F')
+      local mark = meths.get_mark('F', {})
       -- To avoid comparing relative vs absolute path
       local mfname = mark[4]
       local tail_patt = [[[\/][^\/]*$]]