feat(api): named marks set, get, delete #15346

Adds the following API functions.

- nvim_buf_set_mark(buf, name, line, col)
  * Set marks in a buffer.
- nvim_buf_del_mark(buf, name)
  * Delete a mark that belongs to buffer.
- nvim_del_mark(name)
  * Delete a global mark.
- nvim_get_mark(name)
  * Get a global mark.

Tests:

- Adds test to all the new api functions, and adds more for the existing
  nvim_buf_get_mark.
    * Tests include failure cases.

Documentation:

- Adds documentation for all the new functions, and improves the
  existing fucntion docs.

2 files changed, 110 insertions, 0 deletions

diff --git a/test/functional/api/buffer_spec.lua b/test/functional/api/buffer_spec.lua
index 81fad206da..01fcfab543 100644
--- a/test/functional/api/buffer_spec.lua
+++ b/test/functional/api/buffer_spec.lua
@@ -707,4 +707,59 @@ describe('api/buf', function()
       eq({3, 0}, curbuf('get_mark', 'v'))
     end)
   end)
+
+  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({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({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, 'fail', 1, 0))
+    end)
+    it('fails when invalid buffer number is used', function()
+      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)
+      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)
+      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)
+      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)
+      eq(true, curbufmeths.del_mark('z'))
+      eq(false, curbufmeths.del_mark('z'))  -- Mark was already deleted
+    end)
+    it('fails when invalid marks names are used', function()
+      eq(false, pcall(curbufmeths.del_mark, '!'))
+      eq(false, pcall(curbufmeths.del_mark, 'fail'))
+    end)
+    it('fails when invalid buffer number is used', function()
+      eq(false, pcall(meths.buf_del_mark, 99, 'a'))
+    end)
+  end)
 end)
diff --git a/test/functional/api/vim_spec.lua b/test/functional/api/vim_spec.lua
index 6bcf8dd91f..6b644ed519 100644
--- a/test/functional/api/vim_spec.lua
+++ b/test/functional/api/vim_spec.lua
@@ -2267,4 +2267,59 @@ describe('API', function()
       ]]}
     end)
   end)
+
+  describe('nvim_del_mark', 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.del_mark('F'))
+      eq({0, 0}, meths.buf_get_mark(buf, 'F'))
+    end)
+    it('fails when invalid marks are used', function()
+      eq(false, pcall(meths.del_mark, 'f'))
+      eq(false, pcall(meths.del_mark, '!'))
+      eq(false, pcall(meths.del_mark, 'fail'))
+    end)
+  end)
+  describe('nvim_get_mark', 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_name(buf, "mybuf")
+      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)
+    end)
+    it('fails when invalid marks are used', function()
+      eq(false, pcall(meths.del_mark, 'f'))
+      eq(false, pcall(meths.del_mark, '!'))
+      eq(false, pcall(meths.del_mark, 'fail'))
+    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'))
+    end)
+    it('works with deleted buffers', function()
+      local fname = tmpname()
+      write_file(fname, 'a\nbit of\text')
+      nvim("command", "edit " .. fname)
+      local buf = meths.get_current_buf()
+
+      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')
+      -- To avoid comparing relative vs absolute path
+      local mfname = mark[4]
+      local tail_patt = [[[\/][^\/]*$]]
+      -- tail of paths should be equals
+      eq(fname:match(tail_patt), mfname:match(tail_patt))
+      eq({2, 2, buf.id, mark[4]}, mark)
+    end)
+  end)
 end)