navic.txt

*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: