Skip to content

Commit

Permalink
Breaking change: v1.0.0.
Browse files Browse the repository at this point in the history 
Changes are too numerous to list here.
Sorry if your configuration broke (or didn't break)!
Please file a bug if things are not working.

Please take a look at the README or `:h nvim-lightbulb` for the latest
configuration and setup steps.
  • Loading branch information
@kosayoda
kosayoda committed Jul 8, 2023
1 parent ca5b44a commit 02aacd9
Show file tree
Hide file tree
Showing 6 changed files with 771 additions and 350 deletions.
2 changes: 2 additions & 0 deletions .stylua.toml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
indent_type = "Spaces"
indent_width = 2
277 changes: 156 additions & 121 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,169 +2,204 @@

VSCode 💡 for neovim's built-in LSP.

![](https://s2.gifyu.com/images/nvim-lightbulb.gif)

> Code Action selection window shown in the gif is [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
## Table of contents

## Introduction/Rationale
- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)

## Introduction
The plugin shows a lightbulb in the sign column whenever a `textDocument/codeAction` is available at the current cursor position.

This makes code actions both [discoverable and efficient](https://rust-analyzer.github.io/blog/2020/09/28/how-to-make-a-light-bulb.html#the-mighty), as code actions can be available even when there are no visible diagnostics (warning, information, hints etc.).

## Getting Started
### Features

<img width="450" alt="nvim-lightbulb" src="https://github.com/kosayoda/nvim-lightbulb/assets/41782385/f29d9c64-592f-4163-a7cc-d1494e72f020">

> In the screenshot, colorscheme is [catppuccin](https://github.com/catppuccin/nvim), font is [iosevka](https://typeof.net/Iosevka/), programming language is [rust](https://www.rust-lang.org/)
When there is a *code action* available at the current cursor location, show a lightbulb...
1. in the **sign column**
2. as **virtual text**
3. in a **floating window**

or, change the look of

4. the **number column**
5. the **current line**

or, get a configured message

6. as **status text**, retrievable with `require("nvim_lightbulb").get_status_text()`

## Prerequisites

### Prerequisites
- [neovim](https://github.com/neovim/neovim) with LSP capabilities.
- The [FixCursorHold.nvim plugin](https://github.com/antoinemadec/FixCursorHold.nvim) is strongly recommended to work around existing Neovim issues surrounding the `CursorHold` and `CursorHoldI` autocmd events.
* Neovim v0.8.0 and above. Older versions may work but are not tested.
* Working LSP server configuration.

## Installation

### Installation
Just like any other plugin.

Example using [vim-plug](https://github.com/junegunn/vim-plug):
```vim
Plug 'kosayoda/nvim-lightbulb'
Plug 'antoinemadec/FixCursorHold.nvim'
Example using [lazy.nvim](https://github.com/folke/lazy.nvim):
```lua
{ 'kosayoda/nvim-lightbulb' }
```

Example using [packer.nvim](https://github.com/wbthomason/packer.nvim):
```lua
use {
'kosayoda/nvim-lightbulb',
requires = 'antoinemadec/FixCursorHold.nvim',
}
use { 'kosayoda/nvim-lightbulb' }
```

### Usage
Call `require('nvim-lightbulb').update_lightbulb()` whenever you want to show a lightbulb if a code action is available at the current cursor position. Example with an [`autocmd`](https://neovim.io/doc/user/autocmd.html) for all filetypes:

VimScript:
Example using [vim-plug](https://github.com/junegunn/vim-plug):
```vim
autocmd CursorHold,CursorHoldI * lua require('nvim-lightbulb').update_lightbulb()
Plug 'kosayoda/nvim-lightbulb'
```

Lua:
```lua
vim.cmd [[autocmd CursorHold,CursorHoldI * lua require('nvim-lightbulb').update_lightbulb()]]
```
## Usage

It is also possible to let the plugin create this autocommand for you. This can be enabled using the `setup` function:
Place this in your neovim configuration.

```lua
require('nvim-lightbulb').setup({autocmd = {enabled = true}})
require("nvim_lightbulb").setup({
autocmd = { enabled = true }
})
```

For all options, see the Configuration section.
- Configuration can be passed to `NvimLightbulb.setup`, or to `NvimLightbulb.update_lightbulb`.
- Any configuration passed to `update_lightbulb` will override the one in `setup`.
- For all options, see the [Configuration](#configuration) section.

### Configuration

##### Set defaults

Configuration can be passed to the setup function.
## Configuration

```lua
-- Showing defaults
require('nvim-lightbulb').setup({
-- LSP client names to ignore
-- Example: {"sumneko_lua", "null-ls"}
ignore = {},
local default_config = {
-- Priority of the lightbulb for all handlers except float.
priority = 10,

-- Whether or not to hide the lightbulb when the buffer is not focused.
-- Only works if configured during NvimLightbulb.setup
hide_in_unfocused_buffer = true,

-- Whether or not to link the highlight groups automatically.
-- Default highlight group links:
-- LightBulbSign -> DiagnosticSignInfo
-- LightBulbFloatWin -> DiagnosticFloatingInfo
-- LightBulbVirtualText -> DiagnosticVirtualTextInfo
-- LightBulbNumber -> DiagnosticSignInfo
-- LightBulbLine -> CursorLine
-- Only works if configured during NvimLightbulb.setup
link_highlights = true,

-- Perform full validation of configuration.
-- Available options: "auto", "always", "never"
-- "auto" only performs full validation in NvimLightbulb.setup.
-- "always" performs full validation in NvimLightbulb.update_lightbulb as well.
-- "never" disables config validation.
validate_config = "auto",

-- Code action kinds to observe.
-- To match all code actions, set to `nil`.
-- Otherwise, set to a table of kinds.
-- Example: { "quickfix", "refactor.rewrite" }
-- See: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#codeActionKind
action_kinds = nil,

-- Configuration for various handlers:
-- 1. Sign column.
sign = {
enabled = true,
-- Priority of the gutter sign
priority = 10,
-- Text to show in the sign column.
-- Must be between 1-2 characters.
text = "💡",
-- Highlight group to highlight the sign column text.
hl = "LightBulbSign",
},
float = {

-- 2. Virtual text.
virtual_text = {
enabled = false,
-- Text to show in the popup float
-- Text to show in the virt_text.
text = "💡",
-- Available keys for window options:
-- - height of floating window
-- - width of floating window
-- - wrap_at character to wrap at for computing height
-- - max_width maximal width of floating window
-- - max_height maximal height of floating window
-- - pad_left number of columns to pad contents at left
-- - pad_right number of columns to pad contents at right
-- - pad_top number of lines to pad contents at top
-- - pad_bottom number of lines to pad contents at bottom
-- - offset_x x-axis offset of the floating window
-- - offset_y y-axis offset of the floating window
-- - anchor corner of float to place at the cursor (NW, NE, SW, SE)
-- - winblend transparency of the window (0-100)
win_opts = {},
-- Position of virtual text given to |nvim_buf_set_extmark|.
-- Can be a number representing a fixed column (see `virt_text_pos`).
-- Can be a string representing a position (see `virt_text_win_col`).
pos = "eol",
-- Highlight group to highlight the virtual text.
hl = "LightBulbVirtualText",
-- How to combine other highlights with text highlight.
-- See `hl_mode` of |nvim_buf_set_extmark|.
hl_mode = "combine",
},
virtual_text = {

-- 3. Floating window.
float = {
enabled = false,
-- Text to show at virtual text
-- Text to show in the floating window.
text = "💡",
-- highlight mode to use for virtual text (replace, combine, blend), see :help nvim_buf_set_extmark() for reference
hl_mode = "replace",
-- Highlight group to highlight the floating window.
hl = "LightBulbFloatWin",
-- Window options.
-- See |vim.lsp.util.open_floating_preview| and |nvim_open_win|.
-- Note that some options may be overridden by |open_floating_preview|.
win_opts = {
focusable = false,
},
},

-- 4. Status text.
-- When enabled, will allow using |NvimLightbulb.get_status_text|
-- to retrieve the configured text.
status_text = {
enabled = false,
-- Text to provide when code actions are available
-- Text to set if a lightbulb is available.
text = "💡",
-- Text to provide when no actions are available
text_unavailable = ""
-- Text to set if a lightbulb is unavailable.
text_unavailable = "",
},
autocmd = {
enabled = false,
-- see :help autocmd-pattern
pattern = {"*"},
-- see :help autocmd-events
events = {"CursorHold", "CursorHoldI"}
}
})
```

##### Per-call configuration

You can overwrite the defaults by passing options to the `update_lightbulb` function.

VimScript:
```vim
autocmd CursorHold,CursorHoldI * lua require'nvim-lightbulb'.update_lightbulb({ ignore = {"null-ls"} })
```

Lua:
```lua
vim.cmd [[autocmd CursorHold,CursorHoldI * lua require'nvim-lightbulb'.update_lightbulb({ ignore = {"null-ls"} })]]
```

##### Modify the [lightbulb sign](https://neovim.io/doc/user/sign.html#:sign-define):

> Fill `text`, `texthl`, `linehl`, and `numhl` according to your preferences
VimScript:
```vim
call sign_define('LightBulbSign', { text = "", texthl = "", linehl="", numhl="" })
```

Lua:
```lua
vim.fn.sign_define('LightBulbSign', { text = "", texthl = "", linehl="", numhl="" })
```

##### Modify the lightbulb float window and virtual text colors
-- 5. Number column.
number = {
enabled = false,
-- Highlight group to highlight the number column if there is a lightbulb.
hl = "LightBulbNumber",
},

> Fill `ctermfg`, `ctermbg`, `guifg`, `guibg` according to your preferences
-- 6. Content line.
line = {
enabled = false,
-- Highlight group to highlight the line if there is a lightbulb.
hl = "LightBulbLine",
},

VimScript:
```vim
augroup HighlightOverride
autocmd!
au ColorScheme * highlight LightBulbFloatWin ctermfg= ctermbg= guifg= guibg=
au ColorScheme * highlight LightBulbVirtualText ctermfg= ctermbg= guifg= guibg=
augroup END
```
-- Autocmd configuration.
-- If enabled, automatically defines an autocmd to show the lightbulb.
-- If disabled, you will have to manually call |NvimLightbulb.update_lightbulb|.
-- Only works if configured during NvimLightbulb.setup
autocmd = {
-- Whether or not to enable autocmd creation.
enabled = false,
-- See |updatetime|.
-- Set to a negative value to avoid setting the updatetime.
updatetime = 200,
-- See |nvim_create_autocmd|.
events = { "CursorHold", "CursorHoldI" },
-- See |nvim_create_autocmd| and |autocmd-pattern|.
pattern = { "*" },
},

Lua:
```lua
vim.api.nvim_command('highlight LightBulbFloatWin ctermfg= ctermbg= guifg= guibg=')
vim.api.nvim_command('highlight LightBulbVirtualText ctermfg= ctermbg= guifg= guibg=')
-- Scenarios to not show a lightbulb.
ignore = {
-- LSP client names to ignore.
-- Example: {"null-ls", "lua_ls"}
clients = {},
-- Filetypes to ignore.
-- Example: {"neo-tree", "lua"}
ft = {},
},
}
```

##### Status-line text usage

With the status_text option enabled you can access the current lightbulb state
through the lua function `require('nvim-lightbulb').get_status_text()`. This
allows easy integration with multiple different status line plugins.
Loading

0 comments on commit 02aacd9

Please sign in to comment.