README.md

definition-or-references.nvim

Replace `vim.lsp.buf.definition` and `vim.lsp.buf.references` with single command.

⚡️ Description

This plugin implements JetBrains like definition and references handling (in JetBrains it's called declaration or usages). It combines vim.lsp.buf.definition and vim.lsp.buf.references into single command require("definition-or-references").definition_or_references. Tested with tsserver and luals

⚡️ How it works?

tldr; When you are NOT on the definition of the item, then this command puts your cursor on the definition, and when you are on the definition it shows you all the item's references.

In detail: This is exact way that this plugin works:

1. At the same time starts two lsp requests textDocument/definition and textDocument/references.
2. At first it checks textDocument/definition result and if: a) your cursor is on the definition of the item then it shows you all the item's references b) your cursor is not on the definition then it cancells textDocument/references request and moves cursor to the definition of an item
3. When handling item's references if there is only one reference it also moves your cursor to that only rerefence.

📋 Installation

Packer

use {"KostkaBrukowa/definition-or-references.nvim"}

vim-plug

Plug "KostkaBrukowa/definition-or-references.nvim"

lazy.nvim

require("lazy").setup({"KostkaBrukowa/definition-or-references.nvim"})

☄ Getting started

The way to use the plugin is to just make a keymap that calls the plugin e.g.

vim.keymap.set("n", "gd", require("definition-or-references").definition_or_references, { silent = true })

or you can add this on CTRL+click as it is in some other editors:

vim.keymap.set("n", "<C-LeftMouse>", function()
  -- Simulate click to place cursor on correct position
  vim.api.nvim_feedkeys(
    vim.api.nvim_replace_termcodes("<LeftMouse>", false, false, true),
    "in",
    false
  )

  -- defer to let nvim refresh to get correct position
  vim.defer_fn(function()
    require("definition-or-references").definition_or_references()
  end, 0)
end)

or whenever you call this keymap the logic described above will fire.

⚙ Configuration

Note: The options are also available in Neovim by calling :h definition-or-references.options

require("definition-or-references").setup({
  -- Prints useful logs about what event are triggered, and reasons actions are executed.
  debug = false,

  -- Callback that gets called just before sending first request
  before_start_callback = function() end,

  -- Callback that gets called just after opening entry and settig cursor position
  after_jump_callback = function(_) end,

  -- Callback that gets called with all of the references lsp result. You can do whatever you want
  -- with this data e.g. display it in the `telescope` window
  -- For example see Wiki pages
  on_references_result = nil,

  -- Specifies when should the notify be called (if at all)
  -- If you want to disable notify completely set it to `false`: `notify_options = false`
  notify_options = {
    errors = true,
    on_definition_no_reference = true,
    no_definition_no_reference = true,
    on_definition_one_reference = true,
    no_definition_one_reference = true,
  },
})

⌨ Contributing

PRs and issues are always welcome. Make sure to provide as much context as possible when opening one.

🗞 Wiki

You can find guides and showcase of the plugin on the Wiki

TODO

• [] - some tests