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/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)