feat: `vim.inspect_pos()`, `vim.show_pos()` and `:Inspect` #21393

folke · 2022-12-12T22:56:47Z

This PR adds vim.inspect_pos(), vim.show_pos() and :Inspect to get/show the items at a given buffer position.

This PR includes 2e328ba vim.semantic_tokens.get_at_pos

Right now, the function uses nvim_echo, but I can change it to use a floating window if that would be better suited.

Todo

add special handling for semantic token types and modifiers. Would be great if feat(lsp): utility functions for getting and showing tokens #21373 could be re-opened and merged to implement this
put the nvim_create_user_command somewhere. What would be the best place for this? _editor.lua? plugin/inspector.lua?
improve the docs on the return values
add something to news.txt

Included Items

Treesitter captures
Semantic Tokens
Syntax Highlight Groups
Extmarks

Implementation details

The implementation resides in runtime/lua/vim/_inspector.lua
The submodule is lazy-loaded inside _init_packages.lua, so there's no impact on performance
If you want to test, make sure to build Neovim so the lazy-loading is included
any parameter can be nil, meaning the position under the cursor

User Commands

:Inspect is the same as vim.show_pos()
:Inspect! is the same as vim.pretty_print(vim.inspect_pos())

`vim.show_pos(bufnr, row, col, filter)`

`vim.inspect_pos(bufnr, row, col, filter)`

{
  extmarks = { {
      col = 6,
      id = 190,
      ns = "illuminate.highlight",
      ns_id = 30,
      opts = {
        end_col = 7,
        end_right_gravity = false,
        end_row = 4,
        hl_eol = false,
        hl_group = "IlluminatedWordWrite",
        hl_group_link = "IlluminatedWordWrite",
        priority = 1000,
        right_gravity = true
      },
      row = 4
    } },
  semantic_tokens = { {
      client_id = 1,
      end_col = 7,
      extmark_added = true,
      hl_groups = {
        modifiers = { {
            hl_group = "@declaration",
            hl_group_link = "@variable"
          } },
        type = {
          hl_group = "@variable",
          hl_group_link = "@variable"
        }
      },
      line = 4,
      modifiers = { "declaration" },
      start_col = 6,
      type = "variable"
    } },
  syntax = {},
  treesitter = { {
      capture = "variable",
      hl_group = "@variable",
      hl_group_link = "@variable",
      lang = "lua",
      metadata = {}
    }, {
      capture = "constant",
      hl_group = "@constant",
      hl_group_link = "Constant",
      lang = "lua",
      metadata = {}
    } }
}

jdrouhard · 2022-12-13T00:20:12Z

Could it display them in ascending order of priority? That would be pretty neat! Could easily visualize which highlights override others.

justinmk

Looks very useful! However I'm thinking this is a bigger bucket than "highlights". I see two problems being solved here:

we want a way to "give me all the things at this position"
- I propose this lives at vim.get_at_pos(pos, filter) which returns a dict of all the various things that may decorate a buffer position. (virtual text? decorations? etc.)
  - doesn't need to implement everything initially, we can add more later.
  - (future?) filter arg could be similar to that of vim.lsp.get_active_clients()
display the result in a nice way
- Not sure what to do with this. Perhaps we should start with just a command, like :Inspect (could also claim zS, in analogy to scriptease)
  - If it's meant to be interactive, not programmatically used, shouldn't it be a command?
- The idea is, we want to have this useful thing, ~~but I'm not sure we want a bunch of foo.show_x everywhere with randomly different behavior. At least, not yet?~~ Edit:
  - vim.inspect_pos()
  - vim.show_pos()

runtime/lua/vim/highlight.lua

clason · 2022-12-13T05:11:10Z

Just a note: It'd be good to distinguish here between LSP semantic token type and token modifiers. (The exact source of these highlights is important information.)

folke · 2022-12-13T06:30:22Z

For (2) it could be useful to also expose the functionality as a function where the caller can specify the (buf, row, col) and possible filter. The :Inspect command would then use the defaults.

folke · 2022-12-13T06:31:02Z

Just a note: It'd be good to distinguish here between LSP semantic token type and token modifiers. (The exact source of these highlights is important information.)

yes, for sure! Haven't looked closely yet at the new Semantic Tokens API. Will look into it and add the changes

folke · 2022-12-13T06:33:26Z

@justinmk where do you propose to add vim.get_at_pos and vim.show_at_pos? Also the nvim_create_user_command for :Inspect. I mean code wise. _editor.lua, inspect.lua, or in a separate file like inspector.lua, debug.lua?

max397574 · 2022-12-13T17:19:31Z

not sure
but wouldn't it make sense to make the columns 1-indexed?
so it would work with the functions listed under :h api-indexing (most notably nvim_win_get_cursor)
edit:
"work with" in the sense of not having to add a - 1 all the time

folke · 2022-12-13T17:21:27Z

@max397574 wasn't sure what the concensus is right now. Maybe @justinmk can chime in on this?

justinmk · 2022-12-13T21:55:00Z

put the nvim_create_user_command somewhere. What would be the best place for this? _editor.lua? plugin/inspector.lua?

I suggest runtime/plugin/nvim.lua for now.

wouldn't it make sense to make the columns 1-indexed? so it would work with the functions listed under :h api-indexing (most notably nvim_win_get_cursor)

confused by the question because :h api-index mentions that nvim_win_get_cursor uses mark-like indexing (1-indexed row, 0-indexed col). (Not sure why nvim_win_get_cursor does that, because typically editor functions like getcurpos() are (1,1)-indexed).

clason · 2022-12-13T22:08:41Z

I don't think it's necessary to duplicate the semantic tokens under the extmarks category. Modifiers should also have the leading @ (since that's the highlight name).

folke · 2022-12-13T22:36:40Z

@clason wasn't sure about the extmarks. Might make sense to include them there too, since they are effectively extmarks, but that's indeed duplication. Treesitter is different since those extmarks are ephemeral, so they are not visible as an extmark. But you're right. Will exclude the semantic token ones.

I still haven't fully looked into the semantic tokens. Can a modifier be used as a hl group on its own? Or is it always in combination with the token type? Like @variable.declaration?

folke · 2022-12-13T22:39:45Z

@justinmk api indexing is normally 0-0 based, but some functions are indeed 1-0 mark based. Editor vim.fn functions are 1-1 based.

Currently I used 0-0 api indexing, because i thought that's what all the new things use but i might be wrong.

Treesitter, semantic tokens etc all use api indexing as well, so 0-0 based.

@clason what do you think?

jdrouhard · 2022-12-13T22:41:36Z

@clason what do you think? What indexing do the treesitter and semantic token APIs use?

Semantic tokens API is 0-0 based

jdrouhard · 2022-12-13T22:43:39Z

I still haven't fully looked into the semantic tokens. Can a modifier be used as a hl group on its own? Or is it always in combination with the token type? Like @variable.declaration?

Currently they are added as their own highlight group, but eventually we’ll be updating the way they work to somehow allow combinations of types with modifiers (potentially like @variable.declaration), but that is not currently part of the functionality.

runtime/lua/vim/_inspector.lua

folke · 2022-12-17T12:02:53Z

@clason updated!

runtime/lua/vim/_inspector.lua

clason · 2022-12-17T12:42:53Z

I wants it, I merges it -- further changes can be made in the follow-up PR.

Noice job, @folke!

folke · 2022-12-17T13:17:45Z

@clason awesome, thanks!

Dich0tomy · 2022-12-18T14:33:56Z

Neat stuff. But aren't core commands supposed to start with a small letter? :inspect(!) instead of :Inspect(!)?

clason · 2022-12-18T14:39:57Z

Yes, but this is not a core command. It's provided by a (bundled) runtime plugin, same as :Man.

justinmk · 2023-01-02T00:50:56Z

Inspect might be a good addition to the default mouse right-click menu.

zeertzjq · 2023-01-03T11:52:31Z

Inspect might be a good addition to the default mouse right-click menu.

:Inspect is created by runtime/plugin/nvim.lua, which is loaded after user config, and is not loaded with nvim -u NONE. If the menu item is added as a default menu item it may cause errors with nvim -u NONE, but if the menu item is also created by runtime/plugin/nvim.lua the user cannot remove it in their config like other default menu items.

vlada-dudr · 2023-01-06T19:37:01Z

I was curious what happens if I do set ve=all and try to :Inspect virtual text. Sadly nothing. Wouldn't it be nice addition?

github-actions bot added the lua stdlib label Dec 12, 2022

folke changed the title ~~feat: added vim.highlight.show~~ feat: vim.highlight.show shows the highlights under the cursor Dec 12, 2022

justinmk reviewed Dec 13, 2022

View reviewed changes

runtime/lua/vim/highlight.lua Outdated Show resolved Hide resolved

runtime/lua/vim/highlight.lua Outdated Show resolved Hide resolved

runtime/lua/vim/highlight.lua Outdated Show resolved Hide resolved

jdrouhard mentioned this pull request Dec 13, 2022

feat(lsp): utility functions for getting and showing tokens #21373

Closed

folke force-pushed the highlight_show branch 3 times, most recently from ad15e88 to 543d53b Compare December 13, 2022 17:15

folke changed the title ~~feat: vim.highlight.show shows the highlights under the cursor~~ feat: vim.inspector to get/show items at a given buffer position Dec 13, 2022

folke force-pushed the highlight_show branch 2 times, most recently from a5f6b82 to ccefbd3 Compare December 13, 2022 17:36

feat(lsp): add function to get semantic tokens at cursor

04da043

folke force-pushed the highlight_show branch 5 times, most recently from 4ade9ca to fbbb847 Compare December 13, 2022 20:50

folke requested a review from justinmk December 13, 2022 21:02

folke force-pushed the highlight_show branch 6 times, most recently from b06d0fc to 120ecd6 Compare December 17, 2022 11:26

clason reviewed Dec 17, 2022

View reviewed changes

runtime/lua/vim/_inspector.lua Outdated Show resolved Hide resolved

runtime/lua/vim/_inspector.lua Outdated Show resolved Hide resolved

folke force-pushed the highlight_show branch from 120ecd6 to 1f9cf56 Compare December 17, 2022 12:02

clason reviewed Dec 17, 2022

View reviewed changes

runtime/lua/vim/_inspector.lua Outdated Show resolved Hide resolved

runtime/lua/vim/_inspector.lua Outdated Show resolved Hide resolved

runtime/lua/vim/_inspector.lua Outdated Show resolved Hide resolved

feat: vim.inspect_pos, vim.show_pos, :Inspect

ef91146

folke force-pushed the highlight_show branch from 1f9cf56 to ef91146 Compare December 17, 2022 12:05

clason merged commit 1c47949 into neovim:master Dec 17, 2022

dundargoc removed the request for review from justinmk December 17, 2022 12:44

folke mentioned this pull request Dec 18, 2022

feat: add support for LSP semantic tokens nvim-treesitter/playground#57

Closed

augustocdias mentioned this pull request Dec 21, 2022

Colors changed after Neovim update catppuccin/nvim#367

Closed

olimorris mentioned this pull request Dec 29, 2022

[Enhancement] Add support for semantic token highlighting. olimorris/onedarkpro.nvim#138

Closed

jemag mentioned this pull request Jan 1, 2023

Support semantic tokens explicitly Shatur/neovim-ayu#26

Closed

rewhile mentioned this pull request Jan 21, 2023

Provide a way to query which highlights are being used at buffer position nvim-treesitter/nvim-treesitter#1228

Closed

wookayin mentioned this pull request Mar 20, 2023

Cannot get ungrouped extmarks using API or vim.inspect_pos() #22732

Closed

This comment was marked as outdated.

Sign in to view

neovim deleted a comment from Cloudef Aug 1, 2023

neovim locked as resolved and limited conversation to collaborators Aug 1, 2023

Uh oh!

feat: vim.inspect_pos(), vim.show_pos() and :Inspect #21393

feat: vim.inspect_pos(), vim.show_pos() and :Inspect #21393

Uh oh!

Conversation

folke commented Dec 12, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Todo

Included Items

Implementation details

User Commands

vim.show_pos(bufnr, row, col, filter)

vim.inspect_pos(bufnr, row, col, filter)

Uh oh!

jdrouhard commented Dec 13, 2022

Uh oh!

justinmk left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

clason commented Dec 13, 2022

Uh oh!

folke commented Dec 13, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

folke commented Dec 13, 2022

Uh oh!

folke commented Dec 13, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

max397574 commented Dec 13, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

folke commented Dec 13, 2022

Uh oh!

justinmk commented Dec 13, 2022

Uh oh!

clason commented Dec 13, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

folke commented Dec 13, 2022

Uh oh!

folke commented Dec 13, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdrouhard commented Dec 13, 2022

Uh oh!

jdrouhard commented Dec 13, 2022

Uh oh!

Uh oh!

Uh oh!

folke commented Dec 17, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

clason commented Dec 17, 2022

Uh oh!

folke commented Dec 17, 2022

Uh oh!

Dich0tomy commented Dec 18, 2022

Uh oh!

clason commented Dec 18, 2022

Uh oh!

justinmk commented Jan 2, 2023

Uh oh!

zeertzjq commented Jan 3, 2023

Uh oh!

vlada-dudr commented Jan 6, 2023

Uh oh!

This comment was marked as outdated.

Uh oh!

feat: `vim.inspect_pos()`, `vim.show_pos()` and `:Inspect` #21393

feat: `vim.inspect_pos()`, `vim.show_pos()` and `:Inspect` #21393

folke commented Dec 12, 2022 •

edited

Loading

`vim.show_pos(bufnr, row, col, filter)`

`vim.inspect_pos(bufnr, row, col, filter)`

justinmk left a comment •

edited

Loading

folke commented Dec 13, 2022 •

edited

Loading

folke commented Dec 13, 2022 •

edited

Loading

max397574 commented Dec 13, 2022 •

edited

Loading

clason commented Dec 13, 2022 •

edited

Loading

folke commented Dec 13, 2022 •

edited

Loading