Merge pull request #9289 from bfredl/nsclear

API: rename nvim_buf_clear_highlight to nvim_buf_clear_namespace

2 files changed, 74 insertions, 40 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 4559f37191..29c8ea634a 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -913,7 +913,7 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
 /// create a namespace, use |nvim_create_namespace| which returns a namespace
 /// id. Pass it in to this function as `ns_id` to add highlights to the
 /// namespace. All highlights in the same namespace can then be cleared with
-/// single call to |nvim_buf_clear_highlight|. If the highlight never will be
+/// single call to |nvim_buf_clear_namespace|. If the highlight never will be
 /// deleted by an API call, pass `ns_id = -1`.
 ///
 /// As a shorthand, `ns_id = 0` can be used to create a new namespace for the
@@ -967,23 +967,23 @@ Integer nvim_buf_add_highlight(Buffer buffer,
   return ns_id;
 }
 
-/// Clears highlights and virtual text from a given source id and range of lines
+/// Clears namespaced objects, highlights and virtual text, from a line range
 ///
-/// To clear a source group in the entire buffer, pass in 0 and -1 to
+/// To clear the namespace in the entire buffer, pass in 0 and -1 to
 /// line_start and line_end respectively.
 ///
 /// @param buffer     Buffer handle
-/// @param ns_id      Namespace to clear, or -1 to clear all.
+/// @param ns_id      Namespace to clear, or -1 to clear all namespaces.
 /// @param line_start Start of range of lines to clear
 /// @param line_end   End of range of lines to clear (exclusive) or -1 to clear
-///                   to end of file.
+///                   to end of buffer.
 /// @param[out] err   Error details, if any
-void nvim_buf_clear_highlight(Buffer buffer,
+void nvim_buf_clear_namespace(Buffer buffer,
                               Integer ns_id,
                               Integer line_start,
                               Integer line_end,
                               Error *err)
-  FUNC_API_SINCE(1)
+  FUNC_API_SINCE(5)
 {
   buf_T *buf = find_buffer_by_handle(buffer, err);
   if (!buf) {
@@ -1001,6 +1001,26 @@ void nvim_buf_clear_highlight(Buffer buffer,
   bufhl_clear_line_range(buf, (int)ns_id, (int)line_start+1, (int)line_end);
 }
 
+/// Clears highlights and virtual text from namespace and range of lines
+///
+/// @deprecated use |nvim_buf_clear_namespace|.
+///
+/// @param buffer     Buffer handle
+/// @param ns_id      Namespace to clear, or -1 to clear all.
+/// @param line_start Start of range of lines to clear
+/// @param line_end   End of range of lines to clear (exclusive) or -1 to clear
+///                   to end of file.
+/// @param[out] err   Error details, if any
+void nvim_buf_clear_highlight(Buffer buffer,
+                              Integer ns_id,
+                              Integer line_start,
+                              Integer line_end,
+                              Error *err)
+  FUNC_API_SINCE(1)
+{
+  nvim_buf_clear_namespace(buffer, ns_id, line_start, line_end, err);
+}
+
 
 /// Set the virtual text (annotation) for a buffer line.
 ///
@@ -1012,10 +1032,10 @@ void nvim_buf_clear_highlight(Buffer buffer,
 ///
 /// Namespaces are used to support batch deletion/updating of virtual text.
 /// To create a namespace, use |nvim_create_namespace|. Virtual text is
-/// cleared using |nvim_buf_clear_highlight|. The same `ns_id` can be used for
+/// cleared using |nvim_buf_clear_namespace|. The same `ns_id` can be used for
 /// both virtual text and highlights added by |nvim_buf_add_highlight|, both
-/// can then be cleared with a single call to |nvim_buf_clear_highlight|. If the
-/// virtual text never will be cleared by an API call, pass `src_id = -1`.
+/// can then be cleared with a single call to |nvim_buf_clear_namespace|. If the
+/// virtual text never will be cleared by an API call, pass `ns_id = -1`.
 ///
 /// As a shorthand, `ns_id = 0` can be used to create a new namespace for the
 /// virtual text, the allocated id is then returned.
diff --git a/test/functional/ui/bufhl_spec.lua b/test/functional/ui/bufhl_spec.lua
index 95c9427399..f0c9ea42b9 100644
--- a/test/functional/ui/bufhl_spec.lua
+++ b/test/functional/ui/bufhl_spec.lua
@@ -37,8 +37,8 @@ describe('Buffer highlighting', function()
     screen:detach()
   end)
 
-  local add_hl = curbufmeths.add_highlight
-  local clear_hl = curbufmeths.clear_highlight
+  local add_highlight = curbufmeths.add_highlight
+  local clear_namespace = curbufmeths.clear_namespace
 
   it('works', function()
     insert([[
@@ -57,8 +57,8 @@ describe('Buffer highlighting', function()
                                               |
     ]])
 
-    add_hl(-1, "String", 0 , 10, 14)
-    add_hl(-1, "Statement", 1 , 5, -1)
+    add_highlight(-1, "String", 0 , 10, 14)
+    add_highlight(-1, "Statement", 1 , 5, -1)
 
     screen:expect([[
       these are {2:some} lines                    |
@@ -83,7 +83,7 @@ describe('Buffer highlighting', function()
                                               |
     ]])
 
-    clear_hl(-1, 0, -1)
+    clear_namespace(-1, 0, -1)
     screen:expect([[
       these are some lines                    |
       ^                                        |
@@ -96,7 +96,7 @@ describe('Buffer highlighting', function()
     ]])
   end)
 
-  describe('support adding multiple sources', function()
+  describe('support using multiple namespaces', function()
     local id1, id2
     before_each(function()
       insert([[
@@ -106,21 +106,21 @@ describe('Buffer highlighting', function()
         from different sources]])
 
       command("hi ImportantWord gui=bold cterm=bold")
-      id1 = add_hl(0, "ImportantWord", 0, 2, 8)
-      add_hl(id1, "ImportantWord", 1, 12, -1)
-      add_hl(id1, "ImportantWord", 2, 0, 9)
-      add_hl(id1, "ImportantWord", 3, 5, 14)
+      id1 = add_highlight(0, "ImportantWord", 0, 2, 8)
+      add_highlight(id1, "ImportantWord", 1, 12, -1)
+      add_highlight(id1, "ImportantWord", 2, 0, 9)
+      add_highlight(id1, "ImportantWord", 3, 5, 14)
 
       -- add_highlight can be called like this to get a new source
       -- without adding any highlight
-      id2 = add_hl(0, "", 0, 0, 0)
+      id2 = add_highlight(0, "", 0, 0, 0)
       neq(id1, id2)
 
-      add_hl(id2, "Special", 0, 2, 8)
-      add_hl(id2, "Identifier", 1, 3, 8)
-      add_hl(id2, "Special", 1, 14, 20)
-      add_hl(id2, "Underlined", 2, 6, 12)
-      add_hl(id2, "Underlined", 3, 0, 9)
+      add_highlight(id2, "Special", 0, 2, 8)
+      add_highlight(id2, "Identifier", 1, 3, 8)
+      add_highlight(id2, "Special", 1, 14, 20)
+      add_highlight(id2, "Underlined", 2, 6, 12)
+      add_highlight(id2, "Underlined", 3, 0, 9)
 
       screen:expect([[
         a {5:longer} example                        |
@@ -135,7 +135,21 @@ describe('Buffer highlighting', function()
     end)
 
     it('and clearing the first added', function()
-      clear_hl(id1, 0, -1)
+      clear_namespace(id1, 0, -1)
+      screen:expect([[
+        a {4:longer} example                        |
+        in {6:order} to de{4:monstr}ate                 |
+        combin{9:ing hi}ghlights                    |
+        {9:from diff}erent source^s                  |
+        {1:~                                       }|
+        {1:~                                       }|
+        {1:~                                       }|
+                                                |
+      ]])
+    end)
+
+    it('and clearing using deprecated name', function()
+      curbufmeths.clear_highlight(id1, 0, -1)
       screen:expect([[
         a {4:longer} example                        |
         in {6:order} to de{4:monstr}ate                 |
@@ -149,7 +163,7 @@ describe('Buffer highlighting', function()
     end)
 
     it('and clearing the second added', function()
-      clear_hl(id2, 0, -1)
+      clear_namespace(id2, 0, -1)
       screen:expect([[
         a {7:longer} example                        |
         in order to {7:demonstrate}                 |
@@ -163,9 +177,9 @@ describe('Buffer highlighting', function()
     end)
 
     it('and clearing line ranges', function()
-      clear_hl(-1, 0, 1)
-      clear_hl(id1, 1, 2)
-      clear_hl(id2, 2, -1)
+      clear_namespace(-1, 0, 1)
+      clear_namespace(id1, 1, 2)
+      clear_namespace(id2, 2, -1)
       screen:expect([[
         a longer example                        |
         in {6:order} to de{4:monstr}ate                 |
@@ -208,9 +222,9 @@ describe('Buffer highlighting', function()
   it('prioritizes latest added highlight', function()
     insert([[
       three overlapping colors]])
-    add_hl(0, "Identifier", 0, 6, 17)
-    add_hl(0, "String", 0, 14, 23)
-    local id = add_hl(0, "Special", 0, 0, 9)
+    add_highlight(0, "Identifier", 0, 6, 17)
+    add_highlight(0, "String", 0, 14, 23)
+    local id = add_highlight(0, "Special", 0, 0, 9)
 
     screen:expect([[
       {4:three ove}{6:rlapp}{2:ing color}^s                |
@@ -223,7 +237,7 @@ describe('Buffer highlighting', function()
                                               |
     ]])
 
-    clear_hl(id, 0, 1)
+    clear_namespace(id, 0, 1)
     screen:expect([[
       three {6:overlapp}{2:ing color}^s                |
       {1:~                                       }|
@@ -239,8 +253,8 @@ describe('Buffer highlighting', function()
   it('works with multibyte text', function()
     insert([[
       Ta båten över sjön!]])
-    add_hl(-1, "Identifier", 0, 3, 9)
-    add_hl(-1, "String", 0, 16, 21)
+    add_highlight(-1, "Identifier", 0, 3, 9)
+    add_highlight(-1, "String", 0, 16, 21)
 
     screen:expect([[
       Ta {6:båten} över {2:sjön}^!                     |
@@ -257,7 +271,7 @@ describe('Buffer highlighting', function()
   it('works with new syntax groups', function()
     insert([[
       fancy code in a new fancy language]])
-    add_hl(-1, "FancyLangItem", 0, 0, 5)
+    add_highlight(-1, "FancyLangItem", 0, 0, 5)
     screen:expect([[
       fancy code in a new fancy languag^e      |
       {1:~                                       }|
@@ -321,7 +335,7 @@ describe('Buffer highlighting', function()
                                                 |
       ]])
 
-      clear_hl(id1, 0, -1)
+      clear_namespace(id1, 0, -1)
       screen:expect([[
         ^1 + 2                                   |
         3 +                                     |
@@ -449,7 +463,7 @@ describe('Buffer highlighting', function()
                                                 |
       ]])
 
-      clear_hl(-1, 0, -1)
+      clear_namespace(-1, 0, -1)
       screen:expect([[
         ^1 + 2{1:$}                                  |
         3 +{1:$}                                    |