340 lines
10 KiB
Plaintext
340 lines
10 KiB
Plaintext
*nvim-navic* *navic*
|
|
|
|
A simple statusline/winbar component that shows your current code context.
|
|
Named after the Indian satellite navigation system.
|
|
|
|
Requires :
|
|
- nvim-lspconfig: `https://github.com/neovim/nvim-lspconfig`
|
|
- Neovim: 0.7 or above
|
|
|
|
=============================================================================
|
|
CONTENTS *navic-components*
|
|
|
|
API |navic-api|
|
|
Usage |navic-usage|
|
|
Variables |navic-variables|
|
|
Customisation |navic-customise|
|
|
Highlights |navic-highlights|
|
|
|
|
=============================================================================
|
|
API *navic-api*
|
|
|
|
|nvim-navic| provides the following functions for the user.
|
|
|
|
*navic.setup* (opts)
|
|
Configure |nvim-navic|'s options. See more |navic-configuration|.
|
|
|
|
*navic.attach* (client, bufnr)
|
|
Used to attach |nvim-navic| to lsp server. Pass this function as
|
|
on_attach while setting up your desired lsp server.
|
|
|
|
*navic.is_available* (bufnr)
|
|
Returns boolean value indicating whether |nvim-navic| is able to provide
|
|
output for current buffer.
|
|
'bufnr' is optional argument. If bufnr is not provied, current open
|
|
buffer is used.
|
|
|
|
*navic.get_location* (opts, bufnr)
|
|
Returns a pretty string that shows code context and can be used directly
|
|
in statusline or winbar.
|
|
opts table can be passed to override any of |nvim-navic|'s options.
|
|
Follows same table format as |navic-setup|'s opts table. You can pass
|
|
|bufnr| value to determine which buffer is used to get code context. If
|
|
not provided, the current buffer will be used.
|
|
|
|
*navic.get_data* (bufnr)
|
|
Returns a table of tables representing the current code context. Contains
|
|
information about the symbol's name, kind, type, scope and its icon at
|
|
each level. Relation between type and kind is defiend on LSP's website.
|
|
`https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#symbolKind`
|
|
'bufnr' is optional argument. If bufnr is not provied, current open
|
|
buffer is used.
|
|
|
|
*navic.format_data* (data, opts)
|
|
Formats data of the type returned by |navic.get_data| for use in the
|
|
statusline or winbar. This can be used to modify the raw data before
|
|
formatting it.
|
|
|opts| table can be passed to override any of |nvim-navic|'s options.
|
|
Follows same table format as |navic-setup|'s opts table.
|
|
|
|
=============================================================================
|
|
Usage *navic-usage*
|
|
|
|
|nvim-navic| needs to be attached to lsp servers of the buffer to work. Use the
|
|
|navic.attach| function while setting up lsp servers. You can skip this step
|
|
if you have enabled auto_attach option during setup.
|
|
|
|
NOTE: You can attach to only one lsp server per buffer.
|
|
|
|
Example: >lua
|
|
require("lspconfig").clangd.setup {
|
|
on_attach = function(client, bufnr)
|
|
navic.attach(client, bufnr)
|
|
end
|
|
}
|
|
<
|
|
|
|
Next you can use |nvim-navic| in your statusline or winbar with your
|
|
favorite statusline/winbar plugins.
|
|
|
|
Example setup with lualine.nvim `https://github.com/nvim-lualine/lualine.nvim`:
|
|
>lua
|
|
local navic = require("nvim-navic")
|
|
|
|
require("lualine").setup({
|
|
sections = {
|
|
lualine_c = {
|
|
"navic",
|
|
|
|
-- Component specific options
|
|
color_correction = nil, -- Can be nil, "static" or "dynamic". This option is useful only when you have highlights enabled.
|
|
-- Many colorschemes don't define same backgroud for nvim-navic as their lualine statusline backgroud.
|
|
-- Setting it to "static" will perform a adjustment once when the component is being setup. This should
|
|
-- be enough when the lualine section isn't changing colors based on the mode.
|
|
-- Setting it to "dynamic" will keep updating the highlights according to the current modes colors for
|
|
-- the current section.
|
|
|
|
navic_opts = nil -- lua table with same format as setup's option. All options except "lsp" options take effect when set here.
|
|
}
|
|
},
|
|
-- OR in winbar
|
|
winbar = {
|
|
lualine_c = {
|
|
"navic",
|
|
color_correction = nil,
|
|
navic_opts = nil
|
|
}
|
|
}
|
|
})
|
|
|
|
-- OR a more hands on approach
|
|
require("lualine").setup({
|
|
sections = {
|
|
lualine_c = {
|
|
{
|
|
function()
|
|
return navic.get_location()
|
|
end,
|
|
cond = function()
|
|
return navic.is_available()
|
|
end
|
|
},
|
|
}
|
|
},
|
|
-- OR in winbar
|
|
winbar = {
|
|
lualine_c = {
|
|
{
|
|
function()
|
|
return navic.get_location()
|
|
end,
|
|
cond = function()
|
|
return navic.is_available()
|
|
end
|
|
},
|
|
}
|
|
}
|
|
})
|
|
<
|
|
|
|
Example setup with feline.nvim `https://github.com/feline-nvim/feline.nvim`:
|
|
|
|
Statusline: >lua
|
|
local navic = require("nvim-navic")
|
|
|
|
local components = {
|
|
active = {{}, {}, {}},
|
|
}
|
|
|
|
table.insert(components.active[1], {
|
|
provider = function()
|
|
return navic.get_location()
|
|
end,
|
|
enabled = function() return navic.is_available() end,
|
|
})
|
|
|
|
require("feline").setup({
|
|
components = components
|
|
})
|
|
<
|
|
|
|
Winbar: >lua
|
|
local navic = require("nvim-navic")
|
|
|
|
local components = {
|
|
active = {{}, {}, {}},
|
|
}
|
|
|
|
table.insert(components.active[1], {
|
|
provider = function()
|
|
return navic.get_location()
|
|
end,
|
|
enabled = function() return navic.is_available() end,
|
|
})
|
|
|
|
require("feline").winbar.setup({
|
|
components = components
|
|
})
|
|
<
|
|
|
|
You can silence warning/error messages thrown by |nvim-navic| by setting
|
|
>lua
|
|
vim.g.navic_silence = true.
|
|
<
|
|
at the start of your config. However this is not advisable, the error
|
|
messages indicate issues in your setup.
|
|
|
|
=============================================================================
|
|
Variables *navic-variables*
|
|
|
|
*vim.g.navic_silence*
|
|
Set it to true to silence the any warnings/error messages thrown by nvim-navic
|
|
|
|
*vim.b.navic_lazy_update_context*
|
|
Set it to true to update context only on CursorHold event. Could be usefull if
|
|
you are facing performance issues on large files. Example usage
|
|
>lua
|
|
vim.api.nvim_create_autocmd("BufEnter", {
|
|
callback = function()
|
|
if vim.api.nvim_buf_line_count(0) > 10000 then
|
|
vim.b.navic_lazy_update_context = true
|
|
end
|
|
end,
|
|
})
|
|
<
|
|
=============================================================================
|
|
Customisation *navic-customise*
|
|
|
|
Use |navic.setup| to override any of the default options
|
|
|
|
icons: table
|
|
Icons to show for captured symbols. Default icons assume that you
|
|
have nerd-font.
|
|
|
|
highlight: boolean
|
|
Add colors to icons and text as defined by highlight groups
|
|
NavicIcons* (NavicIconsFile, NavicIconsModule.. etc.), NavicText and
|
|
NavicSeparator.
|
|
|
|
separator: string
|
|
Icon to be used to separate two symbols.
|
|
|
|
depth_limit: integer
|
|
Maximum depth of context to be shown. If the context depth exceeds
|
|
this parameter, context information is truncated. default is infinite
|
|
|
|
depth_limit_indicator: string
|
|
Indicator signifing that displayed string is truncated.
|
|
|
|
safe_output: boolean
|
|
Sanitize the output for use in statusline and winbar.
|
|
|
|
click: boolean
|
|
Single click to goto element, double click to open nvim-navbuddy on
|
|
the clicked element.
|
|
|
|
lazy_update_context: boolean
|
|
If true, turns off context updates for the "CursorMoved" event,
|
|
updates will only happen on the "CursorHold" event. The
|
|
difference between this option and the vim.b.navic_lazy_update_context
|
|
variable is that this option turns off context updates on the
|
|
"CursorMoved" completely for all buffers, whereas the
|
|
vim.b.navic_lazy_update_context variable allows you to control that
|
|
behavior with more flexibility, like disabling context updates
|
|
depending on file size, total lines etc.
|
|
|
|
lsp :
|
|
auto_attach: boolean
|
|
Enable to have nvim-navic automatically attach to every LSP for
|
|
current buffer. Its disabled by default.
|
|
preference: table
|
|
Table ranking lsp_servers. Lower the index, higher the priority of
|
|
the server. If there are more than one server attached to a
|
|
buffer, nvim-navic will refer to this list to make a decision on
|
|
which one to use.
|
|
For example - In case a buffer is attached to clangd and ccls both
|
|
and the preference list is `{ "clangd", "pyright" }`. Then clangd
|
|
will be preferred.
|
|
|
|
Defaults >lua
|
|
navic.setup {
|
|
icons = {
|
|
File = " ",
|
|
Module = " ",
|
|
Namespace = " ",
|
|
Package = " ",
|
|
Class = " ",
|
|
Method = " ",
|
|
Property = " ",
|
|
Field = " ",
|
|
Constructor = " ",
|
|
Enum = "",
|
|
Interface = "",
|
|
Function = " ",
|
|
Variable = " ",
|
|
Constant = " ",
|
|
String = " ",
|
|
Number = " ",
|
|
Boolean = "◩ ",
|
|
Array = " ",
|
|
Object = " ",
|
|
Key = " ",
|
|
Null = " ",
|
|
EnumMember = " ",
|
|
Struct = " ",
|
|
Event = " ",
|
|
Operator = " ",
|
|
TypeParameter = " ",
|
|
},
|
|
lsp = {
|
|
auto_attach = false,
|
|
preference = nil,
|
|
},
|
|
highlight = false,
|
|
separator = " > ",
|
|
depth_limit = 0,
|
|
depth_limit_indicator = "..",
|
|
safe_output = true,
|
|
lazy_update_context = false,
|
|
click = false
|
|
}
|
|
<
|
|
|
|
=============================================================================
|
|
Highlight *navic-highlights*
|
|
|
|
|nvim-navic| provides the following highlights which get used when highlight
|
|
option is set to `true`.
|
|
|
|
`NavicIconsFile`
|
|
`NavicIconsModule`
|
|
`NavicIconsNamespace`
|
|
`NavicIconsPackage`
|
|
`NavicIconsClass`
|
|
`NavicIconsMethod`
|
|
`NavicIconsProperty`
|
|
`NavicIconsField`
|
|
`NavicIconsConstructor`
|
|
`NavicIconsEnum`
|
|
`NavicIconsInterface`
|
|
`NavicIconsFunction`
|
|
`NavicIconsVariable`
|
|
`NavicIconsConstant`
|
|
`NavicIconsString`
|
|
`NavicIconsNumber`
|
|
`NavicIconsBoolean`
|
|
`NavicIconsArray`
|
|
`NavicIconsObject`
|
|
`NavicIconsKey`
|
|
`NavicIconsNull`
|
|
`NavicIconsEnumMember`
|
|
`NavicIconsStruct`
|
|
`NavicIconsEvent`
|
|
`NavicIconsOperator`
|
|
`NavicIconsTypeParameter`
|
|
`NavicText`
|
|
`NavicSeparator`
|
|
|
|
=============================================================================
|
|
vim:tw=78:ts=4:ft=help:norl:
|