From c48b1421af28d0317c807bca00c7e2fff97d9ad0 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 6 Jun 2023 08:23:20 -0700 Subject: [PATCH] refactor!: rename "playground" => "dev" #23919 Problem: "playground" is new jargon that overlaps with existing concepts: "dev" (`:help dev`) and "view" (also "scratch" `:help scratch-buffer`) . Solution: We should consistently use "dev" as the namespace for where "developer tools" live. For purposes of a "throwaway sandbox object", we can use the name "view". - Rename `TSPlayground` => `TSView` - Rename `playground.lua` => `dev.lua` --- runtime/doc/news.txt | 2 + runtime/doc/treesitter.txt | 8 ---- runtime/lua/vim/treesitter.lua | 2 +- .../treesitter/{playground.lua => dev.lua} | 44 ++++++++++--------- scripts/gen_vimdoc.py | 2 +- 5 files changed, 27 insertions(+), 31 deletions(-) rename runtime/lua/vim/treesitter/{playground.lua => dev.lua} (93%) diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 0182605b1b..537a737dc8 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -36,6 +36,8 @@ The following changes may require adaptations in user config or plugins. • |LspRequest| autocmd was promoted from a |User| autocmd to a first class citizen. +• Renamed `vim.treesitter.playground` to `vim.treesitter.dev`. + ============================================================================== ADDED FEATURES *news-added* diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 64b4730eee..28ab3ecd8e 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -1216,12 +1216,4 @@ LanguageTree:trees({self}) *LanguageTree:trees()* Parameters: ~ • {self} - -============================================================================== -Lua module: vim.treesitter.playground *lua-treesitter-playground* - -inspect_tree({opts}) *vim.treesitter.playground.inspect_tree()* - Parameters: ~ - • {opts} InspectTreeOpts - vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua index 12fbe1654f..5526c9858c 100644 --- a/runtime/lua/vim/treesitter.lua +++ b/runtime/lua/vim/treesitter.lua @@ -493,7 +493,7 @@ end --- argument and should return a string. function M.inspect_tree(opts) ---@cast opts InspectTreeOpts - require('vim.treesitter.playground').inspect_tree(opts) + require('vim.treesitter.dev').inspect_tree(opts) end --- Returns the fold level for {lnum} in the current buffer. Can be set directly to 'foldexpr': diff --git a/runtime/lua/vim/treesitter/playground.lua b/runtime/lua/vim/treesitter/dev.lua similarity index 93% rename from runtime/lua/vim/treesitter/playground.lua rename to runtime/lua/vim/treesitter/dev.lua index 8293c1bd0a..99cd147658 100644 --- a/runtime/lua/vim/treesitter/playground.lua +++ b/runtime/lua/vim/treesitter/dev.lua @@ -1,16 +1,16 @@ local api = vim.api ----@class TSPlaygroundModule +---@class TSDevModule local M = {} ----@class TSPlayground +---@class TSTreeView ---@field ns integer API namespace ---@field opts table Options table with the following keys: --- - anon (boolean): If true, display anonymous nodes --- - lang (boolean): If true, display the language alongside each node ---@field nodes TSP.Node[] ---@field named TSP.Node[] -local TSPlayground = {} +local TSTreeView = {} ---@class TSP.Node ---@field id integer Node id @@ -82,16 +82,16 @@ local function traverse(node, depth, lang, injections, tree) return tree end ---- Create a new Playground object. +--- Create a new treesitter view. --- ---@param bufnr integer Source buffer number ---@param lang string|nil Language of source buffer --- ----@return TSPlayground|nil +---@return TSTreeView|nil ---@return string|nil Error message, if any --- ---@package -function TSPlayground:new(bufnr, lang) +function TSTreeView:new(bufnr, lang) local ok, parser = pcall(vim.treesitter.get_parser, bufnr or 0, lang) if not ok then return nil, 'No parser available for the given buffer' @@ -139,7 +139,7 @@ function TSPlayground:new(bufnr, lang) return t end -local decor_ns = api.nvim_create_namespace('ts.playground') +local decor_ns = api.nvim_create_namespace('ts.dev') ---@private ---@param lnum integer @@ -154,11 +154,11 @@ local function get_range_str(lnum, col, end_lnum, end_col) return string.format('[%d:%d - %d:%d]', lnum + 1, col + 1, end_lnum + 1, end_col) end ---- Write the contents of this Playground into {bufnr}. +--- Write the contents of this View into {bufnr}. --- ---@param bufnr integer Buffer number to write into. ---@package -function TSPlayground:draw(bufnr) +function TSTreeView:draw(bufnr) vim.bo[bufnr].modifiable = true local lines = {} ---@type string[] local lang_hl_marks = {} ---@type table[] @@ -193,25 +193,25 @@ function TSPlayground:draw(bufnr) vim.bo[bufnr].modifiable = false end ---- Get node {i} from this Playground object. +--- Get node {i} from this View. --- --- The node number is dependent on whether or not anonymous nodes are displayed. --- ---@param i integer Node number to get ---@return TSP.Node ---@package -function TSPlayground:get(i) +function TSTreeView:get(i) local t = self.opts.anon and self.nodes or self.named return t[i] end ---- Iterate over all of the nodes in this Playground object. +--- Iterate over all of the nodes in this View. --- ----@return (fun(): integer, TSP.Node) Iterator over all nodes in this Playground +---@return (fun(): integer, TSP.Node) Iterator over all nodes in this View ---@return table ---@return integer ---@package -function TSPlayground:iter() +function TSTreeView:iter() return ipairs(self.opts.anon and self.nodes or self.named) end @@ -228,6 +228,8 @@ end --- function, it accepts the buffer number of the source --- buffer as its only argument and should return a string. +--- @private +--- --- @param opts InspectTreeOpts function M.inspect_tree(opts) vim.validate({ @@ -238,11 +240,11 @@ function M.inspect_tree(opts) local buf = api.nvim_get_current_buf() local win = api.nvim_get_current_win() - local pg = assert(TSPlayground:new(buf, opts.lang)) + local pg = assert(TSTreeView:new(buf, opts.lang)) - -- Close any existing playground window - if vim.b[buf].playground then - local w = vim.b[buf].playground + -- Close any existing dev window + if vim.b[buf].dev then + local w = vim.b[buf].dev if api.nvim_win_is_valid(w) then api.nvim_win_close(w, true) end @@ -261,7 +263,7 @@ function M.inspect_tree(opts) b = api.nvim_win_get_buf(w) end - vim.b[buf].playground = w + vim.b[buf].dev = w vim.wo[w].scrolloff = 5 vim.wo[w].wrap = false @@ -330,7 +332,7 @@ function M.inspect_tree(opts) end, }) - local group = api.nvim_create_augroup('treesitter/playground', {}) + local group = api.nvim_create_augroup('treesitter/dev', {}) api.nvim_create_autocmd('CursorMoved', { group = group, @@ -399,7 +401,7 @@ function M.inspect_tree(opts) return true end - pg = assert(TSPlayground:new(buf, opts.lang)) + pg = assert(TSTreeView:new(buf, opts.lang)) pg:draw(b) end, }) diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index e9209e219e..b40f8526ea 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -275,7 +275,7 @@ CONFIG = { 'query.lua', 'highlighter.lua', 'languagetree.lua', - 'playground.lua', + 'dev.lua', ], 'files': [ 'runtime/lua/vim/treesitter.lua',