refactor(treesitter): rename "preview" => "edit" #25161

"Edit" more closely describes the generic application than "Preview", though
the buffer contents don't (yet) map to an actual file on disk.

https://github.com/neovim/neovim/pull/24703#discussion_r1321719133

6 files changed, 48 insertions, 43 deletions

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 9adc90ac21..0162a99619 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -135,7 +135,7 @@ The following new APIs and features were added.
     `vim.treesitter.language.register`.
   • The `#set!` directive now supports `injection.self` and `injection.parent` for injecting either the current node's language
     or the parent LanguageTree's language, respectively.
-  • Added `vim.treesitter.preview_query()`, for live editing of treesitter
+  • Added `vim.treesitter.query.edit()`, for live editing of treesitter
     queries.
   • Improved error messages for query parsing.
 
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index c62e210be1..64b4ca7ca2 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -676,8 +676,8 @@ inspect_tree({opts})                           *vim.treesitter.inspect_tree()*
 
     While in the window, press "a" to toggle display of anonymous nodes, "I"
     to toggle the display of the source language of each node, "o" to toggle
-    the query previewer, and press <Enter> to jump to the node under the
-    cursor in the source buffer.
+    the query editor, and press <Enter> to jump to the node under the cursor
+    in the source buffer.
 
     Can also be shown with `:InspectTree`.                      *:InspectTree*
 
@@ -730,11 +730,6 @@ node_contains({node}, {range})                *vim.treesitter.node_contains()*
     Return: ~
         (boolean) True if the {node} contains the {range}
 
-preview_query()                               *vim.treesitter.preview_query()*
-    Open a window for live editing of a treesitter query.
-
-    Can also be shown with `:PreviewQuery`.                    *:PreviewQuery*
-
 start({bufnr}, {lang})                                *vim.treesitter.start()*
     Starts treesitter highlighting for a buffer
 
@@ -858,6 +853,14 @@ add_predicate({name}, {handler}, {force})
                      meanings
       • {force}    (boolean|nil)
 
+edit()                                           *vim.treesitter.query.edit()*
+    Open a window for live editing of a treesitter query.
+
+    Can also be shown with `:EditQuery`.                          *:EditQuery*
+
+    Note that the editor opens a scratch buffer, and so queries aren't
+    persisted on disk.
+
 get({lang}, {query_name})                         *vim.treesitter.query.get()*
     Returns the runtime query {query_name} for {lang}.
 
diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua
index 169aa6c269..cc8be72670 100644
--- a/runtime/lua/vim/treesitter.lua
+++ b/runtime/lua/vim/treesitter.lua
@@ -473,7 +473,7 @@ end
 --- Open a window that displays a textual representation of the nodes in the language tree.
 ---
 --- While in the window, press "a" to toggle display of anonymous nodes, "I" to toggle the
---- display of the source language of each node, "o" to toggle the query previewer, and press
+--- display of the source language of each node, "o" to toggle the query editor, and press
 --- <Enter> to jump to the node under the cursor in the source buffer.
 ---
 --- Can also be shown with `:InspectTree`. *:InspectTree*
@@ -495,13 +495,6 @@ function M.inspect_tree(opts)
   require('vim.treesitter.dev').inspect_tree(opts)
 end
 
---- Open a window for live editing of a treesitter query.
----
---- Can also be shown with `:PreviewQuery`. *:PreviewQuery*
-function M.preview_query()
-  require('vim.treesitter.dev').preview_query()
-end
-
 --- Returns the fold level for {lnum} in the current buffer. Can be set directly to 'foldexpr':
 ---
 --- ```lua
diff --git a/runtime/lua/vim/treesitter/dev.lua b/runtime/lua/vim/treesitter/dev.lua
index e7af259d28..bc54853103 100644
--- a/runtime/lua/vim/treesitter/dev.lua
+++ b/runtime/lua/vim/treesitter/dev.lua
@@ -351,11 +351,11 @@ function M.inspect_tree(opts)
     end,
   })
   api.nvim_buf_set_keymap(b, 'n', 'o', '', {
-    desc = 'Toggle query previewer',
+    desc = 'Toggle query editor',
     callback = function()
-      local preview_w = vim.b[buf].dev_preview
-      if not preview_w or not close_win(preview_w) then
-        M.preview_query()
+      local edit_w = vim.b[buf].dev_edit
+      if not edit_w or not close_win(edit_w) then
+        M.edit_query()
       end
     end,
   })
@@ -464,16 +464,16 @@ function M.inspect_tree(opts)
   })
 end
 
-local preview_ns = api.nvim_create_namespace('treesitter/dev-preview')
+local edit_ns = api.nvim_create_namespace('treesitter/dev-edit')
 
 ---@param query_win integer
 ---@param base_win integer
-local function update_preview_highlights(query_win, base_win)
+local function update_editor_highlights(query_win, base_win)
   local base_buf = api.nvim_win_get_buf(base_win)
   local query_buf = api.nvim_win_get_buf(query_win)
   local parser = vim.treesitter.get_parser(base_buf)
   local lang = parser:lang()
-  api.nvim_buf_clear_namespace(base_buf, preview_ns, 0, -1)
+  api.nvim_buf_clear_namespace(base_buf, edit_ns, 0, -1)
   local query_content = table.concat(api.nvim_buf_get_lines(query_buf, 0, -1, false), '\n')
 
   local ok_query, query = pcall(vim.treesitter.query.parse, lang, query_content)
@@ -493,7 +493,7 @@ local function update_preview_highlights(query_win, base_win)
     local capture_name = query.captures[id]
     if capture_name == cursor_word then
       local lnum, col, end_lnum, end_col = node:range()
-      api.nvim_buf_set_extmark(base_buf, preview_ns, lnum, col, {
+      api.nvim_buf_set_extmark(base_buf, edit_ns, lnum, col, {
         end_row = end_lnum,
         end_col = end_col,
         hl_group = 'Visual',
@@ -506,17 +506,17 @@ local function update_preview_highlights(query_win, base_win)
 end
 
 --- @private
-function M.preview_query()
+function M.edit_query()
   local buf = api.nvim_get_current_buf()
   local win = api.nvim_get_current_win()
 
-  -- Close any existing previewer window
-  if vim.b[buf].dev_preview then
-    close_win(vim.b[buf].dev_preview)
+  -- Close any existing editor window
+  if vim.b[buf].dev_edit then
+    close_win(vim.b[buf].dev_edit)
   end
 
   local cmd = '60vnew'
-  -- If the inspector is open, place the previewer above it.
+  -- If the inspector is open, place the editor above it.
   local base_win = vim.b[buf].dev_base ---@type integer?
   local base_buf = base_win and api.nvim_win_get_buf(base_win)
   local inspect_win = base_buf and vim.b[base_buf].dev_inspect
@@ -537,20 +537,20 @@ function M.preview_query()
   local query_win = api.nvim_get_current_win()
   local query_buf = api.nvim_win_get_buf(query_win)
 
-  vim.b[buf].dev_preview = query_win
+  vim.b[buf].dev_edit = query_win
   vim.bo[query_buf].omnifunc = 'v:lua.vim.treesitter.query.omnifunc'
   set_dev_properties(query_win, query_buf)
 
   -- Note that omnifunc guesses the language based on the containing folder,
   -- so we add the parser's language to the buffer's name so that omnifunc
   -- can infer the language later.
-  api.nvim_buf_set_name(query_buf, string.format('%s/query_previewer.scm', lang))
+  api.nvim_buf_set_name(query_buf, string.format('%s/query_editor.scm', lang))
 
-  local group = api.nvim_create_augroup('treesitter/dev-preview', {})
+  local group = api.nvim_create_augroup('treesitter/dev-edit', {})
   api.nvim_create_autocmd({ 'TextChanged', 'InsertLeave' }, {
     group = group,
     buffer = query_buf,
-    desc = 'Update query previewer diagnostics when the query changes',
+    desc = 'Update query editor diagnostics when the query changes',
     callback = function()
       vim.treesitter.query.lint(query_buf, { langs = lang, clear = false })
     end,
@@ -558,37 +558,37 @@ function M.preview_query()
   api.nvim_create_autocmd({ 'TextChanged', 'InsertLeave', 'CursorMoved', 'BufEnter' }, {
     group = group,
     buffer = query_buf,
-    desc = 'Update query previewer highlights when the cursor moves',
+    desc = 'Update query editor highlights when the cursor moves',
     callback = function()
       if api.nvim_win_is_valid(win) then
-        update_preview_highlights(query_win, win)
+        update_editor_highlights(query_win, win)
       end
     end,
   })
   api.nvim_create_autocmd('BufLeave', {
     group = group,
     buffer = query_buf,
-    desc = 'Clear the query previewer highlights when leaving the previewer',
+    desc = 'Clear highlights when leaving the query editor',
     callback = function()
-      api.nvim_buf_clear_namespace(buf, preview_ns, 0, -1)
+      api.nvim_buf_clear_namespace(buf, edit_ns, 0, -1)
     end,
   })
   api.nvim_create_autocmd('BufLeave', {
     group = group,
     buffer = buf,
-    desc = 'Clear the query previewer highlights when leaving the source buffer',
+    desc = 'Clear the query editor highlights when leaving the source buffer',
     callback = function()
       if not api.nvim_buf_is_loaded(query_buf) then
         return true
       end
 
-      api.nvim_buf_clear_namespace(query_buf, preview_ns, 0, -1)
+      api.nvim_buf_clear_namespace(query_buf, edit_ns, 0, -1)
     end,
   })
   api.nvim_create_autocmd('BufHidden', {
     group = group,
     buffer = buf,
-    desc = 'Close the previewer window when the source buffer is hidden',
+    desc = 'Close the editor window when the source buffer is hidden',
     once = true,
     callback = function()
       close_win(query_win)
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 350ccba7e4..d7973cc48f 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -835,4 +835,13 @@ function M.omnifunc(findstart, base)
   return require('vim.treesitter._query_linter').omnifunc(findstart, base)
 end
 
+--- Open a window for live editing of a treesitter query.
+---
+--- Can also be shown with `:EditQuery`. *:EditQuery*
+---
+--- Note that the editor opens a scratch buffer, and so queries aren't persisted on disk.
+function M.edit()
+  require('vim.treesitter.dev').edit_query()
+end
+
 return M
diff --git a/runtime/plugin/nvim.lua b/runtime/plugin/nvim.lua
index 2ddccfcff6..13a54a5e20 100644
--- a/runtime/plugin/nvim.lua
+++ b/runtime/plugin/nvim.lua
@@ -19,6 +19,6 @@ vim.api.nvim_create_user_command('InspectTree', function(cmd)
   end
 end, { desc = 'Inspect treesitter language tree for buffer', count = true })
 
-vim.api.nvim_create_user_command('PreviewQuery', function()
-  vim.treesitter.preview_query()
-end, { desc = 'Preview treesitter query' })
+vim.api.nvim_create_user_command('EditQuery', function()
+  vim.treesitter.query.edit()
+end, { desc = 'Edit treesitter query' })