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.

1 files changed, 55 insertions, 0 deletions

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)