*nvim-navbuddy* *navbuddy*

A simple popup display that provides breadcrumbs like navigation feature but
in keyboard centric manner inspired by ranger file manager.

Requires :
- nvim-lspconfig: `https://github.com/neovim/nvim-lspconfig`
- nvim-navic: `https://github.com/SmiteshP/nvim-navic`
- nui.nvim: `https://github.com/MunifTanjim/nui.nvim`
- Neovim: 0.8 or above

Optional requirements :
- Comment.nvim: `https://github.com/numToStr/Comment.nvim`
- telescope.nvim: `https://github.com/nvim-telescope/telescope.nvim`

=============================================================================
CONTENTS                                                     *navbuddy-components*

API                                                                 |navbuddy-api|
Usage                                                             |navbuddy-usage|
Customisation                                                 |navbuddy-customise|
Actions                                                         |navbuddy-actions|
Highlights                                                   |navbuddy-highlights|

=============================================================================
API                                                                 *navbuddy-api*

|nvim-navbuddy| provides the following functions for the user.

navbuddy.setup (opts)
	Configure |nvim-navbuddy|'s options. See more |navbuddy-customise|.

navbuddy.attach (client, bufnr)
	Used to attach |nvim-navbuddy| to lsp server. Pass this function as
	on_attach while setting up your desired lsp server. Manual attachment can
	be skiped if you have enabled auto_attach option.

navbuddy.open (bufnr)
	Opens the Navbuddy window.

=============================================================================
Usage                                                             *navbuddy-usage*

|nvim-navbuddy| needs to be attached to lsp servers of the buffer to work. Use the
|navbuddy.attach| function while setting up lsp servers. You can skip this
step if you have enabled auto_attach option during setup.

Example: >lua
	require("lspconfig").clangd.setup {
		on_attach = function(client, bufnr)
			navbuddy.attach(client, bufnr)
		end
	}
<
Then simply use command "Navbuddy" to open the window.

=============================================================================
Customisation                                                 *navbuddy-customise*

Use |navbuddy.setup| to override any of the default options

	icons: table
		Icons to show for captured symbols. Default icons assume that you
		have nerd-fonts.

	window: table
		Set options related to window's "border", "size", "position".

	node_markers: table
		Indicate whether a node is a leaf or branch node. Default icons assume
		you have nerd-fonts.

	use_default_mappings: boolean
		If set to false, only mappings set by user are set. Else default mappings
		are used for keys that are not set by user.

	mappings: table
		Actions to be triggered for specified keybindings. For each keybinding
		it takes a table of format
		{ callback = <function_to_be_called>, description = "string"}.
		The callback function takes the "display" object as an argument.

	lsp: table
		auto_attach: boolean
			Enable to have Navbuddy 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, navbuddy will refer to this list to make a decision on
			which one to use.
			example: Incase a buffer is attached to clangd and ccls both and
			the preference list is { "clangd", "pyright" }. Then clangd will
			be prefered.

	source_buffer:
		follow_node: boolean
			Move the source buffer such that focused node is visible.
		highlight: boolean
			Highlight focused node on source buffer
		reorient: string
			Reorient buffer after changing nodes. options are "smart", "top",
			"mid" or "none"

Defaults >lua

	local navbuddy = require("nvim-navbuddy")
	local actions = require("nvim-navbuddy.actions")

	navbuddy.setup {
		window = {
			border = "single",  -- "rounded", "double", "solid", "none"
								-- or an array with eight chars building up the border in a clockwise fashion
								-- starting with the top-left corner. eg: { "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" }.
			size = "60%",       -- Or table format example: { height = "40%", width = "100%"}
			position = "50%",   -- Or table format example: { row = "100%", col = "0%"}
			scrolloff = nil,    -- scrolloff value within navbuddy window
			sections = {
				left = {
					size = "20%",
					border = nil, -- You can set border style for each section individually as well.
				},
				mid = {
					size = "40%",
					border = nil,
				},
				right = {
					-- No size option for right most section. It fills to
					-- remaining area.
					border = nil,
					preview = "leaf",  -- Right section can show previews too.
									   -- Options: "leaf", "always" or "never"
				}
			}
		},
		node_markers = {
			enabled = true,
			icons = {
				leaf = "  ",
				leaf_selected = " → ",
				branch = " ",
			},
		},
		icons = {
			[1] = "󰈙 ", -- File
			[2] = " ", -- Module
			[3] = "󰌗 ", -- Namespace
			[4] = " ", -- Package
			[5] = "󰌗 ", -- Class
			[6] = "󰆧 ", -- Method
			[7] = " ", -- Property
			[8] = " ", -- Field
			[9] = " ", -- Constructor
			[10] = "󰕘", -- Enum
			[11] = "󰕘", -- Interface
			[12] = "󰊕 ", -- Function
			[13] = "󰆧 ", -- Variable
			[14] = "󰏿 ", -- Constant
			[15] = " ", -- String
			[16] = "󰎠 ", -- Number
			[17] = "◩ ", -- Boolean
			[18] = "󰅪 ", -- Array
			[19] = "󰅩 ", -- Object
			[20] = "󰌋 ", -- Key
			[21] = "󰟢 ", -- Null
			[22] = " ", -- EnumMember
			[23] = "󰌗 ", -- Struct
			[24] = " ", -- Event
			[25] = "󰆕 ", -- Operator
			[26] = "󰊄 ", -- TypeParameter
			[255] = "󰉨 ", -- Macro
		},
		use_default_mappings = true,          -- If set to false, only mappings set
											  -- by user are set. Else default
											  -- mappings are used for keys
											  -- that are not set by user
		mappings = {
			["<esc>"] = actions.close(),        -- Close and cursor to original location
			["q"] = actions.close(),

			["j"] = actions.next_sibling(),     -- down
			["k"] = actions.previous_sibling(), -- up

			["h"] = actions.parent(),           -- Move to left panel
			["l"] = actions.children(),         -- Move to right panel
			["0"] = actions.root(),             -- Move to first panel

			["v"] = actions.visual_name(),      -- Visual selection of name
			["V"] = actions.visual_scope(),     -- Visual selection of scope

			["y"] = actions.yank_name(),        -- Yank the name to system clipboard "+
			["Y"] = actions.yank_scope(),       -- Yank the scope to system clipboard "+

			["i"] = actions.insert_name(),      -- Insert at start of name
			["I"] = actions.insert_scope(),     -- Insert at start of scope

			["a"] = actions.append_name(),      -- Insert at end of name
			["A"] = actions.append_scope(),     -- Insert at end of scope

			["r"] = actions.rename(),           -- Rename currently focused symbol

			["d"] = actions.delete(),           -- Delete scope

			["f"] = actions.fold_create(),      -- Create fold of current scope
			["F"] = actions.fold_delete(),      -- Delete fold of current scope

			["c"] = actions.comment(),          -- Comment out current scope

			["<enter>"] = actions.select(),     -- Goto selected symbol
			["o"] = actions.select(),

			["J"] = actions.move_down(),        -- Move focused node down
			["K"] = actions.move_up(),          -- Move focused node up

			["s"] = actions.toggle_preview(),   -- Show preview of current node

			["<C-v>"] = actions.vsplit(),       -- Open selected node in a vertical split
			["<C-s>"] = actions.hsplit(),       -- Open selected node in a horizontal split

			["t"] = actions.telescope({         -- Fuzzy finder at current level.
				layout_config = {			    -- All options that can be
					height = 0.60,              -- passed to telescope.nvim's
					width = 0.60,			    -- default can be passed here.
					prompt_position = "top",
					preview_width = 0.50
				},
				layout_strategy = "horizontal",
			})

			["g?"] = actions.help(),            -- Open mappings help window
		},
		lsp = {
			auto_attach = false,  -- If set to true, you don't need to manually use attach function
			preference = nil      -- list of lsp server names in order of preference
		},
		source_buffer = {
			follow_node = true,   -- Keep the current node in focus on the source buffer
			highlight = true,     -- Highlight the currently focused node
			reorient = "smart",   -- "smart", "top", "mid" or "none"
			scrolloff = nil       -- scrolloff value when navbuddy is open
		},
		custom_hl_group = nil,    -- "Visual" or any other hl group to use instead of inverted colors
	}
<
=============================================================================
Actions                                                         *navbuddy-actions*

|nvim-navbuddy| provides the following actions for the user.

actions.close ()
	Close the Navbuddy window and return cursor to original location.

actions.next_sibling ()
	Move to next_sibling, below current node, in Navbuddy window.

actions.previous_sibling ()
	Move to previous_sibling, above current node, in Navbuddy window.

actions.parent ()
	Move to parent of current, left of current node, in Navbuddy window.

actions.children ()
	Move to children of current, right of current node, in Navbuddy window.

actions.root ()
	Move to root node, the first node left of current node, in Navbuddy window.

actions.select ()
	Goto currently focus node.

actions.visual_name ()
	Visual select the name of current node.

actions.visual_scope ()
	Visual select the scope of current node.

actions.yank_name ()
	Yank the name of current node.

actions.yank_scope ()
	Yank the scope of current node.

actions.insert_name ()
	Start insert at begin of name.

actions.insert_scope ()
	Start insert at begin of scope.

actions.append_name ()
	Start insert at end of name.

actions.append_scope ()
	Start insert at end of scope.

actions.rename ()
	Trigger lsp rename for current node.

actions.delete ()
	Delete currently focused scope.

actions.fold_create ()
	Create fold for current scope. Requires fold methos to be "manual".

actions.fold_delete ()
	Delete fold for current scope. Requires fold methos to be "manual".

actions.comment ()
	Comment selected scope. Require Comment.nvim plugin to be installed.

actions.move_down ()
	Move currently focued node down. Copies entire lines and works only in case
	there are no overlapping lines between current node and next node.

actions.move_up ()
	Move currently focued node up. Copies entire lines and works only in case
	there are no overlapping lines between current node and previous node.

actions.vsplit ()
	Opens vertical split with currently selected node.
	Will not remember top line like |winsaveview()| does.
	NOTE: Direction of split is controlled by 'splitright'

actions.hsplit ()
	Acts akin to vsplit, but splits horizontally.
	NOTE: Direction of split is controlled by 'splitbelow'

actions.telescope (opts)
	Open Fuzzy finder with telescope to search sibling nodes on current level.
	Can be customized during setup by passing opts table, all configuration
	passed to telescope.nvim's default option can be passed here.

=============================================================================
Highlight                                                    *navbuddy-highlights*

|nvim-navbuddy| provides the following highlights which get used when
available.

	`NavbuddyName`  - highlight for name in source buffer
	`NavbuddyScope` - highlight for scope of context in source buffer
	`NavbuddyFloatBorder` - Floatborder highlight
	`NavbuddyNormalFloat` - Float normal highlight

The following highlights are are used to highlight elements in the navbuddy
window according to their type. If you have "NavicIcons<type>" highlights
already defined, these will automatically get linked to them unless defined
explicitly.

	`NavbuddyFile`
	`NavbuddyModule`
	`NavbuddyNamespace`
	`NavbuddyPackage`
	`NavbuddyClass`
	`NavbuddyMethod`
	`NavbuddyProperty`
	`NavbuddyField`
	`NavbuddyConstructor`
	`NavbuddyEnum`
	`NavbuddyInterface`
	`NavbuddyFunction`
	`NavbuddyVariable`
	`NavbuddyConstant`
	`NavbuddyString`
	`NavbuddyNumber`
	`NavbuddyBoolean`
	`NavbuddyArray`
	`NavbuddyObject`
	`NavbuddyKey`
	`NavbuddyNull`
	`NavbuddyEnumMember`
	`NavbuddyStruct`
	`NavbuddyEvent`
	`NavbuddyOperator`
	`NavbuddyTypeParameter`


=============================================================================
vim:tw=78:ts=4:ft=help:norl:
